@northguild/gmt 1.17.0 → 1.18.0

package/dist/intermodal/calculate/billingTimeline.d.ts

@@ -5,33 +5,53 @@ export interface BillingDates {
      * last incurred or, for a re-bill, the issuance date of the invoice received.
      */
     anchorOn: string;
-    /** The date the invoice was issued, once it has been. */
+    /**
+     * The date the invoice was issued, once it has been, as an ISO date.
+     *
+     * @defaultValue None. `issuedByDeadline` and `disputeDeadline` are `null`.
+     */
     invoiceIssuedOn?: string;
-    /** The date the dispute request was received, once it has been. */
+    /**
+     * The date the dispute request was received, once it has been, as an ISO date. It needs
+     * `invoiceIssuedOn` and may not precede it.
+     *
+     * @defaultValue None. `requestedByDeadline` and `resolutionDeadline` are `null`.
+     */
     requestReceivedOn?: string;
 }
 /** The three windows the caller supplies, in calendar days, none defaulted, and an optional agreed resolution date. */
 export interface BillingWindows {
-    /** Days from `anchorOn` within which the invoice must be issued. */
+    /** The days from `anchorOn` within which the invoice must be issued. */
     issueDays: number;
-    /** Days from `invoiceIssuedOn` within which a dispute may be raised. */
+    /** The days from `invoiceIssuedOn` within which a dispute may be raised. */
     disputeDays: number;
-    /** Days from `requestReceivedOn` within which the dispute must be resolved. */
+    /** The days from `requestReceivedOn` within which the dispute must be resolved. */
     resolutionDays: number;
-    /** A resolution date the parties agreed instead; it replaces the computed one. */
+    /**
+     * A resolution date the parties agreed instead, as an ISO date on or after `requestReceivedOn`;
+     * it replaces the computed one.
+     *
+     * @defaultValue None. `resolutionDeadline` is `requestReceivedOn + resolutionDays`.
+     */
     agreedResolutionOn?: string;
 }
 /** What `billingTimeline` returns: each deadline as an ISO date, and each comparison once its date exists. */
 export interface BillingDeadlines {
-    /** `anchorOn + issueDays`. */
+    /** The last date the invoice may be issued: `anchorOn + issueDays`. */
     invoiceDeadline: string;
     /** Whether `invoiceIssuedOn` is on or before `invoiceDeadline`; `null` until an invoice date exists. */
     issuedByDeadline: boolean | null;
-    /** `invoiceIssuedOn + disputeDays`; `null` until an invoice date exists. */
+    /**
+     * The last date a dispute may be raised: `invoiceIssuedOn + disputeDays`; `null` until an invoice
+     * date exists.
+     */
     disputeDeadline: string | null;
     /** Whether `requestReceivedOn` is on or before `disputeDeadline`; `null` until a request date exists. */
     requestedByDeadline: boolean | null;
-    /** `requestReceivedOn + resolutionDays`, or `agreedResolutionOn`; `null` until a request date exists. */
+    /**
+     * The last date the dispute must be resolved: `requestReceivedOn + resolutionDays`, or
+     * `agreedResolutionOn`; `null` until a request date exists.
+     */
     resolutionDeadline: string | null;
 }
 /**
@@ -76,8 +96,8 @@ export interface BillingDeadlines {
  *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
  *   or a deadline would leave Temporal's range.
  *
- * @param dates { anchorOn: string, invoiceIssuedOn?: string, requestReceivedOn?: string } ISO dates
- * @param windows { issueDays: number, disputeDays: number, resolutionDays: number, agreedResolutionOn?: string } calendar-day windows, none defaulted
+ * @param dates The anchor date, and the invoice and request dates once they exist
+ * @param windows The three calendar-day windows, none defaulted, and an agreed resolution date
  * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
  *
  * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)

package/dist/intermodal/calculate/billingTimeline.js

@@ -43,8 +43,8 @@ import { isValidDate } from "../../plain/validate/isValidDate.js";
  *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
  *   or a deadline would leave Temporal's range.
  *
- * @param dates { anchorOn: string, invoiceIssuedOn?: string, requestReceivedOn?: string } ISO dates
- * @param windows { issueDays: number, disputeDays: number, resolutionDays: number, agreedResolutionOn?: string } calendar-day windows, none defaulted
+ * @param dates The anchor date, and the invoice and request dates once they exist
+ * @param windows The three calendar-day windows, none defaulted, and an agreed resolution date
  * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
  *
  * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)

package/dist/intermodal/calculate/chargeableDays.d.ts

@@ -1,18 +1,18 @@
 import type { FreeTimeBasis, FreeTimeOptions } from "../../types/index.js";
 /** A band of chargeable-day ordinals and how many of the charged days fell in it. */
 export interface TierBand {
-    /** First chargeable-day ordinal of the band, from 1. */
+    /** The first chargeable-day ordinal of the band, from 1. */
     from: number;
-    /** Last ordinal of the band, or `null` for the open final band. */
+    /** The last ordinal of the band, or `null` for the open final band. */
     to: number | null;
-    /** Charged days that fell in the band. */
+    /** The number of charged days that fell in the band. */
     days: number;
 }
 /** What `chargeableDays` returns: the day count an invoice bills, and the dates that back it. */
 export interface FreeTimeCharges {
-    /** Free days the dwell touched, at most the tariff's `freeDays`. */
+    /** The number of free days the dwell touched, at most the tariff's `freeDays`. */
     freeDaysUsed: number;
-    /** Counted days on or after `expiresAt` the dwell touched. */
+    /** The number of counted days on or after `expiresAt` the dwell touched. */
     chargeableDays: number;
     /** The instant free time ended, as a UTC instant, as `freeTimeExpiry` reports it. */
     expiresAt: string;
@@ -31,6 +31,13 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
      * working days of `calendar`. No default; see `chargeableDays`.
      */
     chargeBasis: FreeTimeBasis;
+    /**
+     * The last chargeable-day ordinal of each band, as strictly ascending positive whole numbers:
+     * `[5, 10]` is days 1–5, 6–10 and 11 onward. They are day bands, not rates. Every band is
+     * returned, an empty one with `days: 0`, and the last is always open.
+     *
+     * @defaultValue None. `byTier` is the single open band `{ from: 1, to: null }`.
+     */
     tiers?: number[];
 };
 /**
@@ -66,11 +73,6 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
  * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
  *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
  *   before it are neither free nor charged.
- * - **`tiers` are day bands, not rates.** `[5, 10]` names the last chargeable-day ordinal of
- *   each band: days 1–5, 6–10 and 11 onward. Every band is returned, an empty one with
- *   `days: 0`, and the last is always open. Omitted, `byTier` is the single open band
- *   `{ from: 1, to: null }`. A list that is not strictly ascending positive whole numbers
- *   returns `null`.
  * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
  *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
  *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
@@ -79,7 +81,7 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
  * @param clockStart ISO 8601 instant string of the event that starts the clock
  * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
  * @param freeDays whole number of free days the tariff allows, 0 or more
- * @param options { basis, chargeBasis, timeZone, firstDay, calendar?, tiers?: number[] }
+ * @param options The tariff's counting terms for free time and for charged days, and the tier bands
  * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
  *
  * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)

package/dist/intermodal/calculate/chargeableDays.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
+import { bandsByTier, instantFrom, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 /**
  * Count the days a container is charged for between the start of its clock and its exit,
@@ -34,11 +34,6 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
  *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
  *   before it are neither free nor charged.
- * - **`tiers` are day bands, not rates.** `[5, 10]` names the last chargeable-day ordinal of
- *   each band: days 1–5, 6–10 and 11 onward. Every band is returned, an empty one with
- *   `days: 0`, and the last is always open. Omitted, `byTier` is the single open band
- *   `{ from: 1, to: null }`. A list that is not strictly ascending positive whole numbers
- *   returns `null`.
  * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
  *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
  *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
@@ -47,7 +42,7 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * @param clockStart ISO 8601 instant string of the event that starts the clock
  * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
  * @param freeDays whole number of free days the tariff allows, 0 or more
- * @param options { basis, chargeBasis, timeZone, firstDay, calendar?, tiers?: number[] }
+ * @param options The tariff's counting terms for free time and for charged days, and the tier bands
  * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
  *
  * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
@@ -76,8 +71,8 @@ export function chargeableDays(clockStart, clockEnd, freeDays, options) {
             tiers === null) {
             return null;
         }
-        const start = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
-        const end = Temporal.Instant.from(clockEnd).toZonedDateTimeISO(terms.timeZone);
+        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const end = instantFrom(clockEnd).toZonedDateTimeISO(terms.timeZone);
         if (Temporal.ZonedDateTime.compare(start, end) > 0) {
             return null;
         }

package/dist/intermodal/calculate/demurrageClock.d.ts

@@ -15,8 +15,9 @@ import type { Interval } from "../../types/index.js";
 export type ClockEventType = "discharged" | "available" | "gatedOut" | "emptyReturned" | "emptyReleased" | "gatedIn" | "loaded";
 /** A container event: what happened and the instant it happened. */
 export interface ClockEvent {
+    /** What happened to the container, as one of the events a charging clock can start or end at. */
     type: ClockEventType;
-    /** ISO 8601 instant string: `Z`, an offset, or a bracketed zone. */
+    /** The instant it happened, as an ISO 8601 string: `Z`, an offset, or a bracketed zone. */
     at: string;
 }
 /** Which charge is being clocked. `combined` is the merged demurrage-and-detention clock. */
