@northguild/gmt 1.18.0 → 1.19.0

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

@@ -24,8 +24,10 @@ export declare function parseDayOfWeekFromUnix(value: number | string, options?:
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `null`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseDayOfWeekFromUnix.js

@@ -1,4 +1,4 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of week (1-7) from a unix epoch value.
@@ -21,7 +21,7 @@ export function parseDayOfWeekFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        return unixZonedDateTime(value, options)?.dayOfWeek ?? null;
+        return unixWallClock(value, options)?.dayOfWeek ?? null;
     }
     catch {
         // Never throws (Core Rule 3): a hostile

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

@@ -23,8 +23,10 @@ export declare function parseHourFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -23,8 +23,10 @@ export declare function parseMicrosecondFromUnix(value: number | string, options
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -23,8 +23,10 @@ export declare function parseMillisecondFromUnix(value: number | string, options
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -23,8 +23,10 @@ export declare function parseMinuteFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -24,8 +24,10 @@ export declare function parseMonthFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -24,8 +24,10 @@ export declare function parseNanosecondFromUnix(value: number | string, options?
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -23,8 +23,10 @@ export declare function parseSecondFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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

@@ -14,6 +14,7 @@ import type { UnixUnit } from "../validate/index.js";
  * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
+ * @example parseTimeFromUnix(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function parseTimeFromUnix(value: number | string, options?: {
     /**
@@ -24,8 +25,10 @@ export declare function parseTimeFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseTimeFromUnix.js

@@ -1,4 +1,4 @@
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the time portion from a unix epoch value.
@@ -15,14 +15,15 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example parseTimeFromUnix(-86400, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
  * @example parseTimeFromUnix("1700000000", { epochUnit: "second" }) // "22:13:20" (digit string, UTC by default)
  * @example parseTimeFromUnix(1.5) // "" (not an integer epoch)
+ * @example parseTimeFromUnix(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function parseTimeFromUnix(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
-        return zdt === null ? "" : zdt.toPlainTime().toString();
+        const wallClock = unixWallClock(value, options);
+        return wallClock === null ? "" : wallClock.toPlainTime().toString();
     }
     catch {
         // Never throws (Core Rule 3): a hostile

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

@@ -8,7 +8,7 @@ import type { UnixUnit } from "../validate/index.js";
  *
  * | Member | Description |
  * | --- | --- |
- * | `year` | Full year, no padding (e.g. `2024`). |
+ * | `year` | Four digits (e.g. `2024`, `0005`); a sign and six digits outside 0000–9999 (e.g. `+010000`). |
  * | `month` | Zero-padded 2 (e.g. `03`). |
  * | `week` | Week-of-year, 1–53: ISO 8601 for `weekStartsOn: "monday"`, UTS #35 (minimal days 1) for `"sunday"`, so late-December days can be week 1. |
  * | `day` | Zero-padded 2. |
@@ -33,6 +33,8 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
@@ -40,6 +42,7 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(-61996320000000, "year") // "0005" (1 June of year 5)
  * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
  * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
  * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
@@ -47,6 +50,7 @@ export type PlainNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "ho
  * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
  * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
+ * @example parseUnitFromUnix(45870000, "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export declare function parseUnitFromUnix(value: number | string, unit: PlainNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     /**
@@ -57,8 +61,10 @@ export declare function parseUnitFromUnix(value: number | string, unit: PlainNow
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseUnitFromUnix.js

@@ -1,8 +1,9 @@
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Extract a unit from a unix epoch value.
  *
@@ -11,6 +12,8 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - `microsecond` and `nanosecond` are the 0–999 Temporal fields, zero-padded to 3 digits.
  * - Converts to ZonedDateTime then extracts the unit.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param unit unit to extract (e.g. "year", "month", "hour")
@@ -18,6 +21,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @returns extracted unit value as string, or "" on invalid input
  *
  * @example parseUnitFromUnix(1700000000000, "year") // "2023"
+ * @example parseUnitFromUnix(-61996320000000, "year") // "0005" (1 June of year 5)
  * @example parseUnitFromUnix(1700000000, "hour", { epochUnit: "seconds", timeZone: "UTC" }) // "22"
  * @example parseUnitFromUnix(1704067200000, "week", { timeZone: "UTC" }) // "1"
  * @example parseUnitFromUnix(1704067200000, "week", { weekStartsOn: "sunday", timeZone: "UTC" }) // "1"
@@ -25,6 +29,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example parseUnitFromUnix("1709217045123", "hours") // "14" (digit string, plural unit, UTC by default)
  * @example parseUnitFromUnix(1709217045123, "nanosecond") // "000"
  * @example parseUnitFromUnix("", "year") // "" (a blank string is not epoch 0)
+ * @example parseUnitFromUnix(45870000, "minute", { timeZone: "-00:44:30" }) // "00" (a stored offset with seconds)
  */
 export function parseUnitFromUnix(value, unit, options) {
     try {
@@ -32,36 +37,38 @@ export function parseUnitFromUnix(value, unit, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const zdt = unixZonedDateTime(value, options);
+        const wallClock = unixWallClock(value, options);
         const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
-        if (zdt === null || typeof unit !== "string" || weekStartsOn === null) {
+        if (wallClock === null ||
+            typeof unit !== "string" ||
+            weekStartsOn === null) {
             return "";
         }
         try {
             switch (resolveDateTimeUnit(unit)) {
                 case "year":
-                    return zdt.year.toString();
+                    return isoYearString(wallClock.year);
                 case "month":
-                    return zdt.month.toString().padStart(2, "0");
+                    return wallClock.month.toString().padStart(2, "0");
                 case "week": {
-                    return (getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
+                    return (getWeekNumber(wallClock.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
                 }
                 case "day":
-                    return zdt.day.toString().padStart(2, "0");
+                    return wallClock.day.toString().padStart(2, "0");
                 case "dayOfWeek":
-                    return zdt.dayOfWeek.toString();
+                    return wallClock.dayOfWeek.toString();
                 case "hour":
-                    return zdt.hour.toString().padStart(2, "0");
+                    return wallClock.hour.toString().padStart(2, "0");
                 case "minute":
-                    return zdt.minute.toString().padStart(2, "0");
+                    return wallClock.minute.toString().padStart(2, "0");
                 case "second":
-                    return zdt.second.toString().padStart(2, "0");
+                    return wallClock.second.toString().padStart(2, "0");
                 case "millisecond":
-                    return zdt.millisecond.toString().padStart(3, "0");
+                    return wallClock.millisecond.toString().padStart(3, "0");
                 case "microsecond":
-                    return zdt.microsecond.toString().padStart(3, "0");
+                    return wallClock.microsecond.toString().padStart(3, "0");
                 case "nanosecond":
-                    return zdt.nanosecond.toString().padStart(3, "0");
+                    return wallClock.nanosecond.toString().padStart(3, "0");
                 default:
                     return "";
             }

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

@@ -26,8 +26,9 @@ export declare function parseWeekFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the date is read in: an IANA name, a UTC offset, or `"local"` for the system
-     * time zone. An unknown zone returns `null`.
+     * The time zone the date is read in: an IANA name, a UTC offset (a time zone identifier such as
+     * `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what `getTimeZoneOffset`
+     * returns), or `"local"` for the system time zone. An unknown zone returns `null`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseWeekFromUnix.js

@@ -1,6 +1,6 @@
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
-import { unixZonedDateTime } from "../../internal/unixZonedDateTime.js";
+import { unixWallClock } from "../../internal/unixWallClock.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a unix epoch value.
@@ -26,12 +26,12 @@ export function parseWeekFromUnix(value, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        const zdt = unixZonedDateTime(value, options);
+        const wallClock = unixWallClock(value, options);
         const weekStartsOn = resolveWeekStartsOn(options?.weekStartsOn);
-        if (zdt === null || weekStartsOn === null)
+        if (wallClock === null || weekStartsOn === null)
             return null;
         try {
-            return getWeekNumber(zdt.toPlainDate().toString(), weekStartsOn);
+            return getWeekNumber(wallClock.toPlainDate().toString(), weekStartsOn);
         }
         catch {
             return null;

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

@@ -5,12 +5,15 @@ import type { UnixUnit } from "../validate/index.js";
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
  * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
+ * - The year is written as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param options optional: how `value` is read and the zone its wall clock is read in
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(-61996320000000) // "0005" (1 June of year 5)
  * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)
@@ -24,8 +27,10 @@ export declare function parseYearFromUnix(value: number | string, options?: {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/parse/parseYearFromUnix.js

@@ -6,12 +6,15 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Delegates to {@link parseUnitFromUnix} with unit "year".
  * - `value` is a safe integer or a digit string.
  * - Returns "" for invalid input.
+ * - The year is written as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value unix epoch in milliseconds or seconds: a safe integer, or a string of optionally negative ASCII digits
  * @param options optional: how `value` is read and the zone its wall clock is read in
- * @returns Year (YYYY) or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromUnix(1700000000000) // "2023"
+ * @example parseYearFromUnix(-61996320000000) // "0005" (1 June of year 5)
  * @example parseYearFromUnix(1704067200000, { epochUnit: "milliseconds", timeZone: "UTC" }) // "2024"
  * @example parseYearFromUnix(-86400, { epochUnit: "seconds" }) // "1969"
  * @example parseYearFromUnix("") // "" (a blank string is not epoch 0)

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

@@ -15,7 +15,7 @@
  * import { isValidUnixUnit } from "@northguild/gmt/unix";
  * isValidUnixUnit("milliseconds"); // true
  */
-export type UnixUnit = "seconds" | "second" | "milliseconds" | "millisecond";
+export type UnixUnit = "seconds" | "milliseconds" | "second" | "millisecond";
 /**
  * Return true when `unit` is a valid UnixUnit.
  *

package/dist/utc/calculate/addUtc.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 { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -26,17 +26,14 @@ export function addUtc(value, units, options) {
             return "";
         }
         const validUtc = isValidUtc(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUtc || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validUtc || amounts === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            const result = zoned.add(units, {
+            const result = zoned.add(amounts, {
                 overflow: resolveOverflow(options?.overflow),
             });
             return result.toInstant().toString();

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

@@ -9,8 +9,20 @@ import type { Overflow } from "../../types/index.js";
  *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
  *   resolution matters.
  * - `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, an `offset`, 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.
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
@@ -24,9 +36,10 @@ import type { Overflow } from "../../types/index.js";
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
  * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: "9" }) // "" (not converted)
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
-export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+export declare function setUtc(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset" | "era" | "eraYear">, options?: {
     /**
      * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
      * so `month: 2` on Jan 31 is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.

package/dist/utc/calculate/setUtc.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 { isValidUtc } from "../validate/isValidUtc.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -11,8 +11,20 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   `addUtc()` calls field-by-field — see `setDate`'s doc for why order-independent field
  *   resolution matters.
  * - `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, an `offset`, 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.
  * - There are no `disambiguation` or `offset` options (removed in 1.16.0): a UTC instant's wall
  *   clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
  * - Returns "" for invalid input.
@@ -26,6 +38,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }) // "2024-02-29T12:00:00Z" (constrain clamps to the last valid day)
  * @example setUtc("2024-01-31T12:00:00Z", { month: 2 }, { overflow: "reject" }) // ""
  * @example setUtc("2024-03-10T12:00:00Z", {}) // "2024-03-10T12:00:00Z" (empty fields object is a no-op)
+ * @example setUtc("2024-03-10T12:00:00Z", { hour: "9" }) // "" (not converted)
  * @example setUtc("invalid", { hour: 9 }) // ""
  */
 export function setUtc(value, fields, options) {
@@ -39,11 +52,12 @@ export function setUtc(value, fields, options) {
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
-            // properties found") rather than treating it as a no-op, so short-circuit here.
-            const result = Object.keys(fields).length === 0
-                ? zoned
-                : zoned.with(fields, { overflow });
+            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.
+            const result = Object.keys(set).length === 0 ? zoned : zoned.with(set, { overflow });
             return result.toInstant().toString();
         }
         catch {

package/dist/utc/calculate/subtractUtc.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 { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -26,17 +26,14 @@ export function subtractUtc(value, units, options) {
             return "";
         }
         const validUtc = isValidUtc(value);
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUtc || !validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (!validUtc || amounts === null) {
             return "";
         }
         try {
             const instant = Temporal.Instant.from(value);
             const zoned = instant.toZonedDateTimeISO("UTC");
-            const result = zoned.subtract(units, {
+            const result = zoned.subtract(amounts, {
                 overflow: resolveOverflow(options?.overflow),
             });
             return result.toInstant().toString();

package/dist/utc/convert/convertUtcToPlainDate.d.ts

@@ -2,6 +2,8 @@
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
  * - Converts to the `timeZone` option's zone before extracting the date.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDate` accepts.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
@@ -11,11 +13,15 @@
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z") // "2024-02-29"
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28"
  * @example convertUtcToPlainDate("invalid") // ""
+ * @example convertUtcToPlainDate("+010000-01-01T00:00:00Z") // "+010000-01-01" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDate("1970-01-01T00:30:00Z", { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainDate(value: string, options?: {
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */