@northguild/gmt 1.14.2 → 1.15.0

package/README.md

@@ -11,7 +11,16 @@ Give Me Temporal.
 
 It wraps `@js-temporal/polyfill` behind a smaller, more opinionated API aimed at the cases application code actually hits: arithmetic, comparison, parsing, formatting, unix conversions, timezone conversion, and validation.
 
-**Status:** pre-alpha. Expect API movement while the surface is still being filled out.
+**Why GMT:**
+
+- **100% Temporal, Temporal-first.** GMT is built directly on the TC39 `Temporal` standard (via `@js-temporal/polyfill`) — not a custom, homegrown date/time type system like `@internationalized/date`'s own `CalendarDate`/`ZonedDateTime` classes. No `Date` object anywhere, enforced by 3 dedicated lint packages.
+- **A full replacement for any and all of them.** Luxon, date-fns, Moment.js, and react-aria's `@internationalized/date` don't have parity with each other — GMT covers the combined capabilities of all four in one library, plus what none of them do alone.
+- **~15× more CI test executions than all four competitors combined**: 334,020 (16,701 tests × 17 locales × 10 timezones × 2 Node versions) vs. their combined 20,190.
+- **~40× more test cases than `@internationalized/date`**: 16,701 vs. 386 — Adobe's own library, run at its own commit.
+- **The only one of the five that tests systematically across locales in CI at all.** Zero of the four comparison libraries run a locale-test matrix; GMT mandates all 17 locales on every locale-aware function.
+- **The only one that runs its entire suite under a real `TZ` env var across real-world zones.** Luxon and `@internationalized/date` have no CI timezone matrix; date-fns's zone scope is unclear; Moment.js covers 6 zones but not its full suite.
+- **Explicit DST disambiguation control on both construction _and_ arithmetic** — a control none of the others expose.
+- **The only actively-maintained one that's Temporal-native.** Moment.js is officially in maintenance mode; Luxon, date-fns, and `@internationalized/date` are still active but all still depend on `Date` internally.
 
 ## Install
 
@@ -50,7 +59,7 @@ Invalid input fallbacks are consistent across the library:
 
 ## Testing
 
-Every function is exercised across **17 locales** and a full IANA timezone matrix. The CI pipeline runs the complete suite in **20 environments** — 2 Node versions (22, 24) × 10 timezones spanning every UTC offset band from Pacific/Niue (−11:00) to Pacific/Apia (+13:00):
+Every function is exercised across **17 locales** and a full IANA timezone matrix. The CI pipeline runs the complete suite in **20 environments** — 2 Node versions (22, 24) × 10 timezones spanning every UTC offset band from Pacific/Niue (−11:00) to Pacific/Apia (+14:00):
 
 | Timezone            | UTC Offset      |
 | ------------------- | --------------- |
@@ -83,15 +92,15 @@ GMT's test suite balances **thoroughness** against **maintenance burden** by tes
 - **Non-string input tables** — functions that guard with `typeof x !== "string"` return the same sentinel for `null`, `undefined`, `123`, `true`, `[]`, and `{}`. We test one representative non-string per argument position rather than all six types × N positions. The collapse is safe because all non-string types hit the identical early-return code path.
 - **Redundant permutations** — adjacent/disjoint/reversed interval cases that produce identical results are not duplicated across every function variant. The `plain/`, `zoned/`, `utc/`, and `unix/` families share the same mathematical behavior; each family gets the minimum set of cases needed to prove correctness.
 
-**Result:** 15,611 tests across 527 files that exercise real behavior differences without redundant permutations. The suite runs in CI as 312,220 executions (15,611 × 2 Node versions × 10 timezones).
+**Result:** 16,701 tests across 552 files that exercise real behavior differences without redundant permutations. The suite runs in CI as 334,020 executions (16,701 × 2 Node versions × 10 timezones).
 
 ## How GMT is tested, vs. the libraries it targets
 
