@northguild/gmt 1.18.0 → 1.20.0

package/dist/unix/interval/splitIntervalByUnitUnix.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
-import { Temporal } from "@js-temporal/polyfill";
-import { resolveDurationUnit, tileByUnit } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { frameInstant, resolveDurationUnit, tileByUnit } from "../../internal/index.js";
 import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
 import { resolveUnixIntervalPair } from "../../internal/resolveUnixIntervalPair.js";
 import { minSlicesForSpan, stepNoFinerThan } from "../../internal/splitStep.js";
@@ -17,7 +17,8 @@ import { toUnixEpoch } from "../../internal/unixEpochValue.js";
  *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
  *   to the month's last day, and stepping from that boundary would keep the shortened day
  *   (February 29, then March 29).
- * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
+ * - Each calendar-unit boundary is `start.add(amount × k)` with Temporal's
+ *   `overflow: "constrain"` (TC39 Temporal `add`), never a step from the previous boundary.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER` (boundaries are then floored to milliseconds).
@@ -37,6 +38,12 @@ import { toUnixEpoch } from "../../internal/unixEpochValue.js";
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
  *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `[]`. An offset to the minute has no
+ *   such limit.
  *
  * @param start Unix epoch in `epochUnit` — interval start
  * @param end Unix epoch in `epochUnit` — interval end
@@ -52,7 +59,7 @@ import { toUnixEpoch } from "../../internal/unixEpochValue.js";
  * @example splitIntervalByUnitUnix("invalid", 86400000, "hour", 1) // []
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6, { maxPieces: 3 }) // [] (4 slices exceed the limit)
  * @example splitIntervalByUnitUnix(0, 86400000, "hour", 6, { maxPieces: 4 }) // [{ start: 0, end: 21600000 }, { start: 21600000, end: 43200000 }, { start: 43200000, end: 64800000 }, { start: 64800000, end: 86400000 }]
- * @example splitIntervalByUnitUnix(1710046800000, 1710216000000, "day", 1, { timeZone: "America/New_York" }) // [{ start: 1710046800000, end: 1710129600000 }, { start: 1710129600000, end: 1710216000000 }] (the first local day is 23 hours)
+ * @example splitIntervalByUnitUnix(1728136800000, 1728306000000, "day", 1, { timeZone: "Australia/Sydney" }) // [{ start: 1728136800000, end: 1728219600000 }, { start: 1728219600000, end: 1728306000000 }] (the first local day is 23 hours)
  * @example splitIntervalByUnitUnix("0", "86400", "hours", 12, { epochUnit: "second" }) // [{ start: 0, end: 43200 }, { start: 43200, end: 86400 }]
  * @example splitIntervalByUnitUnix(0, 2, "millisecond", 500, { epochUnit: "seconds" }) // [{ start: 0, end: 1 }, { start: 1, end: 2 }] (a step finer than the epoch unit gives one-second pieces)
  */
@@ -69,7 +76,7 @@ export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
         if (maxPieces === null) {
             return [];
         }
-        const { startVal, endVal, epochUnit } = pair;
+        const { startVal, endVal, epochUnit, frame } = pair;
         // Temporal's plural duration field name, as the tiling steps add `{ [unit]: amount }`. A step
         // finer than the epoch unit would floor neighbouring boundaries to one value (an empty slice),
         // so it steps by one epoch unit instead.
@@ -77,8 +84,8 @@ export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
         if (startVal.epochNanoseconds === endVal.epochNanoseconds) {
             return [
                 {
-                    start: toUnixEpoch(startVal, epochUnit),
-                    end: toUnixEpoch(endVal, epochUnit),
+                    start: toUnixEpoch(frameInstant(startVal, frame), epochUnit),
+                    end: toUnixEpoch(frameInstant(endVal, frame), epochUnit),
                 },
             ];
         }
@@ -90,8 +97,8 @@ export function splitIntervalByUnitUnix(start, end, unit, amount, options) {
             // Boundaries stay ZonedDateTime (nanosecond) values; only the output is floored to epochUnit.
             const slices = tileByUnit(startVal, endVal, Temporal.ZonedDateTime.compare, resolvedUnit, stepAmount, maxPieces);
             return (slices ?? []).map(([sliceStart, sliceEnd]) => ({
-                start: toUnixEpoch(sliceStart, epochUnit),
-                end: toUnixEpoch(sliceEnd, epochUnit),
+                start: toUnixEpoch(frameInstant(sliceStart, frame), epochUnit),
+                end: toUnixEpoch(frameInstant(sliceEnd, frame), epochUnit),
             }));
         }
         catch {

package/dist/unix/parse/parseDateFromUnix.d.ts

@@ -24,8 +24,10 @@ export declare function parseDateFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseDateFromUnix.js

@@ -1,4 +1,4 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the date portion from a unix epoch value.
@@ -21,8 +21,8 @@ export function parseDateFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
-        return zdt === null ? "" : zdt.toPlainDate().toString();
+        const wallClock = unixWallClock(value, options);
+        return wallClock === null ? "" : wallClock.toPlainDate().toString();
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/unix/parse/parseDayFromUnix.d.ts

@@ -23,8 +23,10 @@ export declare function parseDayFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseDayOfWeekFromUnix.d.ts

@@ -24,8 +24,10 @@ export declare function parseDayOfWeekFromUnix(value: number | string, options?:
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * 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
+     * `null`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseDayOfWeekFromUnix.js

@@ -1,4 +1,4 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of week (1-7) from a unix epoch value.
@@ -21,7 +21,7 @@ export function parseDayOfWeekFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        return unixZonedDateTime(value, options)?.dayOfWeek ?? null;
+        return unixWallClock(value, options)?.dayOfWeek ?? null;
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/unix/parse/parseHourFromUnix.d.ts

@@ -23,8 +23,10 @@ export declare function parseHourFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseMicrosecondFromUnix.d.ts

@@ -23,8 +23,10 @@ export declare function parseMicrosecondFromUnix(value: number | string, options
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseMillisecondFromUnix.d.ts

@@ -23,8 +23,10 @@ export declare function parseMillisecondFromUnix(value: number | string, options
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseMinuteFromUnix.d.ts

@@ -23,8 +23,10 @@ export declare function parseMinuteFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseMonthFromUnix.d.ts

@@ -24,8 +24,10 @@ export declare function parseMonthFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseNanosecondFromUnix.d.ts

@@ -24,8 +24,10 @@ export declare function parseNanosecondFromUnix(value: number | string, options?
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseSecondFromUnix.d.ts

@@ -23,8 +23,10 @@ export declare function parseSecondFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseTimeFromUnix.d.ts

@@ -14,6 +14,7 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
+ * @example parseTimeFromUnix(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function parseTimeFromUnix(value: number | string, options?: {
     /**
@@ -24,8 +25,10 @@ export declare function parseTimeFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseTimeFromUnix.js

@@ -1,4 +1,4 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the time portion from a unix epoch value.
@@ -15,14 +15,15 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
+ * @example parseTimeFromUnix(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function parseTimeFromUnix(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
-        return zdt === null ? "" : zdt.toPlainTime().toString();
+        const wallClock = unixWallClock(value, options);
+        return wallClock === null ? "" : wallClock.toPlainTime().toString();
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/unix/parse/parseUnitFromUnix.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { UnixUnit } from "../validate/index.js";
 /**
  * Units extractable from a unix epoch value via `parseUnitFromUnix`. Covers the
@@ -8,7 +8,7 @@ import type { UnixUnit } from "../validate/index.js";
  *
  * | Member | Description |
  * | --- | --- |
- * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `year` | Four digits (e.g. `2024`, `0005`); a sign and six digits outside 0000–9999 (e.g. `+010000`). |
  * | `month` | Zero-padded 2 (e.g. `03`). |
  * | `week` | Week-of-year, 1–53: ISO 8601 for `weekStartsOn: "monday"`, UTS #35 (minimal days 1) for `"sunday"`, so late-December days can be week 1. |
  * | `day` | Zero-padded 2. |
@@ -33,6 +33,8 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * - `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"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
@@ -40,6 +42,7 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(-61996320000000, "year") // "0005" (1 June of year 5)
  * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
  * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
  * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