@@ -27,9 +28,18 @@ export type ClockDirection = "import" | "export";
 export type ClockStartEvent = "discharged" | "available";
 /** The options `demurrageClock` reads. */
 export interface ClockOptions {
-    /** `"import"` or `"export"`; required, because the same scope runs between different events in each. */
+    /**
+     * The leg of the container's cycle, `"import"` or `"export"`; required, because the same scope
+     * runs between different events in each.
+     */
     direction: ClockDirection;
-    /** Import only: `"discharged"` (the default) or `"available"`. Not read for export or detention. */
+    /**
+     * Where an import demurrage, storage or combined clock starts: `"discharged"`, the classic
+     * definition, or `"available"` for tariffs that start at the availability date. Not read for
+     * export or detention.
+     *
+     * @defaultValue `"discharged"`
+     */
     startEvent?: ClockStartEvent;
 }
 /**
@@ -53,9 +63,8 @@ export interface ClockOptions {
  *
  * - **`direction` has no default.** The same scope name selects different events on the import and
  *   export legs, and guessing it from the events present would be a silent guess.
- * - **`startEvent` is import only**: `"discharged"` by default, the classic definition, or
- *   `"available"` for tariffs that start at the availability date. It is not read for detention
- *   or export, so one options object can serve every scope on a leg. A tariff that starts at
+ * - **`startEvent` is import only.** It is not read for detention or export, so one options
+ *   object can serve every scope on a leg. A tariff that starts at
  *   customs release (Hapag-Lloyd Japan) or ends export demurrage at the cut-off or the scheduled
  *   sailing passes that instant as the event's `at`; GMT does not invent an event for one tariff.
  * - Events may be in any order, and every one must be `{ type, at }` with a known type and a
@@ -71,7 +80,7 @@ export interface ClockOptions {
  *
  * @param events the container's events, `{ type, at }`, `type` one of discharged, available, gatedOut, emptyReturned, emptyReleased, gatedIn, loaded
  * @param scope "demurrage" | "detention" | "storage" | "combined"
- * @param options { direction: "import" | "export", startEvent?: "discharged" | "available" }
+ * @param options Which leg of the cycle the clock is on, and where an import clock starts
  * @returns { start, end } of the requested clock, or null on invalid input
  *
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "available", at: "2024-06-15T12:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "demurrage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }

package/dist/intermodal/calculate/demurrageClock.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isObject } from "../../internal/index.js";
+import { instantFrom, isObject } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const CLOCK_EVENT_TYPES = [
     "discharged",
     "available",
@@ -48,9 +49,8 @@ const EXPORT_CLOCKS = {
  *
  * - **`direction` has no default.** The same scope name selects different events on the import and
  *   export legs, and guessing it from the events present would be a silent guess.
- * - **`startEvent` is import only**: `"discharged"` by default, the classic definition, or
- *   `"available"` for tariffs that start at the availability date. It is not read for detention
- *   or export, so one options object can serve every scope on a leg. A tariff that starts at
+ * - **`startEvent` is import only.** It is not read for detention or export, so one options
+ *   object can serve every scope on a leg. A tariff that starts at
  *   customs release (Hapag-Lloyd Japan) or ends export demurrage at the cut-off or the scheduled
  *   sailing passes that instant as the event's `at`; GMT does not invent an event for one tariff.
  * - Events may be in any order, and every one must be `{ type, at }` with a known type and a
@@ -66,7 +66,7 @@ const EXPORT_CLOCKS = {
  *
  * @param events the container's events, `{ type, at }`, `type` one of discharged, available, gatedOut, emptyReturned, emptyReleased, gatedIn, loaded
  * @param scope "demurrage" | "detention" | "storage" | "combined"
- * @param options { direction: "import" | "export", startEvent?: "discharged" | "available" }
+ * @param options Which leg of the cycle the clock is on, and where an import clock starts
  * @returns { start, end } of the requested clock, or null on invalid input
  *
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "available", at: "2024-06-15T12:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "demurrage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
@@ -107,7 +107,7 @@ function selectClock(events, scope, options) {
         return null;
     }
     // An explicit `undefined` is an omission (TC39 GetOption); `null` is a value, and not a valid one.
-    const startEvent = options.startEvent === undefined ? "discharged" : options.startEvent;
+    const startEvent = optionOrDefault(options.startEvent, "discharged");
     if (!CLOCK_START_EVENTS.includes(startEvent)) {
         return null;
     }
@@ -134,7 +134,7 @@ function selectClock(events, scope, options) {
     if (start === null || end === null) {
         return null;
     }
-    return Temporal.Instant.compare(Temporal.Instant.from(start), Temporal.Instant.from(end)) > 0
+    return Temporal.Instant.compare(instantFrom(start), instantFrom(end)) > 0
         ? null
         : { start, end };
 }

package/dist/intermodal/calculate/freeTimeExpiry.d.ts

@@ -1,7 +1,7 @@
 import type { FreeTimeOptions } from "../../types/index.js";
 /** What `freeTimeExpiry` returns: the free-time window as local dates, and the instant it ends. */
 export interface FreeTime {
-    /** Free day one, as a local date in the counting zone. */
+    /** The first free day, as a local date in the counting zone. */
     freeTimeStart: string;
     /** The last free day, as a local date in the counting zone. */
     lastFreeDay: string;
@@ -19,8 +19,9 @@ export interface FreeTime {
  * the free time allowed and the dates it starts and ends.
  *
  * - **Days are the terminal's local days.** `clockStart` is an instant (`Z`, an offset, or a
- *   bracketed zone, of which only the instant is read); its local date in `options.timeZone` is
- *   the event day. A container discharged at 23:00 has used a free day by 00:01 under
+ *   bracketed zone, of which only the instant is read, a minute-rounded offset as the zone's
+ *   real one, as `isValidInstant` describes); its local date in `options.timeZone` is the
+ *   event day. A container discharged at 23:00 has used a free day by 00:01 under
  *   `firstDay: "eventDay"`. Day boundaries are the zone's real ones, as `floorToZone` and
  *   `dwellTime` find them: a 23- or 25-hour day is one day, a date the zone deleted is never a
  *   free day, and a fall-back that re-enters an earlier date never moves the count backwards.
