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;targetholds its target spelling.'unsupported': The target cannot render the field;reasonis 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 (asupportsnarrowing).
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