@northguild/gmt 1.18.0 → 1.19.0

package/dist/internal/zonedNowUnitValue.js

@@ -1,11 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoYearString } from "./isoYearString.js";
 /**
  * One field of a zoned "now" as the `get*NowUnit` accessors return it: zero-padded to two digits
- * (three for sub-second fields), the year and day of week unpadded. The week number is the
+ * (three for sub-second fields), the day of week unpadded, and the year as Temporal writes one
+ * (`isoYearString`: four digits, or a sign and six outside 0000–9999). The week number is the
  * caller's, since the plain and zoned accessors read it through `parseWeekFromDate` and the utc and
  * unix ones from the ISO date.
  *
- * @param now the current moment on the wall clock being read
+ * @param now the current moment on the wall clock being read: a zoned date-time, or the plain wall
+ *   clock of a stored UTC offset with seconds, which no time zone identifier can carry
  * @param unit a singular unit, `dayOfWeek` included (already validated by the caller)
  * @param week the week number for `now`, as a string
  * @returns the field, or "" for any other unit
@@ -16,7 +19,7 @@ import { Temporal } from "@js-temporal/polyfill";
 export function zonedNowUnitValue(now, unit, week) {
     switch (unit) {
         case "year":
-            return now.year.toString();
+            return isoYearString(now.year);
         case "month":
             return now.month.toString().padStart(2, "0");
         case "week":
@@ -44,7 +47,8 @@ export function zonedNowUnitValue(now, unit, week) {
 /**
  * The ISO 8601 week number of `now`'s date, the week the utc and unix `get*NowUnit` accessors read.
  *
- * @param now the current moment on the wall clock being read
+ * @param now the current moment on the wall clock being read: a zoned date-time, or the plain wall
+ *   clock of a stored UTC offset with seconds, which no time zone identifier can carry
  * @returns the week number as a string
  * @example isoWeekOfYear(Temporal.ZonedDateTime.from("2024-12-30T00:00:00+00:00[UTC]")) // "1"
  */

package/dist/internal/zonedWallClockDifference.js

