@northguild/gmt 1.17.0 → 1.18.0

package/dist/plain/format/formatDateTimeToParts.js

@@ -1,14 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { plainDateTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return the locale-formatted parts of a PlainDateTime.
  *
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`, `"literal"`.
@@ -26,8 +26,11 @@ import { isValidDateTime } from "../validate/index.js";
  *   zone field): a `timeZoneName` option is ignored, and a `"long"`/`"full"` `timeStyle` keeps its
  *   hour, minute and second and drops the zone, formatting as the locale's `"medium"` time. As in
  *   `Intl.DateTimeFormat`, `timeZoneName` together with `dateStyle`/`timeStyle` yields `[]`.
- * - Before the day period, `en-US` has used U+202F NARROW NO-BREAK SPACE since CLDR 42 (ICU 72), not
- *   an ordinary space; the examples write it as `"\u202f"` so the difference is visible.
+ * - The literal before the day period depends on the runtime. CLDR 42 (ICU 72) put U+202F NARROW
+ *   NO-BREAK SPACE there for `en-US`; Node 22 and 24 return it in the parts, and Node 26 returns
+ *   an ordinary space (U+0020) instead. Both were checked on those runtimes. The examples show the
+ *   Node 22 and 24 form, written as `"\u202f"` so the difference is visible. Treat the two
+ *   characters as equal when you compare parts.
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 a call with no field options returned only the date parts.
  *   Pass `{ year: "numeric", month: "numeric", day: "numeric" }` to keep that output.
@@ -62,9 +65,10 @@ export function formatDateTimeToParts(value, locale, options) {
         // PlainDateTime format may contain, so no zone field can appear.
         // Constructing with the caller's options first surfaces the TypeError or
         // RangeError Intl.DateTimeFormat raises for invalid ones.
-        new Intl.DateTimeFormat(locale, options);
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
         const epochMilliseconds = Temporal.PlainDateTime.from(value).toZonedDateTime("UTC").epochMilliseconds;
-        return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options ?? {}))
+        return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(read))
             .formatToParts(epochMilliseconds)
             .map((p) => ({ type: p.type, value: p.value }));
     }

package/dist/plain/format/formatDateToParts.d.ts

@@ -5,8 +5,7 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` is one of:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"literal"`.
@@ -22,6 +21,9 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   ignored. With both `dateStyle` and `timeStyle` the parts keep the date style and drop the
  *   `timeStyle` (the `Intl.DateTimeFormat` entry point, required ~any~), whereas the text sibling
  *   `formatDate` returns `""` (`PlainDate#toLocaleString`, required ~date~, is a TypeError).
+ * - The `formatZonedToParts` example below writes the literal before the day period as
+ *   `"\u202f"`, U+202F NARROW NO-BREAK SPACE, which Node 22 and 24 return; Node 26 returns an
+ *   ordinary space there (see `formatZonedToParts`).
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 time options leaked a UTC midnight and a `"UTC"` zone name
  *   into the parts. `formatZonedToParts` on the date at midnight UTC returns those parts.
@@ -44,6 +46,15 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  * @example formatDateToParts("2024-02-03", ["fr-FR", "en-US"]) // [{ type: "day", value: "03" }, { type: "literal", value: "/" }, …]
  */
 export declare function formatDateToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
+    /**
+     * The kind of part, named as ECMA-402 `Intl.DateTimeFormat.prototype.formatToParts` names it: a
+     * field such as `"year"`, `"month"` or `"day"`, or `"literal"` for the separator text between
+     * fields.
+     */
     type: string;
+    /**
+     * The text of the part in the requested locale, exactly as the formatter wrote it. Joining every
+     * `value` in array order gives the whole formatted text.
+     */
     value: string;
 }>;

package/dist/plain/format/formatDateToParts.js

@@ -1,14 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { plainDateFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidDate } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return the locale-formatted parts of a PlainDate.
  *
  * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
  *   `format`). A token pattern hard-codes field order and ships US ordering to
  *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order. See Decision 1 in
