@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/index.js

@@ -1,34 +1,55 @@
-export { advanceBusinessDays } from "./advanceBusinessDays.js";
-export { adjustZonedBusinessDays } from "./adjustZonedBusinessDays.js";
 export { advanceToWeekday } from "./advanceToWeekday.js";
-export { calendarDateParts, formatCalendarDate, parseCalendarDateValue, } from "./calendarDateString.js";
-export { isCalendarSystem, temporalCalendarIds } from "./calendarSystemIds.js";
+export { parseCalendarDateValue } from "./calendarDateString.js";
+export { canonicalCalendarSystem, isCalendarSystem } from "./calendarSystemIds.js";
 export { parseCalendarDatePairForArithmetic } from "./calendarDatePairPolicy.js";
 export { parseCalendarZonedPairForArithmetic } from "./calendarZonedPairPolicy.js";
 export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarValueOfDate.js";
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { fiscalPeriodOfWeek, fiscalYearOf } from "./fiscalCalendar.js";
+export { floorDivide } from "./floorDivide.js";
+export { DOT_NET_TICKS_EPOCH_OFFSET, EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, FILE_TIME_EPOCH_OFFSET_TICKS, MAX_DOT_NET_TICKS, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MAX_FILE_TIME, MILLISECONDS_PER_DAY, MIN_DOT_NET_TICKS, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, MIN_FILE_TIME, MIN_PG_MICROSECONDS, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, NANOSECONDS_PER_TICK, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "./foreignEpochs.js";
+export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNanoseconds.js";
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
-export { calendarDateStringParts, formatDateInCalendar, } from "./formatDateInCalendar.js";
-export { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+export { formatDateInCalendar } from "./formatDateInCalendar.js";
+export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
+export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
+export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
+export { formatHourDuration } from "./hourDurationString.js";
+export { canonicalInstantIntervals } from "./instantIntervalText.js";
+export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
+export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
 export { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
-export { dateFromEthiopicFamilyFields, ethiopicFamilyDateParts, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+export { defaultFractionalDigits } from "./defaultFractionalDigits.js";
 export { getLocaleFirstDayOfWeek } from "./getLocaleFirstDayOfWeek.js";
-export { getLocaleMinimalDaysInFirstWeek } from "./getLocaleMinimalDaysInFirstWeek.js";
+export { resolveMinimalDaysInFirstWeek } from "./resolveMinimalDaysInFirstWeek.js";
 export { getLocaleWeekYearBounds } from "./getLocaleWeekYearBounds.js";
 export { getLocaleWeekendDays } from "./getLocaleWeekendDays.js";
-export { getStartOfZonedUnit, getUnitSpan } from "./intervalCountHelpers.js";
+export { getUnitSpan } from "./intervalCountHelpers.js";
+export { isObject, isOptionsArgument } from "./isObject.js";
 export { isValidAmount } from "./isValidAmount.js";
 export { joinDateTimeConnector } from "./joinDateTimeConnector.js";
 export { isValidDayOfWeek } from "./isValidDayOfWeek.js";
 export { monthGridWeekRow } from "./monthGridWeekRow.js";
 export { normalizeDateTime } from "./normalizeDateTime.js";
 export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
+export { plainDateAdd } from "./plainDateAdd.js";
+export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 export { resolveDurationUnit } from "./resolveDurationUnit.js";
 export { resolveOverflow } from "./resolveOverflow.js";
 export { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochIntervalPair, parseUnixEpochValue, } from "./unixEpochValue.js";
+export { tileByUnit } from "./splitStep.js";
+export { countZonedBuckets, nextZonedBucketStart, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
+export { countZonedLocalDates } from "./zonedLocalDates.js";
+export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { wallClockAtOffset } from "./wallClockAtOffset.js";
+export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
+export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
+export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/instantFormatOptions.d.ts

@@ -0,0 +1,43 @@
+import type { Temporal } from "@js-temporal/polyfill";
+type Options = Intl.DateTimeFormatOptions;
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format an exact time in `timeZone`.
+ *
+ * - Returns `null` when the caller passed a `timeZone` option: the value is
+ *   formatted in its own zone, and `Temporal.ZonedDateTime#toLocaleString`
+ *   throws a TypeError for one (CreateDateTimeFormat with
+ *   toLocaleStringTimeZone).
+ * - With no date or time field and no `dateStyle`/`timeStyle`, year, month,
+ *   day, hour, minute and second default to `"numeric"`. With `defaults`
+ *   `"zoned-date-time"` (ZonedDateTime#toLocaleString) `timeZoneName` also
+ *   defaults to `"short"`; with `"all"` (an Instant) it does not.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @param timeZone the zone the value is formatted in
+ * @param defaults GetDateTimeFormat defaults: `"zoned-date-time"` or `"all"`
+ * @returns runtime options in `timeZone`, or `null` for a `timeZone` option
+ */
+export declare function instantFormatOptions(options: Options, timeZone: string, defaults: "zoned-date-time" | "all"): Options | null;
+/**
+ * Format an exact time as text, either as its wall clock (a PlainDateTime) or
+ * as a ZonedDateTime with its zone, through the runtime's
+ * `Intl.DateTimeFormat`. Shared by `formatUtc` and `formatUnix`.
+ *
+ * - The wall-clock path uses {@link plainDateTimeFormatOptions}
+ *   (GetDateTimeFormat ~any~, ~all~, ~relevant~): `timeZoneName` is not
+ *   inherited.
+ * - The zoned path uses {@link instantFormatOptions} with
+ *   `"zoned-date-time"` defaults.
+ * - `options` must not carry a `timeZone`; the zone comes from
+ *   `zonedDateTime`. Constructing with `options` first surfaces the TypeError
+ *   or RangeError Intl.DateTimeFormat raises for invalid ones.
+ *
+ * @param zonedDateTime the value in the zone it is rendered in
+ * @param locale BCP 47 locale, or `undefined` for the runtime default
+ * @param options caller's `Intl.DateTimeFormatOptions` without `timeZone`
+ * @param includeTimeZoneName `true` for the zoned path
+ * @returns the formatted text, not yet normalised
+ */
+export declare function formatWallClockOrZoned(zonedDateTime: Temporal.ZonedDateTime, locale: string | string[] | undefined, options: Options, includeTimeZoneName: boolean): string;
+export {};

package/dist/internal/instantFormatOptions.js

@@ -0,0 +1,99 @@
+// Option resolution for formatting an exact time (a ZonedDateTime, or an
+// Instant in a given zone) through the runtime's `Intl.DateTimeFormat`. The
+// rules are the Temporal proposal's ECMA-402 amendments: CreateDateTimeFormat
+// and GetDateTimeFormat with required ~any~ and inherit ~all~, so every caller
+// field, including `era` and `timeZoneName`, is passed on unchanged.
+import { plainDateTimeFormatOptions } from "./plainFormatOptions.js";
+// GetDateTimeFormat requiredOptions for ~any~. `era` and `timeZoneName` are
+// deliberately absent: neither suppresses the defaults.
+const REQUIRED_FIELDS = [
+    "weekday",
+    "year",
+    "month",
+    "day",
+    "dayPeriod",
+    "hour",
+    "minute",
+    "second",
+    "fractionalSecondDigits",
+];
+const DEFAULT_FIELDS = {
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+};
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format an exact time in `timeZone`.
+ *
+ * - Returns `null` when the caller passed a `timeZone` option: the value is
+ *   formatted in its own zone, and `Temporal.ZonedDateTime#toLocaleString`
+ *   throws a TypeError for one (CreateDateTimeFormat with
+ *   toLocaleStringTimeZone).
+ * - With no date or time field and no `dateStyle`/`timeStyle`, year, month,
+ *   day, hour, minute and second default to `"numeric"`. With `defaults`
+ *   `"zoned-date-time"` (ZonedDateTime#toLocaleString) `timeZoneName` also
+ *   defaults to `"short"`; with `"all"` (an Instant) it does not.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @param timeZone the zone the value is formatted in
+ * @param defaults GetDateTimeFormat defaults: `"zoned-date-time"` or `"all"`
+ * @returns runtime options in `timeZone`, or `null` for a `timeZone` option
+ */
+export function instantFormatOptions(options, timeZone, defaults) {
+    if (options.timeZone !== undefined)
+        return null;
+    const needDefaults = options.dateStyle === undefined &&
+        options.timeStyle === undefined &&
+        REQUIRED_FIELDS.every((field) => options[field] === undefined);
+    if (!needDefaults)
+        return { ...options, timeZone };
+    // Defaults spread after the caller's options: needDefaults guarantees every
+    // default field is undefined there, even when present as a key.
+    return {
+        ...options,
+        ...DEFAULT_FIELDS,
+        ...(defaults === "zoned-date-time"
+            ? {
+                timeZoneName: options.timeZoneName === undefined ? "short" : options.timeZoneName,
+            }
+            : {}),
+        timeZone,
+    };
+}
+/**
+ * Format an exact time as text, either as its wall clock (a PlainDateTime) or
+ * as a ZonedDateTime with its zone, through the runtime's
+ * `Intl.DateTimeFormat`. Shared by `formatUtc` and `formatUnix`.
+ *
+ * - The wall-clock path uses {@link plainDateTimeFormatOptions}
+ *   (GetDateTimeFormat ~any~, ~all~, ~relevant~): `timeZoneName` is not
+ *   inherited.
+ * - The zoned path uses {@link instantFormatOptions} with
+ *   `"zoned-date-time"` defaults.
+ * - `options` must not carry a `timeZone`; the zone comes from
+ *   `zonedDateTime`. Constructing with `options` first surfaces the TypeError
+ *   or RangeError Intl.DateTimeFormat raises for invalid ones.
+ *
+ * @param zonedDateTime the value in the zone it is rendered in
+ * @param locale BCP 47 locale, or `undefined` for the runtime default
+ * @param options caller's `Intl.DateTimeFormatOptions` without `timeZone`
+ * @param includeTimeZoneName `true` for the zoned path
+ * @returns the formatted text, not yet normalised
+ */
+export function formatWallClockOrZoned(zonedDateTime, locale, options, includeTimeZoneName) {
+    new Intl.DateTimeFormat(locale, options);
+    if (includeTimeZoneName) {
+        const resolved = instantFormatOptions(options, zonedDateTime.timeZoneId, "zoned-date-time");
+        return resolved === null
+            ? ""
+            : new Intl.DateTimeFormat(locale, resolved).format(zonedDateTime.epochMilliseconds);
+    }
+    const wallClockMilliseconds = zonedDateTime
+        .toPlainDateTime()
+        .toZonedDateTime("UTC").epochMilliseconds;
+    return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options)).format(wallClockMilliseconds);
+}

package/dist/internal/instantIntervalText.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Re-serialise instant intervals to `Temporal.Instant.prototype.toString()` spelling.
+ *
+ * The CORE-6 `interval/` functions echo the caller's strings; the positional `utc/interval/`
+ * functions that delegate to them return canonical `Z` strings instead (CORE-8 half-open decisions of record:
+ * outputs stay re-serialised), so tie-breaks between spellings of one instant never surface.
+ *
+ * - Returns `null` if any string fails to parse (callers validate first, so only a throwing
+ *   `Temporal.Instant.from` reaches this).
+ *
+ * @example canonicalInstantIntervals([{ start: "2024-01-01T09:00:00.000Z", end: "2024-01-01T12:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }]
+ * @example canonicalInstantIntervals([]) // []
+ */
+export declare function canonicalInstantIntervals(intervals: ReadonlyArray<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}> | null;

package/dist/internal/instantIntervalText.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Re-serialise instant intervals to `Temporal.Instant.prototype.toString()` spelling.
+ *
+ * The CORE-6 `interval/` functions echo the caller's strings; the positional `utc/interval/`
+ * functions that delegate to them return canonical `Z` strings instead (CORE-8 half-open decisions of record:
+ * outputs stay re-serialised), so tie-breaks between spellings of one instant never surface.
+ *
+ * - Returns `null` if any string fails to parse (callers validate first, so only a throwing
+ *   `Temporal.Instant.from` reaches this).
+ *
+ * @example canonicalInstantIntervals([{ start: "2024-01-01T09:00:00.000Z", end: "2024-01-01T12:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }]
+ * @example canonicalInstantIntervals([]) // []
+ */
+export function canonicalInstantIntervals(intervals) {
+    try {
+        return intervals.map(({ start, end }) => ({
+            start: Temporal.Instant.from(start).toString(),
+            end: Temporal.Instant.from(end).toString(),
+        }));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/instantNanoseconds.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
+ *
+ * The single definition of "an instant string GMT accepts": the RFC 9557 instant grammar
+ * `Temporal.Instant.from` parses, restricted to ISO 8601 extended format before the first `[`
+ * (`instantBody`: `<date>T<time>`, then `Z` or `±HH:MM[:SS[.fraction]]`), minus
+ * leap seconds (which Temporal clamps rather than rejects). Basic format, a space or lower-case
+ * `t` separator, a lower-case `z` and an hour-only time or offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
+ * `ParseISODateTime`, RFC 9557 §3.3): a time zone, calendar (`[u-ca=hebrew]`) or elective
+ * (`[foo=bar]`) annotation is ignored, because an instant has neither zone nor calendar, and an
+ * unknown critical one (`[!foo=bar]`) is rejected. Callers layer their own sentinel on top —
+ * `toNanoseconds` returns `0n`, `spanNs` returns `null` — so the parse result stays unambiguous
+ * here.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns nanoseconds since the Unix epoch, or null when `value` is not a valid instant
+ *
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z") // 0n
+ * @example parseInstantNanoseconds("2016-12-31T23:59:60Z") // null — leap second
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00") // null — no offset designator
+ * @example parseInstantNanoseconds("20240310T120000Z") // null — basic format
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00z") // null — lower-case z
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z[u-ca=hebrew]") // 0n — calendar annotation ignored
+ */
+export declare function parseInstantNanoseconds(value: string): bigint | null;

package/dist/internal/instantNanoseconds.js

@@ -0,0 +1,41 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { instantLeapSecond } from "../regex/leap-second.js";
+import { hasInstantShape } from "./isoStringBody.js";
+/**
+ * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
+ *
+ * The single definition of "an instant string GMT accepts": the RFC 9557 instant grammar
+ * `Temporal.Instant.from` parses, restricted to ISO 8601 extended format before the first `[`
+ * (`instantBody`: `<date>T<time>`, then `Z` or `±HH:MM[:SS[.fraction]]`), minus
+ * leap seconds (which Temporal clamps rather than rejects). Basic format, a space or lower-case
+ * `t` separator, a lower-case `z` and an hour-only time or offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
+ * `ParseISODateTime`, RFC 9557 §3.3): a time zone, calendar (`[u-ca=hebrew]`) or elective
+ * (`[foo=bar]`) annotation is ignored, because an instant has neither zone nor calendar, and an
+ * unknown critical one (`[!foo=bar]`) is rejected. Callers layer their own sentinel on top —
+ * `toNanoseconds` returns `0n`, `spanNs` returns `null` — so the parse result stays unambiguous
+ * here.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns nanoseconds since the Unix epoch, or null when `value` is not a valid instant
+ *
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z") // 0n
+ * @example parseInstantNanoseconds("2016-12-31T23:59:60Z") // null — leap second
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00") // null — no offset designator
+ * @example parseInstantNanoseconds("20240310T120000Z") // null — basic format
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00z") // null — lower-case z
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z[u-ca=hebrew]") // 0n — calendar annotation ignored
+ */
+export function parseInstantNanoseconds(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    if (instantLeapSecond.test(value) || !hasInstantShape(value)) {
+        return null;
+    }
+    try {
+        return Temporal.Instant.from(value).epochNanoseconds;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/intervalCountHelpers.d.ts

@@ -1,18 +1,24 @@
 import type { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeUnit } from "../types/index.js";
 /**
- * Return the start of the specified date-time `unit` for a `Temporal.ZonedDateTime`.
+ * Singular DateTimeUnit to its `Temporal.Duration` field name.
  *
- * - Always uses Monday as the week start (consistent with `startOfZoned` semantics).
- * - Day-and-below units truncate by instant via `round({ roundingMode: "trunc" })`, which
- *   resolves DST correctly — a local day whose midnight is skipped starts at 01:00.
- * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
- *
- * @param source Temporal.ZonedDateTime to truncate
- * @param unit DateTimeUnit to truncate to
- * @returns Temporal.ZonedDateTime at the start of the specified unit
+ * Example lookups:
+ * - DURATION_FIELD_BY_UNIT.day => "days"
+ * - DURATION_FIELD_BY_UNIT.nanosecond => "nanoseconds"
  */
-export declare function getStartOfZonedUnit(source: Temporal.ZonedDateTime, unit: DateTimeUnit): Temporal.ZonedDateTime;
+export declare const DURATION_FIELD_BY_UNIT: {
+    readonly year: "years";
+    readonly month: "months";
+    readonly week: "weeks";
+    readonly day: "days";
+    readonly hour: "hours";
+    readonly minute: "minutes";
+    readonly second: "seconds";
+    readonly millisecond: "milliseconds";
+    readonly microsecond: "microseconds";
+    readonly nanosecond: "nanoseconds";
+};
 /**
  * Extract the whole-unit span from a `Temporal.Duration` measured with `largestUnit: unit`.
  *

package/dist/internal/intervalCountHelpers.js

@@ -5,7 +5,7 @@
  * - DURATION_FIELD_BY_UNIT.day => "days"
  * - DURATION_FIELD_BY_UNIT.nanosecond => "nanoseconds"
  */
-const DURATION_FIELD_BY_UNIT = {
+export const DURATION_FIELD_BY_UNIT = {
     year: "years",
     month: "months",
     week: "weeks",
@@ -17,36 +17,6 @@ const DURATION_FIELD_BY_UNIT = {
     microsecond: "microseconds",
     nanosecond: "nanoseconds",
 };
-/**
- * Return the start of the specified date-time `unit` for a `Temporal.ZonedDateTime`.
- *
- * - Always uses Monday as the week start (consistent with `startOfZoned` semantics).
- * - Day-and-below units truncate by instant via `round({ roundingMode: "trunc" })`, which
- *   resolves DST correctly — a local day whose midnight is skipped starts at 01:00.
- * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
- *
- * @param source Temporal.ZonedDateTime to truncate
- * @param unit DateTimeUnit to truncate to
- * @returns Temporal.ZonedDateTime at the start of the specified unit
- */
-export function getStartOfZonedUnit(source, unit) {
-    switch (unit) {
-        case "year":
-            return source
-                .with({ month: 1, day: 1 })
-                .round({ smallestUnit: "day", roundingMode: "trunc" });
-        case "month":
-            return source
-                .with({ day: 1 })
-                .round({ smallestUnit: "day", roundingMode: "trunc" });
-        case "week":
-            return source
-                .subtract({ days: source.dayOfWeek - 1 })
-                .round({ smallestUnit: "day", roundingMode: "trunc" });
-        default:
-            return source.round({ smallestUnit: unit, roundingMode: "trunc" });
-    }
-}
 /**
  * Extract the whole-unit span from a `Temporal.Duration` measured with `largestUnit: unit`.
  *

package/dist/internal/intervalNanoseconds.d.ts

@@ -0,0 +1,47 @@
+/** An `Interval` parsed once: bigint epoch nanoseconds plus the exact strings they came from. */
+export interface IntervalNanoseconds {
+    start: bigint;
+    end: bigint;
+    startText: string;
+    endText: string;
+}
+/**
+ * Parse a candidate `Interval` to epoch nanoseconds, or `null` when it is not one.
+ *
+ * - Any non-null object with ISO 8601 instant strings `start` ≤ `end` (by instant) is accepted;
+ *   extra keys are ignored (GMT rule: the type is structural).
+ * - Each endpoint is read exactly once, so the validated text is the text callers echo.
+ *
+ * @param value candidate `{ start, end }` record
+ * @returns the parsed record, or null when `value` is not a valid `Interval`
+ *
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:00Z", end: "1970-01-01T00:00:00.000000001Z" }) // { start: 0n, end: 1n, startText: "1970-01-01T00:00:00Z", endText: "1970-01-01T00:00:00.000000001Z" }
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:01Z", end: "1970-01-01T00:00:00Z" }) // null — inverted
+ */
+export declare function parseIntervalNanoseconds(value: unknown): IntervalNanoseconds | null;
+/**
+ * Parse a list of candidate `Interval`s, all-or-nothing.
+ *
+ * @param values candidate array of `{ start, end }` records
+ * @returns the parsed records in input order, or null when `values` is not an array or any element is invalid
+ *
+ * @example parseIntervalNanosecondsList([]) // []
+ * @example parseIntervalNanosecondsList([null]) // null
+ */
+export declare function parseIntervalNanosecondsList(values: unknown): IntervalNanoseconds[] | null;
+/**
+ * Sweep parsed intervals into sorted, disjoint, non-touching, non-empty runs.
+ *
+ * - Touching records coalesce (`start <= run.end`); a 1 ns gap does not.
+ * - Equal starts keep input order (stable sort), so a run keeps its first start text; the first
+ *   record to reach the run's latest end keeps its end text (GMT rule: first wins ties).
+ * - Empty records that touch or fall inside a run are absorbed; a stranded one is dropped.
+ * - Runs are copies; the input records are never mutated.
+ *
+ * @param records parsed intervals, in any order
+ * @returns coalesced runs sorted by start
+ *
+ * @example coalesceIntervalNanoseconds([{ start: 3n, end: 5n, startText: "c", endText: "e" }, { start: 1n, end: 3n, startText: "a", endText: "c" }]) // [{ start: 1n, end: 5n, startText: "a", endText: "e" }]
+ * @example coalesceIntervalNanoseconds([{ start: 4n, end: 4n, startText: "d", endText: "d" }]) // []
+ */
+export declare function coalesceIntervalNanoseconds(records: readonly IntervalNanoseconds[]): IntervalNanoseconds[];

package/dist/internal/intervalNanoseconds.js

@@ -0,0 +1,86 @@
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+/**
+ * Parse a candidate `Interval` to epoch nanoseconds, or `null` when it is not one.
+ *
+ * - Any non-null object with ISO 8601 instant strings `start` ≤ `end` (by instant) is accepted;
+ *   extra keys are ignored (GMT rule: the type is structural).
+ * - Each endpoint is read exactly once, so the validated text is the text callers echo.
+ *
+ * @param value candidate `{ start, end }` record
+ * @returns the parsed record, or null when `value` is not a valid `Interval`
+ *
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:00Z", end: "1970-01-01T00:00:00.000000001Z" }) // { start: 0n, end: 1n, startText: "1970-01-01T00:00:00Z", endText: "1970-01-01T00:00:00.000000001Z" }
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:01Z", end: "1970-01-01T00:00:00Z" }) // null — inverted
+ */
+export function parseIntervalNanoseconds(value) {
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const { start: startText, end: endText } = value;
+    const start = parseInstantNanoseconds(startText);
+    const end = parseInstantNanoseconds(endText);
+    if (start === null || end === null || start > end) {
+        return null;
+    }
+    return {
+        start,
+        end,
+        startText: startText,
+        endText: endText,
+    };
+}
+/**
+ * Parse a list of candidate `Interval`s, all-or-nothing.
+ *
+ * @param values candidate array of `{ start, end }` records
+ * @returns the parsed records in input order, or null when `values` is not an array or any element is invalid
+ *
+ * @example parseIntervalNanosecondsList([]) // []
+ * @example parseIntervalNanosecondsList([null]) // null
+ */
+export function parseIntervalNanosecondsList(values) {
+    if (!Array.isArray(values)) {
+        return null;
+    }
+    const records = [];
+    for (let index = 0; index < values.length; index++) {
+        const record = parseIntervalNanoseconds(values[index]);
+        if (record === null) {
+            return null;
+        }
+        records.push(record);
+    }
+    return records;
+}
+/**
+ * Sweep parsed intervals into sorted, disjoint, non-touching, non-empty runs.
+ *
+ * - Touching records coalesce (`start <= run.end`); a 1 ns gap does not.
+ * - Equal starts keep input order (stable sort), so a run keeps its first start text; the first
+ *   record to reach the run's latest end keeps its end text (GMT rule: first wins ties).
+ * - Empty records that touch or fall inside a run are absorbed; a stranded one is dropped.
+ * - Runs are copies; the input records are never mutated.
+ *
+ * @param records parsed intervals, in any order
+ * @returns coalesced runs sorted by start
+ *
+ * @example coalesceIntervalNanoseconds([{ start: 3n, end: 5n, startText: "c", endText: "e" }, { start: 1n, end: 3n, startText: "a", endText: "c" }]) // [{ start: 1n, end: 5n, startText: "a", endText: "e" }]
+ * @example coalesceIntervalNanoseconds([{ start: 4n, end: 4n, startText: "d", endText: "d" }]) // []
+ */
+export function coalesceIntervalNanoseconds(records) {
+    const sorted = [...records].sort((x, y) => x.start < y.start ? -1 : x.start > y.start ? 1 : 0);
+    const runs = [];
+    for (const record of sorted) {
+        const last = runs[runs.length - 1];
+        if (last !== undefined && record.start <= last.end) {
+            if (record.end > last.end) {
+                last.end = record.end;
+                last.endText = record.endText;
+            }
+        }
+        else {
+            runs.push({ ...record });
+        }
+    }
+    return runs.filter((run) => run.start < run.end);
+}

package/dist/internal/isObject.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type guard for a non-null object (arrays included), the shape an options bag or a props
+ * object must have before it is destructured. A default parameter covers only `undefined`, so a
+ * `null` or primitive argument reaches the destructure and throws `TypeError` without this check.
+ *
+ * @param value candidate
+ * @example isObject({ smallestUnit: "day" }) // true
+ * @example isObject(null) // false
+ * @example isObject("day") // false
+ * @returns whether `value` is a non-null object
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Whether an `options` argument is acceptable under Temporal GetOptionsObject: omitted
+ * (`undefined`, the defaults) or an object. `null`, a string, a number or a boolean is a TypeError
+ * there, so a function that takes an options bag returns its sentinel for it rather than silently
+ * reading the defaults (e.g. a legacy positional unit string such as `"seconds"`).
+ *
+ * @param options the caller's options argument
+ * @example isOptionsArgument(undefined) // true
+ * @example isOptionsArgument({ overflow: "reject" }) // true
+ * @example isOptionsArgument(null) // false
+ * @example isOptionsArgument("seconds") // false
+ * @returns whether `options` is `undefined` or a non-null object
+ */
+export declare function isOptionsArgument(options: unknown): boolean;

package/dist/internal/isObject.js

@@ -0,0 +1,30 @@
+/**
+ * Type guard for a non-null object (arrays included), the shape an options bag or a props
+ * object must have before it is destructured. A default parameter covers only `undefined`, so a
+ * `null` or primitive argument reaches the destructure and throws `TypeError` without this check.
+ *
+ * @param value candidate
+ * @example isObject({ smallestUnit: "day" }) // true
+ * @example isObject(null) // false
+ * @example isObject("day") // false
+ * @returns whether `value` is a non-null object
+ */
+export function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Whether an `options` argument is acceptable under Temporal GetOptionsObject: omitted
+ * (`undefined`, the defaults) or an object. `null`, a string, a number or a boolean is a TypeError
+ * there, so a function that takes an options bag returns its sentinel for it rather than silently
+ * reading the defaults (e.g. a legacy positional unit string such as `"seconds"`).
+ *
+ * @param options the caller's options argument
+ * @example isOptionsArgument(undefined) // true
+ * @example isOptionsArgument({ overflow: "reject" }) // true
+ * @example isOptionsArgument(null) // false
+ * @example isOptionsArgument("seconds") // false
+ * @returns whether `options` is `undefined` or a non-null object
+ */
+export function isOptionsArgument(options) {
+    return options === undefined || isObject(options);
+}