@northguild/gmt 1.15.0 → 1.16.0

package/dist/internal/unixEpochValue.d.ts

@@ -0,0 +1,166 @@
+import { Temporal } from "@js-temporal/polyfill";
+/** The two units a Unix epoch value is expressed in. */
+export type UnixEpochUnit = "seconds" | "milliseconds";
+/**
+ * Parse one Unix epoch argument into a number, or null — the one epoch grammar every `unix/`
+ * function and validator shares.
+ *
+ * - A number must be a safe integer (`Number.isSafeInteger`): fractional values, `NaN`,
+ *   `±Infinity` and anything beyond ±(2^53 − 1) are rejected. Past 2^53 consecutive integers are
+ *   no longer distinct doubles (`2 ** 53 + 1 === 2 ** 53`). Every Temporal instant (±8.64e15 ms) is
+ *   well inside that range.
+ * - A string must be an optionally negative run of ASCII digits (`/^-?\d+$/`) naming a safe
+ *   integer. No whitespace, no `+`, no hex, binary, exponent, decimal point or numeric separator:
+ *   POSIX epoch time is an integer count and has no other notation, so `Number()`'s wider
+ *   StringToNumber grammar (`" 12 "`, `"0x10"`, `"1e3"`, `""` → 0) is not used.
+ * - `-0` reads as `0`.
+ * - Any other type is rejected.
+ *
+ * @param value Unix epoch value as a number or digit string
+ * @returns the epoch as a safe integer, or null when invalid
+ *
+ * @example parseUnixEpochValue(1704067200000) // 1704067200000
+ * @example parseUnixEpochValue("-86400") // -86400
+ * @example parseUnixEpochValue(1.5) // null
+ * @example parseUnixEpochValue(" 12") // null
+ * @example parseUnixEpochValue("1e3") // null
+ */
+export declare function parseUnixEpochValue(value: unknown): number | null;
+/**
+ * Resolve an `epochUnit` option: omitted → `"milliseconds"`; singular or plural `second` /
+ * `millisecond` → the plural name; anything else → null.
+ *
+ * - Singular and plural are the same unit, as in Temporal §13.17 GetTemporalUnitValuedOption.
+ *
+ * @param unit candidate `epochUnit` value
+ * @returns the resolved unit, or null when invalid
+ *
+ * @example resolveUnixEpochUnit(undefined) // "milliseconds"
+ * @example resolveUnixEpochUnit("second") // "seconds"
+ * @example resolveUnixEpochUnit("nanoseconds") // null
+ */
+export declare function resolveUnixEpochUnit(unit: unknown): UnixEpochUnit | null;
+/**
+ * Resolve the `epochUnit` of an options argument (`{ epochUnit }`), or null.
+ *
+ * - `undefined` options → `"milliseconds"`, the same as omitted (TC39 GetOptionsObject).
+ * - Anything that is not an object (`null`, a legacy positional unit string such as `"seconds"`, a
+ *   number) → null: Temporal GetOptionsObject throws `TypeError` for it, so it is never silently
+ *   read as the default.
+ * - Otherwise `resolveUnixEpochUnit(options.epochUnit)`.
+ *
+ * @param options candidate options argument
+ * @returns the resolved unit, or null when invalid
+ *
+ * @example resolveUnixEpochUnitOptions(undefined) // "milliseconds"
+ * @example resolveUnixEpochUnitOptions({ epochUnit: "second" }) // "seconds"
+ * @example resolveUnixEpochUnitOptions("seconds") // null
+ */
+export declare function resolveUnixEpochUnitOptions(options: unknown): UnixEpochUnit | null;
+/**
+ * Read a Unix epoch argument (see `parseUnixEpochValue`) as a `Temporal.Instant`, or null when it
+ * is not an epoch or lies outside the Temporal instant range.
+ *
+ * - Seconds scale by 1000 exactly: every in-range seconds value (±8.64e12) times 1000 is a safe
+ *   integer, and any product that is not exact is already outside the instant range.
+ *
+ * @param value Unix epoch value as a number or digit string
+ * @param epochUnit unit the value is expressed in
+ * @returns the instant, or null
+ *
+ * @example unixEpochToInstant(0, "seconds")?.toString() // "1970-01-01T00:00:00Z"
+ * @example unixEpochToInstant(8.64e15 + 1, "milliseconds") // null
+ */
+export declare function unixEpochToInstant(value: unknown, epochUnit: UnixEpochUnit): Temporal.Instant | null;
+/**
+ * Express an instant (or zoned date-time) as a Unix epoch in `epochUnit`.
+ *
+ * - Seconds floor toward −∞, so `1969-12-31T23:59:59.999Z` is second `-1`, as POSIX
+ *   `time_t` counts whole elapsed seconds.
+ *
+ * @param value anything with `epochMilliseconds`
+ * @param epochUnit unit of the result
+ * @returns the epoch value
+ *
+ * @example toUnixEpoch({ epochMilliseconds: 1710685845999 }, "seconds") // 1710685845
+ * @example toUnixEpoch({ epochMilliseconds: -1 }, "seconds") // -1
+ */
+export declare function toUnixEpoch(value: {
+    epochMilliseconds: number;
+}, epochUnit: UnixEpochUnit): number;
+/**
+ * Parse an epoch for the aggregators (`sortUnix`, `minUnix`, `maxUnix`) that take no `epochUnit`:
+ * the epoch grammar (`parseUnixEpochValue`) inside ±8.64e15, or null.
+ *
+ * - ±8.64e15 is the instant range in milliseconds. It contains the seconds range (±8.64e12), so no
+ *   valid epoch of either unit is dropped.
+ *
+ * @param value candidate epoch value
+ * @returns the epoch as a number, or null
+ *
+ * @example parseUnixEpochInInstantRange("1700000000000") // 1700000000000
+ * @example parseUnixEpochInInstantRange(1e20) // null
+ */
+export declare function parseUnixEpochInInstantRange(value: unknown): number | null;
+/**
+ * The values of a list that `parseUnixEpochInInstantRange` accepts, in list order.
+ *
+ * @param values candidate epoch values
+ * @returns the accepted epochs as numbers; empty when `values` is not an array or none is valid
+ *
+ * @example parseUnixEpochsInInstantRange(["1700000000000", 1.5, 1e20, -1]) // [1700000000000, -1]
+ * @example parseUnixEpochsInInstantRange("1700000000000") // []
+ */
+export declare function parseUnixEpochsInInstantRange(values: unknown): number[];
+/**
+ * Parse a Unix epoch interval `[start, end]`, or null when either value is invalid (see
+ * `parseUnixEpochValue`) or the interval is reversed (`start > end`).
+ *
+ * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
+ * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
+ * @returns `{ start, end }` as safe integers, or null
+ *
+ * @example parseUnixEpochInterval(0, "1500000000") // { start: 0, end: 1500000000 }
+ * @example parseUnixEpochInterval(10, 0) // null (reversed)
+ * @example parseUnixEpochInterval(0, 1.5) // null (fractional)
+ */
+export declare function parseUnixEpochInterval(start: unknown, end: unknown): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Parse two Unix epoch intervals `[aStart, aEnd]` and `[bStart, bEnd]`, or null when either is
+ * invalid or reversed (see `parseUnixEpochInterval`).
+ *
+ * @param aStart first interval start
+ * @param aEnd first interval end
+ * @param bStart second interval start
+ * @param bEnd second interval end
+ * @returns `[a, b]` as `{ start, end }` safe-integer records, or null
+ *
+ * @example parseUnixEpochIntervalPair(0, 10, "5", "20") // [{ start: 0, end: 10 }, { start: 5, end: 20 }]
+ * @example parseUnixEpochIntervalPair(0, 10, 20, 5) // null (B reversed)
+ */
+export declare function parseUnixEpochIntervalPair(aStart: unknown, aEnd: unknown, bStart: unknown, bEnd: unknown): [{
+    start: number;
+    end: number;
+}, {
+    start: number;
+    end: number;
+}] | null;
+/**
+ * Parse a list of Unix epoch `{ start, end }` records, or null when `intervals` is not an array or
+ * any element is not an object holding a valid, non-reversed interval (see
+ * `parseUnixEpochInterval`). An empty list parses to `[]`.
+ *
+ * @param intervals candidate list of `{ start, end }` records
+ * @returns the parsed intervals in input order, or null
+ *
+ * @example parseUnixEpochIntervalList([{ start: 0, end: "10" }]) // [{ start: 0, end: 10 }]
+ * @example parseUnixEpochIntervalList([{ start: 10, end: 0 }]) // null (reversed)
+ * @example parseUnixEpochIntervalList("not-an-array") // null
+ */
+export declare function parseUnixEpochIntervalList(intervals: unknown): Array<{
+    start: number;
+    end: number;
+}> | null;

