formatDateToParts

Signature

formatDateToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): { type: string; value: string; }[]

Return the locale-formatted parts of a PlainDate.

• This is GMT’s substitute for a token formatter (Luxon toFormat, date-fns format). A token pattern hard-codes field order and ships US ordering to every locale; formatToParts gives the caller full control over presentation while the locale keeps control of order.
• Each part is { type, value } where type is one of: "era", "year", "relatedYear", "yearName", "month", "day", "weekday", "literal".
• A lunisolar calendar adds two more: zh-u-ca-chinese and ko-u-ca-dangi emit "relatedYear" (the Gregorian year the cycle falls in) and "yearName" (the sexagenary cycle name) in place of, or beside, "year". Code that looks up a "year" part must handle their absence.
• The caller should iterate the array as returned; reassembling in a fixed order reintroduces exactly the bug formatToParts exists to avoid.
• A PlainDate has no time or zone, so no hour/minute/second/dayPeriod/timeZoneName part is ever returned, following Temporal’s ECMA-402 PlainDate format: timeStyle without dateStyle, or only time fields, yields [] (as formatDate yields ""); timeZoneName is ignored. With both dateStyle and timeStyle the parts keep the date style and drop the timeStyle (the Intl.DateTimeFormat entry point, required any), whereas the text sibling formatDate returns "" (PlainDate#toLocaleString, required date, is a TypeError).
• The formatZonedToParts example below writes the literal before the day period as "\u202f", U+202F NARROW NO-BREAK SPACE, which Node 22 and 24 return; Node 26 returns an ordinary space there (see formatZonedToParts).
• Returns [] for invalid input.
• Compatibility: before 1.16.0 time options leaked a UTC midnight and a "UTC" zone name into the parts. formatZonedToParts on the date at midnight UTC returns those parts.
• options null returns [], as ECMA-402’s CoerceOptionsToObject rejects it. Any other non-object — a string, a number, a boolean — formats with the defaults, as Intl.DateTimeFormat does: CoerceOptionsToObject calls ToObject on it and the wrapper carries no recognised option. Only null and undefined are special-cased.

Parameters

Parameter	Type	Description
value	string	ISO PlainDate string
locale	string | string[]	optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)

Options

options

optional Intl.DateTimeFormatOptions

Type: DateTimeFormatOptions.

Option	Type	Default	Description
…Intl.DateTimeFormatOptions	—	—	Every field of DateTimeFormatOptions, as ECMA-402 defines it.

Returns

array of { type, value } parts, or [] on invalid input

Members of each item

Member	Type	Description
type	string	The kind of part, named as ECMA-402 Intl.DateTimeFormat.prototype.formatToParts names it: a field such as "year", "month" or "day", or "literal" for the separator text between fields.
value	string	The text of the part in the requested locale, exactly as the formatter wrote it. Joining every value in array order gives the whole formatted text.

Related types

• DateTimeFormatOptions

Examples

import { formatDateToParts } from "@northguild/gmt/plain/format";

formatDateToParts("2024-03-15", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }]

valuelocale ?

output

 

Source

plain/format/formatDateToParts.ts