@northguild/gmt 1.15.0 → 1.17.0

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

@@ -0,0 +1,66 @@
+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. */
+    freeTimeStart: string;
+    /** The last free day, as a local date in the counting zone. */
+    lastFreeDay: string;
+    /** The instant free time ends: the start of the local day after `lastFreeDay`, as a UTC instant. */
+    expiresAt: string;
+}
+/**
+ * Lay out a container's free time from the instant its clock started, and say when it ends.
+ *
+ * Free time is the money calculation in container logistics, and none of its terms is a fact
+ * about the port: the number of free days, whether the day of discharge is free day one, and
+ * whether weekends count are all set by the carrier's tariff or the service contract. So every
+ * term is a parameter. No regulation or industry standard fixes how free time is counted (DCSA types only its unit: calendar days, working days, hours or day of discharge; GMT counts
+ * days); the result is the window every tariff states, and what an invoice can print about it:
+ * 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
+ *   `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.
+ * - **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"`
+ *   starts free time on the following counted day. The two differ by exactly one day of charges,
+ *   and a silent default here is a wrong invoice, so omitting it returns `null`.
+ * - **`basis` decides which days count.** `"calendar"` counts every local day, so a weekend
+ *   burns two free days while the terminal is shut. `"working"` counts only the working days of
+ *   `options.calendar` (its weekend and holidays; `calendar.timeZone` is not read), and is
+ *   required to have one: a working-day count without a calendar is a guess and returns `null`.
+ *   Under `"working"` a Saturday discharge starts free time on Monday under either `firstDay`.
+ *   A tariff counting "calendar days excluding bank holidays" (Hapag-Lloyd Japan, MSC Vietnam) is
+ *   `"working"` with an empty `weekend`. How days after expiry are charged is a separate term;
+ *   see `chargeableDays`'s `chargeBasis`.
+ * - **`expiresAt` is half-open.** It is the first instant of the local day after `lastFreeDay`,
+ *   as a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; see
+ *   `chargeableDays`. Under `"working"` it can fall on a weekend, which is then simply not
+ *   chargeable.
+ * - `freeDays` is a whole number of at least `1`: with no free days there is no last free day
+ *   to name, and `chargeableDays` accepts `0` for that tariff.
+ * - Returns `null` when `clockStart` is not an instant, `freeDays` is not a whole number of at
+ *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
+ *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
+ *   would pass 10,000 local days.
+ *
+ * @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 }
+ * @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)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
+ * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
+ * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
+ * @example freeTimeExpiry("2024-09-07T15:00:00Z", 1, { basis: "calendar", timeZone: "America/Santiago", firstDay: "eventDay" }) // { freeTimeStart: "2024-09-07", lastFreeDay: "2024-09-07", expiresAt: "2024-09-08T04:00:00Z" } (Santiago skipped midnight on the 8th, so the day starts at 01:00)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ */
+export declare function freeTimeExpiry(clockStart: string, freeDays: number, options: FreeTimeOptions): FreeTime | null;

package/dist/intermodal/calculate/freeTimeExpiry.js

