@flighthq/intl 0.1.0

package/dist/cache.d.ts

@@ -0,0 +1,21 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Return the cached value for `key`, building and storing it with `build` on a
+ * miss. Memoizes the immutable `Intl.*` formatter instances the format
+ * functions share — building an `Intl.*` per call is the cost this package
+ * exists to remove.
+ *
+ * The cache is a bounded module-level `Map` (see the bottom of this file): it
+ * holds only immutable formatter instances, never mutable app state, and evicts
+ * the oldest entry once it exceeds `cacheCapacity` so it cannot grow unbounded.
+ */
+export declare function getCached<T>(key: string, build: () => T): T;
+/**
+ * Build the stable cache key for one formatter family. `kind` names the family
+ * (`'number'`, `'date'`, …); `locale` and `options` are serialized so that two
+ * calls with equivalent arguments hit the same entry. Options key order follows
+ * insertion order, which is stable because each format function assembles its
+ * options object the same way every call.
+ */
+export declare function getCacheKey(kind: string, locale: LocaleInput, options: Readonly<object> | undefined): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAW3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,GAAG,MAAM,CAG5G"}

package/dist/cache.js

@@ -0,0 +1,40 @@
+/**
+ * Return the cached value for `key`, building and storing it with `build` on a
+ * miss. Memoizes the immutable `Intl.*` formatter instances the format
+ * functions share — building an `Intl.*` per call is the cost this package
+ * exists to remove.
+ *
+ * The cache is a bounded module-level `Map` (see the bottom of this file): it
+ * holds only immutable formatter instances, never mutable app state, and evicts
+ * the oldest entry once it exceeds `cacheCapacity` so it cannot grow unbounded.
+ */
+export function getCached(key, build) {
+    const existing = formatterCache.get(key);
+    if (existing !== undefined)
+        return existing;
+    const built = build();
+    if (formatterCache.size >= cacheCapacity) {
+        const oldest = formatterCache.keys().next().value;
+        if (oldest !== undefined)
+            formatterCache.delete(oldest);
+    }
+    formatterCache.set(key, built);
+    return built;
+}
+/**
+ * Build the stable cache key for one formatter family. `kind` names the family
+ * (`'number'`, `'date'`, …); `locale` and `options` are serialized so that two
+ * calls with equivalent arguments hit the same entry. Options key order follows
+ * insertion order, which is stable because each format function assembles its
+ * options object the same way every call.
+ */
+export function getCacheKey(kind, locale, options) {
+    const localeKey = typeof locale === 'string' ? locale : locale.join(',');
+    return `${kind}|${localeKey}|${options === undefined ? '' : JSON.stringify(options)}`;
+}
+// Immutable `Intl.*` instances keyed by `kind|locale|options`. A Map preserves
+// insertion order, so the first key is the oldest and drives simple FIFO
+// eviction once the cache is full.
+const formatterCache = new Map();
+const cacheCapacity = 256;
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAI,GAAW,EAAE,KAAc;IACtD,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAa,CAAC;IAEjD,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC;IACtB,IAAI,cAAc,CAAC,IAAI,IAAI,aAAa,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAClD,IAAI,MAAM,KAAK,SAAS;YAAE,cAAc,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1D,CAAC;IACD,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAAmB,EAAE,OAAqC;IAClG,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzE,OAAO,GAAG,IAAI,IAAI,SAAS,IAAI,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,+EAA+E;AAC/E,yEAAyE;AACzE,mCAAmC;AACnC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAmB,CAAC;AAClD,MAAM,aAAa,GAAG,GAAG,CAAC"}

package/dist/collator.d.ts

