@northguild/gmt 1.15.0 → 1.17.0

package/dist/transport/calculate/index.js

@@ -0,0 +1,2 @@
+export * from "./dwellTime.js";
+export * from "./transitTime.js";

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

@@ -0,0 +1,53 @@
+/**
+ * Add a transit duration to a departure and return the arrival, in the departure's own zone.
+ *
+ * The first of the three shared transport operations: a leg is a departure plus how long it
+ * takes. Every mode publishes it that way, and every mode gets the same thing wrong — a leg
+ * that crosses a DST transition is a fixed number of *elapsed* hours, not a wall-clock
+ * interval, so the local arrival time reflects the shift.
+ *
+ * - **Transit time is exact time.** Hours, minutes, seconds and fractions are added as elapsed
+ *   time, and a day component means 24 hours, exactly. That is TC39 Temporal's rule:
+ *   `Duration.prototype.round` and `total` without a `relativeTo` treat a day as 24 hours and
+ *   require a `relativeTo` for weeks, months and years. A 26-hour leg that starts the evening
+ *   before a spring-forward arrives at a wall time one hour later than a wall-clock reading would
+ *   suggest, because that is when the vessel, train or aircraft actually gets there.
+ * - **Calendar units are refused.** A `duration` with years, months or weeks returns `""`: no
+ *   leg takes "a month" in a sense that time arithmetic can fix without a reference point, and
+ *   Temporal will not add them to an instant either. Scheduled connections that are dated rather
+ *   than timed belong to `scheduleDelivery`.
+ * - **The departure's zone is preserved.** A bracketed IANA zone (`…-05:00[America/New_York]`)
+ *   stays that zone, so the arrival's offset is whatever is in force there at arrival. A `Z`
+ *   instant returns a `Z` instant; an offset-only instant keeps its offset, written exactly as
+ *   the departure wrote it, sub-minute offsets such as `+05:30:15` included (an offset is not a
+ *   zone, so nothing else can be inferred from it — see `toOffsetInstant`). A bracketed zone
+ *   that does not exist, or that contradicts its offset, is rejected as `isValidZonedDateTime`
+ *   rejects it; it does not fall back to the offset.
+ * - RFC 9557 annotations are read as `Temporal.Instant.from` reads them: a bracket without `=`
+ *   is a time zone, and a `key=value` bracket with an unknown key is ignored when elective and
+ *   rejected when critical (`[!…]`). A calendar on a departure without a zone is accepted and
+ *   changes nothing, since an instant has no calendar; a zoned departure's calendar must be ISO,
+ *   as `isValidZonedDateTime` requires.
+ * - A negative duration is allowed and moves backwards; that is how a departure is recovered
+ *   from an arrival.
+ * - Returns `""` when `departure` is not a zoned datetime or instant string, or `duration` is
+ *   not an ISO 8601 duration.
+ *
+ * @param departure ISO 8601 zoned datetime (bracketed zone) or instant string (`Z` or offset)
+ * @param duration ISO 8601 duration of the leg; time units and 24-hour days only
+ * @returns the arrival in the departure's zone or offset form, or "" on invalid input
+ *
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "PT2H30M") // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H") // "2024-03-10T04:00:00-04:00[America/New_York]" (four elapsed hours across the spring-forward, so the wall clock reads 04:00, not 03:00)
+ * @example transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D") // "2024-03-10T13:00:00-04:00[America/New_York]" (a day is 24 elapsed hours, not "the same wall time tomorrow")
+ * @example transitTime("2024-06-15T10:00:00Z", "PT36H") // "2024-06-16T22:00:00Z"
+ * @example transitTime("2024-06-15T10:00:00+09:00", "PT1H") // "2024-06-15T11:00:00+09:00" (an offset stays an offset)
+ * @example transitTime("2024-06-15T10:00:00+05:30:15", "PT1H") // "2024-06-15T11:00:00+05:30:15" (a sub-minute offset is kept as written)
+ * @example transitTime("2024-06-15T10:00:00Z[foo=bar]", "PT1H") // "2024-06-15T11:00:00Z" (an elective unknown annotation is ignored)
+ * @example transitTime("2024-06-15T12:30:00-04:00[America/New_York]", "-PT2H30M") // "2024-06-15T10:00:00-04:00[America/New_York]"
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "P1M") // "" (calendar units need a reference point)
+ * @example transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H") // "" (New York is -04:00 in June: the offset contradicts the zone)
+ * @example transitTime("2024-06-15T10:00:00", "PT2H") // "" (no zone and no offset: not a moment)
+ * @example transitTime("2024-06-15T10:00:00Z", "2 hours") // ""
+ */
+export declare function transitTime(departure: string, duration: string): string;

