@jarenjs/locales 0.46.4 → 0.49.2

package/src/dates.js

@@ -0,0 +1,263 @@
+//@ts-check
+
+/**
+ * Calendar language: month, weekday and meridiem names, signed
+ * relative-time phrases and date-format display names, on the same flat
+ * msgid machinery every other message in the suite travels on.
+ *
+ * `@jarenjs/core/dates` is locale-free on purpose - its `MMMM`, `EEE`
+ * and `a` tokens refuse to render without a names provider rather than
+ * inventing an English default. This module is that provider, and it is
+ * repository DATA rather than an `Intl` lookup, because the site is
+ * server-rendered under byte-comparison tests and ICU output drifts
+ * between Node versions. A host that wants a hundred locales and does
+ * not need byte-stable output constructs `createIntlDateLocale`
+ * explicitly (`./intl-dates.js`); nothing here reaches for `Intl`.
+ *
+ * The key set is closed and mechanical:
+ *
+ *   date/month/01..12/wide|short     the twelve months, January first
+ *   date/weekday/0..6/wide|short     the seven days, Sunday = 0
+ *   date/meridiem/am|pm              the two day-period markers
+ *   date/relative/<unit>/past|future the seven units, both directions
+ *   date/relative/now|yesterday|today|tomorrow
+ *   format/name/<format>             the date/time format display names
+ *
+ * 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 chosen by the key.
+ */
+
+import { compileMessageCatalog } from '@jarenjs/core/message';
+
+import {
+  RELATIVE_UNITS,
+  checkRelativeArguments,
+  dateNameEntries,
+} from './helpers.js';
+
+export { RELATIVE_UNITS };
+
+//#region The English defaults
+
+/**
+ * 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 const dateMessagesEn = {
+  ...dateNameEntries({
+    months: [
+      'January', 'February', 'March', 'April', 'May', 'June',
+      'July', 'August', 'September', 'October', 'November', 'December',
+    ],
+    monthsShort: [
+      'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+      'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+    ],
+    weekdays: [
+      'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday',
+    ],
+    weekdaysShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
+    meridiem: ['AM', 'PM'],
+  }),
+
+  'date/relative/second/past': (p) => `${p.value} second${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/second/future': (p) => `in ${p.value} second${p.value === 1 ? '' : 's'}`,
+  'date/relative/minute/past': (p) => `${p.value} minute${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/minute/future': (p) => `in ${p.value} minute${p.value === 1 ? '' : 's'}`,
+  'date/relative/hour/past': (p) => `${p.value} hour${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/hour/future': (p) => `in ${p.value} hour${p.value === 1 ? '' : 's'}`,
+  'date/relative/day/past': (p) => `${p.value} day${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/day/future': (p) => `in ${p.value} day${p.value === 1 ? '' : 's'}`,
+  'date/relative/week/past': (p) => `${p.value} week${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/week/future': (p) => `in ${p.value} week${p.value === 1 ? '' : 's'}`,
+  'date/relative/month/past': (p) => `${p.value} month${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/month/future': (p) => `in ${p.value} month${p.value === 1 ? '' : 's'}`,
+  'date/relative/year/past': (p) => `${p.value} year${p.value === 1 ? '' : 's'} ago`,
+  'date/relative/year/future': (p) => `in ${p.value} year${p.value === 1 ? '' : 's'}`,
+  'date/relative/now': 'now',
+  'date/relative/yesterday': 'yesterday',
+  'date/relative/today': 'today',
+  'date/relative/tomorrow': 'tomorrow',
+
+  'format/name/date': 'date',
+  'format/name/time': 'time',
+  'format/name/date-time': 'date and time',
+  'format/name/iso-date': 'ISO date',
+  'format/name/iso-time': 'ISO time',
+  'format/name/iso-date-time': 'ISO date and time',
+};
+
+//#endregion
+
+//#region Compilation
+
+/** Every key a pack has to carry, in catalog order. */
+const DATE_KEYS = Object.freeze(Object.keys(dateMessagesEn));
+
+/** The `format/name/` prefix, and the formats this family closes over. */
+const FORMAT_PREFIX = 'format/name/';
+const FORMAT_NAMES = Object.freeze(DATE_KEYS
+  .filter((key) => key.startsWith(FORMAT_PREFIX))
+  .map((key) => key.slice(FORMAT_PREFIX.length)));
+
+/** The compiled English defaults, once (allocation discipline). */
+const EN = compileMessageCatalog(dateMessagesEn);
+
+/** Shared empty params for the entries that interpolate nothing. */
+const NO_PARAMS = Object.freeze({});
+
+/**
+ * The calendar names a date pattern needs - the shape
+ * `compileDateFormat`'s `names` argument takes.
+ * @typedef {Object} DateLocaleNames
+ * @property {string[]} months - 12 wide month names, January first
+ * @property {string[]} monthsShort - 12 abbreviated month names
+ * @property {string[]} weekdays - 7 wide weekday names, Sunday first
+ * @property {string[]} weekdaysShort - 7 abbreviated weekday names
+ * @property {[string, string]} meridiem - the AM and PM markers
+ */
+
+/**
+ * A compiled calendar language.
+ * @typedef {Object} DateLocale
+ * @property {DateLocaleNames} names - the arrays `compileDateFormat` reads
+ * @property {(amount: number, unit: string, options?: {numeric?: string}) => string} relative - a signed relative-time phrase
+ * @property {(format: string) => string|undefined} formatName - a date-format display name, or undefined when the catalog has none
+ */
+
+/**
+ * Read one entry and insist it rendered readable text: a caller catalog
+ * may hold a closure, and a closure can return anything.
+ * @param {Record<string, (params: object, error?: object) => string>} compiled - The compiled date entries
+ * @param {string} key - The msgid
+ * @returns {string}
+ */
+function readName(compiled, key) {
+  const render = compiled[key] ?? EN[key];
+  const text = render(NO_PARAMS);
+  if (typeof text !== 'string' || text === '')
+    throw new TypeError(`the date catalog entry '${key}' must render a non-empty string`);
+  return text;
+}
+
+/**
+ * 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 function compileDateLocale(catalogLike = undefined) {
+  /** @type {Record<string, any>} */
+  const picked = {};
+  if (catalogLike != null) {
+    for (let i = 0; i < DATE_KEYS.length; ++i) {
+      const key = DATE_KEYS[i];
+      const entry = catalogLike[key];
+      if (entry !== undefined) picked[key] = entry;
+    }
+  }
+  const compiled = compileMessageCatalog(picked);
+
+  const months = [];
+  const monthsShort = [];
+  for (let i = 1; i <= 12; ++i) {
+    const number = i < 10 ? `0${i}` : `${i}`;
+    months.push(readName(compiled, `date/month/${number}/wide`));
+    monthsShort.push(readName(compiled, `date/month/${number}/short`));
+  }
+  const weekdays = [];
+  const weekdaysShort = [];
+  for (let i = 0; i < 7; ++i) {
+    weekdays.push(readName(compiled, `date/weekday/${i}/wide`));
+    weekdaysShort.push(readName(compiled, `date/weekday/${i}/short`));
+  }
+  const names = Object.freeze({
+    months: Object.freeze(months),
+    monthsShort: Object.freeze(monthsShort),
+    weekdays: Object.freeze(weekdays),
+    weekdaysShort: Object.freeze(weekdaysShort),
+    meridiem: /** @type {[string, string]} */ (/** @type {unknown} */ (Object.freeze([
+      readName(compiled, 'date/meridiem/am'),
+      readName(compiled, 'date/meridiem/pm'),
+    ]))),
+  });
+
+  const phrases = Object.create(null);
+  for (const unit of RELATIVE_UNITS) {
+    phrases[unit] = {
+      past: compiled[`date/relative/${unit}/past`] ?? EN[`date/relative/${unit}/past`],
+      future: compiled[`date/relative/${unit}/future`] ?? EN[`date/relative/${unit}/future`],
+    };
+  }
+  const now = readName(compiled, 'date/relative/now');
+  const yesterday = readName(compiled, 'date/relative/yesterday');
+  const today = readName(compiled, 'date/relative/today');
+  const tomorrow = readName(compiled, 'date/relative/tomorrow');
+
+  /**
+   * Phrase a signed offset. The amount is the caller's: negative is
+   * past, positive is future, and nothing here reads a clock.
+   * @param {number} amount - Whole units, signed
+   * @param {string} unit - One of second|minute|hour|day|week|month|year
+   * @param {{numeric?: string}} [options] - `numeric: 'auto'` prefers the four named days
+   * @returns {string}
+   */
+  function relative(amount, unit, options = undefined) {
+    const numeric = checkRelativeArguments(amount, unit, options);
+    // 'auto' reaches for a named day only where it is EXACT: a whole day
+    // away is yesterday/today/tomorrow and a zero-second offset is now,
+    // while '0 minutes' could be anything within the minute and stays
+    // numeric.
+    if (numeric === 'auto') {
+      if (unit === 'day') {
+        if (amount === -1) return yesterday;
+        if (amount === 0) return today;
+        if (amount === 1) return tomorrow;
+      }
+      else if (unit === 'second' && amount === 0) return now;
+    }
+    const pair = phrases[unit];
+    // Math.abs also folds -0 back to 0, so a signed zero cannot reach a
+    // pack's number renderer and come back with a minus in front of it
+    const value = Math.abs(amount);
+    return amount < 0 ? pair.past({ value }) : pair.future({ value });
+  }
+
+  // read at compile time like the names, so a label costs a lookup
+  const formatNames = Object.create(null);
+  for (const format of FORMAT_NAMES)
+    formatNames[format] = readName(compiled, FORMAT_PREFIX + format);
+
+  /**
+   * The display name of a date/time format, for a message that would
+   * otherwise show the format's wire name. The family is closed at the
+   * six date and time formats; anything else has no name here and the
+   * caller keeps its own.
+   * @param {string} format - A format name (`'date-time'`)
+   * @returns {string|undefined} The display name, or undefined when this family has none
+   */
+  function formatName(format) {
+    return typeof format === 'string' ? formatNames[format] : undefined;
+  }
+
+  return Object.freeze({ names, relative, formatName });
+}
+
+//#endregion