@@ -0,0 +1,16 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Compare strings `a` and `b` for locale-aware ordering in `locale`, returning
+ * a negative number when `a` sorts before `b`, `0` when they sort equally, and
+ * a positive number when `a` sorts after `b` — the comparator contract
+ * `Array.prototype.sort` expects. Pass `{ sensitivity, numeric, caseFirst }`
+ * options to tune collation (e.g. `{ numeric: true }` for `'file2' < 'file10'`).
+ */
+export declare function compareStrings(a: string, b: string, locale: LocaleInput, options?: Readonly<Intl.CollatorOptions>): number;
+/**
+ * Return a new array of `items` sorted by locale-aware collation in `locale`.
+ * The input array is not mutated. Uses the same `Intl.Collator` (and cache) as
+ * `compareStrings`, so `options` tune ordering identically.
+ */
+export declare function sortStrings(items: readonly string[], locale: LocaleInput, options?: Readonly<Intl.CollatorOptions>): string[];
+//# sourceMappingURL=collator.d.ts.map

package/dist/collator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collator.d.ts","sourceRoot":"","sources":["../src/collator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,GACvC,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,GACvC,MAAM,EAAE,CAGV"}

package/dist/collator.js

@@ -0,0 +1,25 @@
+import { getCacheKey, getCached } from './cache';
+/**
+ * Compare strings `a` and `b` for locale-aware ordering in `locale`, returning
+ * a negative number when `a` sorts before `b`, `0` when they sort equally, and
+ * a positive number when `a` sorts after `b` — the comparator contract
+ * `Array.prototype.sort` expects. Pass `{ sensitivity, numeric, caseFirst }`
+ * options to tune collation (e.g. `{ numeric: true }` for `'file2' < 'file10'`).
+ */
+export function compareStrings(a, b, locale, options) {
+    return getCollator(locale, options).compare(a, b);
+}
+/**
+ * Return a new array of `items` sorted by locale-aware collation in `locale`.
+ * The input array is not mutated. Uses the same `Intl.Collator` (and cache) as
+ * `compareStrings`, so `options` tune ordering identically.
+ */
+export function sortStrings(items, locale, options) {
+    const collator = getCollator(locale, options);
+    return items.slice().sort((a, b) => collator.compare(a, b));
+}
+function getCollator(locale, options) {
+    const key = getCacheKey('collator', locale, options);
+    return getCached(key, () => new Intl.Collator(locale, options));
+}
+//# sourceMappingURL=collator.js.map

package/dist/collator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collator.js","sourceRoot":"","sources":["../src/collator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,CAAS,EACT,CAAS,EACT,MAAmB,EACnB,OAAwC;IAExC,OAAO,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,KAAwB,EACxB,MAAmB,EACnB,OAAwC;IAExC,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,WAAW,CAAC,MAAmB,EAAE,OAAmD;IAC3F,MAAM,GAAG,GAAG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAA2B,EAAE,OAAO,CAAC,CAAC,CAAC;AACvF,CAAC"}

package/dist/datetime.d.ts

@@ -0,0 +1,23 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Format the date portion of `date` (a `Date` or epoch-millisecond number) in
+ * `locale`. Default field set: numeric `year`, `month`, and `day` — the order
+ * and separators follow the locale (`en-US` → `'1/15/2020'`, `de-DE` →
+ * `'15.1.2020'`). A caller `options` object replaces the default field set.
+ * An invalid `Date` passes through as `Intl`'s own `'Invalid Date'`.
+ */
+export declare function formatDate(date: Date | number, locale: LocaleInput, options?: Readonly<Intl.DateTimeFormatOptions>): string;
+/**
+ * Format both the date and time of `date` (a `Date` or epoch-millisecond
+ * number) in `locale`. Default field set: numeric `year`/`month`/`day` plus
+ * numeric `hour`/`minute`. A caller `options` object replaces the default field
+ * set.
+ */
+export declare function formatDateTime(date: Date | number, locale: LocaleInput, options?: Readonly<Intl.DateTimeFormatOptions>): string;
+/**
+ * Format the time portion of `date` (a `Date` or epoch-millisecond number) in
+ * `locale`. Default field set: numeric `hour` and `minute` (the locale decides
+ * 12- vs 24-hour). A caller `options` object replaces the default field set.
+ */
+export declare function formatTime(date: Date | number, locale: LocaleInput, options?: Readonly<Intl.DateTimeFormatOptions>): string;
+//# sourceMappingURL=datetime.d.ts.map

package/dist/datetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAC7C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAC7C,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAC7C,MAAM,CAER"}

