@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/dateUnitHelpers.d.ts

@@ -3,16 +3,19 @@ import type { Temporal } from "@js-temporal/polyfill";
  * Return the start of the specified date `unit` for a `Temporal.PlainDate`.
  *
  * - Always uses Monday as the week start (consistent with roundDate semantics).
+ * - Works in `source`'s own calendar (a Hebrew month starts on its day 1).
  * - Does NOT validate the unit — caller ensures it is a DateUnit.
  *
  * @param source Temporal.PlainDate to round
  * @param unit DateUnit to specify the unit for the start
- * @returns Temporal.PlainDate at the start of the specified unit
+ * @returns Temporal.PlainDate at the start of the specified unit; throws RangeError when it lies
+ *   before the representable range
  */
 export declare function getStartOfDateUnit(source: Temporal.PlainDate, unit: string): Temporal.PlainDate;
 /**
  * Add `amount` units of the specified date `unit` to a `Temporal.PlainDate`.
  *
+ * - Calendar units resolve in `source`'s calendar through the Temporal compat layer.
  * - Does NOT validate the unit — caller ensures it is a DateUnit.
  *
  * @param date Temporal.PlainDate to advance
@@ -21,3 +24,38 @@ export declare function getStartOfDateUnit(source: Temporal.PlainDate, unit: str
  * @returns new Temporal.PlainDate advanced by the specified amount
  */
 export declare function addDateUnit(date: Temporal.PlainDate, unit: string, amount: number): Temporal.PlainDate;
+/**
+ * Return the start of the date `unit` after the one containing `source`.
+ *
+ * - Steps one unit first and truncates after, so `source`'s own start is never materialised: the
+ *   month holding the first representable date (`-271821-04-19`) began before the range, while the
+ *   next month's start did not. Both orders agree everywhere else, because a one-unit step clamps
+ *   within the next unit (Jan 31 + 1 month = Feb 29, whose month starts on Feb 1).
+ * - Always uses Monday as the week start, like `getStartOfDateUnit`.
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source Temporal.PlainDate inside the current unit
+ * @param unit DateUnit to step by
+ * @returns Temporal.PlainDate at the start of the next unit
+ *
+ * @example getStartOfNextDateUnit(Temporal.PlainDate.from("2024-01-31"), "month") // 2024-02-01
+ * @example getStartOfNextDateUnit(Temporal.PlainDate.from("-271821-04-19"), "month") // -271821-05-01
+ */
+export declare function getStartOfNextDateUnit(source: Temporal.PlainDate, unit: string): Temporal.PlainDate;
+/**
+ * Return the whole days from the start of the date `unit` containing `source` to `source`.
+ *
+ * - Read from the calendar fields, so the unit's start is never materialised (it may lie before
+ *   the representable range).
+ * - Always uses Monday as the week start, like `getStartOfDateUnit`. A day unit is 0 days in.
+ * - Accepts a `Temporal.PlainDate` or a `Temporal.PlainDateTime` (only its date matters).
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source value with calendar date fields, read in its own calendar
+ * @param unit DateUnit to measure within
+ * @returns number of whole days since the unit started
+ *
+ * @example getDaysIntoDateUnit(Temporal.PlainDate.from("2024-03-13"), "month") // 12
+ * @example getDaysIntoDateUnit(Temporal.PlainDate.from("2024-03-13"), "week") // 2 (a Wednesday)
+ */
+export declare function getDaysIntoDateUnit(source: Pick<Temporal.PlainDate, "day" | "dayOfWeek" | "dayOfYear">, unit: string): number;

package/dist/internal/dateUnitHelpers.js

