@northguild/gmt 1.14.2 → 1.16.0

package/dist/calendar/business/businessDaysBetween.d.ts

@@ -0,0 +1,37 @@
+import type { BusinessCalendar } from "../../types/index.js";
+/**
+ * Count the working days between two local dates, **excluding `start` and including `end`**.
+ *
+ * - The convention is stated, not inferred: the range is `(start, end]`. Counting from Monday
+ *   to Friday of the same week gives 4, not 5 — Monday itself is not counted.
+ * - That makes it the inverse of `addBusinessDays` when `n ≥ 0` or `start` is a business day:
+ *   if `end` is `addBusinessDays(start, n, calendar)`, this returns `n`. From a weekend or
+ *   holiday `start`, a negative `n` counts one closer to zero, because `start` itself is
+ *   excluded and is not a business day.
+ * - `end` before `start` returns a negative count, so swapping the arguments negates the
+ *   result. An empty range is always `0`, never `-0`, and `businessDaysBetween(d, d, calendar)`
+ *   is 0 for any `d`.
+ * - The count is computed, not walked, so there is no range limit: whole weeks contribute one
+ *   of each weekday and only the holidays are visited individually.
+ * - Both dates and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A
+ *   caller holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `null` when either date is not a valid ISO PlainDate, or `calendar` is not a valid
+ *   `BusinessCalendar`. Narrow it with `isValidBusinessCalendar` to tell a misconfigured
+ *   calendar apart from a genuine 0.
+ *
+ * @param start ISO PlainDate string, excluded from the count
+ * @param end ISO PlainDate string, included in the count
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns number of working days in `(start, end]`, negative when `end` precedes `start`, or null on invalid input
+ *
+ * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // 3 — Tue, Wed, Fri
+ * @example businessDaysBetween("2024-07-05", "2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 1 — Monday, over the weekend
+ * @example businessDaysBetween("2024-07-01", "2024-07-31", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 22 — July's 23 weekdays less the 1st
+ * @example businessDaysBetween("2024-07-01", "2024-07-01", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0
+ * @example businessDaysBetween("2024-07-05", "2024-07-01", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // -3 — reversed
+ * @example businessDaysBetween("2024-07-06", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0 — addBusinessDays("2024-07-06", -1) is "2024-07-05", but Saturday is excluded
+ * @example businessDaysBetween("2024-07-01", "2024-07-08", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // 5 — Friday–Saturday weekend
+ * @example businessDaysBetween("invalid", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // null
+ * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // null
+ */
+export declare function businessDaysBetween(start: string, end: string, calendar: BusinessCalendar): number | null;

package/dist/calendar/business/businessDaysBetween.js