package/src/de.js

@@ -24,6 +24,7 @@ import {
   makeNumberRenderer,
   makePluralPicker,
   makeTypeNamer,
+  dateNameEntries,
 } from './helpers.js';
 
 //#region Intl singletons
@@ -167,4 +168,52 @@ export const de = {
   'contract/stream-error': 'der Stream der Operation {op} endete mit einem Serverfehler ({code})',
   'contract/heartbeat-missed': 'der Stream der Operation {op} blieb {ms} ms lang still',
   //#endregion
+
+  //#region calendar language (the date names, relative phrasing and
+  //   format display names of @jarenjs/locales' date adapter)
+  // Both 'vor' and 'in' govern the dative, so the counted nouns are the
+  // dative forms ('vor 2 Tagen', not 'vor 2 Tage').
+  ...dateNameEntries({
+    months: [
+      'Januar', 'Februar', 'März', 'April', 'Mai', 'Juni',
+      'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember',
+    ],
+    monthsShort: [
+      'Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun',
+      'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez',
+    ],
+    weekdays: [
+      'Sonntag', 'Montag', 'Dienstag', 'Mittwoch',
+      'Donnerstag', 'Freitag', 'Samstag',
+    ],
+    weekdaysShort: [
+      'So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa',
+    ],
+    meridiem: ['AM', 'PM'],
+  }),
+  'date/relative/second/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Sekunde', 'Sekunden')}`,
+  'date/relative/second/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Sekunde', 'Sekunden')}`,
+  'date/relative/minute/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Minute', 'Minuten')}`,
+  'date/relative/minute/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Minute', 'Minuten')}`,
+  'date/relative/hour/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Stunde', 'Stunden')}`,
+  'date/relative/hour/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Stunde', 'Stunden')}`,
+  'date/relative/day/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Tag', 'Tagen')}`,
+  'date/relative/day/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Tag', 'Tagen')}`,
+  'date/relative/week/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Woche', 'Wochen')}`,
+  'date/relative/week/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Woche', 'Wochen')}`,
+  'date/relative/month/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Monat', 'Monaten')}`,
+  'date/relative/month/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Monat', 'Monaten')}`,
+  'date/relative/year/past': (p) => `vor ${num(p.value)} ${plural(p.value, 'Jahr', 'Jahren')}`,
+  'date/relative/year/future': (p) => `in ${num(p.value)} ${plural(p.value, 'Jahr', 'Jahren')}`,
+  'date/relative/now': 'jetzt',
+  'date/relative/yesterday': 'gestern',
+  'date/relative/today': 'heute',
+  'date/relative/tomorrow': 'morgen',
+  'format/name/date': 'Datum',
+  'format/name/time': 'Uhrzeit',
+  'format/name/date-time': 'Datum und Uhrzeit',
+  'format/name/iso-date': 'ISO-Datum',
+  'format/name/iso-time': 'ISO-Uhrzeit',
+  'format/name/iso-date-time': 'ISO-Datum und -Uhrzeit',
+  //#endregion
 };