package/dist/datetime.js

@@ -0,0 +1,50 @@
+import { getCacheKey, getCached } from './cache';
+/**
+ * Format the date portion of `date` (a `Date` or epoch-millisecond number) in
+ * `locale`. Default field set: numeric `year`, `month`, and `day` — the order
+ * and separators follow the locale (`en-US` → `'1/15/2020'`, `de-DE` →
+ * `'15.1.2020'`). A caller `options` object replaces the default field set.
+ * An invalid `Date` passes through as `Intl`'s own `'Invalid Date'`.
+ */
+export function formatDate(date, locale, options) {
+    return formatDateValue(date, locale, options ?? defaultDateOptions);
+}
+/**
+ * Format both the date and time of `date` (a `Date` or epoch-millisecond
+ * number) in `locale`. Default field set: numeric `year`/`month`/`day` plus
+ * numeric `hour`/`minute`. A caller `options` object replaces the default field
+ * set.
+ */
+export function formatDateTime(date, locale, options) {
+    return formatDateValue(date, locale, options ?? defaultDateTimeOptions);
+}
+/**
+ * Format the time portion of `date` (a `Date` or epoch-millisecond number) in
+ * `locale`. Default field set: numeric `hour` and `minute` (the locale decides
+ * 12- vs 24-hour). A caller `options` object replaces the default field set.
+ */
+export function formatTime(date, locale, options) {
+    return formatDateValue(date, locale, options ?? defaultTimeOptions);
+}
+// `Intl.DateTimeFormat.format` throws `RangeError` on an invalid `Date`, unlike
+// `Date.prototype.toLocale*`. Guarding here keeps the charter's degradation
+// contract — an invalid date returns `'Invalid Date'`, matching the `'NaN'`
+// pass-through of the number formatters rather than surfacing as a throw.
+function formatDateValue(date, locale, options) {
+    const time = typeof date === 'number' ? date : date.getTime();
+    if (Number.isNaN(time))
+        return 'Invalid Date';
+    const key = getCacheKey('datetime', locale, options);
+    const formatter = getCached(key, () => new Intl.DateTimeFormat(locale, options));
+    return formatter.format(date);
+}
+const defaultDateOptions = { year: 'numeric', month: 'numeric', day: 'numeric' };
+const defaultTimeOptions = { hour: 'numeric', minute: 'numeric' };
+const defaultDateTimeOptions = {
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+};
+//# sourceMappingURL=datetime.js.map

package/dist/datetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.js","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,IAAmB,EACnB,MAAmB,EACnB,OAA8C;IAE9C,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,IAAI,kBAAkB,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAmB,EACnB,MAAmB,EACnB,OAA8C;IAE9C,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,IAAI,sBAAsB,CAAC,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,IAAmB,EACnB,MAAmB,EACnB,OAA8C;IAE9C,OAAO,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,IAAI,kBAAkB,CAAC,CAAC;AACtE,CAAC;AAED,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,SAAS,eAAe,CACtB,IAAmB,EACnB,MAAmB,EACnB,OAA6C;IAE7C,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IAC9D,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,cAAc,CAAC;IAE9C,MAAM,GAAG,GAAG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,MAA2B,EAAE,OAAO,CAAC,CAAC,CAAC;IACtG,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,kBAAkB,GAAyC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;AACvH,MAAM,kBAAkB,GAAyC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACxG,MAAM,sBAAsB,GAAyC;IACnE,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,SAAS;IACd,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,SAAS;CAClB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './collator';
+export * from './datetime';
+export * from './list';
+export * from './number';
+export * from './plural';
+export * from './relativeTime';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './collator';
+export * from './datetime';
+export * from './list';
+export * from './number';
+export * from './plural';
+export * from './relativeTime';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}

package/dist/list.d.ts

@@ -0,0 +1,9 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Join `items` into one locale-aware list string in `locale` — for example
+ * `['a', 'b', 'c']` → `'a, b, and c'` in `en-US`. Defaults to a conjunction
+ * (`'and'`) list; pass `{ type: 'disjunction' }` for an `'or'` list or
+ * `{ style: 'short' }` / `{ style: 'narrow' }` for tighter joins.
+ */
+export declare function formatList(items: readonly string[], locale: LocaleInput, options?: Readonly<Intl.ListFormatOptions>): string;
+//# sourceMappingURL=list.d.ts.map