- *   `context/roadmap/issues/J.md`.
+ *   while the *locale* keeps control of order.
  * - Each part is `{ type, value }` where `type` is one of:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"literal"`.
@@ -24,6 +24,9 @@ import { isValidDate } from "../validate/index.js";
  *   ignored. With both `dateStyle` and `timeStyle` the parts keep the date style and drop the
  *   `timeStyle` (the `Intl.DateTimeFormat` entry point, required ~any~), whereas the text sibling
  *   `formatDate` returns `""` (`PlainDate#toLocaleString`, required ~date~, is a TypeError).
+ * - The `formatZonedToParts` example below writes the literal before the day period as
+ *   `"\u202f"`, U+202F NARROW NO-BREAK SPACE, which Node 22 and 24 return; Node 26 returns an
+ *   ordinary space there (see `formatZonedToParts`).
  * - Returns `[]` for invalid input.
  * - **Compatibility:** before 1.16.0 time options leaked a UTC midnight and a `"UTC"` zone name
  *   into the parts. `formatZonedToParts` on the date at midnight UTC returns those parts.
@@ -56,8 +59,9 @@ export function formatDateToParts(value, locale, options) {
         // PlainDate format may contain, so no time or zone field can appear.
         // Constructing with the caller's options first surfaces the TypeError or
         // RangeError Intl.DateTimeFormat raises for invalid ones.
-        new Intl.DateTimeFormat(locale, options);
-        const resolved = plainDateFormatOptions(options ?? {});
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
+        const resolved = plainDateFormatOptions(read);
         if (resolved === null) {
             return [];
         }

package/dist/plain/format/formatRelativeDate.d.ts

@@ -1,19 +1,32 @@
 import type { RelativeDateUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+/**
+ * Options for `formatRelativeDate`: the reference date, the display unit, the rounding and the
+ * wording.
+ */
 export interface FormatRelativeDateOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeDateUnit;
+    /**
+     * The unit the distance is written in, whatever its size: `"day"`, `"week"`, `"month"` or
+     * `"year"`, singular or plural. Any other value returns `""`, a time unit such as `"hour"`
+     * included: a date has no time, and Temporal throws RangeError for a unit outside the units of
+     * the type. Omitted, the unit is picked from the distance: day under 7 days, week under 28,
+     * month under 365 and year beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
+    largestUnit?: RelativeDateUnit | `${RelativeDateUnit}s`;
 }
 /**
  * Format the relative time between a plain date and a reference date.
  *
  * - Auto-picks the display unit (day/week/month/year) based on the distance, unless
  *   `largestUnit` forces one.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of those four units, singular or plural. Any other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"

package/dist/plain/format/formatRelativeDate.js

@@ -1,6 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { durationTotal, normalizeDateTime, resolveRelativeRounding, } from "../../internal/index.js";
+import { durationTotal } from "../../internal/index.js";
+import { formatRelativeAmount } from "../../internal/formatRelativeDuration.js";
 import { isValidDate } from "../validate/index.js";
+import { resolveRelativeUnit } from "../../internal/resolveRelativeUnit.js";
+// Temporal's date unit group: the units a PlainDate difference may be written in.
+const DATE_UNITS = [
+    "year",
+    "month",
+    "week",
+    "day",
+];
 const AUTO_UNITS = [
     { unit: "day", maxDays: 7 },
     { unit: "week", maxDays: 28 },
@@ -12,13 +21,13 @@ const AUTO_UNITS = [
  *
  * - Auto-picks the display unit (day/week/month/year) based on the distance, unless
  *   `largestUnit` forces one.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of those four units, singular or plural. Any other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"
@@ -35,30 +44,32 @@ export function formatRelativeDate(value, locale, options = {}) {
             return "";
         if (!isValidDate(value))
             return "";
-        if (options.reference !== undefined && !isValidDate(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidDate(referenceOption))
             return "";
         try {
+            const forcedUnit = resolveRelativeUnit(options.largestUnit, DATE_UNITS);
+            const roundingMethod = options.roundingMethod;
             const target = Temporal.PlainDate.from(value);
-            const reference = options.reference
-                ? Temporal.PlainDate.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainDate.from(referenceOption)
                 : Temporal.Now.plainDateISO();
             const diff = target.since(reference);
             const absDays = Math.abs(diff.total("day"));
-            const unit = options.largestUnit === undefined
+            const unit = forcedUnit === undefined
                 ? (AUTO_UNITS.find((t) => absDays < t.maxDays)?.unit ?? "year")
-                : options.largestUnit;
-            let amount;
+                : forcedUnit;
+            let total;
             try {
-                amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+                total = diff.total(unit);
             }
             catch {
                 // month/year are calendrical and need a relativeTo anchor
-                amount = resolveRelativeRounding(durationTotal(diff, unit, reference), options.roundingMethod);
+                total = durationTotal(diff, unit, reference);
             }
-            return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-                numeric: options.numeric === undefined ? "auto" : options.numeric,
-                style: options.style === undefined ? "long" : options.style,
-            }).format(amount, unit));
+            // Outside the retry: an invalid roundingMethod throws once, straight to the sentinel.
+            return formatRelativeAmount(total, unit, locale, options, roundingMethod);
         }
         catch {
             return "";

package/dist/plain/format/formatRelativeDateTime.d.ts

@@ -1,6 +1,18 @@
 import type { RelativeDateTimeUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+/**
+ * Options for `formatRelativeDateTime`: the reference date-time, the display unit, the rounding
+ * and the wording.
+ */
 export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeDateTimeUnit;
+    /**
+     * The unit the distance is written in, whatever its size: `"second"`, `"minute"`, `"hour"`,
+     * `"day"`, `"week"`, `"month"` or `"year"`, singular or plural. Any other value returns `""`.
+     * Omitted, the unit is picked from the distance: second under a minute, minute under an hour,
+     * hour under a day, day under 7 days, week under 28, month under 365 and year beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
+    largestUnit?: RelativeDateTimeUnit | `${RelativeDateTimeUnit}s`;
 }
 /**
  * Format the relative time between a plain date-time and a reference date-time.
@@ -11,13 +23,14 @@ export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions
  *   "3 years ago".
  * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
  *   Pass `largestUnit: "day"` to keep a day count.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date-time string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"

package/dist/plain/format/formatRelativeDateTime.js

@@ -12,13 +12,14 @@ import { isValidDateTime } from "../validate/index.js";
  *   "3 years ago".
  * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
  *   Pass `largestUnit: "day"` to keep a day count.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO date-time string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"
@@ -36,12 +37,14 @@ export function formatRelativeDateTime(value, locale, options = {}) {
             return "";
         if (!isValidDateTime(value))
             return "";
-        if (options.reference !== undefined && !isValidDateTime(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidDateTime(referenceOption))
             return "";
         try {
             const target = Temporal.PlainDateTime.from(value);
-            const reference = options.reference
-                ? Temporal.PlainDateTime.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainDateTime.from(referenceOption)
                 : Temporal.Now.plainDateTimeISO();
             const diff = target.since(reference);
             // month/year are calendrical — relativeTo needs a PlainDate

package/dist/plain/format/formatRelativeTime.d.ts

@@ -1,19 +1,32 @@
 import type { RelativeTimeFormatOptions, RelativeTimeUnit } from "../../types/index.js";
+/**
+ * Options for `formatRelativeTime`: the reference time, the display unit, the rounding and the
+ * wording.
+ */
 export interface FormatRelativeTimeOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeTimeUnit;
+    /**
+     * The unit the distance is written in, whatever its size: `"second"`, `"minute"` or `"hour"`,
+     * singular or plural. Any other value returns `""`, a date unit such as `"day"` included: a time
+     * has no date, and Temporal throws RangeError for a unit outside the units of the type. Omitted,
+     * the unit is picked from the distance: second under a minute, minute under an hour and hour
+     * beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
+    largestUnit?: RelativeTimeUnit | `${RelativeTimeUnit}s`;
 }
 /**
  * Format the relative time between a plain time and a reference time.
  *
  * - Auto-picks the display unit (second/minute/hour) based on the distance, unless
  *   `largestUnit` forces one.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of those three units, singular or plural. Any other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO time string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"

package/dist/plain/format/formatRelativeTime.js

@@ -1,6 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { normalizeDateTime, resolveRelativeRounding } from "../../internal/index.js";
+import { formatRelativeAmount } from "../../internal/formatRelativeDuration.js";
 import { isValidTime } from "../validate/index.js";
+import { resolveRelativeUnit } from "../../internal/resolveRelativeUnit.js";
+// Temporal's time unit group down to the second: the units a PlainTime difference may be written
+// in, less the sub-second units, which Intl.RelativeTimeFormat does not have.
+const TIME_UNITS = [
+    "hour",
+    "minute",
+    "second",
+];
 const AUTO_UNITS = [
     { unit: "second", maxSeconds: 60 },
     { unit: "minute", maxSeconds: 3_600 },
@@ -11,13 +19,13 @@ const AUTO_UNITS = [
  *
  * - Auto-picks the display unit (second/minute/hour) based on the distance, unless
  *   `largestUnit` forces one.
- * - `roundingMethod` controls how the distance rounds to the display unit.
+ * - `largestUnit` is one of those three units, singular or plural. Any other value returns `""`.
  * - `options` must be an object or omitted: `null` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ISO time string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference }
+ * @param options How the distance is measured, rounded and worded
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"
@@ -34,23 +42,23 @@ export function formatRelativeTime(value, locale, options = {}) {
             return "";
         if (!isValidTime(value))
             return "";
-        if (options.reference !== undefined && !isValidTime(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidTime(referenceOption))
             return "";
         try {
+            const forcedUnit = resolveRelativeUnit(options.largestUnit, TIME_UNITS);
+            const roundingMethod = options.roundingMethod;
             const target = Temporal.PlainTime.from(value);
-            const reference = options.reference
-                ? Temporal.PlainTime.from(options.reference)
+            const reference = referenceOption
+                ? Temporal.PlainTime.from(referenceOption)
                 : Temporal.Now.plainTimeISO();
             const diff = target.since(reference);
             const absSeconds = Math.abs(diff.total("second"));
-            const unit = options.largestUnit === undefined
+            const unit = forcedUnit === undefined
                 ? (AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ?? "hour")
-                : options.largestUnit;
-            const amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
-            return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-                numeric: options.numeric === undefined ? "auto" : options.numeric,
-                style: options.style === undefined ? "long" : options.style,
-            }).format(amount, unit));
+                : forcedUnit;
+            return formatRelativeAmount(diff.total(unit), unit, locale, options, roundingMethod);
         }
         catch {
             return "";

package/dist/plain/format/formatTime.js

@@ -2,6 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { normalizeDateTime } from "../../internal/index.js";
 import { plainTimeFormatOptions } from "../../internal/plainFormatOptions.js";
 import { isValidTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Return a localized string for a PlainTime ISO input using Intl options.
  *
@@ -42,8 +43,9 @@ export function formatTime(value, locale, options) {
         // (CreateDateTimeFormat ~time~, ~time~). Constructing with the caller's
         // options first surfaces the TypeError or RangeError Intl.DateTimeFormat
         // raises for invalid ones.
-        new Intl.DateTimeFormat(locale, options);
-        const resolved = plainTimeFormatOptions(options ?? {});
+        const read = readDateTimeFormatOptions(options);
+        new Intl.DateTimeFormat(locale, read);
+        const resolved = plainTimeFormatOptions(read);
         if (resolved === null) {
             return "";
         }

package/dist/plain/interval/intervalDifferenceDate.d.ts

@@ -32,6 +32,15 @@
  * @example intervalDifferenceDate("invalid", "2024-12-31", "2024-06-01", "2024-07-01") // []
  */
 export declare function intervalDifferenceDate(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The date the interval begins on, as an ISO 8601 date (`YYYY-MM-DD`). It keeps a calendar
+     * annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first date after the interval, in the same format as `start`. It is exclusive: the interval
+     * holds everything from `start` up to but not including this value. It is always later than
+     * `start`.
+     */
     end: string;
 }>;

package/dist/plain/interval/intervalDifferenceDateTime.d.ts

@@ -25,6 +25,15 @@
  * @example intervalDifferenceDateTime("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // []
  */
 export declare function intervalDifferenceDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The date-time the interval begins at, as an ISO 8601 date-time string with no offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first date-time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/plain/interval/intervalDifferenceTime.d.ts

@@ -27,6 +27,15 @@
  * @example intervalDifferenceTime("invalid", "17:00:00", "12:00:00", "13:00:00") // []
  */
 export declare function intervalDifferenceTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The clock time the interval begins at, as an ISO 8601 time string with no date, offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first clock time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/plain/interval/intervalDivideEquallyDate.d.ts

@@ -10,6 +10,8 @@
  *   the nearest whole day (`round(totalDays · i / n)`, computed exactly in `bigint`, an exact half
  *   rounding up) — when `totalDays` isn't evenly divisible by `n`, the resulting sub-intervals
  *   differ by at most one day rather than being mathematically exact.
+ * - When `n` is larger than the number of whole days in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
@@ -18,14 +20,11 @@
  *   carry the *same* calendar tag (or both be bare ISO); a mismatch returns `[]` (E5 decision
  *   of record D4). Internal boundaries are computed in whole days (calendar-independent), then
  *   re-formatted in the shared calendar.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainDate string for the interval start, optionally calendar-annotated
  * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input / mismatched calendars
  *
  * @example intervalDivideEquallyDate("2024-01-01", "2024-01-05", 4) // [{ start: "2024-01-01", end: "2024-01-02" }, { start: "2024-01-02", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-05" }]
@@ -38,8 +37,24 @@
  * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 3, { maxPieces: 3 }) // [{ start: "2024-01-01", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-10" }]
  */
 export declare function intervalDivideEquallyDate(start: string, end: string, n: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The date the interval begins on, as an ISO 8601 date (`YYYY-MM-DD`). It keeps a calendar
+     * annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first date after the interval, in the same format as `start`. It is exclusive: the interval
+     * holds everything from `start` up to but not including this value. It can equal `start`, which
+     * makes the interval empty.
+     */
     end: string;
 }>;

package/dist/plain/interval/intervalDivideEquallyDate.js

@@ -15,6 +15,8 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   the nearest whole day (`round(totalDays · i / n)`, computed exactly in `bigint`, an exact half
  *   rounding up) — when `totalDays` isn't evenly divisible by `n`, the resulting sub-intervals
  *   differ by at most one day rather than being mathematically exact.
+ * - When `n` is larger than the number of whole days in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
@@ -23,14 +25,11 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *   carry the *same* calendar tag (or both be bare ISO); a mismatch returns `[]` (E5 decision
  *   of record D4). Internal boundaries are computed in whole days (calendar-independent), then
  *   re-formatted in the shared calendar.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainDate string for the interval start, optionally calendar-annotated
  * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input / mismatched calendars
  *
  * @example intervalDivideEquallyDate("2024-01-01", "2024-01-05", 4) // [{ start: "2024-01-01", end: "2024-01-02" }, { start: "2024-01-02", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-05" }]

package/dist/plain/interval/intervalDivideEquallyDateTime.d.ts

@@ -10,18 +10,17 @@
  *   `bigint`: the split is exact whenever the total divides evenly by `n`, and within half a
  *   nanosecond of the exact cut otherwise (an exact half rounds up), at any span length — the
  *   whole PlainDateTime range included.
+ * - When `n` is larger than the number of nanoseconds in the interval, some pieces are empty (their
+ *   `start` equals their `end`): the result always has exactly `n` pieces.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
  * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
- *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
- *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO PlainDateTime string for the interval start
  * @param end ISO PlainDateTime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options The limit on the size of the result
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 3) // [{ start: "2024-01-01T00:00:00", end: "2024-01-02T00:00:00" }, { start: "2024-01-02T00:00:00", end: "2024-01-03T00:00:00" }, { start: "2024-01-03T00:00:00", end: "2024-01-04T00:00:00" }]
@@ -32,8 +31,24 @@
  * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00", end: "2024-01-02T00:00:00" }, { start: "2024-01-02T00:00:00", end: "2024-01-03T00:00:00" }, { start: "2024-01-03T00:00:00", end: "2024-01-04T00:00:00" }]
  */
 export declare function intervalDivideEquallyDateTime(start: string, end: string, n: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The date-time the interval begins at, as an ISO 8601 date-time string with no offset or time
+     * zone.
+     */
     start: string;
+    /**
+     * The first date-time after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;