rosetta-date
A translation engine for date-formatting languages.
rosetta-date translates date-format strings between formatting languages by routing recognized
tokens through a canonical intermediate representation before rendering them in the target language.
import { convert } from 'rosetta-date'
import { ldml, moment } from 'rosetta-date/dialects'
convert('YYYY-MM-DD', { from: moment, to: ldml }) // 'yyyy-MM-dd'Although YYYY-MM-DD and yyyy-MM-dd look different, they express the same date format using
different formatting languages. rosetta-date rewrites the token string while leaving date values
untouched.
Why it exists
Moving a format string from one date library to another is deceptively error-prone. YYYY means a
calendar year in Moment.js but a week-numbering year in LDML; D is a day of month in one and a
day of year in another. Hand-translating these tables is exactly the kind of work that looks trivial
and quietly ships bugs. Migrating a Moment.js format to date-fns is one call:
import { convert } from 'rosetta-date'
import { dateFns, momentjs } from 'rosetta-date/libraries'
convert('dddd, MMMM Do YYYY', { from: momentjs, to: dateFns }) // 'EEEE, MMMM do yyyy'Each grammar maps its tokens to canonical fields once. A token that converts cleanly round-trips faithfully. The unsupported-token policy handles tokens with no clean counterpart and preserves them as literals by default.
Highlights
- 🔁 Bidirectional: Each dialect parses tokens to canonical fields and renders canonical fields back to tokens.
- 🧭 Canonical semantic model: Tokens convert through shared meanings instead of pairwise dialect mappings.
- 🧩 Extensible by design: New dialects map to the canonical model; libraries extend or narrow a dialect.
- 🛡️ Escape-aware tokenizer: Literals round-trip across dialects.
- 🌐
Intladapter: Convert a token pattern toIntl.DateTimeFormatoptions and back. - 🔍 Introspectable:
describereports what a pattern means, andexplainreports what a conversion would do. - 🌳 Tree-shakeable: Dialects and libraries ship from their own entrypoints.
- 🪶 Zero runtime dependencies: No runtime dependencies.
Where to go next
- Start with Installation and the Quick start.
- Read How it works for the canonical model.
- Use Token mapping to look up a specific token.