API reference

string: an open BCP 47 tag. Deliberately no enumeration; which languages a product offers is the host's policy

A RangeError with locale (the tag as passed) and reason. Thrown by every formatter, resolver and getDateFnsLocale for a refused tag; never an English or host-default fallback

'malformed' | 'unsupported' | 'calendar' | 'numbering-system'

(locale: LocaleCode) => boolean. The same verdict without throwing, for a host that tests a tag before it becomes a presentation

(text: string) => string. Every Unicode decimal digit (\p{Nd}) as ASCII; the input side of native digits

(locale: LocaleCode) => CalendarPhrases. Intl-derived calendar words (previous/next month, today, week, month, year), the numbering system and a list joiner, for calendar primitives

The result of getCalendarPhrases

LocaleCode | DatePresentationContext

{languageLocale; dateShape?; dateFormat?; timeFormat?; timeZone?}. Without dateShape the platform fallback SHORT_TEXTUAL applies; without dateFormat/timeFormat the language's own patterns apply (D16)

LocaleCode | NumberPresentationContext

{languageLocale; numberFormat?; currencyDisplay?}. Without numberFormat the language's own convention applies (D16). A language code outside the available languages formats as en, like the date side

LocaleCode | (DatePresentationContext & NumberPresentationContext). The one input of a component whose single value feeds every formatter; generic packages alias it at their own locale prop. Replaced whole, never merged per field (D23)

(presentation: DatePresentation) => Locale. The composed date-fns Locale (words and textual patterns from the language, numeric date and time patterns from the profile notation) for calendar primitives that call date-fns themselves. Any accepted tag: bundled date-fns wording for en (enGB), nl, de, fr, es, an Intl-derived locale otherwise. Throws UnsupportedLocaleError for a refused tag

{dateShape?; dateFormat?; timeFormat?; numberFormat?; currencyDisplay?}. An absent field means "not configured", never a value

{languageLocale; dateShape?; dateFormat?; timeFormat?; numberFormat?; currencyDisplay?; timeZone?}: both a DatePresentationContext and a NumberPresentationContext

(languageLocale, profile: PresentationProfileConfig | null | undefined, timeZone?: IanaTimeZone | null) => PresentationContext. The only place language, profile and zone meet

(presentation: string | {languageLocale}) => LocaleCode. The language of a presentation, for collation, Intl.DisplayNames and calendar language; never for formatting

'numeric' | 'short' | 'long' | 'full' | 'day-month' | 'day-month-numeric' | 'day-month-year-short' | 'month-year' | 'quarter-year' | 'month' | 'month-long' | 'weekday-long' | 'year'

DateOnlyPreset, plus the time presets 'time' | 'time-seconds' | 'time-millis' and the date-time presets 'numeric-datetime' | 'numeric-datetime-seconds' | 'numeric-datetime-millis' | 'datetime' | 'datetime-long' | 'time-day'

(value: string) => value is DatePreset. The guard for preset names arriving as data

(value: string) => value is DateOnlyPreset

(presentation) => DateOnlyPreset. The calendar-day preset inherited from the presentation's shape: NUMERIC → numeric, SHORT_TEXTUAL → short, LONG_TEXTUAL → long

(presentation) => DateTimePreset. The instant preset inherited from the presentation's shape: NUMERIC → numeric-datetime, SHORT_TEXTUAL → datetime, LONG_TEXTUAL → datetime-long

(value, presentation) or (value, preset: DatePreset | undefined, presentation). Formats an instant (a Date, a finite epoch, or an ISO string with Z or an offset) in presentation.timeZone (else the runtime zone). A zone-less date-time is ''; a plain YYYY-MM-DD renders as that calendar day without a zone or a time (D15 amendment). Without a preset it inherits normalDateOnlyPreset

(value, presentation) or (value, preset: DatePreset | undefined, presentation); the input contract of formatDate; without a preset it inherits normalDateTimePreset

(value, presentation) or (value, preset: DateOnlyPreset | undefined, presentation). Formats a calendar day: YYYY-MM-DD, an ISO string (its date part) or a Date whose UTC fields carry the day. Ignores the time zone

(value, pattern: string, presentation: DatePresentation, reason: string). The escape hatch for a date-fns pattern, with the input contract of formatDate (a plain calendar date is read by its calendar fields); reason is required and unused at runtime