@@ -48,7 +49,7 @@ export interface FreeTime {
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
  * @param freeDays whole number of free days the tariff allows, at least 1
- * @param options { basis: "calendar" | "working", timeZone: string, firstDay: "eventDay" | "nextDay", calendar?: BusinessCalendar }
+ * @param options The tariff's counting terms: which days count, in which zone, and where day one starts
  * @returns the free-time start and last free day as local dates, and the expiry instant, or null on invalid input
  *
  * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)

package/dist/intermodal/calculate/freeTimeExpiry.js

@@ -1,5 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { parseFreeDays, parseFreeTimeTerms, walkFreeTime, } from "../../internal/index.js";
+import { instantFrom, parseFreeDays, parseFreeTimeTerms, walkFreeTime, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 /**
  * Lay out a container's free time from the instant its clock started, and say when it ends.
@@ -12,8 +11,9 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * the free time allowed and the dates it starts and ends.
  *
  * - **Days are the terminal's local days.** `clockStart` is an instant (`Z`, an offset, or a
- *   bracketed zone, of which only the instant is read); its local date in `options.timeZone` is
- *   the event day. A container discharged at 23:00 has used a free day by 00:01 under
+ *   bracketed zone, of which only the instant is read, a minute-rounded offset as the zone's
+ *   real one, as `isValidInstant` describes); its local date in `options.timeZone` is the
+ *   event day. A container discharged at 23:00 has used a free day by 00:01 under
  *   `firstDay: "eventDay"`. Day boundaries are the zone's real ones, as `floorToZone` and
  *   `dwellTime` find them: a 23- or 25-hour day is one day, a date the zone deleted is never a
  *   free day, and a fall-back that re-enters an earlier date never moves the count backwards.
@@ -41,7 +41,7 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
  * @param freeDays whole number of free days the tariff allows, at least 1
- * @param options { basis: "calendar" | "working", timeZone: string, firstDay: "eventDay" | "nextDay", calendar?: BusinessCalendar }
+ * @param options The tariff's counting terms: which days count, in which zone, and where day one starts
  * @returns the free-time start and last free day as local dates, and the expiry instant, or null on invalid input
  *
  * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
@@ -63,7 +63,7 @@ export function freeTimeExpiry(clockStart, freeDays, options) {
         if (!isValidInstant(clockStart) || terms === null || allowed === null) {
             return null;
         }
-        const start = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
         const ledger = walkFreeTime(start, allowed, terms);
         if (ledger === null) {
             return null;

package/dist/internal/businessCalendar.d.ts

@@ -11,6 +11,11 @@ export type ResolvedBusinessCalendar = {
     holidays: Set<string>;
 };
 export declare const DEFAULT_BUSINESS_CALENDAR: ResolvedBusinessCalendar;
+/**
+ * Reduce a holiday list to its normalised ISO dates, or `null` when it is not an array of ISO
+ * PlainDate strings. Shared with `OperatingSchedule.holidays`, which takes the same list.
+ */
+export declare function parseHolidays(holidays: unknown): Set<string> | null;
 /**
  * Reduce a caller-supplied `BusinessCalendar` to its lookups, or `null` when it is not one.
  *

package/dist/internal/businessCalendar.js

@@ -29,7 +29,11 @@ function parseWeekend(weekend) {
     // All seven weekdays closed leaves no business day, so every walk would run to its cap.
     return days.size < ISO_WEEKDAYS ? days : null;
 }
-function parseHolidays(holidays) {
+/**
+ * Reduce a holiday list to its normalised ISO dates, or `null` when it is not an array of ISO
+ * PlainDate strings. Shared with `OperatingSchedule.holidays`, which takes the same list.
+ */
+export function parseHolidays(holidays) {
     if (!Array.isArray(holidays)) {
         return null;
     }

package/dist/internal/cycleFieldValue.d.ts

@@ -8,10 +8,12 @@
  *   not by repeatedly correcting a single overflow.
  * - Round path is **not** "round to nearest": it steps by `Math.sign(amount)` first, then snaps to
  *   the next multiple of `Math.abs(amount)` in the direction of that sign (ceiling for positive
- *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. This matches
- *   `@internationalized/date`'s `CycleOptions.round` behavior exactly (verified against its
- *   `manipulation.ts` source) — e.g. minute `22` cycled by `+15` with `round: true` lands on `30`
- *   (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. GMT's own
+ *   rule, not a standard's: a cycle always moves the way `amount` points, and the nearest
+ *   multiple can lie the other way — e.g. minute `22` cycled by `+15` with `round: true` lands on
+ *   `30` (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ * - Comparison: `@internationalized/date`'s `CycleOptions.round` rounds a bounded field the same
+ *   way.
  *
  * @param current the field's current numeric value
  * @param amount signed amount to cycle by

package/dist/internal/cycleFieldValue.js

@@ -8,10 +8,12 @@
  *   not by repeatedly correcting a single overflow.
  * - Round path is **not** "round to nearest": it steps by `Math.sign(amount)` first, then snaps to
  *   the next multiple of `Math.abs(amount)` in the direction of that sign (ceiling for positive
- *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. This matches
- *   `@internationalized/date`'s `CycleOptions.round` behavior exactly (verified against its
- *   `manipulation.ts` source) — e.g. minute `22` cycled by `+15` with `round: true` lands on `30`
- *   (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. GMT's own
+ *   rule, not a standard's: a cycle always moves the way `amount` points, and the nearest
+ *   multiple can lie the other way — e.g. minute `22` cycled by `+15` with `round: true` lands on
+ *   `30` (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ * - Comparison: `@internationalized/date`'s `CycleOptions.round` rounds a bounded field the same
+ *   way.
  *
  * @param current the field's current numeric value
  * @param amount signed amount to cycle by

package/dist/internal/daylightTime.d.ts

@@ -0,0 +1,33 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Whether an instant is in daylight saving time, read from the zone's offset changes alone.
+ *
+ * The rule: daylight time runs from a forward change of the clocks to the backward change that
+ * undoes it. A backward change undoes the most recent forward change of the same size that is not
+ * yet undone, and only if it comes less than 365 days after it. An instant is in daylight time when
+ * it is at or after such a forward change and before the backward change paired with it.
+ *
+ * A forward change that is never undone, or undone a year or more later, is a change of standard
+ * time (`Europe/Istanbul` 2016, `Europe/Moscow` 2011 to 2014), as is any backward change with no
+ * forward change to undo (`Asia/Almaty` 2024).
+ *
+ * This is GMT's own definition, not the tz database's daylight flag, which no JavaScript API
+ * exposes and offsets do not determine.
+ *
+ * Cost: one transition lookup forward, then one back, and more only outside the ordinary summer
+ * case. A paired change is less than 365 days away, so every lookup is given that limit and reads
+ * no further: with GMT's own search (temporalCompat D13) at most 74 offset samples and 51 reads to
+ * pin a change, for any zone and any instant.
+ *
+ * @param zoned the instant, in the zone to read
+ * @returns true in daylight time, false in standard time or when the walk exceeds its bound
+ */
+export declare function isInDaylightTime(zoned: Temporal.ZonedDateTime): boolean;
+/**
+ * Whether a zone observes daylight saving time as of an instant: the instant is in daylight time,
+ * or a daylight period begins within the 365 days after it. Same rule as `isInDaylightTime`.
+ *
+ * @param zoned the instant to judge from, in the zone to read
+ * @returns true when the zone observes daylight time then, false otherwise or past the walk bound
+ */
+export declare function observesDaylightTime(zoned: Temporal.ZonedDateTime): boolean;

package/dist/internal/daylightTime.js

@@ -0,0 +1,164 @@
+import { zonedNextTransition, zonedPreviousTransition, } from "./zonedWallClockOperations.js";
+/**
+ * The longest a daylight period can last: a forward change and the backward change that undoes it
+ * are less than 365 days apart. Daylight time is seasonal, so it recurs within every year, and
+ * 365 days is the shortest year. A longer advance is a change of standard time.
+ */
+const DAYLIGHT_PERIOD_LIMIT_NANOSECONDS = 365n * 86400000000000n;
+/**
+ * Offset changes read in each direction before the walk gives up and answers `false`, the
+ * sentinel: a bounded loop that runs out never returns a partial answer. Every walk here is also
+ * limited to 365 days, and a year of `Africa/Casablanca` holds four changes, so no real zone
+ * reaches the bound; `daylightTime.test.ts` reaches it with a made-up zone.
+ */
+const MAX_WALKED_CHANGES = 64;
+function offsetChangeAt(transition) {
+    return {
+        at: transition.epochNanoseconds,
+        step: transition.offsetNanoseconds -
+            transition.subtract({ nanoseconds: 1 }).offsetNanoseconds,
+    };
+}
+/**
+ * Apply one change to the list of advances not yet undone. A forward change joins the list. A
+ * backward change undoes the most recent advance of the same size, if that advance is less than
+ * 365 days old, and returns it; otherwise it undoes nothing.
+ */
+function applyChange(open, change) {
+    if (change.step > 0) {
+        open.push(change);
+        return null;
+    }
+    for (let i = open.length - 1; i >= 0; i--) {
+        if (open[i].step !== -change.step) {
+            continue;
+        }
+        if (change.at - open[i].at >= DAYLIGHT_PERIOD_LIMIT_NANOSECONDS) {
+            return null;
+        }
+        return open.splice(i, 1)[0];
+    }
+    return null;
+}
+/** Whether `to` is less than the daylight period limit after `from`. */
+function isWithinLimit(from, to) {
+    return to - from < DAYLIGHT_PERIOD_LIMIT_NANOSECONDS;
+}
+/**
+ * The advances still open just before `next`: made in the 365 days before it and not yet undone.
+ * An older advance cannot be undone at or after `next`. Null past `MAX_WALKED_CHANGES` changes.
+ *
+ * @param next the first change after the instant being judged
+ * @param latest the change before `next`, already known to be within the limit
+ */
+function openAdvancesBefore(next, latest) {
+    const changes = [offsetChangeAt(latest)];
+    let cursor = latest;
+    for (let i = 0; i <= MAX_WALKED_CHANGES; i++) {
+        const previous = zonedPreviousTransition(cursor, next.epochNanoseconds - DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+        if (previous === null ||
+            !isWithinLimit(previous.epochNanoseconds, next.epochNanoseconds)) {
+            const open = [];
+            for (const change of changes) {
+                applyChange(open, change);
+            }
+            return open;
+        }
+        changes.unshift(offsetChangeAt(previous));
+        cursor = previous;
+    }
+    return null;
+}
+/**
+ * Whether a change from `next` onwards undoes one of the `open` advances made at or before `at`.
+ * It has to come less than 365 days after `at`, since the advance is no later than `at`.
+ */
+function isUndoneFrom(next, open, at) {
+    let cursor = next;
+    for (let i = 0; i <= MAX_WALKED_CHANGES; i++) {
+        if (cursor === null || !isWithinLimit(at, cursor.epochNanoseconds)) {
+            return false;
+        }
+        const undone = applyChange(open, offsetChangeAt(cursor));
+        if (undone !== null && undone.at <= at) {
+            return true;
+        }
+        cursor = zonedNextTransition(cursor, at + DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+    }
+    return false;
+}
+/**
+ * Whether an instant is in daylight saving time, read from the zone's offset changes alone.
+ *
+ * The rule: daylight time runs from a forward change of the clocks to the backward change that
+ * undoes it. A backward change undoes the most recent forward change of the same size that is not
+ * yet undone, and only if it comes less than 365 days after it. An instant is in daylight time when
+ * it is at or after such a forward change and before the backward change paired with it.
+ *
+ * A forward change that is never undone, or undone a year or more later, is a change of standard
+ * time (`Europe/Istanbul` 2016, `Europe/Moscow` 2011 to 2014), as is any backward change with no
+ * forward change to undo (`Asia/Almaty` 2024).
+ *
+ * This is GMT's own definition, not the tz database's daylight flag, which no JavaScript API
+ * exposes and offsets do not determine.
+ *
+ * Cost: one transition lookup forward, then one back, and more only outside the ordinary summer
+ * case. A paired change is less than 365 days away, so every lookup is given that limit and reads
+ * no further: with GMT's own search (temporalCompat D13) at most 74 offset samples and 51 reads to
+ * pin a change, for any zone and any instant.
+ *
+ * @param zoned the instant, in the zone to read
+ * @returns true in daylight time, false in standard time or when the walk exceeds its bound
+ */
+export function isInDaylightTime(zoned) {
+    const at = zoned.epochNanoseconds;
+    // Daylight time ends with a clock change. No change ahead, or none within the limit: standard.
+    const next = zonedNextTransition(zoned, at + DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+    if (next === null || !isWithinLimit(at, next.epochNanoseconds)) {
+        return false;
+    }
+    // It begins with one too, and no change in the 365 days before `next` leaves nothing to undo.
+    const latest = zonedPreviousTransition(next, next.epochNanoseconds - DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+    if (latest === null ||
+        !isWithinLimit(latest.epochNanoseconds, next.epochNanoseconds)) {
+        return false;
+    }
+    // The ordinary summer: the clocks last went forward, and next go back by as much. The latest
+    // advance is the most recent one open, so `next` undoes it whatever came before.
+    const latestStep = offsetChangeAt(latest).step;
+    const nextStep = next.offsetNanoseconds - zoned.offsetNanoseconds;
+    if (latestStep > 0 && nextStep === -latestStep) {
+        return true;
+    }
+    const open = openAdvancesBefore(next, latest);
+    if (open === null || open.length === 0) {
+        return false;
+    }
+    return isUndoneFrom(next, open, at);
+}
+/**
+ * Whether a zone observes daylight saving time as of an instant: the instant is in daylight time,
+ * or a daylight period begins within the 365 days after it. Same rule as `isInDaylightTime`.
+ *
+ * @param zoned the instant to judge from, in the zone to read
+ * @returns true when the zone observes daylight time then, false otherwise or past the walk bound
+ */
+export function observesDaylightTime(zoned) {
+    if (isInDaylightTime(zoned)) {
+        return true;
+    }
+    let cursor = zoned;
+    for (let i = 0; i <= MAX_WALKED_CHANGES; i++) {
+        const next = zonedNextTransition(cursor, zoned.epochNanoseconds + DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+        if (next === null ||
+            next.epochNanoseconds - zoned.epochNanoseconds >=
+                DAYLIGHT_PERIOD_LIMIT_NANOSECONDS) {
+            return false;
+        }
+        if (isInDaylightTime(next)) {
+            return true;
+        }
+        cursor = next;
+    }
+    return false;
+}