package/dist/transport/calculate/transitTime.js

@@ -0,0 +1,118 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { EXTENDED_UTC_OFFSET, TIME_ZONE_ANNOTATION, utcOffsetStringNanoseconds, wallClockAtOffset, zonedDateTimeFrom, } from "../../internal/index.js";
+import { isValidDuration } from "../../duration/validate/isValidDuration.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidZonedDateTime } from "../../zoned/validate/isValidZonedDateTime.js";
+/**
+ * Trailing `Z` or extended offset of an instant string, before any annotation. The offset grammar
+ * is `isValidInstant`'s own (`EXTENDED_UTC_OFFSET`), so every offset it accepts, `,` fractions
+ * included, is captured as written.
+ */
+const trailingOffset = new RegExp(`(Z|${EXTENDED_UTC_OFFSET})(?:\\[[^\\]]*\\])*$`);
+/**
+ * A time-zone annotation anywhere in the string (`TIME_ZONE_ANNOTATION`). Every `key=value`
+ * bracket is a tagged annotation, which `isValidInstant` already decides.
+ */
+const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
+/**
+ * Add a transit duration to a departure and return the arrival, in the departure's own zone.
+ *
+ * The first of the three shared transport operations: a leg is a departure plus how long it
+ * takes. Every mode publishes it that way, and every mode gets the same thing wrong — a leg
+ * that crosses a DST transition is a fixed number of *elapsed* hours, not a wall-clock
+ * interval, so the local arrival time reflects the shift.
+ *
+ * - **Transit time is exact time.** Hours, minutes, seconds and fractions are added as elapsed
+ *   time, and a day component means 24 hours, exactly. That is TC39 Temporal's rule:
+ *   `Duration.prototype.round` and `total` without a `relativeTo` treat a day as 24 hours and
+ *   require a `relativeTo` for weeks, months and years. A 26-hour leg that starts the evening
+ *   before a spring-forward arrives at a wall time one hour later than a wall-clock reading would
+ *   suggest, because that is when the vessel, train or aircraft actually gets there.
+ * - **Calendar units are refused.** A `duration` with years, months or weeks returns `""`: no
+ *   leg takes "a month" in a sense that time arithmetic can fix without a reference point, and
+ *   Temporal will not add them to an instant either. Scheduled connections that are dated rather
+ *   than timed belong to `scheduleDelivery`.
+ * - **The departure's zone is preserved.** A bracketed IANA zone (`…-05:00[America/New_York]`)
+ *   stays that zone, so the arrival's offset is whatever is in force there at arrival. A `Z`
+ *   instant returns a `Z` instant; an offset-only instant keeps its offset, written exactly as
+ *   the departure wrote it, sub-minute offsets such as `+05:30:15` included (an offset is not a
+ *   zone, so nothing else can be inferred from it — see `toOffsetInstant`). A bracketed zone
+ *   that does not exist, or that contradicts its offset, is rejected as `isValidZonedDateTime`
+ *   rejects it; it does not fall back to the offset.
+ * - RFC 9557 annotations are read as `Temporal.Instant.from` reads them: a bracket without `=`
+ *   is a time zone, and a `key=value` bracket with an unknown key is ignored when elective and
+ *   rejected when critical (`[!…]`). A calendar on a departure without a zone is accepted and
+ *   changes nothing, since an instant has no calendar; a zoned departure's calendar must be ISO,
+ *   as `isValidZonedDateTime` requires.
+ * - A negative duration is allowed and moves backwards; that is how a departure is recovered
+ *   from an arrival.
+ * - Returns `""` when `departure` is not a zoned datetime or instant string, or `duration` is
+ *   not an ISO 8601 duration.
+ *
+ * @param departure ISO 8601 zoned datetime (bracketed zone) or instant string (`Z` or offset)
+ * @param duration ISO 8601 duration of the leg; time units and 24-hour days only
+ * @returns the arrival in the departure's zone or offset form, or "" on invalid input
+ *
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "PT2H30M") // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H") // "2024-03-10T04:00:00-04:00[America/New_York]" (four elapsed hours across the spring-forward, so the wall clock reads 04:00, not 03:00)
+ * @example transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D") // "2024-03-10T13:00:00-04:00[America/New_York]" (a day is 24 elapsed hours, not "the same wall time tomorrow")
+ * @example transitTime("2024-06-15T10:00:00Z", "PT36H") // "2024-06-16T22:00:00Z"
+ * @example transitTime("2024-06-15T10:00:00+09:00", "PT1H") // "2024-06-15T11:00:00+09:00" (an offset stays an offset)
+ * @example transitTime("2024-06-15T10:00:00+05:30:15", "PT1H") // "2024-06-15T11:00:00+05:30:15" (a sub-minute offset is kept as written)
+ * @example transitTime("2024-06-15T10:00:00Z[foo=bar]", "PT1H") // "2024-06-15T11:00:00Z" (an elective unknown annotation is ignored)
+ * @example transitTime("2024-06-15T12:30:00-04:00[America/New_York]", "-PT2H30M") // "2024-06-15T10:00:00-04:00[America/New_York]"
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "P1M") // "" (calendar units need a reference point)
+ * @example transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H") // "" (New York is -04:00 in June: the offset contradicts the zone)
+ * @example transitTime("2024-06-15T10:00:00", "PT2H") // "" (no zone and no offset: not a moment)
+ * @example transitTime("2024-06-15T10:00:00Z", "2 hours") // ""
+ */
+export function transitTime(departure, duration) {
+    // A non-string would reach the regex tests below, which coerce it: a throwing `toString`, a
+    // Symbol or a hostile Proxy would escape. Refuse it before any read.
+    if (typeof departure !== "string" || typeof duration !== "string") {
+        return "";
+    }
+    try {
+        return addLeg(departure, duration);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}
+/** `transitTime` for two strings, without the guard. */
+function addLeg(departure, duration) {
+    if (!isValidDuration(duration)) {
+        return "";
+    }
+    const zoned = isValidZonedDateTime(departure);
+    // A string that names a zone must name a real one that agrees with its offset; only a string
+    // that names none may fall back to the instant path.
+    if (!zoned &&
+        (zoneAnnotation.test(departure) || !isValidInstant(departure))) {
+        return "";
+    }
+    try {
+        const parsed = Temporal.Duration.from(duration);
+        if (parsed.years !== 0 || parsed.months !== 0 || parsed.weeks !== 0) {
+            return "";
+        }
+        // Days become 24 exact hours; every remaining unit is already exact time.
+        const exact = parsed.round({ largestUnit: "hours" });
+        if (zoned) {
+            return zonedDateTimeFrom(departure).add(exact).toString();
+        }
+        const arrival = Temporal.Instant.from(departure).add(exact);
+        const offset = trailingOffset.exec(departure)?.[1] ?? "Z";
+        if (offset === "Z") {
+            return arrival.toString();
+        }
+        // The arrival's wall clock in the departure's own offset, written with that offset's text.
+        const wall = wallClockAtOffset(arrival, utcOffsetStringNanoseconds(offset));
+        return `${wall.toString()}${offset}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/transport/convert/etaAtZone.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Render an arrival instant as local time in the zone where it will be read.
+ *
+ * Schedules are computed in UTC and displayed where the cargo lands. The zone is the caller's
+ * fact: GMT does not resolve a port, airport, terminal or station code to a timezone, and
+ * takes an IANA identifier instead (see the parked registries note in the epic's painpoints).
+ *
+ * - `arrivalUtc` is any instant `isValidInstant` accepts — `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in the input is not the zone the
+ *   result is rendered in, `targetZone` is.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one wall
+ *   time in any zone, so the `disambiguation` vocabulary of `resolveLocal` does not apply here.
+ *   On a fall-back night two moments an hour apart print the same wall time with different
+ *   offsets, and the offset in the result is what tells them apart; on a spring-forward night
+ *   the skipped hour simply never appears. That is also why the result carries its offset and
+ *   zone rather than a bare wall time.
+ * - Returns a zoned ISO 8601 string, `Temporal.ZonedDateTime.prototype.toString()`'s form:
+ *   wall time, offset, bracketed zone.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+09:00"`, which renders with the offset as its zone.
+ *   A fixed offset is a legitimate rendering choice for a ship's log (MAR-18); it is not a place.
+ * - Returns `""` when the instant or the zone is invalid.
+ *
+ * @param arrivalUtc ISO 8601 instant string of the arrival
+ * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @returns zoned ISO 8601 string of the local arrival, or "" on invalid input
+ *
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"
+ * @example etaAtZone("2024-06-15T12:30:00Z", "America/Los_Angeles") // "2024-06-15T05:30:00-07:00[America/Los_Angeles]"
+ * @example etaAtZone("2024-06-15T12:30:00+02:00", "Pacific/Apia") // "2024-06-15T23:30:00+13:00[Pacific/Apia]" (the offset fixes the instant; the zone renders it)
+ * @example etaAtZone("2024-11-03T05:30:00Z", "America/New_York") // "2024-11-03T01:30:00-04:00[America/New_York]" (the first 01:30 of the fall-back night)
+ * @example etaAtZone("2024-11-03T06:30:00Z", "America/New_York") // "2024-11-03T01:30:00-05:00[America/New_York]" (the second; the offset tells them apart)
+ * @example etaAtZone("2024-06-15T12:30:00", "Asia/Tokyo") // "" (no offset designator: not a moment)
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokio") // ""
+ */
+export declare function etaAtZone(arrivalUtc: string, targetZone: string): string;

package/dist/transport/convert/etaAtZone.js

@@ -0,0 +1,53 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
+/**
+ * Render an arrival instant as local time in the zone where it will be read.
+ *
+ * Schedules are computed in UTC and displayed where the cargo lands. The zone is the caller's
+ * fact: GMT does not resolve a port, airport, terminal or station code to a timezone, and
+ * takes an IANA identifier instead (see the parked registries note in the epic's painpoints).
+ *
+ * - `arrivalUtc` is any instant `isValidInstant` accepts — `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in the input is not the zone the
+ *   result is rendered in, `targetZone` is.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one wall
+ *   time in any zone, so the `disambiguation` vocabulary of `resolveLocal` does not apply here.
+ *   On a fall-back night two moments an hour apart print the same wall time with different
+ *   offsets, and the offset in the result is what tells them apart; on a spring-forward night
+ *   the skipped hour simply never appears. That is also why the result carries its offset and
+ *   zone rather than a bare wall time.
+ * - Returns a zoned ISO 8601 string, `Temporal.ZonedDateTime.prototype.toString()`'s form:
+ *   wall time, offset, bracketed zone.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+09:00"`, which renders with the offset as its zone.
+ *   A fixed offset is a legitimate rendering choice for a ship's log (MAR-18); it is not a place.
+ * - Returns `""` when the instant or the zone is invalid.
+ *
+ * @param arrivalUtc ISO 8601 instant string of the arrival
+ * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @returns zoned ISO 8601 string of the local arrival, or "" on invalid input
+ *
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"
+ * @example etaAtZone("2024-06-15T12:30:00Z", "America/Los_Angeles") // "2024-06-15T05:30:00-07:00[America/Los_Angeles]"
+ * @example etaAtZone("2024-06-15T12:30:00+02:00", "Pacific/Apia") // "2024-06-15T23:30:00+13:00[Pacific/Apia]" (the offset fixes the instant; the zone renders it)
+ * @example etaAtZone("2024-11-03T05:30:00Z", "America/New_York") // "2024-11-03T01:30:00-04:00[America/New_York]" (the first 01:30 of the fall-back night)
+ * @example etaAtZone("2024-11-03T06:30:00Z", "America/New_York") // "2024-11-03T01:30:00-05:00[America/New_York]" (the second; the offset tells them apart)
+ * @example etaAtZone("2024-06-15T12:30:00", "Asia/Tokyo") // "" (no offset designator: not a moment)
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokio") // ""
+ */
+export function etaAtZone(arrivalUtc, targetZone) {
+    try {
+        if (!isValidInstant(arrivalUtc) || !isValidTimeZone(targetZone)) {
+            return "";
+        }
+        return Temporal.Instant.from(arrivalUtc)
+            .toZonedDateTimeISO(targetZone)
+            .toString();
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

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

package/dist/transport/convert/index.js

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

package/dist/transport/index.d.ts

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

package/dist/transport/index.js

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

package/dist/types/business-calendar.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A jurisdiction's working week: which weekdays are weekend, which dates are holidays, and
+ * which locality the answer is for.
+ *
+ * - `weekend` is ISO weekday numbers, 1 (Monday) through 7 (Sunday). It is explicit because
+ *   Saturday–Sunday is not universal: much of the Middle East is Friday–Saturday (`[5, 6]`),
+ *   and some markets keep a one-day weekend (`[7]`). `[]` means no weekly closure at all.
+ *   Duplicates are ignored; all seven days being weekend leaves no business day and is invalid.
+ * - `holidays` is ISO PlainDate strings (`"2024-07-04"`), never datetimes. Order does not
+ *   matter and duplicates are ignored. GMT bundles no holiday table — holiday data is
+ *   jurisdictional, changes annually and sometimes with days of notice, so the caller supplies
+ *   it. No exchange or currency calendar ships either; an opt-in data subpath for them is
+ *   planned, not published.
+ * - `timeZone` is an IANA identifier recording which locality the calendar describes. The
+ *   business-day functions never read it: they take and return local dates, so the answer is
+ *   the same whatever it says. It is what a caller holding an *instant* needs, to reduce that
+ *   instant to a local date first — with `floorToZone` or `getZonedDateTimeFields` — before
+ *   asking a business-day question.
+ *
+ * Narrow a candidate with `isValidBusinessCalendar`. Compose two jurisdictions' calendars with
+ * `mergeCalendars`.
+ */
+export type BusinessCalendar = {
+    weekend: number[];
+    holidays: string[];
+    timeZone: string;
+};

package/dist/types/calendar-system.d.ts

@@ -1 +1,9 @@
-export type CalendarSystem = "gregorian" | "hebrew" | "islamic-civil" | "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" | "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic";
+/**
+ * A calendar GMT's calendar functions support, named by its canonical calendar id: the CLDR
+ * `common/bcp47/calendar.xml` type that Temporal's `CanonicalizeCalendar` returns, and that
+ * RFC 9557's `[u-ca=<id>]` annotation carries.
+ *
+ * The set is `"iso8601"` plus the rows of the Intl Era and Month Code proposal's
+ * `table-calendar-types` that GMT supports; `"chinese"` and `"dangi"` are not supported.
+ */
+export type CalendarSystem = "iso8601" | "gregory" | "hebrew" | "islamic-civil" | "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" | "indian" | "ethiopic" | "ethioaa" | "coptic";

package/dist/types/fiscal-calendar.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Week-per-period shape of a 52/53-week fiscal year, one entry per month of a quarter.
+ *
+ * - `"4-5-4"` — the NRF retail calendar, the US retail standard.
+ * - `"4-4-5"` — the longer month falls at the end of the quarter.
+ * - `"5-4-4"` — the longer month falls at the start of the quarter.
+ *
+ * Narrow a candidate — a pattern out of config, an env var or a form — with
+ * `isValidFiscalPattern`.
+ */
+export type FiscalPattern = "4-5-4" | "4-4-5" | "5-4-4";
+/** Caller-supplied 52/53-week fiscal calendar. GMT bundles none. */
+export interface FiscalCalendar {
+    /** Weeks per period within each quarter. */
+    pattern: FiscalPattern;
+    /**
+     * The year-end rule, stated as one ISO date: fiscal years end on this date's **weekday**,
+     * on the occurrence nearest this date's **month and day**. For the NRF retail calendar —
+     * "the Saturday nearest to January 31" — that is `"2026-01-31"`.
+     */
+    yearEndsOn: string;
+}

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

@@ -0,0 +1,34 @@
+import type { BusinessCalendar } from "./business-calendar.js";
+/**
+ * How days are counted: every local calendar day, or only the terminal's working days. Used for
+ * free time (`basis`) and, separately, for the days charged after it (`chargeBasis`), because
+ * published tariffs commonly count the two differently.
+ */
+export type FreeTimeBasis = "calendar" | "working";
+/**
+ * Whether the day of the triggering event is free day one (`"eventDay"`), or free time starts
+ * on the following counted day (`"nextDay"`). The two conventions differ by one full day of
+ * charges, so no function defaults it.
+ */
+export type FreeTimeFirstDay = "eventDay" | "nextDay";
+/**
+ * The tariff terms a free-time count needs. Free time is set by carrier, lane, trade and service
+ * contract, never by port, so every term is a parameter and no counting term has a default.
+ *
+ * - `basis`: `"calendar"` counts every local day, so a weekend burns two free days while the
+ *   terminal is shut; `"working"` counts only the days `calendar` marks as working, and the
+ *   clock does not run on weekends or holidays.
+ * - `timeZone`: the IANA identifier of the terminal, depot or yard whose local midnight ends a
+ *   day. GMT does not resolve a port or terminal code to a zone. A fixed offset such as
+ *   `"+02:00"` is accepted, as `isValidTimeZone` accepts it, but observes no DST.
+ * - `firstDay`: `"eventDay"` or `"nextDay"`, see `FreeTimeFirstDay`.
+ * - `calendar`: the terminal's `BusinessCalendar`, required when `basis` is `"working"` and not
+ *   read when it is `"calendar"`. Its `timeZone` field is not read either, as the business-day
+ *   functions never read it: `timeZone` above is the counting zone.
+ */
+export type FreeTimeOptions = {
+    basis: FreeTimeBasis;
+    timeZone: string;
+    firstDay: FreeTimeFirstDay;
+    calendar?: BusinessCalendar;
+};

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./business-calendar.js";
 export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
@@ -11,7 +12,10 @@ export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
 export * from "./duration-unit.js";
+export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./free-time-options.js";
+export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";
 export * from "./overflow.js";
@@ -21,9 +25,12 @@ export * from "./relative-rounding-method.js";
 export * from "./relative-time-options.js";
 export * from "./relative-time-unit.js";
 export * from "./relative-unit.js";
+export * from "./roll-convention.js";
 export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
+export * from "./zone-bucket-unit.js";
+export type { UnixUnit } from "../unix/validate/isValidUnixUnit.js";

package/dist/types/index.js

@@ -1,3 +1,4 @@
+export * from "./business-calendar.js";
 export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
@@ -11,7 +12,10 @@ export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
 export * from "./duration-unit.js";
+export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./free-time-options.js";
+export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";
 export * from "./overflow.js";
@@ -21,9 +25,11 @@ export * from "./relative-rounding-method.js";
 export * from "./relative-time-options.js";
 export * from "./relative-time-unit.js";
 export * from "./relative-unit.js";
+export * from "./roll-convention.js";
 export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
+export * from "./zone-bucket-unit.js";

package/dist/types/interval.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A span of time between two ISO 8601 instant strings, half-open: `[start, end)`.
+ *
+ * - An instant `t` is inside when `start ≤ t < end` (EWD831; SQL:2011 closed-open `PERIOD`;
+ *   RFC 5545 `DTEND` is non-inclusive). Intervals that touch share no instant.
+ * - Both endpoints are instants: an offset (`Z`, `±HH:MM`) is required, a bracketed IANA zone is
+ *   optional, and the two may name different zones. Leap seconds are rejected; a `[u-ca=...]`
+ *   annotation is ignored, as `Temporal.Instant.from` ignores it.
+ * - `start === end` (as instants) is a valid, empty interval: it has a position but contains no
+ *   instant. `start` after `end` is invalid.
+ *
+ * Narrow a candidate with `isValidInterval`. Used by the `interval/` namespace; the older
+ * `plain|utc|zoned|unix/interval` functions take positional strings and a different model.
+ */
+export type Interval = {
+    start: string;
+    end: string;
+};

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

@@ -2,4 +2,4 @@
  * Units extractable from the current system local time via `getNowUnit`.
  * Defined as `DateTimeUnit | "dayOfWeek"`.
  */
-export type NowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";
+export type NowUnit = import("@js-temporal/polyfill").Temporal.SmallestUnit<import("./date-time-unit.js").DateTimeUnit> | "dayOfWeek";

package/dist/types/roll-convention.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What `rollDate` does when a date lands on a non-business day.
+ *
+ * Every industry has an answer and they differ, so the convention is always explicit.
+ *
+ * No TC39, ECMA or RFC standard governs these, so each cites the domain text that does.
+ * `"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), (ii)
+ * and (iii): "if 'Following' is specified …", "if 'Modified Following' or 'Modified' is
+ * specified …" and "if 'Preceding' is specified, that date will be the first preceding day
+ * that is a Business Day". §4.12(a) defines no Modified Preceding: `"modifiedPreceding"` is
+ * 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`.
+ *
+ * - `"following"` — forward to the next business day, or the date itself if it is one.
+ * - `"modifiedFollowing"` — forward, unless that crosses into the next month, then backward.
+ * - `"preceding"` — backward to the previous business day, or the date itself if it is one.
+ * - `"modifiedPreceding"` — backward, unless that crosses into the previous month, then forward.
+ * - `"endOfMonth"` — the last business day of the date's own month, wherever in the month the
+ *   date falls; it leaves the month only if that whole month is closed. **GMT's own, not
+ *   ISDA's**, and not the industry "EOM rule" — that is a *schedule* rule, holding every date
+ *   in a schedule to its month's last day once the anchor is one. Build that rule from this
+ *   one by testing the anchor for month-end yourself and applying `"endOfMonth"` to the
+ *   unadjusted target date.
+ * - `"none"` — return the date unadjusted, business day or not.
+ *
+ * Narrow a candidate with `isValidRollConvention`.
+ */
+export type RollConvention = "following" | "modifiedFollowing" | "preceding" | "modifiedPreceding" | "endOfMonth" | "none";

package/dist/types/utc-now-unit.d.ts

@@ -2,4 +2,4 @@
  * Units extractable from the current UTC instant via `getUtcNowUnit`.
  * Defined as `DateTimeUnit | "dayOfWeek"`.
  */
-export type UtcNowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";
+export type UtcNowUnit = import("@js-temporal/polyfill").Temporal.SmallestUnit<import("./date-time-unit.js").DateTimeUnit> | "dayOfWeek";

package/dist/types/zone-bucket-unit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Units `floorToZone` and `bucketRange` floor an instant to, in a target time zone.
+ *
+ * Narrower than `DateTimeUnit` on purpose: these are the boundaries a calendar in a zone
+ * actually has. Sub-hour units need no zone (a minute boundary is the same instant
+ * everywhere a zone's offset is a whole minute), and `year` is left out because the fiscal
+ * and calendar year questions are `getFiscalPeriod`'s and `getQuarter`'s.
+ *
+ * Narrow a candidate unit with `isValidZoneBucketUnit`.
+ */
+export type ZoneBucketUnit = "hour" | "day" | "week" | "month";

package/dist/unix/calculate/addUnix.d.ts

@@ -1,25 +1,31 @@
 import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Add a temporal amount to a Unix epoch value and return the resulting epoch.
  *
  * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
  * - Validates duration units and values.
+ * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
  * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
  * @returns Unix epoch number after addition, or null on invalid input
  *
  * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
  * @example addUnix(1706659200, { days: 1 }, { epochUnit: "seconds" }) // 1706745600
  * @example addUnix(-86400000, { days: 1 }) // 0 (Dec 31 1969 + 1 day = Jan 1 1970)
+ * @example addUnix(1.5, { days: 1 }) // null (not an integer epoch)
+ * @example addUnix("1706659200000", { days: 1 }) // 1706745600000 (digit string)
+ * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
  */
-export declare function addUnix(value: number, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function addUnix(value: number | string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
     overflow?: Overflow;
 }): number | null;