package/dist/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,GACzC,MAAM,CAIR"}

package/dist/list.js

@@ -0,0 +1,13 @@
+import { getCacheKey, getCached } from './cache';
+/**
+ * Join `items` into one locale-aware list string in `locale` — for example
+ * `['a', 'b', 'c']` → `'a, b, and c'` in `en-US`. Defaults to a conjunction
+ * (`'and'`) list; pass `{ type: 'disjunction' }` for an `'or'` list or
+ * `{ style: 'short' }` / `{ style: 'narrow' }` for tighter joins.
+ */
+export function formatList(items, locale, options) {
+    const key = getCacheKey('list', locale, options);
+    const formatter = getCached(key, () => new Intl.ListFormat(locale, options));
+    return formatter.format(items);
+}
+//# sourceMappingURL=list.js.map

package/dist/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,KAAwB,EACxB,MAAmB,EACnB,OAA0C;IAE1C,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAA2B,EAAE,OAAO,CAAC,CAAC,CAAC;IAClG,OAAO,SAAS,CAAC,MAAM,CAAC,KAAiB,CAAC,CAAC;AAC7C,CAAC"}

package/dist/number.d.ts

@@ -0,0 +1,31 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Format `value` as a compact number in `locale` (`notation: 'compact'`) — for
+ * example `1200000` → `'1.2M'` in `en-US`. Merges over any caller `options`.
+ */
+export declare function formatCompactNumber(value: number, locale: LocaleInput, options?: Readonly<Intl.NumberFormatOptions>): string;
+/**
+ * Format `value` as an amount in `currency` (ISO 4217 code, e.g. `'USD'`) in
+ * `locale` — for example `1234.5` → `'$1,234.50'` in `en-US`. Sets
+ * `style: 'currency'` and `currency`; a caller may override other options.
+ */
+export declare function formatCurrency(value: number, currency: string, locale: LocaleInput, options?: Readonly<Intl.NumberFormatOptions>): string;
+/**
+ * Format `value` as a plain number in `locale` — for example `1234.56` →
+ * `'1,234.56'` in `en-US`, `'1.234,56'` in `de-DE`. `NaN`/`Infinity` and other
+ * edge inputs pass through `Intl`'s own output unchanged.
+ */
+export declare function formatNumber(value: number, locale: LocaleInput, options?: Readonly<Intl.NumberFormatOptions>): string;
+/**
+ * Format `value` as a percentage in `locale` (`style: 'percent'`) — the value
+ * is a ratio, so `0.25` → `'25%'` in `en-US`. Merges over any caller `options`.
+ */
+export declare function formatPercent(value: number, locale: LocaleInput, options?: Readonly<Intl.NumberFormatOptions>): string;
+/**
+ * Format `value` in a measurement `unit` (a sanctioned CLDR unit identifier such
+ * as `'kilometer-per-hour'`) in `locale` (`style: 'unit'`) — for example
+ * `5` → `'5 km/h'` in `en-US`. Sets `style: 'unit'` and `unit`; a caller may
+ * override other options.
+ */
+export declare function formatUnit(value: number, unit: string, locale: LocaleInput, options?: Readonly<Intl.NumberFormatOptions>): string;
+//# sourceMappingURL=number.d.ts.map

package/dist/number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../src/number.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAC3C,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAC3C,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAErH;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAC3C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAC3C,MAAM,CAER"}

package/dist/number.js