@@ -1,23 +1,36 @@
+import { calendarDateAdd, calendarDateFromFields, calendarFieldsOf, } from "./temporalCompat/index.js";
+/**
+ * Day 1 of `source`'s month, or of month 1 of its year when `month` is 1, in `source`'s calendar.
+ * Non-ISO calendars build it from corrected reads through the Temporal compat layer (CORE-6: the
+ * polyfill's `with` is wrong or throws where its fields → ISO conversion is).
+ */
+function startOfCalendarPeriod(source, month) {
+    if (source.calendarId === "iso8601") {
+        return source.with(month === undefined ? { day: 1 } : { month, day: 1 });
+    }
+    const fields = calendarFieldsOf(source, source.calendarId);
+    return calendarDateFromFields(source.calendarId, { year: fields.year, month: month ?? fields.month, day: 1 }, "reject");
+}
 /**
  * Return the start of the specified date `unit` for a `Temporal.PlainDate`.
  *
  * - Always uses Monday as the week start (consistent with roundDate semantics).
+ * - Works in `source`'s own calendar (a Hebrew month starts on its day 1).
  * - Does NOT validate the unit — caller ensures it is a DateUnit.
  *
  * @param source Temporal.PlainDate to round
  * @param unit DateUnit to specify the unit for the start
- * @returns Temporal.PlainDate at the start of the specified unit
+ * @returns Temporal.PlainDate at the start of the specified unit; throws RangeError when it lies
+ *   before the representable range
  */
 export function getStartOfDateUnit(source, unit) {
     switch (unit) {
         case "year":
-            return source.with({ month: 1, day: 1 });
+            return startOfCalendarPeriod(source, 1);
         case "month":
-            return source.with({ day: 1 });
-        case "week": {
-            const daysToSubtract = source.dayOfWeek - 1;
-            return source.subtract({ days: daysToSubtract });
-        }
+            return startOfCalendarPeriod(source);
+        case "week":
+            return calendarDateAdd(source, { days: 1 - source.dayOfWeek }, "constrain");
         default:
             return source;
     }
@@ -25,6 +38,7 @@ export function getStartOfDateUnit(source, unit) {
 /**
  * Add `amount` units of the specified date `unit` to a `Temporal.PlainDate`.
  *
+ * - Calendar units resolve in `source`'s calendar through the Temporal compat layer.
  * - Does NOT validate the unit — caller ensures it is a DateUnit.
  *
  * @param date Temporal.PlainDate to advance
@@ -35,12 +49,60 @@ export function getStartOfDateUnit(source, unit) {
 export function addDateUnit(date, unit, amount) {
     switch (unit) {
         case "year":
-            return date.add({ years: amount });
+            return calendarDateAdd(date, { years: amount }, "constrain");
+        case "month":
+            return calendarDateAdd(date, { months: amount }, "constrain");
+        case "week":
+            return calendarDateAdd(date, { days: amount * 7 }, "constrain");
+        default:
+            return calendarDateAdd(date, { days: amount }, "constrain");
+    }
+}
+/**
+ * Return the start of the date `unit` after the one containing `source`.
+ *
+ * - Steps one unit first and truncates after, so `source`'s own start is never materialised: the
+ *   month holding the first representable date (`-271821-04-19`) began before the range, while the
+ *   next month's start did not. Both orders agree everywhere else, because a one-unit step clamps
+ *   within the next unit (Jan 31 + 1 month = Feb 29, whose month starts on Feb 1).
+ * - Always uses Monday as the week start, like `getStartOfDateUnit`.
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source Temporal.PlainDate inside the current unit
+ * @param unit DateUnit to step by
+ * @returns Temporal.PlainDate at the start of the next unit
+ *
+ * @example getStartOfNextDateUnit(Temporal.PlainDate.from("2024-01-31"), "month") // 2024-02-01
+ * @example getStartOfNextDateUnit(Temporal.PlainDate.from("-271821-04-19"), "month") // -271821-05-01
+ */
+export function getStartOfNextDateUnit(source, unit) {
+    return getStartOfDateUnit(addDateUnit(source, unit, 1), unit);
+}
+/**
+ * Return the whole days from the start of the date `unit` containing `source` to `source`.
+ *
+ * - Read from the calendar fields, so the unit's start is never materialised (it may lie before
+ *   the representable range).
+ * - Always uses Monday as the week start, like `getStartOfDateUnit`. A day unit is 0 days in.
+ * - Accepts a `Temporal.PlainDate` or a `Temporal.PlainDateTime` (only its date matters).
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source value with calendar date fields, read in its own calendar
+ * @param unit DateUnit to measure within
+ * @returns number of whole days since the unit started
+ *
+ * @example getDaysIntoDateUnit(Temporal.PlainDate.from("2024-03-13"), "month") // 12
+ * @example getDaysIntoDateUnit(Temporal.PlainDate.from("2024-03-13"), "week") // 2 (a Wednesday)
+ */
+export function getDaysIntoDateUnit(source, unit) {
+    switch (unit) {
+        case "year":
+            return source.dayOfYear - 1;
         case "month":
-            return date.add({ months: amount });
+            return source.day - 1;
         case "week":
-            return date.add({ days: amount * 7 });
+            return source.dayOfWeek - 1;
         default:
-            return date.add({ days: amount });
+            return 0;
     }
 }

package/dist/internal/defaultFractionalDigits.d.ts

@@ -0,0 +1,14 @@
+import type { FractionalDigit } from "../types/index.js";
+/**
+ * Resolve how many fractional second digits a result snapped to `unit` is printed with.
+ *
+ * - An explicit `fractionalSecondDigits` always wins — including an invalid one, which Temporal's
+ *   `toString` then rejects, so the caller returns its sentinel. Only an omitted member defaults.
+ * - Otherwise 3 for "millisecond", 6 for "microsecond", 9 for "nanosecond", and 0 for anything
+ *   coarser (or unrecognised), so the output never hides the precision the unit asked for.
+ *
+ * @param unit the unit the value was snapped or rounded to
+ * @param fractionalSecondDigits optional caller-supplied override
+ * @returns the digit count to pass to `toString({ fractionalSecondDigits })`
+ */
+export declare function defaultFractionalDigits(unit: string, fractionalSecondDigits?: FractionalDigit): FractionalDigit;

package/dist/internal/defaultFractionalDigits.js

@@ -0,0 +1,23 @@
+/** Sub-second units to the fractional digits that show them; every other unit shows none. */
+const DIGITS_BY_UNIT = {
+    millisecond: 3,
+    microsecond: 6,
+    nanosecond: 9,
+};
+/**
+ * Resolve how many fractional second digits a result snapped to `unit` is printed with.
+ *
+ * - An explicit `fractionalSecondDigits` always wins — including an invalid one, which Temporal's
+ *   `toString` then rejects, so the caller returns its sentinel. Only an omitted member defaults.
+ * - Otherwise 3 for "millisecond", 6 for "microsecond", 9 for "nanosecond", and 0 for anything
+ *   coarser (or unrecognised), so the output never hides the precision the unit asked for.
+ *
+ * @param unit the unit the value was snapped or rounded to
+ * @param fractionalSecondDigits optional caller-supplied override
+ * @returns the digit count to pass to `toString({ fractionalSecondDigits })`
+ */
+export function defaultFractionalDigits(unit, fractionalSecondDigits) {
+    return fractionalSecondDigits === undefined
+        ? (DIGITS_BY_UNIT[unit] ?? 0)
+        : fractionalSecondDigits;
+}

package/dist/internal/differenceRecord.d.ts

@@ -0,0 +1,32 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/** Temporal's duration fields, largest first (Temporal Table 21, the unit ladder). */
+declare const DURATION_FIELDS: readonly ["years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds"];
+/** A plural Temporal duration field name. */
+export type DurationField = (typeof DURATION_FIELDS)[number];
+/** How one Temporal type moves by a duration and measures the difference to another value. */
+export interface DifferenceOperations<T> {
+    add: (from: T, duration: Temporal.DurationLike) => T;
+    until: (from: T, to: T, largestUnit: DurationField) => Temporal.Duration;
+}
+/**
+ * Express a difference in exactly the listed units, so the record is the whole difference.
+ *
+ * `duration` is `start.until(end)` with `largestUnit` = the largest listed unit and the caller's
+ * rounding options. Its fields are kept while the listed units are contiguous or every unlisted
+ * unit between them is zero, so a single unit or adjacent units return Temporal's own fields.
+ * When an unlisted unit between two listed units has an amount, that amount is carried into the
+ * next smaller listed unit (and a listed `weeks` below months or years is measured afresh, because
+ * Temporal leaves weeks in `days` unless `largestUnit` is weeks): the start is moved by the listed amounts found so far (one Temporal
+ * `add`, which adds years and months before days), and the rest is measured from there to the
+ * rounded end (`start.add(duration)`) with `largestUnit` = that listed unit. The record then
+ * satisfies `start.add(record)` = `start.add(duration)`. Units smaller than the smallest listed
+ * unit are dropped, as for a single unit.
+ *
+ * @param start the start value
+ * @param duration the (rounded) difference from `start` with the largest listed unit
+ * @param units the listed plural units, any order, non-empty
+ * @param operations the type's `add` and `until`
+ * @returns the amount of each listed unit, keyed by plural unit name in the order of `units`
+ */
+export declare function differenceRecord<T>(start: T, duration: Temporal.Duration, units: readonly DurationField[], operations: DifferenceOperations<T>): Record<DurationField, number>;
+export {};

package/dist/internal/differenceRecord.js

@@ -0,0 +1,79 @@
+/** Temporal's duration fields, largest first (Temporal Table 21, the unit ladder). */
+const DURATION_FIELDS = [
+    "years",
+    "months",
+    "weeks",
+    "days",
+    "hours",
+    "minutes",
+    "seconds",
+    "milliseconds",
+    "microseconds",
+    "nanoseconds",
+];
+/** True when a field strictly between `larger` and `smaller` on the ladder has an amount. */
+function hasAmountBetween(duration, larger, smaller) {
+    const from = DURATION_FIELDS.indexOf(larger) + 1;
+    const to = DURATION_FIELDS.indexOf(smaller);
+    return DURATION_FIELDS.slice(from, to).some((field) => duration[field] !== 0);
+}
+/**
+ * True when `unit` has to be measured again from the moved start: an unlisted unit above it (and
+ * below the previous listed unit) has an amount, or `unit` is weeks in a duration whose largest
+ * unit is larger than weeks. Temporal balances weeks only when `largestUnit` is weeks (TC39
+ * Temporal DifferenceISODate: weeks are computed only for largestUnit "week"; for "month" and
+ * "year" the remainder is days), so such a duration holds its weeks in `days`.
+ */
+function needsCarry(duration, largest, previous, unit) {
+    if (hasAmountBetween(duration, previous, unit))
+        return true;
+    return unit === "weeks" && largest !== "weeks" && duration.days !== 0;
+}
+/**
+ * Express a difference in exactly the listed units, so the record is the whole difference.
+ *
+ * `duration` is `start.until(end)` with `largestUnit` = the largest listed unit and the caller's
+ * rounding options. Its fields are kept while the listed units are contiguous or every unlisted
+ * unit between them is zero, so a single unit or adjacent units return Temporal's own fields.
+ * When an unlisted unit between two listed units has an amount, that amount is carried into the
+ * next smaller listed unit (and a listed `weeks` below months or years is measured afresh, because
+ * Temporal leaves weeks in `days` unless `largestUnit` is weeks): the start is moved by the listed amounts found so far (one Temporal
+ * `add`, which adds years and months before days), and the rest is measured from there to the
+ * rounded end (`start.add(duration)`) with `largestUnit` = that listed unit. The record then
+ * satisfies `start.add(record)` = `start.add(duration)`. Units smaller than the smallest listed
+ * unit are dropped, as for a single unit.
+ *
+ * @param start the start value
+ * @param duration the (rounded) difference from `start` with the largest listed unit
+ * @param units the listed plural units, any order, non-empty
+ * @param operations the type's `add` and `until`
+ * @returns the amount of each listed unit, keyed by plural unit name in the order of `units`
+ */
+export function differenceRecord(start, duration, units, operations) {
+    const ordered = DURATION_FIELDS.filter((field) => units.includes(field));
+    const amounts = {};
+    let origin = start;
+    let current = duration;
+    let moved = {};
+    let largest = ordered[0];
+    let end;
+    ordered.forEach((unit, index) => {
+        const previous = ordered[index - 1];
+        if (previous !== undefined &&
+            largest !== undefined &&
+            needsCarry(current, largest, previous, unit)) {
+            end ??= operations.add(start, duration);
+            origin = operations.add(origin, moved);
+            current = operations.until(origin, end, unit);
+            largest = unit;
+            moved = {};
+        }
+        amounts[unit] = current[unit];
+        moved[unit] = current[unit];
+    });
+    // Keys follow the caller's order.
+    return units.reduce((record, unit) => {
+        record[unit] = amounts[unit];
+        return record;
+    }, {});
+}

package/dist/internal/divisionBoundary.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Return the offset of boundary `index` when a span of `total` integer units is cut into `count`
+ * equal pieces: `(total · index) / count` rounded to the nearest unit, an exact half rounding up
+ * (as `Math.round` does for the non-negative quotient).
+ *
+ * - Exact at any magnitude: the product is taken in `bigint`, never in a double, so spans past
+ *   2^53 units (about 104 days of nanoseconds) keep every unit.
+ * - `total` must be non-negative and `count` a positive integer; `index` runs from 0 to `count`.
+ *
+ * @param total span length in integer units (nanoseconds or milliseconds)
+ * @param index boundary number, 0 (the start) to `count` (the end)
+ * @param count number of pieces
+ * @returns the boundary's offset from the start, in the same units
+ *
+ * @example divisionBoundary(1_000_000_000n, 1, 3) // 333_333_333n
+ * @example divisionBoundary(1_000_000_000n, 2, 3) // 666_666_667n
+ * @example divisionBoundary(31_536_000_000_000_000_003n, 1, 3) // 10_512_000_000_000_000_001n
+ */
+export declare function divisionBoundary(total: bigint, index: number, count: number): bigint;

package/dist/internal/divisionBoundary.js

@@ -0,0 +1,23 @@
+/**
+ * Return the offset of boundary `index` when a span of `total` integer units is cut into `count`
+ * equal pieces: `(total · index) / count` rounded to the nearest unit, an exact half rounding up
+ * (as `Math.round` does for the non-negative quotient).
+ *
+ * - Exact at any magnitude: the product is taken in `bigint`, never in a double, so spans past
+ *   2^53 units (about 104 days of nanoseconds) keep every unit.
+ * - `total` must be non-negative and `count` a positive integer; `index` runs from 0 to `count`.
+ *
+ * @param total span length in integer units (nanoseconds or milliseconds)
+ * @param index boundary number, 0 (the start) to `count` (the end)
+ * @param count number of pieces
+ * @returns the boundary's offset from the start, in the same units
+ *
+ * @example divisionBoundary(1_000_000_000n, 1, 3) // 333_333_333n
+ * @example divisionBoundary(1_000_000_000n, 2, 3) // 666_666_667n
+ * @example divisionBoundary(31_536_000_000_000_000_003n, 1, 3) // 10_512_000_000_000_000_001n
+ */
+export function divisionBoundary(total, index, count) {
+    const pieces = BigInt(count);
+    // floor(total · index / count + 1/2); bigint division truncates, which is floor for these signs.
+    return (2n * total * BigInt(index) + pieces) / (2n * pieces);
+}

package/dist/internal/durationUntilString.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "@js-temporal/polyfill";
 import type { DurationStringOptions, RoundingOptions } from "../types/index.js";
 /**
  * Compute the ISO 8601 duration string between two Temporal objects via `.until()` + `.toString()`.

package/dist/internal/durationUntilString.js

@@ -1,10 +1,18 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { plainDateUntil } from "./plainDateUntil.js";
+import { zonedUntil } from "./zonedWallClockDifference.js";
 export function durationUntilString(start, end, largestUnit, options) {
-    const duration = start.until(end, {
+    const untilOptions = {
         largestUnit,
         smallestUnit: options?.smallestUnit,
         roundingIncrement: options?.roundingIncrement,
         roundingMode: options?.roundingMode,
-    });
+    };
+    const duration = start instanceof Temporal.ZonedDateTime
+        ? zonedUntil(start, end, untilOptions)
+        : start instanceof Temporal.PlainDate
+            ? plainDateUntil(start, end, largestUnit, options)
+            : start.until(end, untilOptions);
     return duration.toString({
         smallestUnit: options?.toStringSmallestUnit,
         fractionalSecondDigits: options?.fractionalSecondDigits,

package/dist/internal/englishCalendarNames.d.ts

@@ -1,2 +1,13 @@
+import type { Temporal } from "@js-temporal/polyfill";
 export declare const ENGLISH_WEEKDAY_NAMES: readonly ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
 export declare const ENGLISH_MONTH_NAMES: readonly ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/**
+ * The `Mon, 15 Jul 2024 12:00:00` stem RFC 5322 date-time and RFC 9110 IMF-fixdate share: English
+ * day and month names, zero-padded fields, read from the date-time's own wall clock.
+ *
+ * @param zdt the date-time; the caller has already rejected a year outside 0-9999
+ * @returns the stem, without a zone or `GMT` suffix
+ * @example englishDateTimeStem(Temporal.ZonedDateTime.from("2024-07-15T12:00:05+00:00[UTC]")) // "Mon, 15 Jul 2024 12:00:05"
+ * @example englishDateTimeStem(Temporal.ZonedDateTime.from("0099-01-03T04:05:06+00:00[UTC]")) // "Sat, 03 Jan 0099 04:05:06"
+ */
+export declare function englishDateTimeStem(zdt: Temporal.ZonedDateTime): string;

package/dist/internal/englishCalendarNames.js

@@ -1,4 +1,5 @@
-// RFC 2822 (§3.3) and RFC 7231 (§7.1.1.1) mandate English weekday/month
+// RFC 5322 §3.3 (which obsoletes RFC 2822) and RFC 9110 §5.6.7 (which obsoletes
+// RFC 7231) mandate English weekday/month
 // abbreviations regardless of the caller's locale — these are fixed,
 // non-locale-adaptive grammars, not a display format, so hardcoding the
 // English names here is not the i18n bug it would be in a formatter (see
@@ -28,3 +29,22 @@ export const ENGLISH_MONTH_NAMES = [
     "Nov",
     "Dec",
 ];
+/**
+ * The `Mon, 15 Jul 2024 12:00:00` stem RFC 5322 date-time and RFC 9110 IMF-fixdate share: English
+ * day and month names, zero-padded fields, read from the date-time's own wall clock.
+ *
+ * @param zdt the date-time; the caller has already rejected a year outside 0-9999
+ * @returns the stem, without a zone or `GMT` suffix
+ * @example englishDateTimeStem(Temporal.ZonedDateTime.from("2024-07-15T12:00:05+00:00[UTC]")) // "Mon, 15 Jul 2024 12:00:05"
+ * @example englishDateTimeStem(Temporal.ZonedDateTime.from("0099-01-03T04:05:06+00:00[UTC]")) // "Sat, 03 Jan 0099 04:05:06"
+ */
+export function englishDateTimeStem(zdt) {
+    const weekday = ENGLISH_WEEKDAY_NAMES[zdt.dayOfWeek - 1];
+    const day = String(zdt.day).padStart(2, "0");
+    const month = ENGLISH_MONTH_NAMES[zdt.month - 1];
+    const year = String(zdt.year).padStart(4, "0");
+    const hour = String(zdt.hour).padStart(2, "0");
+    const minute = String(zdt.minute).padStart(2, "0");
+    const second = String(zdt.second).padStart(2, "0");
+    return `${weekday}, ${day} ${month} ${year} ${hour}:${minute}:${second}`;
+}

package/dist/internal/epochNanoseconds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Smallest epoch-nanosecond value `Temporal.Instant` can represent:
+ * -10^8 days from the Unix epoch, i.e. `-271821-04-20T00:00:00Z`.
+ */
+export declare const MIN_EPOCH_NANOSECONDS = -8640000000000000000000n;
+/**
+ * Largest epoch-nanosecond value `Temporal.Instant` can represent:
+ * +10^8 days from the Unix epoch, i.e. `+275760-09-13T00:00:00Z`.
+ */
+export declare const MAX_EPOCH_NANOSECONDS = 8640000000000000000000n;
+/**
+ * Digits in `MAX_EPOCH_NANOSECONDS` (22) — the longest a decimal form of an in-range
+ * epoch-nanosecond value can be, sign excluded.
+ */
+export declare const MAX_EPOCH_NANOSECOND_DIGITS: number;
+/**
+ * Type guard for an epoch-nanosecond value the `precision/` namespace accepts: a `bigint`
+ * inside the range `Temporal.Instant` can represent.
+ *
+ * Every `precision/` function gates on this, so anything one of them accepts is renderable
+ * by `fromNanoseconds` — a value outside the range has no instant to convert back to.
+ *
+ * @example isValidEpochNanoseconds(0n) // true
+ * @example isValidEpochNanoseconds(8_640_000_000_000_000_000_001n) // false
+ * @example isValidEpochNanoseconds(0) // false — number, not bigint
+ */
+export declare function isValidEpochNanoseconds(value: unknown): value is bigint;

package/dist/internal/epochNanoseconds.js

@@ -0,0 +1,31 @@
+/**
+ * Smallest epoch-nanosecond value `Temporal.Instant` can represent:
+ * -10^8 days from the Unix epoch, i.e. `-271821-04-20T00:00:00Z`.
+ */
+export const MIN_EPOCH_NANOSECONDS = -8640000000000000000000n;
+/**
+ * Largest epoch-nanosecond value `Temporal.Instant` can represent:
+ * +10^8 days from the Unix epoch, i.e. `+275760-09-13T00:00:00Z`.
+ */
+export const MAX_EPOCH_NANOSECONDS = 8640000000000000000000n;
+/**
+ * Digits in `MAX_EPOCH_NANOSECONDS` (22) — the longest a decimal form of an in-range
+ * epoch-nanosecond value can be, sign excluded.
+ */
+export const MAX_EPOCH_NANOSECOND_DIGITS = MAX_EPOCH_NANOSECONDS.toString().length;
+/**
+ * Type guard for an epoch-nanosecond value the `precision/` namespace accepts: a `bigint`
+ * inside the range `Temporal.Instant` can represent.
+ *
+ * Every `precision/` function gates on this, so anything one of them accepts is renderable
+ * by `fromNanoseconds` — a value outside the range has no instant to convert back to.
+ *
+ * @example isValidEpochNanoseconds(0n) // true
+ * @example isValidEpochNanoseconds(8_640_000_000_000_000_000_001n) // false
+ * @example isValidEpochNanoseconds(0) // false — number, not bigint
+ */
+export function isValidEpochNanoseconds(value) {
+    return (typeof value === "bigint" &&
+        value >= MIN_EPOCH_NANOSECONDS &&
+        value <= MAX_EPOCH_NANOSECONDS);
+}

package/dist/internal/fiscalCalendar.d.ts

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FiscalPattern } from "../types/index.js";
+/**
+ * Return the fiscal year end falling in calendar year `year`, under the rule `anchor` states.
+ *
+ * The rule is "the <anchor's weekday> nearest to <anchor's month and day>", so the result is
+ * `anchor`'s month and day in `year`, shifted at most three days either way onto `anchor`'s
+ * weekday. A year end within three days of January 1 lands in the previous calendar year,
+ * which is why callers must track the calendar-year argument rather than read `.year` back
+ * off the result.
+ *
+ * - The month-day is moved into `year` with Temporal's `overflow: "constrain"`, so a
+ *   February 29 anchor targets February 28 in a common year before the weekday shift. A
+ *   "month-end" rule (the 26 CFR 1.441-2 style, "the last Saturday of February") would
+ *   instead put a February 28 anchor on February 29 in a leap year; this does not.
+ */
+export declare function fiscalYearEndIn(anchor: Temporal.PlainDate, year: number): Temporal.PlainDate;
+/**
+ * Locate the fiscal year containing `date` under the rule `anchor` states.
+ *
+ * - The fiscal year is the one whose end is the first at or after `date`.
+ * - `weeks` is derived from the gap between consecutive year ends — 52 or 53 — never assumed.
+ * - Returns null when that gap is neither 364 nor 371 days, which no "nearest weekday" rule
+ *   can produce and so only a corrupted anchor could reach.
+ */
+export declare function fiscalYearOf(date: Temporal.PlainDate, anchor: Temporal.PlainDate): {
+    start: Temporal.PlainDate;
+    weeks: number;
+} | null;
+/**
+ * Return the 1-based period holding `week` of a `weeks`-long fiscal year under `pattern`.
+ *
+ * The 53rd week, when the year has one, is appended to the final period — the NRF adds it
+ * "to the end of the calendar", which turns a 4-5-4 year's last quarter into 4-5-5.
+ */
+export declare function fiscalPeriodOfWeek(week: number, weeks: number, pattern: FiscalPattern): number;

package/dist/internal/fiscalCalendar.js

@@ -0,0 +1,86 @@
+import { Temporal } from "@js-temporal/polyfill";
+/** Weeks per period within one quarter, by pattern. */
+const WEEKS_PER_PERIOD = {
+    "4-5-4": [4, 5, 4],
+    "4-4-5": [4, 4, 5],
+    "5-4-4": [5, 4, 4],
+};
+/** Periods in a fiscal year — four quarters of three periods each. */
+const PERIODS_PER_YEAR = 12;
+/** Days in a 52-week fiscal year. */
+const DAYS_IN_52_WEEK_YEAR = 364;
+/** Days in a 53-week fiscal year. */
+const DAYS_IN_53_WEEK_YEAR = 371;
+/**
+ * Calendar-year offsets searched for the fiscal year end that bounds a date.
+ *
+ * A year end sits within three days of its rule's month-day, so it can fall in the calendar
+ * year either side of the one it is named for. Both outer offsets are reachable when the
+ * rule's month-day is within three days of January 1: `-1` when a year end lands in early
+ * January, `+2` when one lands in late December and the date is the last days of a year.
+ */
+const YEAR_END_SEARCH_OFFSETS = [-1, 0, 1, 2];
+/** Half the width of the 7-day window a "nearest weekday" year end can land in. */
+const NEAREST_WEEKDAY_RADIUS = 3;
+/**
+ * Return the fiscal year end falling in calendar year `year`, under the rule `anchor` states.
+ *
+ * The rule is "the <anchor's weekday> nearest to <anchor's month and day>", so the result is
+ * `anchor`'s month and day in `year`, shifted at most three days either way onto `anchor`'s
+ * weekday. A year end within three days of January 1 lands in the previous calendar year,
+ * which is why callers must track the calendar-year argument rather than read `.year` back
+ * off the result.
+ *
+ * - The month-day is moved into `year` with Temporal's `overflow: "constrain"`, so a
+ *   February 29 anchor targets February 28 in a common year before the weekday shift. A
+ *   "month-end" rule (the 26 CFR 1.441-2 style, "the last Saturday of February") would
+ *   instead put a February 28 anchor on February 29 in a leap year; this does not.
+ */
+export function fiscalYearEndIn(anchor, year) {
+    const target = anchor.with({ year }, { overflow: "constrain" });
+    const weekdayDelta = anchor.dayOfWeek - target.dayOfWeek;
+    // Map the -6..6 weekday delta onto the -3..3 nearest-occurrence shift.
+    const shift = ((weekdayDelta + NEAREST_WEEKDAY_RADIUS + 7) % 7) - NEAREST_WEEKDAY_RADIUS;
+    return target.add({ days: shift });
+}
+/**
+ * Locate the fiscal year containing `date` under the rule `anchor` states.
+ *
+ * - The fiscal year is the one whose end is the first at or after `date`.
+ * - `weeks` is derived from the gap between consecutive year ends — 52 or 53 — never assumed.
+ * - Returns null when that gap is neither 364 nor 371 days, which no "nearest weekday" rule
+ *   can produce and so only a corrupted anchor could reach.
+ */
+export function fiscalYearOf(date, anchor) {
+    for (const offset of YEAR_END_SEARCH_OFFSETS) {
+        const year = date.year + offset;
+        const end = fiscalYearEndIn(anchor, year);
+        if (Temporal.PlainDate.compare(end, date) < 0)
+            continue;
+        const start = fiscalYearEndIn(anchor, year - 1).add({ days: 1 });
+        const days = start.until(end, { largestUnit: "day" }).days + 1;
+        if (days !== DAYS_IN_52_WEEK_YEAR && days !== DAYS_IN_53_WEEK_YEAR) {
+            return null;
+        }
+        return { start, weeks: days / 7 };
+    }
+    return null;
+}
+/**
+ * Return the 1-based period holding `week` of a `weeks`-long fiscal year under `pattern`.
+ *
+ * The 53rd week, when the year has one, is appended to the final period — the NRF adds it
+ * "to the end of the calendar", which turns a 4-5-4 year's last quarter into 4-5-5.
+ */
+export function fiscalPeriodOfWeek(week, weeks, pattern) {
+    const quarterShape = WEEKS_PER_PERIOD[pattern];
+    let consumed = 0;
+    for (let period = 1; period <= PERIODS_PER_YEAR; period++) {
+        const isFinalPeriod = period === PERIODS_PER_YEAR;
+        const extraWeek = isFinalPeriod && weeks === 53 ? 1 : 0;
+        consumed += quarterShape[(period - 1) % quarterShape.length] + extraWeek;
+        if (week <= consumed)
+            return period;
+    }
+    return PERIODS_PER_YEAR;
+}

package/dist/internal/floorDivide.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Divide two bigints, flooring toward negative infinity.
+ *
+ * BigInt `/` truncates toward zero, so `-1n / 100n` is `0n` — the same slot as `0n / 100n`.
+ * Every foreign-epoch bridge in `precision/convert/` scales nanoseconds down to a coarser
+ * unit (100 ns for FILETIME and .NET ticks, 2^-32 s for NTP), and a truncating divide would
+ * make the last tick before an epoch collide with the first tick after it. Flooring keeps
+ * the unit grid uniform across zero, which is also what `truncateNanoseconds` does.
+ *
+ * @example floorDivide(150n, 100n) // 1n
+ * @example floorDivide(-150n, 100n) // -2n
+ * @example floorDivide(-100n, 100n) // -1n
+ * @example floorDivide(0n, 100n) // 0n
+ */
+export declare function floorDivide(value: bigint, divisor: bigint): bigint;