Skip to Content
GuidesUnsupported Tokens

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.
  • '' and undefined are accepted as shorthands: '' drops, undefined literalizes.

The four reasons

rosetta-date tags each unsupported token with a reason, which a handler reads from info:

reasonMeaning
unrecognizedThe source dialect does not define this token.
unmappableA valid source field with no token in the target dialect.
unsupported-by-targetThe target dialect has the field, but the target library does not render it (e.g. Day.js can’t render Mo).
unrepresentable-adjacencyThe 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 a Library.

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.

Last updated on