@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/splitStep.d.ts

@@ -0,0 +1,81 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Consecutive split steps allowed to resolve to the previous boundary before a split gives up.
+ *
+ * A deleted local day costs one skipped step; the cap only stops a zone (or a stub) that never
+ * advances from looping forever.
+ */
+export declare const MAX_STALLED_SPLIT_STEPS = 8;
+/**
+ * Whether a plural duration unit is an exact time unit (hours and smaller).
+ *
+ * - Exact units never clamp, so split functions step them from the previous boundary.
+ * - Calendar units (`years`, `months`, `weeks`, `days`) return `false` and stay anchored to the
+ *   interval start.
+ *
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @returns `true` for `hours` through `nanoseconds`, otherwise `false`
+ *
+ * @example isExactDurationUnit("hours") // true
+ * @example isExactDurationUnit("days") // false
+ * @example isExactDurationUnit("hour") // false
+ */
+export declare function isExactDurationUnit(unit: string): boolean;
+/**
+ * Tile `[start, end)` into `amount × unit` steps for one Temporal type.
+ *
+ * - Calendar units are anchored: boundary k is `start.add({ [unit]: amount × k })`, so month-end
+ *   starts don't drift.
+ * - Exact units step from the previous boundary (`previous.add({ [unit]: amount })`), which never
+ *   clamps and avoids `amount × k` passing `Number.MAX_SAFE_INTEGER`.
+ * - A step equal to the previous boundary is skipped (a deleted local day); more than
+ *   `MAX_STALLED_SPLIT_STEPS` in a row returns `null`.
+ * - A step that goes backwards returns `null`.
+ * - More than `maxSlices` slices returns `null` as soon as the next one is due, so the work stays
+ *   bounded by the limit (owner decision A2, CORE-8).
+ * - The last slice's end is trimmed to `end`. Callers handle `start >= end` before calling.
+ * - A step that throws a RangeError (it lands past Temporal's last representable value, so after
+ *   `end`) closes the split with a last slice ending at `end`.
+ *
+ * Generic over the value type only — each caller passes its own Temporal type and comparator, so
+ * plain, zoned and instant values are never mixed.
+ *
+ * @param start interval start
+ * @param end interval end, strictly after `start`
+ * @param compare the Temporal type's `compare`
+ * @param unit plural duration unit
+ * @param amount positive number of units per step
+ * @param maxSlices most slices to build; one more returns `null` before it is built
+ * @param add how a duration is added to a value (default `value.add(duration)`; the plain date
+ *   caller passes its calendar-correct add)
+ * @returns `[sliceStart, sliceEnd]` pairs, or `null` when stepping goes backwards, stalls, or
+ *   would build more than `maxSlices`
+ *
+ * @example tileByUnit(Temporal.PlainDate.from("2024-01-01"), Temporal.PlainDate.from("2024-01-04"), Temporal.PlainDate.compare, "days", 2, 100) // [[2024-01-01, 2024-01-03], [2024-01-03, 2024-01-04]]
+ * @example tileByUnit(Temporal.PlainDate.from("2024-01-01"), Temporal.PlainDate.from("2024-01-04"), Temporal.PlainDate.compare, "hours", 1, 100) // null (PlainDate ignores hours, so no step advances)
+ */
+export declare function tileByUnit<T extends {
+    add(duration: Temporal.DurationLike): T;
+}>(start: T, end: T, compare: (a: T, b: T) => number, unit: string, amount: number, maxSlices: number, add?: (value: T, duration: Temporal.DurationLike) => T): Array<[T, T]> | null;
+/**
+ * A lower bound on the number of slices `tileByUnit` returns for a span, without stepping.
+ *
+ * - Exact units (hours and smaller) never clamp or stall: the bound is `ceil(span / step)`.
+ * - Calendar units step at most `amount ×` the longest unit, so reaching `end` takes at least
+ *   `ceil(span / longest step)` steps.
+ * - `zoned` values may also shift by an offset change (under 48 hours) and may stall up to
+ *   `MAX_STALLED_SPLIT_STEPS` steps in a row, so only one step in `MAX_STALLED_SPLIT_STEPS + 1`
+ *   is guaranteed to be a slice.
+ * - Callers compare the bound with `maxPieces` to return the sentinel before building a huge split;
+ *   `tileByUnit`'s own `maxSlices` settles counts the bound cannot.
+ *
+ * @param spanNs exact span between start and end, in nanoseconds
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @param amount units per step
+ * @param zoned whether the values carry a time zone with offset transitions
+ * @returns a count no greater than the slices `tileByUnit` would build (0 when unknown)
+ *
+ * @example minSlicesForSpan(3 * 3_600_000_000_000, "hours", 1, false) // 3
+ * @example minSlicesForSpan(62 * 86_400_000_000_000, "months", 1, false) // 2
+ */
+export declare function minSlicesForSpan(spanNs: number, unit: string, amount: number, zoned: boolean): number;

