@northguild/gmt 1.17.0 → 1.19.0

package/dist/transport/compare/isPastCutoff.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { instantFrom } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/**
+ * Report whether a cut-off has passed.
+ *
+ * The window to meet a cut-off is half-open, `[…, cutoff)`: at the cut-off instant itself it
+ * has closed, so `now` equal to `cutoff` is past. This matches the half-open rule GMT's
+ * intervals follow, and `timeToCutoff`, which is `PT0S` there.
+ *
+ * - Both arguments are exact: an instant (`Z`/offset) or a zoned string, as `cutoffAt`
+ *   returns one. They are compared as instants, so the zone each is written in does not
+ *   matter, and the two passes of a repeated hour are told apart by their offsets.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a cut-off `cutoffAt` wrote is the instant it
+ *   computed, except a wall time repeated inside a sub-minute offset change, which reads as
+ *   its first pass (see `isValidInstant`). Otherwise the bracket is not checked: a zone that does not exist, or that
+ *   disagrees with the offset, changes nothing.
+ * - `now` is the caller's: GMT does not read the clock here, so the answer is reproducible.
+ * - Returns `false` on invalid input, including `cutoffAt`'s `""` sentinel — which reads as
+ *   "not past". Check the cut-off is not `""` before trusting a `false`.
+ *
+ * @param now ISO 8601 instant or zoned datetime string of the moment asked about
+ * @param cutoff ISO 8601 instant or zoned datetime string of the cut-off
+ * @returns true when now is at or after the cut-off, false otherwise or on invalid input
+ *
+ * @example isPastCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // true
+ * @example isPastCutoff("2024-06-12T14:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // false
+ * @example isPastCutoff("2024-06-12T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // true (at the cut-off, the window has closed)
+ * @example isPastCutoff("2024-11-03T01:30:00-05:00[America/New_York]", "2024-11-03T01:30:00-04:00[America/New_York]") // true (the second 01:30 is an hour after the first)
+ * @example isPastCutoff("2024-06-12T16:00:00", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // false (a zoneless now is not a moment)
+ * @example isPastCutoff("2024-06-12T16:00:00Z", "") // false
+ */
+export function isPastCutoff(now, cutoff) {
+    try {
+        if (!isValidInstant(now) || !isValidInstant(cutoff)) {
+            return false;
+        }
+        return Temporal.Instant.compare(instantFrom(now), instantFrom(cutoff)) >= 0;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/transport/compare/scheduleDeviation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Measure how far an actual time is from its plan: positive when late, negative when early.
+ *
+ * Every mode publishes a plan and records what happened, and measures the gap the same way. This
+ * is that gap; `classifyPunctuality` judges it against a tolerance.
+ *
+ * - **Exact elapsed time**, as an ISO 8601 duration with hours as the largest unit, so the value
+ *   never depends on a calendar or a wall clock. A delay across a fall-back night is `PT1H`,
+ *   never the `PT0S` a wall-clock subtraction reads; across a spring-forward it is `PT1H`, never
+ *   `PT2H`. Two days late is `PT48H`, not `P2D`.
+ * - **Signed:** `actual` after `planned` is positive (late), before it negative (`"-PT5M"`,
+ *   early), and equal is `"PT0S"`.
+ * - Both arguments are exact: an instant (`Z`/offset) or a zoned string. The zone each is written
+ *   in does not matter. To show a schedule's local time, use `etaAtZone`.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** Temporal
+ *   writes a zone's offset rounded to the minute, so an offset written to the minute that is the
+ *   bracketed zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names
+ *   the instant the zone gives, as `Temporal.ZonedDateTime.from` reads it. A zoned string GMT
+ *   wrote is therefore measured from the instant it was written for, except a wall time
+ *   repeated inside a sub-minute offset change, which reads as its first pass
+ *   (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`; see `isValidInstant`). Otherwise the bracket is
+ *   not checked: a zone that does not exist, or that disagrees with the offset, changes nothing.
+ * - Returns `""` on invalid input, including a zoneless wall time, which is not a moment.
+ *
+ * @param planned ISO 8601 instant or zoned datetime string of the planned time
+ * @param actual ISO 8601 instant or zoned datetime string of the actual (or compared) time
+ * @returns ISO 8601 duration from planned to actual, negative when early, or "" on invalid input
+ *
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z") // "PT14M"
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T09:55:00Z") // "-PT5M" (five minutes early)
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z") // "PT0S"
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-17T11:30:00Z") // "PT49H30M" (hours, never days)
+ * @example scheduleDeviation("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]") // "PT1H" (the same wall time, one hour later across the fall-back)
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T12:14:00+02:00[Europe/Amsterdam]") // "PT14M" (the zone it is written in does not matter)
+ * @example scheduleDeviation("2024-06-15T10:00:00", "2024-06-15T10:14:00Z") // "" (a zoneless plan is not a moment)
+ */
+export declare function scheduleDeviation(planned: string, actual: string): string;

package/dist/transport/compare/scheduleDeviation.js

@@ -0,0 +1,53 @@
+import { instantFrom } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/**
+ * Measure how far an actual time is from its plan: positive when late, negative when early.
+ *
+ * Every mode publishes a plan and records what happened, and measures the gap the same way. This
+ * is that gap; `classifyPunctuality` judges it against a tolerance.
+ *
+ * - **Exact elapsed time**, as an ISO 8601 duration with hours as the largest unit, so the value
+ *   never depends on a calendar or a wall clock. A delay across a fall-back night is `PT1H`,
+ *   never the `PT0S` a wall-clock subtraction reads; across a spring-forward it is `PT1H`, never
+ *   `PT2H`. Two days late is `PT48H`, not `P2D`.
+ * - **Signed:** `actual` after `planned` is positive (late), before it negative (`"-PT5M"`,
+ *   early), and equal is `"PT0S"`.
+ * - Both arguments are exact: an instant (`Z`/offset) or a zoned string. The zone each is written
+ *   in does not matter. To show a schedule's local time, use `etaAtZone`.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** Temporal
+ *   writes a zone's offset rounded to the minute, so an offset written to the minute that is the
+ *   bracketed zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names
+ *   the instant the zone gives, as `Temporal.ZonedDateTime.from` reads it. A zoned string GMT
+ *   wrote is therefore measured from the instant it was written for, except a wall time
+ *   repeated inside a sub-minute offset change, which reads as its first pass
+ *   (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`; see `isValidInstant`). Otherwise the bracket is
+ *   not checked: a zone that does not exist, or that disagrees with the offset, changes nothing.
+ * - Returns `""` on invalid input, including a zoneless wall time, which is not a moment.
+ *
+ * @param planned ISO 8601 instant or zoned datetime string of the planned time
+ * @param actual ISO 8601 instant or zoned datetime string of the actual (or compared) time
+ * @returns ISO 8601 duration from planned to actual, negative when early, or "" on invalid input
+ *
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z") // "PT14M"
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T09:55:00Z") // "-PT5M" (five minutes early)
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z") // "PT0S"
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-17T11:30:00Z") // "PT49H30M" (hours, never days)
+ * @example scheduleDeviation("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]") // "PT1H" (the same wall time, one hour later across the fall-back)
+ * @example scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T12:14:00+02:00[Europe/Amsterdam]") // "PT14M" (the zone it is written in does not matter)
+ * @example scheduleDeviation("2024-06-15T10:00:00", "2024-06-15T10:14:00Z") // "" (a zoneless plan is not a moment)
+ */
+export function scheduleDeviation(planned, actual) {
+    try {
+        if (!isValidInstant(planned) || !isValidInstant(actual)) {
+            return "";
+        }
+        return instantFrom(planned)
+            .until(instantFrom(actual), { largestUnit: "hours" })
+            .toString();
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/transport/compare/timeToCutoff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Measure the time left until a cut-off, negative once it has passed.
+ *
+ * - Exact elapsed time as an ISO 8601 duration with hours as the largest unit, so the value
+ *   never depends on a calendar: across a fall-back night, 17:00 to 17:00 the next day is
+ *   `PT25H`. It is `PT0S` at the cut-off itself, where `isPastCutoff` turns `true`.
+ * - Negative (`"-PT1H"`) once `now` is after the cut-off: how late it is.
+ * - Both arguments are exact: an instant (`Z`/offset) or a zoned string, as `cutoffAt`
+ *   returns one. The zone each is written in does not matter.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a cut-off `cutoffAt` wrote is the instant it
+ *   computed, except a wall time repeated inside a sub-minute offset change, which reads as
+ *   its first pass (see `isValidInstant`). Otherwise the bracket is not checked: a zone that does not exist, or that
+ *   disagrees with the offset, changes nothing.
+ * - `now` is the caller's: GMT does not read the clock here.
+ * - Returns `""` on invalid input, including `cutoffAt`'s `""` sentinel.
+ *
+ * @param now ISO 8601 instant or zoned datetime string of the moment asked about
+ * @param cutoff ISO 8601 instant or zoned datetime string of the cut-off
+ * @returns ISO 8601 duration from now to the cut-off, negative after it, or "" on invalid input
+ *
+ * @example timeToCutoff("2024-06-10T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "PT48H"
+ * @example timeToCutoff("2024-06-12T13:30:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "PT1H30M"
+ * @example timeToCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "-PT1H" (an hour past the cut-off)
+ * @example timeToCutoff("2024-06-12T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "PT0S"
+ * @example timeToCutoff("2024-11-02T17:00:00-04:00[America/New_York]", "2024-11-03T17:00:00-05:00[America/New_York]") // "PT25H" (across the fall-back)
+ * @example timeToCutoff("2024-06-12T16:00:00Z", "") // ""
+ */
+export declare function timeToCutoff(now: string, cutoff: string): string;

package/dist/transport/compare/timeToCutoff.js

@@ -0,0 +1,47 @@
+import { instantFrom } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/**
+ * Measure the time left until a cut-off, negative once it has passed.
+ *
+ * - Exact elapsed time as an ISO 8601 duration with hours as the largest unit, so the value
+ *   never depends on a calendar: across a fall-back night, 17:00 to 17:00 the next day is
+ *   `PT25H`. It is `PT0S` at the cut-off itself, where `isPastCutoff` turns `true`.
+ * - Negative (`"-PT1H"`) once `now` is after the cut-off: how late it is.
+ * - Both arguments are exact: an instant (`Z`/offset) or a zoned string, as `cutoffAt`
+ *   returns one. The zone each is written in does not matter.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a cut-off `cutoffAt` wrote is the instant it
+ *   computed, except a wall time repeated inside a sub-minute offset change, which reads as
+ *   its first pass (see `isValidInstant`). Otherwise the bracket is not checked: a zone that does not exist, or that
+ *   disagrees with the offset, changes nothing.
+ * - `now` is the caller's: GMT does not read the clock here.
+ * - Returns `""` on invalid input, including `cutoffAt`'s `""` sentinel.
+ *
+ * @param now ISO 8601 instant or zoned datetime string of the moment asked about
+ * @param cutoff ISO 8601 instant or zoned datetime string of the cut-off
+ * @returns ISO 8601 duration from now to the cut-off, negative after it, or "" on invalid input
+ *
+ * @example timeToCutoff("2024-06-10T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "PT48H"
+ * @example timeToCutoff("2024-06-12T13:30:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "PT1H30M"
+ * @example timeToCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "-PT1H" (an hour past the cut-off)
+ * @example timeToCutoff("2024-06-12T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // "PT0S"
+ * @example timeToCutoff("2024-11-02T17:00:00-04:00[America/New_York]", "2024-11-03T17:00:00-05:00[America/New_York]") // "PT25H" (across the fall-back)
+ * @example timeToCutoff("2024-06-12T16:00:00Z", "") // ""
+ */
+export function timeToCutoff(now, cutoff) {
+    try {
+        if (!isValidInstant(now) || !isValidInstant(cutoff)) {
+            return "";
+        }
+        return instantFrom(now)
+            .until(instantFrom(cutoff), { largestUnit: "hours" })
+            .toString();
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -8,6 +8,13 @@
  * - `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.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so rendering this function's own result again gives
+ *   the same moment, except a wall time repeated inside a sub-minute offset change, which
+ *   reads as its first pass (see `isValidInstant`). A zone that does not exist, or that disagrees with the offset, is not
+ *   checked and changes nothing.
  * - **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
@@ -20,9 +27,14 @@
  *   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.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param arrivalUtc ISO 8601 instant string of the arrival
- * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts), for
+ *   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]"

package/dist/transport/convert/etaAtZone.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { instantFrom } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
 /**
@@ -11,6 +11,13 @@ import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
  * - `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.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so rendering this function's own result again gives
+ *   the same moment, except a wall time repeated inside a sub-minute offset change, which
+ *   reads as its first pass (see `isValidInstant`). A zone that does not exist, or that disagrees with the offset, is not
+ *   checked and changes nothing.
  * - **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
@@ -23,9 +30,14 @@ import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
  *   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.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param arrivalUtc ISO 8601 instant string of the arrival
- * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts), for
+ *   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]"
@@ -41,9 +53,7 @@ export function etaAtZone(arrivalUtc, targetZone) {
         if (!isValidInstant(arrivalUtc) || !isValidTimeZone(targetZone)) {
             return "";
         }
-        return Temporal.Instant.from(arrivalUtc)
-            .toZonedDateTimeISO(targetZone)
-            .toString();
+        return instantFrom(arrivalUtc).toZonedDateTimeISO(targetZone).toString();
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/transport/index.d.ts

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

package/dist/transport/index.js

@@ -1,4 +1,5 @@
 // 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 "./compare/index.js";
 export * from "./convert/index.js";

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

@@ -2,26 +2,32 @@
  * 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.
+ * 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.
  *
  * Narrow a candidate with `isValidBusinessCalendar`. Compose two jurisdictions' calendars with
  * `mergeCalendars`.
  */
 export type BusinessCalendar = {
+    /**
+     * The ISO weekday numbers closed every week, 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,
+     * duplicates are ignored, and all seven days leave no business day and are invalid.
+     */
     weekend: number[];
+    /**
+     * The dates closed in addition to the weekend, as ISO PlainDate strings (`"2024-07-04"`), never
+     * datetimes. Order does not matter and duplicates are ignored.
+     */
     holidays: string[];
+    /**
+     * The time zone recording which locality the calendar describes, an IANA name or a UTC offset to
+     * the minute (what `isValidTimeZone` accepts). It must be a valid zone, but the business-day
+     * functions never use it: they take and return local dates, so the answer is the same whatever it
+     * says. A caller holding an instant uses it to reduce that instant to a local date first, with
+     * `floorToZone` or `getZonedDateTimeFields`.
+     */
     timeZone: string;
 };

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

@@ -4,8 +4,20 @@
  * add domain-specific fields like `timeZone` or `epochUnit`.
  */
 export interface CalendarOptions {
-    /** Anchor point for the relative day comparison. */
+    /**
+     * The moment the day label is measured from, as an ISO string in the same form as the value
+     * being formatted. A value on the same calendar day reads "today", one on the next day
+     * "tomorrow".
+     *
+     * @defaultValue The current date and time.
+     */
     reference?: string;
-    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
-    timeStyle?: "short" | "medium" | "full";
+    /**
+     * The length of the time-of-day part, as the `timeStyle` of `Intl.DateTimeFormat`. `"short"`
+     * writes hours and minutes, `"medium"` adds seconds, `"long"` adds the short time zone name
+     * ("EDT") and `"full"` the long one ("Eastern Daylight Time"). Any other value returns `""`.
+     *
+     * @defaultValue `"short"`
+     */
+    timeStyle?: "short" | "medium" | "long" | "full";
 }

package/dist/types/date-cycle-field.d.ts

@@ -1 +1,6 @@
+/**
+ * A date field `cycleDate`, `cycleDateTime` and `cycleZoned` can step and wrap: `"year"`,
+ * `"month"` or `"day"`. Narrower than `DateUnit` on purpose: `"week"` is a unit, not a field a
+ * date can be set to with Temporal's `with()`.
+ */
 export type DateCycleField = "year" | "month" | "day";

package/dist/types/date-duration-unit.d.ts

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * A date field of an ISO 8601 duration, in the plural: `"years"`, `"months"`, `"weeks"` or
+ * `"days"`. It names the unit an amount of dates is given in or a date difference is measured in.
+ */
 export type DateDurationUnit = keyof Pick<Temporal.DurationLike, "years" | "months" | "weeks" | "days">;

package/dist/types/date-time-cycle-field.d.ts

@@ -1,3 +1,7 @@
 import type { DateCycleField } from "./date-cycle-field.js";
 import type { TimeCycleField } from "./time-cycle-field.js";
+/**
+ * A date or time field `cycleDateTime` and `cycleZoned` can step and wrap: any `DateCycleField`
+ * or `TimeCycleField`.
+ */
 export type DateTimeCycleField = DateCycleField | TimeCycleField;

package/dist/types/date-time-duration-units.d.ts

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Any field of an ISO 8601 duration, in the plural, from `"years"` down to `"nanoseconds"`. It
+ * names the unit an amount of time is given in or a difference is measured in.
+ */
 export type DateTimeDurationUnit = keyof Temporal.DurationLike;

package/dist/types/date-time-unit.d.ts

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * A date or time unit in the singular, from `"year"` down to `"nanosecond"`, as Temporal's
+ * rounding and difference options name units.
+ */
 export type DateTimeUnit = Temporal.TimeUnit | Temporal.DateUnit;

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

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * A date unit in the singular: `"year"`, `"month"`, `"week"` or `"day"`, as Temporal's rounding
+ * and difference options name units.
+ */
 export type DateUnit = Temporal.DateUnit;

package/dist/types/disambiguation.d.ts

@@ -1,2 +1,10 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * How a local wall time that a time zone's clock shows twice or never is resolved to an instant,
+ * as Temporal's `disambiguation` option (`Temporal.ZonedDateTime.from(item, { disambiguation })`).
+ *
+ * `"compatible"` takes the earlier instant of a repeated time and moves a skipped time forward by
+ * the length of the gap. `"earlier"` and `"later"` take that side in both cases, and `"reject"`
+ * accepts neither.
+ */
 export type Disambiguation = Temporal.ToInstantOptions["disambiguation"];

package/dist/types/duration-relative-to.d.ts

@@ -1,2 +1,10 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * The anchor a calendar-unit duration operation is measured from, as Temporal's `relativeTo`
+ * option takes it (`Duration.prototype.round`, `Duration.prototype.total`, `Duration.compare`).
+ *
+ * Years, months and weeks have no fixed length, so any operation touching them needs a starting
+ * point; an operation on days and time units alone does not. A string is an ISO 8601 date or
+ * date-time, or a zoned date-time with its time zone annotation.
+ */
 export type DurationRelativeTo = Temporal.PlainDateTime | Temporal.ZonedDateTime | Temporal.PlainDateTimeLike | Temporal.ZonedDateTimeLike | string;

package/dist/types/duration-string-options.d.ts

@@ -1,6 +1,34 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Precision options for the ISO 8601 duration string a `diff*AsDuration` function writes, passed
+ * to `Temporal.Duration.prototype.toString()`.
+ *
+ * They are kept apart from `RoundingOptions`, and two of them carry a `toString` prefix, because
+ * both sets have a smallest unit and a rounding mode with different Temporal types: one rounds
+ * the difference, the other the text written from it.
+ */
 export type DurationStringOptions = {
+    /**
+     * The smallest unit written in the string: `"second"`, `"millisecond"`, `"microsecond"` or
+     * `"nanosecond"`. It sets how many fractional-second digits appear and takes precedence over
+     * `fractionalSecondDigits`. `"minute"` is refused, as `Temporal.Duration` refuses it.
+     *
+     * @defaultValue None. The precision comes from `fractionalSecondDigits`.
+     */
     toStringSmallestUnit?: Temporal.ToStringPrecisionOptions["smallestUnit"];
+    /**
+     * The number of fractional-second digits written: `0` to `9` writes exactly that many, and
+     * `"auto"` writes as many as the duration needs, with no trailing zeros. It has no effect when
+     * `toStringSmallestUnit` is given.
+     *
+     * @defaultValue `"auto"`, Temporal's default.
+     */
     fractionalSecondDigits?: Temporal.ToStringPrecisionOptions["fractionalSecondDigits"];
+    /**
+     * How the duration is rounded when the precision asked for drops digits. `"trunc"` cuts them
+     * off; `"halfExpand"` rounds to the nearest value, a half going away from zero.
+     *
+     * @defaultValue `"trunc"`, Temporal's default.
+     */
     toStringRoundingMode?: Temporal.ToStringPrecisionOptions["roundingMode"];
 };