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 symbolThe 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.