(preset: DatePreset, presentation) => string. The date-fns pattern behind a preset, for components that call date-fns with a Locale object

(value: CalendarDateString) => string or (value, timeZone: IanaTimeZone) => string. The calendar day (YYYY-MM-DD): a plain day unchanged, an instant's day in the given zone; '' for an invalid value. An instant is a valid Date, a finite epoch or an ISO 8601 string with Z or an offset; a zone-less date-time or free text is '' on every host. An untyped call without a zone throws for an instant (D15)

(domainValues: unknown[], presentation: DatePresentation, options: {temporalSemantic: 'calendarDate' | 'instant'; suppressBoundary?: boolean}). A chart-axis formatter function carrying .basePreset; it picks a preset from the range of the values. calendarDate reads each value's own day without a zone and never picks a time preset; instant reads the presentation zone. The semantic is required (D15)

{absolutePreset?: DatePreset; now?: Date; thresholdDays?: number}: the third argument of resolveRecency. Without now the function reads the clock, which is its documented contract (D18); every other formatter takes its moment from the caller

(value, presentation, options?: {absolutePreset?; now?; thresholdDays?}) => {mode: 'relative' | 'absolute' | 'unavailable'; text; absoluteText; machineValue}. Relative within the threshold (7 days by default, symmetric: a future instant inside it is relative too, "in 3 days"), absolute beyond it, unavailable without a value. now drives both the threshold and the relative text. Accepts an instant only: a valid Date, finite epoch milliseconds or an ISO 8601 string with Z or an offset; a zone-less date-time, a calendar day or free text is unavailable (D18). The only route to relative time

(value) => Date | null. A date-only value as a Date whose calendar fields (and date-fns format()) read that day on every host: a TZDate fixed to UTC, at noon. A Date input is read through its UTC fields

(value) => string. A date-only value as canonical YYYY-MM-DD; '' for an empty or invalid value

(isoDate: string) => Date | null. A strict YYYY-MM-DD as a Date at UTC midnight (the storage convention); null for anything else, including a time or offset suffix

(date: Date | null | undefined) => string. The calendar day of a picker Date, from its local fields

(isoDate: string) => Date | null. YYYY-MM-DD as a Date at local midnight, for calendar components

(timeZone: IanaTimeZone) => string. Today as YYYY-MM-DD in the given zone; never the runtime's day. An untyped call without a zone throws (D15)

(presentation) => string. The numeric date pattern with a four-digit year, for example dd-MM-yyyy (nl), dd.MM.yyyy (de), dd/MM/yyyy (en)

(isoDate: string, presentation) => string. YYYY-MM-DD as input text; '' for an empty or invalid value

(text: string, presentation) => string | null. Strict: impossible dates and years shorter than four digits are null

(text: string, presentation) => {status: DateInputStatus; value: string}. empty, incomplete, invalid or valid with the ISO value

'empty' | 'incomplete' | 'invalid' | 'valid'

(value: number | null | undefined, format: NumberFormat = 'decimal', presentation) => string. Precision, notation and sign come from format; separators, grouping and digits from the presentation

(value, preset: PercentFormat = 'integer', presentation) => string. The stored value is a fraction: 0.125 is 12.5 %

(value, preset: PercentFormat = 'integer', presentation) => string. The stored value is in points: 12.5 is 12.5 %

(value: MonetaryAmount, presentation: NumberPresentation, options?: CurrencyFormatOptions) => string. The currency comes from the data, never the language; decimals follow the currency's minor units, rounded half away from zero. A DecimalString amount reaches Intl as that exact decimal, never through a double (D29). '' for null, undefined, a non-finite number and a string that is not a DecimalString (checked at runtime too). Throws for an invalid decimals, sign or currency code

{amount: number | DecimalString | null | undefined; currency: string} (ISO 4217). A localized string ('1.234,56') is user input: read it with classifyNumberInput first

{decimals?: number; sign?: NumberSign}: a deliberate per-call precision override (integer 0 to 100) and sign display (default auto: a minus, also for an amount rounding to zero from below)

'XXX': for an amount whose currency identity cannot be established; never a substitute for a knowable currency

