@northguild/gmt 1.17.0 → 1.18.0

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

@@ -4,9 +4,6 @@ import type { DateTimeUnit } from "../../types/index.js";
  * Round an ISO 8601 datetime string to the specified date-time unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts all date and time units: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Time units use Temporal.PlainDateTime.round() directly.
  * - Date units (year, month, week) use manual start-of-unit rounding. Weeks start on Monday.
  * - For date units the rounding grid is anchored at the unit containing `value`, so `"halfEven"`
@@ -18,17 +15,13 @@ import type { DateTimeUnit } from "../../types/index.js";
  *   that unrepresentable start, the result is "".
  * - In the last representable year (`+275760`) a value that rounds down to a date unit still
  *   returns that unit's start; only rounding up past `+275760-09-13T23:59:59.999999999` returns "".
- * - `roundingIncrement` and `roundingMode` are read as Temporal reads them for every unit: a
- *   non-integer increment is truncated (`1.5` rounds by 1), an increment below 1 or not finite
- *   returns "", and a `roundingMode` outside Temporal's nine returns "" (previously a date unit
- *   floored silently).
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
  * - Output precision follows `smallestUnit`: no fractional seconds for "second" and coarser,
  *   3 digits for "millisecond", 6 for "microsecond" and 9 for "nanosecond", so the result never
  *   hides the precision the unit asked for.
  *
  * @param value ISO 8601 datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @param options The unit to round to and how to round
  * @returns Rounded ISO 8601 datetime string, or "" on invalid input
  *
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "year" }) // "2024-01-01T00:00:00"
@@ -44,7 +37,28 @@ import type { DateTimeUnit } from "../../types/index.js";
  * @example roundDateTime("invalid", { smallestUnit: "year" }) // ""
  */
 export declare function roundDateTime(value: string, options: {
+    /**
+     * The unit to round to, any date or time unit from `"year"` to `"nanosecond"`, singular
+     * or plural, as Temporal's GetTemporalUnitValuedOption accepts both. It also sets how
+     * many fractional-second digits the result is written with.
+     */
     smallestUnit: Temporal.SmallestUnit<DateTimeUnit>;
+    /**
+     * How many units make one rounding step. For `"day"` and the time units Temporal
+     * requires it to divide the next larger unit evenly and be smaller than it (`15` minutes,
+     * not `7` or `60`; a day only by `1`); for `"year"`, `"month"` and `"week"` the steps are
+     * counted from the unit that holds `value`. A non-integer is truncated, and a value below 1
+     * or not finite returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a value between two steps goes: one of Temporal's nine rounding modes, such as
+     * `"floor"`, `"ceil"` or `"halfExpand"` (to the nearer step, a tie going up). Any other value
+     * returns `""`.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
 }): string;

package/dist/plain/calculate/roundDateTime.js

@@ -85,9 +85,6 @@ function roundDateUnit(source, smallestUnit, increment, mode) {
  * Round an ISO 8601 datetime string to the specified date-time unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts all date and time units: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Time units use Temporal.PlainDateTime.round() directly.
  * - Date units (year, month, week) use manual start-of-unit rounding. Weeks start on Monday.
  * - For date units the rounding grid is anchored at the unit containing `value`, so `"halfEven"`
@@ -99,17 +96,13 @@ function roundDateUnit(source, smallestUnit, increment, mode) {
  *   that unrepresentable start, the result is "".
  * - In the last representable year (`+275760`) a value that rounds down to a date unit still
  *   returns that unit's start; only rounding up past `+275760-09-13T23:59:59.999999999` returns "".
- * - `roundingIncrement` and `roundingMode` are read as Temporal reads them for every unit: a
- *   non-integer increment is truncated (`1.5` rounds by 1), an increment below 1 or not finite
- *   returns "", and a `roundingMode` outside Temporal's nine returns "" (previously a date unit
- *   floored silently).
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
  * - Output precision follows `smallestUnit`: no fractional seconds for "second" and coarser,
  *   3 digits for "millisecond", 6 for "microsecond" and 9 for "nanosecond", so the result never
  *   hides the precision the unit asked for.
  *
  * @param value ISO 8601 datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @param options The unit to round to and how to round
  * @returns Rounded ISO 8601 datetime string, or "" on invalid input
  *
  * @example roundDateTime("2024-06-15T12:34:56", { smallestUnit: "year" }) // "2024-01-01T00:00:00"
@@ -129,9 +122,8 @@ export function roundDateTime(value, options) {
         if (!isObject(options))
             return "";
         const { roundingIncrement, roundingMode } = options;
-        const smallestUnit = typeof options.smallestUnit === "string"
-            ? resolveDateTimeUnit(options.smallestUnit)
-            : options.smallestUnit;
+        // One read (GetOption): resolveDateTimeUnit returns a value that is not a string unchanged.
+        const smallestUnit = resolveDateTimeUnit(options.smallestUnit);
         if (!isValidDateTime(value) || !isValidDateTimeUnit(smallestUnit))
             return "";
         try {

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

@@ -3,16 +3,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * Round an ISO 8601 time string to the specified time unit.
  *
  * - Returns "" for invalid inputs.
- * - Only time units are accepted: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Wraps Temporal.PlainTime.round() which throws on invalid options.
  * - Output precision follows `smallestUnit`: no fractional seconds for "second" and coarser,
  *   3 digits for "millisecond", 6 for "microsecond" and 9 for "nanosecond", so the result never
  *   hides the precision the unit asked for.
  *
  * @param value ISO 8601 time string
- * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @param options The unit to round to and how to round
  * @returns Rounded ISO 8601 time string, or "" on invalid input
  *
  * @example roundTime("12:34:56", { smallestUnit: "hour" }) // "13:00:00"
@@ -23,7 +20,26 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example roundTime("invalid", { smallestUnit: "hour" }) // ""
  */
 export declare function roundTime(value: string, options: {
+    /**
+     * The unit to round to, a time unit from `"hour"` to `"nanosecond"`, singular or plural, as
+     * Temporal's GetTemporalUnitValuedOption accepts both. It also sets how many fractional-second
+     * digits the result is written with. A date unit returns `""`.
+     */
     smallestUnit: Temporal.SmallestUnit<Temporal.TimeUnit>;
+    /**
+     * How many units make one rounding step. Temporal requires it to divide the next larger
+     * unit evenly and be smaller than it (`15` minutes, not `7` or `60`), and truncates a
+     * non-integer; any other value returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a time between two steps goes: one of Temporal's nine rounding modes, such as
+     * `"floor"`, `"ceil"` or `"halfExpand"` (to the nearer step, a tie going up). Any other value
+     * returns `""`.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
 }): string;

package/dist/plain/calculate/roundTime.js

@@ -6,16 +6,13 @@ import { isValidTime, isValidTimeUnit } from "../validate/index.js";
  * Round an ISO 8601 time string to the specified time unit.
  *
  * - Returns "" for invalid inputs.
- * - Only time units are accepted: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Each unit is accepted in its singular or plural form ("hour" or "hours"), as Temporal's
- *   GetTemporalUnitValuedOption accepts both.
  * - Wraps Temporal.PlainTime.round() which throws on invalid options.
  * - Output precision follows `smallestUnit`: no fractional seconds for "second" and coarser,
  *   3 digits for "millisecond", 6 for "microsecond" and 9 for "nanosecond", so the result never
  *   hides the precision the unit asked for.
  *
  * @param value ISO 8601 time string
- * @param options Rounding options: smallestUnit, optional roundingIncrement and roundingMode
+ * @param options The unit to round to and how to round
  * @returns Rounded ISO 8601 time string, or "" on invalid input
  *
  * @example roundTime("12:34:56", { smallestUnit: "hour" }) // "13:00:00"
@@ -30,9 +27,8 @@ export function roundTime(value, options) {
         if (!isObject(options))
             return "";
         const { roundingIncrement, roundingMode } = options;
-        const smallestUnit = typeof options.smallestUnit === "string"
-            ? resolveDateTimeUnit(options.smallestUnit)
-            : options.smallestUnit;
+        // One read (GetOption): resolveDateTimeUnit returns a value that is not a string unchanged.
+        const smallestUnit = resolveDateTimeUnit(options.smallestUnit);
         if (!isValidTime(value) || !isValidTimeUnit(smallestUnit))
             return "";
         try {

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

@@ -12,13 +12,9 @@ import type { Overflow } from "../../types/index.js";
  *   fields keep their current value. An empty object is a no-op.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- * `month: 2` on a date whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- * (resulting in "").
- *
  * @param value ISO PlainDate string
  * @param fields Partial<Temporal.PlainDateLike> object specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range field value is handled
  * @returns ISO PlainDate string with fields set, or "" on invalid input
  *
  * @example setDate("2024-03-10", { year: 2025 }) // "2025-03-10"
@@ -28,5 +24,11 @@ import type { Overflow } from "../../types/index.js";
  * @example setDate("invalid", { year: 2025 }) // ""
  */
 export declare function setDate(value: string, fields: Omit<Temporal.PlainDateLike, "calendar">, options?: {
+    /**
+     * What to do when the fields do not form a real date. `"constrain"` clamps to the last valid
+     * day, so `month: 2` on the 31st gives Feb 29 or 28; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/setDate.js

@@ -14,13 +14,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   fields keep their current value. An empty object is a no-op.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- * `month: 2` on a date whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- * (resulting in "").
- *
  * @param value ISO PlainDate string
  * @param fields Partial<Temporal.PlainDateLike> object specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range field value is handled
  * @returns ISO PlainDate string with fields set, or "" on invalid input
  *
  * @example setDate("2024-03-10", { year: 2025 }) // "2025-03-10"

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

@@ -11,13 +11,9 @@ import type { Overflow } from "../../types/index.js";
  *   their current value. An empty object is a no-op.
  * - 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"
@@ -27,5 +23,12 @@ import type { Overflow } from "../../types/index.js";
  * @example setDateTime("invalid", { hour: 9 }) // ""
  */
 export declare function setDateTime(value: string, fields: Omit<Temporal.PlainDateTimeLike, "calendar">, options?: {
+    /**
+     * What to do when the fields do not form a real date-time. `"constrain"` clamps each field to
+     * its nearest valid value, so `month: 2` on the 31st gives Feb 29 or 28; `"reject"` returns
+     * `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/setDateTime.js

@@ -13,13 +13,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   their current value. An empty object is a no-op.
  * - 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"

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

@@ -8,16 +8,14 @@ import type { Overflow } from "../../types/index.js";
  *   `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.
+ * - 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"
@@ -27,5 +25,11 @@ import type { Overflow } from "../../types/index.js";
  * @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

@@ -10,16 +10,14 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   `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.
+ * - 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"

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

@@ -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

@@ -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"

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

@@ -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"

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