parseUnitFromUnix

Signature

parseUnitFromUnix(value: string | number, unit: PluralUnit<DateTimeUnit> | PlainNowUnit, options?: { epochUnit?: UnixUnit; timeZone?: string; weekStartsOn?: "monday" | "sunday"; }): string

Extract a unit from a unix epoch value.

• Valid units: “year”, “month”, “week”, “day”, “dayOfWeek”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”. Temporal units may also be plural (“hours”).
• value is a safe integer or a string of optionally negative ASCII digits.
• microsecond and nanosecond are the 0–999 Temporal fields, zero-padded to 3 digits.
• Converts to ZonedDateTime then extracts the unit.
• Returns "" for invalid input.
• The "year" unit is written as Temporal writes a year: four digits ("2024", "0005"), or a sign and six digits outside 0000–9999 ("+010000", "-000005").

Parameters

Parameter	Type	Description
value	string | number	unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
unit	PluralUnit<DateTimeUnit> | PlainNowUnit	unit to extract (e.g. “year”, “month”, “hour”)

Options

options

optional: how value is read, the zone its wall clock is read in and the first day of the week; a non-object value (such as null) is invalid

Option	Type	Default	Description
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit the epoch values are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns "".
timeZone?	string	"UTC"	The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone identifier such as +05:30, +0530 or -08, or a stored offset ±HH:MM[:SS], what getTimeZoneOffset returns), or "local" for the system time zone. An unknown zone returns "".
weekStartsOn?	"monday" | "sunday"	"monday"	The first day of the week, which sets how the "week" unit is numbered. "monday" gives the ISO 8601 week number, where week 1 holds the year’s first Thursday; "sunday" gives the UTS #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other value returns "", whatever the unit.

Returns

extracted unit value as string, or "" on invalid input

Types

PlainNowUnit

Units extractable from a unix epoch value via parseUnitFromUnix. Covers the full set of date/time units plus sub-millisecond precision.

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

"year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" | "dayOfWeek"

Related types

• UnixUnit

Examples

import { parseUnitFromUnix } from "@northguild/gmt/unix/parse";

parseUnitFromUnix(1700000000000, "year") // "2023"

value

output

 

Source

unix/parse/parseUnitFromUnix.ts