@@ -47,6 +50,7 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
  * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
+ * @example parseUnitFromUnix(45870000, "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     /**
@@ -57,8 +61,10 @@ export declare function parseUnitFromUnix(value: number | string, unit: PlainNow
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseUnitFromUnix.js

@@ -1,8 +1,9 @@
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Extract a unit from a unix epoch value.
  *
@@ -11,6 +12,8 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - `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"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
@@ -18,6 +21,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(-61996320000000, "year") // "0005" (1 June of year 5)
  * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
  * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
  * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
@@ -25,6 +29,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
  * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
+ * @example parseUnitFromUnix(45870000, "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export function parseUnitFromUnix(value, unit, options) {
     try {
@@ -32,36 +37,38 @@ export function parseUnitFromUnix(value, unit, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
+        const wallClock = unixWallClock(value, options);
         const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
-        if (zdt === null || typeof unit !== "string" || weekStartsOn === null) {
+        if (wallClock === null ||
+            typeof unit !== "string" ||
+            weekStartsOn === null) {
             return "";
         }
         try {
             switch (resolveDateTimeUnit(unit)) {
                 case "year":
-                    return zdt.year.toString();
+                    return isoYearString(wallClock.year);
                 case "month":
-                    return zdt.month.toString().padStart(2, "0");
+                    return wallClock.month.toString().padStart(2, "0");
                 case "week": {
-                    return (getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
+                    return (getWeekNumber(wallClock.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
                 }
                 case "day":
-                    return zdt.day.toString().padStart(2, "0");
+                    return wallClock.day.toString().padStart(2, "0");
                 case "dayOfWeek":
-                    return zdt.dayOfWeek.toString();
+                    return wallClock.dayOfWeek.toString();
                 case "hour":
-                    return zdt.hour.toString().padStart(2, "0");
+                    return wallClock.hour.toString().padStart(2, "0");
                 case "minute":
-                    return zdt.minute.toString().padStart(2, "0");
+                    return wallClock.minute.toString().padStart(2, "0");
                 case "second":
-                    return zdt.second.toString().padStart(2, "0");
+                    return wallClock.second.toString().padStart(2, "0");
                 case "millisecond":
-                    return zdt.millisecond.toString().padStart(3, "0");
+                    return wallClock.millisecond.toString().padStart(3, "0");
                 case "microsecond":
-                    return zdt.microsecond.toString().padStart(3, "0");
+                    return wallClock.microsecond.toString().padStart(3, "0");
                 case "nanosecond":
-                    return zdt.nanosecond.toString().padStart(3, "0");
+                    return wallClock.nanosecond.toString().padStart(3, "0");
                 default:
                     return "";
             }

package/dist/unix/parse/parseWeekFromUnix.d.ts

@@ -26,8 +26,9 @@ export declare function parseWeekFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the date is read in: an IANA name, a UTC offset, or `"local"` for the system
-     * time zone. An unknown zone returns `null`.
+     * The time zone the date is 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 `null`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseWeekFromUnix.js

@@ -1,6 +1,6 @@
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a unix epoch value.
@@ -26,12 +26,12 @@ export function parseWeekFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        const zdt = unixZonedDateTime(value, options);
+        const wallClock = unixWallClock(value, options);
         const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
-        if (zdt === null || weekStartsOn === null)
+        if (wallClock === null || weekStartsOn === null)
             return null;
         try {
-            return getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn);
+            return getWeekNumber(wallClock.toPlainDate().toString(), weekStartsOn);
         }
         catch {
             return null;

package/dist/unix/parse/parseYearFromUnix.d.ts

@@ -5,12 +5,15 @@ import type { UnixUnit } from "../validate/index.js";
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
  * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
+ * - The year is written as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param options optional: how `value` is read and the zone its wall clock is read in
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(-61996320000000) // "0005" (1 June of year 5)
  * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)
@@ -24,8 +27,10 @@ export declare function parseYearFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseYearFromUnix.js

@@ -6,12 +6,15 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
  * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
+ * - The year is written as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param options optional: how `value` is read and the zone its wall clock is read in
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(-61996320000000) // "0005" (1 June of year 5)
  * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)

package/dist/unix/validate/isValidUnixUnit.d.ts

@@ -15,7 +15,7 @@
  * import { isValidUnixUnit } from "@northguild/gmt/unix";
  * isValidUnixUnit("milliseconds"); // true
  */
-export type UnixUnit = "seconds" | "second" | "milliseconds" | "millisecond";
+export type UnixUnit = "seconds" | "milliseconds" | "second" | "millisecond";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *

package/dist/utc/calculate/addUtc.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -26,17 +26,14 @@ export function addUtc(value, units, options) {
             return "";
         }
         const validUtc = isValidUtc(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUtc || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validUtc || amounts === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            const result = zoned.add(units, {
+            const result = zoned.add(amounts, {
                 overflow: resolveOverflow(options?.overflow),
             });
             return result.toInstant().toString();

package/dist/utc/calculate/diffUtc.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js";
 /**
  * Return the difference between two UTC datetimes measured in the given date-time unit.

package/dist/utc/calculate/diffUtc.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { addToZoned, zonedUntil } from "../../internal/index.js";
 import { differenceRecord } from "../../internal/differenceRecord.js";
 import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";

package/dist/utc/calculate/diffUtcAsDuration.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.js";
 /**
  * Return the difference between two UTC datetimes as an ISO 8601 duration string,

package/dist/utc/calculate/diffUtcAsDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { durationUntilString } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";

package/dist/utc/calculate/endOfQuarterForUtc.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 /**
  * Return the end of the quarter for a given UTC Instant string.

package/dist/utc/calculate/endOfUtc.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the specified date-time `unit` for a given UTC datetime string.