@northguild/gmt 1.17.0 → 1.19.0

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

@@ -0,0 +1,72 @@
+import type { BusinessCalendar } from "./business-calendar.js";
+/**
+ * An ISO weekday number: 1 (Monday) through 7 (Sunday), as `Temporal.PlainDate#dayOfWeek`
+ * reads it.
+ */
+export type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/**
+ * A daily window of local wall time, half-open: open from `from` up to (not including) `to`.
+ *
+ * - `from` and `to` are wall-clock readings in the schedule's zone, not instants.
+ * - A window belongs to the date it starts on. A Friday night window listed under weekday 5
+ *   runs into Saturday morning; a holiday or override on Friday removes or replaces it, and one
+ *   on Saturday does not.
+ */
+export type LocalWindow = {
+    /**
+     * The wall time the window opens, as an ISO PlainTime string (`"09:00"`, `"17:30:00"`) that
+     * `isValidTime` accepts.
+     */
+    from: string;
+    /**
+     * The wall time the window closes, as an ISO PlainTime string; the window does not include it.
+     * A value after `from` keeps the window inside one local date. A value at or before `from`
+     * wraps past midnight into the next local date: `{ from: "23:00", to: "06:00" }` is a night,
+     * and `{ from: "00:00", to: "00:00" }` is a whole day.
+     */
+    to: string;
+};
+/** One local date whose windows differ from the weekly pattern. */
+export type OperatingOverride = {
+    /** The local date the override applies to, as an ISO PlainDate string in the schedule's zone. */
+    date: string;
+    /**
+     * The windows that date has instead of its weekly ones, holiday or not. `[]` closes the date
+     * for the whole day.
+     */
+    windows: LocalWindow[];
+};
+/**
+ * Weekly opening hours in one zone, with dated exceptions.
+ *
+ * This is deliberately a weekly pattern with dated exceptions, not an RFC 5545 recurrence rule:
+ * there is no monthly or yearly recurrence.
+ */
+export type OperatingSchedule = {
+    /**
+     * 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;
+    /**
+     * The windows of each ISO weekday. A missing weekday, or `[]`, is closed all day. Windows of
+     * one weekday may overlap or touch; they are merged.
+     */
+    weekly: Partial<Record<IsoWeekday, LocalWindow[]>>;
+    /**
+     * The local dates that are closed, as ISO PlainDate strings. A `BusinessCalendar` can be passed
+     * directly: its `holidays` are read, and its `weekend` and `timeZone` are not, because `weekly`
+     * already says which weekdays open and `timeZone` above is the zone.
+     *
+     * @defaultValue None. No date is closed as a holiday.
+     */
+    holidays?: string[] | BusinessCalendar;
+    /**
+     * The single dates whose windows replace the weekly ones. An override wins over a holiday on the
+     * same date, and two overrides for one date make the schedule invalid.
+     *
+     * @defaultValue None. Every date follows the weekly pattern and the holidays.
+     */
+    overrides?: OperatingOverride[];
+};

package/dist/types/overflow.d.ts

@@ -1,2 +1,8 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * 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
+ * nearest valid value, so January 31 plus one month is the last day of February; `"reject"`
+ * refuses the value.
+ */
 export type Overflow = Temporal.ArithmeticOptions["overflow"];

package/dist/types/relative-rounding-method.d.ts

@@ -1 +1,7 @@
+/**
+ * How the `formatRelative*` functions round a fractional distance to a whole number of the unit
+ * displayed. It is applied to the signed value, where a past distance is negative: `"floor"`
+ * rounds toward negative infinity, `"ceil"` toward positive infinity, and `"round"` to the nearest
+ * whole number, a half going toward positive infinity.
+ */
 export type RelativeRoundingMethod = "floor" | "ceil" | "round";

package/dist/types/relative-time-options.d.ts

