@northguild/gmt 1.15.0 → 1.17.0

package/dist/plain/calculate/diffDateTime.d.ts

@@ -10,16 +10,28 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest hour before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   array (e.g. `["days", "hours"]` with `smallestUnit: "week"`) — this combination is rejected by
  *   Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Nanosecond precision: the result is a JavaScript `number`, so it stops being exact once it
+ *   passes `Number.MAX_SAFE_INTEGER` — about 104 days in nanoseconds and about 285 years in
+ *   microseconds. `diffDateTime("2024-01-01T00:00:00", "2024-04-15T00:00:00.000000001", "nanoseconds")`
+ *   returns `9072000000000000` rather than `9072000000000001`. For an exact count use the `bigint` APIs: `spanNs`
+ *   in `span/`, or `toNanoseconds` in `precision/`.
  *
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "day") // 5
- * @example diffDateTime("invalid", "2024-03-15T12:00:00", "day") // null
+ * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5
+ * @example diffDateTime("invalid", "2024-03-15T12:00:00", "days") // null
+ * @example diffDateTime("2024-01-01T00:00:00", "2025-03-01T00:00:00", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
-export declare function diffDateTime(dateTime1: string, dateTime2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;
+export declare function diffDateTime(dateTime1: string, dateTime2: string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/plain/calculate/diffDateTime.js

@@ -1,6 +1,11 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
+import { differenceRecord } from "../../internal/differenceRecord.js";
+import { plainUntilWithRounding } from "../../internal/index.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
 import { getLargestDateTimeDurationUnit } from "./getLargestDateTimeDurationUnit.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two PlainDateTime values in the requested unit.
  *
@@ -11,47 +16,81 @@ import { getLargestDateTimeDurationUnit } from "./getLargestDateTimeDurationUnit
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest hour before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   array (e.g. `["days", "hours"]` with `smallestUnit: "week"`) — this combination is rejected by
  *   Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Nanosecond precision: the result is a JavaScript `number`, so it stops being exact once it
+ *   passes `Number.MAX_SAFE_INTEGER` — about 104 days in nanoseconds and about 285 years in
+ *   microseconds. `diffDateTime("2024-01-01T00:00:00", "2024-04-15T00:00:00.000000001", "nanoseconds")`
+ *   returns `9072000000000000` rather than `9072000000000001`. For an exact count use the `bigint` APIs: `spanNs`
+ *   in `span/`, or `toNanoseconds` in `precision/`.
  *
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "day") // 5
- * @example diffDateTime("invalid", "2024-03-15T12:00:00", "day") // null
+ * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5
+ * @example diffDateTime("invalid", "2024-03-15T12:00:00", "days") // null
+ * @example diffDateTime("2024-01-01T00:00:00", "2025-03-01T00:00:00", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
 export function diffDateTime(dateTime1, dateTime2, units, options) {
-    const validDateTimes = isValidDateTime(dateTime1) && isValidDateTime(dateTime2);
-    const isSingleUnit = !Array.isArray(units);
-    const validUnits = isSingleUnit
-        ? isValidDateTimeDurationUnit(units)
-        : units.every(isValidDateTimeDurationUnit);
-    //
-    if (!validDateTimes || !validUnits) {
-        return null;
-    }
     try {
-        const dt1 = Temporal.PlainDateTime.from(dateTime1);
-        const dt2 = Temporal.PlainDateTime.from(dateTime2);
-        const duration = dt1.until(dt2, {
-            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
-            smallestUnit: options?.smallestUnit,
-            roundingIncrement: options?.roundingIncrement,
-            roundingMode: options?.roundingMode,
-        });
-        if (isSingleUnit) {
-            return duration[units] ?? 0;
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const validDateTimes = isValidDateTime(dateTime1) && isValidDateTime(dateTime2);
+        // Singular names resolve to their plural (Temporal §13.17); record keys are the plural names.
+        const resolved = Array.isArray(units)
+            ? units.map((unit) => resolveDurationUnit(unit))
+            : resolveDurationUnit(units);
+        const isSingleUnit = !Array.isArray(resolved);
+        const validUnits = isSingleUnit
+            ? isValidDateTimeDurationUnit(resolved)
+            : resolved.every(isValidDateTimeDurationUnit);
+        //
+        if (!validDateTimes || !validUnits) {
+            return null;
+        }
+        try {
+            // An empty units list names no largest unit, so there is nothing to measure.
+            const largestUnit = isSingleUnit
+                ? resolved
+                : getLargestDateTimeDurationUnit(resolved);
+            if (largestUnit === "")
+                return null;
+            const dt1 = Temporal.PlainDateTime.from(dateTime1);
+            const dt2 = Temporal.PlainDateTime.from(dateTime2);
+            const duration = plainUntilWithRounding(dt1, dt2, {
+                largestUnit,
+                smallestUnit: options?.smallestUnit,
+                roundingIncrement: options?.roundingIncrement,
+                roundingMode: options?.roundingMode,
+            });
+            if (isSingleUnit) {
+                return duration[resolved] ?? 0;
+            }
+            // craft record for units passed
+            // An unlisted unit between two listed units is carried into the next smaller listed unit.
+            return differenceRecord(dt1, duration, resolved, {
+                add: (from, amount) => from.add(amount),
+                until: (from, to, largest) => from.until(to, { largestUnit: largest }),
+            });
+        }
+        catch {
+            return null;
         }
-        // craft record for units passed
-        return units.reduce((result, unit) => {
-            result[unit] = duration[unit] ?? 0;
-            return result;
-        }, {});
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/diffDateTimeAsDuration.d.ts

@@ -21,7 +21,7 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"
@@ -30,4 +30,4 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @example diffDateTimeAsDuration("invalid", "2024-03-15T12:00:00", "days") // ""
  * @example diffDateTimeAsDuration("2024-02-29T00:00:00", "2024-02-29T01:30:00", "hours", { smallestUnit: "hours", roundingMode: "halfExpand" }) // "PT2H"
  */
-export declare function diffDateTimeAsDuration(dateTime1: string, dateTime2: string, unit: DateTimeDurationUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;
+export declare function diffDateTimeAsDuration(dateTime1: string, dateTime2: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/plain/calculate/diffDateTimeAsDuration.js

@@ -1,6 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { durationUntilString } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two PlainDateTime values as an ISO 8601 duration string,
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
@@ -22,7 +24,7 @@ import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"
@@ -32,15 +34,20 @@ import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.
  * @example diffDateTimeAsDuration("2024-02-29T00:00:00", "2024-02-29T01:30:00", "hours", { smallestUnit: "hours", roundingMode: "halfExpand" }) // "PT2H"
  */
 export function diffDateTimeAsDuration(dateTime1, dateTime2, unit, options) {
+    // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     const validDateTimes = isValidDateTime(dateTime1) && isValidDateTime(dateTime2);
-    const validUnit = isValidDateTimeDurationUnit(unit);
+    const resolvedUnit = resolveDurationUnit(unit);
+    const validUnit = isValidDateTimeDurationUnit(resolvedUnit);
     if (!validDateTimes || !validUnit) {
         return "";
     }
     try {
         const dt1 = Temporal.PlainDateTime.from(dateTime1);
         const dt2 = Temporal.PlainDateTime.from(dateTime2);
-        return durationUntilString(dt1, dt2, unit, options);
+        return durationUntilString(dt1, dt2, resolvedUnit, options);
     }
     catch {
         return "";

package/dist/plain/calculate/diffTime.d.ts

@@ -10,16 +10,29 @@ import type { RoundingOptions, TimeDurationUnit } from "../../types/index.js";
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "minute", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest minute before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["minute", "second"]` with `smallestUnit: "hour"`) — this combination is
+ *   array (e.g. `["minutes", "seconds"]` with `smallestUnit: "hour"`) — this combination is
  *   rejected by Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["hours", "seconds"]` over
+ *   1 hour 30 minutes 15 seconds returns `{ hours: 1, seconds: 1815 }`.
+ * - Nanosecond precision is always exact here, unlike `diffDateTime`/`diffUtc`/`diffUnix`: two
+ *   plain times are less than a day apart, so the widest possible result,
+ *   `diffTime("00:00:00.000000000", "23:59:59.999999999", "nanoseconds")` = `86399999999999`,
+ *   is well inside `Number.MAX_SAFE_INTEGER`. Those three can span more than about 104 days, at
+ *   which point a nanosecond count stops being a safe integer and the `bigint` APIs (`spanNs` in
+ *   `span/`, `toNanoseconds` in `precision/`) are the exact ones.
  *
  * @param time1 ISO PlainTime string for the start
  * @param time2 ISO PlainTime string for the end
  * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffTime("12:00:00", "14:30:00", "hour") // 2
- * @example diffTime("invalid", "14:30:00", "hour") // null
+ * @example diffTime("12:00:00", "14:30:00", "hours") // 2
+ * @example diffTime("invalid", "14:30:00", "hours") // null
+ * @example diffTime("10:00:00", "11:30:15", ["hours", "seconds"]) // { hours: 1, seconds: 1815 } (PT1H30M15S; the 30 minutes are carried into seconds)
  */
-export declare function diffTime(time1: string, time2: string, units: TimeDurationUnit | TimeDurationUnit[], options?: RoundingOptions<Temporal.TimeUnit>): number | Record<TimeDurationUnit, number> | null;
+export declare function diffTime(time1: string, time2: string, units: TimeDurationUnit | Temporal.TimeUnit | Array<TimeDurationUnit | Temporal.TimeUnit>, options?: RoundingOptions<Temporal.TimeUnit>): number | Record<TimeDurationUnit, number> | null;

package/dist/plain/calculate/diffTime.js

@@ -1,6 +1,10 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
+import { differenceRecord } from "../../internal/differenceRecord.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 import { getLargestTimeDurationUnit } from "./getLargestTimeDurationUnit.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two PlainTime values in the requested unit.
  *
@@ -11,46 +15,83 @@ import { getLargestTimeDurationUnit } from "./getLargestTimeDurationUnit.js";
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "minute", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest minute before extracting the requested unit.
  * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["minute", "second"]` with `smallestUnit: "hour"`) — this combination is
+ *   array (e.g. `["minutes", "seconds"]` with `smallestUnit: "hour"`) — this combination is
  *   rejected by Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["hours", "seconds"]` over
+ *   1 hour 30 minutes 15 seconds returns `{ hours: 1, seconds: 1815 }`.
+ * - Nanosecond precision is always exact here, unlike `diffDateTime`/`diffUtc`/`diffUnix`: two
+ *   plain times are less than a day apart, so the widest possible result,
+ *   `diffTime("00:00:00.000000000", "23:59:59.999999999", "nanoseconds")` = `86399999999999`,
+ *   is well inside `Number.MAX_SAFE_INTEGER`. Those three can span more than about 104 days, at
+ *   which point a nanosecond count stops being a safe integer and the `bigint` APIs (`spanNs` in
+ *   `span/`, `toNanoseconds` in `precision/`) are the exact ones.
  *
  * @param time1 ISO PlainTime string for the start
  * @param time2 ISO PlainTime string for the end
  * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffTime("12:00:00", "14:30:00", "hour") // 2
- * @example diffTime("invalid", "14:30:00", "hour") // null
+ * @example diffTime("12:00:00", "14:30:00", "hours") // 2
+ * @example diffTime("invalid", "14:30:00", "hours") // null
+ * @example diffTime("10:00:00", "11:30:15", ["hours", "seconds"]) // { hours: 1, seconds: 1815 } (PT1H30M15S; the 30 minutes are carried into seconds)
  */
 export function diffTime(time1, time2, units, options) {
-    const validTimes = isValidTime(time1) && isValidTime(time2);
-    const isSingleUnit = !Array.isArray(units);
-    const validUnits = isSingleUnit
-        ? isValidTimeDurationUnit(units)
-        : units.every(isValidTimeDurationUnit);
-    if (!validTimes || !validUnits) {
-        return null;
-    }
     try {
-        const t1 = Temporal.PlainTime.from(time1);
-        const t2 = Temporal.PlainTime.from(time2);
-        const duration = t1.until(t2, {
-            largestUnit: isSingleUnit ? units : getLargestTimeDurationUnit(units),
-            smallestUnit: options?.smallestUnit,
-            roundingIncrement: options?.roundingIncrement,
-            roundingMode: options?.roundingMode,
-        });
-        // craft record for units passed
-        if (isSingleUnit) {
-            return duration[units] ?? 0;
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const validTimes = isValidTime(time1) && isValidTime(time2);
+        // Singular names resolve to their plural (Temporal §13.17); record keys are the plural names.
+        const resolved = Array.isArray(units)
+            ? units.map((unit) => resolveDurationUnit(unit))
+            : resolveDurationUnit(units);
+        const isSingleUnit = !Array.isArray(resolved);
+        const validUnits = isSingleUnit
+            ? isValidTimeDurationUnit(resolved)
+            : resolved.every(isValidTimeDurationUnit);
+        if (!validTimes || !validUnits) {
+            return null;
+        }
+        try {
+            // An empty units list names no largest unit, so there is nothing to measure.
+            const largestUnit = isSingleUnit
+                ? resolved
+                : getLargestTimeDurationUnit(resolved);
+            if (largestUnit === "")
+                return null;
+            const t1 = Temporal.PlainTime.from(time1);
+            const t2 = Temporal.PlainTime.from(time2);
+            const duration = t1.until(t2, {
+                largestUnit,
+                smallestUnit: options?.smallestUnit,
+                roundingIncrement: options?.roundingIncrement,
+                roundingMode: options?.roundingMode,
+            });
+            // craft record for units passed
+            if (isSingleUnit) {
+                return duration[resolved] ?? 0;
+            }
+            // An unlisted unit between two listed units is carried into the next smaller listed unit.
+            // Measured on one arbitrary day, because a rounded PlainTime end can pass midnight.
+            const day = Temporal.PlainDate.from("2000-01-01");
+            return differenceRecord(day.toPlainDateTime(t1), duration, resolved, {
+                add: (from, amount) => from.add(amount),
+                until: (from, to, largest) => from.until(to, { largestUnit: largest }),
+            });
+        }
+        catch {
+            return null;
         }
-        return units.reduce((result, unit) => {
-            result[unit] = duration[unit] ?? 0;
-            return result;
-        }, {});
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/endOfDate.d.ts

@@ -2,16 +2,24 @@ import { Temporal } from "@js-temporal/polyfill";
 /**
  * Return the end of the specified date `unit` for a given ISO 8601 date string.
  *
+ * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
+ * - The end is computed forward from `value`, so it is returned even when the unit began before
+ *   the first representable date (`-271821-04-19`).
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  *
  * @param value ISO 8601 date string
- * @param unit Temporal.DateUnit to specify the unit for the end
+ * @param unit date unit, singular or plural, to specify the unit for the end
  * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDate("2024-02-29", "month") // "2024-02-29"
+ * @example endOfDate("2024-03-03", "week", { weekStartsOn: "sunday" }) // "2024-03-09"
+ * @example endOfDate("-271821-04-19", "month") // "-271821-04-30" (the month began before the range; its end did not)
+ * @example endOfDate("2024-02-29", "years") // "2024-12-31"
  * @example endOfDate("invalid-date", "month") // ""
  */
-export declare function endOfDate(value: string, unit: Temporal.DateUnit, optionsArg?: {
+export declare function endOfDate(value: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/calculate/endOfDate.js

@@ -1,51 +1,76 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 const supported = ["year", "month", "week", "day"];
 /**
  * Return the end of the specified date `unit` for a given ISO 8601 date string.
  *
+ * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
+ * - The end is computed forward from `value`, so it is returned even when the unit began before
+ *   the first representable date (`-271821-04-19`).
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  *
  * @param value ISO 8601 date string
- * @param unit Temporal.DateUnit to specify the unit for the end
+ * @param unit date unit, singular or plural, to specify the unit for the end
  * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDate("2024-02-29", "month") // "2024-02-29"
+ * @example endOfDate("2024-03-03", "week", { weekStartsOn: "sunday" }) // "2024-03-09"
+ * @example endOfDate("-271821-04-19", "month") // "-271821-04-30" (the month began before the range; its end did not)
+ * @example endOfDate("2024-02-29", "years") // "2024-12-31"
  * @example endOfDate("invalid-date", "month") // ""
  */
 export function endOfDate(value, unit, optionsArg) {
-    if (!isValidDate(value) || !supported.includes(unit))
-        return "";
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        const source = Temporal.PlainDate.from(value);
-        let result;
-        switch (unit) {
-            case "year":
-                result = source.with({ month: 12, day: 31 });
-                break;
-            case "month": {
-                const firstOfNext = source.with({ day: 1 }).add({ months: 1 });
-                result = firstOfNext.subtract({ days: 1 });
-                break;
-            }
-            case "week": {
-                const daysToEndOfWeek = weekStartsOn === "monday"
-                    ? 7 - source.dayOfWeek
-                    : (6 - source.dayOfWeek) % 7;
-                result = source.add({ days: daysToEndOfWeek });
-                break;
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (weekStartsOn === null ||
+            !isValidDate(value) ||
+            !supported.includes(resolvedUnit))
+            return "";
+        try {
+            const source = Temporal.PlainDate.from(value);
+            let result;
+            switch (resolvedUnit) {
+                case "year":
+                    result = source.with({ month: 12, day: 31 });
+                    break;
+                case "month":
+                    // Computed from `value` itself: the month's first day may lie before the range.
+                    result = source.with({ day: source.daysInMonth });
+                    break;
+                case "week": {
+                    // Sunday is day 7, so `dayOfWeek % 7` counts Sunday as day 0 of a Sunday-first week.
+                    const daysToEndOfWeek = weekStartsOn === "monday"
+                        ? 7 - source.dayOfWeek
+                        : 6 - (source.dayOfWeek % 7);
+                    result = source.add({ days: daysToEndOfWeek });
+                    break;
+                }
+                case "day":
+                    result = source;
+                    break;
+                default:
+                    return "";
             }
-            case "day":
-                result = source;
-                break;
-            default:
-                return "";
+            return result.toString();
+        }
+        catch {
+            return "";
         }
-        return result.toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/endOfDateTime.d.ts

@@ -3,17 +3,32 @@ import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
+ * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
+ * - The end is computed forward from `value`, so it is returned even when the unit began before
+ *   the first representable date (`-271821-04-19`).
+ * - The end is written at nanosecond precision by default, so the string names the end itself; an
+ *   explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
+ * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
+ *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
+ *   than the end. Pass that `fractionalSecondDigits` to keep the previous string.
  *
  * @param value ISO 8601 datetime string
- * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the unit for the end
+ * @param unit date or time unit, singular or plural, to specify the unit for the end
  * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-29T23:59:59.999999999"
+ * @example endOfDateTime("2024-02-29T12:34:56", "month", { fractionalSecondDigits: 0 }) // "2024-02-29T23:59:59" — the pre-1.16.0 string
+ * @example endOfDateTime("2024-02-29T12:34:56.123456789", "second", { fractionalSecondDigits: 9 }) // "2024-02-29T12:34:56.999999999"
+ * @example endOfDateTime("2024-03-03T12:00:00", "week", { weekStartsOn: "sunday" }) // "2024-03-09T23:59:59.999999999"
+ * @example endOfDateTime("-271821-04-19T12:00:00", "month") // "-271821-04-30T23:59:59.999999999" (the month began before the range; its end did not)
+ * @example endOfDateTime("2024-02-29T12:34:56", "hours") // "2024-02-29T12:59:59.999999999"
  * @example endOfDateTime("invalid-date", "month") // ""
  */
-export declare function endOfDateTime(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+export declare function endOfDateTime(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
     fractionalSecondDigits?: FractionalDigit;
 }): string;