@@ -0,0 +1,45 @@
+import { getCacheKey, getCached } from './cache';
+/**
+ * Format `value` as a compact number in `locale` (`notation: 'compact'`) — for
+ * example `1200000` → `'1.2M'` in `en-US`. Merges over any caller `options`.
+ */
+export function formatCompactNumber(value, locale, options) {
+    return getNumberFormat(locale, { notation: 'compact', ...options }).format(value);
+}
+/**
+ * Format `value` as an amount in `currency` (ISO 4217 code, e.g. `'USD'`) in
+ * `locale` — for example `1234.5` → `'$1,234.50'` in `en-US`. Sets
+ * `style: 'currency'` and `currency`; a caller may override other options.
+ */
+export function formatCurrency(value, currency, locale, options) {
+    return getNumberFormat(locale, { style: 'currency', currency, ...options }).format(value);
+}
+/**
+ * Format `value` as a plain number in `locale` — for example `1234.56` →
+ * `'1,234.56'` in `en-US`, `'1.234,56'` in `de-DE`. `NaN`/`Infinity` and other
+ * edge inputs pass through `Intl`'s own output unchanged.
+ */
+export function formatNumber(value, locale, options) {
+    return getNumberFormat(locale, options).format(value);
+}
+/**
+ * Format `value` as a percentage in `locale` (`style: 'percent'`) — the value
+ * is a ratio, so `0.25` → `'25%'` in `en-US`. Merges over any caller `options`.
+ */
+export function formatPercent(value, locale, options) {
+    return getNumberFormat(locale, { style: 'percent', ...options }).format(value);
+}
+/**
+ * Format `value` in a measurement `unit` (a sanctioned CLDR unit identifier such
+ * as `'kilometer-per-hour'`) in `locale` (`style: 'unit'`) — for example
+ * `5` → `'5 km/h'` in `en-US`. Sets `style: 'unit'` and `unit`; a caller may
+ * override other options.
+ */
+export function formatUnit(value, unit, locale, options) {
+    return getNumberFormat(locale, { style: 'unit', unit, ...options }).format(value);
+}
+function getNumberFormat(locale, options) {
+    const key = getCacheKey('number', locale, options);
+    return getCached(key, () => new Intl.NumberFormat(locale, options));
+}
+//# sourceMappingURL=number.js.map

package/dist/number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.js","sourceRoot":"","sources":["../src/number.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,MAAmB,EACnB,OAA4C;IAE5C,OAAO,eAAe,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,QAAgB,EAChB,MAAmB,EACnB,OAA4C;IAE5C,OAAO,eAAe,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAAmB,EAAE,OAA4C;IAC3G,OAAO,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,MAAmB,EACnB,OAA4C;IAE5C,OAAO,eAAe,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,KAAa,EACb,IAAY,EACZ,MAAmB,EACnB,OAA4C;IAE5C,OAAO,eAAe,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpF,CAAC;AAED,SAAS,eAAe,CACtB,MAAmB,EACnB,OAAuD;IAEvD,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,MAA2B,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3F,CAAC"}

package/dist/plural.d.ts

@@ -0,0 +1,17 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Select the ordinal plural category of `value` in `locale` (`type: 'ordinal'`)
+ * — which grammatical form a positional number (`1st`, `2nd`, …) takes. In
+ * `en-US`: `1` → `'one'`, `2` → `'two'`, `3` → `'few'`, `4` → `'other'`. Use it
+ * to pick the right ordinal suffix per locale.
+ */
+export declare function selectOrdinalCategory(value: number, locale: LocaleInput, options?: Readonly<Intl.PluralRulesOptions>): Intl.LDMLPluralRule;
+/**
+ * Select the cardinal plural category of `value` in `locale` (`type:
+ * 'cardinal'`) — which grammatical form a count takes. In `en-US`: `1` →
+ * `'one'`, everything else → `'other'`; other locales return `'zero'` / `'two'`
+ * / `'few'` / `'many'` where their grammar distinguishes them. Use it to pick
+ * the right message variant for a count.
+ */
+export declare function selectPluralCategory(value: number, locale: LocaleInput, options?: Readonly<Intl.PluralRulesOptions>): Intl.LDMLPluralRule;
+//# sourceMappingURL=plural.d.ts.map

package/dist/plural.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plural.d.ts","sourceRoot":"","sources":["../src/plural.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAC1C,IAAI,CAAC,cAAc,CAErB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAC1C,IAAI,CAAC,cAAc,CAErB"}

package/dist/plural.js

