@northguild/gmt 1.14.2 → 1.16.0

package/skills/gmt-timezone/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: gmt-timezone
+description: >
+  Timezone-aware operations — get zoned now, format zoned datetimes/ranges,
+  convert between plain↔zoned↔UTC↔Unix, DST disambiguation control on
+  construction and arithmetic, the instant-plus-offset pair, classifying a
+  zoneless wall time before resolving it, real zone unit boundaries
+  (startOfZoned/endOfZoned/startOfUnix/endOfUnix, never after the input), hours
+  in a local day, and flooring or bucketing instants on local calendar
+  boundaries (floorToZone/bucketRange) instead of roundZoned, calendar-annotated
+  zoned strings, and zoned values exact at the range limits (Australia/Sydney at
+  the maximum, Etc/GMT+12 at the minimum). Reads the installed package README.md
+  and source JSDoc for API details; this skill is a routing pointer, not an API
+  dump.
+sources:
+  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/roundZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/getHoursInZonedDay.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/clampZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/instant/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.16.0'
+---
+
+# GMT Timezone
+
+Use this skill when the task requires IANA time zone awareness — formatting,
+converting between time zones, or doing arithmetic that must respect DST.
+
+## When to load
+
+- The user needs the current time in a specific timezone (`"America/New_York"`).
+- The user wants to format a datetime with its zone attached.
+- The user needs to convert a plain datetime to a zoned instant, or between
+  timezones, or between UTC and Unix epochs.
+- The user is adding/subtracting durations across a DST transition.
+- The user has a timestamp that must keep the local offset it happened at, or a
+  local wall time that arrived with no offset at all.
+- The user needs the start or end of a local hour, day, week, month or quarter.
+- The user is grouping or aggregating UTC timestamps by local day, hour, week or
+  month — an observability rollup, a chargeable-days count.
+
+## Core rules
+
+1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[America/New_York]"`
+   is correct; bare `"-05:00"` loses the zone and can't observe DST rules.
+2. **DST disambiguation.** `convertPlainDateTimeToZoned`, `addZoned` and
+   `setZoned` accept `disambiguation` (`"compatible"` | `"earlier"` |
+   `"later"` | `"reject"`) for gap/overlap resolution. On `addZoned`,
+   `subtractZoned` and `intervalFromDurationZoned` it follows TC39
+   AddZonedDateTime: the date part (years to days) moves the wall clock, the
+   time part (hours and smaller) is added in exact time, and `disambiguation`
+   resolves the wall clock the date part lands on, in a spring-forward gap or
+   a fall-back overlap: `"compatible"`/`"later"` move a gap landing forward,
+   `"earlier"` back, `"reject"` returns the sentinel. A time-only duration
+   ignores it, so `+ { minutes: 10 }` is always 10 real minutes.
+3. **Boundaries are always the real zone boundary.** `startOfZoned`,
+   `endOfZoned`, `startOfQuarterForZoned`, `endOfQuarterForZoned`,
+   `getLocaleZonedStartOfWeek`, `getLocaleZonedEndOfWeek` and their `unix/`
+   counterparts (`startOfUnix`,
+   `endOfUnix`, …) return the real start and end of the unit that contains the
+   input: the start is never after the input, and the end is the last
+   nanosecond before the next start, printed at nanosecond precision by default
+   (`"…T23:59:59.999999999…"`); pass `fractionalSecondDigits: 0` for the shorter
+   pre-1.16.0 string. `Pacific/Chatham`'s 03:00 hour on its
+   spring-forward begins at 03:45, and New York's repeated 1 a.m. is its own
+   hour. `areZonedEqualBy`/`areUnixEqualBy` compare these boundary instants, so
+   the two passes of a repeated hour are not equal. A day whose midnight repeats
+   on the same date (America/Havana, 2024-11-03) is one 25-hour day.
+   `getHoursInZonedDay` and `mapZonedHoursInDay` measure the input's calendar
+   date via TC39 `hoursInDay`; that differs from `startOfZoned(…, "day")` only
+   where a fall-back re-enters the previous date (America/Goose_Bay,
+   2010-11-07).
+4. **Boundary functions take no `disambiguation` or `offset`.** They match
+   TC39 `startOfDay()`, which takes no such options. Resolution options belong on
+   functions that set wall-clock fields —
+   `convertPlainDateTimeToZoned`, `resolveLocal`, `addZoned`, `setZoned`.
+5. **Classify a zoneless wall time before resolving it.** `classifyLocal(local,
+   zone)` returns `"unique"` | `"ambiguous"` | `"nonexistent"` so code can branch
+   rather than accept a policy — 01:30 happens twice on a fall-back day and never
+   on a spring-forward one. `resolveLocal(local, zone, { disambiguation })` then
+   returns the instant, exact to the nanosecond, or `""` under `"reject"`. Reach
+   for `convertPlainDateTimeToZoned` instead when you want the zoned string.
+6. **An offset is not a zone.** `-05:00` does not identify `America/New_York`.
+   `toOffsetInstant` splits a timestamp into `{ instant, offset, timeZone? }` —
+   the shape EPCIS 2.0, EDIFACT DTM and DICOM all exchange, because the instant
+   orders events and the offset renders them where they happened, and neither
+   derives from the other. Keep the zone for what is still to be scheduled.
+7. **Bucket in the zone, not in UTC.** `floorToZone(instant, unit, zone)` and
+   `bucketRange(start, end, unit, zone)` floor on the zone's own calendar
+   boundaries. 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. The buckets are deliberately
+   not uniform: a day that springs forward is 23 hours and one that falls back is
+   25, and forcing 24 is what makes a daily aggregate drift.
+   `intervalCountZoned`/`intervalCountUnix`/`intervalCountUtc` count exactly
+   the buckets `bucketRange` returns.
+8. **`roundZoned`/`roundUnix` are not a floor.** They follow TC39
+   `ZonedDateTime.round`, which rounds the wall clock and re-resolves it in the
+   zone, so `roundingMode: "trunc"` can land after the input:
+   `"2024-09-29T03:50:00+13:45[Pacific/Chatham]"` truncated to the hour gives
+   04:00. Never truncate-and-re-resolve (`round` with `"trunc"`, or `.with()`
+   on the wall clock) to find a zoned boundary — use `floorToZone` or
+   `startOfZoned` with no options.
+9. **Hours in a day come from the zone.** `getHoursInZonedDay` is Temporal's
+   `hoursInDay`: 23 on a spring-forward day, 25 on a fall-back day, 23.5 in
+   `Australia/Lord_Howe`, and 23 on a day whose midnight is skipped
+   (`America/Santiago`, 2024-09-08). `mapZonedHoursInDay` stops at the next
+   local day.
+10. **Calendar annotations.** A calendar-annotated zoned string is RFC 9557,
+    `Temporal.ZonedDateTime#toString()`: ISO digits, then `[timeZone]`, then
+    `[u-ca=<id>]` (`"2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"`).
+    A calendar annotation before the zone is rejected. Only `addZoned`, `subtractZoned`,
+    `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar`,
+    `isValidCalendarZonedDateTime` and `zoned/interval/*` (including
+    `isValidCalendarZonedInterval`) accept it; everything else rejects it and
+    returns its invalid-input sentinel — `""` for a string result, `null` for a
+    number, `[]` for a list, and `false` for a validator or predicate such as
+    `isValidZonedDateTime` or `isBeforeZoned`. Always produce these with
+    `convertZonedToCalendar`. Calendar ids are the canonical Temporal ids (see
+    the `gmt-arithmetic` skill), and `[!u-ca=…]` is accepted wherever
+    `[u-ca=…]` is. Differences between values naming different calendars
+    return the sentinel for every unit, hours included.
+11. **Zoned values are exact at the range limits.** In zones ahead of UTC,
+    `isValidZonedDateTime("+275760-09-13T10:00:00+10:00[Australia/Sydney]")`
+    is `true` and one nanosecond later is `false`. Parsing, arithmetic,
+    boundaries, differences and `relativeTo` totals all work there.
+    Daylight-saving rules hold to the end: `America/Santiago`'s
+    `+275760-09-07` is a 23-hour day. At the first instant in a zone behind
+    UTC, an offset-less wall clock (`"-271821-04-19T12:00:00[Etc/GMT+12]"`)
+    resolves. The same string with its `-12:00` offset returns the sentinel,
+    because TC39 checks that local date against the day range.
+12. **Zoned differences count calendar units on the wall clock.** `diffZoned`,
+    `diffZonedAsDuration` and `intervalLengthZoned` follow TC39
+    DifferenceZonedDateTime: days, weeks, months and years are counted on the
+    zone's wall clock (noon to noon across a 23-hour day is `1` day), and hours
+    and smaller are exact time. Two values in different zones have no shared
+    wall clock, so a calendar unit returns `null`/`""`; hours still work.
+    Convert both ends to one zone with `convertZonedToZoned` first, or diff the
+    UTC instants with `diffUtc` if UTC days are what you mean.
+    `intervalOverlappingDaysZoned`/`intervalOverlappingDaysUnix` count the
+    distinct local dates the overlap touches: a deleted day is not counted, and a
+    fall-back into the previous date counts that date.
+13. **Zone names and leap seconds.** Every IANA name is a zone, including
+    single-component links (`Japan`, `Zulu`, `EST5EDT`), in any case.
+    `toOffsetInstant` returns IANA casing (`"america/new_york"` gives
+    `"America/New_York"`). `:60` is invalid in every spelling (`T`, `t`, space,
+    basic format) and every zoned function returns its sentinel for it rather
+    than reading `:59`.
+14. **A zoned value formats in its own zone.** `formatZonedDateTime`,
+    `formatZonedRange` and `formatZonedToParts` return `""`/`[]` for a
+    `timeZone` option. To show an instant in another zone, use
+    `formatUtc(convertZonedToUtc(value), locale, { timeZone })`.
+15. **Read the README.** This skill is a routing pointer. For the full DST
+    disambiguation walkthrough, code examples, and locale ICU notes, read the
+    installed package's `README.md` and the source JSDoc.
+
+## Key functions
+
+- **Current**: `getZonedNow`, `getZonedToday`
+- **Formatting**: `formatZonedDateTime`, `formatZonedRange`,
+  `formatRelativeZoned`, `formatTimeZoneName`
+- **Validation**: `isValidTimeZone`, `isValidZonedDateTime`,
+  `hasDaylightSaving`, `getDstTransitions`, `isInDaylightSaving`
+- **Conversion**: `convertPlainDateTimeToZoned`, `convertZonedToPlainDateTime`,
+  `convertUtcToZoned`, `convertZonedToUtc`, `convertZonedToCalendar`,
+  `convertUtcToUnix`, `convertUnixToUtc`
+- **Arithmetic (with disambiguation)**: `addZoned`, `subtractZoned`, `clampZoned`,
+  `closestZonedTo`, `setZoned`, `cycleZoned`, `roundZoned`
+- **Boundaries (real by default)**: `startOfZoned`, `endOfZoned`,
+  `startOfQuarterForZoned`, `endOfQuarterForZoned`,
+  `getLocaleZonedStartOfWeek`, `getLocaleZonedEndOfWeek`, `startOfUnix`,
+  `endOfUnix`, `mapZonedHoursInDay`, `getHoursInZonedDay`
+- **Offset/DST reads**: `getZonedOffset`, `getZonedOffsetAs`,
+  `getTimeZoneOffset`, `parseTimeZoneFromZoned`
+- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`
+- **Local-time resolution**: `classifyLocal`, `resolveLocal`
+- **Zone-aware buckets**: `floorToZone`, `bucketRange`,
+  `isValidZoneBucketUnit`
+
+## References
+
+- [README — Timezone and Calendar examples](README.md)
+- [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/guides/concepts/dst-disambiguation/)

package/dist/internal/advanceBusinessDays.d.ts

@@ -1,2 +0,0 @@
-import type { Temporal } from "@js-temporal/polyfill";
-export declare function advanceBusinessDays(start: Temporal.PlainDate, direction: 1 | -1, target: number): Temporal.PlainDate;

package/dist/internal/advanceBusinessDays.js

@@ -1,15 +0,0 @@
-function getStep(date, direction) {
-    return direction === 1 ? date.add({ days: 1 }) : date.subtract({ days: 1 });
-}
-export function advanceBusinessDays(start, direction, target) {
-    const advance = (date, remaining) => {
-        if (remaining === 0)
-            return date;
-        const next = getStep(date, direction);
-        if (next.dayOfWeek >= 1 && next.dayOfWeek <= 5) {
-            return advance(next, remaining - 1);
-        }
-        return advance(next, remaining);
-    };
-    return advance(start, target);
-}

package/dist/internal/ethiopicFamilyCalendar.d.ts

@@ -1,47 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-export type EthiopicFamilyCalendar = "ethiopic" | "ethiopic-amete-alem" | "coptic";
-export declare function isEthiopicFamilyCalendar(value: string): value is EthiopicFamilyCalendar;
-export interface EthiopicFamilyFields {
-    year: number;
-    era?: "ethioaa" | "ethiopic";
-    eraYear?: number;
-    month: number;
-    day: number;
-}
-/**
- * Derive an Ethiopic-family calendar's native year/month/day (+ era, for "ethiopic") from a
- * Temporal.PlainDate, via Temporal's ICU-independent "ethioaa" calendar rather than the
- * target's own native calendar id. See the module comment above for why.
- */
-export declare function ethiopicFamilyFieldsFromDate(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): EthiopicFamilyFields;
-/**
- * Construct a Temporal.PlainDate from an Ethiopic-family calendar's native fields, backed
- * by Temporal's "ethioaa" calendar rather than the target's own native calendar id. Throws
- * on an unrecognized era or a missing required field — callers wrap this in try-catch per
- * GMT's sentinel-return contract. See the module comment above for why.
- */
-export declare function dateFromEthiopicFamilyFields(calendar: EthiopicFamilyCalendar, fields: {
-    year?: number;
-    era?: string;
-    eraYear?: number;
-    month: number;
-    day: number;
-}): Temporal.PlainDate;
-/**
- * Split a Temporal.PlainDate into GMT's calendar-annotated string halves for an Ethiopic-family
- * calendar, mirroring `calendarDateParts`' shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- *
- * Returned as `{ date, annotation }` rather than one string so the zoned grammar can splice its
- * time/offset between the two halves — see `calendarDateParts`' doc comment for why.
- */
-export declare function ethiopicFamilyDateParts(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): {
-    date: string;
-    annotation: string;
-};
-/**
- * Format a Temporal.PlainDate as GMT's calendar-annotated string for an Ethiopic-family
- * calendar, mirroring `formatCalendarDate`'s shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- */
-export declare function formatEthiopicFamilyDate(date: Temporal.PlainDate, calendar: EthiopicFamilyCalendar): string;

package/dist/internal/ethiopicFamilyCalendar.js

@@ -1,136 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-export function isEthiopicFamilyCalendar(value) {
-    return (value === "ethiopic" ||
-        value === "ethiopic-amete-alem" ||
-        value === "coptic");
-}
-// @js-temporal/polyfill@0.5.1's "ethiopic" and "coptic" calendar ids resolve year/era by
-// formatting the date through Intl.DateTimeFormat and matching the resulting era part
-// against a hardcoded era-name table (its HelperBase.isoToCalendarDate — used because,
-// unlike "ethioaa", these two calendars aren't a fixed year-offset from ISO, so the
-// polyfill can't compute them with pure arithmetic the way it does for "ethioaa"). CLDR's
-// era abbreviation for both calendars changed at the ICU 78 boundary, not at any particular
-// Node major version: ICU < 78 emits an era string the polyfill's table matches; ICU >= 78
-// emits "am", which isn't in that table. This is a real trap for "which Node am I on" bug
-// hunting — ICU 78 ships in *both* Node 22 and Node 24 (confirmed directly against a Node 20 /
-// ICU 78.2 environment during E5, issue #78, where the bug reproduces despite being on Node
-// 20 — an earlier draft of this comment wrongly pinned the boundary to "Node 24"). The result
-// is that *every* read or write of Temporal's "ethiopic"/"coptic" calendar ids throws a
-// RangeError under ICU >= 78 (verified directly — this isn't a hypothetical). "ethioaa" (Ethiopic Amete Alem)
-// has no era at all — a single continuous count from a fixed epoch — so the polyfill
-// resolves it with pure arithmetic and never touches Intl, making it stable across Node
-// versions. This module uses "ethioaa" as a computation carrier for the whole Ethiopic
-// family: month/day are identical across all three (they share one annual 13-month cycle),
-// so only the displayed year (+ era, for "ethiopic") needs converting, which this module
-// does with GMT-owned arithmetic instead of ever constructing or reading a Temporal
-// PlainDate calendared as "ethiopic" or "coptic".
-//
-// The two constants below are ported from the same source file
-// (@js-temporal/polyfill/lib/calendar.ts)'s EthiopicHelper/CopticHelper definitions, not
-// independently derived: the Amete Mihret ("ethiopic") era begins at ethioaa proleptic year
-// 5501 (EthiopicHelper's `anchorEpoch: { year: 5501 }`), and Coptic's own epoch
-// (0284-08-29) falls 5776 ethioaa years after ethioaa's epoch (-005492-07-17) — both
-// verified against the polyfill's own output across a spread of dates spanning multiple
-// centuries and both 13th-month lengths before being hardcoded here.
-const ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR = 5501;
-const COPTIC_ETHIOAA_YEAR_OFFSET = 5776;
-/**
- * Derive an Ethiopic-family calendar's native year/month/day (+ era, for "ethiopic") from a
- * Temporal.PlainDate, via Temporal's ICU-independent "ethioaa" calendar rather than the
- * target's own native calendar id. See the module comment above for why.
- */
-export function ethiopicFamilyFieldsFromDate(date, calendar) {
-    const { year: ethioaaYear, month, day } = date.withCalendar("ethioaa");
-    if (calendar === "ethiopic-amete-alem") {
-        return { year: ethioaaYear, month, day };
-    }
-    if (calendar === "coptic") {
-        return { year: ethioaaYear - COPTIC_ETHIOAA_YEAR_OFFSET, month, day };
-    }
-    if (ethioaaYear >= ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR) {
-        return {
-            year: ethioaaYear,
-            era: "ethiopic",
-            eraYear: ethioaaYear - (ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR - 1),
-            month,
-            day,
-        };
-    }
-    return {
-        year: ethioaaYear,
-        era: "ethioaa",
-        eraYear: ethioaaYear,
-        month,
-        day,
-    };
-}
-/**
- * Construct a Temporal.PlainDate from an Ethiopic-family calendar's native fields, backed
- * by Temporal's "ethioaa" calendar rather than the target's own native calendar id. Throws
- * on an unrecognized era or a missing required field — callers wrap this in try-catch per
- * GMT's sentinel-return contract. See the module comment above for why.
- */
-export function dateFromEthiopicFamilyFields(calendar, fields) {
-    let ethioaaYear;
-    if (calendar === "ethiopic-amete-alem" || calendar === "coptic") {
-        if (fields.year === undefined) {
-            throw new RangeError(`${calendar} requires a year`);
-        }
-        ethioaaYear =
-            calendar === "coptic"
-                ? fields.year + COPTIC_ETHIOAA_YEAR_OFFSET
-                : fields.year;
-    }
-    else if (fields.era === "ethioaa" || fields.era === "ethiopic") {
-        if (fields.eraYear === undefined) {
-            throw new RangeError("ethiopic requires an eraYear");
-        }
-        ethioaaYear =
-            fields.era === "ethioaa"
-                ? fields.eraYear
-                : fields.eraYear + (ETHIOPIC_ERA_ANCHOR_ETHIOAA_YEAR - 1);
-    }
-    else {
-        throw new RangeError(`Unknown ethiopic era: ${fields.era}`);
-    }
-    return Temporal.PlainDate.from({
-        year: ethioaaYear,
-        month: fields.month,
-        day: fields.day,
-        calendar: "ethioaa",
-    }, { overflow: "reject" });
-}
-/**
- * Split a Temporal.PlainDate into GMT's calendar-annotated string halves for an Ethiopic-family
- * calendar, mirroring `calendarDateParts`' shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- *
- * Returned as `{ date, annotation }` rather than one string so the zoned grammar can splice its
- * time/offset between the two halves — see `calendarDateParts`' doc comment for why.
- */
-export function ethiopicFamilyDateParts(date, calendar) {
-    const fields = ethiopicFamilyFieldsFromDate(date, calendar);
-    const month = String(fields.month).padStart(2, "0");
-    const day = String(fields.day).padStart(2, "0");
-    if (calendar === "ethiopic") {
-        const eraYear = String(fields.eraYear).padStart(4, "0");
-        return {
-            date: `${eraYear}-${month}-${day}`,
-            annotation: `[u-ca=ethiopic;era=${fields.era}]`,
-        };
-    }
-    const year = String(fields.year).padStart(4, "0");
-    return {
-        date: `${year}-${month}-${day}`,
-        annotation: `[u-ca=${calendar}]`,
-    };
-}
-/**
- * Format a Temporal.PlainDate as GMT's calendar-annotated string for an Ethiopic-family
- * calendar, mirroring `formatCalendarDate`'s shape for the rest of the calendar systems but
- * routed entirely through `ethiopicFamilyFieldsFromDate` — see the module comment above.
- */
-export function formatEthiopicFamilyDate(date, calendar) {
-    const { date: datePart, annotation } = ethiopicFamilyDateParts(date, calendar);
-    return `${datePart}${annotation}`;
-}

package/dist/internal/getLocaleMinimalDaysInFirstWeek.d.ts

@@ -1,20 +0,0 @@
-/**
- * Resolve the minimum number of days a week must have in January for that
- * week to count as a locale's week 1, via `Intl.Locale.prototype.weekInfo`.
- *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to `4` (matching ISO 8601's rule — week 1 is the first
- *   week with at least 4 days in January, equivalently the week
- *   containing Jan 4) if `weekInfo` is unavailable on the runtime (older
- *   engines) or unresolvable for the given locale. This mirrors
- *   `getLocaleFirstDayOfWeek`'s fallback-to-ISO-default pattern.
- * - Observed on Node 24 (V8/ICU 78): `weekInfo` omits `minimalDays`
- *   entirely, for every locale, even though Node 20/22 (ICU 77) populate
- *   it — so this fallback engages universally on that runtime rather
- *   than only for locales missing data. `getLocaleWeekYear` and
- *   `getWeeksInLocaleWeekYear` therefore lose locale-specific
- *   minimal-days behavior (silently degrading to the ISO value) on
- *   runtimes where the engine doesn't expose it, which is worth knowing
- *   before treating a Node-version-only test failure as a real bug.
- */
-export declare function getLocaleMinimalDaysInFirstWeek(locale: string): number | null;

package/dist/internal/getLocaleMinimalDaysInFirstWeek.js

@@ -1,31 +0,0 @@
-/**
- * Resolve the minimum number of days a week must have in January for that
- * week to count as a locale's week 1, via `Intl.Locale.prototype.weekInfo`.
- *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
- * - Falls back to `4` (matching ISO 8601's rule — week 1 is the first
- *   week with at least 4 days in January, equivalently the week
- *   containing Jan 4) if `weekInfo` is unavailable on the runtime (older
- *   engines) or unresolvable for the given locale. This mirrors
- *   `getLocaleFirstDayOfWeek`'s fallback-to-ISO-default pattern.
- * - Observed on Node 24 (V8/ICU 78): `weekInfo` omits `minimalDays`
- *   entirely, for every locale, even though Node 20/22 (ICU 77) populate
- *   it — so this fallback engages universally on that runtime rather
- *   than only for locales missing data. `getLocaleWeekYear` and
- *   `getWeeksInLocaleWeekYear` therefore lose locale-specific
- *   minimal-days behavior (silently degrading to the ISO value) on
- *   runtimes where the engine doesn't expose it, which is worth knowing
- *   before treating a Node-version-only test failure as a real bug.
- */
-export function getLocaleMinimalDaysInFirstWeek(locale) {
-    try {
-        const weekInfo = new Intl.Locale(locale).weekInfo;
-        if (!weekInfo || typeof weekInfo.minimalDays !== "number") {
-            return 4;
-        }
-        return weekInfo.minimalDays;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/internal/resolveUnixTimeZone.d.ts

@@ -1,20 +0,0 @@
-/**
- * Resolve an optional Unix diff timeZone to its default (system timeZone) when unset.
- *
- * @param timeZone optional IANA timeZone
- * @returns the resolved timeZone, or "" if invalid
- * @example resolveUnixTimeZone(undefined) // system timeZone, e.g. "America/New_York"
- * @example resolveUnixTimeZone("Europe/Helsinki") // "Europe/Helsinki"
- * @example resolveUnixTimeZone("not-a-timezone") // ""
- */
-export declare function resolveUnixTimeZone(timeZone?: string): string;
-/**
- * Validate that both Unix epoch values are finite integers.
- *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
- * @returns true if both values are finite integers
- * @example isValidUnixEpochPair(1704067200000, 1704153600000) // true
- * @example isValidUnixEpochPair(NaN, 1704153600000) // false
- */
-export declare function isValidUnixEpochPair(value1: number, value2: number): boolean;

package/dist/internal/resolveUnixTimeZone.js

@@ -1,30 +0,0 @@
-import { getSystemTimeZone } from "../zoned/get/index.js";
-import { isValidTimeZone } from "../zoned/validate/index.js";
-/**
- * Resolve an optional Unix diff timeZone to its default (system timeZone) when unset.
- *
- * @param timeZone optional IANA timeZone
- * @returns the resolved timeZone, or "" if invalid
- * @example resolveUnixTimeZone(undefined) // system timeZone, e.g. "America/New_York"
- * @example resolveUnixTimeZone("Europe/Helsinki") // "Europe/Helsinki"
- * @example resolveUnixTimeZone("not-a-timezone") // ""
- */
-export function resolveUnixTimeZone(timeZone) {
-    const resolved = timeZone ?? getSystemTimeZone();
-    return resolved && isValidTimeZone(resolved) ? resolved : "";
-}
-/**
- * Validate that both Unix epoch values are finite integers.
- *
- * @param value1 first Unix timestamp
- * @param value2 second Unix timestamp
- * @returns true if both values are finite integers
- * @example isValidUnixEpochPair(1704067200000, 1704153600000) // true
- * @example isValidUnixEpochPair(NaN, 1704153600000) // false
- */
-export function isValidUnixEpochPair(value1, value2) {
-    return (Number.isFinite(value1) &&
-        Number.isInteger(value1) &&
-        Number.isFinite(value2) &&
-        Number.isInteger(value2));
-}

package/dist/unix/calculate/startOrEndOfUnix.d.ts

@@ -1,9 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { Disambiguation, Offset } from "../../types/index.js";
-export declare function startOrEndOfUnix(value: number, unit: Temporal.DateUnit | Temporal.TimeUnit, options: {
-    epochUnit?: "seconds" | "milliseconds";
-    timeZone?: string;
-    weekStartsOn?: "monday" | "sunday";
-    disambiguation?: Disambiguation;
-    offset?: Offset;
-}, isEnd: boolean): number | null;

package/dist/unix/calculate/startOrEndOfUnix.js

@@ -1,122 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidDateTimeUnit } from "../../plain/index.js";
-import { isValidUnixUnit } from "../../unix/validate/isValidUnixUnit.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
-export function startOrEndOfUnix(value, unit, options, isEnd) {
-    const epochUnit = options.epochUnit ?? "milliseconds";
-    const timeZone = options.timeZone ?? getSystemTimeZone();
-    const weekStartsOn = options.weekStartsOn ?? "monday";
-    const disambiguation = options.disambiguation ?? "compatible";
-    const offset = options.offset ?? "ignore";
-    if (!timeZone ||
-        !isValidDateTimeUnit(unit) ||
-        !isValidTimeZone(timeZone) ||
-        !isValidUnixUnit(epochUnit)) {
-        return null;
-    }
-    if (!Number.isFinite(value) || !Number.isInteger(value)) {
-        return null;
-    }
-    try {
-        const epochMs = epochUnit === "seconds" ? value * 1000 : value;
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochMs);
-        const source = instant.toZonedDateTimeISO(timeZone);
-        const timeFields = isEnd
-            ? {
-                hour: 23,
-                minute: 59,
-                second: 59,
-                millisecond: 999,
-                microsecond: 999,
-                nanosecond: 999,
-            }
-            : {
-                hour: 0,
-                minute: 0,
-                second: 0,
-                millisecond: 0,
-                microsecond: 0,
-                nanosecond: 0,
-            };
-        let result;
-        switch (unit) {
-            case "year":
-                result = isEnd
-                    ? source.with({ month: 12, day: 31, ...timeFields }, { disambiguation, offset })
-                    : source.with({ month: 1, day: 1, ...timeFields }, { disambiguation, offset });
-                break;
-            case "month": {
-                const lastDay = Temporal.PlainDate.from({
-                    year: source.year,
-                    month: source.month,
-                    day: 1,
-                }).daysInMonth;
-                result = isEnd
-                    ? source.with({ day: lastDay, ...timeFields }, { disambiguation, offset })
-                    : source.with({ day: 1, ...timeFields }, { disambiguation, offset });
-                break;
-            }
-            case "week": {
-                const daysToSubtract = weekStartsOn === "monday"
-                    ? source.dayOfWeek - 1
-                    : source.dayOfWeek % 7;
-                const weekAnchor = source.subtract({ days: daysToSubtract });
-                result = isEnd
-                    ? weekAnchor
-                        .add({ days: 6 })
-                        .with({ ...timeFields }, { disambiguation, offset })
-                    : weekAnchor.with({ ...timeFields }, { disambiguation, offset });
-                break;
-            }
-            case "day":
-                result = source.with({ ...timeFields }, { disambiguation, offset });
-                break;
-            case "hour":
-                result = source.with({
-                    minute: timeFields.minute,
-                    second: timeFields.second,
-                    millisecond: timeFields.millisecond,
-                    microsecond: timeFields.microsecond,
-                    nanosecond: timeFields.nanosecond,
-                }, { disambiguation, offset });
-                break;
-            case "minute":
-                result = source.with({
-                    second: timeFields.second,
-                    millisecond: timeFields.millisecond,
-                    microsecond: timeFields.microsecond,
-                    nanosecond: timeFields.nanosecond,
-                }, { disambiguation, offset });
-                break;
-            case "second":
-                result = source.with({
-                    millisecond: timeFields.millisecond,
-                    microsecond: timeFields.microsecond,
-                    nanosecond: timeFields.nanosecond,
-                }, { disambiguation, offset });
-                break;
-            case "millisecond":
-                result = source.with({
-                    microsecond: timeFields.microsecond,
-                    nanosecond: timeFields.nanosecond,
-                }, { disambiguation, offset });
-                break;
-            case "microsecond":
-                result = source.with({ nanosecond: timeFields.nanosecond }, { disambiguation, offset });
-                break;
-            case "nanosecond":
-                result = source;
-                break;
-            default:
-                return null;
-        }
-        const epoch = epochUnit === "seconds"
-            ? Math.floor(result.epochMilliseconds / 1000)
-            : result.epochMilliseconds;
-        return epoch;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/unix/interval/resolveUnixIntervalPair.d.ts

@@ -1,7 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-export interface ResolvedUnixInterval {
-    startVal: Temporal.ZonedDateTime;
-    endVal: Temporal.ZonedDateTime;
-    resolvedUnit: Temporal.DateTimeUnit;
-}
-export declare function resolveUnixIntervalPair(start: number | string, end: number | string, unit: string): ResolvedUnixInterval | null;