Libraries

A Library models one concrete tool built on a dialect. It refines the dialect’s grammar in two ways, both keyed by canonical field:

supports narrows the grammar to the subset of fields the tool renders (e.g. Day.js).
extends adds tokens the tool understands beyond the base dialect (e.g. date-fns).

A reference implementation that renders its whole dialect omits supports. Converting to a library routes any field it cannot render through onUnsupportedToken.

Built-in libraries are imported from rosetta-date/libraries:


import { dateFns, dayjs, momentjs } from 'rosetta-date/libraries'

Library	Tool	Speaks	Coverage	Reference
`momentjs`	Moment.js	`moment`	the full grammar	momentjs
`dayjs`	Day.js	`moment`	a core subset + common plugins	dayjs
`dateFns`	date-fns	`ldml`	the full grammar + its own extensions	dateFns

Each library page opens with its base grammar, support model, and extensions, then documents — only where they apply — the fields it cannot render, its extension tokens, and its localized presets.

Localized presets

The L… family (Moment.js / Day.js) and P… / p… (date-fns) render per the library’s loaded locale. rosetta-date maps them preset → preset — never expanded to a concrete pattern, which would hardcode one locale — so the token stays locale-deferred and the target library applies its own locale, including the compound connector (" at ", ", ", …) it picks. The canonical preset meanings are in the vocabulary; each library page lists how it spells them.

Locale caveat: conversion rewrites the token, not the date. Matching output needs equivalent locales loaded in both libraries; the conversion only guarantees the token stays the locale’s preset, never a hardcoded pattern. en-US samples like LL vs PPP differ only as June 7, 2024 vs June 7th, 2024 — each library’s locale data, not a conversion error.

Match widths: for date + time, use a matched compound preset or a separator. rosetta-date maps each preset faithfully, but gluing mismatched widths can drop a locale connector or re-lex into a different token — a glued mismatched-width input was never valid to begin with. The per-library pages note where a target lacks a given compound width.

Unrenderable tokens

When converting to a library, a field the tool cannot render is flagged as unsupported-by-target and handled by onUnsupportedToken. Note that supports models the tool’s grammar, not its runtime configuration — a token a tool renders only with a plugin or option loaded is emitted as-is, and the tool signals the problem itself at format time.

To add a library, see the Contributing guide.