'integer' | 'decimal' | 'decimal-1' | 'decimal-2' | 'decimal-4' | 'compact'

NumberPreset | NumberSpec

{decimals?, maxDecimals?} (integers 0 to 100) or {significantDigits?, maxSignificantDigits?} (1 to 21), never both (the type refuses it), plus notation?: NumberNotation (default standard) and sign?: NumberSign (default auto). No precision: Intl's default for the notation. {decimals: 2} formats exactly as before. Out-of-range or inconsistent values throw a RangeError, never a clamp. Not an Intl options bag: no field reaches separators or grouping (D16)

'standard' | 'scientific' | 'engineering' | 'compact'; exponent separator and compact words come from the language

'auto' | 'negative' | 'exceptZero' | 'always' | 'never'

'integer' | 'decimal-1' | 'decimal-2' | 'decimal-4' | 'signed-decimal-1' | 'signed-decimal-2'; signed- shows an explicit +

PercentPreset, or {decimals: number; maxDecimals?: number} (validated, integers 0 to 100)

(value: number | null | undefined, unit: MeasureUnit, presentation: NumberPresentation, options?: UnitFormatOptions) => string. A measured quantity in the unit the caller supplies; never converted (D29). '12,5 km' (nl), '12.5 kilometers' (en, long). Throws for an unknown unit or display

{display?: 'short' | 'long' | 'narrow'; format?: NumberFormat}; defaults short and decimal (package-owned)

the ECMA-402 sanctioned simple units without data sizes and percent, and <unit>-per-<unit> of two of them

the simple units as a runtime value

(unit: string) => unit is MeasureUnit

(bytes: number | null | undefined, presentation: NumberPresentation, options: ByteSizeOptions) => string. A count of BYTES (never bits). The largest unit whose rounded value is at least 1, up to peta; a value that rounds up to the next unit moves there. decimal: Intl units with the language's label (1,54 kB, 5 Mo); binary: IEC symbols KiB to PiB, written as they are, after a no-break space; below 1024 the language's byte unit. '' for null, undefined, negative and non-finite. 0 is zero bytes in the language

{system: ByteSizeSystem; maxDecimals?: number}. system is required (there is no default scale); maxDecimals an integer 0 to 20, default 1, trailing zeros dropped

'decimal' | 'binary'

(value: number | null | undefined, inputUnit: ElapsedInputUnit, presentation: NumberPresentation, options: ElapsedDurationOptions) => string. An ELAPSED duration in fixed units, from milliseconds to days of exactly 24 hours; never weeks, months or years (D30). Rounded half away from zero to the last unit shown; a negative value gets one minus; zero is written in the smallest unit (0 sec). Requires Intl.DurationFormat and throws without it: no English fallback

'millisecond' | 'second': what the input number counts

DigitalElapsedDurationOptions | WordedElapsedDurationOptions

{style: 'digital'; smallestUnit?: 'second' | 'millisecond'}: 1:02:05, hours never folded into days, milliseconds as three decimals

{style: 'short' | 'long' | 'narrow'; largestUnit?; smallestUnit?; maxUnits?}; defaults hour, second, all units. maxUnits 1 to 5, counted from the largest non-zero unit. smallestUnit larger than largestUnit throws

'day' | 'hour' | 'minute' | 'second' | 'millisecond'

(items: readonly string[], presentation: LocaleCode | {languageLocale}, options?: ListFormatOptions) => string. Joins host text in the language (Amsterdam, Utrecht en Delft). Only the language counts. [] is ''; one item is that item. Non-string items throw a TypeError

{type?: 'conjunction' | 'disjunction' | 'unit'; style?: 'long' | 'short' | 'narrow'}; defaults conjunction, long

(start, end, format: NumberFormat, presentation: NumberPresentation) => string. Intl formatRange with the tag and options of formatNumber. Equal bounds: the single number. Bounds that round to the same text: the language's approximation (~5.0). Start above end, or a missing or non-finite bound: ''

(start, end, preset: DateOnlyPreset | undefined, presentation: DatePresentation) => string. Each calendar day through formatDateOnly, joined by the language's own range separator (measured from Intl). No collapsing of shared fields: that would bypass the date notation preset (D30). The same day: that day once. Start after end, or an unreadable bound: ''. An instant range is not built