@@ -3,6 +3,7 @@ import { TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
 import { calendarDateAdd as compatCalendarDateAdd, calendarDateUntil as compatCalendarDateUntil, isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./temporalCompat/index.js";
 import { epochNanosecondsFor, isNamedTimeZone, isValidEpoch, utcEpochNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+import { isObject } from "./isObject.js";
 const UNITS = [
     "year",
     "month",
@@ -771,7 +772,7 @@ function zonedRelativeTo(relativeTo) {
                 ? zonedDateTimeFrom(relativeTo)
                 : null;
         }
-        if (typeof relativeTo === "object" &&
+        if (isObject(relativeTo) &&
             !(relativeTo instanceof Temporal.PlainDateTime) &&
             "timeZone" in relativeTo &&
             relativeTo.timeZone !== undefined) {
@@ -956,7 +957,7 @@ function relativeToDayOfMonth(relativeTo, zoned) {
         if (typeof relativeTo === "string") {
             return Temporal.PlainDate.from(relativeTo).day;
         }
-        if (relativeTo !== null && typeof relativeTo === "object") {
+        if (isObject(relativeTo)) {
             return Temporal.PlainDate.from(relativeTo).day;
         }
     }
@@ -978,8 +979,7 @@ function plainRelativeTo(relativeTo) {
             !timeZoneAnnotation.test(relativeTo)) {
             return Temporal.PlainDate.from(relativeTo);
         }
-        if (relativeTo !== null &&
-            typeof relativeTo === "object" &&
+        if (isObject(relativeTo) &&
             !(relativeTo instanceof Temporal.ZonedDateTime)) {
             return Temporal.PlainDate.from(relativeTo);
         }

package/dist/internal/zonedWallClockOperations.d.ts

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import type { Disambiguation, Offset, Overflow } from "../types/index.js";
+import type { DATE_TIME_FIELDS, SetFields } from "./readSetFields.js";
 type RoundingSmallestUnit = Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
 interface ZonedRoundTo {
     smallestUnit: RoundingSmallestUnit;
@@ -125,15 +126,17 @@ interface ZonedWithOptions {
     disambiguation?: Disambiguation;
     offset?: Offset;
 }
+/** The date and time fields a `set*` function passes, as `readSetFields` checked them. */
+type ZonedWithFields = SetFields<(typeof DATE_TIME_FIELDS)[number]>;
 /**
  * `ZonedDateTime#with`, correct at the range limits.
  *
  * @param zoned the value to change
- * @param fields the date/time (and optional offset) fields to set
+ * @param fields the date and time fields to set
  * @param options Temporal `overflow` / `disambiguation` / `offset` (default `"prefer"`)
  * @returns the changed value; throws where TC39 Temporal throws
  */
-export declare function withZonedFields(zoned: Temporal.ZonedDateTime, fields: Temporal.ZonedDateTimeLike, options?: ZonedWithOptions): Temporal.ZonedDateTime;
+export declare function withZonedFields(zoned: Temporal.ZonedDateTime, fields: ZonedWithFields, options?: ZonedWithOptions): Temporal.ZonedDateTime;
 /**
  * `ZonedDateTime#round`, correct at the range limits and, by day, before 1847.
  *

package/dist/internal/zonedWallClockOperations.js

@@ -2,7 +2,7 @@ import { Temporal } from "@js-temporal/polyfill";
 import { MAX_EPOCH_NANOSECONDS } from "./epochNanoseconds.js";
 import { calendarDateAdd, isCalendarArithmeticCompatNeeded, isTransitionSearchCompatNeeded, } from "./temporalCompat/index.js";
 import { nextTransitionAfter, previousTransitionBefore, } from "./zonedTransitionSearch.js";
-import { epochNanosecondsFor, interpretISODateTimeOffset, isNamedTimeZone, isNearRangeEdge, isValidEpoch, MAX_TRANSITIONS_BEFORE_MAXIMUM, missedNextTransition, missedPreviousTransition, needsOwnDayBoundsSearch, needsOwnStartOfDaySearch, NEXT_TRANSITION_HORIZON_NANOSECONDS, startOfDayEpochNanoseconds, timeZoneIdOf, utcOffsetStringNanoseconds, } from "./zonedWallClock.js";
+import { epochNanosecondsFor, interpretISODateTimeOffset, isNamedTimeZone, isNearRangeEdge, isValidEpoch, MAX_TRANSITIONS_BEFORE_MAXIMUM, missedNextTransition, missedPreviousTransition, needsOwnDayBoundsSearch, needsOwnStartOfDaySearch, NEXT_TRANSITION_HORIZON_NANOSECONDS, startOfDayEpochNanoseconds, timeZoneIdOf, } from "./zonedWallClock.js";
 import { optionOrDefault } from "./optionOrDefault.js";
 /*
  * Polyfill-first wrappers for the Temporal operations that resolve a wall clock or a start of day
@@ -480,22 +480,19 @@ export function addToZonedDisambiguated(zoned, duration, sign, options) {
 /** TC39 `ZonedDateTime#with` at the range limits. */
 function withAtEdge(zoned, fields, options) {
     let wall;
-    let offset;
     try {
         Temporal.ZonedDateTime.from(zoned, options);
-        const { offset: offsetString, ...dateTimeFields } = fields;
         wall = zoned
             .toPlainDateTime()
-            .with(dateTimeFields, { overflow: options?.overflow });
-        offset = {
-            nanoseconds: offsetString === undefined
-                ? BigInt(zoned.offsetNanoseconds)
-                : utcOffsetStringNanoseconds(offsetString),
-        };
+            .with(fields, { overflow: options?.overflow });
     }
     catch {
         return null;
     }
+    // `fields` holds no offset, so the merged wall clock keeps the receiver's (ZonedDateTime#with).
+    const offset = {
+        nanoseconds: BigInt(zoned.offsetNanoseconds),
+    };
     if (!isAtRangeEdge(zoned.timeZoneId, wall.toPlainDate())) {
         return null;
     }
@@ -506,7 +503,7 @@ function withAtEdge(zoned, fields, options) {
  * `ZonedDateTime#with`, correct at the range limits.
  *
  * @param zoned the value to change
- * @param fields the date/time (and optional offset) fields to set
+ * @param fields the date and time fields to set
  * @param options Temporal `overflow` / `disambiguation` / `offset` (default `"prefer"`)
  * @returns the changed value; throws where TC39 Temporal throws
  */

package/dist/plain/calculate/addDate.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, plainDateAdd, resolveOverflow, } from "../../internal/index.js";
+import { calendarSystemOfDateValue, formatDateInCalendar, parseCalendarDateValue, plainDateAdd, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -37,11 +37,8 @@ export function addDate(value /* ISO 8601 date */, units, options) {
             return "";
         }
         const validDate = isValidCalendarDate(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDate || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateDurationUnit);
+        if (!validDate || amounts === null) {
             return "";
         }
         try {
@@ -50,7 +47,7 @@ export function addDate(value /* ISO 8601 date */, units, options) {
                 return "";
             }
             const date = parseCalendarDateValue(value);
-            const result = plainDateAdd(date, units, resolveOverflow(options?.overflow));
+            const result = plainDateAdd(date, amounts, resolveOverflow(options?.overflow));
             return formatDateInCalendar(result, calendar);
         }
         catch {

package/dist/plain/calculate/addDateTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -24,17 +24,14 @@ export function addDateTime(value, units, options) {
             return "";
         }
         const validDateTime = isValidDateTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDateTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validDateTime || amounts === null) {
             return "";
         }
         try {
             const dateTime = Temporal.PlainDateTime.from(value);
             return dateTime
-                .add(units, { overflow: resolveOverflow(options?.overflow) })
+                .add(amounts, { overflow: resolveOverflow(options?.overflow) })
                 .toString();
         }
         catch {

package/dist/plain/calculate/addTime.js

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

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

@@ -8,7 +8,7 @@ import type { FractionalDigit } from "../../types/index.js";
  * import { EndOfTimeUnit } from "@northguild/gmt/plain";
  * const unit: EndOfTimeUnit = "minutes";
  */
-export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
+export type EndOfTimeUnit = Temporal.SmallestUnit<"day" | Temporal.TimeUnit>;
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *

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

@@ -8,8 +8,20 @@ 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.
  *
  * @param value ISO PlainDate string
@@ -20,10 +32,15 @@ import type { Overflow } from "../../types/index.js";
  * @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 `""`.

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,8 +10,20 @@ 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.
  *
  * @param value ISO PlainDate string
@@ -22,7 +34,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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) {
@@ -33,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,8 +7,19 @@ 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.
  *
  * @param value ISO PlainDateTime string
@@ -20,9 +31,10 @@ import type { Overflow } from "../../types/index.js";
  * @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

package/dist/plain/calculate/setDateTime.js

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

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

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

package/dist/plain/calculate/setTime.js

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

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

@@ -7,7 +7,7 @@ import type { FractionalDigit } from "../../types/index.js";
  * import { StartOfTimeUnit } from "@northguild/gmt/plain";
  * const unit: StartOfTimeUnit = "hours";
  */
-export type StartOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
+export type StartOfTimeUnit = Temporal.SmallestUnit<"day" | Temporal.TimeUnit>;
 /**
  * Return the start of the specified time `unit` for a given ISO 8601 time string.
  *

package/dist/plain/calculate/subtractDate.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, plainDateAdd, resolveOverflow, } from "../../internal/index.js";
+import { calendarSystemOfDateValue, formatDateInCalendar, parseCalendarDateValue, plainDateAdd, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -30,11 +30,8 @@ export function subtractDate(value, units, options) {
             return "";
         }
         const validDate = isValidCalendarDate(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDate || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateDurationUnit);
+        if (!validDate || amounts === null) {
             return "";
         }
         try {
@@ -43,7 +40,7 @@ export function subtractDate(value, units, options) {
                 return "";
             }
             const date = parseCalendarDateValue(value);
-            const result = plainDateAdd(date, Temporal.Duration.from(units).negated(), resolveOverflow(options?.overflow));
+            const result = plainDateAdd(date, Temporal.Duration.from(amounts).negated(), resolveOverflow(options?.overflow));
             return formatDateInCalendar(result, calendar);
         }
         catch {

package/dist/plain/calculate/subtractDateTime.js

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { readDurationUnits, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -24,17 +24,14 @@ export function subtractDateTime(value, units, options) {
             return "";
         }
         const validDateTime = isValidDateTime(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validDateTime || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validDateTime || amounts === null) {
             return "";
         }
         try {
             const dateTime = Temporal.PlainDateTime.from(value);
             return dateTime
-                .subtract(units, { overflow: resolveOverflow(options?.overflow) })
+                .subtract(amounts, { overflow: resolveOverflow(options?.overflow) })
                 .toString();
         }
         catch {

package/dist/plain/calculate/subtractTime.js

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