@northguild/gmt 1.16.0 → 1.18.0

package/dist/unix/parse/parseUnitFromUnix.d.ts

@@ -29,15 +29,14 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * Extract a unit from a unix epoch value.
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
- * - `value` is a safe integer or a string of optionally negative ASCII digits; an omitted `timeZone` is UTC and `"local"` is the system zone.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits.
  * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "", for every unit.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its wall clock is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
@@ -50,7 +49,27 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
  */
 export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/unix/parse/parseUnitFromUnix.js

@@ -7,15 +7,14 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Extract a unit from a unix epoch value.
  *
  * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
- * - `value` is a safe integer or a string of optionally negative ASCII digits; an omitted `timeZone` is UTC and `"local"` is the system zone.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits.
  * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "", for every unit.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its wall clock is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"

package/dist/unix/parse/parseWeekFromUnix.d.ts

@@ -2,16 +2,12 @@ import type { UnixUnit } from "../validate/index.js";
 /**
  * Return the week number from a unix epoch value.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
- *   first Thursday, so late-December days can be week 1 of the next year. The result is 1–53.
- * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
- *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
- *   next year. The result is 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - Returns the week of the week-year, 1–53, so late-December days can be week 1 of the next
+ *   year — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its date is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns Week number (1-53 for "monday" and for "sunday") or null on invalid input
  *
  * @example parseWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1
@@ -22,7 +18,27 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseWeekFromUnix(1735646400000, { weekStartsOn: "sunday", timeZone: "UTC" }) // 1 (2024-12-31T12:00:00Z; its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the date is read in: an IANA name, a UTC offset, or `"local"` for the system
+     * time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * The first day of the week, which sets how the week is numbered. `"monday"` gives the ISO 8601
+     * week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS #35 week
+     * number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other
+     * value returns `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/unix/parse/parseWeekFromUnix.js

@@ -5,16 +5,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a unix epoch value.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
- *   first Thursday, so late-December days can be week 1 of the next year. The result is 1–53.
- * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
- *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
- *   next year. The result is 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - Returns the week of the week-year, 1–53, so late-December days can be week 1 of the next
+ *   year — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid), weekStartsOn ("monday" | "sunday"); a non-object value (such as `null`) is invalid
+ * @param options optional: how `value` is read, the zone its date is read in and the first day of the week; a non-object value (such as `null`) is invalid
  * @returns Week number (1-53 for "monday" and for "sunday") or null on invalid input
  *
  * @example parseWeekFromUnix(1704067200000, { timeZone: "UTC" }) // 1

package/dist/unix/parse/parseYearFromUnix.d.ts

@@ -3,11 +3,11 @@ import type { UnixUnit } from "../validate/index.js";
  * Return the year from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
@@ -16,6 +16,18 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)
  */
 export declare function parseYearFromUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/parse/parseYearFromUnix.js

@@ -4,11 +4,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Return the year from a unix epoch value.
  *
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
- * - `value` is a safe integer or a digit string; an omitted `timeZone` is UTC.
+ * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone is invalid)
+ * @param options optional: how `value` is read and the zone its wall clock is read in
  * @returns Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"

package/dist/unix/validate/isValidUnixRange.d.ts

@@ -7,11 +7,8 @@
  * - Fractional values, `NaN`, `±Infinity` and anything beyond ±(2^53 − 1) return `false`.
  * - Strings with whitespace, `+`, a decimal point, an exponent or hex digits return `false`, and an
  *   empty string is not epoch 0.
- * - Equal `value1 === value2` is valid only when `options.allowEqual` is true.
  *
- * @param value1 first Unix epoch value (seconds or milliseconds)
- * @param value2 second Unix epoch value (seconds or milliseconds)
- * @param options optional allowEqual flag
+ * @param props the two epoch values and the settings for the check
  * @returns boolean indicating whether the Unix range is valid
  *
  * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true
