@jarenjs/locales 0.46.4 → 0.49.2

package/README.md

@@ -3,7 +3,8 @@
 Locale packs (message catalogs) for the error messages of
 [`@jarenjs/validate`](../validate/README.md),
 [`@jarenjs/forms`](../forms/README.md) and
-[`@jarenjs/contract`](../contract/README.md).
+[`@jarenjs/contract`](../contract/README.md), and the calendar language
+`@jarenjs/core/dates` refuses to invent.
 
 Jaren validators and form checks never bake prose into the hot path: every
 failure carries a stable message key (`msgid`) plus raw structured
@@ -48,6 +49,96 @@ way - the package is `sideEffects: false`):
 import { nl } from '@jarenjs/locales/nl';
 ```
 
+## Calendar language
+
+`@jarenjs/core/dates` is locale-free by design: its `MMMM`, `EEE` and `a`
+pattern tokens raise rather than fall back to English. Every pack carries
+the data those tokens need, on the same flat msgid machinery as the error
+messages, and `compileDateLocale` turns a pack into the frozen record a
+formatter and a UI read:
+
+```js
+import { compileDateFormat, parseRFC3339Parts } from '@jarenjs/core/dates';
+import { compileDateLocale, nl } from '@jarenjs/locales';
+
+const dates = compileDateLocale(nl);
+const long = compileDateFormat('EEEE d MMMM yyyy', dates.names);
+long(parseRFC3339Parts('2026-07-05'));           // 'zondag 5 juli 2026'
+dates.relative(-3, 'day');                        // '3 dagen geleden'
+dates.relative(-1, 'day', { numeric: 'auto' });   // 'gisteren'
+dates.formatName('date-time');                    // 'datum en tijd'
+```
+
+The compiled record has three members: `names` (the five arrays
+`compileDateFormat` takes), `relative(amount, unit, options?)` and
+`formatName(format)`. `relative` takes an **explicit signed amount** -
+negative is past, positive is future - and reads no clock; deciding how
+long ago something was is the caller's job, and phrasing it is this
+package's. `numeric: 'auto'` reaches for `yesterday`/`today`/`tomorrow`
+and `now` only where they are exact (a whole day away, a zero-second
+offset); a fractional amount, an unsupported unit and an unknown mode are
+each refused. Compilation reads the catalog once, so a formatter built
+from `names` costs no message lookup per date.
+
+The msgids are closed and mechanical, so a pack cannot half-cover them:
+
+| Family | Keys |
+|---|---|
+| months | `date/month/01`…`12` × `/wide`, `/short` |
+| weekdays | `date/weekday/0`…`6` × `/wide`, `/short` (Sunday = 0) |
+| day period | `date/meridiem/am`, `date/meridiem/pm` |
+| relative | `date/relative/{second,minute,hour,day,week,month,year}/{past,future}` |
+| named days | `date/relative/{now,yesterday,today,tomorrow}` |
+| format names | `format/name/{date,time,date-time,iso-date,iso-time,iso-date-time}` |
+
+`dateMessagesEn` is the English set and the canonical key list. Name
+entries take no parameters; a relative entry receives the **absolute**
+amount as `{ value }` and owns its language's plural and case grammar -
+the direction is already in the key. A pack authors the forty name keys
+through `dateNameEntries({ months, monthsShort, weekdays, weekdaysShort,
+meridiem })`, which checks the lengths as it expands them.
+
+Two consequences worth knowing before writing a pack. The month array
+feeds a *pattern*, so a language that inflects months by position ships
+the **format** forms rather than the standalone ones (Russian's
+`5 июля 2026`, not `июль`). And a language whose abbreviations equal its
+full names ships them equal (Arabic, Japanese, Chinese) rather than
+inventing shorter ones.
+
+### Format display names, and why they exist
+
+A format's name is its wire name - `date-time`, `iso-time` - which is
+English by construction. Interpolated into a translated sentence it reads
+as gibberish: a Dutch user used to be told *"Moet een geldige date-time
+zijn"*. `@jarenjs/forms` now resolves `format/name/<format>` through the
+catalog it is rendering with, so the same failure reads *"Moet een
+geldige datum en tijd zijn"* while the error's own
+`params.format` stays `'date-time'` - structural, so re-rendering it in a
+second language answers in that language rather than repeating the first
+one's noun. A format the catalog cannot name keeps its own, which is the
+readable answer for names that are already words (`email`, `hostname`)
+and the only possible one for a format this repository has never heard of.
+
+### The optional `Intl` provider
+
+`createIntlDateLocale(locale, options?)` builds the same shape out of the
+platform's ICU data, for a host that wants a hundred locales more than it
+wants byte stability:
+
+```js
+import { createIntlDateLocale } from '@jarenjs/locales/intl-dates';
+
+const dates = createIntlDateLocale('hu-HU');   // same three members
+```
+
+It is a separate module and an explicit call because it cannot be the
+default. ICU output moves between Node versions and between a browser and
+a server, and this repository's own site is server-rendered under
+byte-comparison tests. Nothing on the default path constructs an `Intl`
+object, and a bundler drops the provider from a bundle that never calls
+it. ICU has no date-format display names, so that member carries the
+repository's English ones unless `options.formatNames` overrides them.
+
 ## Authoring a pack
 
 A catalog is a plain flat object; each entry is either a **template
@@ -68,9 +159,11 @@ Rules of the road:
 
 1. **Key parity.** Cover every key of validate's `messagesEn`, every
    `form/*` key of forms' `formsMessagesEn`, every `contract/*` wire-error
-   key of contract's `contractMessagesEn`, plus `x-form/assert` and the
-   `JQ2xxx` query runtime codes. The repo enforces this with tests
-   (`test/locales/`); missing keys silently fall back to English.
+   key of contract's `contractMessagesEn`, every `date/*` and
+   `format/name/*` key of this package's own `dateMessagesEn`, plus
+   `x-form/assert` and the `JQ2xxx` query runtime codes. The repo enforces
+   this with tests (`test/locales/`); missing keys silently fall back to
+   English.
 2. **Never depend on a consumer.** A pack must stay importable without
    dragging in `@jarenjs/validate` or `@jarenjs/forms`, so that either one
    can serve any pack. The platform and `@jarenjs/core` are the only things

package/dist/types/dates.d.ts

@@ -0,0 +1,68 @@
+import { RELATIVE_UNITS } from './helpers.js';
+export { RELATIVE_UNITS };
+/**
+ * The English date catalog: the canonical key set every pack covers,
+ * and the entries `compileDateLocale` falls back to for a partial
+ * caller-supplied catalog.
+ * @type {Record<string, string | ((params: any, error?: object) => string)>}
+ */
+export declare const dateMessagesEn: Record<string, string | ((params: any, error?: object) => string)>;
+export type DateLocaleNames = {
+    /**
+     * - 12 wide month names, January first
+     */
+    months: string[];
+    /**
+     * - 12 abbreviated month names
+     */
+    monthsShort: string[];
+    /**
+     * - 7 wide weekday names, Sunday first
+     */
+    weekdays: string[];
+    /**
+     * - 7 abbreviated weekday names
+     */
+    weekdaysShort: string[];
+    /**
+     * - the AM and PM markers
+     */
+    meridiem: [string, string];
+};
+export type DateLocale = {
+    /**
+     * - the arrays `compileDateFormat` reads
+     */
+    names: DateLocaleNames;
+    /**
+     * - a signed relative-time phrase
+     */
+    relative: (amount: number, unit: string, options?: {
+        numeric?: string;
+    }) => string;
+    /**
+     * - a date-format display name, or undefined when the catalog has none
+     */
+    formatName: (format: string) => string | undefined;
+};
+/**
+ * Compile a catalog into the calendar language a formatter and a UI
+ * need. Names are read once and frozen, so a formatter compiled against
+ * them and a label rendered from them cost no lookup per date.
+ *
+ * The argument is a catalog-like - a locale pack, an already-compiled
+ * catalog, or a partial object of overrides; every key it leaves out
+ * falls back to English. The eleven shipped packs cover the whole key
+ * set, so that fallback exists for a caller's own catalog, not for them.
+ *
+ * @param {Record<string, any>} [catalogLike] - A catalog to read, or undefined for English
+ * @returns {Readonly<DateLocale>} The frozen calendar language
+ * @throws {TypeError} when an entry does not render a non-empty string
+ * @example
+ * import { compileDateFormat } from '@jarenjs/core/dates';
+ * const dates = compileDateLocale(nl);
+ * const long = compileDateFormat('EEEE d MMMM yyyy', dates.names);
+ * dates.relative(-3, 'day');                    // '3 dagen geleden'
+ * dates.relative(-1, 'day', { numeric: 'auto' }); // 'gisteren'
+ */
+export declare function compileDateLocale(catalogLike?: Record<string, any>): Readonly<DateLocale>;

