@ultimat3/time 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -12,6 +12,7 @@
 | `zone-canonical.ts` | one zone, one key: `canonicalTimeZone` — the casing/alias collapse every cache keys on |
 | `zoned.ts` | `toZoned` / `fromZoned` + gap and overlap policies. Everything depends on this. |
 | `format.ts` | `Intl` rendering. Every function takes `locale` **and** `zone`. |
+| `locale.ts` | `assertLocale` — the ONE screen a caller-supplied BCP 47 tag passes before `Intl` |
 | `duration.ts` | `'2h30m'` ⇄ ms |
 | `cron.ts` | barrel over the three cron modules — the only one `index.ts` re-exports |
 | `cron-parse.ts` | field grammar → `CronExpression`. Non-integer, non-name tokens are rejected. |
@@ -43,8 +44,20 @@
   (`Japan` → `Asia/Tokyo`, `GB` → `Europe/London`) and that is the point: the slashed spelling is
   the one that survives being a formatter-cache key. **Breaking at 6.0.0.** `zones.test.ts` pins
   one named case per refused name, so an ICU bump that reopens one names it.
+- **A malformed locale tag is `X_LOCALE_INVALID` at EVERY entry point, `As of 2026-08-23`** —
+  `formatDateTime`, `formatDate`, `formatTime`, `formatWithOffset`, `formatRange`, `formatRelative`,
+  `formatDuration` and `zoneAbbrev`, not `describeCron` alone. Each of the other eight passed the
+  caller's raw string to an `Intl` constructor, so `formatRelative(at, { locale: 'en_US', … })` died
+  as a bare, uncoded `RangeError` several frames from the `Accept-Language` header it came out of —
+  a code that has shipped since 1.0, with a runnable `fix:`, thrown by exactly one of nine callers.
+  `format.ts` argued the pass-through decided "a cache key, never whether a locale is acceptable",
+  which is true of the cache and was not an argument for letting the tag through. **Breaking at
+  9.x.** `assertLocale` (`locale.ts`) is the one screen and it VALIDATES AND CANONICALIZES in one
+  step — `Intl.getCanonicalLocales` runs the same structural check `supportedLocalesOf` throws on
+  and hands back the spelling the cache keys on, so there is no second question to ask. Well-formed
+  but unknown to ICU (`zz`) is **not** refused: `Intl` falls back, and so must a rendered page.
 - **Never cache an `Intl` formatter on a raw caller string.** A zone and a locale both arrive from
-  a request header, so the key must be canonical (`canonicalTimeZone` for a zone, `canonicalLocale`
+  a request header, so the key must be canonical (`canonicalTimeZone` for a zone, `assertLocale`
   for a locale) and the cache must be bounded (`cachedFormatter`). **`cachedFormatter`,
   `MAX_CACHED_FORMATTERS` and `canonicalLocale` are `@ultimat3/core`'s as of 2.0.0**, not this
   package's: `@ultimat3/money` hit the identical unbounded-`Map`-on-a-header bug and tier 1 may not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/time",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "UTC instants, DST-correct zone math, cron, durations and Intl formatting with an explicit timezone",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0"
+    "@ultimat3/core": "10.0.0"
   }
 }

package/src/cron-describe.ts

@@ -4,9 +4,10 @@
  * ship English to every locale that forgot the argument — so injection is mandatory, not opt-in.
  */
 
-import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+import { cachedFormatter } from '@ultimat3/core';
 import { type CronExpression, parseCronOnce } from './cron-parse';
