formatZonedToParts

Signature

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

import { formatZonedToParts } from "@northguild/gmt/zoned/format";

Return the locale-formatted parts of a ZonedDateTime.

• 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. See Decision 1 in context/roadmap/issues/J.md.
• Each part is { type, value } where type can be: "era", "year", "month", "day", "weekday", "hour", "minute", "second", "fractionalSecond", "dayPeriod", "timeZoneName", "literal".
• The caller should iterate the array as returned; reassembling in a fixed order reintroduces exactly the bug formatToParts exists to avoid.
• Returns [] for invalid input.

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
locale	string	optional locale tag (e.g. “en-US”)

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

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

Examples

formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: " " }, { type: "dayPeriod", value: "PM" }]
formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // includes { type: "timeZoneName", value: "GMT-4" }
formatZonedToParts("invalid", "en-US") // []

Source

zoned/format/formatZonedToParts.ts