@northguild/gmt 1.18.0 → 1.20.0

package/dist/timescale/calculate/taiMinusUtc.js

@@ -0,0 +1,38 @@
+import { LEAP_SECOND_STEPS, NANOSECONDS_PER_SECOND, parseUtcReading, taiOfUtc, } from "../../internal/index.js";
+/**
+ * Return TAI − UTC, in whole seconds, at a UTC instant.
+ *
+ * - From the IERS leap-second table built into GMT (Leap_Second.dat through Bulletin C 72,
+ *   6 July 2026): 10 s from 1972-01-01, 37 s from 2017-01-01 on. The table is closed
+ *   (continuous UTC from 20 May 2027, CGPM 2026), so 37 holds for every later date.
+ * - At an inserted leap second (`…T23:59:60Z`, accepted only on the 27 listed days) the value is
+ *   the one before the insertion: TAI − UTC changes at 00:00:00 UTC.
+ * - `null` before 1972-01-01 (TAI − UTC was then fractional with a daily rate term), for a
+ *   second-60 string on a day with no insertion, and on invalid input.
+ *
+ * @param isoString ISO 8601 instant string; a listed leap second (`…T23:59:60Z`) is accepted
+ * @returns TAI − UTC in seconds, or null on invalid input or a date before 1972
+ *
+ * @example taiMinusUtc("2024-01-01T00:00:00Z") // 37
+ * @example taiMinusUtc("2016-01-01T00:00:00Z") // 36
+ * @example taiMinusUtc("2016-12-31T23:59:60Z") // 36 — the inserted second
+ * @example taiMinusUtc("2100-01-01T00:00:00Z") // 37
+ * @example taiMinusUtc("1971-01-01T00:00:00Z") // null — before 1972
+ */
+export function taiMinusUtc(isoString) {
+    try {
+        const reading = parseUtcReading(isoString);
+        if (reading === null) {
+            return null;
+        }
+        const tai = taiOfUtc(LEAP_SECOND_STEPS, reading);
+        if (tai === null) {
+            return null;
+        }
+        return (Number((tai - reading.epochNanoseconds) / NANOSECONDS_PER_SECOND) -
+            (reading.secondSixty ? 1 : 0));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/timescale/convert/fromTAI.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Convert a TAI time-scale string to a UTC instant string.
+ *
+ * - Reads `YYYY-MM-DDTHH:MM:SS[.fraction] TAI`: four-digit year, `T`, seconds required, 1 to 9
+ *   fraction digits after `.`, one space, `TAI` (the FITS time-scale token). TAI has no second 60.
+ * - UTC = TAI − (TAI − UTC), from the IERS leap-second table built into GMT (Leap_Second.dat
+ *   through Bulletin C 72, 6 July 2026). The table is closed: after the last insertion
+ *   (2016-12-31) TAI − UTC stays 37 s.
+ * - During an inserted leap second the result is `…T23:59:60Z` (ITU-R TF.460-6 Annex 3). Only this
+ *   realm's functions read that string back; other GMT functions reject a second of 60.
+ * - "" before 1972-01-01T00:00:10 TAI and on invalid input.
+ *
+ * @param taiString TAI time-scale string
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input or a date before 1972
+ *
+ * @example fromTAI("2026-01-01T00:00:37 TAI") // "2026-01-01T00:00:00Z"
+ * @example fromTAI("2017-01-01T00:00:36 TAI") // "2016-12-31T23:59:60Z"
+ * @example fromTAI("2017-01-01T00:00:36.5 TAI") // "2016-12-31T23:59:60.5Z"
+ * @example fromTAI("2024-01-01T00:00:37 GPS") // "" — wrong token
+ * @example fromTAI("2016-12-31T23:59:60 TAI") // "" — TAI has no leap seconds
+ */
+export declare function fromTAI(taiString: string): string;

package/dist/timescale/convert/fromTAI.js

@@ -0,0 +1,35 @@
+import { formatUtcReading, LEAP_SECOND_STEPS, parseTimeScaleString, utcOfTai, } from "../../internal/index.js";
+/**
+ * Convert a TAI time-scale string to a UTC instant string.
+ *
+ * - Reads `YYYY-MM-DDTHH:MM:SS[.fraction] TAI`: four-digit year, `T`, seconds required, 1 to 9
+ *   fraction digits after `.`, one space, `TAI` (the FITS time-scale token). TAI has no second 60.
+ * - UTC = TAI − (TAI − UTC), from the IERS leap-second table built into GMT (Leap_Second.dat
+ *   through Bulletin C 72, 6 July 2026). The table is closed: after the last insertion
+ *   (2016-12-31) TAI − UTC stays 37 s.
+ * - During an inserted leap second the result is `…T23:59:60Z` (ITU-R TF.460-6 Annex 3). Only this
+ *   realm's functions read that string back; other GMT functions reject a second of 60.
+ * - "" before 1972-01-01T00:00:10 TAI and on invalid input.
+ *
+ * @param taiString TAI time-scale string
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input or a date before 1972
+ *
+ * @example fromTAI("2026-01-01T00:00:37 TAI") // "2026-01-01T00:00:00Z"
+ * @example fromTAI("2017-01-01T00:00:36 TAI") // "2016-12-31T23:59:60Z"
+ * @example fromTAI("2017-01-01T00:00:36.5 TAI") // "2016-12-31T23:59:60.5Z"
+ * @example fromTAI("2024-01-01T00:00:37 GPS") // "" — wrong token
+ * @example fromTAI("2016-12-31T23:59:60 TAI") // "" — TAI has no leap seconds
+ */
+export function fromTAI(taiString) {
+    try {
+        const label = parseTimeScaleString(taiString, "TAI");
+        if (label === null || label.secondSixty) {
+            return "";
+        }
+        const reading = utcOfTai(LEAP_SECOND_STEPS, label.labelNanoseconds);
+        return reading === null ? "" : formatUtcReading(reading);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/timescale/convert/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./fromTAI.js";
+export * from "./toTAI.js";

package/dist/timescale/convert/index.js

@@ -0,0 +1,2 @@
+export * from "./fromTAI.js";
+export * from "./toTAI.js";

package/dist/timescale/convert/toTAI.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Convert a UTC instant to a TAI time-scale string, `YYYY-MM-DDTHH:MM:SS[.fraction] TAI`.
+ *
+ * - TAI = UTC + (TAI − UTC), from the IERS leap-second table built into GMT (Leap_Second.dat
+ *   through Bulletin C 72, 6 July 2026). The table is closed: the CGPM decided in 2026 that UTC
+ *   becomes continuous on 20 May 2027, so after the last insertion (2016-12-31) TAI − UTC stays
+ *   37 s.
+ * - An inserted leap second maps to its own TAI second: `2016-12-31T23:59:60Z` is
+ *   `2017-01-01T00:00:36 TAI`. A second 60 on any other day returns "".
+ * - Accepts any offset or bracketed zone `toNanoseconds` accepts; TAI has no zone.
+ * - `TAI` is the FITS time-scale token. No other GMT function reads the string; `fromTAI` does.
+ * - "" before 1972-01-01, for a result past year 9999, and on invalid input.
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns the TAI time-scale string, or "" on invalid input or a date before 1972
+ *
+ * @example toTAI("2026-01-01T00:00:00Z") // "2026-01-01T00:00:37 TAI"
+ * @example toTAI("2013-06-01T00:00:00Z") // "2013-06-01T00:00:35 TAI"
+ * @example toTAI("2016-12-31T23:59:60.5Z") // "2017-01-01T00:00:36.5 TAI"
+ * @example toTAI("2017-12-31T23:59:60Z") // "" — no leap second that day
+ * @example toTAI("1971-12-31T00:00:00Z") // ""
+ */
+export declare function toTAI(isoString: string): string;

package/dist/timescale/convert/toTAI.js

@@ -0,0 +1,39 @@
+import { formatTimeScaleString, LEAP_SECOND_STEPS, parseUtcReading, taiOfUtc, } from "../../internal/index.js";
+/**
+ * Convert a UTC instant to a TAI time-scale string, `YYYY-MM-DDTHH:MM:SS[.fraction] TAI`.
+ *
+ * - TAI = UTC + (TAI − UTC), from the IERS leap-second table built into GMT (Leap_Second.dat
+ *   through Bulletin C 72, 6 July 2026). The table is closed: the CGPM decided in 2026 that UTC
+ *   becomes continuous on 20 May 2027, so after the last insertion (2016-12-31) TAI − UTC stays
+ *   37 s.
+ * - An inserted leap second maps to its own TAI second: `2016-12-31T23:59:60Z` is
+ *   `2017-01-01T00:00:36 TAI`. A second 60 on any other day returns "".
+ * - Accepts any offset or bracketed zone `toNanoseconds` accepts; TAI has no zone.
+ * - `TAI` is the FITS time-scale token. No other GMT function reads the string; `fromTAI` does.
+ * - "" before 1972-01-01, for a result past year 9999, and on invalid input.
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns the TAI time-scale string, or "" on invalid input or a date before 1972
+ *
+ * @example toTAI("2026-01-01T00:00:00Z") // "2026-01-01T00:00:37 TAI"
+ * @example toTAI("2013-06-01T00:00:00Z") // "2013-06-01T00:00:35 TAI"
+ * @example toTAI("2016-12-31T23:59:60.5Z") // "2017-01-01T00:00:36.5 TAI"
+ * @example toTAI("2017-12-31T23:59:60Z") // "" — no leap second that day
+ * @example toTAI("1971-12-31T00:00:00Z") // ""
+ */
+export function toTAI(isoString) {
+    try {
+        const reading = parseUtcReading(isoString);
+        if (reading === null) {
+            return "";
+        }
+        const tai = taiOfUtc(LEAP_SECOND_STEPS, reading);
+        if (tai === null) {
+            return "";
+        }
+        return formatTimeScaleString({ labelNanoseconds: tai, secondSixty: false }, "TAI");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/timescale/index.d.ts

@@ -0,0 +1,4 @@
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
+export * from "./calculate/index.js";
+export * from "./convert/index.js";
+export * from "./validate/index.js";

package/dist/timescale/index.js

@@ -0,0 +1,5 @@
+// Re-export `Temporal`, `Intl` and `toTemporalInstant` from the internal seam so every namespace subpath offers them
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
+export * from "./calculate/index.js";
+export * from "./convert/index.js";
+export * from "./validate/index.js";

package/dist/timescale/validate/index.d.ts

@@ -0,0 +1 @@
+export * from "./isLeapSecond.js";

package/dist/timescale/validate/index.js

@@ -0,0 +1 @@
+export * from "./isLeapSecond.js";

package/dist/timescale/validate/isLeapSecond.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Return true when a UTC instant string is one of the 27 inserted leap seconds.
+ *
+ * - A table lookup, not a pattern match: `23:59:60` is well-formed on any day and real on 27 of
+ *   them, the days the IERS leap-second table built into GMT lists (Leap_Second.dat through
+ *   Bulletin C 72, 6 July 2026). The table is closed (continuous UTC from 20 May 2027, CGPM
+ *   2026), so 2016-12-31 is the last. For the syntax test alone, use `hasSecond60`.
+ * - Accepts the inserted second in any offset spelling (`2017-01-01T08:59:60+09:00`).
+ * - Leap smearing is not a leap second: a smeared clock never reads `23:59:60` and is up to a second
+ *   off true UTC around an insertion. GMT cannot detect smearing.
+ * - `false` is also the answer for every ordinary second.
+ * - **Compatibility:** in 1.19.0 and earlier `isLeapSecond` (in `plain/`) was the syntactic
+ *   second-60 test, now `hasSecond60`; a call relying on that now returns `false` on days with no
+ *   insertion, and for a second 60 that is not an extended-format instant (`"23:59:60"`, no
+ *   designator, a lowercase `t`, basic format).
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns true for an inserted leap second, or false otherwise and on invalid input
+ *
+ * @example isLeapSecond("2016-12-31T23:59:60Z") // true
+ * @example isLeapSecond("2009-01-01T08:59:60+09:00") // true
+ * @example isLeapSecond("2017-12-31T23:59:60Z") // false — well-formed, no insertion that day
+ * @example isLeapSecond("2016-12-31T23:59:59Z") // false
+ */
+export declare function isLeapSecond(isoString: string): boolean;

package/dist/timescale/validate/isLeapSecond.js

@@ -0,0 +1,36 @@
+import { LEAP_SECOND_STEPS, parseUtcReading, taiOfUtc } from "../../internal/index.js";
+/**
+ * Return true when a UTC instant string is one of the 27 inserted leap seconds.
+ *
+ * - A table lookup, not a pattern match: `23:59:60` is well-formed on any day and real on 27 of
+ *   them, the days the IERS leap-second table built into GMT lists (Leap_Second.dat through
+ *   Bulletin C 72, 6 July 2026). The table is closed (continuous UTC from 20 May 2027, CGPM
+ *   2026), so 2016-12-31 is the last. For the syntax test alone, use `hasSecond60`.
+ * - Accepts the inserted second in any offset spelling (`2017-01-01T08:59:60+09:00`).
+ * - Leap smearing is not a leap second: a smeared clock never reads `23:59:60` and is up to a second
+ *   off true UTC around an insertion. GMT cannot detect smearing.
+ * - `false` is also the answer for every ordinary second.
+ * - **Compatibility:** in 1.19.0 and earlier `isLeapSecond` (in `plain/`) was the syntactic
+ *   second-60 test, now `hasSecond60`; a call relying on that now returns `false` on days with no
+ *   insertion, and for a second 60 that is not an extended-format instant (`"23:59:60"`, no
+ *   designator, a lowercase `t`, basic format).
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns true for an inserted leap second, or false otherwise and on invalid input
+ *
+ * @example isLeapSecond("2016-12-31T23:59:60Z") // true
+ * @example isLeapSecond("2009-01-01T08:59:60+09:00") // true
+ * @example isLeapSecond("2017-12-31T23:59:60Z") // false — well-formed, no insertion that day
+ * @example isLeapSecond("2016-12-31T23:59:59Z") // false
+ */
+export function isLeapSecond(isoString) {
+    try {
+        const reading = parseUtcReading(isoString);
+        return (reading !== null &&
+            reading.secondSixty &&
+            taiOfUtc(LEAP_SECOND_STEPS, reading) !== null);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/transport/calculate/crossingTime.d.ts

@@ -39,16 +39,21 @@ export interface Crossing {
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   crossing is a data error, not a negative transit), or when the zone is invalid. A zero-length
  *   crossing is `PT0S`.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of entering the crossing
  * @param exit ISO 8601 zoned datetime or instant string of leaving it
- * @param targetZone IANA timeZone identifier or fixed offset the crossing is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   crossing is read in
  * @returns exact duration and zone-local entry and exit, or null on invalid input
  *
  * @example crossingTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]" }
  * @example crossingTime("2024-06-15T10:00:00+09:00", "2024-06-15T12:00:00+09:00", "Asia/Tokyo") // { duration: "PT2H", enter: "2024-06-15T10:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T12:00:00+09:00[Asia/Tokyo]" }
- * @example crossingTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York") // { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]", exit: "2024-03-10T08:00:00-04:00[America/New_York]" } (seven elapsed hours across the spring-forward)
- * @example crossingTime("2024-11-03T05:30:00Z", "2024-11-03T06:30:00Z", "America/New_York") // { duration: "PT1H", enter: "2024-11-03T01:30:00-04:00[America/New_York]", exit: "2024-11-03T01:30:00-05:00[America/New_York]" } (both ends read 01:30; the offsets tell them apart)
+ * @example crossingTime("2024-10-05T14:00:00Z", "2024-10-05T21:00:00Z", "Australia/Sydney") // { duration: "PT7H", enter: "2024-10-06T00:00:00+10:00[Australia/Sydney]", exit: "2024-10-06T08:00:00+11:00[Australia/Sydney]" } (seven elapsed hours across the spring-forward)
+ * @example crossingTime("2024-10-27T00:30:00Z", "2024-10-27T01:30:00Z", "Europe/London") // { duration: "PT1H", enter: "2024-10-27T01:30:00+01:00[Europe/London]", exit: "2024-10-27T01:30:00+00:00[Europe/London]" } (both ends read 01:30; the offsets tell them apart)
  * @example crossingTime("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z", "Asia/Tokyo") // { duration: "PT0S", enter: "2024-06-15T19:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T19:00:00+09:00[Asia/Tokyo]" }
  * @example crossingTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "+02:00") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[+02:00]", exit: "2024-06-16T03:00:00+02:00[+02:00]" } (a fixed offset renders with no DST)
  * @example crossingTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London") // null (exit before entry)

package/dist/transport/calculate/crossingTime.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { instantFrom } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
@@ -31,16 +31,21 @@ import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   crossing is a data error, not a negative transit), or when the zone is invalid. A zero-length
  *   crossing is `PT0S`.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of entering the crossing
  * @param exit ISO 8601 zoned datetime or instant string of leaving it
- * @param targetZone IANA timeZone identifier or fixed offset the crossing is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   crossing is read in
  * @returns exact duration and zone-local entry and exit, or null on invalid input
  *
  * @example crossingTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]" }
  * @example crossingTime("2024-06-15T10:00:00+09:00", "2024-06-15T12:00:00+09:00", "Asia/Tokyo") // { duration: "PT2H", enter: "2024-06-15T10:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T12:00:00+09:00[Asia/Tokyo]" }
- * @example crossingTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York") // { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]", exit: "2024-03-10T08:00:00-04:00[America/New_York]" } (seven elapsed hours across the spring-forward)
- * @example crossingTime("2024-11-03T05:30:00Z", "2024-11-03T06:30:00Z", "America/New_York") // { duration: "PT1H", enter: "2024-11-03T01:30:00-04:00[America/New_York]", exit: "2024-11-03T01:30:00-05:00[America/New_York]" } (both ends read 01:30; the offsets tell them apart)
+ * @example crossingTime("2024-10-05T14:00:00Z", "2024-10-05T21:00:00Z", "Australia/Sydney") // { duration: "PT7H", enter: "2024-10-06T00:00:00+10:00[Australia/Sydney]", exit: "2024-10-06T08:00:00+11:00[Australia/Sydney]" } (seven elapsed hours across the spring-forward)
+ * @example crossingTime("2024-10-27T00:30:00Z", "2024-10-27T01:30:00Z", "Europe/London") // { duration: "PT1H", enter: "2024-10-27T01:30:00+01:00[Europe/London]", exit: "2024-10-27T01:30:00+00:00[Europe/London]" } (both ends read 01:30; the offsets tell them apart)
  * @example crossingTime("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z", "Asia/Tokyo") // { duration: "PT0S", enter: "2024-06-15T19:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T19:00:00+09:00[Asia/Tokyo]" }
  * @example crossingTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "+02:00") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[+02:00]", exit: "2024-06-16T03:00:00+02:00[+02:00]" } (a fixed offset renders with no DST)
  * @example crossingTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London") // null (exit before entry)

package/dist/transport/calculate/cutoffAt.d.ts

@@ -1,7 +1,10 @@
 import type { BusinessCalendar, RollConvention } from "../../types/index.js";
 /** Options for `cutoffAt`. */
 export interface CutoffOptions {
-    /** The time zone the cut-off is read in, the terminal's clock: an IANA name or a UTC offset. */
+    /**
+     * The time zone the cut-off is read in, the terminal's clock: an IANA name or a UTC offset to the
+     * minute (what `isValidTimeZone` accepts).
+     */
     timeZone: string;
     /**
      * The local time of day the cut-off is pinned to (`"17:00"`), as `isValidTime` accepts.
@@ -69,6 +72,8 @@ export interface CutoffOptions {
  *   **nonexistent** one (a skipped hour, a deleted day) returns `""` rather than being
  *   shifted. An exact result that is not re-resolved stays as it is.
  * - Returns the cut-off as a zoned string in `timeZone`, or `""` on invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadline counts back from
  * @param offset ISO 8601 duration before the anchor
@@ -78,12 +83,12 @@ export interface CutoffOptions {
  * @example cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00" }) // "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"
  * @example cutoffAt("2024-06-14T16:00:00Z", "PT48H", { timeZone: "Europe/Amsterdam" }) // "2024-06-12T18:00:00+02:00[Europe/Amsterdam]" (48 hours keeps the departure's 18:00)
  * @example cutoffAt("2024-06-14T16:00:00Z", "P1D", { timeZone: "Europe/Amsterdam", atLocalTime: "10:00" }) // "2024-06-13T10:00:00+02:00[Europe/Amsterdam]"
- * @example cutoffAt("2024-11-05T17:00:00Z", "PT96H", { timeZone: "America/New_York" }) // "2024-11-01T13:00:00-04:00[America/New_York]" (96 elapsed hours across the fall-back)
- * @example cutoffAt("2024-03-11T22:00:00Z", "P2D", { timeZone: "America/New_York", atLocalTime: "17:00" }) // "2024-03-09T17:00:00-05:00[America/New_York]" (17:00 local, across the spring-forward)
+ * @example cutoffAt("2024-04-09T07:00:00Z", "PT96H", { timeZone: "Australia/Sydney" }) // "2024-04-05T18:00:00+11:00[Australia/Sydney]" (96 elapsed hours across the fall-back)
+ * @example cutoffAt("2024-04-01T16:00:00Z", "P2D", { timeZone: "Europe/London", atLocalTime: "17:00" }) // "2024-03-30T17:00:00+00:00[Europe/London]" (17:00 local, across the spring-forward)
  * @example cutoffAt("2024-06-18T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" }, roll: "preceding" }) // "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" (Sunday rolls back to Friday)
  * @example cutoffAt("2024-06-18T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" } }) // "" (a calendar needs a roll convention)
- * @example cutoffAt("2024-11-04T23:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "01:30" }) // "2024-11-03T01:30:00-04:00[America/New_York]" (a repeated hour takes the earlier pass)
- * @example cutoffAt("2024-03-11T22:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "02:30" }) // "" (02:30 on 10 March never happened)
+ * @example cutoffAt("2024-10-28T18:00:00Z", "P1D", { timeZone: "Europe/London", atLocalTime: "01:30" }) // "2024-10-27T01:30:00+01:00[Europe/London]" (a repeated hour takes the earlier pass)
+ * @example cutoffAt("2024-10-07T07:00:00Z", "P1D", { timeZone: "Australia/Sydney", atLocalTime: "02:30" }) // "" (02:30 on 6 October never happened)
  * @example cutoffAt("2024-06-14T18:00:00", "P2D", { timeZone: "Europe/Amsterdam" }) // "" (a zoneless anchor is not a moment)
  * @example cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", roll: "preceding" }) // "" (a roll needs a calendar)
  */

package/dist/transport/calculate/cutoffAt.js

@@ -1,104 +1,8 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { rollDate } from "../../calendar/business/rollDate.js";
-import { isValidBusinessCalendar } from "../../calendar/validate/isValidBusinessCalendar.js";
-import { isValidRollConvention } from "../../calendar/validate/isValidRollConvention.js";
-import { isValidDuration } from "../../duration/validate/isValidDuration.js";
-import { classifyLocal } from "../../instant/convert/classifyLocal.js";
-import { resolveLocal } from "../../instant/convert/resolveLocal.js";
-import { instantFrom } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { cutoffAtResolved, resolveCutoffTime, resolveSharedCutoffOptions, } from "../../internal/cutoffAtResolved.js";
+import { instantFrom, parseInstantNanoseconds } from "../../internal/index.js";
+import { isDurationString } from "../../internal/inputChecks.js";
 import { isObject } from "../../internal/isObject.js";
-import { isValidTime } from "../../plain/validate/isValidTime.js";
-import { isValidInstant } from "../../precision/validate/isValidInstant.js";
-import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
-function resolveOptions(options) {
-    if (!isObject(options)) {
-        return null;
-    }
-    const { timeZone, atLocalTime, calendar, roll } = options;
-    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
-        return null;
-    }
-    if (atLocalTime !== undefined && !isValidTime(atLocalTime)) {
-        return null;
-    }
-    if (calendar !== undefined && !isValidBusinessCalendar(calendar)) {
-        return null;
-    }
-    if (roll !== undefined && !isValidRollConvention(roll)) {
-        return null;
-    }
-    // Rolling needs both a calendar and a direction, and no standard supplies either one by
-    // default: a calendar without a roll, or a roll without a calendar, is a missing term.
-    if ((calendar === undefined) !== (roll === undefined)) {
-        return null;
-    }
-    return {
-        timeZone,
-        atLocalTime: atLocalTime === undefined ? null : Temporal.PlainTime.from(atLocalTime),
-        rolling: calendar === undefined || roll === undefined ? null : { calendar, roll },
-    };
-}
-/**
- * The instant a local wall time names: the first occurrence of a repeated hour, as RFC 5545
- * §3.3.5 reads a local time that "occurs more than once", and `null` for a skipped one, which
- * is never shifted.
- */
-function resolveWallTime(wall, timeZone) {
-    const local = wall.toString();
-    const kind = classifyLocal(local, timeZone);
-    if (kind === null || kind === "nonexistent") {
-        return null;
-    }
-    const instant = resolveLocal(local, timeZone, { disambiguation: "earlier" });
-    return instant === ""
-        ? null
-        : Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone);
-}
-/** The calendar part of a duration — years, months, weeks and days. */
-function datePart(offset) {
-    return Temporal.Duration.from({
-        years: offset.years,
-        months: offset.months,
-        weeks: offset.weeks,
-        days: offset.days,
-    });
-}
-/** The exact part of a duration — hours and smaller. */
-function timePart(offset) {
-    return Temporal.Duration.from({
-        hours: offset.hours,
-        minutes: offset.minutes,
-        seconds: offset.seconds,
-        milliseconds: offset.milliseconds,
-        microseconds: offset.microseconds,
-        nanoseconds: offset.nanoseconds,
-    });
-}
-/**
- * The offset taken off the anchor with no pinning: the calendar part moves the local wall
- * clock, then the exact part comes off in exact time — Temporal's `ZonedDateTime#subtract`,
- * except that a wall clock landing in a skipped hour is `null` rather than moved forward.
- */
-function subtractOffset(anchor, offset) {
-    const calendarPart = datePart(offset);
-    if (calendarPart.blank) {
-        return anchor.subtract(timePart(offset));
-    }
-    const wall = resolveWallTime(anchor.toPlainDateTime().subtract(calendarPart), anchor.timeZoneId);
-    return wall === null ? null : wall.subtract(timePart(offset));
-}
-/**
- * The local date the cut-off falls on after rolling, or `null` when the roll fails. With no
- * calendar the date is left as it is.
- */
-function rolledDate(date, options) {
-    if (options.rolling === null) {
-        return date;
-    }
-    const { calendar, roll } = options.rolling;
-    const rolled = rollDate(date.toString(), roll, calendar);
-    return rolled === "" ? null : Temporal.PlainDate.from(rolled);
-}
 /**
  * Find a deadline stated as an offset before an anchor event, in the local time of the place
  * that enforces it.
@@ -144,6 +48,8 @@ function rolledDate(date, options) {
  *   **nonexistent** one (a skipped hour, a deleted day) returns `""` rather than being
  *   shifted. An exact result that is not re-resolved stays as it is.
  * - Returns the cut-off as a zoned string in `timeZone`, or `""` on invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadline counts back from
  * @param offset ISO 8601 duration before the anchor
@@ -153,49 +59,36 @@ function rolledDate(date, options) {
  * @example cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00" }) // "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"
  * @example cutoffAt("2024-06-14T16:00:00Z", "PT48H", { timeZone: "Europe/Amsterdam" }) // "2024-06-12T18:00:00+02:00[Europe/Amsterdam]" (48 hours keeps the departure's 18:00)
  * @example cutoffAt("2024-06-14T16:00:00Z", "P1D", { timeZone: "Europe/Amsterdam", atLocalTime: "10:00" }) // "2024-06-13T10:00:00+02:00[Europe/Amsterdam]"
- * @example cutoffAt("2024-11-05T17:00:00Z", "PT96H", { timeZone: "America/New_York" }) // "2024-11-01T13:00:00-04:00[America/New_York]" (96 elapsed hours across the fall-back)
- * @example cutoffAt("2024-03-11T22:00:00Z", "P2D", { timeZone: "America/New_York", atLocalTime: "17:00" }) // "2024-03-09T17:00:00-05:00[America/New_York]" (17:00 local, across the spring-forward)
+ * @example cutoffAt("2024-04-09T07:00:00Z", "PT96H", { timeZone: "Australia/Sydney" }) // "2024-04-05T18:00:00+11:00[Australia/Sydney]" (96 elapsed hours across the fall-back)
+ * @example cutoffAt("2024-04-01T16:00:00Z", "P2D", { timeZone: "Europe/London", atLocalTime: "17:00" }) // "2024-03-30T17:00:00+00:00[Europe/London]" (17:00 local, across the spring-forward)
  * @example cutoffAt("2024-06-18T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" }, roll: "preceding" }) // "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" (Sunday rolls back to Friday)
  * @example cutoffAt("2024-06-18T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" } }) // "" (a calendar needs a roll convention)
- * @example cutoffAt("2024-11-04T23:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "01:30" }) // "2024-11-03T01:30:00-04:00[America/New_York]" (a repeated hour takes the earlier pass)
- * @example cutoffAt("2024-03-11T22:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "02:30" }) // "" (02:30 on 10 March never happened)
+ * @example cutoffAt("2024-10-28T18:00:00Z", "P1D", { timeZone: "Europe/London", atLocalTime: "01:30" }) // "2024-10-27T01:30:00+01:00[Europe/London]" (a repeated hour takes the earlier pass)
+ * @example cutoffAt("2024-10-07T07:00:00Z", "P1D", { timeZone: "Australia/Sydney", atLocalTime: "02:30" }) // "" (02:30 on 6 October never happened)
  * @example cutoffAt("2024-06-14T18:00:00", "P2D", { timeZone: "Europe/Amsterdam" }) // "" (a zoneless anchor is not a moment)
  * @example cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", roll: "preceding" }) // "" (a roll needs a calendar)
  */
 export function cutoffAt(anchor, offset, options) {
     try {
-        const resolved = resolveOptions(options);
-        if (resolved === null ||
-            !isValidInstant(anchor) ||
-            !isValidDuration(offset)) {
+        if (!isObject(options)) {
+            return "";
+        }
+        // Every read of `options` happens here, once.
+        const { timeZone, atLocalTime, calendar, roll } = options;
+        // The time of day is checked before the calendar is read, so an invalid one never reads it.
+        const local = resolveCutoffTime(atLocalTime);
+        const shared = local === null
+            ? null
+            : resolveSharedCutoffOptions(timeZone, calendar, roll);
+        if (shared === null ||
+            local === null ||
+            parseInstantNanoseconds(anchor) === null ||
+            !isDurationString(offset)) {
             return "";
         }
         try {
-            const start = instantFrom(anchor).toZonedDateTimeISO(resolved.timeZone);
-            const duration = Temporal.Duration.from(offset);
-            if (resolved.atLocalTime !== null) {
-                const day = rolledDate(start
-                    .subtract(timePart(duration))
-                    .toPlainDate()
-                    .subtract(datePart(duration)), resolved);
-                const pinned = day === null
-                    ? null
-                    : resolveWallTime(day.toPlainDateTime(resolved.atLocalTime), resolved.timeZone);
-                return pinned === null ? "" : pinned.toString();
-            }
-            const cutoff = subtractOffset(start, duration);
-            if (cutoff === null) {
-                return "";
-            }
-            const day = rolledDate(cutoff.toPlainDate(), resolved);
-            if (day === null) {
-                return "";
-            }
-            if (day.equals(cutoff.toPlainDate())) {
-                return cutoff.toString();
-            }
-            const rolled = resolveWallTime(day.toPlainDateTime(cutoff.toPlainTime()), resolved.timeZone);
-            return rolled === null ? "" : rolled.toString();
+            const found = cutoffAtResolved(instantFrom(anchor), Temporal.Duration.from(offset), local.time, shared);
+            return found === null ? "" : found.text;
         }
         catch {
             return "";

package/dist/transport/calculate/cutoffSchedule.d.ts

@@ -1,4 +1,4 @@
-import { type CutoffOptions } from "./cutoffAt.js";
+import type { CutoffOptions } from "./cutoffAt.js";
 /** One named deadline in a cut-off stack: how long before the anchor, and at what local time. */
 export interface Cutoff {
     /** The caller's label, echoed back (`"document"`, `"VGM"`); GMT does not interpret it. */
@@ -22,7 +22,10 @@ export interface CutoffTime {
 }
 /** Options for `cutoffSchedule`: `cutoffAt`'s, with `atLocalTime` read from each entry instead. */
 export interface CutoffScheduleOptions {
-    /** The time zone every cut-off is read in: an IANA name or a UTC offset. */
+    /**
+     * The time zone every cut-off is read in: an IANA name or a UTC offset to the minute (what
+     * `isValidTimeZone` accepts).
+     */
     timeZone: string;
     /**
      * The working week and holidays every cut-off's local date is rolled against. Requires `roll`.
@@ -55,6 +58,8 @@ export interface CutoffScheduleOptions {
  * - Every entry must succeed: one invalid entry, or one cut-off in a skipped local hour,
  *   returns `[]` rather than a stack with a deadline silently missing. An empty `cutoffs` array
  *   returns `[]`.
+ * - An offset with seconds (`-00:44:30`) returns `[]`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadlines count back from
  * @param cutoffs the named deadlines, each with an offset and an optional local time of day
@@ -65,6 +70,6 @@ export interface CutoffScheduleOptions {
  * @example cutoffSchedule("2024-06-18T16:00:00Z", [{ name: "document", offset: "P2D", atLocalTime: "17:00" }, { name: "VGM", offset: "P1D", atLocalTime: "10:00" }], { timeZone: "Europe/Amsterdam", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" }, roll: "preceding" }) // [{ name: "document", at: "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" }, { name: "VGM", at: "2024-06-17T10:00:00+02:00[Europe/Amsterdam]" }] (Sunday's document cut-off rolls back to Friday)
  * @example cutoffSchedule("2024-06-14T16:00:00Z", [], { timeZone: "Europe/Amsterdam" }) // []
  * @example cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "document", offset: "2 days" }], { timeZone: "Europe/Amsterdam" }) // []
- * @example cutoffSchedule("2024-03-11T22:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "VGM", offset: "P1D", atLocalTime: "02:30" }], { timeZone: "America/New_York" }) // [] (02:30 on 10 March never happened)
+ * @example cutoffSchedule("2024-10-07T07:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "VGM", offset: "P1D", atLocalTime: "02:30" }], { timeZone: "Australia/Sydney" }) // [] (02:30 on 6 October never happened)
  */
 export declare function cutoffSchedule(anchor: string, cutoffs: Cutoff[], options: CutoffScheduleOptions): CutoffTime[];