@northguild/gmt 1.15.0 → 1.16.0

package/dist/calendar/calculate/bucketRange.js

@@ -0,0 +1,169 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { nextZonedBucketStart, zonedNextTransition, zonedUnitStart, } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { isValidZoneBucketUnit } from "../validate/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+/**
+ * Buckets a single call will return before giving up.
+ *
+ * Temporal's range runs to ±273,790 years, so an unbounded hour walk over it would exhaust
+ * memory. This covers 416 days of hours, 27 years of days, 192 years of weeks or 833 years of
+ * months — past anything a caller renders or aggregates in one pass.
+ */
+const MAX_BUCKETS = 10_000;
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+/**
+ * The longest wall-clock stretch of each unit. Any wall-clock interval this long holds a unit
+ * start: an hour holds an hour start, 24 hours a midnight, 7 days a Monday, 31 days a first of
+ * the month.
+ */
+const LONGEST_UNIT_NANOSECONDS = {
+    hour: NANOSECONDS_PER_HOUR,
+    day: 24n * NANOSECONDS_PER_HOUR,
+    week: 168n * NANOSECONDS_PER_HOUR,
+    month: 744n * NANOSECONDS_PER_HOUR,
+};
+/** Offset transitions read before the pre-count gives up and leaves the answer to the walk. */
+const MAX_PRECOUNT_TRANSITIONS = 4_096;
+/**
+ * True when `[start, end)` certainly touches more than `MAX_BUCKETS` buckets, decided from the span
+ * instead of stepping bucket by bucket (which costs milliseconds a step in some zones).
+ *
+ * Over a prefix of the range, the local wall clock runs continuously between offset transitions.
+ * Those stretches cover at least the prefix's length less every backward offset change, in at most
+ * one stretch more than there are transitions, and each stretch of wall clock holds at least
+ * `floor(length / LONGEST_UNIT_NANOSECONDS)` distinct unit starts, each the start of its own
+ * bucket before `end`. The count subtracts two per stretch for the partial units at its ends.
+ * `false` means "not certain": the walk decides, exactly as before.
+ */
+function certainlyExceedsBucketCap(startZoned, endZoned, unit) {
+    const unitNs = LONGEST_UNIT_NANOSECONDS[unit];
+    const startNs = startZoned.epochNanoseconds;
+    const prefixEndNs = [
+        endZoned.epochNanoseconds,
+        startNs + 2n * BigInt(MAX_BUCKETS + 1) * unitNs,
+    ].reduce((a, b) => (a < b ? a : b));
+    if (prefixEndNs - startNs <= BigInt(MAX_BUCKETS) * unitNs) {
+        return false;
+    }
+    let backwardNs = 0n;
+    let transitions = 0;
+    try {
+        for (let current = startZoned, next = zonedNextTransition(current); next !== null && next.epochNanoseconds < prefixEndNs; current = next, next = zonedNextTransition(current)) {
+            if (++transitions > MAX_PRECOUNT_TRANSITIONS) {
+                return false;
+            }
+            const shift = BigInt(current.offsetNanoseconds - next.offsetNanoseconds);
+            backwardNs += shift > 0n ? shift : 0n;
+        }
+    }
+    catch {
+        return false;
+    }
+    const wallStarts = (prefixEndNs - startNs - backwardNs) / unitNs;
+    return wallStarts - 2n * BigInt(transitions + 1) > BigInt(MAX_BUCKETS);
+}
+/**
+ * The bucket start after `current`: `undefined` when it lies past Temporal's last representable
+ * instant, null when the stepper cannot find it.
+ */
+function nextBucketStartWithinRange(current, unit) {
+    try {
+        return nextZonedBucketStart(current, unit);
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Return the start instant of every `unit` bucket the half-open range `[start, end)` touches,
+ * bucketed **in `timeZone`**.
+ *
+ * This is "group by day in `America/New_York`" over UTC timestamps, done correctly. Buckets
+ * are not uniform in length and that is the point: a day that springs forward is 23 hours and
+ * one that falls back is 25, so a daily aggregate built on a fixed 24 hours drifts an hour
+ * twice a year, and a container's chargeable days — counted in terminal-local calendar days —
+ * come out wrong.
+ *
+ * - Each entry is a boundary `floorToZone` would return, so bucket *i* runs from `result[i]`
+ *   up to (not including) `result[i + 1]`, and the last runs to the next boundary after it.
+ * - The range is half-open: an `end` landing exactly on a boundary does not open that bucket.
+ *   A zero-length range mid-bucket still returns the one bucket holding it; on a boundary it
+ *   returns `[]`.
+ * - Both endpoints are read in `timeZone`. Any bracketed zone they carry is ignored, as in
+ *   `floorToZone`.
+ * - Weeks start on Monday (ISO 8601). `unit` is the same four-unit set `floorToZone` takes,
+ *   singular or plural, which `isValidZoneBucketUnit` narrows.
+ * - A local boundary that does not exist is not invented: the day Samoa deleted crossing the
+ *   date line is absent, a local day whose midnight is skipped starts at 01:00, and in a zone
+ *   that falls back by half an hour the local 01:00 hour bucket is 90 minutes long.
+ * - A bucket is returned when its start is representable, even if the bucket after it would
+ *   start past Temporal's last instant (`+275760-09-13T00:00:00Z`).
+ * - Returns `[]` on invalid input, when `start` is after `end`, when the range would need more
+ *   than 10,000 buckets, when a boundary in it is not representable (see `floorToZone`), and
+ *   if a zone ever presented more transitions inside one bucket than the stepper walks — no
+ *   IANA zone does, and the whole table was swept to confirm it. A truncated list would be
+ *   worse than the sentinel, so none is returned in any of those cases.
+ *
+ * @param start ISO 8601 instant string for the range start (inclusive)
+ * @param end ISO 8601 instant string for the range end (exclusive)
+ * @param unit bucket unit ("hour" | "day" | "week" | "month", or its plural)
+ * @param timeZone IANA timeZone identifier the buckets are computed in
+ * @returns array of UTC instant strings ending in "Z", or [] on invalid input
+ *
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "day", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"]
+ * @example bucketRange("2024-03-09T05:00:00Z", "2024-03-12T04:00:00Z", "day", "America/New_York") // ["2024-03-09T05:00:00Z", "2024-03-10T05:00:00Z", "2024-03-11T04:00:00Z"] (the middle day is 23 hours)
+ * @example bucketRange("2024-11-02T04:00:00Z", "2024-11-05T05:00:00Z", "day", "America/New_York") // ["2024-11-02T04:00:00Z", "2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z"] (the middle day is 25 hours)
+ * @example bucketRange("2024-11-03T04:00:00Z", "2024-11-03T08:00:00Z", "hour", "America/New_York") // ["2024-11-03T04:00:00Z", "2024-11-03T05:00:00Z", "2024-11-03T06:00:00Z", "2024-11-03T07:00:00Z"] (the repeated 01:00 is its own bucket)
+ * @example bucketRange("2024-06-14T04:00:00Z", "2024-06-14T04:00:00Z", "day", "America/New_York") // [] (zero length, on a boundary)
+ * @example bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/New_York") // ["+275760-09-12T04:00:00Z"] (the next day would start past the last instant; this one is still returned)
+ * @example bucketRange("2024-06-16T00:00:00Z", "2024-06-15T00:00:00Z", "day", "UTC") // [] (start after end)
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "days", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"] (plural unit name)
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "year", "UTC") // [] (not a bucketing unit)
+ */
+export function bucketRange(start, end, unit, timeZone) {
+    // The singular name; the guard below rejects anything outside the four units.
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidInstant(start) ||
+        !isValidInstant(end) ||
+        !isValidZoneBucketUnit(resolvedUnit) ||
+        !isValidTimeZone(timeZone)) {
+        return [];
+    }
+    try {
+        const startZoned = Temporal.Instant.from(start).toZonedDateTimeISO(timeZone);
+        const endZoned = Temporal.Instant.from(end).toZonedDateTimeISO(timeZone);
+        if (Temporal.ZonedDateTime.compare(startZoned, endZoned) > 0)
+            return [];
+        if (certainlyExceedsBucketCap(startZoned, endZoned, resolvedUnit))
+            return [];
+        const boundaries = [];
+        const first = zonedUnitStart(startZoned, resolvedUnit);
+        if (!first)
+            return [];
+        let current = first;
+        for (let i = 0; i < MAX_BUCKETS; i++) {
+            if (Temporal.ZonedDateTime.compare(current, endZoned) >= 0) {
+                return boundaries;
+            }
+            boundaries.push(current.toInstant().toString());
+            const next = nextBucketStartWithinRange(current, resolvedUnit);
+            // Past the last representable instant, so after `end`: every touched bucket is collected.
+            if (next === undefined)
+                return boundaries;
+            if (!next)
+                return [];
+            current = next;
+        }
+        // `MAX_BUCKETS` boundaries are collected; the range fit only if the next one clears `end`.
+        return Temporal.ZonedDateTime.compare(current, endZoned) >= 0
+            ? boundaries
+            : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/calendar/calculate/floorToZone.d.ts

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { ZoneBucketUnit } from "../../types/index.js";
+/**
+ * Floor an instant to the start of the `unit` containing it **in `timeZone`**, and return
+ * the instant of that boundary.
+ *
+ * Flooring a UTC instant to a UTC day and calling it a local day is wrong for most of the
+ * world for most of the day: 03:00 UTC on 15 June is still 14 June in New York, so the local
+ * day it belongs to started 20 hours before the UTC one did. The zone is an argument because
+ * GMT has no ambient one and must not acquire one.
+ *
+ * - `unit` is `"hour"`, `"day"`, `"week"` or `"month"`, or its plural (`"days"`), as Temporal
+ *   accepts. Weeks start on Monday (ISO 8601), matching `startOfZoned` and `intervalCountZoned`.
+ *   `isValidZoneBucketUnit` narrows a candidate unit, singular or plural, so a unit out of config
+ *   can be told apart from a bad instant.
+ * - `value` is any instant `isValidInstant` accepts — `Z`, an offset, or a bracketed zone.
+ *   Only its instant is read: a bracketed zone in `value` is *not* the zone the boundary is
+ *   computed in, `timeZone` is, and the two may differ freely.
+ * - The boundary is a real instant in the zone, so it survives the days a local boundary does
+ *   not exist: a local day whose midnight is skipped by a spring-forward starts at 01:00, and
+ *   a wall hour repeated by a fall-back floors to whichever pass `value` was in.
+ * - Returns a UTC instant string ending in `"Z"`, exactly — no rounding.
+ * - Returns `""` on invalid input, and where the boundary itself is not representable — the
+ *   week or month containing the first instant Temporal supports began before it.
+ *
+ * @param value ISO 8601 instant string (e.g. "2024-06-15T03:00:00Z")
+ * @param unit boundary unit ("hour" | "day" | "week" | "month", or its plural)
+ * @param timeZone IANA timeZone identifier the boundary is computed in
+ * @returns UTC instant string ending in "Z", or "" on invalid input
+ *
+ * @example floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York") // "2024-06-14T04:00:00Z" (the 14 June local midnight — the instant is already 14 June there)
+ * @example floorToZone("2024-06-15T03:00:00Z", "day", "UTC") // "2024-06-15T00:00:00Z" (the same instant, a different local day)
+ * @example floorToZone("2024-06-15T03:00:00Z", "hour", "Asia/Kathmandu") // "2024-06-15T02:15:00Z" (a +05:45 zone's hour boundary)
+ * @example floorToZone("2024-06-15T03:00:00Z", "week", "America/New_York") // "2024-06-10T04:00:00Z" (the Monday)
+ * @example floorToZone("2024-09-08T10:00:00Z", "day", "America/Santiago") // "2024-09-08T04:00:00Z" (local midnight is skipped, so the day starts at 01:00)
+ * @example floorToZone("2024-05-15T10:20:30.123Z", "days", "Europe/Berlin") // "2024-05-14T22:00:00Z" (plural unit name)
+ * @example floorToZone("2024-06-15T03:00:00Z", "year", "UTC") // "" (not a bucketing unit)
+ * @example floorToZone("2024-06-15T03:00:00", "day", "UTC") // "" (zoneless, so it names no instant)
+ * @example floorToZone("-271821-04-20T00:00:00Z", "month", "UTC") // "" (that month began before Temporal's range does)
+ * @example floorToZone("2024-06-15T03:00:00Z", "day", "Invalid/Zone") // ""
+ */
+export declare function floorToZone(value: string, unit: Temporal.SmallestUnit<ZoneBucketUnit>, timeZone: string): string;

package/dist/calendar/calculate/floorToZone.js

@@ -0,0 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { zonedUnitStart } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { isValidZoneBucketUnit } from "../validate/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+/**
+ * Floor an instant to the start of the `unit` containing it **in `timeZone`**, and return
+ * the instant of that boundary.
+ *
+ * Flooring a UTC instant to a UTC day and calling it a local day is wrong for most of the
+ * world for most of the day: 03:00 UTC on 15 June is still 14 June in New York, so the local
+ * day it belongs to started 20 hours before the UTC one did. The zone is an argument because
+ * GMT has no ambient one and must not acquire one.
+ *
+ * - `unit` is `"hour"`, `"day"`, `"week"` or `"month"`, or its plural (`"days"`), as Temporal
+ *   accepts. Weeks start on Monday (ISO 8601), matching `startOfZoned` and `intervalCountZoned`.
+ *   `isValidZoneBucketUnit` narrows a candidate unit, singular or plural, so a unit out of config
+ *   can be told apart from a bad instant.
+ * - `value` is any instant `isValidInstant` accepts — `Z`, an offset, or a bracketed zone.
+ *   Only its instant is read: a bracketed zone in `value` is *not* the zone the boundary is
+ *   computed in, `timeZone` is, and the two may differ freely.
+ * - The boundary is a real instant in the zone, so it survives the days a local boundary does
+ *   not exist: a local day whose midnight is skipped by a spring-forward starts at 01:00, and
+ *   a wall hour repeated by a fall-back floors to whichever pass `value` was in.
+ * - Returns a UTC instant string ending in `"Z"`, exactly — no rounding.
+ * - Returns `""` on invalid input, and where the boundary itself is not representable — the
+ *   week or month containing the first instant Temporal supports began before it.
+ *
+ * @param value ISO 8601 instant string (e.g. "2024-06-15T03:00:00Z")
+ * @param unit boundary unit ("hour" | "day" | "week" | "month", or its plural)
+ * @param timeZone IANA timeZone identifier the boundary is computed in
+ * @returns UTC instant string ending in "Z", or "" on invalid input
+ *
+ * @example floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York") // "2024-06-14T04:00:00Z" (the 14 June local midnight — the instant is already 14 June there)
+ * @example floorToZone("2024-06-15T03:00:00Z", "day", "UTC") // "2024-06-15T00:00:00Z" (the same instant, a different local day)
+ * @example floorToZone("2024-06-15T03:00:00Z", "hour", "Asia/Kathmandu") // "2024-06-15T02:15:00Z" (a +05:45 zone's hour boundary)
+ * @example floorToZone("2024-06-15T03:00:00Z", "week", "America/New_York") // "2024-06-10T04:00:00Z" (the Monday)
+ * @example floorToZone("2024-09-08T10:00:00Z", "day", "America/Santiago") // "2024-09-08T04:00:00Z" (local midnight is skipped, so the day starts at 01:00)
+ * @example floorToZone("2024-05-15T10:20:30.123Z", "days", "Europe/Berlin") // "2024-05-14T22:00:00Z" (plural unit name)
+ * @example floorToZone("2024-06-15T03:00:00Z", "year", "UTC") // "" (not a bucketing unit)
+ * @example floorToZone("2024-06-15T03:00:00", "day", "UTC") // "" (zoneless, so it names no instant)
+ * @example floorToZone("-271821-04-20T00:00:00Z", "month", "UTC") // "" (that month began before Temporal's range does)
+ * @example floorToZone("2024-06-15T03:00:00Z", "day", "Invalid/Zone") // ""
+ */
+export function floorToZone(value, unit, timeZone) {
+    // The singular name; the guard below rejects anything outside the four units.
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidInstant(value) ||
+        !isValidZoneBucketUnit(resolvedUnit) ||
+        !isValidTimeZone(timeZone)) {
+        return "";
+    }
+    try {
+        const zoned = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+        const start = zonedUnitStart(zoned, resolvedUnit);
+        return start ? start.toInstant().toString() : "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/calendar/calculate/getFiscalPeriod.d.ts

@@ -0,0 +1,64 @@
+import type { FiscalCalendar } from "../../types/index.js";
+/**
+ * Return the fiscal year, period and week `value` falls in, for a 52/53-week retail calendar.
+ *
+ * 52 × 7 is 364 days, so a 52-week fiscal year drifts a day or two against the sun every year
+ * and a 53rd week is inserted every five or six to pull it back. Both the drift and the
+ * insertion fall out of `calendar` — nothing here is bundled, because there is no single
+ * correct retail calendar.
+ *
+ * - `calendar.pattern` is the weeks-per-period shape of a quarter: `"4-5-4"` (the NRF retail
+ *   standard), `"4-4-5"` or `"5-4-4"`. Four quarters of 13 weeks make the 52-week year.
+ * - **`calendar.yearEndsOn` states the year-end *rule*, by example, not one year's end.**
+ *   Fiscal years end on that date's weekday, on the occurrence nearest that date's month and
+ *   day. The NRF's published rule — "the Saturday nearest to January 31"
+ *   ([NRF 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar)) — is `"2026-01-31"`, a
+ *   Saturday falling exactly on January 31. Passing a published year end from a 53-week year
+ *   instead (`"2024-02-03"`) states a different rule, because that date sits three days off
+ *   the target the rule is centred on, and yields a different, self-consistent calendar.
+ * - `week` is the week of the fiscal year, 1–53, the numbering the NRF publishes. `period` is
+ *   1–12. A 53rd week is appended to period 12 — the NRF adds it "to the end of the
+ *   calendar", which makes a 4-5-4 year's final quarter 4-5-5.
+ * - **`year` is the calendar year the fiscal year starts in**, matching the NRF: fiscal 2023
+ *   runs 2023-01-29 to 2024-02-03. Organisations labelling by the end year should add one.
+ * - **`year` is not a unique key for a rule anchored near 1 January.** A 52/53-week year is
+ *   364 or 371 days, so it drifts against the calendar, and no label taken from a calendar
+ *   year survives that for every anchor. Under `yearEndsOn: "2022-12-31"` — the Saturday
+ *   nearest to 31 December — two consecutive fiscal years both start in 2023 and share the
+ *   label, and 2020, 2025 and 2031 label no fiscal year at all. Grouping by `year` there
+ *   merges 104 weeks and drops a year. `"2027-01-02"` states a different rule, the Saturday
+ *   nearest to 2 January: it too gives 2023 twice, merging 105 weeks, and skips 2018, 2024
+ *   and 2029. January/February anchors like the NRF's
+ *   are unaffected. If your rule sits near a year boundary, key on the fiscal year's own start
+ *   date — which `yearEndsOn` determines, and which is yours to enumerate — not on `year`.
+ *   GMT does not invent a label the inputs do not fix.
+ * - A `yearEndsOn` month-day that does not exist in a year follows Temporal's
+ *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A
+ *   "month-end" rule (26 CFR 1.441-2 style) would put a February 28 anchor on February 29 in
+ *   leap years; this does not — state such a rule with a date that exists every year.
+ * - Whether a fiscal year has 52 or 53 weeks is derived from the gap between its own two
+ *   ends, never assumed from a table.
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
+ *   `getIsoWeekDate` for why a moment is not accepted here.
+ * - Returns null on invalid input, including an unrecognised pattern or a `yearEndsOn` that
+ *   is not a plain ISO date. Both share the sentinel with a date that cannot be placed, so
+ *   check the calendar with `isValidFiscalPattern` and `isValidDate` first to tell a
+ *   misconfigured calendar apart from an unusable date.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @param calendar { pattern: "4-5-4" | "4-4-5" | "5-4-4", yearEndsOn: ISO date stating the rule }
+ * @returns { year, period, week }, or null on invalid input
+ *
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 5, week: 19 }
+ * @example getFiscalPeriod("2024-02-04", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 1, week: 1 } (NRF fiscal 2024 opens)
+ * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2023, period: 12, week: 53 } (the 53rd week of NRF fiscal 2023)
+ * @example getFiscalPeriod("2024-03-31", { pattern: "4-4-5", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 3, week: 9 } (the same week, a period later than 4-5-4 puts it)
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-5", yearEndsOn: "2026-01-31" }) // null (not one of the three patterns)
+ * @example getFiscalPeriod("2024-06-15T12:00:00Z", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null (a moment, not a calendar date)
+ * @example getFiscalPeriod("invalid", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null
+ */
+export declare function getFiscalPeriod(value: string, calendar: FiscalCalendar): {
+    year: number;
+    period: number;
+    week: number;
+} | null;

package/dist/calendar/calculate/getFiscalPeriod.js

@@ -0,0 +1,96 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { fiscalPeriodOfWeek, fiscalYearOf, zonelessCalendarDate, } from "../../internal/index.js";
+import { isValidDate } from "../../plain/validate/index.js";
+import { isValidFiscalPattern } from "../validate/index.js";
+/** Days in a fiscal week. */
+const DAYS_PER_WEEK = 7;
+/**
+ * Return the fiscal year, period and week `value` falls in, for a 52/53-week retail calendar.
+ *
+ * 52 × 7 is 364 days, so a 52-week fiscal year drifts a day or two against the sun every year
+ * and a 53rd week is inserted every five or six to pull it back. Both the drift and the
+ * insertion fall out of `calendar` — nothing here is bundled, because there is no single
+ * correct retail calendar.
+ *
+ * - `calendar.pattern` is the weeks-per-period shape of a quarter: `"4-5-4"` (the NRF retail
+ *   standard), `"4-4-5"` or `"5-4-4"`. Four quarters of 13 weeks make the 52-week year.
+ * - **`calendar.yearEndsOn` states the year-end *rule*, by example, not one year's end.**
+ *   Fiscal years end on that date's weekday, on the occurrence nearest that date's month and
+ *   day. The NRF's published rule — "the Saturday nearest to January 31"
+ *   ([NRF 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar)) — is `"2026-01-31"`, a
+ *   Saturday falling exactly on January 31. Passing a published year end from a 53-week year
+ *   instead (`"2024-02-03"`) states a different rule, because that date sits three days off
+ *   the target the rule is centred on, and yields a different, self-consistent calendar.
+ * - `week` is the week of the fiscal year, 1–53, the numbering the NRF publishes. `period` is
+ *   1–12. A 53rd week is appended to period 12 — the NRF adds it "to the end of the
+ *   calendar", which makes a 4-5-4 year's final quarter 4-5-5.
+ * - **`year` is the calendar year the fiscal year starts in**, matching the NRF: fiscal 2023
+ *   runs 2023-01-29 to 2024-02-03. Organisations labelling by the end year should add one.
+ * - **`year` is not a unique key for a rule anchored near 1 January.** A 52/53-week year is
+ *   364 or 371 days, so it drifts against the calendar, and no label taken from a calendar
+ *   year survives that for every anchor. Under `yearEndsOn: "2022-12-31"` — the Saturday
+ *   nearest to 31 December — two consecutive fiscal years both start in 2023 and share the
+ *   label, and 2020, 2025 and 2031 label no fiscal year at all. Grouping by `year` there
+ *   merges 104 weeks and drops a year. `"2027-01-02"` states a different rule, the Saturday
+ *   nearest to 2 January: it too gives 2023 twice, merging 105 weeks, and skips 2018, 2024
+ *   and 2029. January/February anchors like the NRF's
+ *   are unaffected. If your rule sits near a year boundary, key on the fiscal year's own start
+ *   date — which `yearEndsOn` determines, and which is yours to enumerate — not on `year`.
+ *   GMT does not invent a label the inputs do not fix.
+ * - A `yearEndsOn` month-day that does not exist in a year follows Temporal's
+ *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A
+ *   "month-end" rule (26 CFR 1.441-2 style) would put a February 28 anchor on February 29 in
+ *   leap years; this does not — state such a rule with a date that exists every year.
+ * - Whether a fiscal year has 52 or 53 weeks is derived from the gap between its own two
+ *   ends, never assumed from a table.
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
+ *   `getIsoWeekDate` for why a moment is not accepted here.
+ * - Returns null on invalid input, including an unrecognised pattern or a `yearEndsOn` that
+ *   is not a plain ISO date. Both share the sentinel with a date that cannot be placed, so
+ *   check the calendar with `isValidFiscalPattern` and `isValidDate` first to tell a
+ *   misconfigured calendar apart from an unusable date.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @param calendar { pattern: "4-5-4" | "4-4-5" | "5-4-4", yearEndsOn: ISO date stating the rule }
+ * @returns { year, period, week }, or null on invalid input
+ *
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 5, week: 19 }
+ * @example getFiscalPeriod("2024-02-04", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 1, week: 1 } (NRF fiscal 2024 opens)
+ * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2023, period: 12, week: 53 } (the 53rd week of NRF fiscal 2023)
+ * @example getFiscalPeriod("2024-03-31", { pattern: "4-4-5", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 3, week: 9 } (the same week, a period later than 4-5-4 puts it)
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-5", yearEndsOn: "2026-01-31" }) // null (not one of the three patterns)
+ * @example getFiscalPeriod("2024-06-15T12:00:00Z", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null (a moment, not a calendar date)
+ * @example getFiscalPeriod("invalid", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null
+ */
+export function getFiscalPeriod(value, calendar) {
+    try {
+        const pattern = calendar?.pattern;
+        const yearEndsOn = calendar?.yearEndsOn;
+        if (!isValidFiscalPattern(pattern) || !isValidDate(yearEndsOn)) {
+            return null;
+        }
+        const date = zonelessCalendarDate(value);
+        if (!date)
+            return null;
+        try {
+            const fiscalYear = fiscalYearOf(date, Temporal.PlainDate.from(yearEndsOn));
+            if (!fiscalYear)
+                return null;
+            const { start, weeks } = fiscalYear;
+            const week = Math.floor(start.until(date, { largestUnit: "day" }).days / DAYS_PER_WEEK) + 1;
+            return {
+                year: start.year,
+                period: fiscalPeriodOfWeek(week, weeks, pattern),
+                week,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/calendar/calculate/getIsoWeekDate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Return the ISO 8601 week date — week-numbering year, week and weekday — for `value`.
+ *
+ * Vessel schedules, production plans and retail reports are published by week number, and a
+ * week number alone is ambiguous: the week-numbering year is not the calendar year at either
+ * end of a year, so all three fields come back together rather than as three calls a caller
+ * could combine inconsistently.
+ *
+ * - `year` is the ISO week-numbering year (`Temporal.PlainDate.yearOfWeek`), which differs
+ *   from the calendar year for late-December and early-January dates.
+ * - `week` is 1–53. ISO week 1 is the week containing the year's first Thursday, so a
+ *   week-numbering year has 53 weeks roughly every five to six years.
+ * - `weekday` is 1 (Monday) through 7 (Sunday).
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. An
+ *   offset, a `Z` or a bracketed zone makes it a moment rather than a calendar date; convert
+ *   it in the zone you mean first (`convertUtcToZoned` then `convertZonedToPlainDateTime`),
+ *   or floor it with `floorToZone`.
+ * - Returns null on invalid input.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @returns { year, week, weekday }, or null on invalid input
+ *
+ * @example getIsoWeekDate("2024-06-15") // { year: 2024, week: 24, weekday: 6 }
+ * @example getIsoWeekDate("2027-01-01") // { year: 2026, week: 53, weekday: 5 } (week-year 2026, not 2027)
+ * @example getIsoWeekDate("2024-12-30") // { year: 2025, week: 1, weekday: 1 } (a December date in the next week-year)
+ * @example getIsoWeekDate("2020-12-31") // { year: 2020, week: 53, weekday: 4 } (a 53-week ISO year)
+ * @example getIsoWeekDate("2024-06-15T23:59:59") // { year: 2024, week: 24, weekday: 6 }
+ * @example getIsoWeekDate("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
+ * @example getIsoWeekDate("invalid") // null
+ */
+export declare function getIsoWeekDate(value: string): {
+    year: number;
+    week: number;
+    weekday: number;
+} | null;

package/dist/calendar/calculate/getIsoWeekDate.js

@@ -0,0 +1,41 @@
+import { zonelessCalendarDate } from "../../internal/index.js";
+/**
+ * Return the ISO 8601 week date — week-numbering year, week and weekday — for `value`.
+ *
+ * Vessel schedules, production plans and retail reports are published by week number, and a
+ * week number alone is ambiguous: the week-numbering year is not the calendar year at either
+ * end of a year, so all three fields come back together rather than as three calls a caller
+ * could combine inconsistently.
+ *
+ * - `year` is the ISO week-numbering year (`Temporal.PlainDate.yearOfWeek`), which differs
+ *   from the calendar year for late-December and early-January dates.
+ * - `week` is 1–53. ISO week 1 is the week containing the year's first Thursday, so a
+ *   week-numbering year has 53 weeks roughly every five to six years.
+ * - `weekday` is 1 (Monday) through 7 (Sunday).
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. An
+ *   offset, a `Z` or a bracketed zone makes it a moment rather than a calendar date; convert
+ *   it in the zone you mean first (`convertUtcToZoned` then `convertZonedToPlainDateTime`),
+ *   or floor it with `floorToZone`.
+ * - Returns null on invalid input.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @returns { year, week, weekday }, or null on invalid input
+ *
+ * @example getIsoWeekDate("2024-06-15") // { year: 2024, week: 24, weekday: 6 }
+ * @example getIsoWeekDate("2027-01-01") // { year: 2026, week: 53, weekday: 5 } (week-year 2026, not 2027)
+ * @example getIsoWeekDate("2024-12-30") // { year: 2025, week: 1, weekday: 1 } (a December date in the next week-year)
+ * @example getIsoWeekDate("2020-12-31") // { year: 2020, week: 53, weekday: 4 } (a 53-week ISO year)
+ * @example getIsoWeekDate("2024-06-15T23:59:59") // { year: 2024, week: 24, weekday: 6 }
+ * @example getIsoWeekDate("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
+ * @example getIsoWeekDate("invalid") // null
+ */
+export function getIsoWeekDate(value) {
+    const date = zonelessCalendarDate(value);
+    if (!date)
+        return null;
+    const year = date.yearOfWeek;
+    const week = date.weekOfYear;
+    if (year === undefined || week === undefined)
+        return null;
+    return { year, week, weekday: date.dayOfWeek };
+}

package/dist/calendar/calculate/getOrdinalDate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Return the ISO 8601 ordinal date — calendar year and day of year — for `value`.
+ *
+ * - `dayOfYear` is 1–365, or 1–366 in a leap year.
+ * - `year` is the calendar year, unlike `getIsoWeekDate`'s week-numbering year: an ordinal
+ *   date never disagrees with the calendar year it is written beside.
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
+ *   `getIsoWeekDate` for why a moment is not accepted here.
+ * - Returns null on invalid input.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @returns { year, dayOfYear }, or null on invalid input
+ *
+ * @example getOrdinalDate("2024-01-01") // { year: 2024, dayOfYear: 1 }
+ * @example getOrdinalDate("2024-06-15") // { year: 2024, dayOfYear: 167 }
+ * @example getOrdinalDate("2024-12-31") // { year: 2024, dayOfYear: 366 } (leap year)
+ * @example getOrdinalDate("2023-12-31") // { year: 2023, dayOfYear: 365 }
+ * @example getOrdinalDate("2024-03-01") // { year: 2024, dayOfYear: 61 } (after the Feb 29 leap day)
+ * @example getOrdinalDate("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
+ * @example getOrdinalDate("invalid") // null
+ */
+export declare function getOrdinalDate(value: string): {
+    year: number;
+    dayOfYear: number;
+} | null;

package/dist/calendar/calculate/getOrdinalDate.js

@@ -0,0 +1,28 @@
+import { zonelessCalendarDate } from "../../internal/index.js";
+/**
+ * Return the ISO 8601 ordinal date — calendar year and day of year — for `value`.
+ *
+ * - `dayOfYear` is 1–365, or 1–366 in a leap year.
+ * - `year` is the calendar year, unlike `getIsoWeekDate`'s week-numbering year: an ordinal
+ *   date never disagrees with the calendar year it is written beside.
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
+ *   `getIsoWeekDate` for why a moment is not accepted here.
+ * - Returns null on invalid input.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @returns { year, dayOfYear }, or null on invalid input
+ *
+ * @example getOrdinalDate("2024-01-01") // { year: 2024, dayOfYear: 1 }
+ * @example getOrdinalDate("2024-06-15") // { year: 2024, dayOfYear: 167 }
+ * @example getOrdinalDate("2024-12-31") // { year: 2024, dayOfYear: 366 } (leap year)
+ * @example getOrdinalDate("2023-12-31") // { year: 2023, dayOfYear: 365 }
+ * @example getOrdinalDate("2024-03-01") // { year: 2024, dayOfYear: 61 } (after the Feb 29 leap day)
+ * @example getOrdinalDate("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
+ * @example getOrdinalDate("invalid") // null
+ */
+export function getOrdinalDate(value) {
+    const date = zonelessCalendarDate(value);
+    if (!date)
+        return null;
+    return { year: date.year, dayOfYear: date.dayOfYear };
+}

package/dist/calendar/calculate/getQuarter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Return the quarter `value` falls in, as a year and a quarter number.
+ *
+ * - `quarter` is 1–4. With no options these are the calendar quarters: Q1 is January to
+ *   March, and `year` is the calendar year.
+ * - `fiscalYearStartMonth` (1–12, default 1) moves the year's first month. A date before it
+ *   belongs to the previous fiscal year, so `getQuarter("2024-03-31", { fiscalYearStartMonth:
+ *   4 })` is Q4 of 2023.
+ * - **`year` is the calendar year the fiscal year starts in**, matching the NRF retail
+ *   convention `getFiscalPeriod` uses. Organisations that label a fiscal year by the calendar
+ *   year it *ends* in — the US federal government's October-start FY2025 begins in October
+ *   2024 — should add one.
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
+ *   `getIsoWeekDate` for why a moment is not accepted here.
+ * - Returns null on invalid input, including a `fiscalYearStartMonth` that is not an integer
+ *   from 1 to 12.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @param optionsArg optional: fiscalYearStartMonth (1-12, default 1)
+ * @returns { year, quarter }, or null on invalid input
+ *
+ * @example getQuarter("2024-06-15") // { year: 2024, quarter: 2 }
+ * @example getQuarter("2024-10-01") // { year: 2024, quarter: 4 }
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 1 }) // { year: 2024, quarter: 2 } (the default, stated)
+ * @example getQuarter("2024-04-01", { fiscalYearStartMonth: 4 }) // { year: 2024, quarter: 1 }
+ * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }) // { year: 2023, quarter: 4 } (the previous fiscal year)
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 13 }) // null
+ * @example getQuarter("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
+ * @example getQuarter("invalid") // null
+ */
+export declare function getQuarter(value: string, optionsArg?: {
+    fiscalYearStartMonth?: number;
+}): {
+    year: number;
+    quarter: number;
+} | null;