package/dist/internal/unixEpochValue.js

@@ -0,0 +1,245 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { MAX_EPOCH_NANOSECONDS } from "./epochNanoseconds.js";
+// TC39 Temporal IsValidEpochNanoseconds bound (nsMaxInstant = 10^8 days) in milliseconds: 8.64e15.
+const MAX_EPOCH_MILLISECONDS = Number(MAX_EPOCH_NANOSECONDS / 1000000n);
+// An optionally negative run of ASCII digits and nothing else. `\d` without the `u` flag is
+// ASCII-only, and `$` without the `m` flag does not match before a trailing newline.
+const EPOCH_DIGITS = /^-?\d+$/;
+/**
+ * Parse one Unix epoch argument into a number, or null — the one epoch grammar every `unix/`
+ * function and validator shares.
+ *
+ * - A number must be a safe integer (`Number.isSafeInteger`): fractional values, `NaN`,
+ *   `±Infinity` and anything beyond ±(2^53 − 1) are rejected. Past 2^53 consecutive integers are
+ *   no longer distinct doubles (`2 ** 53 + 1 === 2 ** 53`). Every Temporal instant (±8.64e15 ms) is
+ *   well inside that range.
+ * - A string must be an optionally negative run of ASCII digits (`/^-?\d+$/`) naming a safe
+ *   integer. No whitespace, no `+`, no hex, binary, exponent, decimal point or numeric separator:
+ *   POSIX epoch time is an integer count and has no other notation, so `Number()`'s wider
+ *   StringToNumber grammar (`" 12 "`, `"0x10"`, `"1e3"`, `""` → 0) is not used.
+ * - `-0` reads as `0`.
+ * - Any other type is rejected.
+ *
+ * @param value Unix epoch value as a number or digit string
+ * @returns the epoch as a safe integer, or null when invalid
+ *
+ * @example parseUnixEpochValue(1704067200000) // 1704067200000
+ * @example parseUnixEpochValue("-86400") // -86400
+ * @example parseUnixEpochValue(1.5) // null
+ * @example parseUnixEpochValue(" 12") // null
+ * @example parseUnixEpochValue("1e3") // null
+ */
+export function parseUnixEpochValue(value) {
+    let parsed;
+    if (typeof value === "number") {
+        parsed = value;
+    }
+    else if (typeof value === "string" && EPOCH_DIGITS.test(value)) {
+        parsed = Number(value);
+    }
+    else {
+        return null;
+    }
+    if (!Number.isSafeInteger(parsed)) {
+        return null;
+    }
+    return parsed === 0 ? 0 : parsed;
+}
+/**
+ * Resolve an `epochUnit` option: omitted → `"milliseconds"`; singular or plural `second` /
+ * `millisecond` → the plural name; anything else → null.
+ *
+ * - Singular and plural are the same unit, as in Temporal §13.17 GetTemporalUnitValuedOption.
+ *
+ * @param unit candidate `epochUnit` value
+ * @returns the resolved unit, or null when invalid
+ *
+ * @example resolveUnixEpochUnit(undefined) // "milliseconds"
+ * @example resolveUnixEpochUnit("second") // "seconds"
+ * @example resolveUnixEpochUnit("nanoseconds") // null
+ */
+export function resolveUnixEpochUnit(unit) {
+    switch (unit) {
+        case undefined:
+        case "millisecond":
+        case "milliseconds":
+            return "milliseconds";
+        case "second":
+        case "seconds":
+            return "seconds";
+        default:
+            return null;
+    }
+}
+/**
+ * Resolve the `epochUnit` of an options argument (`{ epochUnit }`), or null.
+ *
+ * - `undefined` options → `"milliseconds"`, the same as omitted (TC39 GetOptionsObject).
+ * - Anything that is not an object (`null`, a legacy positional unit string such as `"seconds"`, a
+ *   number) → null: Temporal GetOptionsObject throws `TypeError` for it, so it is never silently
+ *   read as the default.
+ * - Otherwise `resolveUnixEpochUnit(options.epochUnit)`.
+ *
+ * @param options candidate options argument
+ * @returns the resolved unit, or null when invalid
+ *
+ * @example resolveUnixEpochUnitOptions(undefined) // "milliseconds"
+ * @example resolveUnixEpochUnitOptions({ epochUnit: "second" }) // "seconds"
+ * @example resolveUnixEpochUnitOptions("seconds") // null
+ */
+export function resolveUnixEpochUnitOptions(options) {
+    if (options === undefined) {
+        return "milliseconds";
+    }
+    if (options === null || typeof options !== "object") {
+        return null;
+    }
+    return resolveUnixEpochUnit(options.epochUnit);
+}
+/**
+ * Read a Unix epoch argument (see `parseUnixEpochValue`) as a `Temporal.Instant`, or null when it
+ * is not an epoch or lies outside the Temporal instant range.
+ *
+ * - Seconds scale by 1000 exactly: every in-range seconds value (±8.64e12) times 1000 is a safe
+ *   integer, and any product that is not exact is already outside the instant range.
+ *
+ * @param value Unix epoch value as a number or digit string
+ * @param epochUnit unit the value is expressed in
+ * @returns the instant, or null
+ *
+ * @example unixEpochToInstant(0, "seconds")?.toString() // "1970-01-01T00:00:00Z"
+ * @example unixEpochToInstant(8.64e15 + 1, "milliseconds") // null
+ */
+export function unixEpochToInstant(value, epochUnit) {
+    const epoch = parseUnixEpochValue(value);
+    if (epoch === null) {
+        return null;
+    }
+    try {
+        return Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? epoch * 1000 : epoch);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Express an instant (or zoned date-time) as a Unix epoch in `epochUnit`.
+ *
+ * - Seconds floor toward −∞, so `1969-12-31T23:59:59.999Z` is second `-1`, as POSIX
+ *   `time_t` counts whole elapsed seconds.
+ *
+ * @param value anything with `epochMilliseconds`
+ * @param epochUnit unit of the result
+ * @returns the epoch value
+ *
+ * @example toUnixEpoch({ epochMilliseconds: 1710685845999 }, "seconds") // 1710685845
+ * @example toUnixEpoch({ epochMilliseconds: -1 }, "seconds") // -1
+ */
+export function toUnixEpoch(value, epochUnit) {
+    return epochUnit === "seconds"
+        ? Math.floor(value.epochMilliseconds / 1000)
+        : value.epochMilliseconds;
+}
+/**
+ * Parse an epoch for the aggregators (`sortUnix`, `minUnix`, `maxUnix`) that take no `epochUnit`:
+ * the epoch grammar (`parseUnixEpochValue`) inside ±8.64e15, or null.
+ *
+ * - ±8.64e15 is the instant range in milliseconds. It contains the seconds range (±8.64e12), so no
+ *   valid epoch of either unit is dropped.
+ *
+ * @param value candidate epoch value
+ * @returns the epoch as a number, or null
+ *
+ * @example parseUnixEpochInInstantRange("1700000000000") // 1700000000000
+ * @example parseUnixEpochInInstantRange(1e20) // null
+ */
+export function parseUnixEpochInInstantRange(value) {
+    const epoch = parseUnixEpochValue(value);
+    return epoch !== null && Math.abs(epoch) <= MAX_EPOCH_MILLISECONDS
+        ? epoch
+        : null;
+}
+/**
+ * The values of a list that `parseUnixEpochInInstantRange` accepts, in list order.
+ *
+ * @param values candidate epoch values
+ * @returns the accepted epochs as numbers; empty when `values` is not an array or none is valid
+ *
+ * @example parseUnixEpochsInInstantRange(["1700000000000", 1.5, 1e20, -1]) // [1700000000000, -1]
+ * @example parseUnixEpochsInInstantRange("1700000000000") // []
+ */
+export function parseUnixEpochsInInstantRange(values) {
+    if (!Array.isArray(values))
+        return [];
+    return values
+        .map(parseUnixEpochInInstantRange)
+        .filter((epoch) => epoch !== null);
+}
+/**
+ * Parse a Unix epoch interval `[start, end]`, or null when either value is invalid (see
+ * `parseUnixEpochValue`) or the interval is reversed (`start > end`).
+ *
+ * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
+ * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
+ * @returns `{ start, end }` as safe integers, or null
+ *
+ * @example parseUnixEpochInterval(0, "1500000000") // { start: 0, end: 1500000000 }
+ * @example parseUnixEpochInterval(10, 0) // null (reversed)
+ * @example parseUnixEpochInterval(0, 1.5) // null (fractional)
+ */
+export function parseUnixEpochInterval(start, end) {
+    const startValue = parseUnixEpochValue(start);
+    const endValue = parseUnixEpochValue(end);
+    if (startValue === null || endValue === null || startValue > endValue) {
+        return null;
+    }
+    return { start: startValue, end: endValue };
+}
+/**
+ * Parse two Unix epoch intervals `[aStart, aEnd]` and `[bStart, bEnd]`, or null when either is
+ * invalid or reversed (see `parseUnixEpochInterval`).
+ *
+ * @param aStart first interval start
+ * @param aEnd first interval end
+ * @param bStart second interval start
+ * @param bEnd second interval end
+ * @returns `[a, b]` as `{ start, end }` safe-integer records, or null
+ *
+ * @example parseUnixEpochIntervalPair(0, 10, "5", "20") // [{ start: 0, end: 10 }, { start: 5, end: 20 }]
+ * @example parseUnixEpochIntervalPair(0, 10, 20, 5) // null (B reversed)
+ */
+export function parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd) {
+    const a = parseUnixEpochInterval(aStart, aEnd);
+    const b = parseUnixEpochInterval(bStart, bEnd);
+    return a === null || b === null ? null : [a, b];
+}
+/**
+ * Parse a list of Unix epoch `{ start, end }` records, or null when `intervals` is not an array or
+ * any element is not an object holding a valid, non-reversed interval (see
+ * `parseUnixEpochInterval`). An empty list parses to `[]`.
+ *
+ * @param intervals candidate list of `{ start, end }` records
+ * @returns the parsed intervals in input order, or null
+ *
+ * @example parseUnixEpochIntervalList([{ start: 0, end: "10" }]) // [{ start: 0, end: 10 }]
+ * @example parseUnixEpochIntervalList([{ start: 10, end: 0 }]) // null (reversed)
+ * @example parseUnixEpochIntervalList("not-an-array") // null
+ */
+export function parseUnixEpochIntervalList(intervals) {
+    if (!Array.isArray(intervals)) {
+        return null;
+    }
+    const parsed = [];
+    for (const interval of intervals) {
+        if (!interval || typeof interval !== "object") {
+            return null;
+        }
+        const { start, end } = interval;
+        const next = parseUnixEpochInterval(start, end);
+        if (next === null) {
+            return null;
+        }
+        parsed.push(next);
+    }
+    return parsed;
+}

