Unsupported Tokens
A token can lack a clean conversion. The onUnsupportedToken option decides what happens, and
rosetta-date classifies why so a handler can react. The default never throws.
The policy
onUnsupportedToken accepts a string preset or a handler function:
import { convert, Unsupported, UnsupportedTokenError } from 'rosetta-date'
import { ldml, moment } from 'rosetta-date/dialects'
// 'literalize' (default): escape it as a literal, so it cannot be re-read as a token.
convert('K', { from: ldml, to: moment }) // '[K]'
// 'throw': fail on unsupported tokens during migrations or validation.
convert('K', { from: ldml, to: moment, onUnsupportedToken: 'throw' }) // throws UnsupportedTokenError
// handler: decide per token using `info.reason` (listed below).
convert('K', {
from: ldml,
to: moment,
onUnsupportedToken: (token, info) =>
info.reason === 'unmappable' ? Unsupported.drop : Unsupported.literalize,
})Handler return values
A handler’s string return value is emitted verbatim. Use a sentinel for the built-in behaviors:
Unsupported.drop: omit the token entirely.Unsupported.literalize: defer to the default and escape the token as a literal.''andundefinedare accepted as shorthands:''drops,undefinedliteralizes.
The four reasons
rosetta-date tags each unsupported token with a reason, which a handler reads from info:
reason | Meaning |
|---|---|
unrecognized | The source dialect does not define this token. |
unmappable | A valid source field with no token in the target dialect. |
unsupported-by-target | The target dialect has the field, but the target library does not render it (e.g. Day.js can’t render Mo). |
unrepresentable-adjacency | The token converts, but would merge with its neighbour and the target has no empty literal to separate them. See Literals & Adjacency. |
The info argument
The second handler argument carries:
reason: one of the four reasons above.from/to: the resolved dialects.fromLibrary/toLibrary: present when an endpoint was aLibrary.
Because libraries that share a dialect (e.g. Day.js and Moment.js both speak moment) resolve to the
same to dialect, toLibrary is how a handler distinguishes libraries built on the same dialect.
The default policy preserves unsupported tokens as literals instead of throwing.
What the supports set does not cover
A Library’s supports set lists which canonical fields the tool renders and flags
unsupported-by-target. It does not model the consumer’s runtime configuration. A token a
library renders only with a plugin or option loaded (Day.js’s Q, date-fns’s D) is emitted
as-is. The target library reports missing runtime configuration at format time: date-fns throws,
while Day.js mis-renders the token. See Libraries for details by tool.