-import { cronNotDescribable, localeInvalid } from './errors';
+import { cronNotDescribable } from './errors';
+import { assertLocale } from './locale';
 
 export interface CronPhrases {
   everyMinute: string;
@@ -99,16 +100,6 @@ function clockTimes(
   return `${shown} ${fill(phrases.andMore, { n: times.length - MAX_LISTED_TIMES })}`;
 }
 
-/**
- * `Intl` throws a bare `RangeError` on a malformed tag; convert it once, at the entry point — and
- * hand back the canonical spelling, so validating and keying are the same single step.
- */
-function assertLocale(locale: string): string {
-  const tag = canonicalLocale(locale);
-  if (tag === undefined) throw localeInvalid(locale);
-  return tag;
-}
-
 /** Step fields: an evenly spaced set starting at 0 that covers the whole range. */
 function uniformStep(values: readonly number[], size: number): number | undefined {
   const first = values[0];
@@ -130,7 +121,7 @@ function fill(template: string, vars: Readonly<Record<string, string | number>>)
 
 /**
  * Canonically keyed **and** hard-capped, because `locale` can arrive from an Accept-Language
- * header. `canonicalLocale` collapses the spellings of one locale — `EN-us`, `en-latn-us` — but it
+ * header. `assertLocale` collapses the spellings of one locale — `EN-us`, `en-latn-us` — but it
  * still returns a distinct string for every unknown `-u-` extension value, so the key alone does
  * not bound anything and only the cap keeps the key space finite. Neither half is redundant. The
  * cap and its FIFO live in `@ultimat3/core`'s `intl-cache.ts`, because `zones.ts`, `format.ts` and

package/src/duration.ts

@@ -4,6 +4,7 @@
  */
 
 import { durationInvalid, scheduleInvalid } from './errors';
+import { assertLocale } from './locale';
 
 export const MS = 1;
 export const SECOND = 1000;
@@ -112,6 +113,9 @@ export function formatDuration(
   if (!Number.isInteger(maxUnits) || maxUnits < 1) {
     throw scheduleInvalid('maxUnits', maxUnits, 'at least 1');
   }
+  // Screened once, here, rather than at each of the three `Intl` constructions below — and before
+  // any of them, so a malformed tag is one refusal and never a partially built string.
+  const tag = assertLocale(locale);
   let remaining = Math.abs(Math.round(ms));
   const pieces: string[] = [];
 
@@ -121,19 +125,19 @@ export function formatDuration(
     if (count === 0) continue;
     remaining -= count * scale;
     pieces.push(
-      new Intl.NumberFormat(locale, { style: 'unit', unit, unitDisplay: style }).format(count),
+      new Intl.NumberFormat(tag, { style: 'unit', unit, unitDisplay: style }).format(count),
     );
   }
 
   if (pieces.length === 0) {
-    return new Intl.NumberFormat(locale, {
+    return new Intl.NumberFormat(tag, {
       style: 'unit',
       unit: 'second',
       unitDisplay: style,
     }).format(0);
   }
 
-  const joined = new Intl.ListFormat(locale, { style: 'narrow', type: 'unit' }).format(pieces);
+  const joined = new Intl.ListFormat(tag, { style: 'narrow', type: 'unit' }).format(pieces);
   return ms < 0 ? `-${joined}` : joined;
 }
 

package/src/errors.ts

@@ -44,7 +44,6 @@ export class TimeError extends UltimateError {
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
     });
   }
 }

package/src/format.ts

@@ -4,8 +4,9 @@
  * because "the server's timezone" is never the answer to "what time is it for the user".
  */
 
-import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+import { cachedFormatter } from '@ultimat3/core';
 import { differenceMs, type Instant } from './instant';
+import { assertLocale } from './locale';
 import { isoDateInZone } from './zoned';
 import { assertTimeZone, type TimeZone } from './zones';
 
@@ -120,7 +121,7 @@ const RELATIVE_UNITS: readonly [Intl.RelativeTimeFormatUnit, number][] = [
 /** `in 3 days` / `2 hours ago`, picking the largest unit that fits. */
 export function formatRelative(at: Instant, options: FormatRelativeOptions): string {
   const delta = differenceMs(options.now, at);
-  const formatter = new Intl.RelativeTimeFormat(options.locale, {
+  const formatter = new Intl.RelativeTimeFormat(assertLocale(options.locale), {
     numeric: options.numeric ?? 'auto',
     style: options.style ?? 'long',
   });
@@ -176,16 +177,18 @@ export function ordinal(value: number): string {
 const cache = new Map<string, Intl.DateTimeFormat>();
 
 /**
- * Bounded, and keyed on a zone `assertTimeZone` and a locale `canonicalLocale` have both already
+ * Bounded, and keyed on a zone `assertTimeZone` and a locale `assertLocale` have both already
  * canonicalized — `Accept-Language` sends `EN-us` and `en-US` for one locale, and each spelling
  * used to mint its own permanent entry. The bound stays: an unknown `-u-` extension value survives
  * canonicalization as a distinct string, so only the cap keeps this key space finite.
  *
- * A tag `Intl` cannot parse falls through unchanged, so the `Intl.DateTimeFormat` constructor
- * still raises it — this seam decides a cache key, never whether a locale is acceptable.
+ * A tag `Intl` cannot parse is refused here as `X_LOCALE_INVALID`, the same code `describeCron`
+ * has always raised. It used to fall through unchanged so the `Intl.DateTimeFormat` constructor
+ * raised a bare `RangeError` instead — one package answering "is this locale acceptable" two ways,
+ * and the answer a caller could act on was the one seven of the eight entry points did not give.
  */
 function formatterFor(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
-  const tag = canonicalLocale(locale) ?? locale;
+  const tag = assertLocale(locale);
   const key = `${tag}|${JSON.stringify(options)}`;
   return cachedFormatter(cache, key, () => new Intl.DateTimeFormat(tag, options));
 }

package/src/locale.ts

@@ -0,0 +1,24 @@
+// Single responsibility: the one place a caller-supplied BCP 47 tag is screened before it reaches
+// an `Intl` constructor. One question, one answer (axiom 1) — `cron-describe.ts` refused a
+// malformed tag from the start while seven sibling formatters handed the raw string to `Intl` and
+// let a bare, uncoded `RangeError` escape several frames from the header it came out of.
+
+import { canonicalLocale } from '@ultimat3/core';
+import { localeInvalid } from './errors';
+
+/**
+ * The canonical spelling of a well-formed tag, or `X_LOCALE_INVALID`.
+ *
+ * Validating and keying are one step: `Intl.getCanonicalLocales` runs exactly the structural check
+ * `Intl.DateTimeFormat.supportedLocalesOf` throws on — which is what `localeInvalid`'s `fix:` tells
+ * the caller to run — and unlike it hands back the spelling every formatter cache keys on, so
+ * `EN-us` and `en-US` cannot mint two entries for one locale.
+ *
+ * Well-formed but unknown to this runtime's ICU (`zz`) is NOT refused: `Intl` falls back for those,
+ * and a user carrying a locale the runtime has no data for must still get a rendered page.
+ */
+export function assertLocale(locale: string): string {
+  const tag = canonicalLocale(locale);
+  if (tag === undefined) throw localeInvalid(locale);
+  return tag;
+}

package/src/zones.ts

@@ -4,9 +4,10 @@
  * is no offset table to keep in sync and no `date-fns-tz` dependency.
  */
 
-import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+import { cachedFormatter } from '@ultimat3/core';
 import { timezoneInvalid } from './errors';
 import type { Instant } from './instant';
+import { assertLocale } from './locale';
 import { canonicalTimeZone } from './zone-canonical';
 
 /** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */
@@ -118,9 +119,10 @@ export function zoneAbbrev(
   style: 'short' | 'long' | 'shortOffset' | 'longOffset' = 'short',
 ): string {
   const canonical = assertTimeZone(zone);
-  // A tag `Intl` cannot parse falls through unchanged, exactly as in `format.ts`: this decides a
-  // cache key, never whether a locale is acceptable.
-  const tag = canonicalLocale(locale) ?? locale;
+  // Both arguments arrive from a request header on the path this function exists for, so a tag
+  // `Intl` cannot parse is refused with a code exactly as an unknown zone is — `X_LOCALE_INVALID`,
+  // the same one `describeCron` and every formatter in `format.ts` raise.
+  const tag = assertLocale(locale);
   // The one `Intl` construction in this package that escaped the shared cache: it built a formatter
   // per call on the caller's raw zone and locale, so an `x-timezone` an app renders a label from
   // paid for a fresh `Intl.DateTimeFormat` every time and an unknown one escaped as a `RangeError`.