@northguild/gmt 1.17.0 → 1.19.0

package/dist/plain/calculate/setDateTime.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
+import { DATE_TIME_FIELDS, readSetFields, resolveOverflow, } from "../../internal/index.js";
 import { isValidDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -9,23 +9,31 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
  *   `addDateTime()` calls field-by-field.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A field is
+ *   read with a property get, as Temporal reads it, so an inherited or getter field is set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- * `month: 2` on a datetime whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- * (resulting in "").
- *
  * @param value ISO PlainDateTime string
  * @param fields Partial<Temporal.PlainDateTimeLike> object specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range field value is handled
  * @returns ISO PlainDateTime string with fields set, or "" on invalid input
  *
  * @example setDateTime("2024-03-10T12:00:00", { hour: 9 }) // "2024-03-10T09:00:00"
  * @example setDateTime("2024-01-31T12:00:00", { month: 2 }) // "2024-02-29T12:00:00" (constrain clamps to the last valid day)
  * @example setDateTime("2024-01-31T12:00:00", { month: 2 }, { overflow: "reject" }) // ""
  * @example setDateTime("2024-03-10T12:00:00", {}) // "2024-03-10T12:00:00" (empty fields object is a no-op)
+ * @example setDateTime("2024-03-10T12:00:00", { hour: "9" }) // "" (not converted)
  * @example setDateTime("invalid", { hour: 9 }) // ""
  */
 export function setDateTime(value, fields, options) {
@@ -36,12 +44,15 @@ export function setDateTime(value, fields, options) {
         return "";
     try {
         const dateTime = Temporal.PlainDateTime.from(value);
-        // Temporal.PlainDateTime.prototype.with() throws on an empty fields object ("no supported
-        // properties found") rather than treating it as a no-op, so short-circuit here.
-        if (Object.keys(fields).length === 0)
+        const set = readSetFields(fields, DATE_TIME_FIELDS);
+        if (set === null)
+            return "";
+        // Only the values readSetFields checked reach Temporal. An empty result sets nothing: a
+        // no-op here, where Temporal's with() would throw.
+        if (Object.keys(set).length === 0)
             return dateTime.toString();
         return dateTime
-            .with(fields, { overflow: resolveOverflow(options?.overflow) })
+            .with(set, { overflow: resolveOverflow(options?.overflow) })
             .toString();
     }
     catch {

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

@@ -7,25 +7,41 @@ import type { Overflow } from "../../types/index.js";
  *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
  *   `addTime()` calls field-by-field.
  * - `fields` may set any of `hour`, `minute`, `second`, `millisecond`, `microsecond`, and/or
- *   `nanosecond`; omitted fields keep their current value. An empty object is a no-op.
+ *   `nanosecond`; omitted fields keep their current value. An object with no field set, such as
+ *   `{}` or `{ hour: undefined }`, is a no-op.
+ * - Values are not converted: all six fields must be integer numbers. `null`, a numeric string, a
+ *   boolean or a fraction returns "", where Temporal would convert or truncate it. A bigint, `NaN`
+ *   or an infinity returns "" too. An out-of-range number follows `overflow`.
+ * - An own key that is not one of these fields, such as a misspelt `huor`, returns "". So does a
+ *   date field, such as `year`, or a `calendar` or `timeZone` property, whether own, inherited or a
+ *   getter. A field is read with a property get, as Temporal reads it, so an inherited or getter
+ *   field is set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
+ * - Unlike `addTime`, which takes no `overflow` because addition always wraps around the clock,
+ *   `overflow` has an effect here: `.with()` assigns fixed field values rather than adding a
+ *   delta.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range field values, e.g.
- * `hour: 25`: "constrain" clamps to 23, "reject" throws (resulting in ""). Unlike `addTime`
- * (which takes no `overflow`, because addition always wraps around the clock), `overflow` has
- * a real effect here because `.with()` assigns fixed field values rather than adding a delta.
- *
  * @param value ISO PlainTime string
  * @param fields Partial<Temporal.PlainTimeLike> object specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range field value is handled
  * @returns ISO PlainTime string with fields set, or "" on invalid input
  *
  * @example setTime("12:00:00", { hour: 9 }) // "09:00:00"
  * @example setTime("12:00:00", { hour: 25 }) // "23:00:00" (constrain clamps to the max valid hour)
  * @example setTime("12:00:00", { hour: 25 }, { overflow: "reject" }) // ""
  * @example setTime("12:00:00", {}) // "12:00:00" (empty fields object is a no-op)
+ * @example setTime("12:00:00", { hour: 9.5 }) // "" (not truncated)
  * @example setTime("invalid", { hour: 9 }) // ""
  */
 export declare function setTime(value: string, fields: Temporal.PlainTimeLike, options?: {
+    /**
+     * What to do when a field value is out of range. `"constrain"` clamps it to the nearest valid
+     * value, so `hour: 25` becomes 23; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/setTime.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
+import { TIME_FIELDS, readSetFields, resolveOverflow } from "../../internal/index.js";
 import { isValidTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -9,23 +9,33 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
  *   `addTime()` calls field-by-field.
  * - `fields` may set any of `hour`, `minute`, `second`, `millisecond`, `microsecond`, and/or
- *   `nanosecond`; omitted fields keep their current value. An empty object is a no-op.
+ *   `nanosecond`; omitted fields keep their current value. An object with no field set, such as
+ *   `{}` or `{ hour: undefined }`, is a no-op.
+ * - Values are not converted: all six fields must be integer numbers. `null`, a numeric string, a
+ *   boolean or a fraction returns "", where Temporal would convert or truncate it. A bigint, `NaN`
+ *   or an infinity returns "" too. An out-of-range number follows `overflow`.
+ * - An own key that is not one of these fields, such as a misspelt `huor`, returns "". So does a
+ *   date field, such as `year`, or a `calendar` or `timeZone` property, whether own, inherited or a
+ *   getter. A field is read with a property get, as Temporal reads it, so an inherited or getter
+ *   field is set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
+ * - Unlike `addTime`, which takes no `overflow` because addition always wraps around the clock,
+ *   `overflow` has an effect here: `.with()` assigns fixed field values rather than adding a
+ *   delta.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range field values, e.g.
- * `hour: 25`: "constrain" clamps to 23, "reject" throws (resulting in ""). Unlike `addTime`
- * (which takes no `overflow`, because addition always wraps around the clock), `overflow` has
- * a real effect here because `.with()` assigns fixed field values rather than adding a delta.
- *
  * @param value ISO PlainTime string
  * @param fields Partial<Temporal.PlainTimeLike> object specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range field value is handled
  * @returns ISO PlainTime string with fields set, or "" on invalid input
  *
  * @example setTime("12:00:00", { hour: 9 }) // "09:00:00"
  * @example setTime("12:00:00", { hour: 25 }) // "23:00:00" (constrain clamps to the max valid hour)
  * @example setTime("12:00:00", { hour: 25 }, { overflow: "reject" }) // ""
  * @example setTime("12:00:00", {}) // "12:00:00" (empty fields object is a no-op)
+ * @example setTime("12:00:00", { hour: 9.5 }) // "" (not truncated)
  * @example setTime("invalid", { hour: 9 }) // ""
  */
 export function setTime(value, fields, options) {
@@ -36,12 +46,15 @@ export function setTime(value, fields, options) {
         return "";
     try {
         const time = Temporal.PlainTime.from(value);
-        // Temporal.PlainTime.prototype.with() throws on an empty fields object ("invalid time-like")
-        // rather than treating it as a no-op, so short-circuit here.
-        if (Object.keys(fields).length === 0)
+        const set = readSetFields(fields, TIME_FIELDS);
+        if (set === null)
+            return "";
+        // Only the values readSetFields checked reach Temporal. An empty result sets nothing: a
+        // no-op here, where Temporal's with() would throw.
+        if (Object.keys(set).length === 0)
             return time.toString();
         return time
-            .with(fields, { overflow: resolveOverflow(options?.overflow) })
+            .with(set, { overflow: resolveOverflow(options?.overflow) })
             .toString();
     }
     catch {

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

@@ -4,12 +4,11 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - `"day"` returns the date itself: a date is already a whole day, as `endOfDate` treats it.
  * - `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 date unit, singular or plural, to specify the unit for the start
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfDate("2024-02-29", "month") // "2024-02-01"
@@ -18,5 +17,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example startOfDate("invalid-date", "month") // ""
  */
 export declare function startOfDate(value: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/calculate/startOfDate.js

@@ -10,12 +10,11 @@ const supported = ["year", "month", "week", "day"];
  *
  * - `"day"` returns the date itself: a date is already a whole day, as `endOfDate` treats it.
  * - `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 date unit, singular or plural, to specify the unit for the start
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfDate("2024-02-29", "month") // "2024-02-01"

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

@@ -4,12 +4,11 @@ import type { FractionalDigit } from "../../types/index.js";
  * Return the start of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
  * - `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 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the start
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param optionsArg How the week is defined and how the result is written
  * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-01T00:00:00"
@@ -17,6 +16,20 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example startOfDateTime("invalid-datetime", "month") // ""
  */
 export declare function startOfDateTime(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer digits than `unit` names truncate, as Temporal's `toString` does.
+     *
+     * @defaultValue The digits `unit` names: `3` for `"millisecond"`, `6` for `"microsecond"`, `9`
+     * for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/plain/calculate/startOfDateTime.js

@@ -9,12 +9,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the start of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
  * - `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 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the start
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param optionsArg How the week is defined and how the result is written
  * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-01T00:00:00"

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

@@ -7,7 +7,7 @@ import type { FractionalDigit } from "../../types/index.js";
  * import { StartOfTimeUnit } from "@northguild/gmt/plain";
  * const unit: StartOfTimeUnit = "hours";
  */
-export type StartOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
+export type StartOfTimeUnit = Temporal.SmallestUnit<"day" | Temporal.TimeUnit>;
 /**
  * Return the start of the specified time `unit` for a given ISO 8601 time string.
  *
@@ -20,7 +20,7 @@ export type StartOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
  *
  * @param value ISO 8601 time string
  * @param unit StartOfTimeUnit to specify the unit for the start
- * @param optionsArg optional: fractionalSecondDigits (number)
+ * @param optionsArg How the result is written
  * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfTime("12:34:56", "hour") // "12:00:00"
@@ -29,5 +29,12 @@ export type StartOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
  * @example startOfTime("invalid", "hour") // ""
  */
 export declare function startOfTime(value: string, unit: StartOfTimeUnit, optionsArg?: {
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer digits than `unit` names truncate, as Temporal's `toString` does.
+     *
+     * @defaultValue The digits `unit` names: `3` for `"millisecond"`, `6` for `"microsecond"`, `9`
+     * for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/plain/calculate/startOfTime.js

@@ -25,7 +25,7 @@ const supported = [
  *
  * @param value ISO 8601 time string
  * @param unit StartOfTimeUnit to specify the unit for the start
- * @param optionsArg optional: fractionalSecondDigits (number)
+ * @param optionsArg How the result is written
  * @returns ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfTime("12:34:56", "hour") // "12:00:00"

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

@@ -10,12 +10,9 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  *   calendar ids); see `isValidCalendarDate`.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO PlainDate string, optionally calendar-annotated
  * @param units Partial<Record<DateDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDate string after subtraction, or "" on invalid input
  *
  * @example subtractDate("2024-03-15", { days: 5 }) // "2024-03-10"
@@ -24,5 +21,11 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  * @example subtractDate("2024-03-25[u-ca=hebrew]", { months: 1 }) // "2024-02-24[u-ca=hebrew]" (15 Adar II 5784 -> 15 Adar I)
  */
 export declare function subtractDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Mar 31 - 1 month is Feb 29 or 28; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/subtractDate.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, plainDateAdd, resolveOverflow, } from "../../internal/index.js";
+import { calendarSystemOfDateValue, formatDateInCalendar, parseCalendarDateValue, plainDateAdd, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -14,12 +14,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   calendar ids); see `isValidCalendarDate`.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO PlainDate string, optionally calendar-annotated
  * @param units Partial<Record<DateDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDate string after subtraction, or "" on invalid input
  *
  * @example subtractDate("2024-03-15", { days: 5 }) // "2024-03-10"
@@ -33,11 +30,8 @@ export function subtractDate(value, units, options) {
             return "";
         }
         const validDate = isValidCalendarDate(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDate || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateDurationUnit);
+        if (!validDate || amounts === null) {
             return "";
         }
         try {
@@ -46,7 +40,7 @@ export function subtractDate(value, units, options) {
                 return "";
             }
             const date = parseCalendarDateValue(value);
-            const result = plainDateAdd(date, Temporal.Duration.from(units).negated(), resolveOverflow(options?.overflow));
+            const result = plainDateAdd(date, Temporal.Duration.from(amounts).negated(), resolveOverflow(options?.overflow));
             return formatDateInCalendar(result, calendar);
         }
         catch {

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

@@ -5,12 +5,9 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * - Validates `value`, `units`, and `amount` before performing the subtract.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO PlainDateTime string
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDateTime string after subtraction, or "" on invalid input
  *
  * @example subtractDateTime("2024-03-15T12:00:00", { days: 5 }) // "2024-03-10T12:00:00"
@@ -18,5 +15,11 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * @example subtractDateTime("2024-03-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
  */
 export declare function subtractDateTime(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Mar 31 - 1 month is Feb 29 or 28; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/subtractDateTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -9,12 +9,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates `value`, `units`, and `amount` before performing the subtract.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO PlainDateTime string
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns ISO PlainDateTime string after subtraction, or "" on invalid input
  *
  * @example subtractDateTime("2024-03-15T12:00:00", { days: 5 }) // "2024-03-10T12:00:00"
@@ -27,17 +24,14 @@ export function subtractDateTime(value, units, options) {
             return "";
         }
         const validDateTime = isValidDateTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDateTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validDateTime || amounts === null) {
             return "";
         }
         try {
             const dateTime = Temporal.PlainDateTime.from(value);
             return dateTime
-                .subtract(units, { overflow: resolveOverflow(options?.overflow) })
+                .subtract(amounts, { overflow: resolveOverflow(options?.overflow) })
                 .toString();
         }
         catch {

package/dist/plain/calculate/subtractTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
+import { readDurationUnits } from "../../internal/index.js";
 import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 /**
  * Return a PlainTime ISO string with `units` subtracted from `value`.
@@ -22,16 +22,13 @@ import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 export function subtractTime(value, units) {
     try {
         const validTime = isValidTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidTimeDurationUnit);
+        if (!validTime || amounts === null) {
             return "";
         }
         try {
             const time = Temporal.PlainTime.from(value);
-            return time.subtract(units).toString();
+            return time.subtract(amounts).toString();
         }
         catch {
             return "";

package/dist/plain/compare/areDateTimesEqualBy.d.ts

@@ -4,18 +4,19 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Equality means both values share the same start-of-`unit` boundary, so
  *   `"month"` requires the same month AND year — March 2023 and March 2024 are
- *   NOT equal by month, matching date-fns's `isSameMonth` and Luxon's
- *   `dt.hasSame(other, "month")`.
+ *   NOT equal by month. A calendar month is a year and a month together, as in
+ *   Temporal's `PlainYearMonth`, not a bare month-of-year number.
+ * - Comparison: date-fns's `isSameMonth` and Luxon's `dt.hasSame(other, "month")`
+ *   give the same answer.
  * - Supports the full `Temporal.DateUnit | Temporal.TimeUnit` range, down to
  *   `"nanosecond"`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  * - Takes no `fractionalSecondDigits`: equality compares full-precision `unit` boundaries, and output
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areDateTimesEqualBy(a, b, "day")`
  * - `isSameHour(a, b)` → `areDateTimesEqualBy(a, b, "hour")`
  * - `isSameMinute(a, b)` → `areDateTimesEqualBy(a, b, "minute")`
@@ -26,7 +27,7 @@ import { Temporal } from "@js-temporal/polyfill";
  * @param value1 first ISO datetime string
  * @param value2 second ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns true if both datetimes share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areDateTimesEqualBy("2024-03-15T10:00:00", "2024-03-15T18:00:00", "day") // true
@@ -38,5 +39,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example areDateTimesEqualBy("invalid", "2024-03-15T10:00:00", "day") // false
  */
 export declare function areDateTimesEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/plain/compare/areDateTimesEqualBy.js

@@ -9,18 +9,19 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - Equality means both values share the same start-of-`unit` boundary, so
  *   `"month"` requires the same month AND year — March 2023 and March 2024 are
- *   NOT equal by month, matching date-fns's `isSameMonth` and Luxon's
- *   `dt.hasSame(other, "month")`.
+ *   NOT equal by month. A calendar month is a year and a month together, as in
+ *   Temporal's `PlainYearMonth`, not a bare month-of-year number.
+ * - Comparison: date-fns's `isSameMonth` and Luxon's `dt.hasSame(other, "month")`
+ *   give the same answer.
  * - Supports the full `Temporal.DateUnit | Temporal.TimeUnit` range, down to
  *   `"nanosecond"`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  * - Takes no `fractionalSecondDigits`: equality compares full-precision `unit` boundaries, and output
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areDateTimesEqualBy(a, b, "day")`
  * - `isSameHour(a, b)` → `areDateTimesEqualBy(a, b, "hour")`
  * - `isSameMinute(a, b)` → `areDateTimesEqualBy(a, b, "minute")`
@@ -31,7 +32,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 first ISO datetime string
  * @param value2 second ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns true if both datetimes share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areDateTimesEqualBy("2024-03-15T10:00:00", "2024-03-15T18:00:00", "day") // true

package/dist/plain/compare/areDatesEqualBy.d.ts

@@ -4,19 +4,21 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Equality means both values share the same start-of-`unit` boundary, so
  *   `"month"` requires the same month AND year — March 2023 and March 2024 are
- *   NOT equal by month, matching date-fns's `isSameMonth` and Luxon's
- *   `dt.hasSame(other, "month")`. This is a common point of confusion for
- *   callers expecting a bare "same month-of-year" comparison.
+ *   NOT equal by month. A calendar month is a year and a month together, as in
+ *   Temporal's `PlainYearMonth`, not a bare month-of-year number. This is a
+ *   common point of confusion for callers expecting a bare "same month-of-year"
+ *   comparison.
+ * - Comparison: date-fns's `isSameMonth` and Luxon's `dt.hasSame(other, "month")`
+ *   give the same answer.
  * - `"day"` matches `areDatesEqual` for PlainDate inputs only: `areDatesEqual` also accepts
  *   PlainDateTime strings (`areDatesEqual("2024-01-01", "2024-01-01T10:00")` is `true`), while this
  *   function accepts PlainDate strings only (`areDatesEqualBy` with those inputs and `"day"` is
  *   `false`).
  * - `"year"`, `"month"`, `"week"` are computed via `startOfDate`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areDatesEqualBy(a, b, "day")`
  * - `isSameWeek(a, b, options)` → `areDatesEqualBy(a, b, "week", { weekStartsOn })`
  * - `isSameMonth(a, b)` → `areDatesEqualBy(a, b, "month")`
@@ -25,7 +27,7 @@ import { Temporal } from "@js-temporal/polyfill";
  * @param value1 first ISO date string
  * @param value2 second ISO date string
  * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns true if both dates share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areDatesEqualBy("2024-03-15", "2024-03-20", "month") // true
@@ -37,5 +39,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example areDatesEqualBy("invalid", "2024-03-15", "month") // false
  */
 export declare function areDatesEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;