@@ -22,9 +19,28 @@
  * @example isValidUnixRange({ value1: "0", value2: "1e3" }) // false (exponent notation is not an epoch)
  */
 export declare function isValidUnixRange(props: {
+    /**
+     * The start of the range: a Unix epoch in seconds or milliseconds, as a safe integer or a digit
+     * string.
+     */
     value1: number | string;
+    /**
+     * The end of the range, in the same form and unit as `value1`.
+     */
     value2: number | string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Equal values are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` equal to `value2` is a valid range. `false` requires `value1` to be
+         * before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/unix/validate/isValidUnixRange.js

@@ -8,11 +8,8 @@ import { isObject, isOptionsArgument, parseUnixEpochValue, } from "../../interna
  * - Fractional values, `NaN`, `±Infinity` and anything beyond ±(2^53 − 1) return `false`.
  * - Strings with whitespace, `+`, a decimal point, an exponent or hex digits return `false`, and an
  *   empty string is not epoch 0.
- * - Equal `value1 === value2` is valid only when `options.allowEqual` is true.
  *
- * @param value1 first Unix epoch value (seconds or milliseconds)
- * @param value2 second Unix epoch value (seconds or milliseconds)
- * @param options optional allowEqual flag
+ * @param props the two epoch values and the settings for the check
  * @returns boolean indicating whether the Unix range is valid
  *
  * @example isValidUnixRange({ value1: 0, value2: 1700000000 }) // true

package/dist/utc/calculate/addUtc.d.ts

@@ -6,12 +6,9 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after addition, or "" on invalid input
  *
  * @example addUtc("2024-03-10T12:00:00Z", { days: 5 }) // "2024-03-15T12:00:00Z"
@@ -19,5 +16,11 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * @example addUtc("invalid", { days: 5 }) // ""
  */
 export declare function addUtc(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 Jan 31 + 1 month is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/utc/calculate/addUtc.js

@@ -11,12 +11,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after addition, or "" on invalid input
  *
  * @example addUtc("2024-03-10T12:00:00Z", { days: 5 }) // "2024-03-15T12:00:00Z"

package/dist/utc/calculate/diffUtc.d.ts

@@ -31,7 +31,7 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24

package/dist/utc/calculate/diffUtc.js

@@ -38,7 +38,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // 24

package/dist/utc/calculate/diffUtcAsDuration.d.ts

@@ -21,7 +21,7 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUtcAsDuration("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // "PT24H"

package/dist/utc/calculate/diffUtcAsDuration.js

@@ -25,7 +25,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 UTC ISO datetime string (start)
  * @param value2 UTC ISO datetime string (end)
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUtcAsDuration("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hours") // "PT24H"

package/dist/utc/calculate/endOfUtc.d.ts

@@ -5,8 +5,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
- * - 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.
+ * - The end is the last nanosecond of the unit, one nanosecond before the next unit starts.
  * - Returns "" for invalid input.
  * - **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
@@ -14,7 +13,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the end of the unit, or "" on invalid input
  *
  * @example endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"
@@ -24,6 +23,20 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example endOfUtc("invalid", "year") // ""
  */
 export declare function endOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * 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 than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/endOfUtc.js

@@ -5,8 +5,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
- * - 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.
+ * - The end is the last nanosecond of the unit, one nanosecond before the next unit starts.
  * - Returns "" for invalid input.
  * - **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
@@ -14,7 +13,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the end of the unit, or "" on invalid input
  *
  * @example endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"

package/dist/utc/calculate/isBetweenUtc.d.ts

@@ -3,12 +3,11 @@
  *
  * - Uses Temporal.Instant.compare for comparison.
  * - Returns false if start > end or inputs are invalid.
- * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
  *
  * @param value ISO UTC datetime string to check
  * @param start ISO UTC datetime string for range start
  * @param end ISO UTC datetime string for range end
- * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param options Whether each boundary counts as inside the range
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUtc("2024-03-15T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // true
@@ -16,6 +15,18 @@
  * @example isBetweenUtc("invalid", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // false
  */
 export declare function isBetweenUtc(value: string, start: string, end: string, options?: {
+    /**
+     * Whether `value` equal to `start` counts as inside the range. `false` requires it to be after
+     * `start`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveStart?: boolean;
+    /**
+     * Whether `value` equal to `end` counts as inside the range. `false` requires it to be before
+     * `end`.
+     *
+     * @defaultValue `true`
+     */
     inclusiveEnd?: boolean;
 }): boolean;

package/dist/utc/calculate/isBetweenUtc.js

@@ -2,17 +2,17 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return true when `value` is between `start` and `end` (inclusive by default).
  *
  * - Uses Temporal.Instant.compare for comparison.
  * - Returns false if start > end or inputs are invalid.
- * - Use options.inclusiveStart/inclusiveEnd to control boundaries.
  *
  * @param value ISO UTC datetime string to check
  * @param start ISO UTC datetime string for range start
  * @param end ISO UTC datetime string for range end
- * @param options optional: inclusiveStart (boolean), inclusiveEnd (boolean)
+ * @param options Whether each boundary counts as inside the range
  * @returns boolean indicating whether value is between start and end
  *
  * @example isBetweenUtc("2024-03-15T12:00:00Z", "2024-03-10T12:00:00Z", "2024-03-20T12:00:00Z") // true
@@ -28,8 +28,8 @@ export function isBetweenUtc(value, start, end, options) {
         // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
         // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
         // behaves here exactly as `0` and `""` already do.
-        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
-        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        const inclusiveStart = optionOrDefault(options?.inclusiveStart, true);
+        const inclusiveEnd = optionOrDefault(options?.inclusiveEnd, true);
         if (!isValidUtc(value) || !isValidUtc(start) || !isValidUtc(end)) {
             return false;
         }

package/dist/utc/calculate/roundUtc.d.ts

@@ -4,22 +4,14 @@ import type { FractionalDigit } from "../../types/index.js";
  * Round a UTC datetime string to the specified unit.
  *
  * - Converts to Instant, rounds, converts back to UTC Instant string.
- * - Supports: "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.
  * - Day and larger units ("day", "week", "month", "year") return "". This is the Temporal spec, not
  *   a polyfill limitation: `Instant.prototype.round` validates `smallestUnit` as a time unit
  *   (ValidateTemporalUnitValue with ~time~), because an instant has no calendar or zone to define a
  *   day. Round a zoned value with `roundZoned` for a day boundary.
  * - 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.
- * - `fractionalSecondDigits` overrides that count outright, coarser or finer than the unit; an
- *   invalid value returns "".
  *
  * @param value ISO UTC datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, fractionalSecondDigits
+ * @param options What to round to, how, and the precision of the result
  * @returns Rounded ISO UTC Instant string, or "" on invalid input
  *
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
@@ -33,8 +25,33 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example roundUtc("", { smallestUnit: "hour" }) // ""
  */
 export declare function roundUtc(value: string, options: {
+    /**
+     * The unit to round to: `"hour"`, `"minute"`, `"second"`, `"millisecond"`, `"microsecond"` or
+     * `"nanosecond"`, singular or plural as Temporal's GetTemporalUnitValuedOption accepts both.
+     */
     smallestUnit: Temporal.SmallestUnit<"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    /**
+     * The multiple of `smallestUnit` to round to, such as 15 for quarter hours. It must divide a
+     * 24-hour day evenly (Temporal's `Instant.prototype.round`); any other value returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which multiple a value between two is rounded to. `"halfExpand"` picks the nearer one and
+     * sends a tie to the later instant; `"floor"` and `"trunc"` pick the earlier, `"ceil"` and
+     * `"expand"` the later, and the other `"half…"` modes differ only in how a tie breaks.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. It overrides the unit's own count, coarser or finer; an invalid value
+     * returns `""`.
+     *
+     * @defaultValue The digits `smallestUnit` names: `3` for `"millisecond"`, `6` for
+     * `"microsecond"`, `9` for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/roundUtc.js

@@ -6,22 +6,14 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * Round a UTC datetime string to the specified unit.
  *
  * - Converts to Instant, rounds, converts back to UTC Instant string.
- * - Supports: "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.
  * - Day and larger units ("day", "week", "month", "year") return "". This is the Temporal spec, not
  *   a polyfill limitation: `Instant.prototype.round` validates `smallestUnit` as a time unit
  *   (ValidateTemporalUnitValue with ~time~), because an instant has no calendar or zone to define a
  *   day. Round a zoned value with `roundZoned` for a day boundary.
  * - 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.
- * - `fractionalSecondDigits` overrides that count outright, coarser or finer than the unit; an
- *   invalid value returns "".
  *
  * @param value ISO UTC datetime string
- * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode, fractionalSecondDigits
+ * @param options What to round to, how, and the precision of the result
  * @returns Rounded ISO UTC Instant string, or "" on invalid input
  *
  * @example roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
@@ -39,9 +31,8 @@ export function roundUtc(value, options) {
         if (!isObject(options))
             return "";
         const { roundingIncrement, roundingMode, fractionalSecondDigits } = 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);
         // Temporal Instant.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~)
         if (!isValidUtc(value) || !isValidTimeUnit(smallestUnit))
             return "";

package/dist/utc/calculate/setUtc.d.ts

@@ -11,16 +11,13 @@ import type { Overflow } from "../../types/index.js";
  * - `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.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- *   (resulting in "").
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string with fields set, or "" on invalid input
  *
  * @example setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"
@@ -30,5 +27,11 @@ import type { Overflow } from "../../types/index.js";
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
 export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so `month: 2` on Jan 31 is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/utc/calculate/setUtc.js

@@ -13,16 +13,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - `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.
- * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- *   (resulting in "").
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string with fields set, or "" on invalid input
  *
  * @example setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"