package/dist/types/helpers.d.ts

@@ -6,8 +6,11 @@
  * Each factory takes a pack's own `Intl` singleton or translated table
  * and returns the render closure the catalog entries call. Building the
  * closure once at module load keeps the packs' allocation discipline:
- * nothing is constructed per message. This module is internal to
- * `@jarenjs/locales` - packs import it, consumers never see it.
+ * nothing is constructed per message. The calendar half is here for the
+ * same reason: the date msgids are mechanical, and expanding them from
+ * arrays is what keeps forty keys per pack from being forty chances to
+ * mistype one. This module is internal to `@jarenjs/locales` - packs and
+ * the date adapters import it, consumers never see it.
  */
 export { formatMessageValue } from '@jarenjs/core/message';
 /**
@@ -39,3 +42,61 @@ export declare function makePluralPicker(pluralRules: Intl.PluralRules): (count:
  * @returns {(type: string) => string} The type-name renderer
  */
 export declare function makeTypeNamer(typeNames: Record<string, string>): (type: string) => string;
+/**
+ * Build a multi-form noun picker over a pack's plural rules: the
+ * count's CLDR category selects a member of the `forms` record, and
+ * `other` covers every category the record leaves out. For languages
+ * whose counted messages need more than the two forms
+ * {@link makePluralPicker} covers - Russian's one/few/many, Arabic's
+ * six.
+ *
+ * @param {Intl.PluralRules} pluralRules - The pack's plural rules
+ * @returns {(count: number, forms: Record<string, string>) => string} The form picker
+ * @example
+ * plural(21, { one: 'секунду', few: 'секунды', other: 'секунд' }); // 'секунду'
+ */
+export declare function makePluralForms(pluralRules: Intl.PluralRules): (count: number, forms: Record<string, string>) => string;
+/**
+ * The relative-time units, in the order a duration shrinks. A unit
+ * outside this list is refused rather than approximated.
+ */
+export declare const RELATIVE_UNITS: readonly string[];
+/**
+ * Check a relative-time call and resolve its numeric mode. Both date
+ * locale providers - the repository one and the `Intl` one - run this,
+ * so the opt-in provider refuses exactly what the default provider
+ * refuses instead of quietly answering where the other raises.
+ *
+ * @param {number} amount - Whole units, signed: negative past, positive future
+ * @param {string} unit - One of {@link RELATIVE_UNITS}
+ * @param {{numeric?: string}} [options] - The caller's options
+ * @returns {string} The resolved numeric mode, `'always'` or `'auto'`
+ * @throws {TypeError} on a fractional amount, an unsupported unit or an unknown mode
+ */
+export declare function checkRelativeArguments(amount: number, unit: string, options?: {
+    numeric?: string;
+}): string;
+/**
+ * Expand a pack's five calendar-name arrays into the flat `date/...`
+ * msgid entries every catalog carries. The arrays are what a translator
+ * wants to read and the flat keys are what the catalog contract needs,
+ * so the expansion - and the length/order check that goes with it -
+ * happens once here rather than as forty hand-typed keys per pack.
+ *
+ * Weekdays start at Sunday, matching the index
+ * `@jarenjs/core/dates`' `EEEE`/`EEE` tokens look names up by.
+ *
+ * @param {{months: string[], monthsShort: string[], weekdays: string[], weekdaysShort: string[], meridiem: string[]}} names - The pack's calendar names
+ * @returns {Record<string, string>} The `date/month|weekday|meridiem/...` entries
+ * @throws {TypeError} when an array has the wrong length or a non-string member
+ * @example
+ * dateNameEntries({ months, monthsShort, weekdays, weekdaysShort, meridiem })
+ * // { 'date/month/01/wide': 'januari', ..., 'date/meridiem/pm': 'p.m.' }
+ */
+export declare function dateNameEntries({ months, monthsShort, weekdays, weekdaysShort, meridiem }: {
+    months: string[];
+    monthsShort: string[];
+    weekdays: string[];
+    weekdaysShort: string[];
+    meridiem: string[];
+}): Record<string, string>;