package/src/es.js

@@ -24,6 +24,7 @@ import {
   makeNumberRenderer,
   makePluralPicker,
   makeTypeNamer,
+  dateNameEntries,
 } from './helpers.js';
 
 //#region Intl singletons
@@ -167,4 +168,50 @@ export const es = {
   'contract/stream-error': 'el flujo de la operación {op} terminó con un error del servidor ({code})',
   'contract/heartbeat-missed': 'el flujo de la operación {op} quedó en silencio durante {ms} ms',
   //#endregion
+
+  //#region calendar language (the date names, relative phrasing and
+  //   format display names of @jarenjs/locales' date adapter)
+  ...dateNameEntries({
+    months: [
+      'enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio',
+      'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre',
+    ],
+    monthsShort: [
+      'ene', 'feb', 'mar', 'abr', 'may', 'jun',
+      'jul', 'ago', 'sept', 'oct', 'nov', 'dic',
+    ],
+    weekdays: [
+      'domingo', 'lunes', 'martes', 'miércoles',
+      'jueves', 'viernes', 'sábado',
+    ],
+    weekdaysShort: [
+      'dom', 'lun', 'mar', 'mié', 'jue', 'vie', 'sáb',
+    ],
+    meridiem: ['a. m.', 'p. m.'],
+  }),
+  'date/relative/second/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'segundo', 'segundos')}`,
+  'date/relative/second/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'segundo', 'segundos')}`,
+  'date/relative/minute/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'minuto', 'minutos')}`,
+  'date/relative/minute/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'minuto', 'minutos')}`,
+  'date/relative/hour/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'hora', 'horas')}`,
+  'date/relative/hour/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'hora', 'horas')}`,
+  'date/relative/day/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'día', 'días')}`,
+  'date/relative/day/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'día', 'días')}`,
+  'date/relative/week/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'semana', 'semanas')}`,
+  'date/relative/week/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'semana', 'semanas')}`,
+  'date/relative/month/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'mes', 'meses')}`,
+  'date/relative/month/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'mes', 'meses')}`,
+  'date/relative/year/past': (p) => `hace ${num(p.value)} ${plural(p.value, 'año', 'años')}`,
+  'date/relative/year/future': (p) => `dentro de ${num(p.value)} ${plural(p.value, 'año', 'años')}`,
+  'date/relative/now': 'ahora',
+  'date/relative/yesterday': 'ayer',
+  'date/relative/today': 'hoy',
+  'date/relative/tomorrow': 'mañana',
+  'format/name/date': 'fecha',
+  'format/name/time': 'hora',
+  'format/name/date-time': 'fecha y hora',
+  'format/name/iso-date': 'fecha ISO',
+  'format/name/iso-time': 'hora ISO',
+  'format/name/iso-date-time': 'fecha y hora ISO',
+  //#endregion
 };

