Skip to Content
ReferenceLibrariesOverview

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'
LibraryToolSpeaksCoverageReference
momentjsMoment.js momentthe full grammarmomentjs
dayjsDay.js momenta core subset + common pluginsdayjs
dateFnsdate-fns ldmlthe full grammar + its own extensionsdateFns

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 instead of expanding them to a fixed pattern. The target library applies its locale, including the compound connector (" at ", ", ", …). The canonical preset meanings are in the vocabulary; each library page lists its tokens.

Locale caveat: conversion rewrites the token string. 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 because each library supplies its own locale data.

Match widths: for date + time, use a matched compound preset or a separator. rosetta-date maps each preset, but gluing mismatched widths can drop a locale connector or re-lex into a different token. 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. supports models the tool’s grammar, not its runtime configuration. A token that requires a plugin or option is emitted as-is, and the tool reports missing configuration at format time.

To add a library, see the Contributing guide.

Last updated on