@northguild/gmt 1.17.0 → 1.18.0

package/dist/plain/calculate/diffDateTimeAsDuration.js

@@ -24,7 +24,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); 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 diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"

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

@@ -28,7 +28,7 @@ import type { RoundingOptions, TimeDurationUnit } from "../../types/index.js";
  * @param time1 ISO PlainTime string for the start
  * @param time2 ISO PlainTime string for the end
  * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); 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 diffTime("12:00:00", "14:30:00", "hours") // 2

package/dist/plain/calculate/diffTime.js

@@ -33,7 +33,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param time1 ISO PlainTime string for the start
  * @param time2 ISO PlainTime string for the end
  * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); 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 diffTime("12:00:00", "14:30:00", "hours") // 2

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

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

@@ -8,16 +8,14 @@ const supported = ["year", "month", "week", "day"];
 /**
  * Return the end of the specified date `unit` for a given ISO 8601 date string.
  *
- * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
  * - The end is computed forward from `value`, so it is returned even when the unit began before
  *   the first representable date (`-271821-04-19`).
  * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  *
  * @param value ISO 8601 date string
  * @param unit date unit, singular or plural, to specify the unit for the end
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDate("2024-02-29", "month") // "2024-02-29"

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

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

@@ -19,13 +19,9 @@ const supported = [
 /**
  * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
- * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
  * - The end is computed forward from `value`, so it is returned even when the unit began before
  *   the first representable date (`-271821-04-19`).
- * - The end is written at nanosecond precision by default, so the string names the end itself; an
- *   explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -33,7 +29,7 @@ const supported = [
  *
  * @param value ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the end
- * @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 end of the specified unit, or "" on invalid input
  *
  * @example endOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-29T23:59:59.999999999"

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

@@ -12,7 +12,6 @@ export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
@@ -21,7 +20,7 @@ export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
  *
  * @param value ISO 8601 time string
  * @param unit EndOfTimeUnit to specify the unit for the end
- * @param optionsArg optional: fractionalSecondDigits (number)
+ * @param optionsArg How the result is written
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfTime("12:34:56", "hour") // "12:59:59.999999999"
@@ -30,5 +29,12 @@ export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
  * @example endOfTime("invalid", "hour") // ""
  */
 export declare function endOfTime(value: string, unit: EndOfTimeUnit, optionsArg?: {
+    /**
+     * 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/plain/calculate/endOfTime.js

@@ -15,7 +15,6 @@ const supported = [
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
@@ -24,7 +23,7 @@ const supported = [
  *
  * @param value ISO 8601 time string
  * @param unit EndOfTimeUnit to specify the unit for the end
- * @param optionsArg optional: fractionalSecondDigits (number)
+ * @param optionsArg How the result is written
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfTime("12:34:56", "hour") // "12:59:59.999999999"

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

@@ -7,21 +7,21 @@
  * - Week 1 is the week starting on `locale`'s first day of week that holds at least `minimalDays`
  *   days of January (UTS #35 Part 4, Week Data). The first day of week comes from
  *   `Intl.Locale.prototype.getWeekInfo`.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days: Intl Locale Info returns only `firstDay` and `weekend`
- *   (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with
- *   newer ones about the same date. Pass CLDR's value when you need a locale's own rule: in CLDR 48
- *   `weekData`, the world default (`001`) is `1` — week 1 always contains January 1, as in `US`,
- *   `CA`, `MX`, `JP` and `CN` — and `4` is set for a list of mostly European regions such as `GB`,
- *   `DE` and `FR`, where it matches this default.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime, so one input has one answer
+ *   everywhere. ECMA-402 does not expose a locale's minimal days: Intl Locale Info returns only
+ *   `firstDay` and `weekend` (tc39/proposal-intl-locale-info#86), so older runtimes that still
+ *   reported it disagreed with newer ones about the same date. Pass CLDR's value when you need a
+ *   locale's own rule: in CLDR 48 `weekData`, the world default (`001`) is `1`, as in `US`, `CA`,
+ *   `MX`, `JP` and `CN`, and `4` is set for a list of mostly European regions such as `GB`, `DE`
+ *   and `FR`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns locale-relative week-numbering year, or null on invalid input
  *
  * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024
@@ -34,5 +34,12 @@
  * @example getLocaleWeekYear("2024-12-29", ["en-US", "fr-FR"]) // 2025
  */
 export declare function getLocaleWeekYear(value: string, locale: string | string[], options?: {
+    /**
+     * How many days of January the first week must hold to be week 1 (UTS #35 Part 4, Week
+     * Data). `4` is the ISO 8601 rule; `1` puts January 1 in week 1 every year, as CLDR's world
+     * default does. A value that is not an integer from 1 to 7 returns `null`.
+     *
+     * @defaultValue `4`
+     */
     minimalDays?: number;
 }): number | null;

package/dist/plain/calculate/getLocaleWeekYear.js

@@ -12,21 +12,21 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Week 1 is the week starting on `locale`'s first day of week that holds at least `minimalDays`
  *   days of January (UTS #35 Part 4, Week Data). The first day of week comes from
  *   `Intl.Locale.prototype.getWeekInfo`.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days: Intl Locale Info returns only `firstDay` and `weekend`
- *   (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with
- *   newer ones about the same date. Pass CLDR's value when you need a locale's own rule: in CLDR 48
- *   `weekData`, the world default (`001`) is `1` — week 1 always contains January 1, as in `US`,
- *   `CA`, `MX`, `JP` and `CN` — and `4` is set for a list of mostly European regions such as `GB`,
- *   `DE` and `FR`, where it matches this default.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime, so one input has one answer
+ *   everywhere. ECMA-402 does not expose a locale's minimal days: Intl Locale Info returns only
+ *   `firstDay` and `weekend` (tc39/proposal-intl-locale-info#86), so older runtimes that still
+ *   reported it disagreed with newer ones about the same date. Pass CLDR's value when you need a
+ *   locale's own rule: in CLDR 48 `weekData`, the world default (`001`) is `1`, as in `US`, `CA`,
+ *   `MX`, `JP` and `CN`, and `4` is set for a list of mostly European regions such as `GB`, `DE`
+ *   and `FR`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns locale-relative week-numbering year, or null on invalid input
  *
  * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024

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

@@ -3,10 +3,13 @@
  * grid, using `locale`'s first day of week.
  *
  * - Week 1 is the row containing the 1st of the month, even when that row
- *   is a partial week (matches date-fns's `getWeekOfMonth`, verified
- *   against date-fns source 2026-08-21) — this is the convention every
- *   calendar-grid UI (and `@internationalized/date`'s `getWeeksInMonth`)
- *   expects for sizing a month grid.
+ *   is a partial week. This is GMT's own rule, not a standard's: a month
+ *   grid draws every day of the month, so its first row always holds the 1st.
+ * - Not CLDR's week-of-month field (`W`, UTS #35): that count applies the
+ *   locale's `minDays`, so a short leading week may not count as part of
+ *   the month.
+ * - Comparison: date-fns's `getWeekOfMonth` returns the same number for the
+ *   same first day of week.
  * - Distinct from ISO `weekOfYear`: this counts rows within a single
  *   month's grid, reset every month, rather than weeks since Jan 1.
  * - Resolves the locale's first day of week via

package/dist/plain/calculate/getWeekOfMonth.js

@@ -7,10 +7,13 @@ import { isValidDate } from "../validate/index.js";
  * grid, using `locale`'s first day of week.
  *
  * - Week 1 is the row containing the 1st of the month, even when that row
- *   is a partial week (matches date-fns's `getWeekOfMonth`, verified
- *   against date-fns source 2026-08-21) — this is the convention every
- *   calendar-grid UI (and `@internationalized/date`'s `getWeeksInMonth`)
- *   expects for sizing a month grid.
+ *   is a partial week. This is GMT's own rule, not a standard's: a month
+ *   grid draws every day of the month, so its first row always holds the 1st.
+ * - Not CLDR's week-of-month field (`W`, UTS #35): that count applies the
+ *   locale's `minDays`, so a short leading week may not count as part of
+ *   the month.
+ * - Comparison: date-fns's `getWeekOfMonth` returns the same number for the
+ *   same first day of week.
  * - Distinct from ISO `weekOfYear`: this counts rows within a single
  *   month's grid, reset every month, rather than weeks since Jan 1.
  * - Resolves the locale's first day of week via

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

@@ -7,18 +7,18 @@
  * - Computed as the calendar days between this week-year's start and the next one's, divided by 7 —
  *   always whole, since both starts fall on the locale's first day of week. Counted by day
  *   arithmetic, so a start outside the representable range still counts.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
- *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when it
- *   differs. See `getLocaleWeekYear`.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime: ECMA-402 does not expose a
+ *   locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
+ *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when you
+ *   need its own rule. See `getLocaleWeekYear`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns 52 or 53, or null on invalid input
  *
  * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52
@@ -31,5 +31,12 @@
  * @example getWeeksInLocaleWeekYear("2024-12-29", ["fr-FR", "en-US"]) // 52
  */
 export declare function getWeeksInLocaleWeekYear(value: string, locale: string | string[], options?: {
+    /**
+     * How many days of January the first week must hold to be week 1 (UTS #35 Part 4, Week
+     * Data). `4` is the ISO 8601 rule; `1` puts January 1 in week 1 every year, as CLDR's world
+     * default does. A value that is not an integer from 1 to 7 returns `null`.
+     *
+     * @defaultValue `4`
+     */
     minimalDays?: number;
 }): number | null;

package/dist/plain/calculate/getWeeksInLocaleWeekYear.js

@@ -12,18 +12,18 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Computed as the calendar days between this week-year's start and the next one's, divided by 7 —
  *   always whole, since both starts fall on the locale's first day of week. Counted by day
  *   arithmetic, so a start outside the representable range still counts.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
- *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when it
- *   differs. See `getLocaleWeekYear`.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime: ECMA-402 does not expose a
+ *   locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
+ *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when you
+ *   need its own rule. See `getLocaleWeekYear`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns 52 or 53, or null on invalid input
  *
  * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52

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

@@ -5,8 +5,11 @@
  * - The count depends on which day the week starts — the same month can
  *   span 4, 5, or 6 rows depending on locale (e.g. February 2026 is 4
  *   rows starting Sunday but 5 rows starting Monday).
- * - Sized the same way `@internationalized/date`'s `getWeeksInMonth`
- *   sizes a datepicker's calendar grid.
+ * - The count is the row the month's last day falls on, where row 1 holds
+ *   the 1st (see `getWeekOfMonth`). This is GMT's own rule for sizing a
+ *   month grid, not a standard's; CLDR's `minDays` plays no part.
+ * - Comparison: `@internationalized/date`'s `getWeeksInMonth` returns the
+ *   same number for the same first day of week.
  * - Resolves the locale's first day of week via
  *   `Intl.Locale.prototype.weekInfo`.
  * - Returns null if `value` or `locale` is invalid.

package/dist/plain/calculate/getWeeksInMonth.js

@@ -9,8 +9,11 @@ import { isValidDate } from "../validate/index.js";
  * - The count depends on which day the week starts — the same month can
  *   span 4, 5, or 6 rows depending on locale (e.g. February 2026 is 4
  *   rows starting Sunday but 5 rows starting Monday).
- * - Sized the same way `@internationalized/date`'s `getWeeksInMonth`
- *   sizes a datepicker's calendar grid.
+ * - The count is the row the month's last day falls on, where row 1 holds
+ *   the 1st (see `getWeekOfMonth`). This is GMT's own rule for sizing a
+ *   month grid, not a standard's; CLDR's `minDays` plays no part.
+ * - Comparison: `@internationalized/date`'s `getWeeksInMonth` returns the
+ *   same number for the same first day of week.
  * - Resolves the locale's first day of week via
  *   `Intl.Locale.prototype.weekInfo`.
  * - Returns null if `value` or `locale` is invalid.

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

@@ -3,8 +3,6 @@
  *
  * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
  *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
- * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
- *   `dayOfWeek`: `false` advances a full week (matching date-fns), `true` returns `value` as-is.
  * - Returns "" on invalid input.
  *
  * Replaces date-fns's sixteen `next*` functions with one parameterized call:
@@ -22,7 +20,7 @@
  *
  * @param value ISO PlainDate string
  * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
- * @param options optional: inclusive (boolean, default false)
+ * @param options Whether `value` itself can be the result
  * @returns ISO PlainDate string for the next occurrence of `dayOfWeek`, or "" on invalid input
  *
  * @example nextWeekday("2024-03-15", 5) // "2024-03-22" (2024-03-15 is already a Friday, so it advances a full week)
@@ -32,5 +30,11 @@
  * @example nextWeekday("2024-03-15", 8) // "" (dayOfWeek out of range)
  */
 export declare function nextWeekday(value: string, dayOfWeek: number, options?: {
+    /**
+     * Whether `value` counts when it already falls on `dayOfWeek`. `true` returns `value`
+     * unchanged; `false` advances a full week.
+     *
+     * @defaultValue `false`
+     */
     inclusive?: boolean;
 }): string;

package/dist/plain/calculate/nextWeekday.js

@@ -8,8 +8,6 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
  *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
- * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
- *   `dayOfWeek`: `false` advances a full week (matching date-fns), `true` returns `value` as-is.
  * - Returns "" on invalid input.
  *
  * Replaces date-fns's sixteen `next*` functions with one parameterized call:
@@ -27,7 +25,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value ISO PlainDate string
  * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
- * @param options optional: inclusive (boolean, default false)
+ * @param options Whether `value` itself can be the result
  * @returns ISO PlainDate string for the next occurrence of `dayOfWeek`, or "" on invalid input
  *
  * @example nextWeekday("2024-03-15", 5) // "2024-03-22" (2024-03-15 is already a Friday, so it advances a full week)

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

@@ -3,8 +3,6 @@
  *
  * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
  *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
- * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
- *   `dayOfWeek`: `false` goes back a full week (matching date-fns), `true` returns `value` as-is.
  * - Returns "" on invalid input.
  *
  * Replaces date-fns's sixteen `previous*` functions with one parameterized call:
@@ -22,7 +20,7 @@
  *
  * @param value ISO PlainDate string
  * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
- * @param options optional: inclusive (boolean, default false)
+ * @param options Whether `value` itself can be the result
  * @returns ISO PlainDate string for the previous occurrence of `dayOfWeek`, or "" on invalid input
  *
  * @example previousWeekday("2024-03-15", 5) // "2024-03-08" (2024-03-15 is already a Friday, so it goes back a full week)
@@ -32,5 +30,11 @@
  * @example previousWeekday("2024-03-15", 0) // "" (dayOfWeek out of range)
  */
 export declare function previousWeekday(value: string, dayOfWeek: number, options?: {
+    /**
+     * Whether `value` counts when it already falls on `dayOfWeek`. `true` returns `value`
+     * unchanged; `false` goes back a full week.
+     *
+     * @defaultValue `false`
+     */
     inclusive?: boolean;
 }): string;

package/dist/plain/calculate/previousWeekday.js

@@ -8,8 +8,6 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - `dayOfWeek` uses Temporal's ISO numbering: 1 (Monday) through 7 (Sunday), consistent with
  *   `getDayOfWeek`/`parseDayOfWeekFromDate`.
- * - `options.inclusive` (default `false`) controls what happens when `value` already falls on
- *   `dayOfWeek`: `false` goes back a full week (matching date-fns), `true` returns `value` as-is.
  * - Returns "" on invalid input.
  *
  * Replaces date-fns's sixteen `previous*` functions with one parameterized call:
@@ -27,7 +25,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value ISO PlainDate string
  * @param dayOfWeek target ISO day of week (1-7, Monday-Sunday)
- * @param options optional: inclusive (boolean, default false)
+ * @param options Whether `value` itself can be the result
  * @returns ISO PlainDate string for the previous occurrence of `dayOfWeek`, or "" on invalid input
  *
  * @example previousWeekday("2024-03-15", 5) // "2024-03-08" (2024-03-15 is already a Friday, so it goes back a full week)

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

@@ -4,9 +4,6 @@ import type { DateUnit } from "../../types/index.js";
  * Round an ISO 8601 date string to the specified date unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts date units: "year", "month", "week", "day", each in its singular or plural form
- *   ("month" or "months"), as Temporal's GetTemporalUnitValuedOption accepts both (§13.17).
- * - Time units ("hour", "minute", etc.) are rejected and return "".
  * - All date units use manual start-of-unit rounding. Weeks start on Monday.
  * - The rounding grid is anchored at the unit containing `value`, so `"halfEven"` breaks an exact
  *   tie towards that unit's start (multiple 0, the even one).
@@ -15,13 +12,10 @@ import type { DateUnit } from "../../types/index.js";
  *   When it rounds down to that unrepresentable start, the result is "".
  * - In the last representable year (`+275760`) a date that rounds down still returns its unit's
  *   start; only rounding up past `+275760-09-13` returns "".
- * - `roundingIncrement` and `roundingMode` are read as Temporal reads them: 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 it floored silently).
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
  *
  * @param value ISO 8601 date 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 date string, or "" on invalid input
  *
  * @example roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"
@@ -38,7 +32,26 @@ import type { DateUnit } from "../../types/index.js";
  * @example roundDate("invalid", { smallestUnit: "year" }) // ""
  */
 export declare function roundDate(value: string, options: {
+    /**
+     * The unit to round to: `"year"`, `"month"`, `"week"` or `"day"`, singular or plural, as
+     * Temporal's GetTemporalUnitValuedOption accepts both (§13.17). A time unit such as `"hour"`
+     * returns `""`.
+     */
     smallestUnit: Temporal.SmallestUnit<DateUnit>;
+    /**
+     * How many units make one rounding step, counted from the unit that holds `value`. Read as
+     * Temporal reads it: a non-integer is truncated (`1.5` rounds by 1), and a value below 1 or not
+     * finite returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a date 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/roundDate.js

@@ -10,9 +10,6 @@ import { isObject } from "../../internal/isObject.js";
  * Round an ISO 8601 date string to the specified date unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts date units: "year", "month", "week", "day", each in its singular or plural form
- *   ("month" or "months"), as Temporal's GetTemporalUnitValuedOption accepts both (§13.17).
- * - Time units ("hour", "minute", etc.) are rejected and return "".
  * - All date units use manual start-of-unit rounding. Weeks start on Monday.
  * - The rounding grid is anchored at the unit containing `value`, so `"halfEven"` breaks an exact
  *   tie towards that unit's start (multiple 0, the even one).
@@ -21,13 +18,10 @@ import { isObject } from "../../internal/isObject.js";
  *   When it rounds down to that unrepresentable start, the result is "".
  * - In the last representable year (`+275760`) a date that rounds down still returns its unit's
  *   start; only rounding up past `+275760-09-13` returns "".
- * - `roundingIncrement` and `roundingMode` are read as Temporal reads them: 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 it floored silently).
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
  *
  * @param value ISO 8601 date 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 date string, or "" on invalid input
  *
  * @example roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"
@@ -48,9 +42,8 @@ export function roundDate(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 (!isValidDate(value) || !isValidDateUnit(smallestUnit))
             return "";
         try {