@northguild/gmt 1.14.2 → 1.16.0

package/dist/zoned/calculate/getLocaleZonedStartOfWeek.js

@@ -1,68 +1,62 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
+import { getLocaleFirstDayOfWeek, zonedDateTimeFrom, zonedUnitStart, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the start of the week containing `value`, using `locale`'s
  * first day of week (e.g. en-US: Sunday, fr-FR: Monday).
  *
  * - Resolves the locale's first day of week via
- *   `Intl.Locale.prototype.weekInfo`, then resets the local time-of-day to
- *   midnight.
+ *   `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
  *   a first day for the locale.
- * - `disambiguation` controls DST gap/overlap resolution when the
- *   midnight reset lands on an ambiguous local time: "compatible"
- *   (default, matches Temporal's default), "earlier", "later", or
- *   "reject" (throws, resulting in "").
- * - `offset` controls whether the source's existing UTC offset is kept
- *   when resetting to midnight: "prefer" (Temporal's own default — keeps
- *   the source offset whenever still valid, which **makes
- *   `disambiguation` inert** for almost every case here), "use", "ignore"
- *   (**this function's default** — always recomputes from time zone +
- *   local time, discarding the stale offset; this is what makes
- *   `disambiguation` actually take effect), or "reject" (throws if the
- *   source offset is invalid for the new fields, independent of
- *   `disambiguation`). Leave `offset` at its default unless you
- *   specifically need Temporal's raw `.with()` semantics.
+ * - Returns the real start of the local week containing `value` in its own
+ *   zone — the same kind of bucket `floorToZone` uses — so the result is
+ *   never after `value`. A week whose first midnight was skipped starts at
+ *   its first real instant.
  * - Distinct from `startOfZoned(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
- * - Returns "" if `value` or `locale` is invalid.
+ * - Returns "" if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
- * @param options optional: fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
+ * @param options optional: fractionalSecondDigits (number)
  * @returns zoned ISO 8601 string for the start of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US") // "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
  * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR") // "2024-02-26T00:00:00+00:00[UTC]" (Monday)
+ * @example getLocaleZonedStartOfWeek("2024-09-11T12:00:00-03:00[America/Santiago]", "en-US") // "2024-09-08T01:00:00-03:00[America/Santiago]" (that Sunday's midnight was skipped)
  * @example getLocaleZonedStartOfWeek("invalid", "en-US") // ""
- * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale") // ""
+ * @example getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "not-a-locale-!!") // ""
+ * @example getLocaleZonedStartOfWeek("2024-05-15T12:00:00+02:00[Europe/Berlin]", ["en-US", "fr-FR"]) // "2024-05-12T00:00:00+02:00[Europe/Berlin]"
  */
 export function getLocaleZonedStartOfWeek(value, locale, optionsArg) {
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits ?? 0;
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    if (!isValidZonedDateTime(value))
-        return "";
-    const firstDay = getLocaleFirstDayOfWeek(locale);
-    if (firstDay === null)
-        return "";
     try {
-        const source = Temporal.ZonedDateTime.from(value);
-        const daysToSubtract = (source.dayOfWeek - firstDay + 7) % 7;
-        const startOfWeekDate = source.subtract({ days: daysToSubtract });
-        const result = startOfWeekDate.with({
-            hour: 0,
-            minute: 0,
-            second: 0,
-            millisecond: 0,
-            microsecond: 0,
-            nanosecond: 0,
-        }, { disambiguation, offset });
-        return result.toString({ fractionalSecondDigits });
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
+            ? 0
+            : optionsArg.fractionalSecondDigits;
+        if (!isValidZonedDateTime(value))
+            return "";
+        const firstDay = getLocaleFirstDayOfWeek(locale);
+        if (firstDay === null)
+            return "";
+        try {
+            const start = zonedUnitStart(zonedDateTimeFrom(value), "week", firstDay);
+            return start ? start.toString({ fractionalSecondDigits }) : "";
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/calculate/getQuarterForZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the quarter of the year (1-4) for a given zoned ISO datetime.
  *
@@ -19,7 +19,7 @@ export function getQuarterForZoned(value) {
         return null;
     }
     try {
-        const zdt = Temporal.ZonedDateTime.from(value);
+        const zdt = zonedDateTimeFrom(value);
         return Math.floor((zdt.month - 1) / 3) + 1;
     }
     catch {

package/dist/zoned/calculate/maxZoned.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the latest (maximum) of the given ZonedDateTime values.
  *
@@ -15,21 +16,28 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @example maxZoned([]) // null
  */
 export function maxZoned(zonedDateTimes) {
-    if (!zonedDateTimes.length)
-        return null;
-    const valid = zonedDateTimes.filter(isValidZonedDateTime);
-    if (!valid.length)
-        return null;
     try {
-        const max = valid.reduce((currentMax, candidateStr) => {
-            const candidate = Temporal.ZonedDateTime.from(candidateStr);
-            return Temporal.ZonedDateTime.compare(candidate, currentMax) > 0
-                ? candidate
-                : currentMax;
-        }, Temporal.ZonedDateTime.from(valid[0]));
-        return max.toString();
+        if (!Array.isArray(zonedDateTimes) || !zonedDateTimes.length)
+            return null;
+        const valid = zonedDateTimes.filter(isValidZonedDateTime);
+        if (!valid.length)
+            return null;
+        try {
+            const max = valid.reduce((currentMax, candidateStr) => {
+                const candidate = zonedDateTimeFrom(candidateStr);
+                return Temporal.ZonedDateTime.compare(candidate, currentMax) > 0
+                    ? candidate
+                    : currentMax;
+            }, zonedDateTimeFrom(valid[0]));
+            return max.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/zoned/calculate/minZoned.d.ts

@@ -7,7 +7,7 @@
  * @param zonedDateTimes Array of ISO ZonedDateTime strings
  * @returns The earliest zoned datetime string, or null on invalid input
  *
- * @example minZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-10T12:00:00-05:00[America/New_York]"
+ * @example minZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-10T12:00:00-04:00[America/New_York]"
  * @example minZoned(["invalid", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
  * @example minZoned(["invalid", "also invalid"]) // null
  * @example minZoned([]) // null

package/dist/zoned/calculate/minZoned.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the earliest (minimum) of the given ZonedDateTime values.
  *
@@ -9,27 +10,34 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @param zonedDateTimes Array of ISO ZonedDateTime strings
  * @returns The earliest zoned datetime string, or null on invalid input
  *
- * @example minZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-10T12:00:00-05:00[America/New_York]"
+ * @example minZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-10T12:00:00-04:00[America/New_York]"
  * @example minZoned(["invalid", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
  * @example minZoned(["invalid", "also invalid"]) // null
  * @example minZoned([]) // null
  */
 export function minZoned(zonedDateTimes) {
-    if (!zonedDateTimes.length)
-        return null;
-    const valid = zonedDateTimes.filter(isValidZonedDateTime);
-    if (!valid.length)
-        return null;
     try {
-        const min = valid.reduce((currentMin, candidateStr) => {
-            const candidate = Temporal.ZonedDateTime.from(candidateStr);
-            return Temporal.ZonedDateTime.compare(candidate, currentMin) < 0
-                ? candidate
-                : currentMin;
-        }, Temporal.ZonedDateTime.from(valid[0]));
-        return min.toString();
+        if (!Array.isArray(zonedDateTimes) || !zonedDateTimes.length)
+            return null;
+        const valid = zonedDateTimes.filter(isValidZonedDateTime);
+        if (!valid.length)
+            return null;
+        try {
+            const min = valid.reduce((currentMin, candidateStr) => {
+                const candidate = zonedDateTimeFrom(candidateStr);
+                return Temporal.ZonedDateTime.compare(candidate, currentMin) < 0
+                    ? candidate
+                    : currentMin;
+            }, zonedDateTimeFrom(valid[0]));
+            return min.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/zoned/calculate/roundZoned.d.ts

@@ -4,16 +4,30 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - Returns "" for invalid inputs.
  * - Accepts "day" and time units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return "".
+ * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both.
+ * - Date units ("year", "month", "week") return "". This is the Temporal spec, not a polyfill
+ *   limitation: `ZonedDateTime.prototype.round` accepts time units and "day" only
+ *   (ValidateTemporalUnitValue with ~time~ and « day »).
  * - Wraps Temporal.ZonedDateTime.round() which throws on invalid options.
- * - Note: The polyfill's `.round()` does not support `disambiguation` or `offset` options.
+ * - Output precision follows `smallestUnit`: no fractional seconds for "day", "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.
+ * - Note: Temporal's `ZonedDateTime.prototype.round` takes no `disambiguation` or `offset` options.
+ * - Follows TC39 `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the
+ *   zone. Across a transition the result can land after the input or on another local date —
+ *   `Pacific/Chatham` "2024-09-29T03:50:00+13:45" truncated to the hour gives 04:00+13:45, 15
+ *   minutes later. Use `floorToZone` for a boundary that never exceeds the instant.
  *
  * @param value ISO 8601 zoned datetime string
  * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode
  * @returns Rounded ISO 8601 zoned datetime string, or "" on invalid input
  *
- * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-05:00[America/New_York]"
- * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00-05:00[America/New_York]"
+ * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-04:00[America/New_York]"
+ * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example roundZoned("2024-09-29T03:50:00+13:45[Pacific/Chatham]", { smallestUnit: "hour", roundingMode: "trunc" }) // "2024-09-29T04:00:00+13:45[Pacific/Chatham]" (after the input — TC39 wall-clock rounding)
+ * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hours" }) // "2024-06-15T13:00:00-04:00[America/New_York]" (plural unit name)
+ * @example roundZoned("2024-06-15T12:34:56.123456789-04:00[America/New_York]", { smallestUnit: "millisecond" }) // "2024-06-15T12:34:56.123-04:00[America/New_York]" (precision follows the unit)
  * @example roundZoned("invalid", { smallestUnit: "hour" }) // ""
  */
 export declare function roundZoned(value: string, options: {

package/dist/zoned/calculate/roundZoned.js

@@ -1,55 +1,80 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
+import { defaultFractionalDigits, isObject, resolveDateTimeUnit, roundZonedDateTime, zonedDateTimeFrom, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+const ZONED_ROUNDING_UNITS = [
+    "day",
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+function isZonedRoundingUnit(unit) {
+    return ZONED_ROUNDING_UNITS.includes(unit);
+}
 /**
  * Round an ISO 8601 zoned datetime string to the specified unit.
  *
  * - Returns "" for invalid inputs.
  * - Accepts "day" and time units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return "".
+ * - Each unit is accepted in its singular or plural form ("day" or "days"), as Temporal's
+ *   GetTemporalUnitValuedOption accepts both.
+ * - Date units ("year", "month", "week") return "". This is the Temporal spec, not a polyfill
+ *   limitation: `ZonedDateTime.prototype.round` accepts time units and "day" only
+ *   (ValidateTemporalUnitValue with ~time~ and « day »).
  * - Wraps Temporal.ZonedDateTime.round() which throws on invalid options.
- * - Note: The polyfill's `.round()` does not support `disambiguation` or `offset` options.
+ * - Output precision follows `smallestUnit`: no fractional seconds for "day", "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.
+ * - Note: Temporal's `ZonedDateTime.prototype.round` takes no `disambiguation` or `offset` options.
+ * - Follows TC39 `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the
+ *   zone. Across a transition the result can land after the input or on another local date —
+ *   `Pacific/Chatham` "2024-09-29T03:50:00+13:45" truncated to the hour gives 04:00+13:45, 15
+ *   minutes later. Use `floorToZone` for a boundary that never exceeds the instant.
  *
  * @param value ISO 8601 zoned datetime string
  * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode
  * @returns Rounded ISO 8601 zoned datetime string, or "" on invalid input
  *
- * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-05:00[America/New_York]"
- * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00-05:00[America/New_York]"
+ * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-04:00[America/New_York]"
+ * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example roundZoned("2024-09-29T03:50:00+13:45[Pacific/Chatham]", { smallestUnit: "hour", roundingMode: "trunc" }) // "2024-09-29T04:00:00+13:45[Pacific/Chatham]" (after the input — TC39 wall-clock rounding)
+ * @example roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hours" }) // "2024-06-15T13:00:00-04:00[America/New_York]" (plural unit name)
+ * @example roundZoned("2024-06-15T12:34:56.123456789-04:00[America/New_York]", { smallestUnit: "millisecond" }) // "2024-06-15T12:34:56.123-04:00[America/New_York]" (precision follows the unit)
  * @example roundZoned("invalid", { smallestUnit: "hour" }) // ""
  */
 export function roundZoned(value, options) {
-    const { smallestUnit, roundingIncrement, roundingMode } = options;
-    if (!isValidZonedDateTime(value))
-        return "";
-    // Polyfill limitation: year/month/week not supported for ZonedDateTime.round()
-    const supportedUnits = [
-        "day",
-        "hour",
-        "minute",
-        "second",
-        "millisecond",
-        "microsecond",
-        "nanosecond",
-    ];
-    if (!supportedUnits.includes(smallestUnit))
-        return "";
     try {
-        const source = Temporal.ZonedDateTime.from(value);
-        const result = source.round({
-            smallestUnit,
-            roundingIncrement,
-            roundingMode,
-        });
-        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = precisionMap[smallestUnit] || 0;
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
+        if (!isObject(options))
+            return "";
+        const { roundingIncrement, roundingMode } = options;
+        const smallestUnit = typeof options.smallestUnit === "string"
+            ? resolveDateTimeUnit(options.smallestUnit)
+            : options.smallestUnit;
+        if (!isValidZonedDateTime(value))
+            return "";
+        // Temporal ZonedDateTime.prototype.round: ValidateTemporalUnitValue(smallestUnit, ~time~, « day »)
+        if (!isZonedRoundingUnit(smallestUnit))
+            return "";
+        try {
+            const source = zonedDateTimeFrom(value);
+            const result = roundZonedDateTime(source, {
+                smallestUnit,
+                roundingIncrement,
+                roundingMode,
+            });
+            const fractionalDigits = defaultFractionalDigits(smallestUnit);
+            return result.toString({ fractionalSecondDigits: fractionalDigits });
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/calculate/setZoned.d.ts

@@ -17,19 +17,25 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
  *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
  *   (resulting in "").
+ * - `offset` defaults to `"prefer"`, as Temporal's `ZonedDateTime#with` does: when the source's
+ *   offset is still valid for the new wall time (a repeated fall-back hour), it is kept and
+ *   `disambiguation` is not consulted; pass `offset: "ignore"` to re-resolve the wall time through
+ *   `disambiguation` instead. In a gap the source offset cannot hold, so `disambiguation` applies.
+ * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
+ *   to keep that resolution.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
  * @returns zoned ISO 8601 string with fields set, or "" on invalid input
  *
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
  * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }) // "2024-02-29T12:00:00-05:00[America/New_York]" (constrain clamps to the last valid day)
  * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }, { overflow: "reject" }) // ""
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
- * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "" (offset defaults to "ignore", so disambiguation actually fires and "reject" throws on this fall-back overlap)
- * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset:"prefer" makes disambiguation inert here — the source's -05:00 offset is still valid, so it's kept and "reject" never fires)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset defaults to "prefer": the source's -05:00 is still valid, so it is kept and "reject" never fires)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "ignore" }) // "" (offset "ignore" re-resolves the repeated 01:00, and "reject" throws)
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
 export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {

package/dist/zoned/calculate/setZoned.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveOverflow } from "../../internal/index.js";
+import { resolveOverflow, withZonedFields, zonedDateTimeFrom, } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a zoned ISO 8601 datetime string with the given `fields` set on `value`.
  *
@@ -18,39 +19,59 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
  *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
  *   (resulting in "").
+ * - `offset` defaults to `"prefer"`, as Temporal's `ZonedDateTime#with` does: when the source's
+ *   offset is still valid for the new wall time (a repeated fall-back hour), it is kept and
+ *   `disambiguation` is not consulted; pass `offset: "ignore"` to re-resolve the wall time through
+ *   `disambiguation` instead. In a gap the source offset cannot hold, so `disambiguation` applies.
+ * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
+ *   to keep that resolution.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
- * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
  * @returns zoned ISO 8601 string with fields set, or "" on invalid input
  *
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
  * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }) // "2024-02-29T12:00:00-05:00[America/New_York]" (constrain clamps to the last valid day)
  * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }, { overflow: "reject" }) // ""
  * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
- * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "" (offset defaults to "ignore", so disambiguation actually fires and "reject" throws on this fall-back overlap)
- * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset:"prefer" makes disambiguation inert here — the source's -05:00 offset is still valid, so it's kept and "reject" never fires)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset defaults to "prefer": the source's -05:00 is still valid, so it is kept and "reject" never fires)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "ignore" }) // "" (offset "ignore" re-resolves the repeated 01:00, and "reject" throws)
  * @example setZoned("invalid", { hour: 9 }) // ""
  */
 export function setZoned(value, fields, options) {
-    if (!isValidZonedDateTime(value))
-        return "";
-    const overflow = resolveOverflow(options?.overflow);
-    const disambiguation = options?.disambiguation ?? "compatible";
-    // "ignore" (not Temporal's own "prefer" default) so `disambiguation` actually takes effect —
-    // see C3 / docs/dst-disambiguation.md: with "prefer", the source's still-valid offset is kept
-    // and disambiguation is silently never consulted.
-    const offset = options?.offset ?? "ignore";
     try {
-        const zoned = Temporal.ZonedDateTime.from(value);
-        // 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.
-        if (Object.keys(fields).length === 0)
-            return zoned.toString();
-        return zoned.with(fields, { overflow, disambiguation, offset }).toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        if (!isValidZonedDateTime(value))
+            return "";
+        const overflow = resolveOverflow(options?.overflow);
+        const disambiguation = options?.disambiguation === undefined
+            ? "compatible"
+            : options.disambiguation;
+        // Temporal ZonedDateTime#with's own default: keep the source offset while it is still valid.
+        const offset = options?.offset === undefined ? "prefer" : options.offset;
+        try {
+            const zoned = zonedDateTimeFrom(value);
+            // 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.
+            if (Object.keys(fields).length === 0)
+                return zoned.toString();
+            return withZonedFields(zoned, fields, {
+                overflow,
+                disambiguation,
+                offset,
+            }).toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/calculate/sortZoned.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Sort an array of ZonedDateTime values in ascending or descending order.
  *
@@ -17,20 +18,27 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @example sortZoned([]) // []
  */
 export function sortZoned(zonedDateTimes, order = "asc") {
-    if (!zonedDateTimes.length)
-        return [];
-    const valid = zonedDateTimes.filter(isValidZonedDateTime);
-    if (!valid.length)
-        return [];
     try {
-        const comparables = valid.map((d) => Temporal.ZonedDateTime.from(d));
-        comparables.sort(Temporal.ZonedDateTime.compare);
-        if (order === "desc") {
-            return comparables.reverse().map((d) => d.toString());
+        if (!Array.isArray(zonedDateTimes) || !zonedDateTimes.length)
+            return [];
+        const valid = zonedDateTimes.filter(isValidZonedDateTime);
+        if (!valid.length)
+            return [];
+        try {
+            const comparables = valid.map((d) => zonedDateTimeFrom(d));
+            comparables.sort(Temporal.ZonedDateTime.compare);
+            if (order === "desc") {
+                return comparables.reverse().map((d) => d.toString());
+            }
+            return comparables.map((d) => d.toString());
+        }
+        catch {
+            return [];
         }
-        return comparables.map((d) => d.toString());
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/zoned/calculate/startOfQuarterForZoned.d.ts

@@ -1,15 +1,14 @@
-import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the start of the quarter for a given zoned ISO datetime.
  *
- * - Calculates which quarter (1-4) the date falls into and returns the first day of that quarter.
- * - `disambiguation` controls DST gap/overlap resolution when the quarter-start boundary lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
- * - `offset` controls whether the source's existing UTC offset is kept when computing the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** in the (rare) common-zone case since quarter boundaries don't fall on DST transitions), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect where a quarter boundary does coincide with a transition), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Calculates which quarter (1-4) the date falls into and returns the first instant of that quarter, with every field below the day reset — milliseconds, microseconds and nanoseconds included.
+ * - Returns the real start of the local quarter in `value`'s own zone (see `floorToZone`), so the result is never after `value`: a skipped first midnight starts at the quarter's first real instant, and a repeated one (`Africa/Tunis`, 1978-10-01) at its first pass.
  * - `fractionalSecondDigits` controls how many fractional seconds are included in the output: 0 (default — no fractional seconds), 3 (milliseconds), 6 (microseconds), or 9 (nanoseconds).
  * - Validation is performed on the input.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore"), fractionalSecondDigits (0 | 3 | 6 | 9, default 0)
+ * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 0)
  * @returns ISO ZonedDateTime string for the start of the quarter, or "" on invalid input
  *
  * @example startOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-01-01T00:00:00+00:00[UTC]"
@@ -19,7 +18,5 @@ import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.
  * @example startOfQuarterForZoned("invalid") // ""
  */
 export declare function startOfQuarterForZoned(value: string, optionsArg?: {
-    disambiguation?: Disambiguation;
-    offset?: Offset;
     fractionalSecondDigits?: FractionalDigit;
 }): string;