@@ -0,0 +1,82 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { 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.
+ *
+ * Free time is the money calculation in container logistics, and none of its terms is a fact
+ * about the port: the number of free days, whether the day of discharge is free day one, and
+ * whether weekends count are all set by the carrier's tariff or the service contract. So every
+ * term is a parameter. No regulation or industry standard fixes how free time is counted (DCSA types only its unit: calendar days, working days, hours or day of discharge; GMT counts
+ * days); the result is the window every tariff states, and what an invoice can print about it:
+ * 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
+ *   `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.
+ * - **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"`
+ *   starts free time on the following counted day. The two differ by exactly one day of charges,
+ *   and a silent default here is a wrong invoice, so omitting it returns `null`.
+ * - **`basis` decides which days count.** `"calendar"` counts every local day, so a weekend
+ *   burns two free days while the terminal is shut. `"working"` counts only the working days of
+ *   `options.calendar` (its weekend and holidays; `calendar.timeZone` is not read), and is
+ *   required to have one: a working-day count without a calendar is a guess and returns `null`.
+ *   Under `"working"` a Saturday discharge starts free time on Monday under either `firstDay`.
+ *   A tariff counting "calendar days excluding bank holidays" (Hapag-Lloyd Japan, MSC Vietnam) is
+ *   `"working"` with an empty `weekend`. How days after expiry are charged is a separate term;
+ *   see `chargeableDays`'s `chargeBasis`.
+ * - **`expiresAt` is half-open.** It is the first instant of the local day after `lastFreeDay`,
+ *   as a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; see
+ *   `chargeableDays`. Under `"working"` it can fall on a weekend, which is then simply not
+ *   chargeable.
+ * - `freeDays` is a whole number of at least `1`: with no free days there is no last free day
+ *   to name, and `chargeableDays` accepts `0` for that tariff.
+ * - Returns `null` when `clockStart` is not an instant, `freeDays` is not a whole number of at
+ *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
+ *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
+ *   would pass 10,000 local days.
+ *
+ * @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 }
+ * @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)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
+ * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
+ * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
+ * @example freeTimeExpiry("2024-09-07T15:00:00Z", 1, { basis: "calendar", timeZone: "America/Santiago", firstDay: "eventDay" }) // { freeTimeStart: "2024-09-07", lastFreeDay: "2024-09-07", expiresAt: "2024-09-08T04:00:00Z" } (Santiago skipped midnight on the 8th, so the day starts at 01:00)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ */
+export function freeTimeExpiry(clockStart, freeDays, options) {
+    try {
+        const terms = parseFreeTimeTerms(options);
+        const allowed = parseFreeDays(freeDays, 1);
+        if (!isValidInstant(clockStart) || terms === null || allowed === null) {
+            return null;
+        }
+        const start = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const ledger = walkFreeTime(start, allowed, terms);
+        if (ledger === null) {
+            return null;
+        }
+        return {
+            freeTimeStart: ledger.free[0].date,
+            lastFreeDay: ledger.free[allowed - 1].date,
+            expiresAt: ledger.expiresAt.toInstant().toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from "./billingTimeline.js";
+export * from "./chargeableDays.js";
+export * from "./demurrageClock.js";
+export * from "./freeTimeExpiry.js";

package/dist/intermodal/calculate/index.js

@@ -0,0 +1,4 @@
+export * from "./billingTimeline.js";
+export * from "./chargeableDays.js";
+export * from "./demurrageClock.js";
+export * from "./freeTimeExpiry.js";

package/dist/intermodal/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";

package/dist/intermodal/index.js

@@ -0,0 +1,3 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";

package/dist/internal/adjustZonedBusinessDays.js

@@ -1,13 +1,15 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { advanceBusinessDays } from "./advanceBusinessDays.js";
+import { DEFAULT_BUSINESS_CALENDAR, stepBusinessDates, } from "./businessCalendar.js";
+import { plainToZoned, zonedWithPlainTime } from "./zonedWallClockOperations.js";
+import { zonedDateTimeFrom } from "./zonedWallClock.js";
 export function adjustZonedBusinessDays(value, direction, absAmount) {
     try {
-        const zoned = Temporal.ZonedDateTime.from(value);
+        const zoned = zonedDateTimeFrom(value);
         const plainDate = zoned.toPlainDate();
-        const resultDate = advanceBusinessDays(plainDate, direction, absAmount);
-        const resultZoned = resultDate
-            .toZonedDateTime(zoned.timeZoneId)
-            .withPlainTime(zoned.toPlainTime());
+        const resultDate = stepBusinessDates(plainDate, direction, absAmount, DEFAULT_BUSINESS_CALENDAR);
+        if (resultDate === null) {
+            return "";
+        }
+        const resultZoned = zonedWithPlainTime(plainToZoned(resultDate, zoned.timeZoneId), zoned.toPlainTime());
         return resultZoned.toString();
     }
     catch {

package/dist/internal/businessCalendar.d.ts

@@ -0,0 +1,46 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { BusinessCalendar } from "../types/index.js";
+/**
+ * Calendar days a single business-day walk may step before giving up — roughly 547 years, far
+ * past any real schedule. A walk that runs out returns the sentinel, never a partial answer.
+ */
+export declare const MAX_BUSINESS_DAY_STEPS = 200000;
+/** A `BusinessCalendar` reduced to the two lookups every walk needs. */
+export type ResolvedBusinessCalendar = {
+    weekend: Set<number>;
+    holidays: Set<string>;
+};
+export declare const DEFAULT_BUSINESS_CALENDAR: ResolvedBusinessCalendar;
+/**
+ * Reduce a caller-supplied `BusinessCalendar` to its lookups, or `null` when it is not one.
+ *
+ * `undefined` is rejected here; `resolveBusinessCalendar` is the entry point that treats an
+ * absent calendar as the default Saturday–Sunday week.
+ */
+export declare function parseBusinessCalendar(calendar: unknown): ResolvedBusinessCalendar | null;
+/**
+ * Resolve an optional calendar: absent means the default Saturday–Sunday week with no
+ * holidays, anything else must be a valid `BusinessCalendar` or this returns `null`.
+ */
+export declare function resolveBusinessCalendar(calendar: BusinessCalendar | undefined): ResolvedBusinessCalendar | null;
+/** True when `date` is neither a weekend day nor a holiday in `calendar`. */
+export declare function isBusinessDate(date: Temporal.PlainDate, calendar: ResolvedBusinessCalendar): boolean;
+/**
+ * The first business day at or beyond `date`, walking in `direction`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. Returns `date` itself when it is
+ * already a business day, and `null` when the walk exceeds `MAX_BUSINESS_DAY_STEPS`. Throws a
+ * `RangeError` when the walk passes a Temporal range limit.
+ */
+export declare function businessDateFrom(date: Temporal.PlainDate, direction: 1 | -1, calendar: ResolvedBusinessCalendar): Temporal.PlainDate | null;
+/**
+ * Step `count` business days from `date` in `direction`, counting only days that are business
+ * days in `calendar`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. `count` is a non-negative whole
+ * number of business days. `date` itself is never counted, so a `count` of 0 returns `date`
+ * unchanged even when it is not a business day. Returns `null`
+ * when the walk exceeds `MAX_BUSINESS_DAY_STEPS`, and throws a `RangeError` when it passes a
+ * Temporal range limit.
+ */
+export declare function stepBusinessDates(date: Temporal.PlainDate, direction: 1 | -1, count: number, calendar: ResolvedBusinessCalendar): Temporal.PlainDate | null;

package/dist/internal/businessCalendar.js

@@ -0,0 +1,230 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../plain/validate/isValidDate.js";
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+const ISO_WEEKDAYS = 7;
+/**
+ * The weekend GMT assumed before calendars existed: Saturday and Sunday, no holidays. It is
+ * what `isBusinessDay`, `addBusinessDays` and `subtractBusinessDays` use when no calendar is
+ * passed, so their shipped behaviour is unchanged.
+ */
+const DEFAULT_WEEKEND = [6, 7];
+/**
+ * Calendar days a single business-day walk may step before giving up — roughly 547 years, far
+ * past any real schedule. A walk that runs out returns the sentinel, never a partial answer.
+ */
+export const MAX_BUSINESS_DAY_STEPS = 200_000;
+export const DEFAULT_BUSINESS_CALENDAR = {
+    weekend: new Set(DEFAULT_WEEKEND),
+    holidays: new Set(),
+};
+function parseWeekend(weekend) {
+    if (!Array.isArray(weekend)) {
+        return null;
+    }
+    const everyDayInRange = weekend.every((day) => Number.isInteger(day) && day >= 1 && day <= ISO_WEEKDAYS);
+    if (!everyDayInRange) {
+        return null;
+    }
+    const days = new Set(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) {
+    if (!Array.isArray(holidays)) {
+        return null;
+    }
+    const dates = new Set();
+    try {
+        for (const holiday of holidays) {
+            if (typeof holiday !== "string" || !isValidDate(holiday)) {
+                return null;
+            }
+            // Normalise through Temporal so a holiday and a walked date compare as the same string.
+            dates.add(Temporal.PlainDate.from(holiday).toString());
+        }
+    }
+    catch {
+        return null;
+    }
+    return dates;
+}
+/**
+ * Reduce a caller-supplied `BusinessCalendar` to its lookups, or `null` when it is not one.
+ *
+ * `undefined` is rejected here; `resolveBusinessCalendar` is the entry point that treats an
+ * absent calendar as the default Saturday–Sunday week.
+ */
+export function parseBusinessCalendar(calendar) {
+    if (typeof calendar !== "object" ||
+        calendar === null ||
+        Array.isArray(calendar)) {
+        return null;
+    }
+    const { weekend, holidays, timeZone } = calendar;
+    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    const weekendDays = parseWeekend(weekend);
+    const holidayDates = parseHolidays(holidays);
+    if (weekendDays === null || holidayDates === null) {
+        return null;
+    }
+    return { weekend: weekendDays, holidays: holidayDates };
+}
+/**
+ * Resolve an optional calendar: absent means the default Saturday–Sunday week with no
+ * holidays, anything else must be a valid `BusinessCalendar` or this returns `null`.
+ */
+export function resolveBusinessCalendar(calendar) {
+    return calendar === undefined
+        ? DEFAULT_BUSINESS_CALENDAR
+        : parseBusinessCalendar(calendar);
+}
+/** True when `date` is neither a weekend day nor a holiday in `calendar`. */
+export function isBusinessDate(date, calendar) {
+    return (!calendar.weekend.has(date.dayOfWeek) &&
+        !calendar.holidays.has(date.toString()));
+}
+/*
+ * The walks step whole days as integers — days since 1970-01-01 — rather than PlainDates: a walk
+ * to the 200,000-day cap through the polyfill's `add`, `dayOfWeek` and `toString` took seconds.
+ * Only the date a walk returns is built as a Temporal object.
+ */
+/**
+ * TC39 `ISODateWithinLimits`: -271821-04-19 and +275760-09-13, counted in days from 1970-01-01,
+ * are the first and last dates a PlainDate holds.
+ */
+const MIN_EPOCH_DAY = -100_000_001;
+const MAX_EPOCH_DAY = 100_000_000;
+/** 1970-01-01 was a Thursday, ISO weekday 4. */
+const EPOCH_WEEKDAY_OFFSET = 3;
+/** Days in a 400-year cycle of the proleptic Gregorian calendar. */
+const DAYS_PER_400_YEARS = 146_097;
+/** Days from 0000-03-01, the start of a March-based year, to 1970-01-01. */
+const DAYS_FROM_MARCH_0000_TO_EPOCH = 719_468;
+/** TC39 `PadISOYear`: years 0–9999 print with four digits, any other with a sign and six. */
+const MAX_FOUR_DIGIT_YEAR = 9999;
+/**
+ * Days from 1970-01-01 to an ISO date, in the proleptic Gregorian calendar of ECMA-262 §21.4.1
+ * that Temporal's ISO calendar extends. Years run from March so the leap day ends each one.
+ */
+function epochDayOf(year, month, day) {
+    const marchYear = month <= 2 ? year - 1 : year;
+    const cycle = Math.floor(marchYear / 400);
+    const yearOfCycle = marchYear - cycle * 400;
+    const dayOfYear = Math.floor((153 * ((month + 9) % 12) + 2) / 5) + day - 1;
+    const dayOfCycle = yearOfCycle * 365 +
+        Math.floor(yearOfCycle / 4) -
+        Math.floor(yearOfCycle / 100) +
+        dayOfYear;
+    return (cycle * DAYS_PER_400_YEARS + dayOfCycle - DAYS_FROM_MARCH_0000_TO_EPOCH);
+}
+/** The ISO year, month and day `epochDay` days from 1970-01-01 — `epochDayOf` inverted. */
+function isoFieldsOf(epochDay) {
+    const shifted = epochDay + DAYS_FROM_MARCH_0000_TO_EPOCH;
+    const cycle = Math.floor(shifted / DAYS_PER_400_YEARS);
+    const dayOfCycle = shifted - cycle * DAYS_PER_400_YEARS;
+    // Remove the leap days of every 4th, 100th and 400th year before dividing into 365-day years.
+    const yearOfCycle = Math.floor((dayOfCycle -
+        Math.floor(dayOfCycle / 1460) +
+        Math.floor(dayOfCycle / 36_524) -
+        Math.floor(dayOfCycle / (DAYS_PER_400_YEARS - 1))) /
+        365);
+    const dayOfYear = dayOfCycle -
+        (365 * yearOfCycle +
+            Math.floor(yearOfCycle / 4) -
+            Math.floor(yearOfCycle / 100));
+    const monthFromMarch = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthFromMarch + 2) / 5) + 1;
+    const month = monthFromMarch < 10 ? monthFromMarch + 3 : monthFromMarch - 9;
+    const year = yearOfCycle + cycle * 400 + (month <= 2 ? 1 : 0);
+    return [year, month, day];
+}
+/** `Temporal.PlainDate#toString` for an ISO date, which is how `holidays` stores its dates. */
+function isoDateString(epochDay) {
+    const [year, month, day] = isoFieldsOf(epochDay);
+    const yearText = year < 0 || year > MAX_FOUR_DIGIT_YEAR
+        ? `${year < 0 ? "-" : "+"}${String(Math.abs(year)).padStart(6, "0")}`
+        : String(year).padStart(4, "0");
+    return `${yearText}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+/**
+ * Days from 1970-01-01 to `date`, an ISO-calendar date. Any other calendar throws a
+ * `RangeError`, which callers turn into their sentinel: its year, month and day are not ISO
+ * fields, so the arithmetic below would silently walk from the wrong day.
+ */
+function epochDayOfDate(date) {
+    if (date.calendarId !== "iso8601") {
+        throw new RangeError("business-day walks take an ISO-calendar date");
+    }
+    return epochDayOf(date.year, date.month, date.day);
+}
+function isBusinessEpochDay(epochDay, calendar) {
+    // `%` keeps the dividend's sign, so a date before 1970 needs the second `+ ISO_WEEKDAYS`.
+    const weekday = ((((epochDay + EPOCH_WEEKDAY_OFFSET) % ISO_WEEKDAYS) + ISO_WEEKDAYS) %
+        ISO_WEEKDAYS) +
+        1;
+    return (!calendar.weekend.has(weekday) &&
+        (calendar.holidays.size === 0 ||
+            !calendar.holidays.has(isoDateString(epochDay))));
+}
+/** One day on from `epochDay`, throwing the `RangeError` `PlainDate#add` throws past a limit. */
+function nextEpochDay(epochDay, direction) {
+    const next = epochDay + direction;
+    if (next < MIN_EPOCH_DAY || next > MAX_EPOCH_DAY) {
+        throw new RangeError("date/time value is outside of supported range");
+    }
+    return next;
+}
+/** The walked-to date; `date` itself when the walk never moved. */
+function dateAt(date, startEpochDay, epochDay) {
+    if (epochDay === startEpochDay) {
+        return date;
+    }
+    const [year, month, day] = isoFieldsOf(epochDay);
+    return new Temporal.PlainDate(year, month, day);
+}
+/**
+ * The first business day at or beyond `date`, walking in `direction`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. Returns `date` itself when it is
+ * already a business day, and `null` when the walk exceeds `MAX_BUSINESS_DAY_STEPS`. Throws a
+ * `RangeError` when the walk passes a Temporal range limit.
+ */
+export function businessDateFrom(date, direction, calendar) {
+    const start = epochDayOfDate(date);
+    let current = start;
+    // `step` counts calendar days moved, exactly as it does in `stepBusinessDates`, so both
+    // walks give up at the same distance — the 200,000 the public JSDoc quotes.
+    for (let step = 0; step < MAX_BUSINESS_DAY_STEPS; step++) {
+        if (isBusinessEpochDay(current, calendar)) {
+            return dateAt(date, start, current);
+        }
+        current = nextEpochDay(current, direction);
+    }
+    return isBusinessEpochDay(current, calendar)
+        ? dateAt(date, start, current)
+        : null;
+}
+/**
+ * Step `count` business days from `date` in `direction`, counting only days that are business
+ * days in `calendar`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. `count` is a non-negative whole
+ * number of business days. `date` itself is never counted, so a `count` of 0 returns `date`
+ * unchanged even when it is not a business day. Returns `null`
+ * when the walk exceeds `MAX_BUSINESS_DAY_STEPS`, and throws a `RangeError` when it passes a
+ * Temporal range limit.
+ */
+export function stepBusinessDates(date, direction, count, calendar) {
+    const start = epochDayOfDate(date);
+    let current = start;
+    let remaining = count;
+    for (let step = 0; step < MAX_BUSINESS_DAY_STEPS && remaining > 0; step++) {
+        current = nextEpochDay(current, direction);
+        if (isBusinessEpochDay(current, calendar)) {
+            remaining -= 1;
+        }
+    }
+    return remaining === 0 ? dateAt(date, start, current) : null;
+}

package/dist/internal/businessDayValues.d.ts

@@ -0,0 +1,20 @@
+import type { BusinessCalendar } from "../types/index.js";
+/**
+ * The shared body of `addBusinessDays` and `subtractBusinessDays`: validate, resolve the
+ * calendar, and walk `amount` working days from `value`.
+ *
+ * - `sign` is the direction a **positive** `amount` moves — `1` for adding, `-1` for
+ *   subtracting — so a negative `amount` walks the other way in both.
+ * - `calendar` is optional; absent means Saturday–Sunday with no holidays.
+ * - Returns `""` on an invalid date, a non-integer or out-of-range `amount`, an invalid
+ *   calendar, and when the walk runs past `MAX_BUSINESS_DAY_STEPS`.
+ */
+export declare function stepBusinessDaysValue(value: string, amount: number, sign: 1 | -1, calendar: BusinessCalendar | undefined): string;
+/**
+ * The shared body of `nextBusinessDay` and `previousBusinessDay`: the first working day
+ * **strictly** one business day away from `value`, in `direction`.
+ *
+ * Unlike `stepBusinessDaysValue`, `calendar` is required — these two assume no weekend, so an
+ * absent calendar is invalid input rather than the Saturday–Sunday default.
+ */
+export declare function neighbourBusinessDayValue(value: string, direction: 1 | -1, calendar: BusinessCalendar): string;

package/dist/internal/businessDayValues.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseBusinessCalendar, resolveBusinessCalendar, stepBusinessDates, } from "./businessCalendar.js";
+import { isValidAmount } from "./isValidAmount.js";
+import { isValidDate } from "../plain/validate/isValidDate.js";
+/**
+ * The shared body of `addBusinessDays` and `subtractBusinessDays`: validate, resolve the
+ * calendar, and walk `amount` working days from `value`.
+ *
+ * - `sign` is the direction a **positive** `amount` moves — `1` for adding, `-1` for
+ *   subtracting — so a negative `amount` walks the other way in both.
+ * - `calendar` is optional; absent means Saturday–Sunday with no holidays.
+ * - Returns `""` on an invalid date, a non-integer or out-of-range `amount`, an invalid
+ *   calendar, and when the walk runs past `MAX_BUSINESS_DAY_STEPS`.
+ */
+export function stepBusinessDaysValue(value, amount, sign, calendar) {
+    const resolved = resolveBusinessCalendar(calendar);
+    if (!isValidDate(value) ||
+        !isValidAmount(amount) ||
+        !Number.isInteger(amount) ||
+        resolved === null) {
+        return "";
+    }
+    try {
+        if (amount === 0) {
+            return Temporal.PlainDate.from(value).toString();
+        }
+        const direction = amount > 0 ? sign : sign === 1 ? -1 : 1;
+        const result = stepBusinessDates(Temporal.PlainDate.from(value), direction, Math.abs(amount), resolved);
+        return result === null ? "" : result.toString();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The shared body of `nextBusinessDay` and `previousBusinessDay`: the first working day
+ * **strictly** one business day away from `value`, in `direction`.
+ *
+ * Unlike `stepBusinessDaysValue`, `calendar` is required — these two assume no weekend, so an
+ * absent calendar is invalid input rather than the Saturday–Sunday default.
+ */
+export function neighbourBusinessDayValue(value, direction, calendar) {
+    const resolved = parseBusinessCalendar(calendar);
+    if (!isValidDate(value) || resolved === null) {
+        return "";
+    }
+    try {
+        const result = stepBusinessDates(Temporal.PlainDate.from(value), direction, 1, resolved);
+        return result === null ? "" : result.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/internal/calendarDatePairPolicy.d.ts

@@ -7,19 +7,17 @@ export interface CalendarDatePair {
 }
 /**
  * Parse two GMT PlainDate values for calendar-unit arithmetic (diff, count, length, split-by-
- * unit): measure in the endpoints' shared calendar when both match, fall back to Gregorian/ISO
- * otherwise, rather than rejecting outright.
+ * unit): both must name the same calendar, which the pair is measured in.
  *
- * E5 decision of record D5: unlike D4's value-returning interval set-operations (union,
- * intersection, difference, xor, split, divide, merge — which reject a mismatch via
- * `calendarOfAllDateValues` instead, since there's no principled output calendar to pick for a
- * *value* the caller reads back as a date), ordering and duration math both remain well-defined
- * across mismatched calendars: Temporal's own `compare` is calendar-independent, and falling
- * back to ISO for a genuinely mismatched pair is a reasonable, well-defined answer rather than
- * an arbitrary pick.
+ * Follows TC39 Temporal's `DifferenceTemporalPlainDate`: when `CalendarEquals` is false it throws
+ * a RangeError, for every `largestUnit`. Calendars are compared by their canonical id, so
+ * `ethiopic-amete-alem` and `ethioaa` agree, while `iso8601` and `gregory`, or `ethiopic` and
+ * `ethioaa`, do not. A bare ISO string names `iso8601`. Callers catch the throw and return their
+ * sentinel. (Before 1.16.0 the pair fell back to ISO; ordering-only functions still accept
+ * mixed calendars, because `Temporal.PlainDate.compare` has no calendar check.)
  *
- * Throws if either value fails to parse as a valid GMT PlainDate string — callers are expected
- * to have already validated both values (e.g. via `isValidCalendarDate`) before calling this,
- * consistent with GMT's existing gate-then-parse-inside-try structure.
+ * Throws if either value fails to parse as a valid GMT PlainDate string, or if the calendars
+ * differ — callers validate both values first (e.g. via `isValidCalendarDate`) and wrap this in
+ * try-catch, consistent with GMT's gate-then-parse-inside-try structure.
  */
 export declare function parseCalendarDatePairForArithmetic(aValue: string, bValue: string): CalendarDatePair;

package/dist/internal/calendarDatePairPolicy.js

@@ -2,32 +2,26 @@ import { parseCalendarDateValue } from "./calendarDateString.js";
 import { calendarSystemOfDateValue } from "./calendarValueOfDate.js";
 /**
  * Parse two GMT PlainDate values for calendar-unit arithmetic (diff, count, length, split-by-
- * unit): measure in the endpoints' shared calendar when both match, fall back to Gregorian/ISO
- * otherwise, rather than rejecting outright.
+ * unit): both must name the same calendar, which the pair is measured in.
  *
- * E5 decision of record D5: unlike D4's value-returning interval set-operations (union,
- * intersection, difference, xor, split, divide, merge — which reject a mismatch via
- * `calendarOfAllDateValues` instead, since there's no principled output calendar to pick for a
- * *value* the caller reads back as a date), ordering and duration math both remain well-defined
- * across mismatched calendars: Temporal's own `compare` is calendar-independent, and falling
- * back to ISO for a genuinely mismatched pair is a reasonable, well-defined answer rather than
- * an arbitrary pick.
+ * Follows TC39 Temporal's `DifferenceTemporalPlainDate`: when `CalendarEquals` is false it throws
+ * a RangeError, for every `largestUnit`. Calendars are compared by their canonical id, so
+ * `ethiopic-amete-alem` and `ethioaa` agree, while `iso8601` and `gregory`, or `ethiopic` and
+ * `ethioaa`, do not. A bare ISO string names `iso8601`. Callers catch the throw and return their
+ * sentinel. (Before 1.16.0 the pair fell back to ISO; ordering-only functions still accept
+ * mixed calendars, because `Temporal.PlainDate.compare` has no calendar check.)
  *
- * Throws if either value fails to parse as a valid GMT PlainDate string — callers are expected
- * to have already validated both values (e.g. via `isValidCalendarDate`) before calling this,
- * consistent with GMT's existing gate-then-parse-inside-try structure.
+ * Throws if either value fails to parse as a valid GMT PlainDate string, or if the calendars
+ * differ — callers validate both values first (e.g. via `isValidCalendarDate`) and wrap this in
+ * try-catch, consistent with GMT's gate-then-parse-inside-try structure.
  */
 export function parseCalendarDatePairForArithmetic(aValue, bValue) {
     const calendarA = calendarSystemOfDateValue(aValue);
     const calendarB = calendarSystemOfDateValue(bValue);
     const a = parseCalendarDateValue(aValue);
     const b = parseCalendarDateValue(bValue);
-    if (calendarA && calendarB && calendarA === calendarB) {
-        return { calendar: calendarA, a, b };
+    if (!calendarA || calendarA !== calendarB) {
+        throw new RangeError(`Mismatched calendars: ${String(calendarA)} and ${String(calendarB)}`);
     }
-    return {
-        calendar: "gregorian",
-        a: a.withCalendar("iso8601"),
-        b: b.withCalendar("iso8601"),
-    };
+    return { calendar: calendarA, a, b };
 }