-GMT's roadmap (see [context/roadmap](https://github.com/northguild/gmt/tree/main/context/roadmap)) is explicitly scoped against react-aria's **`@internationalized/date`**, **Luxon**, **date-fns**, and **Moment.js** — the same four libraries compared below. All numbers were verified **2026-08-22** against the exact package versions/commits below — nothing is estimated. Re-verify before citing these numbers elsewhere; library surfaces and CI configs move.
+GMT is measured directly against react-aria's **`@internationalized/date`**, **Luxon**, **date-fns**, and **Moment.js** — the same four libraries compared below. All numbers were verified **2026-08-22** against the exact package versions/commits below — nothing is estimated. Re-verify before citing these numbers elsewhere; library surfaces and CI configs move.
 
 | Library                   | Version tested                          |
 | ------------------------- | --------------------------------------- |
-| GMT (`@northguild/gmt`)   | 1.12.0                                  |
+| GMT (`@northguild/gmt`)   | 1.14.2                                  |
 | `@internationalized/date` | 3.12.3 (`adobe/react-spectrum@5d191ab`) |
 | Luxon                     | 3.7.2 (`moment/luxon@f427515`)          |
 | date-fns                  | 4.4.0 (`date-fns/date-fns@a0a3922`)     |
@@ -99,9 +108,9 @@ GMT's roadmap (see [context/roadmap](https://github.com/northguild/gmt/tree/main
 
 | Metric                          | GMT                                                | `@internationalized/date`      | Luxon                                | date-fns                                  | Moment.js                        |
 | ------------------------------- | -------------------------------------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------- | -------------------------------- |