package/src/fr.js

@@ -24,6 +24,7 @@ import {
   makeNumberRenderer,
   makePluralPicker,
   makeTypeNamer,
+  dateNameEntries,
 } from './helpers.js';
 
 //#region Intl singletons
@@ -167,4 +168,52 @@ export const fr = {
   'contract/stream-error': "le flux de l'opération {op} s'est terminé par une erreur serveur ({code})",
   'contract/heartbeat-missed': "le flux de l'opération {op} est resté silencieux pendant {ms} ms",
   //#endregion
+
+  //#region calendar language (the date names, relative phrasing and
+  //   format display names of @jarenjs/locales' date adapter)
+  // French keeps the singular at zero as well as at one, which is what
+  // the pack's CLDR plural rules already say; 'mois' has no plural mark.
+  ...dateNameEntries({
+    months: [
+      'janvier', 'février', 'mars', 'avril', 'mai', 'juin',
+      'juillet', 'août', 'septembre', 'octobre', 'novembre', 'décembre',
+    ],
+    monthsShort: [
+      'janv.', 'févr.', 'mars', 'avr.', 'mai', 'juin',
+      'juil.', 'août', 'sept.', 'oct.', 'nov.', 'déc.',
+    ],
+    weekdays: [
+      'dimanche', 'lundi', 'mardi', 'mercredi',
+      'jeudi', 'vendredi', 'samedi',
+    ],
+    weekdaysShort: [
+      'dim.', 'lun.', 'mar.', 'mer.', 'jeu.', 'ven.', 'sam.',
+    ],
+    meridiem: ['AM', 'PM'],
+  }),
+  'date/relative/second/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'seconde', 'secondes')}`,
+  'date/relative/second/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'seconde', 'secondes')}`,
+  'date/relative/minute/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'minute', 'minutes')}`,
+  'date/relative/minute/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'minute', 'minutes')}`,
+  'date/relative/hour/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'heure', 'heures')}`,
+  'date/relative/hour/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'heure', 'heures')}`,
+  'date/relative/day/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'jour', 'jours')}`,
+  'date/relative/day/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'jour', 'jours')}`,
+  'date/relative/week/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'semaine', 'semaines')}`,
+  'date/relative/week/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'semaine', 'semaines')}`,
+  'date/relative/month/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'mois', 'mois')}`,
+  'date/relative/month/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'mois', 'mois')}`,
+  'date/relative/year/past': (p) => `il y a ${num(p.value)} ${plural(p.value, 'an', 'ans')}`,
+  'date/relative/year/future': (p) => `dans ${num(p.value)} ${plural(p.value, 'an', 'ans')}`,
+  'date/relative/now': 'maintenant',
+  'date/relative/yesterday': 'hier',
+  'date/relative/today': 'aujourd\'hui',
+  'date/relative/tomorrow': 'demain',
+  'format/name/date': 'date',
+  'format/name/time': 'heure',
+  'format/name/date-time': 'date et heure',
+  'format/name/iso-date': 'date ISO',
+  'format/name/iso-time': 'heure ISO',
+  'format/name/iso-date-time': 'date et heure ISO',
+  //#endregion
 };

