@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/errors/problem-json.js

@@ -0,0 +1,58 @@
+export const PROBLEM_JSON = "application/problem+json";
+/* RFC 9110 §15.5–15.6 reason phrases (418 from RFC 2324), for every error status honey names */
+const REASON = /* @__PURE__ */ Object.freeze({
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Content Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Content",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+});
+/** The Problem Details document for a standard error; `instance` is the request id, or `null`. */
+export function problemDetails(error, instance) {
+    const doc = {
+        detail: error.message,
+        status: error.status,
+        title: REASON[error.status] ?? error.statusKey,
+        type: `https://honey.dev/errors/${error.errorKey}`,
+    };
+    if (instance !== null)
+        doc.instance = instance;
+    if (Object.keys(error.fields).length > 0)
+        doc.errors = error.fields;
+    return doc;
+}

package/dist/errors/projector.d.ts

@@ -0,0 +1,50 @@
+import { HoneyError } from "./error.ts";
+import { ERROR_META, type ErrorMetaEntry } from "./errors.ts";
+import { type ErrorFormat } from "./problem-json.ts";
+/** Shapes a standard error's default body. */
+export type ErrorFormatter = (error: HoneyError, defaultShape: Record<string, unknown>) => Record<string, unknown>;
+/** Shapes a schema error's `data` body. */
+export type CustomErrorFormatter = (error: HoneyError, data: Record<string, unknown>) => Record<string, unknown>;
+/** A `defineErrors` result, as the projector reads it. */
+export type ErrorFactoryRecord = {
+    readonly [key: string]: unknown;
+    readonly [ERROR_META]?: Readonly<Record<string, ErrorMetaEntry>>;
+};
+/** The digest an unknown error's 500 carries: the same value is on the operator's log line. */
+export declare const DIGEST: unique symbol;
+/** What a route allows to reach the client. */
+export type ErrorPolicy = {
+    /** The error an undeclared or unknown throw becomes; `null`: a 500. */
+    boundaryKey: string | null;
+    /** The keys the route declared via `.errors()`; `null`: the route does not enforce them. */
+    declared: ReadonlySet<string> | null;
+    factory: ErrorFactoryRecord | null;
+};
+/** What `ctx.error` holds for a throw: the HoneyError itself, or the 500 it became. */
+export declare function asHoneyError(thrown: unknown): HoneyError;
+/** The boundary error for `errorKey`: the factory's standard error, else a 500 under that key. */
+export declare function boundaryError(errorKey: string, cause: unknown, factory: ErrorFactoryRecord | null): HoneyError;
+/** The error a throw becomes under the route's policy. */
+export declare function projectThrown(thrown: unknown, policy: ErrorPolicy): HoneyError;
+/** Hears a formatter that crashed; the answer still falls back to a well-formed body. */
+export type FormatterReport = (failure: unknown) => void;
+/**
+ * How an error answer is built: who hears a crashed formatter, whether it goes out over the Node
+ * bridge (a HoneyResponse, so a middleware's header write stays on the plain map, b4), its format,
+ * and the request id a Problem Details document names as its instance.
+ */
+export type ErrorAnswer = {
+    readonly format?: ErrorFormat;
+    readonly instance?: string | null;
+    readonly nodeOut?: boolean;
+    readonly report?: FormatterReport | undefined;
+};
+/** A JSON answer built the way the bridge it goes out over writes it fastest. */
+export declare function jsonAnswer(payload: string, headers: Record<string, string>, status: number, nodeOut: boolean): Response;
+/** The JSON response for an error: a schema error's data, or the formatted default shape. */
+export declare function createErrorResponse(error: HoneyError, defaultFormatter: ErrorFormatter, customFormatter?: CustomErrorFormatter | null, answer?: ErrorAnswer): Response;
+/**
+ * The last resort when the error path itself failed: the HoneyError's own response, a 500 for
+ * anything else, and a fixed 500 when even that cannot be serialized.
+ */
+export declare function safeErrorResponse(thrown: unknown, defaultFormatter: ErrorFormatter, customFormatter: CustomErrorFormatter | null, answer?: ErrorAnswer): Response;

package/dist/errors/projector.js

@@ -0,0 +1,107 @@
+/**
+ * The thrown-value projector: what a handler or middleware threw becomes the `HoneyError` the
+ * route's error boundary allows, and that error becomes a JSON response through the app's
+ * formatters. Pure: dispatch wraps it with onError, i18n and telemetry.
+ */
+import { createHoneyResponse, withRawBody } from "../response/builder.js";
+import { EK, HoneyError, hasUnknownStatus, isFrameworkErrorKey } from "./error.js";
+import { ERROR_META } from "./errors.js";
+import { PROBLEM_JSON, problemDetails } from "./problem-json.js";
+/** The digest an unknown error's 500 carries: the same value is on the operator's log line. */
+export const DIGEST = /* @__PURE__ */ Symbol("honey.digest");
+function internalError(cause) {
+    return new HoneyError({ cause, errorKey: EK.internal_server_error, status: "internal_server_error" });
+}
+/** What `ctx.error` holds for a throw: the HoneyError itself, or the 500 it became. */
+export function asHoneyError(thrown) {
+    return thrown instanceof HoneyError ? thrown : internalError(thrown);
+}
+/** The boundary error for `errorKey`: the factory's standard error, else a 500 under that key. */
+export function boundaryError(errorKey, cause, factory) {
+    const make = factory?.[errorKey];
+    /* a schema error needs its payload: it cannot serve as the boundary */
+    if (typeof make === "function" && !factory?.[ERROR_META]?.[errorKey]?.schema) {
+        return make({ cause });
+    }
+    return new HoneyError({ cause, errorKey, status: "internal_server_error" });
+}
+/** The error a throw becomes under the route's policy. */
+export function projectThrown(thrown, policy) {
+    if (thrown instanceof HoneyError && !hasUnknownStatus(thrown)) {
+        const allowed = policy.declared === null || isFrameworkErrorKey(thrown.errorKey) || policy.declared.has(thrown.errorKey);
+        if (allowed)
+            return thrown;
+    }
+    return policy.boundaryKey === null ? internalError(thrown) : boundaryError(policy.boundaryKey, thrown, policy.factory);
+}
+/** A JSON answer built the way the bridge it goes out over writes it fastest. */
+export function jsonAnswer(payload, headers, status, nodeOut) {
+    if (nodeOut)
+        return createHoneyResponse({ headers, raw: payload, status });
+    return withRawBody(new Response(payload, { headers, status }), payload);
+}
+/** The default shape of a standard error: honey's envelope, or a Problem Details document. */
+function defaultShapeOf(error, answer) {
+    if (answer.format === "problem+json")
+        return problemDetails(error, answer.instance ?? null);
+    return {
+        error_key: error.errorKey,
+        fields: error.fields,
+        message: error.message,
+        status: error.status,
+        status_key: error.statusKey,
+        success: false,
+    };
+}
+function errorBody(error, defaultFormatter, customFormatter, answer) {
+    const report = answer.report;
+    if (error.data !== undefined) {
+        const data = error.data;
+        if (!customFormatter)
+            return data;
+        try {
+            return customFormatter(error, data);
+        }
+        catch (failure) {
+            /* a crashed custom formatter: reported, and the client still gets the error's data */
+            report?.(failure);
+            return data;
+        }
+    }
+    const defaultShape = defaultShapeOf(error, answer);
+    const digest = error[DIGEST];
+    if (digest !== undefined)
+        defaultShape.digest = digest;
+    try {
+        return defaultFormatter(error, defaultShape);
+    }
+    catch (failure) {
+        /* a crashed formatter: reported, and the client still gets the default shape */
+        report?.(failure);
+        return defaultShape;
+    }
+}
+/** The JSON response for an error: a schema error's data, or the formatted default shape. */
+export function createErrorResponse(error, defaultFormatter, customFormatter, answer = {}) {
+    const payload = JSON.stringify(errorBody(error, defaultFormatter, customFormatter, answer));
+    /* a schema error keeps its declared body, and so its type */
+    const type = answer.format === "problem+json" && error.data === undefined ? PROBLEM_JSON : "application/json";
+    const headers = { "content-type": type, ...error.headers };
+    return jsonAnswer(payload, headers, error.status, answer.nodeOut === true);
+}
+/**
+ * The last resort when the error path itself failed: the HoneyError's own response, a 500 for
+ * anything else, and a fixed 500 when even that cannot be serialized.
+ */
+export function safeErrorResponse(thrown, defaultFormatter, customFormatter, answer = {}) {
+    try {
+        return createErrorResponse(thrown instanceof HoneyError ? thrown : internalError(undefined), defaultFormatter, customFormatter, answer);
+    }
+    catch {
+        /* the last resort: the boundary logs what failed (on-error.ts); this only keeps the answer well-formed */
+        return new Response(JSON.stringify({ error: { errorKey: EK.internal_server_error } }), {
+            headers: { "content-type": "application/json" },
+            status: 500,
+        });
+    }
+}

package/dist/i18n/error-i18n.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error-message i18n: `errorI18n({ errors, fieldNames, resolveLocale })` builds the value
+ * `app.errorI18n(value)` carries (H23: a value, never a module slot). For an error answer, core
+ * resolves the request's locale and asks it to `translate`: the message from the locale's template
+ * for the error key, its vars filled in, and each field path's display name, tried as written and
+ * then without its leading segments (`json.email`, then `email`). The result is a copy; the thrown
+ * error is never changed, so one instance can answer many requests in many locales.
+ */
+import { HoneyError } from "../errors/error.ts";
+import type { ErrorI18n, ResolveLocaleCtx } from "../routing/settings.ts";
+import type { MaybePromise } from "../middleware/middleware.ts";
+/** Message templates and field display names, each keyed by locale. */
+export type ErrorTranslations = {
+    /** locale → error key → ICU template */
+    errors?: Record<string, Record<string, string>>;
+    /** locale → field path → display name */
+    fieldNames?: Record<string, Record<string, string>>;
+};
+export type ErrorI18nConfig<TEnv> = ErrorTranslations & {
+    /** The request's locale: a header, a cookie, the tenant in env, a path param. */
+    resolveLocale: (ctx: ResolveLocaleCtx<TEnv>) => MaybePromise<string>;
+};
+/** `error` in `locale`, as a copy; `error` itself when nothing translates. */
+export declare function translateError(error: HoneyError, translations: ErrorTranslations, locale: string): HoneyError;
+/** The value `app.errorI18n(value)` carries; it keeps one Formatter, so plural rules are built once. */
+export declare function errorI18n<TEnv = unknown>(config: ErrorI18nConfig<TEnv>): ErrorI18n<TEnv>;

package/dist/i18n/error-i18n.js

@@ -0,0 +1,77 @@
+/**
+ * Error-message i18n: `errorI18n({ errors, fieldNames, resolveLocale })` builds the value
+ * `app.errorI18n(value)` carries (H23: a value, never a module slot). For an error answer, core
+ * resolves the request's locale and asks it to `translate`: the message from the locale's template
+ * for the error key, its vars filled in, and each field path's display name, tried as written and
+ * then without its leading segments (`json.email`, then `email`). The result is a copy; the thrown
+ * error is never changed, so one instance can answer many requests in many locales.
+ */
+import { HoneyError } from "../errors/error.js";
+import { DIGEST } from "../errors/projector.js";
+import { dict } from "../routing/tree.js";
+import { Formatter } from "./icu.js";
+/* the locale and keys come from request data: own keys only */
+function ownValue(record, key) {
+    return record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
+}
+/** `path`'s display name: as written, else without its leading segments; the path itself when none. */
+function displayName(names, path) {
+    let candidate = path;
+    while (candidate) {
+        const name = ownValue(names, candidate);
+        if (name)
+            return name;
+        const dot = candidate.indexOf(".");
+        if (dot === -1)
+            break;
+        candidate = candidate.slice(dot + 1);
+    }
+    return path;
+}
+function translatedFields(fields, names) {
+    const out = dict();
+    for (const source of Object.keys(fields)) {
+        out[source] = fields[source].map((field) => ({ ...field, path: displayName(names, field.path) }));
+    }
+    return out;
+}
+/** A copy of `error` with `message` and `fields`: same key, status, data, headers, vars, cause, stack and digest. */
+function copyOf(error, message, fields) {
+    const copy = new HoneyError({
+        cause: error.cause,
+        data: error.data,
+        errorKey: error.errorKey,
+        fields: fields ?? error.fields,
+        headers: error.headers,
+        status: error.statusKey,
+        vars: error.vars,
+    });
+    copy.message = message ?? error.message;
+    if (error.stack !== undefined)
+        copy.stack = error.stack;
+    /* a 5xx's digest names the operator's line: the client's copy carries it too */
+    const digest = error[DIGEST];
+    if (digest !== undefined)
+        Object.defineProperty(copy, DIGEST, { value: digest });
+    return copy;
+}
+function translateWith(formatter, error, translations, locale) {
+    const template = ownValue(ownValue(translations.errors, locale), error.errorKey);
+    const message = template ? formatter.interpolate(template, error.vars ?? {}, locale) : undefined;
+    const names = ownValue(translations.fieldNames, locale);
+    const fields = names && Object.keys(error.fields).length > 0 ? translatedFields(error.fields, names) : undefined;
+    return message === undefined && fields === undefined ? error : copyOf(error, message, fields);
+}
+/** `error` in `locale`, as a copy; `error` itself when nothing translates. */
+export function translateError(error, translations, locale) {
+    return translateWith(new Formatter(), error, translations, locale);
+}
+/** The value `app.errorI18n(value)` carries; it keeps one Formatter, so plural rules are built once. */
+export function errorI18n(config) {
+    const formatter = new Formatter();
+    const translations = { errors: config.errors, fieldNames: config.fieldNames };
+    return Object.freeze({
+        resolveLocale: config.resolveLocale,
+        translate: (error, locale) => translateWith(formatter, error, translations, locale),
+    });
+}

package/dist/i18n/i18n.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Translations by locale: a `TranslationRegistry` loads each locale's map once (a map, or a sync or
+ * async loader) and keeps it, and `resolveTranslation` / `resolveFieldName` read through it. A
+ * registry owns a `Formatter`, so the plural rules and number formats its messages need are built
+ * once for as long as it lives. Keys and locales are own keys only: a `constructor` misses.
+ */
+import { Formatter } from "./icu.ts";
+export type TranslationMap = Record<string, string>;
+export type TranslationSource = (() => Promise<TranslationMap> | TranslationMap) | TranslationMap;
+export declare class TranslationRegistry {
+    #private;
+    /** The formatter this registry's translations interpolate with. */
+    readonly formatter: Formatter;
+    constructor(sources: Record<string, TranslationSource>);
+    /** `locale`'s map, loaded on first ask; `undefined` for a locale it has no source for. A loader's failure rejects. */
+    get(locale: string): Promise<TranslationMap | undefined>;
+}
+/** `key`'s message in `locale` with `vars` filled in; the key itself when the locale or the key is unknown. */
+export declare function resolveTranslation(registry: TranslationRegistry, locale: string, key: string, vars: Record<string, number | string>): Promise<string>;
+/** `fieldPath`'s display name in `locale`; the path itself when there is none. */
+export declare function resolveFieldName(registry: TranslationRegistry, locale: string, fieldPath: string): Promise<string>;

package/dist/i18n/i18n.js

@@ -0,0 +1,40 @@
+/**
+ * Translations by locale: a `TranslationRegistry` loads each locale's map once (a map, or a sync or
+ * async loader) and keeps it, and `resolveTranslation` / `resolveFieldName` read through it. A
+ * registry owns a `Formatter`, so the plural rules and number formats its messages need are built
+ * once for as long as it lives. Keys and locales are own keys only: a `constructor` misses.
+ */
+import { Formatter } from "./icu.js";
+export class TranslationRegistry {
+    #loaded = new Map();
+    #sources;
+    /** The formatter this registry's translations interpolate with. */
+    formatter = new Formatter();
+    constructor(sources) {
+        this.#sources = sources;
+    }
+    /** `locale`'s map, loaded on first ask; `undefined` for a locale it has no source for. A loader's failure rejects. */
+    async get(locale) {
+        const loaded = this.#loaded.get(locale);
+        if (loaded !== undefined)
+            return loaded;
+        if (!Object.hasOwn(this.#sources, locale))
+            return undefined;
+        const source = this.#sources[locale];
+        const map = typeof source === "function" ? await source() : source;
+        this.#loaded.set(locale, map);
+        return map;
+    }
+}
+/** `key`'s message in `locale` with `vars` filled in; the key itself when the locale or the key is unknown. */
+export async function resolveTranslation(registry, locale, key, vars) {
+    const map = await registry.get(locale);
+    if (map === undefined || !Object.hasOwn(map, key))
+        return key;
+    return registry.formatter.interpolate(map[key], vars, locale);
+}
+/** `fieldPath`'s display name in `locale`; the path itself when there is none. */
+export async function resolveFieldName(registry, locale, fieldPath) {
+    const map = await registry.get(locale);
+    return map !== undefined && Object.hasOwn(map, fieldPath) ? map[fieldPath] : fieldPath;
+}

package/dist/i18n/icu.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The ICU MessageFormat subset honey speaks: `{var}`, `{var, number}`, `{var, plural, =N{…}
+ * category{…} other{…}}` with `#`, and `{var, select, …}`, nested to any depth. A missing var stays
+ * the literal `{var}`, unbalanced braces pass through as text, and nothing throws. Branches and vars
+ * are looked up as own keys only, so a `constructor` or `__proto__` branch or var is plain data.
+ *
+ * Building an `Intl.PluralRules` or `Intl.NumberFormat` costs some 9 µs, using one well under 1 µs,
+ * so a `Formatter` keeps them per locale for as long as it lives (bounded, never module state,
+ * H23): the error-i18n value and each registry own one, `createInterpolator()` hands one out, and
+ * the free `interpolate` builds one per call.
+ */
+/**
+ * The `{var}` names of an ICU message literal, as a vars type (`cause` is HoneyError's own); `{}`
+ * when it has none, so `vars` can be left out.
+ */
+export type ExtractICUVars<T extends string> = T extends `${string}{${infer Var}}${infer Rest}` ? Var extends "cause" ? ExtractICUVars<Rest> : {
+    [K in Var | keyof ExtractICUVars<Rest>]: number | string;
+} : {};
+/** Interpolates ICU messages, keeping each locale's plural rules and number format while it lives. */
+export declare class Formatter {
+    #private;
+    interpolate(template: string, vars: Record<string, unknown>, locale?: string): string;
+}
+/** An `interpolate` that keeps plural rules and number formats between calls: for a caller formatting in a loop. */
+export declare function createInterpolator(): {
+    interpolate: (template: string, vars: Record<string, unknown>, locale?: string) => string;
+};
+/** Fill an ICU message's vars for `locale`. Each call builds the formatters it needs; `createInterpolator` keeps them. */
+export declare function interpolate(template: string, vars: Record<string, unknown>, locale?: string): string;

package/dist/i18n/icu.js

@@ -0,0 +1,170 @@
+/**
+ * The ICU MessageFormat subset honey speaks: `{var}`, `{var, number}`, `{var, plural, =N{…}
+ * category{…} other{…}}` with `#`, and `{var, select, …}`, nested to any depth. A missing var stays
+ * the literal `{var}`, unbalanced braces pass through as text, and nothing throws. Branches and vars
+ * are looked up as own keys only, so a `constructor` or `__proto__` branch or var is plain data.
+ *
+ * Building an `Intl.PluralRules` or `Intl.NumberFormat` costs some 9 µs, using one well under 1 µs,
+ * so a `Formatter` keeps them per locale for as long as it lives (bounded, never module state,
+ * H23): the error-i18n value and each registry own one, `createInterpolator()` hands one out, and
+ * the free `interpolate` builds one per call.
+ */
+/* past this many locales a Formatter stops remembering new ones: a locale from request data cannot grow it */
+const MAX_LOCALES = 256;
+/** Own-key lookup: branches and vars are keyed by data, so `constructor` must not reach the prototype. */
+function own(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+function matchingBrace(text, start) {
+    let depth = 0;
+    for (let i = start; i < text.length; i++) {
+        if (text[i] === "{")
+            depth++;
+        else if (text[i] === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+const SPACE = /\s/;
+function skipSpace(text, from) {
+    let i = from;
+    while (i < text.length && SPACE.test(text[i]))
+        i++;
+    return i;
+}
+/** `one {…} other {…}` as a null-prototype record of category → template. */
+function parseBranches(content) {
+    const branches = Object.create(null);
+    let i = 0;
+    for (;;) {
+        i = skipSpace(content, i);
+        let category = "";
+        while (i < content.length && content[i] !== "{" && !SPACE.test(content[i]))
+            category += content[i++];
+        if (category === "")
+            return branches;
+        i = skipSpace(content, i);
+        if (content[i] !== "{")
+            return branches;
+        /* a block is tokenized only once its braces match, so its content is balanced: this brace closes */
+        const end = matchingBrace(content, i);
+        branches[category] = content.slice(i + 1, end);
+        i = end + 1;
+    }
+}
+/** One `{…}`'s inside as a token: a simple var, a number, or a plural/select block. */
+function blockOf(inner) {
+    const comma = inner.indexOf(",");
+    if (comma === -1)
+        return { type: "simple", varName: inner.trim() };
+    const varName = inner.slice(0, comma).trim();
+    const rest = inner.slice(comma + 1).trim();
+    const second = rest.indexOf(",");
+    if (second === -1)
+        return { type: rest === "number" ? "number" : "simple", varName };
+    const format = rest.slice(0, second).trim();
+    if (format !== "plural" && format !== "select")
+        return { type: "simple", varName };
+    return { branches: parseBranches(rest.slice(second + 1).trim()), type: format, varName };
+}
+function tokenize(message) {
+    const tokens = [];
+    let i = 0;
+    while (i < message.length) {
+        const open = message.indexOf("{", i);
+        if (open === -1) {
+            tokens.push(message.slice(i));
+            break;
+        }
+        if (open > i)
+            tokens.push(message.slice(i, open));
+        const close = matchingBrace(message, open);
+        if (close === -1) {
+            tokens.push(message.slice(open));
+            break;
+        }
+        tokens.push(blockOf(message.slice(open + 1, close)));
+        i = close + 1;
+    }
+    return tokens;
+}
+/** Interpolates ICU messages, keeping each locale's plural rules and number format while it lives. */
+export class Formatter {
+    #numbers = new Map();
+    #plurals = new Map();
+    /** CLDR plural category of `n` in `locale` ("one", "few", "other"…); English rules for an unknown locale. */
+    #category(n, locale) {
+        const key = locale ?? "en";
+        let rules = this.#plurals.get(key);
+        if (rules === undefined) {
+            try {
+                rules = new Intl.PluralRules(key);
+            }
+            catch {
+                /* the answer, not a failure: a locale Intl does not know takes English plural rules */
+                rules = new Intl.PluralRules("en");
+            }
+            if (this.#plurals.size < MAX_LOCALES)
+                this.#plurals.set(key, rules);
+        }
+        return rules.select(n);
+    }
+    /** `n` formatted for `locale` (the host's own when unset); plain digits for a locale Intl rejects. */
+    #number(n, locale) {
+        const key = locale ?? "";
+        let format = this.#numbers.get(key);
+        if (format === undefined) {
+            try {
+                format = new Intl.NumberFormat(locale);
+            }
+            catch {
+                /* the answer, not a failure: a locale Intl rejects formats as plain digits */
+                format = null;
+            }
+            if (this.#numbers.size < MAX_LOCALES)
+                this.#numbers.set(key, format);
+        }
+        return format === null ? String(n) : format.format(n);
+    }
+    /* a plural block: the exact `=N` branch, else the CLDR category, else `other`; `#` is the count */
+    #plural(block, value, vars, locale) {
+        const n = Number(value ?? 0);
+        const { branches } = block;
+        const template = own(branches, `=${n}`) ?? own(branches, this.#category(n, locale)) ?? own(branches, "other") ?? "";
+        /* ICU formats `#` for the locale; without one, plain digits (the host's locale would make output vary) */
+        return this.interpolate(template.replaceAll("#", locale === undefined ? String(n) : this.#number(n, locale)), vars, locale);
+    }
+    #resolve(token, vars, locale) {
+        if (typeof token === "string")
+            return token;
+        const value = own(vars, token.varName);
+        const missing = value === undefined || value === null;
+        switch (token.type) {
+            case "simple":
+                return missing ? `{${token.varName}}` : String(value);
+            case "number":
+                return missing ? `{${token.varName}}` : this.#number(Number(value), locale);
+            case "select":
+                return this.interpolate(own(token.branches, missing ? "" : String(value)) ?? own(token.branches, "other") ?? "", vars, locale);
+            default:
+                return this.#plural(token, value, vars, locale);
+        }
+    }
+    interpolate(template, vars, locale) {
+        if (!template)
+            return template;
+        let out = "";
+        for (const token of tokenize(template))
+            out += this.#resolve(token, vars, locale);
+        return out;
+    }
+}
+/** An `interpolate` that keeps plural rules and number formats between calls: for a caller formatting in a loop. */
+export function createInterpolator() {
+    const formatter = new Formatter();
+    return { interpolate: (template, vars, locale) => formatter.interpolate(template, vars, locale) };
+}
+/** Fill an ICU message's vars for `locale`. Each call builds the formatters it needs; `createInterpolator` keeps them. */
+export function interpolate(template, vars, locale) {
+    return new Formatter().interpolate(template, vars, locale);
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,4 @@
+/** `@lovrozagar/honey/i18n`: the error translations `app.errorI18n(value)` carries, and ICU interpolation. */
+export { type ErrorI18nConfig, type ErrorTranslations, errorI18n, translateError } from "./error-i18n.ts";
+export { createInterpolator, type ExtractICUVars, interpolate } from "./icu.ts";
+export type { TranslationMap, TranslationSource } from "./i18n.ts";

package/dist/i18n/index.js

@@ -0,0 +1,3 @@
+/** `@lovrozagar/honey/i18n`: the error translations `app.errorI18n(value)` carries, and ICU interpolation. */
+export { errorI18n, translateError } from "./error-i18n.js";
+export { createInterpolator, interpolate } from "./icu.js";