formatCalendarUnix

Signature

formatCalendarUnix(value: string | number, locale?: string | string[], options?: FormatCalendarUnixOptions): string

Format a unix epoch value as a relative day label plus time-of-day, e.g. “Tomorrow at 2:30 PM” — the unix counterpart of formatCalendar. See that function’s JSDoc for the day-label/threshold/connector design; this variant compares calendar days and renders the clock time in timeZone.

• value and a numeric reference are safe integers or strings of optionally negative ASCII digits; anything else returns "".
• options must be an object or omitted: null returns "", as Temporal’s GetOptionsObject 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 (string or number, per epochUnit) to format
locale	string | string[]	optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)

Options

options

optional: the reference instant, how epochs are read, the zone and the width of the time

Options for formatCalendarUnix. Like formatCalendar, it takes a reference and a timeStyle (here also "full"); it adds epochUnit and timeZone for the unix domain.

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

Option	Type	Default	Description
reference?	string | number	The current instant.	The instant the day label is measured from, as a UTC ISO string, or an epoch in epochUnit given as a safe integer or a digit string. Any other value returns "".
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit value and a numeric reference are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns "".
timeZone?	string	"UTC"	The time zone used for both the calendar-day comparison and the rendered clock time: 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.
timeStyle?	"long" | "short" | "medium" | "full"	"short"	The length of the time-of-day part, as the timeStyle of Intl.DateTimeFormat. "short" writes hours and minutes, "medium" adds seconds, "long" adds the short time zone name (“EDT”) and "full" the long one (“Eastern Daylight Time”). Any other value returns "".

Returns

the formatted calendar string, or "" on invalid input

Related types

• UnixUnit

Examples

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

formatCalendarUnix(1710685845000, "en-US", { epochUnit: "milliseconds", timeZone: "America/New_York" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold

valuelocale ?

output

 

Source

unix/format/formatCalendarUnix.ts