Skip to Content
GuidesDescribing Formats

Describing Formats

describe(format, endpoint) parses a pattern and reports what each token means without converting it. It returns the canonical semantics used by convert.

import { describe } from 'rosetta-date' import { moment } from 'rosetta-date/dialects' describe('DD/MM', moment) // [ // { kind: 'field', token: 'DD', canonical: 'day-of-month/2-digit', field: 'day-of-month', style: '2-digit', qualifiers: [] }, // { kind: 'literal', value: '/' }, // { kind: 'field', token: 'MM', canonical: 'month/2-digit', field: 'month', style: '2-digit', qualifiers: [] }, // ]

It reuses the same parser as convert, so the result mirrors the input in order and covers every character: fields, literals, and unrecognized runs.

The segments

Each entry is one of three kinds:

KindShapeMeaning
field{ kind, token, canonical, field, style, qualifiers }A recognized token, decoded into its canonical field / style / qualifiers.
literal{ kind, value }Verbatim text (the dialect’s quoted/bracketed literals, and any non-token characters).
unknown{ kind, value }A run the dialect does not recognize.

A field carries its raw token (for example, 'DD'), stable canonical symbol (for example, 'day-of-month/2-digit'), and decoded parts. Qualifiers record refinements such as the ISO rule, hour cycle, and stand-alone form:

import { ldml } from 'rosetta-date/dialects' describe('K', ldml) // [{ kind: 'field', token: 'K', canonical: 'hour/numeric/h11', field: 'hour', style: 'numeric', qualifiers: ['h11'] }]

An endpoint may be a Dialect or a Library; a library is read through its effective grammar, so its extensions (e.g. date-fns ISO tokens) describe correctly.

Decoding a canonical symbol directly

When you already have a CanonicalToken, decodeCanonical returns the same field, style, and qualifiers split without a format string:

import { Canonical, decodeCanonical } from 'rosetta-date' decodeCanonical(Canonical.WeekOfYearOrdinalIso) // { field: 'week-of-year', style: 'ordinal', qualifiers: ['iso'] }

describe parses without rendering and does not apply locale or unsupported-token policy. Use explain to inspect target mappings and convert to produce the final string.

Last updated on