Skip to Content
GuidesCustom Dialects & Libraries

Custom Dialects & Libraries

Define a formatting language with defineDialect, or model a tool on an existing dialect with defineLibrary.

Map tokens to canonical meanings

Map each token to a canonical symbol that represents its meaning, such as year or 2-digit month. Do not map it to another dialect’s spelling. Canonical is the neutral vocabulary every built-in dialect uses, so a token mapped to Canonical.YearNumeric converts to and from every other dialect without pairwise mappings.

defineDialect

import { Canonical, convert, defineDialect } from 'rosetta-date' import { ldml } from 'rosetta-date/dialects' const custom = defineDialect({ name: 'custom', syntax: { kind: 'delimited', open: '{', close: '}' }, tokens: [ { token: 'yr', canonical: Canonical.YearNumeric }, { token: 'mo', canonical: Canonical.MonthTwoDigit }, { token: 'dy', canonical: Canonical.DayOfMonthTwoDigit }, ], }) convert('yr-mo-dy', { from: custom, to: ldml }) // 'yyyy-MM-dd'

The syntax chooses a tokenization family. The example above is delimited (letter tokens with {...} literals). For a %-directive grammar like strftime, use the directive family. Token spellings include the marker, and doubling the marker produces a literal marker:

const percent = defineDialect({ name: 'percent', syntax: { kind: 'directive', marker: '%' }, tokens: [ { token: '%Y', canonical: Canonical.YearNumeric }, { token: '%m', canonical: Canonical.MonthTwoDigit }, { token: '%d', canonical: Canonical.DayOfMonthTwoDigit }, ], }) convert('%Y-%m-%d', { from: percent, to: ldml }) // 'yyyy-MM-dd'

A dialect can also declare composites: parse-time macros where one spelling expands to a sub-pattern. Rendering uses the expansion, so a composite normalizes on a round trip:

const withComposites = defineDialect({ name: 'percent-composites', syntax: { kind: 'directive', marker: '%' }, tokens: [/* … %H %M %S … */], composites: [{ token: '%T', expandsTo: '%H:%M:%S' }], }) convert('%T', { from: withComposites, to: ldml }) // 'HH:mm:ss'

defineLibrary

A library can add a tool’s tokens to a dialect through extends. Built-in libraries can also declare a supports set. This example adds an LDML-flavoured tool that understands the Unix epoch:

import { Canonical, convert, defineLibrary } from 'rosetta-date' import { ldml } from 'rosetta-date/dialects' import { dateFns } from 'rosetta-date/libraries' const ldmlPlus = defineLibrary({ name: 'ldml-plus', dialect: ldml, extends: [{ token: 'u', canonical: Canonical.EpochSeconds }], }) convert('u', { from: ldmlPlus, to: dateFns }) // 't', bridged by the canonical symbol

The token u is not in the bare ldml dialect, but because it maps to Canonical.EpochSeconds, it bridges straight to date-fns’s t.

Narrowing what a tool renders with supports

extends adds tokens, while supports narrows a tool to a subset of the grammar. supports is keyed by canonical field, not spelling. List the fields the tool renders, and each is emitted with the dialect’s primary spelling. Omit supports, as ldmlPlus does, to render the whole grammar.

import { Canonical, convert, defineLibrary } from 'rosetta-date' import { moment } from 'rosetta-date/dialects' const dayjsLike = defineLibrary({ name: 'dayjs-like', dialect: moment, supports: new Set([Canonical.YearNumeric, Canonical.MonthTwoDigit, Canonical.DayOfMonthTwoDigit]), }) convert('MM', { from: moment, to: dayjsLike }) // 'MM', a supported field convert('Mo', { from: moment, to: dayjsLike }) // '[Mo]', because month ordinal is not in `supports`

Validation happens once

defineDialect and defineLibrary validate a definition once. They reject an incoherent token table or syntax, including a directive token that omits its marker, and return a stable object. Per-dialect compilation is cached by object identity, so define the object once and reuse it across conversions.

Canonical symbols

Canonical values are stable identifiers shaped as field/style, versioned by semver:

  • Adding a symbol is a minor (additive) change.
  • Renaming or removing one is breaking.

Prefer the named members (Canonical.YearNumeric) over the raw strings. The full vocabulary is exported from the package root, and the TokenRule and TokenSyntax types are available for annotating your token tables and syntax.

See the API Reference for the exact signatures and types.

Last updated on