@@ -0,0 +1,25 @@
+import { getCacheKey, getCached } from './cache';
+/**
+ * Select the ordinal plural category of `value` in `locale` (`type: 'ordinal'`)
+ * — which grammatical form a positional number (`1st`, `2nd`, …) takes. In
+ * `en-US`: `1` → `'one'`, `2` → `'two'`, `3` → `'few'`, `4` → `'other'`. Use it
+ * to pick the right ordinal suffix per locale.
+ */
+export function selectOrdinalCategory(value, locale, options) {
+    return getPluralRules(locale, { type: 'ordinal', ...options }).select(value);
+}
+/**
+ * Select the cardinal plural category of `value` in `locale` (`type:
+ * 'cardinal'`) — which grammatical form a count takes. In `en-US`: `1` →
+ * `'one'`, everything else → `'other'`; other locales return `'zero'` / `'two'`
+ * / `'few'` / `'many'` where their grammar distinguishes them. Use it to pick
+ * the right message variant for a count.
+ */
+export function selectPluralCategory(value, locale, options) {
+    return getPluralRules(locale, { type: 'cardinal', ...options }).select(value);
+}
+function getPluralRules(locale, options) {
+    const key = getCacheKey('plural', locale, options);
+    return getCached(key, () => new Intl.PluralRules(locale, options));
+}
+//# sourceMappingURL=plural.js.map

package/dist/plural.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plural.js","sourceRoot":"","sources":["../src/plural.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,MAAmB,EACnB,OAA2C;IAE3C,OAAO,cAAc,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAa,EACb,MAAmB,EACnB,OAA2C;IAE3C,OAAO,cAAc,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,cAAc,CAAC,MAAmB,EAAE,OAA0C;IACrF,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,MAA2B,EAAE,OAAO,CAAC,CAAC,CAAC;AAC1F,CAAC"}

package/dist/relativeTime.d.ts

@@ -0,0 +1,10 @@
+import type { LocaleInput } from '@flighthq/types';
+/**
+ * Format `value` of `unit` as a locale-aware relative-time phrase in `locale` —
+ * a positive value is in the future, a negative value in the past. For example
+ * `formatRelativeTime(2, 'day', 'en-US')` → `'in 2 days'` and `(-1, 'day')` →
+ * `'1 day ago'`. Defaults to `numeric: 'always'`; pass `{ numeric: 'auto' }` to
+ * allow words like `'tomorrow'` / `'yesterday'`.
+ */
+export declare function formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, locale: LocaleInput, options?: Readonly<Intl.RelativeTimeFormatOptions>): string;
+//# sourceMappingURL=relativeTime.d.ts.map

package/dist/relativeTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relativeTime.d.ts","sourceRoot":"","sources":["../src/relativeTime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,CAAC,sBAAsB,EACjC,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,yBAAyB,CAAC,GACjD,MAAM,CAIR"}

package/dist/relativeTime.js

@@ -0,0 +1,14 @@
+import { getCacheKey, getCached } from './cache';
+/**
+ * Format `value` of `unit` as a locale-aware relative-time phrase in `locale` —
+ * a positive value is in the future, a negative value in the past. For example
+ * `formatRelativeTime(2, 'day', 'en-US')` → `'in 2 days'` and `(-1, 'day')` →
+ * `'1 day ago'`. Defaults to `numeric: 'always'`; pass `{ numeric: 'auto' }` to
+ * allow words like `'tomorrow'` / `'yesterday'`.
+ */
+export function formatRelativeTime(value, unit, locale, options) {
+    const key = getCacheKey('relativetime', locale, options);
+    const formatter = getCached(key, () => new Intl.RelativeTimeFormat(locale, options));
+    return formatter.format(value, unit);
+}
+//# sourceMappingURL=relativeTime.js.map

package/dist/relativeTime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relativeTime.js","sourceRoot":"","sources":["../src/relativeTime.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAa,EACb,IAAiC,EACjC,MAAmB,EACnB,OAAkD;IAElD,MAAM,GAAG,GAAG,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAA2B,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1G,OAAO,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/intl",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Locale-aware formatting — number, currency, percent, unit, date/time, list, relative-time, plural/ordinal, and collation over cached Intl instances",
+  "sideEffects": false
+}

