Skip to Content
GuidesExplaining Conversions

Explaining Conversions

explain(format, { from, to }) reports what a conversion would do for each token without producing the converted string. It adds a target outcome to each field returned by describe.

import { explain } from 'rosetta-date' import { dayjs, momentjs } from 'rosetta-date/libraries' explain('DDD', { from: momentjs, to: dayjs }) // [{ kind: 'field', token: 'DDD', canonical: 'day-of-year/numeric', field: 'day-of-year', // style: 'numeric', qualifiers: [], status: 'unsupported', reason: 'unsupported-by-target' }]

Use it to inspect what a migration keeps, remaps, or drops before converting the pattern.

Field outcomes

Every recognized field carries the same decoded semantics as describe, plus a status:

  • 'converted': The target renders the field; target holds its target spelling.
  • 'unsupported': The target cannot render the field; reason is one of:
    • 'unmappable': The target grammar has no token for this field.
    • 'unsupported-by-target': The grammar has a token, but the target library does not render it (a supports narrowing).
import { explain } from 'rosetta-date' import { ldml, moment } from 'rosetta-date/dialects' explain('DD/MM', { from: moment, to: ldml }) // [ { kind: 'field', token: 'DD', canonical: 'day-of-month/2-digit', ..., status: 'converted', target: 'dd' }, // { kind: 'literal', value: '/' }, // { kind: 'field', token: 'MM', canonical: 'month/2-digit', ..., status: 'converted', target: 'MM' } ]

Literals and unrecognized runs pass through unchanged, mirroring the input in order.

explain classifies each field independently. It cannot detect whole-string rendering effects such as unrepresentable-adjacency, where adjacent converted tokens would merge. convert detects those effects while producing the final string and applies its onUnsupportedToken policy.

Last updated on