package/dist/internal/unixFormatReference.d.ts

@@ -0,0 +1,18 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { type UnixEpochUnit } from "./unixEpochValue.js";
+/**
+ * Resolve the `reference` option of the unix formatters to an instant.
+ *
+ * - Omitted: now.
+ * - A string is a numeric unix epoch (`"1709164800000"`) or a UTC ISO string
+ *   (`"2024-02-29T00:00:00Z"`). The numeric reading is tried first, matching `formatUnix`.
+ * - A number is a unix epoch in `epochUnit`.
+ *
+ * @param reference the option as given
+ * @param epochUnit the unit a numeric reference is read in
+ * @returns the instant, or null when the reference is neither form or the clock is unavailable
+ * @example resolveUnixFormatReference(1709164800, "seconds")?.toString() // "2024-02-29T00:00:00Z"
+ * @example resolveUnixFormatReference("2024-02-29T00:00:00Z", "milliseconds")?.toString() // "2024-02-29T00:00:00Z"
+ * @example resolveUnixFormatReference("yesterday", "milliseconds") // null
+ */
+export declare function resolveUnixFormatReference(reference: string | number | undefined, epochUnit: UnixEpochUnit): Temporal.Instant | null;

package/dist/internal/unixFormatReference.js

@@ -0,0 +1,44 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+import { unixEpochToInstant } from "./unixEpochValue.js";
+/**
+ * Resolve the `reference` option of the unix formatters to an instant.
+ *
+ * - Omitted: now.
+ * - A string is a numeric unix epoch (`"1709164800000"`) or a UTC ISO string
+ *   (`"2024-02-29T00:00:00Z"`). The numeric reading is tried first, matching `formatUnix`.
+ * - A number is a unix epoch in `epochUnit`.
+ *
+ * @param reference the option as given
+ * @param epochUnit the unit a numeric reference is read in
+ * @returns the instant, or null when the reference is neither form or the clock is unavailable
+ * @example resolveUnixFormatReference(1709164800, "seconds")?.toString() // "2024-02-29T00:00:00Z"
+ * @example resolveUnixFormatReference("2024-02-29T00:00:00Z", "milliseconds")?.toString() // "2024-02-29T00:00:00Z"
+ * @example resolveUnixFormatReference("yesterday", "milliseconds") // null
+ */
+export function resolveUnixFormatReference(reference, epochUnit) {
+    if (reference === undefined) {
+        try {
+            return Temporal.Now.instant();
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof reference !== "string") {
+        return unixEpochToInstant(reference, epochUnit);
+    }
+    const numericRef = unixEpochToInstant(reference, epochUnit);
+    if (numericRef !== null) {
+        return numericRef;
+    }
+    if (!isValidUtc(reference)) {
+        return null;
+    }
+    try {
+        return Temporal.Instant.from(reference);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/unixZonedDateTime.d.ts

@@ -0,0 +1,22 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read a Unix epoch argument as a `Temporal.ZonedDateTime` under the shared `unix/` options, or
+ * null when anything is invalid.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
+ *   (see `normalizeTimeZone`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the zoned date-time, or null
+ *
+ * @example unixZonedDateTime(0)?.toString() // "1970-01-01T00:00:00+00:00[UTC]"
+ * @example unixZonedDateTime("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixZonedDateTime(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export declare function unixZonedDateTime(value: unknown, options?: {
+    epochUnit?: unknown;
+    timeZone?: unknown;
+}): Temporal.ZonedDateTime | null;

package/dist/internal/unixZonedDateTime.js

@@ -0,0 +1,32 @@
+import { normalizeTimeZone } from "./normalizeTimeZone.js";
+import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
+/**
+ * Read a Unix epoch argument as a `Temporal.ZonedDateTime` under the shared `unix/` options, or
+ * null when anything is invalid.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
+ *   (see `normalizeTimeZone`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the zoned date-time, or null
+ *
+ * @example unixZonedDateTime(0)?.toString() // "1970-01-01T00:00:00+00:00[UTC]"
+ * @example unixZonedDateTime("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixZonedDateTime(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export function unixZonedDateTime(value, options) {
+    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+    const timeZone = normalizeTimeZone(options?.timeZone);
+    if (epochUnit === null || !timeZone) {
+        return null;
+    }
+    try {
+        return (unixEpochToInstant(value, epochUnit)?.toZonedDateTimeISO(timeZone) ?? null);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/utcOffsetString.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Parse a `±HH:MM[:SS]` UTC offset to the nanoseconds local time runs ahead of UTC.
+ *
+ * Temporal exposes no offset parser of its own — `offsetNanoseconds` is only ever read off a
+ * `ZonedDateTime`, which needs a zone GMT does not have here. So the offset is read the one
+ * way Temporal will read it: as the offset half of an instant string anchored at the epoch.
+ * `1970-01-01T00:00:00-04:00` *is* `1970-01-01T04:00:00Z`, so the epoch nanoseconds of that
+ * instant are the offset with its sign flipped. The regex proves the shape and Temporal does
+ * the parsing, so no offset digits are ever sliced by hand.
+ *
+ * @param offset `±HH:MM` or `±HH:MM:SS` offset string
+ * @returns nanoseconds ahead of UTC (negative west of it), or null when `offset` is not one
+ *
+ * @example parseUtcOffsetNanoseconds("-04:00") // -14400000000000n
+ * @example parseUtcOffsetNanoseconds("+05:45") // 20700000000000n
+ * @example parseUtcOffsetNanoseconds("Z") // null — a designator, not an offset
+ */
+export declare function parseUtcOffsetNanoseconds(offset: string): bigint | null;
+/**
+ * Format nanoseconds ahead of UTC as a canonical `±HH:MM[:SS]` offset string.
+ *
+ * The inverse of `parseUtcOffsetNanoseconds`, and the canonicaliser both halves of the
+ * offset-instant pair route through — `+05:45:00` and `+05:45` name one offset, and only one
+ * of them is what GMT stores.
+ *
+ * - Emits the `:SS` field only when the offset is not a whole number of minutes, matching
+ *   `Temporal.ZonedDateTime.prototype.offset`.
+ * - Returns null for an offset finer than a second, or at or beyond ±24 hours — neither is a
+ *   value any zone or standard that stores this pair has ever used.
+ *
+ * @param offsetNanoseconds nanoseconds local time runs ahead of UTC
+ * @returns `±HH:MM[:SS]` offset string, or null when the value is not one GMT stores
+ *
+ * @example formatUtcOffset(-14400000000000n) // "-04:00"
+ * @example formatUtcOffset(0n) // "+00:00"
+ * @example formatUtcOffset(-2670000000000n) // "-00:44:30"
+ * @example formatUtcOffset(1n) // null — finer than a second
+ */
+export declare function formatUtcOffset(offsetNanoseconds: bigint): string | null;

package/dist/internal/utcOffsetString.js

@@ -0,0 +1,75 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { utcOffset } from "../regex/utc-offset.js";
+const NANOSECONDS_PER_SECOND = 1000000000n;
+const SECONDS_PER_MINUTE = 60n;
+const SECONDS_PER_HOUR = 3600n;
+const SECONDS_PER_DAY = 86400n;
+function padTwo(value) {
+    return value.toString().padStart(2, "0");
+}
+/**
+ * Parse a `±HH:MM[:SS]` UTC offset to the nanoseconds local time runs ahead of UTC.
+ *
+ * Temporal exposes no offset parser of its own — `offsetNanoseconds` is only ever read off a
+ * `ZonedDateTime`, which needs a zone GMT does not have here. So the offset is read the one
+ * way Temporal will read it: as the offset half of an instant string anchored at the epoch.
+ * `1970-01-01T00:00:00-04:00` *is* `1970-01-01T04:00:00Z`, so the epoch nanoseconds of that
+ * instant are the offset with its sign flipped. The regex proves the shape and Temporal does
+ * the parsing, so no offset digits are ever sliced by hand.
+ *
+ * @param offset `±HH:MM` or `±HH:MM:SS` offset string
+ * @returns nanoseconds ahead of UTC (negative west of it), or null when `offset` is not one
+ *
+ * @example parseUtcOffsetNanoseconds("-04:00") // -14400000000000n
+ * @example parseUtcOffsetNanoseconds("+05:45") // 20700000000000n
+ * @example parseUtcOffsetNanoseconds("Z") // null — a designator, not an offset
+ */
+export function parseUtcOffsetNanoseconds(offset) {
+    if (typeof offset !== "string" || !utcOffset.test(offset)) {
+        return null;
+    }
+    try {
+        return -Temporal.Instant.from(`1970-01-01T00:00:00${offset}`)
+            .epochNanoseconds;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Format nanoseconds ahead of UTC as a canonical `±HH:MM[:SS]` offset string.
+ *
+ * The inverse of `parseUtcOffsetNanoseconds`, and the canonicaliser both halves of the
+ * offset-instant pair route through — `+05:45:00` and `+05:45` name one offset, and only one
+ * of them is what GMT stores.
+ *
+ * - Emits the `:SS` field only when the offset is not a whole number of minutes, matching
+ *   `Temporal.ZonedDateTime.prototype.offset`.
+ * - Returns null for an offset finer than a second, or at or beyond ±24 hours — neither is a
+ *   value any zone or standard that stores this pair has ever used.
+ *
+ * @param offsetNanoseconds nanoseconds local time runs ahead of UTC
+ * @returns `±HH:MM[:SS]` offset string, or null when the value is not one GMT stores
+ *
+ * @example formatUtcOffset(-14400000000000n) // "-04:00"
+ * @example formatUtcOffset(0n) // "+00:00"
+ * @example formatUtcOffset(-2670000000000n) // "-00:44:30"
+ * @example formatUtcOffset(1n) // null — finer than a second
+ */
+export function formatUtcOffset(offsetNanoseconds) {
+    if (offsetNanoseconds % NANOSECONDS_PER_SECOND !== 0n) {
+        return null;
+    }
+    const totalSeconds = offsetNanoseconds / NANOSECONDS_PER_SECOND;
+    const magnitude = totalSeconds < 0n ? -totalSeconds : totalSeconds;
+    if (magnitude >= SECONDS_PER_DAY) {
+        return null;
+    }
+    const sign = totalSeconds < 0n ? "-" : "+";
+    const hours = magnitude / SECONDS_PER_HOUR;
+    const minutes = (magnitude / SECONDS_PER_MINUTE) % SECONDS_PER_MINUTE;
+    const seconds = magnitude % SECONDS_PER_MINUTE;
+    return seconds === 0n
+        ? `${sign}${padTwo(hours)}:${padTwo(minutes)}`
+        : `${sign}${padTwo(hours)}:${padTwo(minutes)}:${padTwo(seconds)}`;
+}

package/dist/internal/utcZonedDateTime.d.ts

@@ -0,0 +1,16 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone` (UTC when omitted). The utc twin of
+ * `unixZonedDateTime`.
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the zoned date-time, or null when the value or the zone is invalid
+ * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
+ * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
+ */
+export declare function utcZonedDateTime(value: string, options?: {
+    timeZone?: string;
+}): Temporal.ZonedDateTime | null;