package/dist/internal/splitStep.js

@@ -0,0 +1,182 @@
+import { Temporal } from "@js-temporal/polyfill";
+const EXACT_DURATION_UNITS = new Set([
+    "hours",
+    "minutes",
+    "seconds",
+    "milliseconds",
+    "microseconds",
+    "nanoseconds",
+]);
+/**
+ * Consecutive split steps allowed to resolve to the previous boundary before a split gives up.
+ *
+ * A deleted local day costs one skipped step; the cap only stops a zone (or a stub) that never
+ * advances from looping forever.
+ */
+export const MAX_STALLED_SPLIT_STEPS = 8;
+/**
+ * Whether a plural duration unit is an exact time unit (hours and smaller).
+ *
+ * - Exact units never clamp, so split functions step them from the previous boundary.
+ * - Calendar units (`years`, `months`, `weeks`, `days`) return `false` and stay anchored to the
+ *   interval start.
+ *
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @returns `true` for `hours` through `nanoseconds`, otherwise `false`
+ *
+ * @example isExactDurationUnit("hours") // true
+ * @example isExactDurationUnit("days") // false
+ * @example isExactDurationUnit("hour") // false
+ */
+export function isExactDurationUnit(unit) {
+    return EXACT_DURATION_UNITS.has(unit);
+}
+/**
+ * `add(value, duration)`, or null when a valid duration throws a RangeError — the result lies past
+ * Temporal's representable range. An invalid duration (a fraction, an out-of-range amount) rethrows.
+ */
+function stepWithinRange(add, value, duration) {
+    try {
+        return add(value, duration);
+    }
+    catch (error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        Temporal.Duration.from(duration);
+        return null;
+    }
+}
+/**
+ * The split when a step lands past Temporal's last representable value, so after `end` (which is
+ * representable): the remaining span is the last slice, unless that would exceed `maxSlices`.
+ */
+function closedAtRangeLimit(slices, current, end, maxSlices) {
+    if (slices.length === maxSlices)
+        return null;
+    slices.push([current, end]);
+    return slices;
+}
+/**
+ * Tile `[start, end)` into `amount × unit` steps for one Temporal type.
+ *
+ * - Calendar units are anchored: boundary k is `start.add({ [unit]: amount × k })`, so month-end
+ *   starts don't drift.
+ * - Exact units step from the previous boundary (`previous.add({ [unit]: amount })`), which never
+ *   clamps and avoids `amount × k` passing `Number.MAX_SAFE_INTEGER`.
+ * - A step equal to the previous boundary is skipped (a deleted local day); more than
+ *   `MAX_STALLED_SPLIT_STEPS` in a row returns `null`.
+ * - A step that goes backwards returns `null`.
+ * - More than `maxSlices` slices returns `null` as soon as the next one is due, so the work stays
+ *   bounded by the limit (owner decision A2, CORE-8).
+ * - The last slice's end is trimmed to `end`. Callers handle `start >= end` before calling.
+ * - A step that throws a RangeError (it lands past Temporal's last representable value, so after
+ *   `end`) closes the split with a last slice ending at `end`.
+ *
+ * Generic over the value type only — each caller passes its own Temporal type and comparator, so
+ * plain, zoned and instant values are never mixed.
+ *
+ * @param start interval start
+ * @param end interval end, strictly after `start`
+ * @param compare the Temporal type's `compare`
+ * @param unit plural duration unit
+ * @param amount positive number of units per step
+ * @param maxSlices most slices to build; one more returns `null` before it is built
+ * @param add how a duration is added to a value (default `value.add(duration)`; the plain date
+ *   caller passes its calendar-correct add)
+ * @returns `[sliceStart, sliceEnd]` pairs, or `null` when stepping goes backwards, stalls, or
+ *   would build more than `maxSlices`
+ *
+ * @example tileByUnit(Temporal.PlainDate.from("2024-01-01"), Temporal.PlainDate.from("2024-01-04"), Temporal.PlainDate.compare, "days", 2, 100) // [[2024-01-01, 2024-01-03], [2024-01-03, 2024-01-04]]
+ * @example tileByUnit(Temporal.PlainDate.from("2024-01-01"), Temporal.PlainDate.from("2024-01-04"), Temporal.PlainDate.compare, "hours", 1, 100) // null (PlainDate ignores hours, so no step advances)
+ */
+export function tileByUnit(start, end, compare, unit, amount, maxSlices, add = (value, duration) => value.add(duration)) {
+    // Exact units step from the previous boundary; calendar units stay anchored to `start`.
+    const stepAfter = isExactDurationUnit(unit)
+        ? (current) => stepWithinRange(add, current, { [unit]: amount })
+        : (_current, step) => stepWithinRange(add, start, { [unit]: amount * step });
+    const slices = [];
+    for (let step = 1, stalled = 0, current = start; compare(current, end) < 0; step++) {
+        const next = stepAfter(current, step);
+        if (next === null) {
+            return closedAtRangeLimit(slices, current, end, maxSlices);
+        }
+        const order = compare(next, current);
+        if (order === 0) {
+            stalled++;
+            if (stalled > MAX_STALLED_SPLIT_STEPS)
+                return null;
+            continue;
+        }
+        if (order < 0 || slices.length === maxSlices) {
+            return null;
+        }
+        stalled = 0;
+        slices.push([current, compare(next, end) > 0 ? end : next]);
+        current = next;
+    }
+    return slices;
+}
+const NANOSECONDS_PER_DAY = 86_400_000_000_000;
+/**
+ * The longest a single unit can be, in nanoseconds.
+ *
+ * Exact units are fixed. A calendar month is at most 31 days in every CLDR calendar, and a
+ * calendar year at most 385 days (a Hebrew or Chinese leap year).
+ */
+const LONGEST_UNIT_NANOSECONDS = {
+    nanoseconds: 1,
+    microseconds: 1_000,
+    milliseconds: 1_000_000,
+    seconds: 1_000_000_000,
+    minutes: 60_000_000_000,
+    hours: 3_600_000_000_000,
+    days: NANOSECONDS_PER_DAY,
+    weeks: 7 * NANOSECONDS_PER_DAY,
+    months: 31 * NANOSECONDS_PER_DAY,
+    years: 385 * NANOSECONDS_PER_DAY,
+};
+/**
+ * A zoned boundary can sit this far from its wall-clock distance: a UTC offset lies strictly
+ * within ±24 hours (Temporal IsOffsetTimeZoneIdentifier / ECMA-262 time zone offset range), so
+ * two offsets differ by less than 48 hours.
+ */
+const ZONE_OFFSET_SLACK_NANOSECONDS = 2 * NANOSECONDS_PER_DAY;
+/**
+ * Guards the floating-point quotient so a lower bound is never rounded above the true count: the
+ * span, the step and their quotient each carry at most half an ulp of rounding error.
+ */
+const QUOTIENT_TOLERANCE = 1 - 8 * Number.EPSILON;
+/**
+ * A lower bound on the number of slices `tileByUnit` returns for a span, without stepping.
+ *
+ * - Exact units (hours and smaller) never clamp or stall: the bound is `ceil(span / step)`.
+ * - Calendar units step at most `amount ×` the longest unit, so reaching `end` takes at least
+ *   `ceil(span / longest step)` steps.
+ * - `zoned` values may also shift by an offset change (under 48 hours) and may stall up to
+ *   `MAX_STALLED_SPLIT_STEPS` steps in a row, so only one step in `MAX_STALLED_SPLIT_STEPS + 1`
+ *   is guaranteed to be a slice.
+ * - Callers compare the bound with `maxPieces` to return the sentinel before building a huge split;
+ *   `tileByUnit`'s own `maxSlices` settles counts the bound cannot.
+ *
+ * @param spanNs exact span between start and end, in nanoseconds
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @param amount units per step
+ * @param zoned whether the values carry a time zone with offset transitions
+ * @returns a count no greater than the slices `tileByUnit` would build (0 when unknown)
+ *
+ * @example minSlicesForSpan(3 * 3_600_000_000_000, "hours", 1, false) // 3
+ * @example minSlicesForSpan(62 * 86_400_000_000_000, "months", 1, false) // 2
+ */
+export function minSlicesForSpan(spanNs, unit, amount, zoned) {
+    const longest = LONGEST_UNIT_NANOSECONDS[unit];
+    if (longest === undefined || !(amount > 0)) {
+        return 0;
+    }
+    const stepNs = longest * amount;
+    if (isExactDurationUnit(unit)) {
+        return Math.ceil((spanNs / stepNs) * QUOTIENT_TOLERANCE);
+    }
+    const reach = Math.max(0, spanNs - (zoned ? ZONE_OFFSET_SLACK_NANOSECONDS : 0));
+    const steps = Math.ceil((reach / stepNs) * QUOTIENT_TOLERANCE);
+    return zoned ? Math.floor(steps / (MAX_STALLED_SPLIT_STEPS + 1)) : steps;
+}

