Skip to Content
Core ConceptsDialects & Libraries

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 for pure grammar conversion: rewriting tokens from one language to another without targeting a concrete tool.

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, including when unrenderable tokens must be flagged instead of emitted.

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

You want to…Use
Rewrite tokens from one grammar to anotherDialect → Dialect
Migrate a format string for a specific tool, flagging what it can’t renderLibrary → Library
Convert generic grammar into a specific tool’s inputDialect → Library

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) })

Each registry function imports every built-in. Use getDialect or getLibrary only when the direction is dynamic. Otherwise, import the specific dialect or library.

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

Last updated on