package/src/cache.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { getCacheKey, getCached } from './cache';
+
+describe('getCached', () => {
+  it('builds once per key and reuses the stored value', () => {
+    const build = vi.fn(() => ({}));
+    const first = getCached('cache-test|reuse', build);
+    const second = getCached('cache-test|reuse', build);
+    expect(build).toHaveBeenCalledTimes(1);
+    expect(second).toBe(first);
+  });
+
+  it('rebuilds for a different key', () => {
+    const build = vi.fn(() => ({}));
+    const a = getCached('cache-test|a', build);
+    const b = getCached('cache-test|b', build);
+    expect(build).toHaveBeenCalledTimes(2);
+    expect(b).not.toBe(a);
+  });
+});
+
+describe('getCacheKey', () => {
+  it('serializes a string locale and options into a stable key', () => {
+    expect(getCacheKey('number', 'en-US', { style: 'percent' })).toBe('number|en-US|{"style":"percent"}');
+  });
+
+  it('joins a locale fallback list', () => {
+    expect(getCacheKey('number', ['fr-CA', 'fr'], undefined)).toBe('number|fr-CA,fr|');
+  });
+
+  it('separates keys by kind and by options', () => {
+    expect(getCacheKey('number', 'en-US', undefined)).not.toBe(getCacheKey('date', 'en-US', undefined));
+    expect(getCacheKey('number', 'en-US', { style: 'percent' })).not.toBe(
+      getCacheKey('number', 'en-US', { style: 'currency' }),
+    );
+  });
+});

package/src/collator.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { compareStrings, sortStrings } from './collator';
+
+describe('compareStrings', () => {
+  it('orders a before b in en-US', () => {
+    expect(compareStrings('a', 'b', 'en-US')).toBeLessThan(0);
+    expect(compareStrings('b', 'a', 'en-US')).toBeGreaterThan(0);
+  });
+});
+
+describe('sortStrings', () => {
+  it('returns a new sorted array in en-US', () => {
+    expect(sortStrings(['b', 'a', 'c'], 'en-US')).toEqual(['a', 'b', 'c']);
+  });
+
+  it('does not mutate the input array', () => {
+    const input = ['b', 'a', 'c'];
+    sortStrings(input, 'en-US');
+    expect(input).toEqual(['b', 'a', 'c']);
+  });
+});

package/src/datetime.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatDate, formatDateTime, formatTime } from './datetime';
+
+// A fixed instant (2020-01-15T13:05:00Z). Assertions pass an explicit
+// `timeZone: 'UTC'` so they are deterministic regardless of the host time zone.
+const instant = new Date(Date.UTC(2020, 0, 15, 13, 5, 0));
+
+describe('formatDate', () => {
+  it('orders numeric fields per locale', () => {
+    const utc = { year: 'numeric', month: 'numeric', day: 'numeric', timeZone: 'UTC' } as const;
+    expect(formatDate(instant, 'en-US', utc)).toBe('1/15/2020');
+    expect(formatDate(instant, 'de-DE', utc)).toBe('15.1.2020');
+  });
+
+  it('renders a string with the default field set', () => {
+    expect(typeof formatDate(instant, 'en-US')).toBe('string');
+  });
+
+  it('passes an invalid Date through as Intl does', () => {
+    expect(formatDate(new Date(NaN), 'en-US')).toBe('Invalid Date');
+  });
+});
+
+describe('formatDateTime', () => {
+  it('includes both the date and the time', () => {
+    const utc = {
+      year: 'numeric',
+      month: 'numeric',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+      timeZone: 'UTC',
+    } as const;
+    const result = formatDateTime(instant, 'en-US', utc);
+    expect(result).toContain('1/15/2020');
+    expect(result).toContain('1:05');
+  });
+});
+
+describe('formatTime', () => {
+  it('formats the time per locale clock convention', () => {
+    const utc = { hour: 'numeric', minute: 'numeric', timeZone: 'UTC' } as const;
+    expect(formatTime(instant, 'en-US', utc)).toBe('1:05 PM');
+    expect(formatTime(instant, 'de-DE', utc)).toBe('13:05');
+  });
+});