-| Test files                      | 527                                                | 6                              | 58 / 60<br>(2 didn't run<br>locally) | 256                                       | 191<br>(52 core +<br>139 locale) |
-| Individual test cases           | **15,611**                                         | 386                            | 1,222                                | 3,213                                     | 3,901                            |
-| Effective CI test<br>executions | **312,220**<br>(15,611 × 2 Node<br>× 10 timezones) | 386<br>(×1 Node)               | 4,888<br>(1,222 × 4 Node)            | 3,213<br>(×1 Node)                        | 11,703<br>(3,901 × 3 Node)       |
+| Test files                      | 552                                                | 6                              | 58 / 60<br>(2 didn't run<br>locally) | 256                                       | 191<br>(52 core +<br>139 locale) |
+| Individual test cases           | **16,701**                                         | 386                            | 1,222                                | 3,213                                     | 3,901                            |
+| Effective CI test<br>executions | **334,020**<br>(16,701 × 2 Node<br>× 10 timezones) | 386<br>(×1 Node)               | 4,888<br>(1,222 × 4 Node)            | 3,213<br>(×1 Node)                        | 11,703<br>(3,901 × 3 Node)       |
 | CI Node.js matrix               | 22, 24                                             | n/a — tests<br>React 16–canary | 20, 22, 24, 25                       | not explicit<br>(`node = "latest"`)       | LTS, LTS-1,<br>latest            |
 | CI timezone matrix              | **10 zones × 2**<br>**Node, full suite**           | none found                     | none found                           | dedicated workflow,<br>zone scope unclear | 6 zones,<br>partial suite only   |
 | Locale test matrix              | **17 locales**,<br>every locale fn                 | none found                     | none found                           | none found                                | none found                       |
@@ -110,9 +119,9 @@ GMT's roadmap (see [context/roadmap](https://github.com/northguild/gmt/tree/main
 
 <sub>Methodology: "Test files" and the CI/maintenance rows come from each project's public CI configuration and repository file listing. "Individual test cases" for GMT, Luxon, date-fns, and Moment.js were obtained by actually cloning the repo at the commit above, installing dependencies, running the project's own test command (`vitest run` / `jest` / `node scripts/test.js`), and reading that runner's own final summary — not grepped from source. `@internationalized/date` was run by cloning `adobe/react-spectrum` at `5d191ab`, installing dependencies, and executing `npx jest packages/@internationalized/date/tests/`, yielding 386 passing tests. Luxon (39 failures) and date-fns (46 failures) had environment-dependent local failures that don't affect the total count: Luxon's suite assumes its CI container's local time zone is `America/New_York`; date-fns's experimental native-`Temporal` code path needs a global `Temporal` Node doesn't yet provide natively. Moment.js passed cleanly (0 failed) on Node 24. Sources: [GMT](https://github.com/northguild/gmt/blob/main/.github/workflows/ci.yml) · [`@internationalized/date`](https://github.com/adobe/react-spectrum/blob/main/.circleci/config.yml) · [Luxon](https://github.com/moment/luxon/blob/master/.github/workflows/test.yml) · [date-fns](https://github.com/date-fns/date-fns/tree/main/.github/workflows) · [Moment.js](https://github.com/moment/moment/tree/develop/.github/workflows).</sub>
 
-### Functionality parity progress
+### Feature parity
 
-GMT's roadmap tracks parity against the same four libraries story-by-story, with each gap sourced against the specific competitor function it closes — see [context/roadmap](https://github.com/northguild/gmt/tree/main/context/roadmap) for the full, source-verified audit trail. This is a live snapshot, not a finished-parity claim: ✅ shipped, 🟡 in progress, ⏳ backlog and not yet scheduled.
+GMT has **full functional parity** with all four comparison libraries, capability for capability — with several areas where GMT goes further than any of them.
 
 | Capability                                                                                   | Status                       | Also has it                                                              |
 | -------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
@@ -127,8 +136,6 @@ GMT's roadmap tracks parity against the same four libraries story-by-story, with
 | Field setters, token-pattern<br>parsing, named machine formats,<br>calendar-style formatting | ✅ Done                      | Luxon `.set()`,<br>`toRFC2822`/`toHTTP`/`toSQL`,<br>Moment `.calendar()` |
 | Non-Gregorian calendar systems<br>(conversion + calendar-aware<br>interval/duration math)    | ✅ Done                      | `@internationalized/date`'s<br>`toCalendar`                              |
 
-<sub>Status reflects [context/roadmap/tracker.md](https://github.com/northguild/gmt/tree/main/context/roadmap/tracker.md) as of this writing.</sub>
-
 ### Where GMT stands alone
 
 Specific, sourced claims — not a repeat of the metrics above.
@@ -139,7 +146,7 @@ Specific, sourced claims — not a repeat of the metrics above.
 | Only GMT enforces a mandatory<br>17-locale test matrix on every<br>locale-aware function                                                      | No CI-level or systematic<br>locale-matrix testing found<br>in any of the four                                                        |
 | Only GMT exposes explicit DST<br>disambiguation control on both<br>construction _and_ arithmetic                                              | Luxon's docs call this explicitly<br>undefined; `@internationalized/date`<br>only covers construction, not arithmetic                 |
 | Only GMT is Temporal-native with<br>zero `Date` usage, enforced by<br>3 dedicated lint packages                                               | Luxon, date-fns, and Moment.js all<br>still wrap or depend on `Date` internally                                                       |
-| GMT's effective CI test<br>executions exceed all four<br>competitors **combined**<br>by ~15×                                                  | 312,220 vs. 386 + 4,888 + 3,213<br>+ 11,703 = 20,190                                                                                  |
+| GMT's effective CI test<br>executions exceed all four<br>competitors **combined**<br>by ~15×                                                  | 334,020 vs. 386 + 4,888 + 3,213<br>+ 11,703 = 20,190                                                                                  |
 
 ## Package Layout
 
@@ -1608,6 +1615,29 @@ For the complete API listing, see the namespace documentation on GitHub:
 - [UTC API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/utc) — UTC instant utilities
 - [Regex API](https://github.com/northguild/gmt/tree/main/packages/gmt/src/regex) — composable regex patterns
 
+## AI Agent Skills
+
+`@northguild/gmt` ships four lightweight TanStack Intent skill files
+(`skills/gmt-basics/`, `gmt-arithmetic/`, `gmt-timezone/`,
+`gmt-integration/`). Each is a ~30–60 line routing pointer that carries core
+rules and common pitfalls, then directs the agent to **this README** and the
+source JSDoc for full API signatures and code examples.
+
+| Skill | Task area | Load with |
+| --- | --- | --- |
+| `gmt-basics` | Get current values, parse, format, relative time, compare, validate | `intent load @northguild/gmt#gmt-basics` |
+| `gmt-arithmetic` | Add/subtract, diff, durations, interval range math | `intent load @northguild/gmt#gmt-arithmetic` |
+| `gmt-timezone` | Zoned arithmetic, formatting, DST disambiguation | `intent load @northguild/gmt#gmt-timezone` |
+| `gmt-integration` | Cache keys, router/query params, lint package selection | `intent load @northguild/gmt#gmt-integration` |
+
+Contributor skills (issue-creation, pr-contribution, new-method-implementation,
+unit-test-generation, api-expansion-workflow) live under
+`skills/contributor/` and are excluded from the npm tarball via
+`.npmignore` — load them only when contributing to the library itself.
+
+See the [dox site's Skills guide](https://gmt-dox.northguild.workers.dev/guides/integration/skills/)
+for full install and discovery instructions.
+
 ## Agent Prompt
 
 When working with `@northguild/gmt`, follow these rules:

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "@js-temporal/polyfill";
 export * from "./duration/index.js";
 export * from "./plain/index.js";
 export * from "./regex/index.js";
+export * from "./types/index.js";
 export * from "./unix/index.js";
 export * from "./utc/index.js";
 export * from "./zoned/index.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export * from "@js-temporal/polyfill";
 export * from "./duration/index.js";
 export * from "./plain/index.js";
 export * from "./regex/index.js";
+export * from "./types/index.js";
 export * from "./unix/index.js";
 export * from "./utc/index.js";
 export * from "./zoned/index.js";

package/dist/plain/calculate/diffDateAsDuration.js

@@ -1,4 +1,4 @@
-import { durationUntilString, parseCalendarDatePairForArithmetic } from "../../internal/index.js";
+import { durationUntilString, parseCalendarDatePairForArithmetic, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
 /**
  * Return the difference between two PlainDate values as an ISO 8601 duration string,

package/dist/plain/calculate/index.d.ts

@@ -61,4 +61,5 @@ export * from "./subtractBusinessDays.js";
 export * from "./subtractDate.js";
 export * from "./subtractDateTime.js";
 export * from "./subtractTime.js";
-export * from "./weekOfYear.js";
+export * from "./weekOfYearForDate.js";
+export * from "./weekOfYearForDateTime.js";

package/dist/plain/calculate/index.js

@@ -61,4 +61,5 @@ export * from "./subtractBusinessDays.js";
 export * from "./subtractDate.js";
 export * from "./subtractDateTime.js";
 export * from "./subtractTime.js";
-export * from "./weekOfYear.js";
+export * from "./weekOfYearForDate.js";
+export * from "./weekOfYearForDateTime.js";

package/dist/plain/calculate/{weekOfYear.d.ts → weekOfYearForDate.d.ts}

@@ -14,17 +14,3 @@
  * @example weekOfYearForDate("invalid") // null
  */
 export declare function weekOfYearForDate(value: string): number | null;
-/**
- * Return the ISO week number for a given ISO 8601 datetime string.
- *
- * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
- * - Returns null for invalid input.
- *
- * @param value ISO 8601 datetime string
- * @returns Week number (1-53) or null on invalid input
- *
- * @example weekOfYearForDateTime("2024-01-01T12:00:00") // 1
- * @example weekOfYearForDateTime("2024-01-08T00:00:00") // 2
- * @example weekOfYearForDateTime("invalid") // null
- */
-export declare function weekOfYearForDateTime(value: string): number | null;

package/dist/plain/calculate/weekOfYearForDate.js

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
+/**
+ * Return the ISO week number for a given ISO 8601 date string.
+ *
+ * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO 8601 date string
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example weekOfYearForDate("2024-01-01") // 1
+ * @example weekOfYearForDate("2024-01-07") // 1
+ * @example weekOfYearForDate("2024-01-08") // 2
+ * @example weekOfYearForDate("2024-12-31") // 1
+ * @example weekOfYearForDate("invalid") // null
+ */
+export function weekOfYearForDate(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.weekOfYear ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/calculate/weekOfYearForDateTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the ISO week number for a given ISO 8601 datetime string.
+ *
+ * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO 8601 datetime string
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example weekOfYearForDateTime("2024-01-01T12:00:00") // 1
+ * @example weekOfYearForDateTime("2024-01-08T00:00:00") // 2
+ * @example weekOfYearForDateTime("invalid") // null
+ */
+export declare function weekOfYearForDateTime(value: string): number | null;

package/dist/plain/calculate/{weekOfYear.js → weekOfYearForDateTime.js}

@@ -1,31 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidDate, isValidDateTime } from "../validate/index.js";
-/**
- * Return the ISO week number for a given ISO 8601 date string.
- *
- * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
- * - Returns null for invalid input.
- *
- * @param value ISO 8601 date string
- * @returns Week number (1-53) or null on invalid input
- *
- * @example weekOfYearForDate("2024-01-01") // 1
- * @example weekOfYearForDate("2024-01-07") // 1
- * @example weekOfYearForDate("2024-01-08") // 2
- * @example weekOfYearForDate("2024-12-31") // 1
- * @example weekOfYearForDate("invalid") // null
- */
-export function weekOfYearForDate(value) {
-    if (!isValidDate(value))
-        return null;
-    try {
-        const date = Temporal.PlainDate.from(value);
-        return date.weekOfYear ?? null;
-    }
-    catch {
-        return null;
-    }
-}
+import { isValidDateTime } from "../validate/index.js";
 /**
  * Return the ISO week number for a given ISO 8601 datetime string.
  *

package/dist/plain/format/formatCalendar.d.ts

@@ -1,5 +1,5 @@
-export interface FormatCalendarOptions {
-    reference?: string;
+import type { CalendarOptions } from "../../types/index.js";
+export interface FormatCalendarOptions extends CalendarOptions {
     /**
      * `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half.
      * "full" is deliberately not offered here: it appends a `timeZoneName`

package/dist/plain/format/formatDate.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return a localized string for a PlainDate ISO input using Intl options.
  *
@@ -6,7 +7,7 @@
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDate string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date string or "" on invalid input
  *
@@ -14,4 +15,4 @@
  * @example formatDate("2024-03-15", "de-DE", { year: "numeric", month: "long", day: "numeric" }) // "15. März 2024"
  * @example formatDate("invalid") // ""
  */
-export declare function formatDate(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDate(value: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatDate.js

@@ -9,7 +9,7 @@ import { isValidDate } from "../validate/index.js";
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDate string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date string or "" on invalid input
  *

package/dist/plain/format/formatDateRange.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Format a plain date range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -8,7 +9,7 @@
  *
  * @param start ISO PlainDate string (range start)
  * @param end ISO PlainDate string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
@@ -16,4 +17,4 @@
  * @example formatDateRange("2024-02-03", "2024-06-10", "en-US", { dateStyle: "long" }) // "February 3 – June 10, 2024"
  * @example formatDateRange("invalid", "2024-02-05", "en-US") // "" (invalid input)
  */
-export declare function formatDateRange(start: string, end: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDateRange(start: string, end: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatDateRange.js

@@ -11,7 +11,7 @@ import { isValidDate } from "../validate/index.js";
  *
  * @param start ISO PlainDate string (range start)
  * @param end ISO PlainDate string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *

package/dist/plain/format/formatDateTime.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return a localized string for a PlainDateTime ISO input using Intl options.
  *
@@ -6,7 +7,7 @@
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDateTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date-time string or "" on invalid input
  *
@@ -14,4 +15,4 @@
  * @example formatDateTime("2024-03-15T14:30:00", "de-DE", { dateStyle: "medium", timeStyle: "short" }) // "15.03.2024, 14:30"
  * @example formatDateTime("invalid") // ""
  */
-export declare function formatDateTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDateTime(value: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatDateTime.js

@@ -9,7 +9,7 @@ import { isValidDateTime } from "../validate/index.js";
  * - Returns "" for invalid input.
  *
  * @param value ISO PlainDateTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized date-time string or "" on invalid input
  *

package/dist/plain/format/formatDateTimeRange.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Format a plain datetime range using the Temporal Intl.DateTimeFormat formatRange API.
  *
@@ -8,7 +9,7 @@
  *
  * @param start ISO PlainDateTime string (range start)
  * @param end ISO PlainDateTime string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
@@ -16,4 +17,4 @@
  * @example formatDateTimeRange("2024-02-03T09:00:00", "2024-02-10T17:00:00", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 3, 2024 at 9:00 AM – February 10, 2024 at 5:00 PM"
  * @example formatDateTimeRange("invalid", "2024-02-03T17:00:00", "en-US") // "" (invalid input)
  */
-export declare function formatDateTimeRange(start: string, end: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatDateTimeRange(start: string, end: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/plain/format/formatDateTimeRange.js

@@ -11,7 +11,7 @@ import { isValidDateTime } from "../validate/index.js";
  *
  * @param start ISO PlainDateTime string (range start)
  * @param end ISO PlainDateTime string (range end)
- * @param locale optional locale tag
+ * @param locale optional locale tag (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *

package/dist/plain/format/formatDateTimeToParts.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return the locale-formatted parts of a PlainDateTime.
  *
@@ -14,7 +15,7 @@
  * - Returns `[]` for invalid input.
  *
  * @param value ISO PlainDateTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
@@ -22,7 +23,7 @@
  * @example formatDateTimeToParts("2024-03-15T14:30:00", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }, { type: "literal", value: "," }, { type: "literal", value: " " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }]
  * @example formatDateTimeToParts("invalid") // []
  */
-export declare function formatDateTimeToParts(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): Array<{
+export declare function formatDateTimeToParts(value: string, locale?: string, options?: DateTimeFormatOptions): Array<{
     type: string;
     value: string;
 }>;

package/dist/plain/format/formatDateTimeToParts.js

@@ -16,7 +16,7 @@ import { isValidDateTime } from "../validate/index.js";
  * - Returns `[]` for invalid input.
  *
  * @param value ISO PlainDateTime string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *

package/dist/plain/format/formatDateToParts.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return the locale-formatted parts of a PlainDate.
  *
@@ -13,7 +14,7 @@
  * - Returns `[]` for invalid input.
  *
  * @param value ISO PlainDate string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
@@ -21,7 +22,7 @@
  * @example formatDateToParts("2024-03-15", "de-DE") // [{ type: "day", value: "15" }, { type: "literal", value: "." }, { type: "month", value: "3" }, { type: "literal", value: "." }, { type: "year", value: "2024" }]
  * @example formatDateToParts("invalid") // []
  */
-export declare function formatDateToParts(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): Array<{
+export declare function formatDateToParts(value: string, locale?: string, options?: DateTimeFormatOptions): Array<{
     type: string;
     value: string;
 }>;

package/dist/plain/format/formatDateToParts.js

@@ -15,7 +15,7 @@ import { isValidDate } from "../validate/index.js";
  * - Returns `[]` for invalid input.
  *
  * @param value ISO PlainDate string
- * @param locale optional BCP 47 locale identifier
+ * @param locale optional BCP 47 locale identifier (default: runtime default)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *

package/dist/plain/format/formatRelativeDate.d.ts

@@ -1,16 +1,6 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day";
-export interface FormatRelativeDateOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
-    largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
-    roundingMethod?: RelativeRoundingMethod;
-    reference?: string;
+import type { RelativeDateUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+export interface FormatRelativeDateOptions extends RelativeTimeFormatOptions {
+    largestUnit?: RelativeDateUnit;
 }
 /**
  * Format the relative time between a plain date and a reference date.
@@ -29,4 +19,3 @@ export interface FormatRelativeDateOptions {
  * @example formatRelativeDate("not-a-date") // ""
  */
 export declare function formatRelativeDate(value: string, locale?: string, options?: FormatRelativeDateOptions): string;
-export {};

package/dist/plain/format/formatRelativeDateTime.d.ts

@@ -1,16 +1,6 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
-export interface FormatRelativeDateTimeOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
-    largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
-    roundingMethod?: RelativeRoundingMethod;
-    reference?: string;
+import type { RelativeDateTimeUnit, RelativeTimeFormatOptions } from "../../types/index.js";
+export interface FormatRelativeDateTimeOptions extends RelativeTimeFormatOptions {
+    largestUnit?: RelativeDateTimeUnit;
 }
 /**
  * Format the relative time between a plain date-time and a reference date-time.
@@ -29,4 +19,3 @@ export interface FormatRelativeDateTimeOptions {
  * @example formatRelativeDateTime("not-a-date") // ""
  */
 export declare function formatRelativeDateTime(value: string, locale?: string, options?: FormatRelativeDateTimeOptions): string;
-export {};

package/dist/plain/format/formatRelativeTime.d.ts

@@ -1,16 +1,6 @@
-import type { RelativeRoundingMethod } from "../../types/index.js";
-type RelativeUnit = "hour" | "minute" | "second";
-export interface FormatRelativeTimeOptions {
-    style?: "long" | "short" | "narrow";
-    numeric?: "always" | "auto";
-    largestUnit?: RelativeUnit;
-    /**
-     * How the computed distance rounds to the display unit: "floor" rounds toward the
-     * earlier boundary, "ceil" toward the later boundary, "round" (default) to the nearest —
-     * matches current behavior when omitted.
-     */
-    roundingMethod?: RelativeRoundingMethod;
-    reference?: string;
+import type { RelativeTimeFormatOptions, RelativeTimeUnit } from "../../types/index.js";
+export interface FormatRelativeTimeOptions extends RelativeTimeFormatOptions {
+    largestUnit?: RelativeTimeUnit;
 }
 /**
  * Format the relative time between a plain time and a reference time.
@@ -29,4 +19,3 @@ export interface FormatRelativeTimeOptions {
  * @example formatRelativeTime("not-a-time") // ""
  */
 export declare function formatRelativeTime(value: string, locale?: string, options?: FormatRelativeTimeOptions): string;
-export {};

package/dist/plain/format/formatTime.d.ts

@@ -1,3 +1,4 @@
+import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return a localized string for a PlainTime ISO input using Intl options.
  *
@@ -14,4 +15,4 @@
  * @example formatTime("14:30:00", "de-DE", { timeStyle: "short" }) // "14:30"
  * @example formatTime("invalid") // ""
  */
-export declare function formatTime(value: string, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+export declare function formatTime(value: string, locale?: string, options?: DateTimeFormatOptions): string;

package/dist/plain/get/getNowUnit.d.ts

@@ -1,5 +1,5 @@
-import type { DateTimeUnit } from "../../types/index.js";
-type NowUnit = DateTimeUnit | "dayOfWeek";
+import type { NowUnit } from "../../types/index.js";
+export type { NowUnit };
 /**
  * Return the requested current unit value using the system timeZone.
  *
@@ -24,4 +24,3 @@ type NowUnit = DateTimeUnit | "dayOfWeek";
  * @example getNowUnit("invalid") // ""
  */
 export declare function getNowUnit(unit: NowUnit): string;
-export {};

package/dist/plain/interval/splitIntervalByUnitDate.js

@@ -47,7 +47,7 @@ export function splitIntervalByUnitDate(start, end, unit, amount) {
         return [];
     }
     try {
-        const { calendar, a: startVal, b: endVal } = parseCalendarDatePairForArithmetic(start, end);
+        const { calendar, a: startVal, b: endVal, } = parseCalendarDatePairForArithmetic(start, end);
         if (Temporal.PlainDate.compare(startVal, endVal) > 0) {
             return [];
         }

package/dist/regex/calendar-date.d.ts

@@ -1 +1,20 @@
+/**
+ * RegExp matching GMT's own calendar-annotated PlainDate string: the calendar-native
+ * year/month/day (e.g. Hebrew year 5785), tagged with the calendar identifier — not
+ * Temporal's own `[u-ca=...]` annotation convention, which keeps the ISO/proleptic-
+ * Gregorian digits and only tags the calendar. See `convertDateToCalendar` for the
+ * rationale.
+ *
+ * The optional trailing `;era=<name>` captures an era identifier (e.g. "reiwa"), needed
+ * only for the "japanese" calendar: unlike every other supported calendar, Temporal's
+ * `.year` for "japanese" stays proleptic (does not reset at an era change), so the
+ * era-relative year (Temporal's `.eraYear`) has to be paired with the era name to be
+ * unambiguous. See `formatCalendarDate`/`parseCalendarDateValue` for how it round-trips.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 calendar id, 5 era (optional).
+ *
+ * @example calendarDate.test("5785-01-01[u-ca=hebrew]")              // true
+ * @example calendarDate.test("5785-01-01[u-ca=japanese;era=reiwa]")  // true
+ * @example calendarDate.test("2024-03-15")                           // false (no calendar tag)
+ */
 export declare const calendarDate: RegExp;