@northguild/gmt 1.17.0 → 1.19.0

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 {

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

@@ -8,25 +8,44 @@ import type { Overflow } from "../../types/index.js";
  *   field-by-field: each sequential `.add()` resolves overflow against its own intermediate
  *   value, so setting month-then-day vs. day-then-month on the same target can silently
  *   diverge — `.with()` has no such order-dependence.
- * - `fields` may set `year`, `month`, `monthCode`, `day`, `era`, and/or `eraYear`; omitted
- *   fields keep their current value. An empty object is a no-op.
+ * - `fields` may set `year`, `month`, `monthCode` and/or `day`; omitted fields keep their current
+ *   value. An object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `year`, `month` and `day` must be integer numbers and `monthCode` a
+ *   string. `null`, a numeric string, a boolean or a fraction returns "", where Temporal would
+ *   convert or truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for
+ *   its field follows `overflow`. A month or day below 1, or a date outside Temporal's range,
+ *   returns "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does a
+ *   field this function does not take, such as `hour`, or a `calendar` or `timeZone` property,
+ *   whether own, inherited or a getter. A field is read with a property get, as Temporal reads it,
+ *   so an inherited or getter field is set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- * `month: 2` on a 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"
  * @example setDate("2024-01-31", { month: 2 }) // "2024-02-29" (constrain clamps to the last valid day)
  * @example setDate("2024-01-31", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setDate("2024-01-31", { month: 13 }) // "2024-12-31" (too large: constrain clamps it)
+ * @example setDate("2024-01-31", { month: 0 }) // "" (below 1, under either overflow)
  * @example setDate("2024-03-10", {}) // "2024-03-10" (empty fields object is a no-op)
+ * @example setDate("2024-01-31", { year: "2025" }) // "" (not converted)
+ * @example setDate("2024-01-31", { year: 2025, yaer: 1 }) // "" (misspelt key)
+ * @example setDate("2024-03-10", { year: 2025, hour: 5 }) // "" (setDate takes no hour)
  * @example setDate("invalid", { year: 2025 }) // ""
  */
-export declare function setDate(value: string, fields: Omit<Temporal.PlainDateLike, "calendar">, options?: {
+export declare function setDate(value: string, fields: Omit<Temporal.PlainDateLike, "calendar" | "era" | "eraYear">, 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

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
+import { DATE_FIELDS, readSetFields, resolveOverflow } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -10,23 +10,36 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   field-by-field: each sequential `.add()` resolves overflow against its own intermediate
  *   value, so setting month-then-day vs. day-then-month on the same target can silently
  *   diverge — `.with()` has no such order-dependence.
- * - `fields` may set `year`, `month`, `monthCode`, `day`, `era`, and/or `eraYear`; omitted
- *   fields keep their current value. An empty object is a no-op.
+ * - `fields` may set `year`, `month`, `monthCode` and/or `day`; omitted fields keep their current
+ *   value. An object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `year`, `month` and `day` must be integer numbers and `monthCode` a
+ *   string. `null`, a numeric string, a boolean or a fraction returns "", where Temporal would
+ *   convert or truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for
+ *   its field follows `overflow`. A month or day below 1, or a date outside Temporal's range,
+ *   returns "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does a
+ *   field this function does not take, such as `hour`, or a `calendar` or `timeZone` property,
+ *   whether own, inherited or a getter. A field is read with a property get, as Temporal reads it,
+ *   so an inherited or getter field is set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- * `month: 2` on a 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"
  * @example setDate("2024-01-31", { month: 2 }) // "2024-02-29" (constrain clamps to the last valid day)
  * @example setDate("2024-01-31", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setDate("2024-01-31", { month: 13 }) // "2024-12-31" (too large: constrain clamps it)
+ * @example setDate("2024-01-31", { month: 0 }) // "" (below 1, under either overflow)
  * @example setDate("2024-03-10", {}) // "2024-03-10" (empty fields object is a no-op)
+ * @example setDate("2024-01-31", { year: "2025" }) // "" (not converted)
+ * @example setDate("2024-01-31", { year: 2025, yaer: 1 }) // "" (misspelt key)
+ * @example setDate("2024-03-10", { year: 2025, hour: 5 }) // "" (setDate takes no hour)
  * @example setDate("invalid", { year: 2025 }) // ""
  */
 export function setDate(value, fields, options) {
@@ -37,12 +50,15 @@ export function setDate(value, fields, options) {
         return "";
     try {
         const date = Temporal.PlainDate.from(value);
-        // Temporal.PlainDate.prototype.with() throws on an empty fields object ("no supported
-        // properties found") rather than treating it as a no-op, so short-circuit here.
-        if (Object.keys(fields).length === 0)
+        const set = readSetFields(fields, DATE_FIELDS);
+        if (set === null)
+            return "";
+        // Only the values readSetFields checked reach Temporal. An empty result sets nothing: a
+        // no-op here, where Temporal's with() would throw.
+        if (Object.keys(set).length === 0)
             return date.toString();
         return date
-            .with(fields, { overflow: resolveOverflow(options?.overflow) })
+            .with(set, { overflow: resolveOverflow(options?.overflow) })
             .toString();
     }
     catch {

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

@@ -7,25 +7,40 @@ import type { Overflow } from "../../types/index.js";
  *   single atomic overflow pass — see `setDate`'s doc for why that matters over composing
  *   `addDateTime()` calls field-by-field.
  * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
- *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
- *   their current value. An empty object is a no-op.
+ *   `millisecond`, `microsecond` and/or `nanosecond`; omitted fields keep their current value. An
+ *   object with no field set, such as `{}` or `{ year: undefined }`, is a no-op.
+ * - Values are not converted: `monthCode` must be a string and every other field an integer number.
+ *   `null`, a numeric string, a boolean or a fraction returns "", where Temporal would convert or
+ *   truncate it. A bigint, `NaN` or an infinity returns "" too. A number too large for its
+ *   field follows `overflow`. A month or day below 1, or a date outside Temporal's range, returns
+ *   "".
+ * - An own key that is not one of these fields, such as a misspelt `yaer`, returns "". So does an
+ *   era, or a `calendar` or `timeZone` property, whether own, inherited or a getter. A field is
+ *   read with a property get, as Temporal reads it, so an inherited or getter field is set.
+ * - A Temporal date or time object returns "", as Temporal's `with` refuses one. One whose
+ *   prototype has been replaced with `Object.prototype`, `null` or `Function.prototype` sets
+ *   nothing instead.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
- * `month: 2` on a datetime whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
- * (resulting in "").
- *
  * @param value ISO PlainDateTime string
  * @param fields Partial<Temporal.PlainDateTimeLike> object specifying fields to set
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range field value is handled
  * @returns ISO PlainDateTime string with fields set, or "" on invalid input
  *
  * @example setDateTime("2024-03-10T12:00:00", { hour: 9 }) // "2024-03-10T09:00:00"
  * @example setDateTime("2024-01-31T12:00:00", { month: 2 }) // "2024-02-29T12:00:00" (constrain clamps to the last valid day)
  * @example setDateTime("2024-01-31T12:00:00", { month: 2 }, { overflow: "reject" }) // ""
  * @example setDateTime("2024-03-10T12:00:00", {}) // "2024-03-10T12:00:00" (empty fields object is a no-op)
+ * @example setDateTime("2024-03-10T12:00:00", { hour: "9" }) // "" (not converted)
  * @example setDateTime("invalid", { hour: 9 }) // ""
  */
-export declare function setDateTime(value: string, fields: Omit<Temporal.PlainDateTimeLike, "calendar">, options?: {
+export declare function setDateTime(value: string, fields: Omit<Temporal.PlainDateTimeLike, "calendar" | "era" | "eraYear">, 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;