package/dist/types/index.d.ts

@@ -9,7 +9,18 @@
  * own translations and `Intl` singletons, and imports nothing but the
  * rendering helpers of `./helpers.js` - never a consumer package, so
  * either consumer can serve any pack.
+ *
+ * Beside the error messages, every pack carries the calendar language
+ * `@jarenjs/core/dates` refuses to invent: month, weekday and meridiem
+ * names, relative-time phrases and date-format display names.
+ * `compileDateLocale` (`./dates`) turns a pack into the frozen record a
+ * formatter and a UI read; importing that subpath directly costs no
+ * `Intl` construction at all, which is what keeps server-rendered output
+ * byte-stable. `createIntlDateLocale` (`./intl-dates`) is the opt-in
+ * provider for hosts that want the platform's locales instead.
  */
+export { dateMessagesEn, compileDateLocale, RELATIVE_UNITS } from './dates.js';
+export { createIntlDateLocale } from './intl-dates.js';
 export { ar } from './ar.js';
 export { de } from './de.js';
 export { es } from './es.js';

package/dist/types/intl-dates.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build a calendar language from the host's ICU data.
+ *
+ * The returned shape is the one `compileDateLocale` returns, so a
+ * consumer takes either without knowing which: `names` plugs into
+ * `compileDateFormat`, and `relative` takes the same signed amount and
+ * refuses the same arguments. What differs is only where the text comes
+ * from, and therefore whether it is stable across host versions.
+ *
+ * @param {string} locale - A BCP 47 locale tag (`'nl-NL'`)
+ * @param {{formatNames?: Record<string, string>}} [options] - Date-format display names, merged over the English ones
+ * @returns {Readonly<import('./dates.js').DateLocale>} The frozen calendar language
+ * @example
+ * const dates = createIntlDateLocale('hu-HU');
+ * compileDateFormat('yyyy MMMM d.', dates.names);
+ * dates.relative(-3, 'day'); // '3 napja'
+ */
+export declare function createIntlDateLocale(locale: string, options?: {
+    formatNames?: Record<string, string>;
+}): Readonly<import('./dates.js').DateLocale>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/locales",
   "private": false,