@@ -5,14 +5,42 @@ import type { RelativeRoundingMethod } from "./relative-rounding-method.js";
  * restrict `largestUnit` or add domain-specific fields.
  */
 export interface RelativeTimeFormatOptions {
-    /** Name style: "long" (default), "short", or "narrow". */
+    /**
+     * The length of the unit name, as the `style` of `Intl.RelativeTimeFormat`: `"long"` ("in 3
+     * months"), `"short"` ("in 3 mo.") or `"narrow"` (the locale's most compact form).
+     *
+     * @defaultValue `"long"`
+     */
     style?: "long" | "short" | "narrow";
-    /** Whether to use relative time words ("in 2 days") or numeric ("2 days"). */
+    /**
+     * Whether a distance may be written as a word instead of a number, as the `numeric` option of
+     * `Intl.RelativeTimeFormat`. `"auto"` uses the locale's word where it has one ("yesterday",
+     * "next year"); `"always"` writes the number every time ("1 day ago").
+     *
+     * @defaultValue `"auto"`
+     */
     numeric?: "always" | "auto";
-    /** The largest unit to display. Each domain restricts the allowed values. */
+    /**
+     * The one unit the distance is written in, whatever its size, so `"hour"` renders a day and a
+     * half as "in 36 hours". Each domain restricts the allowed values to the units its values have,
+     * singular or plural; any other value returns `""`.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
     largestUnit?: string;
-    /** How the computed distance rounds to the display unit. */
+    /**
+     * The way a fractional distance becomes the whole number displayed: `"round"` goes to the nearest
+     * whole number, `"floor"` down and `"ceil"` up. It applies to the signed value, where a past
+     * distance is negative, so `"floor"` turns −1.5 hours into "2 hours ago".
+     *
+     * @defaultValue `"round"`
+     */
     roundingMethod?: RelativeRoundingMethod;
-    /** Anchor point for the relative diff. */
+    /**
+     * The moment the distance is measured from, as an ISO string in the same form as the value
+     * being formatted.
+     *
+     * @defaultValue The current date and time.
+     */
     reference?: string;
 }

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

@@ -1,6 +1,33 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * 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
+ * being compared have: date units for dates, time units for times.
+ */
 export type RoundingOptions<Unit extends Temporal.DateTimeUnit> = {
+    /**
+     * The smallest unit kept in the difference; anything smaller is rounded into it. It may not be
+     * larger than the largest unit asked for.
+     *
+     * @defaultValue None. The difference is not rounded: Temporal uses the smallest unit the
+     * values have, `"day"` for dates and `"nanosecond"` otherwise.
+     */
     smallestUnit?: Temporal.SmallestUnit<Unit>;
+    /**
+     * The step the smallest unit is rounded to, so `15` with `"minute"` rounds to a quarter of an
+     * hour. For a time unit it must divide the next larger unit evenly and be smaller than it (`15`
+     * or `30` minutes, not `7` or `60`); a date unit takes any whole number from 1 up. A non-integer
+     * is truncated first, as Temporal does, and any other value is invalid input.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a value between two steps goes. `"trunc"` rounds toward zero and `"halfExpand"` to
+     * the nearest step, a half going away from zero; the other modes are those of Temporal's
+     * `roundingMode` option.
+     *
+     * @defaultValue `"trunc"`, Temporal's default for a difference.
+     */
     roundingMode?: Temporal.RoundingMode;
 };

package/dist/types/time-cycle-field.d.ts

@@ -1 +1,5 @@
+/**
+ * A time field `cycleTime`, `cycleDateTime` and `cycleZoned` can step and wrap, from `"hour"`
+ * down to `"nanosecond"`: the fields of Temporal's `PlainTime`.
+ */
 export type TimeCycleField = "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";

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

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * 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.
+ */
 export type TimeDurationUnit = keyof Pick<Temporal.DurationLike, "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds">;

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

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

