formatUnix

Signature

formatUnix(value: string | number, locale?: string | string[], options?: FormatUnixOptions): string

Format a unix epoch value (string or number) as a localized date/time string.

• Returns "" if the input is not a valid unix epoch value for the given epochUnit.
• value is a safe integer or a string of optionally negative ASCII digits (no whitespace, +, decimal point or exponent).
• Without includeTimeZoneName the wall clock is formatted as Temporal’s ECMA-402 PlainDateTime format does (timeZoneName is ignored); with it, as the ZonedDateTime format does (a short zone name is added to the defaults). Either way the requested fields and style widths are kept, and era alone still gets the date and time defaults.
• Compatibility: before 1.16.0 some locales and calendars lost a requested width (ja-JP with the japanese calendar and month: "long" gave "R6/2"), a long/full timeStyle replaced the dateStyle width, era alone dropped the time, and timeZoneName alone without includeTimeZoneName returned "". Pass the fields the old text showed to keep it.
• options null returns "", as ECMA-402’s CoerceOptionsToObject rejects it.
• An offset with seconds (-00:44:30) returns "". Intl.DateTimeFormat takes a time zone identifier only: constructing one with an offset that has seconds throws (ECMA-402, the DateTimeFormat construction step “If parseResult contains more than one MinuteSecond Parse Node, throw a RangeError exception”). Pass the IANA name.

Parameters

Parameter	Type	Description
value	string | number	unix epoch value to format (string or number, per epochUnit)
locale	string | string[]	optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)

Options

options

optional: Intl.DateTimeFormatOptions fields, plus how value is read, the zone and whether its name is shown

Options for formatUnix: every Intl.DateTimeFormatOptions field, plus the epoch unit, the time zone the value is rendered in and whether the zone name is shown.

import type { FormatUnixOptions } from "@northguild/gmt";

Option	Type	Default	Description
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit value is counted in: "seconds" or "milliseconds", singular or plural. Any other value returns "".
timeZone?	string	"UTC"	The time zone the value is rendered in: an IANA name, a UTC offset to the minute (what isValidTimeZone accepts), or "local" for the system time zone. An unknown zone returns "", as ECMA-402 throws RangeError for it.
includeTimeZoneName?	boolean	false	Whether the value is formatted as a zoned date-time, which adds the localized time zone name. When false the wall clock is formatted on its own and timeZoneName is ignored.
…Intl.DateTimeFormatOptions	—	—	Every other field of DateTimeFormatOptions, as ECMA-402 defines it.

Returns

the formatted date/time string, or "" on invalid input

Related types

• UnixUnit

Examples

import { formatUnix } from "@northguild/gmt/unix/format";

formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"

valuelocale ?

output

 

Source

unix/format/formatUnix.ts