@northguild/gmt 1.18.0 → 1.20.0

package/dist/types/offset.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../internal/temporal.js";
 /**
  * What to do when the UTC offset written in a zoned value disagrees with its time zone, as
  * Temporal's `offset` option (`Temporal.ZonedDateTime.prototype.with(item, { offset })`). It is

package/dist/types/operating-schedule.d.ts

@@ -44,8 +44,9 @@ export type OperatingOverride = {
  */
 export type OperatingSchedule = {
     /**
-     * The time zone the windows are read in: an IANA name or a UTC offset. A UTC offset such as
-     * `"+02:00"` observes no DST.
+     * The time zone the windows are read in, an IANA name or UTC offset: a time zone identifier
+     * (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset`
+     * returns). A UTC offset such as `"+02:00"` observes no DST.
      */
     timeZone: string;
     /**

package/dist/types/overflow.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../internal/temporal.js";
 /**
  * What to do when a date or time field is out of range, as Temporal's `overflow` option
  * (`Temporal.PlainDate.prototype.add(item, { overflow })`). `"constrain"` clamps the field to the

package/dist/types/rounding-options.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../internal/temporal.js";
 /**
  * How a difference is rounded, as the rounding options of Temporal's `until()` and `since()`
  * (`Temporal.PlainDate.prototype.until(other, options)`). `Unit` is the set of units the values

package/dist/types/stored-zoned-classification.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What `classifyStoredZoned` finds when an RFC 9557 string carries both a UTC offset and a
+ * bracketed IANA zone. Every reading is a `Z` instant string (`Temporal.Instant#toString`), and
+ * every offset is `±HH:MM[:SS]`. Each kind carries enough readings to reproduce each of
+ * Temporal's `offset` values (`use`, `ignore`, `prefer`, `reject`).
+ *
+ * @example
+ * import type { StoredZonedClassification } from "@northguild/gmt/types";
+ * const found: StoredZonedClassification = {
+ *   kind: "offsetMismatch",
+ *   storedOffset: "+02:00",
+ *   zoneOffset: "+03:00",
+ *   atStoredOffset: "2016-12-01T07:00:00Z",
+ *   atZoneOffset: "2016-12-01T06:00:00Z",
+ * };
+ */
+export type StoredZonedClassification = {
+    /**
+     * The string names one instant. Either it ends in `Z`, which Temporal reads as exact
+     * whatever the zone's wall clock does, or its offset matches the zone's offset at that
+     * local time (to the minute, or exactly when written with seconds) and the local time
+     * occurs once. `instant` is what `reject`, `prefer` and `ignore` give.
+     */
+    kind: "valid";
+    /** The instant the string names. */
+    instant: string;
+    /** The instant `offset: "use"` gives: the written wall clock minus the written offset. */
+    atStoredOffset: string;
+} | {
+    /**
+     * The local time occurs twice, and the stored offset picks one of the two: `instant`, which
+     * is either `earlier` or `later`. `ignore` gives `earlier` or `later` by `disambiguation`.
+     */
+    kind: "validInOverlap";
+    /** The occurrence the stored offset picks. `reject` and `prefer` give it. */
+    instant: string;
+    /** The first occurrence. */
+    earlier: string;
+    /** The second occurrence. */
+    later: string;
+    /** The instant `offset: "use"` gives. */
+    atStoredOffset: string;
+} | {
+    /**
+     * The local time occurs once, but not at the stored offset. `reject` refuses it, and `ignore`
+     * and `prefer` give `atZoneOffset`.
+     */
+    kind: "offsetMismatch";
+    /** The offset as written in the string, `±HH:MM` or `±HH:MM:SS`. Seconds are kept when written. */
+    storedOffset: string;
+    /** The offset the zone has at that local time. */
+    zoneOffset: string;
+    /** The instant `offset: "use"` gives. */
+    atStoredOffset: string;
+    /** The instant the zone's own offset gives. */
+    atZoneOffset: string;
+} | {
+    /**
+     * The local time occurs twice, and the stored offset picks neither occurrence. `reject`
+     * refuses it, and `ignore` and `prefer` give `earlier` or `later` by `disambiguation`.
+     */
+    kind: "ambiguous";
+    /** The first occurrence. */
+    earlier: string;
+    /** The second occurrence. */
+    later: string;
+    /** The instant `offset: "use"` gives. */
+    atStoredOffset: string;
+} | {
+    /**
+     * The local time falls in a gap, so there is no occurrence to match. `reject` refuses it,
+     * and `ignore` and `prefer` give `earlier` or `later` by `disambiguation`. `earlier` and
+     * `later` are the wall time shifted back or forward by the size of the gap, as
+     * `disambiguation` names them.
+     */
+    kind: "nonexistent";
+    /** The reading `disambiguation: "earlier"` gives. */
+    earlier: string;
+    /** The reading `disambiguation: "later"` and `"compatible"` give. */
+    later: string;
+    /** The instant `offset: "use"` gives. */
+    atStoredOffset: string;
+};

package/dist/types/time-duration-unit.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../internal/temporal.js";
 /**
  * A time field of an ISO 8601 duration, in the plural, from `"hours"` down to `"nanoseconds"`.
  * It names the unit an amount of time is given in or a time difference is measured in.

package/dist/types/time-unit.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../internal/temporal.js";
 /**
  * A time unit in the singular, from `"hour"` down to `"nanosecond"`, as Temporal's rounding and
  * difference options name units.

package/dist/types/two-digit-year.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How a two-digit year (`yy` in a pattern, `YYMMDD` in an EDI value) gets its century.
+ *
+ * No standard says which century a two-digit year belongs to, so GMT holds no cut-off of its own:
+ * the caller names the hundred-year window. A two-digit year is a legacy form; a four-digit year
+ * is the one to ask a data source for.
+ */
+export interface TwoDigitYearOptions {
+    /**
+     * The hundred-year window a two-digit year falls in. A number is the first year of a fixed
+     * window, an integer from 0 to 9900: `2000` reads `00`–`99` as 2000–2099; `1950` reads `50`–`99`
+     * as 1950–1999 and `00`–`49` as 2000–2049. A fixed window gives the same answer in any year,
+     * so it is the form for stored data, archives and anything re-processed later. `"rolling"` is
+     * the hundred years around today: from 50 years before the current UTC calendar year to 49
+     * years after it (in 2026, 1976–2075). It is the form for live messages and never needs
+     * maintenance, but it gives a different answer for the same stored value as years pass. Any
+     * other value returns the function's sentinel.
+     *
+     * @defaultValue None. A value with a two-digit year returns the sentinel: no standard says which
+     * century it belongs to, so the caller states it.
+     */
+    yearWindow?: "rolling" | number;
+}

package/dist/types/utc-now-unit.d.ts

@@ -2,4 +2,4 @@
  * Units extractable from the current UTC instant via `getUtcNowUnit`.
  * Defined as `DateTimeUnit | "dayOfWeek"`.
  */
-export type UtcNowUnit = import("@js-temporal/polyfill").Temporal.SmallestUnit<import("./date-time-unit.js").DateTimeUnit> | "dayOfWeek";
+export type UtcNowUnit = import("../internal/temporal.js").Temporal.SmallestUnit<import("./date-time-unit.js").DateTimeUnit> | "dayOfWeek";

package/dist/types/zone-bucket-unit.d.ts

@@ -8,4 +8,4 @@
  *
  * Narrow a candidate unit with `isValidZoneBucketUnit`.
  */
-export type ZoneBucketUnit = "hour" | "day" | "week" | "month";
+export type ZoneBucketUnit = "month" | "week" | "day" | "hour";

package/dist/unix/calculate/addUnix.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 add
@@ -19,6 +25,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example addUnix(1.5, { days: 1 }) // null (not an integer epoch)
  * @example addUnix("1706659200000", { days: 1 }) // 1706745600000 (digit string)
  * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
+ * @example addUnix(45870000, { days: 1 }, { timeZone: "-00:44:30" }) // 132270000 (a stored offset with seconds)
  */
 export declare function addUnix(value: number | string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
     /**
@@ -29,8 +36,10 @@ export declare function addUnix(value: number | string, units: Partial<Record<Da
      */
     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/addUnix.js

@@ -1,5 +1,4 @@
-import { addToZoned, isValidAmount, resolveOverflow } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { addToZoned, frameInstant, frameZoned, normalizeZoneFrame, readDurationUnits, resolveOverflow, } 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 add
@@ -22,6 +27,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example addUnix(1.5, { days: 1 }) // null (not an integer epoch)
  * @example addUnix("1706659200000", { days: 1 }) // 1706745600000 (digit string)
  * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
+ * @example addUnix(45870000, { days: 1 }, { timeZone: "-00:44:30" }) // 132270000 (a stored offset with seconds)
  */
 export function addUnix(value, units, options) {
     try {
@@ -29,15 +35,12 @@ export function addUnix(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 +48,8 @@ export function addUnix(value, units, options) {
             return null;
         }
         try {
-            const zdt = instant.toZonedDateTimeISO(timeZone);
-            return toUnixEpoch(addToZoned(zdt, units, { overflow }), epochUnit);
+            const zdt = frameZoned(instant, frame);
+            return toUnixEpoch(frameInstant(addToZoned(zdt, amounts, { overflow }), frame), epochUnit);
         }
         catch {
             return null;

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

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js";
 import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
@@ -35,6 +35,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal; a record result
  *   keeps the plural keys.
+ * - **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 value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
@@ -58,8 +64,10 @@ export declare function diffUnix(value1: number | string, value2: number | strin
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone calendar units are measured in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * The time zone calendar units are measured 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/diffUnix.js

@@ -1,6 +1,5 @@
-import { addToZoned, resolveDurationUnit, zonedUntil } from "../../internal/index.js";
+import { addToZoned, frameZoned, normalizeZoneFrame, resolveDurationUnit, zonedUntil, } from "../../internal/index.js";
 import { differenceRecord } from "../../internal/differenceRecord.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
@@ -39,6 +38,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal; a record result
  *   keeps the plural keys.
+ * - **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 value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
@@ -60,8 +65,8 @@ export function diffUnix(value1, value2, units, 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 requested = Array.isArray(units) ? units : [units];
         const plurals = requested.map((unit) => typeof unit === "string" ? resolveDurationUnit(unit) : "");
@@ -77,7 +82,7 @@ export function diffUnix(value1, value2, units, options) {
         if (largestUnit === "")
             return null;
         try {
-            const duration = zonedUntil(instant1.toZonedDateTimeISO(timeZone), instant2.toZonedDateTimeISO(timeZone), {
+            const duration = zonedUntil(frameZoned(instant1, frame), frameZoned(instant2, frame), {
                 largestUnit,
                 smallestUnit: options?.smallestUnit,
                 roundingIncrement: options?.roundingIncrement,
@@ -87,7 +92,7 @@ export function diffUnix(value1, value2, units, options) {
                 return duration[plurals[0]] ?? 0;
             }
             // An unlisted unit between two listed units is carried into the next smaller listed unit.
-            const start = instant1.toZonedDateTimeISO(timeZone);
+            const start = frameZoned(instant1, frame);
             // Record keys are the plural names, as in every other diff family.
             return differenceRecord(start, duration, plurals, {
                 add: (from, amount) => addToZoned(from, amount),

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

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.js";
 import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
@@ -24,6 +24,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * different Temporal types.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal.
+ * - **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 value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
@@ -46,8 +52,10 @@ export declare function diffUnixAsDuration(value1: number | string, value2: numb
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone calendar units are measured in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone calendar units are measured 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/calculate/diffUnixAsDuration.js

@@ -1,5 +1,4 @@
-import { durationUntilString, resolveDurationUnit } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { durationUntilString, frameZoned, normalizeZoneFrame, resolveDurationUnit, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -26,6 +25,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * different Temporal types.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal.
+ * - **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 value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
@@ -46,8 +51,8 @@ export function diffUnixAsDuration(value1, value2, unit, options) {
             return "";
         }
         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 "";
         const largestUnit = typeof unit === "string" ? resolveDurationUnit(unit) : unit;
         if (!isValidDateTimeDurationUnit(largestUnit)) {
@@ -59,7 +64,7 @@ export function diffUnixAsDuration(value1, value2, unit, options) {
             return "";
         }
         try {
-            return durationUntilString(instant1.toZonedDateTimeISO(timeZone), instant2.toZonedDateTimeISO(timeZone), largestUnit, options);
+            return durationUntilString(frameZoned(instant1, frame), frameZoned(instant2, frame), largestUnit, options);
         }
         catch {
             return "";

package/dist/unix/calculate/endOfQuarterForUnix.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
@@ -28,8 +34,10 @@ export declare function endOfQuarterForUnix(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/endOfQuarterForUnix.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/endOfUnix.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 end 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 end
@@ -20,10 +26,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example endOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1706745599999
  * @example endOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706745599
  * @example endOfUnix(-86400000, "year", { timeZone: "UTC" }) // -1 (end of 1969)
- * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730617199999 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour ends at the second 1:59:59.999)
+ * @example endOfUnix(1729993500000, "hour", { timeZone: "Europe/London" }) // 1729994399999 (1729993500000 is the second, repeated 1:45am of the Oct 27 2024 fall-back; its hour ends at the second 1:59:59.999)
  * @example endOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706831999 (plural unit, singular epochUnit, UTC by default)
  * @example endOfUnix(1706659200000, "quarter") // null (use endOfQuarterForUnix)
  * @example endOfUnix(NaN, "day") // null
+ * @example endOfUnix(45870000, "day", { timeZone: "-00:44:30" }) // 89069999 (a stored offset with seconds)
  */
 export declare function endOfUnix(value: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     /**
@@ -34,8 +41,10 @@ export declare function endOfUnix(value: number | string, unit: Temporal.DateTim
      */
     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/endOfUnix.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 end
@@ -22,10 +28,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example endOfUnix(1706659200000, "month", { timeZone: "UTC" }) // 1706745599999
  * @example endOfUnix(1706659200, "day", { epochUnit: "seconds", timeZone: "UTC" }) // 1706745599
  * @example endOfUnix(-86400000, "year", { timeZone: "UTC" }) // -1 (end of 1969)
- * @example endOfUnix(1730616300000, "hour", { timeZone: "America/New_York" }) // 1730617199999 (1730616300000 is the second, repeated 1:45am of the Nov 3 2024 fall-back; its hour ends at the second 1:59:59.999)
+ * @example endOfUnix(1729993500000, "hour", { timeZone: "Europe/London" }) // 1729994399999 (1729993500000 is the second, repeated 1:45am of the Oct 27 2024 fall-back; its hour ends at the second 1:59:59.999)
  * @example endOfUnix(1706780800, "days", { epochUnit: "second" }) // 1706831999 (plural unit, singular epochUnit, UTC by default)
  * @example endOfUnix(1706659200000, "quarter") // null (use endOfQuarterForUnix)
  * @example endOfUnix(NaN, "day") // null
+ * @example endOfUnix(45870000, "day", { timeZone: "-00:44:30" }) // 89069999 (a stored offset with seconds)
  */
 export function endOfUnix(value, unit, options) {
     try {

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

@@ -28,8 +28,9 @@ export declare function isBetweenUnix(value: number | string, start: number | st
     epochUnit?: UnixUnit;
     /**
      * A time zone that is validated only: the comparison is on exact instants, so the zone never
-     * changes the result. It is an IANA name, a UTC offset, or `"local"` for the system time zone.
-     * An unknown zone returns `false`.
+     * changes the result. It is 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/calculate/isBetweenUnix.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 { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { Temporal } from "../../internal/temporal.js";
+import { normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
@@ -29,14 +29,14 @@ export function isBetweenUnix(value, start, end, options) {
             return false;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
+        const frame = normalizeZoneFrame(options?.timeZone);
         // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
         const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
         const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
-        if (!timeZone || epochUnit === null)
+        if (frame === null || epochUnit === null)
             return false;
         const instant = unixEpochToInstant(value, epochUnit);
         const startInstant = unixEpochToInstant(start, epochUnit);

package/dist/unix/calculate/roundUnix.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";
 /**
  * Round a Unix timestamp to the specified unit.
@@ -9,12 +9,20 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   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
@@ -60,8 +68,10 @@ export declare function roundUnix(value: number | string, options: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall clock is rounded 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 is rounded 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"`
      */