package/dist/types/transport-timestamps.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What a transport timestamp claims to be, in DCSA's `eventClassifierCode` vocabulary:
+ *
+ * - `PLN`: planned, the schedule.
+ * - `EST`: estimated, a prediction that may be revised.
+ * - `REQ`: requested, the time one party asked another for.
+ * - `ACT`: actual, an observation of what happened.
+ *
+ * One field can hold all four. A value is only comparable with another once its class is known:
+ * an estimate compared with an actual as though both were observations is the standard
+ * visibility-dashboard error.
+ */
+export type TimestampClass = "PLN" | "EST" | "REQ" | "ACT";
+/**
+ * One recorded timestamp of an event: what it claims, when it claims it, and when that claim was
+ * recorded.
+ */
+export type TimestampEvent = {
+    /** What the timestamp claims to be: planned, estimated, requested or actual. */
+    classifier: TimestampClass;
+    /**
+     * The moment the timestamp names, as an ISO 8601 instant (`Z` or an offset) or zoned string.
+     * Functions that return it echo it exactly as written.
+     */
+    at: string;
+    /**
+     * When the timestamp was recorded or received, as an ISO 8601 instant or zoned string. It
+     * orders revisions of the same class: the latest recorded is the current one.
+     */
+    recordedAt: string;
+};
+/**
+ * The caller's punctuality tolerance, as ISO 8601 durations of exact time (a day is 24 hours;
+ * years, months and weeks are refused; neither may be negative).
+ *
+ * GMT holds no default: "on time" without a stated tolerance is not a measurement. A 15-minute
+ * tolerance is `{ late: "PT15M" }`; a day-based one is `{ late: "P1D", early: "P1D" }`.
+ */
+export type PunctualityTolerance = {
+    /**
+     * How far after the plan an arrival may be before it is late: a deviation of this much or more
+     * is late. `"PT0S"` makes every arrival at or after the plan late.
+     */
+    late: string;
+    /**
+     * How far before the plan an arrival may be before it is early: a deviation of this much or
+     * more ahead of the plan is early.
+     *
+     * @defaultValue None. An early arrival is on time.
+     */
+    early?: string;
+};
+/** An arrival's punctuality against a `PunctualityTolerance`. */
+export type Punctuality = "early" | "onTime" | "late";

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/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

@@ -6,15 +6,17 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
- *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in 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 units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns Unix epoch number after addition, or null on invalid input
  *
  * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
@@ -23,9 +25,30 @@ 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?: {
+    /**
+     * 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.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * 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"`
+     */
     timeZone?: string;
+    /**
+     * How a result day that does not exist in its month is handled, such as January 31 plus one
+     * month. `"constrain"` clamps to the last valid day, and `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): number | null;

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";
@@ -9,15 +8,17 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
- *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in 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 units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns Unix epoch number after addition, or null on invalid input
  *
  * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
@@ -26,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 {
@@ -33,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);
@@ -49,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

@@ -33,15 +33,19 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   gives the same number back. For an exact count use the `bigint` APIs: `spanNs` in `span/`,
  *   or `toNanoseconds` in `precision/`.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone 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
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read and how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUnix(1706745600000, 1706659200000, "days", { timeZone: "UTC" }) // -1 (measured from the first value to the second)
@@ -52,6 +56,20 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example diffUnix(1704067200000, 1740787200000, ["years", "days"], { timeZone: "UTC" }) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
 export declare function diffUnix(value1: number | string, value2: number | string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * 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"`
+     */
     timeZone?: string;
 } & RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

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";
@@ -37,15 +36,19 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   gives the same number back. For an exact count use the `bigint` APIs: `spanNs` in `span/`,
  *   or `toNanoseconds` in `precision/`.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone 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
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read and how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUnix(1706745600000, 1706659200000, "days", { timeZone: "UTC" }) // -1 (measured from the first value to the second)
@@ -62,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) : "");
@@ -79,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,
@@ -89,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

@@ -23,14 +23,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone 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
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read, how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
@@ -40,6 +44,20 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example diffUnixAsDuration(NaN, 1706745600000, "days") // ""
  */
 export declare function diffUnixAsDuration(value1: number | string, value2: number | string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * 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"`
+     */
     timeZone?: string;
 } & RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

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";
@@ -25,14 +24,18 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone 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
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read, how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
@@ -48,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)) {
@@ -61,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 "";