Dialects & Libraries

rosetta-date works with two kinds of endpoint, and both from and to accept either one.

Dialect

A Dialect represents a formatting language: its token grammar, the tokenization family its syntax belongs to (letter tokens with […]/'…' literals, or %-style directives), and the canonical meaning of each token. It is tool-agnostic.

Use a dialect when you want pure grammar conversion — rewriting tokens from one language to another without caring which concrete tool will consume the result.

import { convert } from 'rosetta-date'
import { ldml, moment } from 'rosetta-date/dialects'
 
convert('DD/MM/YYYY', { from: moment, to: ldml }) // 'dd/MM/yyyy'

Library

A Library builds on a dialect to model one specific tool: the subset of fields it actually renders, the aliases it accepts, and the limitations it has. Several libraries can speak the same dialect (e.g. Day.js and Moment.js both speak moment) yet render different slices of it.

Use a library when tool-specific behavior matters — most importantly, when you want unrenderable tokens to be flagged rather than emitted blindly.

import { convert } from 'rosetta-date'
import { dateFns, momentjs } from 'rosetta-date/libraries'
 
convert('DD/MM/YYYY', { from: momentjs, to: dateFns }) // 'dd/MM/yyyy'

Converting to a library routes any token it cannot render through onUnsupportedToken. A reference implementation (such as momentjs or dateFns) renders its whole dialect.

Mixing them

Because both endpoints accept either type, you can mix freely — e.g. convert from a bare dialect into a specific library:

import { convert } from 'rosetta-date'
import { moment } from 'rosetta-date/dialects'
import { dateFns } from 'rosetta-date/libraries'
 
convert('YYYY-MM-DD', { from: moment, to: dateFns }) // 'yyyy-MM-dd'

Choosing one

Name-driven resolution

For a path where the endpoint is chosen at runtime (e.g. from config), getDialect / getLibrary resolve a name string to its object:

import { convert } from 'rosetta-date'
import { getDialect } from 'rosetta-date/dialects'
import { getLibrary } from 'rosetta-date/libraries'
 
convert(format, { from: getDialect(config.from), to: getLibrary(config.to) })

See the full list of built-ins under Dialects and Libraries.