package/dist/internal/startOrEndOfUnix.d.ts

@@ -0,0 +1,26 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Internal shared implementation for `startOfUnix` / `endOfUnix` and the quarter functions.
+ *
+ * - Converts the epoch to a ZonedDateTime, snaps to the start or end of the
+ *   requested unit, then converts back to an epoch number.
+ * - `unit` is already resolved to a singular Temporal `DateUnit` / `TimeUnit` by the public caller,
+ *   or `"quarter"` from `startOfQuarterForUnix` / `endOfQuarterForUnix` only.
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`); `epochUnit` accepts singular
+ *   and plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone returns null.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The boundary is always the real local bucket from `internal/zonedBucket.ts` — a start never
+ *   after `value`, an end never before it.
+ *
+ * @param value Unix epoch number or digit string
+ * @param unit resolved unit to snap to
+ * @param options optional: epochUnit, timeZone, weekStartsOn
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns Unix epoch number, or null on invalid input
+ */
+export declare function startOrEndOfUnix(value: unknown, unit: Temporal.DateTimeUnit | "quarter", options: {
+    epochUnit?: unknown;
+    timeZone?: string;
+    weekStartsOn?: unknown;
+}, isEnd: boolean): number | null;

package/dist/internal/startOrEndOfUnix.js

@@ -0,0 +1,47 @@
+import { normalizeTimeZone } from "./normalizeTimeZone.js";
+import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
+import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "./unixEpochValue.js";
+import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
+/**
+ * Internal shared implementation for `startOfUnix` / `endOfUnix` and the quarter functions.
+ *
+ * - Converts the epoch to a ZonedDateTime, snaps to the start or end of the
+ *   requested unit, then converts back to an epoch number.
+ * - `unit` is already resolved to a singular Temporal `DateUnit` / `TimeUnit` by the public caller,
+ *   or `"quarter"` from `startOfQuarterForUnix` / `endOfQuarterForUnix` only.
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`); `epochUnit` accepts singular
+ *   and plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone returns null.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The boundary is always the real local bucket from `internal/zonedBucket.ts` — a start never
+ *   after `value`, an end never before it.
+ *
+ * @param value Unix epoch number or digit string
+ * @param unit resolved unit to snap to
+ * @param options optional: epochUnit, timeZone, weekStartsOn
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns Unix epoch number, or null on invalid input
+ */
+export function startOrEndOfUnix(value, unit, options, isEnd) {
+    const epochUnit = resolveUnixEpochUnit(options.epochUnit);
+    const timeZone = normalizeTimeZone(options.timeZone);
+    const weekStartsOn = resolveWeekStartsOn(options.weekStartsOn);
+    if (!timeZone || epochUnit === null || weekStartsOn === null) {
+        return null;
+    }
+    const instant = unixEpochToInstant(value, epochUnit);
+    if (instant === null) {
+        return null;
+    }
+    const weekStartDay = weekStartsOn === "monday" ? 1 : 7;
+    try {
+        const source = instant.toZonedDateTimeISO(timeZone);
+        const boundary = isEnd
+            ? zonedUnitEnd(source, unit, weekStartDay)
+            : zonedUnitStart(source, unit, weekStartDay);
+        return boundary ? toUnixEpoch(boundary, epochUnit) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/startOrEndOfUtc.d.ts

@@ -0,0 +1,27 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../types/index.js";
+/**
+ * Internal shared implementation for `startOfUtc` / `endOfUtc`.
+ *
+ * - Converts the UTC Instant to a ZonedDateTime, snaps to the start or end of
+ *   the requested unit, then converts back to an Instant string.
+ * - Supports every Temporal `DateUnit` and `TimeUnit`.
+ * - `weekStartsOn` shifts the week boundary: `"monday"` (default) or `"sunday"`.
+ * - Ends are computed forward from `value`, never from the unit's start, so an end is returned
+ *   even when its unit began before the first representable instant (`-271821-04-20T00:00:00Z`).
+ *   A start that lies before that instant returns "".
+ * - `fractionalSecondDigits` overrides the default sub-second precision for the
+ *   returned Instant string. An end is written at nanosecond precision by default (next start
+ *   − 1 ns); a start defaults to 3 for millisecond, 6 for microsecond, 9 for nanosecond, and 0
+ *   for all coarser units.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
+ * @param options optional: weekStartsOn, fractionalSecondDigits
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns UTC Instant string, or "" on invalid input
+ */
+export declare function startOrEndOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}, isEnd: boolean): string;

