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 another | Dialect → Dialect |
| Migrate a format string for a specific tool, flagging what it can’t render | Library → Library |
| Convert generic grammar into a specific tool’s input | Dialect → 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.