parseUnitFromUtc

Signature

parseUnitFromUtc(value: string, unit: UtcUnit, optionsArg?: { weekStartsOn?: "monday" | "sunday"; timeZone?: string; }): string

Extract a unit from a UTC datetime string.

• Valid units: “year”, “month”, “week”, “day”, “dayOfWeek”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”.
• unit accepts the singular or plural name of a Temporal unit ("hour" or "hours"), as Temporal does; "dayOfWeek" has no plural.
• A "week" in late December can be week 1 of the next year, under either week numbering.
• optionsArg must be an object or omitted: a non-object value (such as null) returns "".
• 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	ISO UTC datetime string (e.g., “2024-03-17T14:30:45Z”)
unit	UtcUnit	unit to extract from the datetime

Options

optionsArg

How weeks are numbered, and the time zone the value is read in

Option	Type	Default	Description
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.
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 "".

Returns

string representation of the requested unit or "" on invalid input

Types

UtcUnit

Units supported by parseUnitFromUtc when extracting a value from a UTC ISO string. Each Temporal unit is also accepted in its plural form ("months"), as Temporal accepts.

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

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

Examples

import { parseUnitFromUtc } from "@northguild/gmt/utc/parse";

parseUnitFromUtc("2024-03-17T14:30:45Z", "month") // "03"

value

output

 

Source

utc/parse/parseUnitFromUtc.ts