package/src/helpers.js

@@ -8,8 +8,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';
@@ -57,3 +60,114 @@ export function makeTypeNamer(typeNames) {
     return typeNames[type] ?? type;
   };
 }
+
+/**
+ * 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 function makePluralForms(pluralRules) {
+  return function pickPluralForms(count, forms) {
+    return forms[pluralRules.select(count)] ?? forms.other;
+  };
+}
+
+/**
+ * The relative-time units, in the order a duration shrinks. A unit
+ * outside this list is refused rather than approximated.
+ */
+export const RELATIVE_UNITS = Object.freeze([
+  'second', 'minute', 'hour', 'day', 'week', 'month', 'year',
+]);
+
+/**
+ * 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 function checkRelativeArguments(amount, unit, options) {
+  if (!Number.isInteger(amount))
+    throw new TypeError(`a relative amount must be a whole number of units, got ${amount}`);
+  if (!RELATIVE_UNITS.includes(unit))
+    throw new TypeError(`unsupported relative unit '${unit}'`);
+  const numeric = options == null || options.numeric === undefined ? 'always' : options.numeric;
+  if (numeric !== 'always' && numeric !== 'auto')
+    throw new TypeError(`unknown relative numeric mode '${numeric}'`);
+  return numeric;
+}
+
+/** Two-digit month numbers, so a msgid sorts the way a calendar reads. */
+const MONTH_NUMBERS = Object.freeze([
+  '01', '02', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12',
+]);
+
+/**
+ * Check one name array: exact length, every member a non-empty string.
+ * @param {unknown} values - The candidate array
+ * @param {number} count - The exact length required
+ * @param {string} what - The member name, for the refusal
+ * @returns {string[]}
+ */
+function requireNames(values, count, what) {
+  if (!Array.isArray(values) || values.length !== count)
+    throw new TypeError(`date names '${what}' must be an array of exactly ${count} strings`);
+  for (let i = 0; i < count; ++i) {
+    if (typeof values[i] !== 'string' || values[i] === '')
+      throw new TypeError(`date names '${what}[${i}]' must be a non-empty string`);
+  }
+  return values;
+}
+
+/**
+ * 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 function dateNameEntries({ months, monthsShort, weekdays, weekdaysShort, meridiem }) {
+  requireNames(months, 12, 'months');
+  requireNames(monthsShort, 12, 'monthsShort');
+  requireNames(weekdays, 7, 'weekdays');
+  requireNames(weekdaysShort, 7, 'weekdaysShort');
+  requireNames(meridiem, 2, 'meridiem');
+
+  /** @type {Record<string, string>} */
+  const entries = {};
+  for (let i = 0; i < 12; ++i) {
+    entries[`date/month/${MONTH_NUMBERS[i]}/wide`] = months[i];
+    entries[`date/month/${MONTH_NUMBERS[i]}/short`] = monthsShort[i];
+  }
+  for (let i = 0; i < 7; ++i) {
+    entries[`date/weekday/${i}/wide`] = weekdays[i];
+    entries[`date/weekday/${i}/short`] = weekdaysShort[i];
+  }
+  entries['date/meridiem/am'] = meridiem[0];
+  entries['date/meridiem/pm'] = meridiem[1];
+  return entries;
+}

package/src/index.js

@@ -11,8 +11,20 @@
  * 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';