package/dist/{utc/calculate → internal}/startOrEndOfUtc.js

@@ -1,16 +1,43 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidDateTimeUnit } from "../../plain/index.js";
-import { isValidUtc } from "../validate/isValidUtc.js";
+import { defaultFractionalDigits } from "./defaultFractionalDigits.js";
+import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
+import { isValidDateTimeUnit } from "../plain/index.js";
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+/**
+ * Internal shared implementation for `startOfUtc` / `endOfUtc`.
+ *
+ * - Converts the UTC Instant to a ZonedDateTime, snaps to the start or end of
+ *   the requested unit, then converts back to an Instant string.
+ * - Supports every Temporal `DateUnit` and `TimeUnit`.
+ * - `weekStartsOn` shifts the week boundary: `"monday"` (default) or `"sunday"`.
+ * - Ends are computed forward from `value`, never from the unit's start, so an end is returned
+ *   even when its unit began before the first representable instant (`-271821-04-20T00:00:00Z`).
+ *   A start that lies before that instant returns "".
+ * - `fractionalSecondDigits` overrides the default sub-second precision for the
+ *   returned Instant string. An end is written at nanosecond precision by default (next start
+ *   − 1 ns); a start defaults to 3 for millisecond, 6 for microsecond, 9 for nanosecond, and 0
+ *   for all coarser units.
+ *
+ * @param value ISO UTC datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to snap to
+ * @param options optional: weekStartsOn, fractionalSecondDigits
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns UTC Instant string, or "" on invalid input
+ */
 export function startOrEndOfUtc(value, unit, options, isEnd) {
-    const weekStartsOn = options.weekStartsOn ?? "monday";
+    const weekStartsOn = resolveWeekStartsOn(options.weekStartsOn);
+    const resolvedUnit = resolveDateTimeUnit(unit);
     const fractionalSecondDigits = options.fractionalSecondDigits;
-    if (!isValidUtc(value) || !isValidDateTimeUnit(unit))
+    if (!isValidUtc(value) ||
+        !isValidDateTimeUnit(resolvedUnit) ||
+        weekStartsOn === null)
         return "";
     try {
         const instant = Temporal.Instant.from(value);
         const source = instant.toZonedDateTimeISO("UTC");
         let result;
-        switch (unit) {
+        switch (resolvedUnit) {
             case "year":
                 result = isEnd
                     ? source.with({ month: 12, day: 31 }).withPlainTime({
@@ -24,16 +51,9 @@ export function startOrEndOfUtc(value, unit, options, isEnd) {
                     : source.with({ month: 1, day: 1 }).withPlainTime();
                 break;
             case "month":
+                // The end is computed from `value` itself: the month's first day may lie before the range.
                 result = isEnd
-                    ? source
-                        .with({
-                        day: Temporal.PlainDate.from({
-                            year: source.year,
-                            month: source.month,
-                            day: 1,
-                        }).daysInMonth,
-                    })
-                        .withPlainTime({
+                    ? source.with({ day: source.daysInMonth }).withPlainTime({
                         hour: 23,
                         minute: 59,
                         second: 59,
@@ -44,14 +64,14 @@ export function startOrEndOfUtc(value, unit, options, isEnd) {
                     : source.with({ day: 1 }).withPlainTime();
                 break;
             case "week": {
+                // Days since the week started: Sunday is day 7, so `dayOfWeek % 7` makes it day 0 of a
+                // Sunday-first week. The end steps forward (6 - that) days rather than back to the start,
+                // which may lie before the first representable instant.
                 const daysToSubtract = weekStartsOn === "monday"
                     ? source.dayOfWeek - 1
                     : source.dayOfWeek % 7;
                 result = isEnd
-                    ? source
-                        .subtract({ days: daysToSubtract })
-                        .add({ days: 6 })
-                        .withPlainTime({
+                    ? source.add({ days: 6 - daysToSubtract }).withPlainTime({
                         hour: 23,
                         minute: 59,
                         second: 59,
@@ -127,12 +147,13 @@ export function startOrEndOfUtc(value, unit, options, isEnd) {
             default:
                 return "";
         }
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[unit] || 0);
+        // An end is next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
+        // print an earlier instant than the end (Calendar & zone semantics §3).
+        const fractionalDigits = isEnd
+            ? fractionalSecondDigits === undefined
+                ? 9
+                : fractionalSecondDigits
+            : defaultFractionalDigits(resolvedUnit, fractionalSecondDigits);
         return result
             .toInstant()
             .toString({ fractionalSecondDigits: fractionalDigits });

package/dist/internal/startOrEndOfZoned.d.ts

@@ -0,0 +1,22 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeUnit, FractionalDigit } from "../types/index.js";
+/**
+ * Internal shared implementation for `startOfZoned` / `endOfZoned`.
+ *
+ * - Snaps to the real local bucket from `internal/zonedBucket.ts` in `value`'s own zone: a
+ *   start is never after `value`, an end never before it.
+ * - `weekStartsOn` picks the week's first day. An end is written at nanosecond precision by
+ *   default (next start − 1 ns); a start's `fractionalSecondDigits` defaults to the unit's own
+ *   precision (see `defaultFractionalDigits`).
+ * - `unit` may be singular or plural; an invalid `weekStartsOn` returns "".
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit DateTimeUnit to snap to, singular or plural
+ * @param options optional: weekStartsOn, fractionalSecondDigits
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns zoned ISO 8601 string, or "" on invalid input
+ */
+export declare function startOrEndOfZoned(value: string, unit: Temporal.SmallestUnit<DateTimeUnit>, options: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}, isEnd: boolean): string;

package/dist/internal/startOrEndOfZoned.js

@@ -0,0 +1,49 @@
+import { defaultFractionalDigits } from "./defaultFractionalDigits.js";
+import { zonedDateTimeFrom } from "./zonedWallClock.js";
+import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
+import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
+import { isValidDateTimeUnit } from "../plain/validate/index.js";
+import { isValidZonedDateTime } from "../zoned/validate/index.js";
+/**
+ * Internal shared implementation for `startOfZoned` / `endOfZoned`.
+ *
+ * - Snaps to the real local bucket from `internal/zonedBucket.ts` in `value`'s own zone: a
+ *   start is never after `value`, an end never before it.
+ * - `weekStartsOn` picks the week's first day. An end is written at nanosecond precision by
+ *   default (next start − 1 ns); a start's `fractionalSecondDigits` defaults to the unit's own
+ *   precision (see `defaultFractionalDigits`).
+ * - `unit` may be singular or plural; an invalid `weekStartsOn` returns "".
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit DateTimeUnit to snap to, singular or plural
+ * @param options optional: weekStartsOn, fractionalSecondDigits
+ * @param isEnd false for start-of-unit, true for end-of-unit
+ * @returns zoned ISO 8601 string, or "" on invalid input
+ */
+export function startOrEndOfZoned(value, unit, options, isEnd) {
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    const weekStartsOn = resolveWeekStartsOn(options.weekStartsOn);
+    if (!isValidZonedDateTime(value) ||
+        !isValidDateTimeUnit(resolvedUnit) ||
+        weekStartsOn === null)
+        return "";
+    const weekStartDay = weekStartsOn === "monday" ? 1 : 7;
+    // An end is next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
+    // print an earlier instant than the end (Calendar & zone semantics §3).
+    const fractionalSecondDigits = isEnd
+        ? options.fractionalSecondDigits === undefined
+            ? 9
+            : options.fractionalSecondDigits
+        : defaultFractionalDigits(resolvedUnit, options.fractionalSecondDigits);
+    try {
+        const source = zonedDateTimeFrom(value);
+        const boundary = isEnd
+            ? zonedUnitEnd(source, resolvedUnit, weekStartDay)
+            : zonedUnitStart(source, resolvedUnit, weekStartDay);
+        return boundary ? boundary.toString({ fractionalSecondDigits }) : "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/internal/temporalCompat/calendarDateArithmetic.d.ts

@@ -0,0 +1,33 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import { type ArithmeticOverflow, type DateDurationFields } from "./nonIsoArithmetic.js";
+export type CalendarDateUnit = "year" | "month" | "week" | "day";
+/**
+ * `one.until(two, { largestUnit })`'s date fields, made correct where `@js-temporal/polyfill` is not
+ * (TC39 `CalendarDateUntil`, Intl era/monthCode proposal `NonISODateUntil`). Both dates must carry
+ * the same calendar.
+ *
+ * - `iso8601` is the polyfill's own `until`, untouched.
+ * - `"day"` / `"week"` are ISO `until`: days do not depend on the calendar.
+ * - D6/D7: the polyfill answers first; while its probe fails, the answer is kept only when it is
+ *   exactly the spec's (`isNonIsoDateUntilResult`), otherwise the spec loops recompute it.
+ * - D1: a polyfill RangeError near a range limit is answered by the spec loops.
+ * - D2/D3/D4/D5: in a corrected range the spec loops run over ISO (buddhist) or the owned Hebrew
+ *   and Indian arithmetic.
+ * - D9: months counted across `LARGE_MONTH_SPAN` months or more run the spec loops, whose month
+ *   counts are bounded.
+ */
+export declare function calendarDateUntil(one: Temporal.PlainDate, two: Temporal.PlainDate, largestUnit: CalendarDateUnit): DateDurationFields;
+/**
+ * `date.add(duration, { overflow })`, made correct where `@js-temporal/polyfill` is not (TC39
+ * `CalendarDateAdd`, Intl era/monthCode proposal `NonISODateAdd`).
+ *
+ * - `iso8601` is the polyfill's own `add`, untouched.
+ * - Weeks and days alone are ISO day arithmetic.
+ * - D1: a polyfill RangeError near a range limit is answered by the spec algorithm.
+ * - D2/D3/D4/D5: in a corrected range the spec algorithm runs over ISO (buddhist) or the owned
+ *   Hebrew and Indian arithmetic.
+ * - D9: `LARGE_MONTH_SPAN` months or more run the spec algorithm, whose month jumps are bounded.
+ *
+ * @returns a PlainDate in `date`'s calendar; throws RangeError out of range or on `reject`
+ */
+export declare function calendarDateAdd(date: Temporal.PlainDate, duration: Partial<DateDurationFields>, overflow: ArithmeticOverflow): Temporal.PlainDate;