package/src/list.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatList } from './list';
+
+describe('formatList', () => {
+  it('joins items as an en-US conjunction list', () => {
+    expect(formatList(['a', 'b', 'c'], 'en-US')).toBe('a, b, and c');
+  });
+
+  it('joins items as a disjunction list when asked', () => {
+    expect(formatList(['a', 'b', 'c'], 'en-US', { type: 'disjunction' })).toBe('a, b, or c');
+  });
+});

package/src/number.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { formatCompactNumber, formatCurrency, formatNumber, formatPercent, formatUnit } from './number';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('formatCompactNumber', () => {
+  it('abbreviates large numbers in en-US', () => {
+    expect(formatCompactNumber(1_200_000, 'en-US')).toBe('1.2M');
+  });
+});
+
+describe('formatCurrency', () => {
+  it('formats USD amounts in en-US with the currency symbol and two fraction digits', () => {
+    expect(formatCurrency(1234.5, 'USD', 'en-US')).toBe('$1,234.50');
+  });
+});
+
+describe('formatNumber', () => {
+  it('groups and separates by locale', () => {
+    expect(formatNumber(1234.56, 'en-US')).toBe('1,234.56');
+    expect(formatNumber(1234.56, 'de-DE')).toBe('1.234,56');
+  });
+
+  it('passes NaN through as Intl does', () => {
+    expect(formatNumber(NaN, 'en-US')).toBe('NaN');
+  });
+
+  it('reuses one cached Intl.NumberFormat for identical (locale, options) and builds another for different options', () => {
+    // Preserve real construction so `.format` still works, while counting builds.
+    // A regular function (not an arrow) so vitest can invoke it under `new`.
+    const OriginalNumberFormat = Intl.NumberFormat;
+    const spy = vi.spyOn(Intl, 'NumberFormat').mockImplementation(function (
+      locales?: Intl.LocalesArgument,
+      options?: Intl.NumberFormatOptions,
+    ) {
+      return new OriginalNumberFormat(locales, options);
+    });
+
+    // A locale used only by this test, so the cache starts empty for it.
+    formatNumber(1, 'ja-JP');
+    formatNumber(2, 'ja-JP');
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    formatNumber(3, 'ja-JP', { minimumFractionDigits: 2 });
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('formatPercent', () => {
+  it('scales a ratio to a percentage in en-US', () => {
+    expect(formatPercent(0.25, 'en-US')).toBe('25%');
+  });
+});
+
+describe('formatUnit', () => {
+  it('renders a compound unit in en-US', () => {
+    expect(formatUnit(5, 'kilometer-per-hour', 'en-US')).toContain('km/h');
+  });
+});

package/src/plural.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { selectOrdinalCategory, selectPluralCategory } from './plural';
+
+describe('selectOrdinalCategory', () => {
+  it('distinguishes ordinal forms in en-US', () => {
+    expect(selectOrdinalCategory(1, 'en-US')).toBe('one');
+    expect(selectOrdinalCategory(2, 'en-US')).toBe('two');
+    expect(selectOrdinalCategory(3, 'en-US')).toBe('few');
+    expect(selectOrdinalCategory(4, 'en-US')).toBe('other');
+  });
+});
+
+describe('selectPluralCategory', () => {
+  it('distinguishes cardinal forms in en-US', () => {
+    expect(selectPluralCategory(1, 'en-US')).toBe('one');
+    expect(selectPluralCategory(2, 'en-US')).toBe('other');
+  });
+});

package/src/relativeTime.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatRelativeTime } from './relativeTime';
+
+describe('formatRelativeTime', () => {
+  it('phrases a future offset in en-US', () => {
+    expect(formatRelativeTime(2, 'day', 'en-US')).toBe('in 2 days');
+  });
+
+  it('phrases a past offset in en-US', () => {
+    expect(formatRelativeTime(-1, 'day', 'en-US')).toBe('1 day ago');
+  });
+});