@northguild/gmt 1.18.0 → 1.20.0

package/dist/unix/calculate/roundUnix.js

@@ -1,6 +1,5 @@
 import { isValidDateTimeUnit } from "../../plain/index.js";
-import { isObject, resolveDateTimeUnit, roundZonedDateTime, } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameInstant, frameZoned, isObject, normalizeZoneFrame, resolveDateTimeUnit, roundZonedDateTime, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 const ZONED_ROUNDING_UNITS = [
     "day",
@@ -23,12 +22,20 @@ function isZonedRoundingUnit(unit) {
  *   GetTemporalUnitValuedOption accepts both (§13.17).
  * - Date units ("year", "month", "week", in either form) return null: Temporal's
  *   ZonedDateTime.prototype.round accepts no unit larger than "day".
- * - Follows TC39 `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the
- *   zone. Across a transition the result can land after the input — in `Pacific/Chatham`,
- *   1727532300000 (03:50+13:45) truncated to the hour gives 1727532900000, 15 minutes later.
- *   Use `floorToZone` for a boundary that never exceeds the instant.
+ * - Follows TC39 `ZonedDateTime.round`. Below the day it rounds the wall clock and re-resolves it
+ *   in the zone, so across a transition the result can land after the input — in
+ *   `Pacific/Chatham`, 1727532300000 (03:50+13:45) truncated to the hour gives 1727532900000,
+ *   15 minutes later. To the day it rounds between the start of the input's date and the start of
+ *   the next, so `"floor"` and `"trunc"` never leave the input's date, even when a clock change
+ *   makes that date start twice. Use `floorToZone` for a boundary that never exceeds the instant.
  * - `value` is a safe integer or a digit string (`"1706661000000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param options rounding settings: the unit to round to, how to round, and how `value` is read
@@ -50,10 +57,12 @@ export function roundUnix(value, options) {
             return null;
         const { roundingIncrement, roundingMode } = options;
         const epochUnit = resolveUnixEpochUnit(options.epochUnit);
-        const timeZone = normalizeTimeZone(options.timeZone);
+        const frame = normalizeZoneFrame(options.timeZone);
         // One read (GetOption): resolveDateTimeUnit returns a value that is not a string unchanged.
         const smallestUnit = resolveDateTimeUnit(options.smallestUnit);
-        if (!timeZone || epochUnit === null || !isValidDateTimeUnit(smallestUnit)) {
+        if (frame === null ||
+            epochUnit === null ||
+            !isValidDateTimeUnit(smallestUnit)) {
             return null;
         }
         // Temporal ZonedDateTime.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~, « day »)
@@ -65,12 +74,12 @@ export function roundUnix(value, options) {
             return null;
         }
         try {
-            const result = roundZonedDateTime(instant.toZonedDateTimeISO(timeZone), {
+            const result = roundZonedDateTime(frameZoned(instant, frame), {
                 smallestUnit,
                 roundingIncrement,
                 roundingMode,
             });
-            return toUnixEpoch(result, epochUnit);
+            return toUnixEpoch(frameInstant(result, frame), epochUnit);
         }
         catch {
             return null;

package/dist/unix/calculate/setUnix.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
 import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
@@ -10,10 +10,28 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   why order-independent field resolution matters, and why `disambiguation`/`offset` require
  *   `.with()` rather than arithmetic.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns null, where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns null too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   null.
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns null. So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns null, as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - `value` is a safe integer or a digit string (`"1710072000000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
@@ -23,11 +41,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
  * @example setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
  * @example setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
- * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York" }) // 1730616300000 (the second 01:30 keeps -05:00)
- * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York", offset: "ignore" }) // 1730612700000 (re-resolved: the earlier 01:45)
+ * @example setUnix(1729992600000, { minute: 45 }, { timeZone: "Europe/London" }) // 1729993500000 (the second 01:30 keeps +00:00)
+ * @example setUnix(1729992600000, { minute: 45 }, { timeZone: "Europe/London", offset: "ignore" }) // 1729989900000 (re-resolved: the earlier 01:45)
+ * @example setUnix(1710072000000, { hour: "9" }, { timeZone: "UTC" }) // null (not converted)
  * @example setUnix(NaN, { hour: 9 }) // null
  */
-export declare function setUnix(value: number | string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+export declare function setUnix(value: number | string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset" | "era" | "eraYear">, options?: {
     /**
      * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
      * plural. Any other value returns `null`. The result is in the same unit.
@@ -36,8 +55,9 @@ export declare function setUnix(value: number | string, fields: Omit<Temporal.Zo
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the fields are set in: an IANA name, a UTC offset, or `"local"` for the system
-     * time zone. An unknown zone returns `null`.
+     * The time zone the fields are set 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/calculate/setUnix.js

@@ -1,5 +1,4 @@
-import { resolveOverflow, withZonedFields } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { DATE_TIME_FIELDS, frameInstant, frameZoned, normalizeZoneFrame, readSetFields, resolveOverflow, withZonedFields, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
@@ -12,10 +11,28 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *   why order-independent field resolution matters, and why `disambiguation`/`offset` require
  *   `.with()` rather than arithmetic.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns null, where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns null too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   null.
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns null. So does an
+ *   era, an `offset`, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A
+ *   field is read with a property get, as Temporal reads it, so an inherited or getter field is
+ *   set.
+ * - A Temporal date or time object returns null, as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - `value` is a safe integer or a digit string (`"1710072000000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
@@ -25,8 +42,9 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  * @example setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
  * @example setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
  * @example setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
- * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York" }) // 1730616300000 (the second 01:30 keeps -05:00)
- * @example setUnix(1730615400000, { minute: 45 }, { timeZone: "America/New_York", offset: "ignore" }) // 1730612700000 (re-resolved: the earlier 01:45)
+ * @example setUnix(1729992600000, { minute: 45 }, { timeZone: "Europe/London" }) // 1729993500000 (the second 01:30 keeps +00:00)
+ * @example setUnix(1729992600000, { minute: 45 }, { timeZone: "Europe/London", offset: "ignore" }) // 1729989900000 (re-resolved: the earlier 01:45)
+ * @example setUnix(1710072000000, { hour: "9" }, { timeZone: "UTC" }) // null (not converted)
  * @example setUnix(NaN, { hour: 9 }) // null
  */
 export function setUnix(value, fields, options) {
@@ -35,8 +53,8 @@ export function setUnix(value, fields, options) {
             return null;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (!timeZone || epochUnit === null)
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null || epochUnit === null)
             return null;
         const instant = unixEpochToInstant(value, epochUnit);
         if (instant === null)
@@ -46,17 +64,20 @@ export function setUnix(value, fields, options) {
         // Temporal ZonedDateTime.prototype.with: GetTemporalOffsetOption(options, "prefer").
         const offset = optionOrDefault(options?.offset, "prefer");
         try {
-            const zoned = instant.toZonedDateTimeISO(timeZone);
-            // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
-            // properties found") rather than treating it as a no-op, so short-circuit here.
-            const result = Object.keys(fields).length === 0
+            const zoned = frameZoned(instant, frame);
+            const set = readSetFields(fields, DATE_TIME_FIELDS);
+            if (set === null)
+                return null;
+            // Only the values readSetFields checked reach Temporal, on both paths of withZonedFields. An
+            // empty result sets nothing: a no-op here, where Temporal's with() would throw.
+            const result = Object.keys(set).length === 0
                 ? zoned
-                : withZonedFields(zoned, fields, {
+                : withZonedFields(zoned, set, {
                     overflow,
                     disambiguation,
                     offset,
                 });
-            return toUnixEpoch(result, epochUnit);
+            return toUnixEpoch(frameInstant(result, frame), epochUnit);
         }
         catch {
             return null;

package/dist/unix/calculate/startOfQuarterForUnix.d.ts

@@ -9,6 +9,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param options optional: how `value` is read and the zone the quarter is found in
@@ -29,8 +35,10 @@ export declare function startOfQuarterForUnix(value: number | string, options?:
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * The time zone the unit boundaries are found 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/calculate/startOfQuarterForUnix.js

@@ -10,6 +10,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param options optional: how `value` is read and the zone the quarter is found in

package/dist/unix/calculate/startOfUnix.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/isValidUnixUnit.js";
 /**
  * Return the start of the specified unit for a Unix timestamp.
@@ -10,6 +10,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the start
@@ -20,10 +26,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example startOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1704067200000
  * @example startOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706659200
  * @example startOfUnix(-86400000, "year", { timeZone: "UTC" }) // -31536000000 (start of 1969)
- * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730613600000 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour starts at the second 1am)
+ * @example startOfUnix(1729993500000, "hour", { timeZone: "Europe/London" }) // 1729990800000 (1729993500000 is the second, repeated 1:45am of the Oct 27 2024 fall-back; its hour starts at the second 1am)
  * @example startOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706745600 (plural unit, singular epochUnit, UTC by default)
  * @example startOfUnix(1706659200000, "quarter") // null (use startOfQuarterForUnix)
  * @example startOfUnix(NaN, "day") // null
+ * @example startOfUnix(45870000, "day", { timeZone: "-00:44:30" }) // 2670000 (local midnight at a stored offset with seconds)
  */
 export declare function startOfUnix(value: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     /**
@@ -34,8 +41,10 @@ export declare function startOfUnix(value: number | string, unit: Temporal.DateT
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * The time zone the unit boundaries are found 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/calculate/startOfUnix.js

@@ -12,6 +12,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the start
@@ -22,10 +28,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example startOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1704067200000
  * @example startOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706659200
  * @example startOfUnix(-86400000, "year", { timeZone: "UTC" }) // -31536000000 (start of 1969)
- * @example startOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730613600000 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour starts at the second 1am)
+ * @example startOfUnix(1729993500000, "hour", { timeZone: "Europe/London" }) // 1729990800000 (1729993500000 is the second, repeated 1:45am of the Oct 27 2024 fall-back; its hour starts at the second 1am)
  * @example startOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706745600 (plural unit, singular epochUnit, UTC by default)
  * @example startOfUnix(1706659200000, "quarter") // null (use startOfQuarterForUnix)
  * @example startOfUnix(NaN, "day") // null
+ * @example startOfUnix(45870000, "day", { timeZone: "-00:44:30" }) // 2670000 (local midnight at a stored offset with seconds)
  */
 export function startOfUnix(value, unit, options) {
     try {

package/dist/unix/calculate/subtractUnix.d.ts

@@ -7,6 +7,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
@@ -29,8 +35,10 @@ export declare function subtractUnix(value: number | string, units: Partial<Reco
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the calendar arithmetic runs in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * The time zone the calendar arithmetic runs 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/calculate/subtractUnix.js

@@ -1,5 +1,4 @@
-import { subtractFromZoned, isValidAmount, resolveOverflow, } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameInstant, frameZoned, normalizeZoneFrame, readDurationUnits, resolveOverflow, subtractFromZoned, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -10,6 +9,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
@@ -29,15 +34,12 @@ export function subtractUnix(value, units, options) {
             return null;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
+        const frame = normalizeZoneFrame(options?.timeZone);
         const overflow = resolveOverflow(options?.overflow);
-        if (!timeZone || epochUnit === null)
+        if (frame === null || epochUnit === null)
             return null;
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (amounts === null) {
             return null;
         }
         const instant = unixEpochToInstant(value, epochUnit);
@@ -45,8 +47,8 @@ export function subtractUnix(value, units, options) {
             return null;
         }
         try {
-            const zdt = instant.toZonedDateTimeISO(timeZone);
-            return toUnixEpoch(subtractFromZoned(zdt, units, { overflow }), epochUnit);
+            const zdt = frameZoned(instant, frame);
+            return toUnixEpoch(frameInstant(subtractFromZoned(zdt, amounts, { overflow }), frame), epochUnit);
         }
         catch {
             return null;

package/dist/unix/compare/areUnixEqualBy.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/isValidUnixUnit.js";
 /**
  * Compare two Unix epoch values for equality at a given unit.
@@ -12,8 +12,14 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Each value is a safe integer or a string of optionally negative ASCII digits; `unit` may be
  *   singular or plural.
  * - Returns false for an unsupported unit (including `"quarter"`) or invalid input.
+ * - **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 `false`. There `false` is the sentinel,
+ *   not a comparison. An offset to the minute has no such limit.
  *
- * Mapping from date-fns:
+ * Migrating from date-fns:
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
@@ -28,6 +34,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
  * @example areUnixEqualBy("1710498000000", 1710503000000, "days") // true (digit string, plural unit, UTC by default)
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
+ * @example areUnixEqualBy(2669999, 2670000, "day", { timeZone: "-00:44:30" }) // false (the local day turns at 00:44:30Z)
  */
 export declare function areUnixEqualBy(value1: number | string, value2: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     /**
@@ -38,8 +45,10 @@ export declare function areUnixEqualBy(value1: number | string, value2: number |
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `false`.
+     * The time zone the unit boundaries are found 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
+     * `false`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/compare/areUnixEqualBy.js

@@ -12,8 +12,14 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Each value is a safe integer or a string of optionally negative ASCII digits; `unit` may be
  *   singular or plural.
  * - Returns false for an unsupported unit (including `"quarter"`) or invalid input.
+ * - **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 `false`. There `false` is the sentinel,
+ *   not a comparison. An offset to the minute has no such limit.
  *
- * Mapping from date-fns:
+ * Migrating from date-fns:
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
@@ -28,6 +34,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
  * @example areUnixEqualBy("1710498000000", 1710503000000, "days") // true (digit string, plural unit, UTC by default)
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
+ * @example areUnixEqualBy(2669999, 2670000, "day", { timeZone: "-00:44:30" }) // false (the local day turns at 00:44:30Z)
  */
 export function areUnixEqualBy(value1, value2, unit, options) {
     if (!isOptionsArgument(options)) {

package/dist/unix/convert/convertUnixToPlainDate.d.ts

@@ -18,6 +18,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example convertUnixToPlainDate(NaN) // ""
+ * @example convertUnixToPlainDate(1800000, { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainDate(unix: number | string, options?: {
     /**
@@ -28,8 +29,10 @@ export declare function convertUnixToPlainDate(unix: 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/convert/convertUnixToPlainDate.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -21,6 +21,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example convertUnixToPlainDate(NaN) // ""
+ * @example convertUnixToPlainDate(1800000, { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export function convertUnixToPlainDate(unix, options) {
     try {
@@ -28,14 +29,14 @@ export function convertUnixToPlainDate(unix, options) {
             return "";
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (epochUnit === null || !timeZone)
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (epochUnit === null || frame === null)
             return "";
         const instant = unixEpochToInstant(unix, epochUnit);
         if (instant === null)
             return "";
         try {
-            return instant.toZonedDateTimeISO(timeZone).toPlainDate().toString();
+            return frameWallClock(instant, frame).toPlainDate().toString();
         }
         catch {
             return "";

package/dist/unix/convert/convertUnixToPlainDateTime.d.ts

@@ -16,6 +16,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDateTime(-1, { timeZone: "UTC" }) // "1969-12-31T23:59:59.999"
  * @example convertUnixToPlainDateTime("1709164800000", { timeZone: "Asia/Tokyo" }) // "2024-02-29T09:00:00"
  * @example convertUnixToPlainDateTime(NaN) // ""
+ * @example convertUnixToPlainDateTime(45870000, { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainDateTime(unix: number | string, options?: {
     /**
@@ -26,8 +27,10 @@ export declare function convertUnixToPlainDateTime(unix: number | string, option
      */
     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/convert/convertUnixToPlainDateTime.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -19,6 +19,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example convertUnixToPlainDateTime(-1, { timeZone: "UTC" }) // "1969-12-31T23:59:59.999"
  * @example convertUnixToPlainDateTime("1709164800000", { timeZone: "Asia/Tokyo" }) // "2024-02-29T09:00:00"
  * @example convertUnixToPlainDateTime(NaN) // ""
+ * @example convertUnixToPlainDateTime(45870000, { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export function convertUnixToPlainDateTime(unix, options) {
     try {
@@ -26,14 +27,14 @@ export function convertUnixToPlainDateTime(unix, options) {
             return "";
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (epochUnit === null || !timeZone)
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (epochUnit === null || frame === null)
             return "";
         const instant = unixEpochToInstant(unix, epochUnit);
         if (instant === null)
             return "";
         try {
-            return instant.toZonedDateTimeISO(timeZone).toPlainDateTime().toString();
+            return frameWallClock(instant, frame).toString();
         }
         catch {
             return "";

package/dist/unix/convert/convertUnixToPlainTime.d.ts

@@ -14,8 +14,9 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainTime(1706659200000, { timeZone: "UTC" }) // "00:00:00"
  * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example convertUnixToPlainTime(-1, { timeZone: "UTC" }) // "23:59:59.999"
- * @example convertUnixToPlainTime("1706659200000", { timeZone: "local" }) // system-zone wall clock, e.g. "19:00:00" in America/New_York
+ * @example convertUnixToPlainTime("1706659200000", { timeZone: "local" }) // system-zone wall clock, e.g. "09:00:00" in Asia/Tokyo
  * @example convertUnixToPlainTime(NaN) // ""
+ * @example convertUnixToPlainTime(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainTime(unix: number | string, options?: {
     /**
@@ -26,8 +27,10 @@ export declare function convertUnixToPlainTime(unix: 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"`
      */