-  "version": "0.46.4",
+  "version": "0.49.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -11,6 +11,14 @@
       "types": "./dist/types/index.d.ts",
       "default": "./src/index.js"
     },
+    "./dates": {
+      "types": "./dist/types/dates.d.ts",
+      "default": "./src/dates.js"
+    },
+    "./intl-dates": {
+      "types": "./dist/types/intl-dates.d.ts",
+      "default": "./src/intl-dates.js"
+    },
     "./ar": {
       "types": "./dist/types/ar.d.ts",
       "default": "./src/ar.js"
@@ -90,6 +98,6 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.4"
+    "@jarenjs/core": "^0.49.2"
   }
 }

package/src/ar.js

@@ -15,7 +15,9 @@
  * - Arabic pluralizes across six categories, so counted messages phrase
  *   around a fixed "عدد" (count-of) noun ("يجب ألا يقل عدد الأحرف عن 2")
  *   instead of agreeing the noun with the number - the standard
- *   software-string convention; no plural helper is needed,
+ *   software-string convention. The relative-time phrases are the
+ *   exception, because there the counted noun IS the message, so they
+ *   agree through `Intl.PluralRules`,
  * - `Intl.NumberFormat` is pinned to Latin digits (`numberingSystem:
  *   'latn'`): the limits describe JSON documents, which are written in
  *   Latin digits regardless of UI language,
