formatDateToParts
Signature
Section titled “Signature”formatDateToParts(value: string, locale?: string, options?: DateTimeFormatOptions): { type: string; value: string; }[]import { formatDateToParts } from "@northguild/gmt/plain/format";Return the locale-formatted parts of a PlainDate.
- This is GMT’s substitute for a token formatter (Luxon
toFormat, date-fnsformat). A token pattern hard-codes field order and ships US ordering to every locale;formatToPartsgives the caller full control over presentation while the locale keeps control of order. See Decision 1 incontext/roadmap/issues/J.md. - Each part is
{ type, value }wheretypeis one of:"era","year","month","day","weekday","literal". - The caller should iterate the array as returned; reassembling in a fixed order reintroduces exactly the bug
formatToPartsexists to avoid. - Returns
[]for invalid input.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value |
string |
ISO PlainDate string |
locale |
string |
optional BCP 47 locale identifier |
Options
Section titled “Options”options
| Option | Type | Default |
|---|---|---|
localeMatcher? |
"best fit" | "lookup" |
— |
weekday? |
"long" | "short" | "narrow" |
— |
era? |
"long" | "short" | "narrow" |
— |
year? |
"numeric" | "2-digit" |
— |
month? |
"long" | "short" | "narrow" | "numeric" | "2-digit" |
— |
day? |
"numeric" | "2-digit" |
— |
hour? |
"numeric" | "2-digit" |
— |
minute? |
"numeric" | "2-digit" |
— |
second? |
"numeric" | "2-digit" |
— |
timeZoneName? |
"long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric" |
— |
formatMatcher? |
"best fit" | "basic" |
— |
hour12? |
boolean |
— |
timeZone? |
string |
— |
calendar? |
string |
— |
dayPeriod? |
"long" | "short" | "narrow" |
— |
numberingSystem? |
string |
— |
dateStyle? |
"long" | "short" | "medium" | "full" |
— |
timeStyle? |
"long" | "short" | "medium" | "full" |
— |
hourCycle? |
"h11" | "h12" | "h23" | "h24" |
— |
fractionalSecondDigits? |
1 | 2 | 3 |
— |
Returns
Section titled “Returns”array of { type, value } parts, or [] on invalid input
Examples
Section titled “Examples”formatDateToParts("2024-03-15", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }]formatDateToParts("2024-03-15", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }]formatDateToParts("invalid") // []