@@ -0,0 +1,89 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
+import { isValidDate } from "../../plain/validate/index.js";
+const DAYS_PER_WEEK = 7;
+/**
+ * Count the business days in `(from, to]`, given `from` is not after `to`.
+ *
+ * Whole weeks contribute one of each weekday, so only the remainder is walked and the count
+ * costs the same for a range of days as for one of centuries.
+ */
+function countBusinessDates(from, to, weekend, holidays) {
+    const days = from.until(to, { largestUnit: "day" }).days;
+    const wholeWeeks = Math.floor(days / DAYS_PER_WEEK);
+    const businessDaysPerWeek = DAYS_PER_WEEK - weekend.size;
+    let count = wholeWeeks * businessDaysPerWeek;
+    for (let offset = wholeWeeks * DAYS_PER_WEEK + 1; offset <= days; offset++) {
+        if (!weekend.has(from.add({ days: offset }).dayOfWeek)) {
+            count += 1;
+        }
+    }
+    for (const holiday of holidays) {
+        const date = Temporal.PlainDate.from(holiday);
+        const insideRange = Temporal.PlainDate.compare(date, from) > 0 &&
+            Temporal.PlainDate.compare(date, to) <= 0;
+        if (insideRange && !weekend.has(date.dayOfWeek)) {
+            count -= 1;
+        }
+    }
+    return count;
+}
+/**
+ * Count the working days between two local dates, **excluding `start` and including `end`**.
+ *
+ * - The convention is stated, not inferred: the range is `(start, end]`. Counting from Monday
+ *   to Friday of the same week gives 4, not 5 — Monday itself is not counted.
+ * - That makes it the inverse of `addBusinessDays` when `n ≥ 0` or `start` is a business day:
+ *   if `end` is `addBusinessDays(start, n, calendar)`, this returns `n`. From a weekend or
+ *   holiday `start`, a negative `n` counts one closer to zero, because `start` itself is
+ *   excluded and is not a business day.
+ * - `end` before `start` returns a negative count, so swapping the arguments negates the
+ *   result. An empty range is always `0`, never `-0`, and `businessDaysBetween(d, d, calendar)`
+ *   is 0 for any `d`.
+ * - The count is computed, not walked, so there is no range limit: whole weeks contribute one
+ *   of each weekday and only the holidays are visited individually.
+ * - Both dates and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A
+ *   caller holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `null` when either date is not a valid ISO PlainDate, or `calendar` is not a valid
+ *   `BusinessCalendar`. Narrow it with `isValidBusinessCalendar` to tell a misconfigured
+ *   calendar apart from a genuine 0.
+ *
+ * @param start ISO PlainDate string, excluded from the count
+ * @param end ISO PlainDate string, included in the count
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns number of working days in `(start, end]`, negative when `end` precedes `start`, or null on invalid input
+ *
+ * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // 3 — Tue, Wed, Fri
+ * @example businessDaysBetween("2024-07-05", "2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 1 — Monday, over the weekend
+ * @example businessDaysBetween("2024-07-01", "2024-07-31", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 22 — July's 23 weekdays less the 1st
+ * @example businessDaysBetween("2024-07-01", "2024-07-01", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0
+ * @example businessDaysBetween("2024-07-05", "2024-07-01", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // -3 — reversed
+ * @example businessDaysBetween("2024-07-06", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0 — addBusinessDays("2024-07-06", -1) is "2024-07-05", but Saturday is excluded
+ * @example businessDaysBetween("2024-07-01", "2024-07-08", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // 5 — Friday–Saturday weekend
+ * @example businessDaysBetween("invalid", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // null
+ * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // null
+ */
+export function businessDaysBetween(start, end, calendar) {
+    try {
+        const resolved = parseBusinessCalendar(calendar);
+        if (!isValidDate(start) || !isValidDate(end) || resolved === null) {
+            return null;
+        }
+        try {
+            const startDate = Temporal.PlainDate.from(start);
+            const endDate = Temporal.PlainDate.from(end);
+            const reversed = Temporal.PlainDate.compare(startDate, endDate) > 0;
+            const count = countBusinessDates(reversed ? endDate : startDate, reversed ? startDate : endDate, resolved.weekend, resolved.holidays);
+            // `0 - count` rather than `-count`: an empty reversed range must be 0, not -0.
+            return reversed ? 0 - count : count;
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/calendar/business/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./businessDaysBetween.js";
+export * from "./mergeCalendars.js";
+export * from "./nextBusinessDay.js";
+export * from "./previousBusinessDay.js";
+export * from "./rollDate.js";
+export { addBusinessDays, subtractBusinessDays } from "../../plain/calculate/index.js";
+export { isBusinessDay } from "../../plain/compare/index.js";

package/dist/calendar/business/index.js

@@ -0,0 +1,10 @@
+export * from "./businessDaysBetween.js";
+export * from "./mergeCalendars.js";
+export * from "./nextBusinessDay.js";
+export * from "./previousBusinessDay.js";
+export * from "./rollDate.js";
+// `isBusinessDay`, `addBusinessDays` and `subtractBusinessDays` predate this namespace and
+// keep their published `plain/` subpath. They are the same bindings, re-exported here so the
+// business-day family reads as one unit.
+export { addBusinessDays, subtractBusinessDays } from "../../plain/calculate/index.js";
+export { isBusinessDay } from "../../plain/compare/index.js";

package/dist/calendar/business/mergeCalendars.d.ts

@@ -0,0 +1,33 @@
+import type { BusinessCalendar } from "../../types/index.js";
+/**
+ * Compose several jurisdictions' calendars into one whose working days are those they all
+ * share.
+ *
+ * - A date is a working day in the result only if it is a working day in **every** input: the
+ *   weekend days union and so do the holidays, so a closure anywhere closes the merged
+ *   calendar.
+ * - This is why the business-day engine is core rather than finance. FX settlement needs both
+ *   currencies' calendars, an intermodal move the origin port's and the destination port's,
+ *   and a cross-border rail path both national calendars — one implementation, four consumers.
+ * - `weekend` and `holidays` come back sorted ascending and de-duplicated, so the result is
+ *   stable whatever order the inputs arrive in. Holidays sort chronologically, not
+ *   lexicographically, so an expanded year such as `"+010000-01-01"` lands where it belongs.
+ * - `timeZone` is the **first** calendar's. The merged calendar spans localities that may
+ *   disagree, and GMT does not invent a zone for it; the field records locality only and no
+ *   business-day function reads it.
+ * - Returns `null` for an empty list — there is no `timeZone` to take — when `calendars` is
+ *   not an array, when any element is not a valid `BusinessCalendar`, and when the merged
+ *   weekend swallows all seven weekdays, leaving a calendar with no working day at all.
+ *   `isValidBusinessCalendar` tells a legitimate result apart from that sentinel.
+ *
+ * @param calendars array of BusinessCalendar records to compose
+ * @returns merged BusinessCalendar, or null on invalid input
+ *
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }, { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" }]) // { weekend: [6, 7], holidays: ["2024-05-06", "2024-07-04"], timeZone: "America/New_York" }
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: [], timeZone: "UTC" }, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }]) // { weekend: [5, 6, 7], holidays: [], timeZone: "UTC" } — only Sunday to Thursday survive
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }]) // { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }
+ * @example mergeCalendars([]) // null
+ * @example mergeCalendars([{ weekend: [1, 2, 3, 4], holidays: [], timeZone: "UTC" }, { weekend: [5, 6, 7], holidays: [], timeZone: "UTC" }]) // null — no working day left
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }]) // null
+ */
+export declare function mergeCalendars(calendars: BusinessCalendar[]): BusinessCalendar | null;

package/dist/calendar/business/mergeCalendars.js

@@ -0,0 +1,68 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
+/**
+ * Compose several jurisdictions' calendars into one whose working days are those they all
+ * share.
+ *
+ * - A date is a working day in the result only if it is a working day in **every** input: the
+ *   weekend days union and so do the holidays, so a closure anywhere closes the merged
+ *   calendar.
+ * - This is why the business-day engine is core rather than finance. FX settlement needs both
+ *   currencies' calendars, an intermodal move the origin port's and the destination port's,
+ *   and a cross-border rail path both national calendars — one implementation, four consumers.
+ * - `weekend` and `holidays` come back sorted ascending and de-duplicated, so the result is
+ *   stable whatever order the inputs arrive in. Holidays sort chronologically, not
+ *   lexicographically, so an expanded year such as `"+010000-01-01"` lands where it belongs.
+ * - `timeZone` is the **first** calendar's. The merged calendar spans localities that may
+ *   disagree, and GMT does not invent a zone for it; the field records locality only and no
+ *   business-day function reads it.
+ * - Returns `null` for an empty list — there is no `timeZone` to take — when `calendars` is
+ *   not an array, when any element is not a valid `BusinessCalendar`, and when the merged
+ *   weekend swallows all seven weekdays, leaving a calendar with no working day at all.
+ *   `isValidBusinessCalendar` tells a legitimate result apart from that sentinel.
+ *
+ * @param calendars array of BusinessCalendar records to compose
+ * @returns merged BusinessCalendar, or null on invalid input
+ *
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }, { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" }]) // { weekend: [6, 7], holidays: ["2024-05-06", "2024-07-04"], timeZone: "America/New_York" }
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: [], timeZone: "UTC" }, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }]) // { weekend: [5, 6, 7], holidays: [], timeZone: "UTC" } — only Sunday to Thursday survive
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }]) // { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }
+ * @example mergeCalendars([]) // null
+ * @example mergeCalendars([{ weekend: [1, 2, 3, 4], holidays: [], timeZone: "UTC" }, { weekend: [5, 6, 7], holidays: [], timeZone: "UTC" }]) // null — no working day left
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }]) // null
+ */
+export function mergeCalendars(calendars) {
+    try {
+        if (!Array.isArray(calendars) || calendars.length === 0) {
+            return null;
+        }
+        const weekend = new Set();
+        const holidays = new Set();
+        for (const calendar of calendars) {
+            const resolved = parseBusinessCalendar(calendar);
+            if (resolved === null) {
+                return null;
+            }
+            for (const day of resolved.weekend) {
+                weekend.add(day);
+            }
+            for (const holiday of resolved.holidays) {
+                holidays.add(holiday);
+            }
+        }
+        const merged = {
+            weekend: [...weekend].sort((a, b) => a - b),
+            // Chronological, not lexicographic: a bare `.sort()` compares as strings, which puts the
+            // "+" and "-" of an expanded year below every digit.
+            holidays: [...holidays].sort((a, b) => Temporal.PlainDate.compare(a, b)),
+            timeZone: calendars[0].timeZone,
+        };
+        // The union can close every weekday even when no input does, which is not a calendar.
+        return parseBusinessCalendar(merged) === null ? null : merged;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/calendar/business/nextBusinessDay.d.ts

@@ -0,0 +1,30 @@
+import type { BusinessCalendar } from "../../types/index.js";
+/**
+ * Return the first working day **strictly after** `value`.
+ *
+ * - Strictly after: called on a working day it returns the next one, never `value` itself.
+ *   For the on-or-after behaviour — leave a working day alone, move a non-working one forward
+ *   — use `rollDate(value, "following", calendar)`.
+ * - Equivalent to `addBusinessDays(value, 1, calendar)` for any valid calendar, but the
+ *   calendar is **required** here: there is no Saturday–Sunday default to fall back on,
+ *   because a weekend is never assumed.
+ * - `value` may be any local date, working or not: being called from a weekend or a holiday is
+ *   the normal case, not an error.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `""` when `value` is not a valid ISO PlainDate, when `calendar` is not a valid
+ *   `BusinessCalendar`, and when the walk runs past 200,000 calendar days without finding a
+ *   working day.
+ *
+ * @param value ISO PlainDate string to start from, excluded from the search
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns ISO PlainDate string of the next working day, or "" on invalid input
+ *
+ * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — skips the holiday
+ * @example nextBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — from the holiday itself
+ * @example nextBusinessDay("2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-08" — Friday over the weekend
+ * @example nextBusinessDay("2024-07-04", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" — Friday–Saturday weekend
+ * @example nextBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""
+ * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // ""
+ */
+export declare function nextBusinessDay(value: string, calendar: BusinessCalendar): string;

package/dist/calendar/business/nextBusinessDay.js

@@ -0,0 +1,39 @@
+import { neighbourBusinessDayValue } from "../../internal/businessDayValues.js";
+/**
+ * Return the first working day **strictly after** `value`.
+ *
+ * - Strictly after: called on a working day it returns the next one, never `value` itself.
+ *   For the on-or-after behaviour — leave a working day alone, move a non-working one forward
+ *   — use `rollDate(value, "following", calendar)`.
+ * - Equivalent to `addBusinessDays(value, 1, calendar)` for any valid calendar, but the
+ *   calendar is **required** here: there is no Saturday–Sunday default to fall back on,
+ *   because a weekend is never assumed.
+ * - `value` may be any local date, working or not: being called from a weekend or a holiday is
+ *   the normal case, not an error.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `""` when `value` is not a valid ISO PlainDate, when `calendar` is not a valid
+ *   `BusinessCalendar`, and when the walk runs past 200,000 calendar days without finding a
+ *   working day.
+ *
+ * @param value ISO PlainDate string to start from, excluded from the search
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns ISO PlainDate string of the next working day, or "" on invalid input
+ *
+ * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — skips the holiday
+ * @example nextBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — from the holiday itself
+ * @example nextBusinessDay("2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-08" — Friday over the weekend
+ * @example nextBusinessDay("2024-07-04", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" — Friday–Saturday weekend
+ * @example nextBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""
+ * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // ""
+ */
+export function nextBusinessDay(value, calendar) {
+    try {
+        return neighbourBusinessDayValue(value, 1, calendar);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/calendar/business/previousBusinessDay.d.ts

@@ -0,0 +1,30 @@
+import type { BusinessCalendar } from "../../types/index.js";
+/**
+ * Return the last working day **strictly before** `value`.
+ *
+ * - Strictly before: called on a working day it returns the previous one, never `value`
+ *   itself. For the on-or-before behaviour — leave a working day alone, move a non-working one
+ *   backward — use `rollDate(value, "preceding", calendar)`.
+ * - Equivalent to `subtractBusinessDays(value, 1, calendar)` for any valid calendar, but the
+ *   calendar is **required** here: there is no Saturday–Sunday default to fall back on,
+ *   because a weekend is never assumed.
+ * - `value` may be any local date, working or not: being called from a weekend or a holiday is
+ *   the normal case, not an error.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `""` when `value` is not a valid ISO PlainDate, when `calendar` is not a valid
+ *   `BusinessCalendar`, and when the walk runs past 200,000 calendar days without finding a
+ *   working day.
+ *
+ * @param value ISO PlainDate string to start from, excluded from the search
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns ISO PlainDate string of the previous working day, or "" on invalid input
+ *
+ * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — skips the holiday
+ * @example previousBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — from the holiday itself
+ * @example previousBusinessDay("2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-05" — Monday back over the weekend
+ * @example previousBusinessDay("2024-07-07", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-04" — Friday–Saturday weekend
+ * @example previousBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""
+ * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // ""
+ */
+export declare function previousBusinessDay(value: string, calendar: BusinessCalendar): string;

package/dist/calendar/business/previousBusinessDay.js

@@ -0,0 +1,39 @@
+import { neighbourBusinessDayValue } from "../../internal/businessDayValues.js";
+/**
+ * Return the last working day **strictly before** `value`.
+ *
+ * - Strictly before: called on a working day it returns the previous one, never `value`
+ *   itself. For the on-or-before behaviour — leave a working day alone, move a non-working one
+ *   backward — use `rollDate(value, "preceding", calendar)`.
+ * - Equivalent to `subtractBusinessDays(value, 1, calendar)` for any valid calendar, but the
+ *   calendar is **required** here: there is no Saturday–Sunday default to fall back on,
+ *   because a weekend is never assumed.
+ * - `value` may be any local date, working or not: being called from a weekend or a holiday is
+ *   the normal case, not an error.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `""` when `value` is not a valid ISO PlainDate, when `calendar` is not a valid
+ *   `BusinessCalendar`, and when the walk runs past 200,000 calendar days without finding a
+ *   working day.
+ *
+ * @param value ISO PlainDate string to start from, excluded from the search
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns ISO PlainDate string of the previous working day, or "" on invalid input
+ *
+ * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — skips the holiday
+ * @example previousBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — from the holiday itself
+ * @example previousBusinessDay("2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-05" — Monday back over the weekend
+ * @example previousBusinessDay("2024-07-07", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-04" — Friday–Saturday weekend
+ * @example previousBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""
+ * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // ""
+ */
+export function previousBusinessDay(value, calendar) {
+    try {
+        return neighbourBusinessDayValue(value, -1, calendar);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/calendar/business/rollDate.d.ts

@@ -0,0 +1,59 @@
+import type { BusinessCalendar, RollConvention } from "../../types/index.js";
+/**
+ * Move a local date onto a working day according to `convention`.
+ *
+ * Every industry answers "what if it lands on a non-working day" differently, so the
+ * convention is always explicit — there is no default.
+ *
+ * | Convention | Behaviour |
+ * | --- | --- |
+ * | `following` | Forward to the next working day; a working day is left alone |
+ * | `modifiedFollowing` | Forward, unless that crosses into the next month, then backward |
+ * | `preceding` | Backward to the previous working day; a working day is left alone |
+ * | `modifiedPreceding` | Backward, unless that crosses into the previous month, then forward |
+ * | `endOfMonth` | The last working day of `value`'s own month, wherever in the month it falls |
+ * | `none` | Return `value` unadjusted, working day or not |
+ *
+ * - `following` and `preceding` are **on or after** and **on or before**: they return `value`
+ *   itself when it is already a working day. For the strict neighbours use `nextBusinessDay`
+ *   and `previousBusinessDay`.
+ * - `following`, `modifiedFollowing` and `preceding` are the three conventions
+ *   [ISDA 2006 Definitions §4.12(a)](https://www.isda.org/a/smMDE/Blackline-2000-v-2006-ISDA-Definitions.pdf) defines, in
+ *   (i)–(iii), and match that text: (iii) reads "if 'Preceding' is specified, that date will be
+ *   the first preceding day that is a Business Day". §4.12(a) has no Modified Preceding;
+ *   `modifiedPreceding` follows FpML's `BusinessDayConventionEnum` `MODPRECEDING`: "adjusted
+ *   to the first preceding day that is a business day unless that day falls in the previous
+ *   calendar month, in which case … the first following day". `none` is what
+ *   [OpenGamma Strata](https://strata.opengamma.io/apidocs/com/opengamma/strata/basics/date/BusinessDayConventions.html)
+ *   calls `NO_ADJUST`. No TC39, ECMA or RFC standard governs them.
+ * - `endOfMonth` is **not** an ISDA business-day convention, and not the industry "EOM rule",
+ *   which is a *schedule* rule: hold every date in a schedule to its month's last day once
+ *   the anchor is one. It is GMT's primitive for building that rule. It always snaps to the
+ *   last working day on or before the month's final day, even from mid-month — leaving the
+ *   month only if that whole month is closed, as a works shutdown would make it. A forward
+ *   from a month-end anchor settles on the last working day of the *target* month, so the
+ *   caller tests the anchor for month-end and applies this to the unadjusted target. Applied
+ *   to a month-end date it agrees with `modifiedFollowing`.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `""` when `value` is not a valid ISO PlainDate, when `convention` is not one GMT
+ *   implements, when `calendar` is not a valid `BusinessCalendar`, and when the walk runs past
+ *   200,000 calendar days without finding a working day. Narrow the convention with
+ *   `isValidRollConvention` to tell a misconfigured contract term apart from a bad date.
+ *
+ * @param value ISO PlainDate string to roll
+ * @param convention RollConvention to apply
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns ISO PlainDate string of the rolled date, or "" on invalid input
+ *
+ * @example rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03"
+ * @example rollDate("2024-05-31", "modifiedFollowing", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-05-30" — forward would leave May
+ * @example rollDate("2024-06-01", "modifiedPreceding", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03" — backward would leave June
+ * @example rollDate("2024-05-29", "following", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-05-29" — already a working day
+ * @example rollDate("2024-03-15", "endOfMonth", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-03-29" — March ends on a Sunday
+ * @example rollDate("2024-06-01", "none", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-06-01" — a Saturday, unadjusted
+ * @example rollDate("2024-07-05", "following", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" — Friday–Saturday weekend
+ * @example rollDate("2024-05-31", "nearest", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "" — not a convention GMT implements
+ * @example rollDate("invalid", "following", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""
+ */
+export declare function rollDate(value: string, convention: RollConvention, calendar: BusinessCalendar): string;

package/dist/calendar/business/rollDate.js

@@ -0,0 +1,116 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { businessDateFrom, parseBusinessCalendar, } from "../../internal/businessCalendar.js";
+import { isValidDate } from "../../plain/validate/index.js";
+import { isValidRollConvention } from "../validate/index.js";
+function sameMonth(a, b) {
+    return a.year === b.year && a.month === b.month;
+}
+/**
+ * Roll in `direction`, and if that leaves the date's month, roll the other way instead.
+ */
+function modifiedRoll(date, direction, calendar) {
+    const rolled = businessDateFrom(date, direction, calendar);
+    // An exhausted walk is a sentinel, not a "left the month" answer: turning round here would
+    // report the opposite direction's date as though the first walk had succeeded.
+    if (rolled === null) {
+        return null;
+    }
+    return sameMonth(rolled, date)
+        ? rolled
+        : businessDateFrom(date, direction === 1 ? -1 : 1, calendar);
+}
+function rollTo(date, convention, calendar) {
+    switch (convention) {
+        case "following":
+            return businessDateFrom(date, 1, calendar);
+        case "preceding":
+            return businessDateFrom(date, -1, calendar);
+        case "modifiedFollowing":
+            return modifiedRoll(date, 1, calendar);
+        case "modifiedPreceding":
+            return modifiedRoll(date, -1, calendar);
+        case "endOfMonth":
+            return businessDateFrom(date.with({ day: date.daysInMonth }), -1, calendar);
+        case "none":
+            return date;
+    }
+}
+/**
+ * Move a local date onto a working day according to `convention`.
+ *
+ * Every industry answers "what if it lands on a non-working day" differently, so the
+ * convention is always explicit — there is no default.
+ *
+ * | Convention | Behaviour |
+ * | --- | --- |
+ * | `following` | Forward to the next working day; a working day is left alone |
+ * | `modifiedFollowing` | Forward, unless that crosses into the next month, then backward |
+ * | `preceding` | Backward to the previous working day; a working day is left alone |
+ * | `modifiedPreceding` | Backward, unless that crosses into the previous month, then forward |
+ * | `endOfMonth` | The last working day of `value`'s own month, wherever in the month it falls |
+ * | `none` | Return `value` unadjusted, working day or not |
+ *
+ * - `following` and `preceding` are **on or after** and **on or before**: they return `value`
+ *   itself when it is already a working day. For the strict neighbours use `nextBusinessDay`
+ *   and `previousBusinessDay`.
+ * - `following`, `modifiedFollowing` and `preceding` are the three conventions
+ *   [ISDA 2006 Definitions §4.12(a)](https://www.isda.org/a/smMDE/Blackline-2000-v-2006-ISDA-Definitions.pdf) defines, in
+ *   (i)–(iii), and match that text: (iii) reads "if 'Preceding' is specified, that date will be
+ *   the first preceding day that is a Business Day". §4.12(a) has no Modified Preceding;
+ *   `modifiedPreceding` follows FpML's `BusinessDayConventionEnum` `MODPRECEDING`: "adjusted
+ *   to the first preceding day that is a business day unless that day falls in the previous
+ *   calendar month, in which case … the first following day". `none` is what
+ *   [OpenGamma Strata](https://strata.opengamma.io/apidocs/com/opengamma/strata/basics/date/BusinessDayConventions.html)
+ *   calls `NO_ADJUST`. No TC39, ECMA or RFC standard governs them.
+ * - `endOfMonth` is **not** an ISDA business-day convention, and not the industry "EOM rule",
+ *   which is a *schedule* rule: hold every date in a schedule to its month's last day once
+ *   the anchor is one. It is GMT's primitive for building that rule. It always snaps to the
+ *   last working day on or before the month's final day, even from mid-month — leaving the
+ *   month only if that whole month is closed, as a works shutdown would make it. A forward
+ *   from a month-end anchor settles on the last working day of the *target* month, so the
+ *   caller tests the anchor for month-end and applies this to the unadjusted target. Applied
+ *   to a month-end date it agrees with `modifiedFollowing`.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns `""` when `value` is not a valid ISO PlainDate, when `convention` is not one GMT
+ *   implements, when `calendar` is not a valid `BusinessCalendar`, and when the walk runs past
+ *   200,000 calendar days without finding a working day. Narrow the convention with
+ *   `isValidRollConvention` to tell a misconfigured contract term apart from a bad date.
+ *
+ * @param value ISO PlainDate string to roll
+ * @param convention RollConvention to apply
+ * @param calendar BusinessCalendar naming the weekend days and holidays
+ * @returns ISO PlainDate string of the rolled date, or "" on invalid input
+ *
+ * @example rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03"
+ * @example rollDate("2024-05-31", "modifiedFollowing", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-05-30" — forward would leave May
+ * @example rollDate("2024-06-01", "modifiedPreceding", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03" — backward would leave June
+ * @example rollDate("2024-05-29", "following", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-05-29" — already a working day
+ * @example rollDate("2024-03-15", "endOfMonth", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-03-29" — March ends on a Sunday
+ * @example rollDate("2024-06-01", "none", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-06-01" — a Saturday, unadjusted
+ * @example rollDate("2024-07-05", "following", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" — Friday–Saturday weekend
+ * @example rollDate("2024-05-31", "nearest", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "" — not a convention GMT implements
+ * @example rollDate("invalid", "following", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""
+ */
+export function rollDate(value, convention, calendar) {
+    try {
+        const resolved = parseBusinessCalendar(calendar);
+        if (!isValidDate(value) ||
+            !isValidRollConvention(convention) ||
+            resolved === null) {
+            return "";
+        }
+        try {
+            const rolled = rollTo(Temporal.PlainDate.from(value), convention, resolved);
+            return rolled === null ? "" : rolled.toString();
+        }
+        catch {
+            return "";
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/calendar/calculate/bucketRange.d.ts

@@ -0,0 +1,49 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { ZoneBucketUnit } from "../../types/index.js";
+/**
+ * Return the start instant of every `unit` bucket the half-open range `[start, end)` touches,
+ * bucketed **in `timeZone`**.
+ *
+ * This is "group by day in `America/New_York`" over UTC timestamps, done correctly. Buckets
+ * are not uniform in length and that is the point: a day that springs forward is 23 hours and
+ * one that falls back is 25, so a daily aggregate built on a fixed 24 hours drifts an hour
+ * twice a year, and a container's chargeable days — counted in terminal-local calendar days —
+ * come out wrong.
+ *
+ * - Each entry is a boundary `floorToZone` would return, so bucket *i* runs from `result[i]`
+ *   up to (not including) `result[i + 1]`, and the last runs to the next boundary after it.
+ * - The range is half-open: an `end` landing exactly on a boundary does not open that bucket.
+ *   A zero-length range mid-bucket still returns the one bucket holding it; on a boundary it
+ *   returns `[]`.
+ * - Both endpoints are read in `timeZone`. Any bracketed zone they carry is ignored, as in
+ *   `floorToZone`.
+ * - Weeks start on Monday (ISO 8601). `unit` is the same four-unit set `floorToZone` takes,
+ *   singular or plural, which `isValidZoneBucketUnit` narrows.
+ * - A local boundary that does not exist is not invented: the day Samoa deleted crossing the
+ *   date line is absent, a local day whose midnight is skipped starts at 01:00, and in a zone
+ *   that falls back by half an hour the local 01:00 hour bucket is 90 minutes long.
+ * - A bucket is returned when its start is representable, even if the bucket after it would
+ *   start past Temporal's last instant (`+275760-09-13T00:00:00Z`).
+ * - Returns `[]` on invalid input, when `start` is after `end`, when the range would need more
+ *   than 10,000 buckets, when a boundary in it is not representable (see `floorToZone`), and
+ *   if a zone ever presented more transitions inside one bucket than the stepper walks — no
+ *   IANA zone does, and the whole table was swept to confirm it. A truncated list would be
+ *   worse than the sentinel, so none is returned in any of those cases.
+ *
+ * @param start ISO 8601 instant string for the range start (inclusive)
+ * @param end ISO 8601 instant string for the range end (exclusive)
+ * @param unit bucket unit ("hour" | "day" | "week" | "month", or its plural)
+ * @param timeZone IANA timeZone identifier the buckets are computed in
+ * @returns array of UTC instant strings ending in "Z", or [] on invalid input
+ *
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "day", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"]
+ * @example bucketRange("2024-03-09T05:00:00Z", "2024-03-12T04:00:00Z", "day", "America/New_York") // ["2024-03-09T05:00:00Z", "2024-03-10T05:00:00Z", "2024-03-11T04:00:00Z"] (the middle day is 23 hours)
+ * @example bucketRange("2024-11-02T04:00:00Z", "2024-11-05T05:00:00Z", "day", "America/New_York") // ["2024-11-02T04:00:00Z", "2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z"] (the middle day is 25 hours)
+ * @example bucketRange("2024-11-03T04:00:00Z", "2024-11-03T08:00:00Z", "hour", "America/New_York") // ["2024-11-03T04:00:00Z", "2024-11-03T05:00:00Z", "2024-11-03T06:00:00Z", "2024-11-03T07:00:00Z"] (the repeated 01:00 is its own bucket)
+ * @example bucketRange("2024-06-14T04:00:00Z", "2024-06-14T04:00:00Z", "day", "America/New_York") // [] (zero length, on a boundary)
+ * @example bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/New_York") // ["+275760-09-12T04:00:00Z"] (the next day would start past the last instant; this one is still returned)
+ * @example bucketRange("2024-06-16T00:00:00Z", "2024-06-15T00:00:00Z", "day", "UTC") // [] (start after end)
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "days", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"] (plural unit name)
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "year", "UTC") // [] (not a bucketing unit)
+ */
+export declare function bucketRange(start: string, end: string, unit: Temporal.SmallestUnit<ZoneBucketUnit>, timeZone: string): string[];