@@ -26,11 +28,14 @@
 import {
   formatMessageValue,
   makeNumberRenderer,
+  makePluralForms,
   makeTypeNamer,
+  dateNameEntries,
 } from './helpers.js';
 
 //#region Intl singletons
 
+const pluralRules = new Intl.PluralRules('ar');
 const numberFormat = new Intl.NumberFormat('ar', { numberingSystem: 'latn' });
 const listFormat = new Intl.ListFormat('ar', { style: 'long', type: 'disjunction' });
 
@@ -54,6 +59,28 @@ const TYPE_NAMES = {
 /** Type keyword values under their Arabic display name. */
 const typeName = makeTypeNamer(TYPE_NAMES);
 
+/** Pick the form a counted noun takes across Arabic's six categories. */
+const plural = makePluralForms(pluralRules);
+
+/**
+ * Count a noun the Arabic way: one and two are carried by the noun's own
+ * forms and take no numeral at all ("ثانية واحدة", "ثانيتين"), three to
+ * ten take the broken plural after the numeral, eleven to ninety-nine
+ * take the accusative singular ("21 يومًا") and a hundred or more the
+ * bare singular. This is the one place the pack
+ * cannot phrase around a fixed noun - a relative-time phrase IS the
+ * counted noun.
+ * @param {number} value - The absolute amount
+ * @param {Record<string, string>} forms - The noun's forms by CLDR category
+ * @returns {string}
+ */
+function counted(value, forms) {
+  const category = pluralRules.select(value);
+  return (category === 'one' || category === 'two')
+    ? plural(value, forms)
+    : `${num(value)} ${plural(value, forms)}`;
+}
+
 /**
  * The limit comparisons in words: an ASCII operator between RTL text
  * and a number falls to the bidi algorithm's neutral reordering and
@@ -198,4 +225,52 @@ export const ar = {
   'contract/stream-error': 'انتهى دفق العملية ⁨{op}⁩ بخطأ من الخادم (⁨{code}⁩)',
   'contract/heartbeat-missed': 'ظل دفق العملية ⁨{op}⁩ صامتًا لمدة {ms} مللي ثانية',
   //#endregion
+
+  //#region calendar language (the date names, relative phrasing and
+  //   format display names of @jarenjs/locales' date adapter)
+  // Arabic abbreviates neither month nor weekday names, so the wide and
+  // short arrays hold the same strings - as CLDR has them.
+  ...dateNameEntries({
+    months: [
+      'يناير', 'فبراير', 'مارس', 'أبريل', 'مايو', 'يونيو',
+      'يوليو', 'أغسطس', 'سبتمبر', 'أكتوبر', 'نوفمبر', 'ديسمبر',
+    ],
+    monthsShort: [
+      'يناير', 'فبراير', 'مارس', 'أبريل', 'مايو', 'يونيو',
+      'يوليو', 'أغسطس', 'سبتمبر', 'أكتوبر', 'نوفمبر', 'ديسمبر',
+    ],
+    weekdays: [
+      'الأحد', 'الاثنين', 'الثلاثاء', 'الأربعاء',
+      'الخميس', 'الجمعة', 'السبت',
+    ],
+    weekdaysShort: [
+      'الأحد', 'الاثنين', 'الثلاثاء', 'الأربعاء', 'الخميس', 'الجمعة', 'السبت',
+    ],
+    meridiem: ['ص', 'م'],
+  }),
+  'date/relative/second/past': (p) => `قبل ${counted(p.value, { one: 'ثانية واحدة', two: 'ثانيتين', few: 'ثوانٍ', many: 'ثانيةً', other: 'ثانية' })}`,
+  'date/relative/second/future': (p) => `خلال ${counted(p.value, { one: 'ثانية واحدة', two: 'ثانيتين', few: 'ثوانٍ', many: 'ثانيةً', other: 'ثانية' })}`,
+  'date/relative/minute/past': (p) => `قبل ${counted(p.value, { one: 'دقيقة واحدة', two: 'دقيقتين', few: 'دقائق', many: 'دقيقةً', other: 'دقيقة' })}`,
+  'date/relative/minute/future': (p) => `خلال ${counted(p.value, { one: 'دقيقة واحدة', two: 'دقيقتين', few: 'دقائق', many: 'دقيقةً', other: 'دقيقة' })}`,
+  'date/relative/hour/past': (p) => `قبل ${counted(p.value, { one: 'ساعة واحدة', two: 'ساعتين', few: 'ساعات', many: 'ساعةً', other: 'ساعة' })}`,
+  'date/relative/hour/future': (p) => `خلال ${counted(p.value, { one: 'ساعة واحدة', two: 'ساعتين', few: 'ساعات', many: 'ساعةً', other: 'ساعة' })}`,
+  'date/relative/day/past': (p) => `قبل ${counted(p.value, { one: 'يوم واحد', two: 'يومين', few: 'أيام', many: 'يومًا', other: 'يوم' })}`,
+  'date/relative/day/future': (p) => `خلال ${counted(p.value, { one: 'يوم واحد', two: 'يومين', few: 'أيام', many: 'يومًا', other: 'يوم' })}`,
+  'date/relative/week/past': (p) => `قبل ${counted(p.value, { one: 'أسبوع واحد', two: 'أسبوعين', few: 'أسابيع', many: 'أسبوعًا', other: 'أسبوع' })}`,
+  'date/relative/week/future': (p) => `خلال ${counted(p.value, { one: 'أسبوع واحد', two: 'أسبوعين', few: 'أسابيع', many: 'أسبوعًا', other: 'أسبوع' })}`,
+  'date/relative/month/past': (p) => `قبل ${counted(p.value, { one: 'شهر واحد', two: 'شهرين', few: 'أشهر', many: 'شهرًا', other: 'شهر' })}`,
+  'date/relative/month/future': (p) => `خلال ${counted(p.value, { one: 'شهر واحد', two: 'شهرين', few: 'أشهر', many: 'شهرًا', other: 'شهر' })}`,
+  'date/relative/year/past': (p) => `قبل ${counted(p.value, { one: 'سنة واحدة', two: 'سنتين', few: 'سنوات', many: 'سنةً', other: 'سنة' })}`,
+  'date/relative/year/future': (p) => `خلال ${counted(p.value, { one: 'سنة واحدة', two: 'سنتين', few: 'سنوات', many: 'سنةً', other: 'سنة' })}`,
+  'date/relative/now': 'الآن',
+  'date/relative/yesterday': 'أمس',
+  'date/relative/today': 'اليوم',
+  'date/relative/tomorrow': 'غدًا',
+  'format/name/date': 'تاريخ',
+  'format/name/time': 'وقت',
+  'format/name/date-time': 'تاريخ ووقت',
+  'format/name/iso-date': 'تاريخ ISO',
+  'format/name/iso-time': 'وقت ISO',
+  'format/name/iso-date-time': 'تاريخ ووقت ISO',
+  //#endregion
 };