(text: string, presentation, contract?: {mode?: 'typing' | 'paste'; allowNegative?; maxDecimals?; currency?; allowPercentSign?}) => {status: NumberInputStatus; value: string; number: number | null; rejection?: NumberInputRejection; decimals?: number}; value is the canonical text form

'empty' | 'incomplete' | 'invalid' | 'valid'

'not-a-number' | 'cross-convention' | 'grouping-position' | 'grouping-while-typing' | 'unsupported-negative' | 'unsupported-notation' | 'negative-not-allowed' | 'precision-exceeded' | 'currency-mismatch'

(value: string, presentation, decimals?: number) => string. A canonical value as editable text; with decimals padded in decimal text (never rounded, more decimals kept, PP-031)

(presentation, decimals?: number) => string. The notation itself, no prose

(value: number | null | undefined) => string. The canonical text form of a number, always plain decimal (never exponent notation)

(value: string) => number | null. The number of a canonical text form

(text: string, presentation: DatePresentation, constraints?: TimeInputConstraints) => TimeInputResult. empty; incomplete (a prefix of a valid time, 1:05 on a 12-hour clock without its day period, 13:05 when seconds are required); invalid with format, range or step; valid with the 24-hour value. Native digits and the language separator are read. Never rounds: off the step grid is invalid (step)

{precision?: TimeInputPrecision; step?: TimeInputStep; min?: LocalTimeString; max?: LocalTimeString}; precision defaults to minute; bounds inclusive

'minute' | 'second'. minute refuses typed seconds (format); second requires them

{unit: 'minute' | 'second'; value: number}: every value units counted from midnight; a positive integer of at most one day. A second step needs precision: 'second'

the four states above; 'format' | 'range' | 'step'

(constraints?) => void. Throws a RangeError for an unknown precision, an invalid step, a second step on a minute field, a malformed bound, min after max

(presentation, precision?: TimeInputPrecision) => string. The format hint in date-fns tokens: HH:mm, HH:mm:ss, h:mm a, a h:mm

(value: string, presentation) => string. A LocalTimeString in the presentation's clock (1:05 PM), seconds when the value has them; '' for anything else

(value: Date | string | number | null | undefined) => string. A date-only value as yyyy-MM-dd (a YYYY-MM-DD or ISO string by its written date, a Date or epoch by its UTC fields); '' for null, undefined, ''. Throws for any other value, including an unreadable or impossible date string and an invalid Date. Not a readability probe: use isoDateFromDateOnly

(value: Date | InstantString | number | null | undefined) => string. An instant as YYYY-MM-DDTHH:mm:ss.sssZ; '' for null, undefined, ''. Throws for an invalid Date or epoch and for any string that is not an instant with Z or an offset, including a zone-less date-time

(value: number | null | undefined, decimals?: number) => string. Plain dot decimal, no grouping, never an exponent; signed zero as zero; '' for null, undefined. Throws for NaN, Infinity, -Infinity and for decimals outside the integers 0 to 100

which notation choices exist; each has its union type (DateShapePreset, DateNotationPreset, TimeNotationPreset, NumberNotationPreset, CurrencyDisplayPreset). Which value applies is the host's

one complete notation (all five dimensions) and the list of its dimensions

a zone-less YYYY-MM-DD day; an ISO instant with time and Z or an offset; their union. Obtain through a guard or constructor, never a cast

guards return a boolean; constructors throw an Error naming the invalid input; instantStringFromDate gives the canonical UTC instant of a valid Date

a WALL-CLOCK value, never a moment: YYYY-MM-DDTHH:mm[:ss[.sss]] on an existing day, without zone; HH:mm[:ss] from 00:00 to 23:59:59. Moved here from @workspace/active-types (D31)

guards return a boolean (a Z or offset is refused); constructors throw an Error naming the invalid input

an exact decimal as machine data: optional minus, digits, optional dot fraction; no grouping, exponent, plus or whitespace; at most 308 integer digits

guard (accepts unknown) and throwing constructor

a validated IANA zone identity, never an offset; 'UTC'

validation through the runtime's Intl time-zone data; toIanaTimeZone throws on an invalid zone; canonicalizeTimeZone returns null for one