moost 0.7.2 → 0.7.4

package/dist/index.cjs

@@ -48,7 +48,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.7.2",
+		version: "0.7.4",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
@@ -658,7 +658,7 @@ function formatNewInstanceArg(a) {
 //#endregion
 //#region packages/moost/src/composables/global-key.ts
 var _g;
-const registry$1 = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PURE__ */ new Map());
+const registry = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PURE__ */ new Map());
 /**
 * Creates a typed event-context key that stays a single instance across duplicate
 * moost loads (dual ESM/CJS, or duplicate installs). Use this for every
@@ -666,8 +666,8 @@ const registry$1 = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PU
 *
 * @param name - Debug label AND the registry lookup key; must be unique per slot.
 */ function globalKey(name) {
-	if (!registry$1.has(name)) registry$1.set(name, (0, _wooksjs_event_core.key)(name));
-	return registry$1.get(name);
+	if (!registry.has(name)) registry.set(name, (0, _wooksjs_event_core.key)(name));
+	return registry.get(name);
 }
 
 //#endregion
@@ -3184,48 +3184,258 @@ function _define_property(obj, key, value) {
 
 //#endregion
 //#region packages/moost/src/i18n.ts
-const TRANSLATOR = Symbol.for("moost.translator");
-const registry = globalThis;
-/**
-* Registers the app's translator (process-wide), or removes it with `undefined`.
-* It takes effect where code calls {@link useTranslate} — your own code and packages that opt
-* in to translating the text they serialise; with no translator registered, text stays as
-* authored.
+var _globalThis, _STATE, _state, _state1, _state2, _state3, _state4;
+const STATE = Symbol.for("moost.i18n");
+const NO_LOCALES = Object.freeze([]);
+/** Distinct scopes given memo keys per generation: keeps every memo keyed by `key` bounded. */ const MAX_SCOPES = 32;
+const state = (_globalThis = globalThis)[_STATE = STATE] ?? (_globalThis[_STATE] = {});
+(_state = state).locales ?? (_state.locales = NO_LOCALES);
+(_state1 = state).generation ?? (_state1.generation = 0);
+(_state2 = state).catalogs ?? (_state2.catalogs = /* @__PURE__ */ new WeakSet());
+(_state3 = state).templates ?? (_state3.templates = /* @__PURE__ */ new Map());
+(_state4 = state).memo ?? (_state4.memo = /* @__PURE__ */ new Map());
+/**
+* Registers the app's translator (process-wide), or removes it with `undefined`: a
+* {@link TTranslate} function or a {@link TTranslations} map. Load your languages before the
+* server listens, or call `setTranslator` again once they are loaded.
+*
+* `opts.locales` lists the locales the app serves, the first being the default (`MoostHttp`
+* negotiates `Accept-Language` against them). For a map they default to its keys — put the
+* source language first: `{ en: {}, de: {…} }`. Give a function translator `locales`, or
+* requests get a locale only from your own `resolveLocale` / `useLocale().set()`.
 *
 * @example
 * ```ts
-* const messages = { de: { 'Name taken': 'Name vergeben' } }
-* setTranslator((text, params, { locale }) => messages[locale ?? '']?.[text])
+* setTranslator({ en: {}, de: { NAME_TAKEN: 'Name {name} ist vergeben' } })
+*
+* setTranslator(
+*   (id, params, { locale }) =>
+*     locale && i18next.exists(id, { lng: locale }) ? i18next.t(id, { ...params, lng: locale }) : undefined,
+*   { locales: ['en', 'de'] },
+* )
 * ```
-*/ function setTranslator(translate) {
-	registry[TRANSLATOR] = translate;
-}
-/** The registered translator, or `undefined` (e.g. to skip a per-locale variant entirely). */ function getTranslator() {
-	return registry[TRANSLATOR];
+*/ function setTranslator(translate, opts) {
+	const isMap = typeof translate === "object";
+	state.translate = isMap ? mapTranslator(translate) : translate;
+	state.scoping = opts?.scope && {
+		translate: state.translate,
+		get: opts.scope
+	};
+	const locales = opts?.locales ?? (isMap ? Object.keys(translate) : void 0);
+	state.locales = translate && locales?.length ? Object.freeze([...locales]) : NO_LOCALES;
+	state.failureLogged = false;
+	state.scopeFailureLogged = false;
+	newGeneration();
+}
+/** The registered translator (a map wrapped as a function), or `undefined`. */ function getTranslator() {
+	return state.translate;
+}
+/** The locales of the registered translator, the default first (empty without a translator). */ function getTranslatorLocales() {
+	return state.locales;
+}
+/**
+* Registers message templates by code (`{ MIN_LENGTH: 'At least {min} characters' }`),
+* process-wide: the English text `useTranslate()` falls back to for the code, and the templates
+* {@link TTranslation.messages} serves translated. Registering the same catalog object again
+* does nothing; a later catalog wins for a code both define. A call that adds or changes a
+* template starts a new generation, like {@link setTranslator} ({@link TTranslation.key}
+* changes).
+*/ function registerMessages(catalog) {
+	if (state.catalogs.has(catalog)) return;
+	state.catalogs.add(catalog);
+	let changed = false;
+	for (const code of Object.keys(catalog)) if (state.templates.get(code) !== catalog[code]) {
+		state.templates.set(code, catalog[code]);
+		changed = true;
+	}
+	if (changed) newGeneration();
+}
+/** Drops everything derived from the translator and the templates. */ function newGeneration() {
+	state.generation++;
+	state.memo.clear();
+}
+const PLACEHOLDER = /\{(\w+)\}/g;
+/**
+* Fills `{name}` placeholders with `params` in one pass (arrays: items joined with `, `).
+* A placeholder without a param stays as it is; filled-in values are never filled again.
+*/ function formatMessage(template, params) {
+	if (!params || !template.includes("{")) return template;
+	return template.replace(PLACEHOLDER, (match, name) => {
+		const value = Object.hasOwn(params, name) ? params[name] : void 0;
+		if (value === void 0) return match;
+		return Array.isArray(value) ? value.map(String).join(", ") : String(value);
+	});
 }
 /**
-* Returns `t(text, params?)` for the current event: the registered translator's result in the
-* event's locale (`useLocale().get()`), else `text` unchanged — never a missing-key marker.
-* With no translator registered, `t` returns `text` (params are not interpolated).
+* Returns `t(id, params?, fallback?)` for the current event (or `ctx`), in the event's locale
+* (`useLocale().get()`). `id` is a code or a source text. `t` returns:
+* - the translator's result, as is (it is final text: params are not filled again);
+* - else `fallback` as is — it is final too, never filled: pass already-filled English text
+*   (e.g. an error's message), or pass no fallback and {@link registerMessages} a template;
+* - else the code's registered template ({@link registerMessages}), or `id` itself, with
+*   `params` filled in ({@link formatMessage}).
 *
 * @example
 * ```ts
 * const t = useTranslate()
-* throw new HttpError(409, { message: t('Name taken'), code: 'NAME_TAKEN' })
+* throw new HttpError(409, { message: t('NAME_TAKEN', { name }, `Name ${name} is taken`), code: 'NAME_TAKEN', params: { name } })
 * ```
 */ function useTranslate(ctx) {
 	const event = ctx ?? (0, _wooksjs_event_core.current)();
 	let translateCtx;
-	return (text, params) => {
-		const translate = getTranslator();
-		if (!translate) return text;
-		translateCtx ?? (translateCtx = {
-			locale: (0, _wooksjs_event_core.useLocale)(event).get(),
-			event
-		});
-		return translate(text, params, translateCtx) ?? text;
+	return (id, params, fallback) => {
+		const translate = state.translate;
+		return (translate ? callTranslator(translate, id, params, translateCtx ?? (translateCtx = translateContext(event, (0, _wooksjs_event_core.useLocale)(event).get(), readScope(event)))) : void 0) ?? untranslated(id, params, fallback);
 	};
 }
+/** `t`'s text without a translation: `fallback` as is, else the filled template (or id). */ function untranslated(id, params, fallback) {
+	return fallback ?? formatMessage(state.templates.get(id) ?? id, params);
+}
+/**
+* The translation of the current event (or `ctx`): its locale, a memo key, `t` and the
+* translated message templates. `undefined` when no translator is registered or the event has
+* no locale — serve the source texts then.
+*/ function useTranslation(ctx) {
+	const translate = state.translate;
+	if (!translate) return;
+	const event = ctx ?? (0, _wooksjs_event_core.current)();
+	const locale = (0, _wooksjs_event_core.useLocale)(event).get();
+	if (locale === void 0) return;
+	const scope = readScope(event);
+	const translateCtx = translateContext(event, locale, scope);
+	const generation = state.generation;
+	const partition = typeof scope === "string" ? `${locale}:${scope}` : locale;
+	const key = state.locales.includes(locale) && (scope === void 0 || scope !== null && admitted(scope)) ? `${generation}:${partition}` : void 0;
+	const t = (id, params, fallback) => callTranslator(translate, id, params, translateCtx) ?? untranslated(id, params, fallback);
+	const messages = () => {
+		if (key === void 0 || state.generation !== generation) return translateTemplates(translate, translateCtx);
+		let out = state.memo.get(key);
+		if (!out) {
+			out = translateTemplates(translate, translateCtx);
+			state.memo.set(key, out);
+		}
+		return out;
+	};
+	return {
+		locale,
+		partition,
+		key,
+		t,
+		messages
+	};
+}
+function translateContext(event, locale, scope) {
+	return typeof scope === "string" ? {
+		locale,
+		scope,
+		event
+	} : {
+		locale,
+		event
+	};
+}
+/**
+* The event's scope (`opts.scope`): `undefined` without one, `null` when the scope function
+* threw (logged once) — translated unscoped then, and not memoized.
+*/ function readScope(event) {
+	const scoping = state.scoping;
+	if (!scoping || scoping.translate !== state.translate) return;
+	try {
+		const { get } = scoping;
+		const scope = (0, _wooksjs_event_core.tryGetCurrent)() === event ? get() : (0, _wooksjs_event_core.run)(event, get);
+		return typeof scope === "string" ? scope : typeof scope === "number" && Number.isFinite(scope) ? String(scope) : void 0;
+	} catch (error) {
+		logOnce("scopeFailureLogged", event, "The translation scope threw — translating unscoped, without memoizing (logged once)", error);
+		return null;
+	}
+}
+/** Whether `scope` gets memo keys: one of the first {@link MAX_SCOPES} of the generation. */ function admitted(scope) {
+	if (state.admittedScopes?.generation !== state.generation) state.admittedScopes = {
+		generation: state.generation,
+		names: /* @__PURE__ */ new Set()
+	};
+	const { names } = state.admittedScopes;
+	if (names.size < MAX_SCOPES) names.add(scope);
+	return names.has(scope);
+}
+/** Logs a failure of the translator or the scope function once per `setTranslator`. */ function logOnce(flag, event, message, error) {
+	if (!state[flag]) {
+		state[flag] = true;
+		(0, _wooksjs_event_core.useLogger)("i18n", event).error(message, error);
+	}
+}
+/**
+* Returns a translated copy of an error body (`{ message, code?, params?, errors? }`) in the
+* event's locale — the body itself when there is no translation ({@link useTranslation}).
+*
+* - each entry of `errors` (and of its entries' `details`): by its `code` (unless `custom`),
+*   else by its message text, its English `message` being the fallback;
+* - the top `message`: by `code` when the body has one; else, when it is the first entry's
+*   message (`path: message`), the first entry's translation; else by its text.
+*
+* `MoostHttp` applies it to every error body when it creates the HTTP app.
+*/ function translateErrorBody(body, ctx) {
+	const event = ctx ?? (0, _wooksjs_event_core.current)();
+	if (!state.translate || (0, _wooksjs_event_core.useLocale)(event).get() === void 0) return body;
+	const t = useTranslate(event);
+	const source = Array.isArray(body.errors) ? body.errors : void 0;
+	const errors = source && translateEntries(source, t);
+	let message;
+	if (typeof body.code === "string" && body.code) message = t(body.code, body.params, body.message);
+	else if (source && errors && isEntry(source[0]) && body.message === topMessage(source[0])) message = topMessage(errors[0]);
+	else message = t(body.message, body.params, body.message);
+	return errors ? {
+		...body,
+		message,
+		errors
+	} : {
+		...body,
+		message
+	};
+}
+function mapTranslator(map) {
+	return (id, params, { locale }) => {
+		const texts = locale !== void 0 && Object.hasOwn(map, locale) ? map[locale] : void 0;
+		return texts && Object.hasOwn(texts, id) ? formatMessage(texts[id], params) : void 0;
+	};
+}
+/** The translator's text, `undefined` if it has none or throws (logged once per `setTranslator`). */ function callTranslator(translate, id, params, ctx) {
+	try {
+		const out = translate(id, params, ctx);
+		return typeof out === "string" ? out : void 0;
+	} catch (error) {
+		logOnce("failureLogged", ctx.event, `The translator threw for "${id}" — using the untranslated text (logged once)`, error);
+		return;
+	}
+}
+/** The registered templates translated with placeholder params, if they differ. */ function translateTemplates(translate, ctx) {
+	const out = {};
+	for (const [code, template] of state.templates) {
+		let params;
+		for (const [placeholder, name] of template.matchAll(PLACEHOLDER)) (params ?? (params = {}))[name] = placeholder;
+		const translated = callTranslator(translate, code, params, ctx);
+		if (translated !== void 0 && translated !== template) out[code] = translated;
+	}
+	return Object.freeze(out);
+}
+function isEntry(value) {
+	return typeof value === "object" && value !== null && typeof value.message === "string";
+}
+function translateEntries(entries, t) {
+	return entries.map((entry) => {
+		if (!isEntry(entry)) return entry;
+		const id = typeof entry.code === "string" && entry.code && entry.custom !== true ? entry.code : entry.message;
+		const out = {
+			...entry,
+			message: t(id, entry.params, entry.message)
+		};
+		if (Array.isArray(entry.details)) out.details = translateEntries(entry.details, t);
+		return out;
+	});
+}
+function topMessage(entry) {
+	return typeof entry.path === "string" && entry.path ? `${entry.path}: ${entry.message}` : entry.message;
+}
 
 //#endregion
 exports.After = After;
@@ -3337,6 +3547,7 @@ Object.defineProperty(exports, 'eventTypeKey', {
   }
 });
 exports.forkEventContext = forkEventContext;
+exports.formatMessage = formatMessage;
 Object.defineProperty(exports, 'getClassKey', {
   enumerable: true,
   get: function () {
@@ -3370,6 +3581,7 @@ exports.getMoostInfact = getMoostInfact;
 exports.getMoostMate = getMoostMate;
 exports.getNewMoostInfact = getNewMoostInfact;
 exports.getTranslator = getTranslator;
+exports.getTranslatorLocales = getTranslatorLocales;
 exports.globalKey = globalKey;
 Object.defineProperty(exports, 'isConstructor', {
   enumerable: true,
@@ -3387,6 +3599,7 @@ Object.defineProperty(exports, 'key', {
 exports.loggerConsoleTransport = loggerConsoleTransport;
 exports.mergeSorted = mergeSorted;
 exports.registerEventScope = registerEventScope;
+exports.registerMessages = registerMessages;
 Object.defineProperty(exports, 'replaceContextInjector', {
   enumerable: true,
   get: function () {
@@ -3414,6 +3627,7 @@ exports.setOvertake = setOvertake;
 exports.setTranslator = setTranslator;
 exports.stampModuleIdentity = stampModuleIdentity;
 exports.stampOnce = stampOnce;
+exports.translateErrorBody = translateErrorBody;
 exports.useControllerContext = useControllerContext;
 exports.useHandlerPaths = useHandlerPaths;
 exports.useInterceptOriginal = useInterceptOriginal;
@@ -3433,4 +3647,5 @@ Object.defineProperty(exports, 'useLogger', {
 exports.useOvertake = useOvertake;
 exports.useScopeId = useScopeId;
 exports.useTranslate = useTranslate;
+exports.useTranslation = useTranslation;
 exports.withControllerContext = withControllerContext;

package/dist/index.d.ts

@@ -1771,54 +1771,162 @@ declare function defineInterceptor(def: TInterceptorDef, priority?: TInterceptor
  */
 declare function definePipeFn<T extends TObject = TEmpty>(fn: TPipeFn<T>, priority?: TPipePriority): TPipeFn<T>;
 
-/** What a translator gets besides the text: the event's locale and the event itself. */
+/** What a translator gets besides the text: the event's locale, its scope and the event itself. */
 interface TTranslateContext {
     /** `useLocale().get()` of the event the text is translated for. */
     locale: string | undefined;
+    /**
+     * The event's translation scope ({@link TTranslatorOptions.scope}) — e.g. a tenant whose
+     * wording differs. `undefined`: the shared wording.
+     */
+    scope?: string;
     /** The event context — read anything else your policy needs from it. */
     event: EventContext;
 }
 /**
- * The app's translator. `text` is a source text (gettext-style message id) or an error/message
- * code (`WF_EXPIRED`, `NAME_TAKEN`, …); `params` are the values it refers to. Return the
- * translation, or `undefined` to keep `text` as is.
+ * The app's translator. `text` is a message id: an error/message code (`WF_EXPIRED`,
+ * `MIN_LENGTH`, …) or a source text (gettext-style); `params` are the values it refers to.
+ * Return the final text (with `params` filled in), or `undefined` when there is no translation.
  *
- * Moost never translates on its own: plug in any i18n library (vue-i18n, i18next, FormatJS)
- * or a plain map here.
+ * Moost never translates on its own: plug in any i18n library (i18next, FormatJS, …) or pass a
+ * plain {@link TTranslations} map to {@link setTranslator}.
  */
 type TTranslate = (text: string, params: Record<string, unknown> | undefined, ctx: TTranslateContext) => string | undefined;
 /**
- * Registers the app's translator (process-wide), or removes it with `undefined`.
- * It takes effect where code calls {@link useTranslate} — your own code and packages that opt
- * in to translating the text they serialise; with no translator registered, text stays as
- * authored.
+ * Translations as a plain map: `{ [locale]: { [id]: template } }`. Templates use `{name}`
+ * placeholders, filled with {@link formatMessage}.
+ */
+type TTranslations = Record<string, Record<string, string>>;
+/** The options of {@link setTranslator}. */
+interface TTranslatorOptions {
+    /** The locales the app serves, the default first. For a map: its keys by default. */
+    locales?: readonly string[];
+    /**
+     * The event's translation scope, for wording that differs by more than the locale (per
+     * tenant, brand, user group, …). Called in the event's context each time a translation is
+     * taken — keep it cheap. Its result is passed to the translator ({@link TTranslateContext.scope})
+     * and partitions everything memoized per translation ({@link TTranslation.key}); a finite
+     * number counts as its string, and `undefined` (or any other value) is the shared, unscoped
+     * wording. The translator must return the same text for the same (id, params, locale, scope).
+     *
+     * Derive it from a validated value (the authenticated principal's tenant), never straight from
+     * request input: only the first 32 scopes seen per generation get a {@link TTranslation.key}.
+     */
+    scope?: () => string | number | undefined;
+}
+/** `t(id, params?, fallback?)` — see {@link useTranslate}. */
+type TTranslateFn = (id: string, params?: Record<string, unknown>, fallback?: string) => string;
+/** The translation of one event's locale — see {@link useTranslation}. */
+interface TTranslation {
+    /** The event's locale. */
+    locale: string;
+    /**
+     * What to index memoized results by: the locale, plus the event's scope when it has one
+     * ({@link TTranslatorOptions.scope}). Keep one entry per partition, replaced when
+     * {@link TTranslation.key} changes.
+     */
+    partition: string;
+    /**
+     * A memo key for anything derived from this translation: the locale, the scope (if any) and
+     * the generation — changes with every {@link setTranslator} call and every
+     * {@link registerMessages} call that adds or changes a template. `undefined` for a locale
+     * outside the translator's `locales`, or a scope past the cap ({@link TTranslatorOptions.scope})
+     * — don't memoize then.
+     */
+    key: string | undefined;
+    /** {@link useTranslate}'s `t`, bound to this translation. */
+    t: TTranslateFn;
+    /**
+     * The registered message templates ({@link registerMessages}) translated to `locale`, with
+     * their `{name}` placeholders kept — only the ones that differ from the English template.
+     * Memoized per {@link TTranslation.key}.
+     */
+    messages: () => Readonly<Record<string, string>>;
+}
+/**
+ * Registers the app's translator (process-wide), or removes it with `undefined`: a
+ * {@link TTranslate} function or a {@link TTranslations} map. Load your languages before the
+ * server listens, or call `setTranslator` again once they are loaded.
+ *
+ * `opts.locales` lists the locales the app serves, the first being the default (`MoostHttp`
+ * negotiates `Accept-Language` against them). For a map they default to its keys — put the
+ * source language first: `{ en: {}, de: {…} }`. Give a function translator `locales`, or
+ * requests get a locale only from your own `resolveLocale` / `useLocale().set()`.
  *
  * @example
  * ```ts
- * const messages = { de: { 'Name taken': 'Name vergeben' } }
- * setTranslator((text, params, { locale }) => messages[locale ?? '']?.[text])
+ * setTranslator({ en: {}, de: { NAME_TAKEN: 'Name {name} ist vergeben' } })
+ *
+ * setTranslator(
+ *   (id, params, { locale }) =>
+ *     locale && i18next.exists(id, { lng: locale }) ? i18next.t(id, { ...params, lng: locale }) : undefined,
+ *   { locales: ['en', 'de'] },
+ * )
  * ```
  */
-declare function setTranslator(translate: TTranslate | undefined): void;
-/** The registered translator, or `undefined` (e.g. to skip a per-locale variant entirely). */
+declare function setTranslator(translate: TTranslate | TTranslations | undefined, opts?: TTranslatorOptions): void;
+/** The registered translator (a map wrapped as a function), or `undefined`. */
 declare function getTranslator(): TTranslate | undefined;
-/**
- * Returns `t(text, params?)` for the current event: the registered translator's result in the
- * event's locale (`useLocale().get()`), else `text` unchanged — never a missing-key marker.
- * With no translator registered, `t` returns `text` (params are not interpolated).
+/** The locales of the registered translator, the default first (empty without a translator). */
+declare function getTranslatorLocales(): readonly string[];
+/**
+ * Registers message templates by code (`{ MIN_LENGTH: 'At least {min} characters' }`),
+ * process-wide: the English text `useTranslate()` falls back to for the code, and the templates
+ * {@link TTranslation.messages} serves translated. Registering the same catalog object again
+ * does nothing; a later catalog wins for a code both define. A call that adds or changes a
+ * template starts a new generation, like {@link setTranslator} ({@link TTranslation.key}
+ * changes).
+ */
+declare function registerMessages(catalog: Readonly<Record<string, string>>): void;
+/**
+ * Fills `{name}` placeholders with `params` in one pass (arrays: items joined with `, `).
+ * A placeholder without a param stays as it is; filled-in values are never filled again.
+ */
+declare function formatMessage(template: string, params?: Record<string, unknown>): string;
+/**
+ * Returns `t(id, params?, fallback?)` for the current event (or `ctx`), in the event's locale
+ * (`useLocale().get()`). `id` is a code or a source text. `t` returns:
+ * - the translator's result, as is (it is final text: params are not filled again);
+ * - else `fallback` as is — it is final too, never filled: pass already-filled English text
+ *   (e.g. an error's message), or pass no fallback and {@link registerMessages} a template;
+ * - else the code's registered template ({@link registerMessages}), or `id` itself, with
+ *   `params` filled in ({@link formatMessage}).
  *
  * @example
  * ```ts
  * const t = useTranslate()
- * throw new HttpError(409, { message: t('Name taken'), code: 'NAME_TAKEN' })
+ * throw new HttpError(409, { message: t('NAME_TAKEN', { name }, `Name ${name} is taken`), code: 'NAME_TAKEN', params: { name } })
  * ```
  */
-declare function useTranslate(ctx?: EventContext): (text: string, params?: Record<string, unknown>) => string;
+declare function useTranslate(ctx?: EventContext): TTranslateFn;
+/**
+ * The translation of the current event (or `ctx`): its locale, a memo key, `t` and the
+ * translated message templates. `undefined` when no translator is registered or the event has
+ * no locale — serve the source texts then.
+ */
+declare function useTranslation(ctx?: EventContext): TTranslation | undefined;
+/**
+ * Returns a translated copy of an error body (`{ message, code?, params?, errors? }`) in the
+ * event's locale — the body itself when there is no translation ({@link useTranslation}).
+ *
+ * - each entry of `errors` (and of its entries' `details`): by its `code` (unless `custom`),
+ *   else by its message text, its English `message` being the fallback;
+ * - the top `message`: by `code` when the body has one; else, when it is the first entry's
+ *   message (`path: message`), the first entry's translation; else by its text.
+ *
+ * `MoostHttp` applies it to every error body when it creates the HTTP app.
+ */
+declare function translateErrorBody<T extends {
+    message: string;
+    code?: string;
+    params?: Record<string, unknown>;
+    errors?: unknown;
+}>(body: T, ctx?: EventContext): T;
 
 /** Creates a new `ProstoLogger` instance with sensible defaults (level 4, colored console). */
 declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogger;
 /** Default colored console transport used by Moost loggers. */
 declare const loggerConsoleTransport: _prostojs_logger.TProstoLoggerTransportFn<any>;
 
-export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, Locale, LoggerTopic, MOOST_ADAPTER_BRAND, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, detachedKind, disposeInstances, forkEventContext, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, getTranslator, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptOriginal, setInterceptResult, setOvertake, setTranslator, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptOriginal, useInterceptResult, useOvertake, useScopeId, useTranslate, withControllerContext };
-export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TDisposeError, TDisposeOptions, TDisposeResult, TEmpty, TForkEventContextOptions, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TIsolatedSlot, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives, TRegistryMergeOptions, TRunDetachedOptions, TTranslate, TTranslateContext, TWithControllerContextOptions };
+export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, Locale, LoggerTopic, MOOST_ADAPTER_BRAND, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, detachedKind, disposeInstances, forkEventContext, formatMessage, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, getTranslator, getTranslatorLocales, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, registerMessages, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptOriginal, setInterceptResult, setOvertake, setTranslator, stampModuleIdentity, stampOnce, translateErrorBody, useControllerContext, useHandlerPaths, useInterceptOriginal, useInterceptResult, useOvertake, useScopeId, useTranslate, useTranslation, withControllerContext };
+export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TControllerRegistration, TControllersGroup, TDisposeError, TDisposeOptions, TDisposeResult, TEmpty, TForkEventContextOptions, TFunction, TGetHandlerPathsOptions, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TIsolatedSlot, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostModuleIdentity, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives, TRegistryMergeOptions, TRunDetachedOptions, TTranslate, TTranslateContext, TTranslation, TTranslations, TTranslatorOptions, TWithControllerContextOptions };

package/dist/index.mjs

@@ -47,7 +47,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.7.2",
+		version: "0.7.4",
 		path: typeof __filename === "string" ? __filename : import.meta.url
 	});
 }
@@ -657,7 +657,7 @@ function formatNewInstanceArg(a) {
 //#endregion
 //#region packages/moost/src/composables/global-key.ts
 var _g;
-const registry$1 = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PURE__ */ new Map());
+const registry = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PURE__ */ new Map());
 /**
 * Creates a typed event-context key that stays a single instance across duplicate
 * moost loads (dual ESM/CJS, or duplicate installs). Use this for every
@@ -665,8 +665,8 @@ const registry$1 = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PU
 *
 * @param name - Debug label AND the registry lookup key; must be unique per slot.
 */ function globalKey(name) {
-	if (!registry$1.has(name)) registry$1.set(name, key$1(name));
-	return registry$1.get(name);
+	if (!registry.has(name)) registry.set(name, key$1(name));
+	return registry.get(name);
 }
 
 //#endregion
@@ -3183,48 +3183,258 @@ function _define_property(obj, key, value) {
 
 //#endregion
 //#region packages/moost/src/i18n.ts
-const TRANSLATOR = Symbol.for("moost.translator");
-const registry = globalThis;
-/**
-* Registers the app's translator (process-wide), or removes it with `undefined`.
-* It takes effect where code calls {@link useTranslate} — your own code and packages that opt
-* in to translating the text they serialise; with no translator registered, text stays as
-* authored.
+var _globalThis, _STATE, _state, _state1, _state2, _state3, _state4;
+const STATE = Symbol.for("moost.i18n");
+const NO_LOCALES = Object.freeze([]);
+/** Distinct scopes given memo keys per generation: keeps every memo keyed by `key` bounded. */ const MAX_SCOPES = 32;
+const state = (_globalThis = globalThis)[_STATE = STATE] ?? (_globalThis[_STATE] = {});
+(_state = state).locales ?? (_state.locales = NO_LOCALES);
+(_state1 = state).generation ?? (_state1.generation = 0);
+(_state2 = state).catalogs ?? (_state2.catalogs = /* @__PURE__ */ new WeakSet());
+(_state3 = state).templates ?? (_state3.templates = /* @__PURE__ */ new Map());
+(_state4 = state).memo ?? (_state4.memo = /* @__PURE__ */ new Map());
+/**
+* Registers the app's translator (process-wide), or removes it with `undefined`: a
+* {@link TTranslate} function or a {@link TTranslations} map. Load your languages before the
+* server listens, or call `setTranslator` again once they are loaded.
+*
+* `opts.locales` lists the locales the app serves, the first being the default (`MoostHttp`
+* negotiates `Accept-Language` against them). For a map they default to its keys — put the
+* source language first: `{ en: {}, de: {…} }`. Give a function translator `locales`, or
+* requests get a locale only from your own `resolveLocale` / `useLocale().set()`.
 *
 * @example
 * ```ts
-* const messages = { de: { 'Name taken': 'Name vergeben' } }
-* setTranslator((text, params, { locale }) => messages[locale ?? '']?.[text])
+* setTranslator({ en: {}, de: { NAME_TAKEN: 'Name {name} ist vergeben' } })
+*
+* setTranslator(
+*   (id, params, { locale }) =>
+*     locale && i18next.exists(id, { lng: locale }) ? i18next.t(id, { ...params, lng: locale }) : undefined,
+*   { locales: ['en', 'de'] },
+* )
 * ```
-*/ function setTranslator(translate) {
-	registry[TRANSLATOR] = translate;
-}
-/** The registered translator, or `undefined` (e.g. to skip a per-locale variant entirely). */ function getTranslator() {
-	return registry[TRANSLATOR];
+*/ function setTranslator(translate, opts) {
+	const isMap = typeof translate === "object";
+	state.translate = isMap ? mapTranslator(translate) : translate;
+	state.scoping = opts?.scope && {
+		translate: state.translate,
+		get: opts.scope
+	};
+	const locales = opts?.locales ?? (isMap ? Object.keys(translate) : void 0);
+	state.locales = translate && locales?.length ? Object.freeze([...locales]) : NO_LOCALES;
+	state.failureLogged = false;
+	state.scopeFailureLogged = false;
+	newGeneration();
+}
+/** The registered translator (a map wrapped as a function), or `undefined`. */ function getTranslator() {
+	return state.translate;
+}
+/** The locales of the registered translator, the default first (empty without a translator). */ function getTranslatorLocales() {
+	return state.locales;
+}
+/**
+* Registers message templates by code (`{ MIN_LENGTH: 'At least {min} characters' }`),
+* process-wide: the English text `useTranslate()` falls back to for the code, and the templates
+* {@link TTranslation.messages} serves translated. Registering the same catalog object again
+* does nothing; a later catalog wins for a code both define. A call that adds or changes a
+* template starts a new generation, like {@link setTranslator} ({@link TTranslation.key}
+* changes).
+*/ function registerMessages(catalog) {
+	if (state.catalogs.has(catalog)) return;
+	state.catalogs.add(catalog);
+	let changed = false;
+	for (const code of Object.keys(catalog)) if (state.templates.get(code) !== catalog[code]) {
+		state.templates.set(code, catalog[code]);
+		changed = true;
+	}
+	if (changed) newGeneration();
+}
+/** Drops everything derived from the translator and the templates. */ function newGeneration() {
+	state.generation++;
+	state.memo.clear();
+}
+const PLACEHOLDER = /\{(\w+)\}/g;
+/**
+* Fills `{name}` placeholders with `params` in one pass (arrays: items joined with `, `).
+* A placeholder without a param stays as it is; filled-in values are never filled again.
+*/ function formatMessage(template, params) {
+	if (!params || !template.includes("{")) return template;
+	return template.replace(PLACEHOLDER, (match, name) => {
+		const value = Object.hasOwn(params, name) ? params[name] : void 0;
+		if (value === void 0) return match;
+		return Array.isArray(value) ? value.map(String).join(", ") : String(value);
+	});
 }
 /**
-* Returns `t(text, params?)` for the current event: the registered translator's result in the
-* event's locale (`useLocale().get()`), else `text` unchanged — never a missing-key marker.
-* With no translator registered, `t` returns `text` (params are not interpolated).
+* Returns `t(id, params?, fallback?)` for the current event (or `ctx`), in the event's locale
+* (`useLocale().get()`). `id` is a code or a source text. `t` returns:
+* - the translator's result, as is (it is final text: params are not filled again);
+* - else `fallback` as is — it is final too, never filled: pass already-filled English text
+*   (e.g. an error's message), or pass no fallback and {@link registerMessages} a template;
+* - else the code's registered template ({@link registerMessages}), or `id` itself, with
+*   `params` filled in ({@link formatMessage}).
 *
 * @example
 * ```ts
 * const t = useTranslate()
-* throw new HttpError(409, { message: t('Name taken'), code: 'NAME_TAKEN' })
+* throw new HttpError(409, { message: t('NAME_TAKEN', { name }, `Name ${name} is taken`), code: 'NAME_TAKEN', params: { name } })
 * ```
 */ function useTranslate(ctx) {
 	const event = ctx ?? current$1();
 	let translateCtx;
-	return (text, params) => {
-		const translate = getTranslator();
-		if (!translate) return text;
-		translateCtx ?? (translateCtx = {
-			locale: useLocale$1(event).get(),
-			event
-		});
-		return translate(text, params, translateCtx) ?? text;
+	return (id, params, fallback) => {
+		const translate = state.translate;
+		return (translate ? callTranslator(translate, id, params, translateCtx ?? (translateCtx = translateContext(event, useLocale$1(event).get(), readScope(event)))) : void 0) ?? untranslated(id, params, fallback);
 	};
 }
+/** `t`'s text without a translation: `fallback` as is, else the filled template (or id). */ function untranslated(id, params, fallback) {
+	return fallback ?? formatMessage(state.templates.get(id) ?? id, params);
+}
+/**
+* The translation of the current event (or `ctx`): its locale, a memo key, `t` and the
+* translated message templates. `undefined` when no translator is registered or the event has
+* no locale — serve the source texts then.
+*/ function useTranslation(ctx) {
+	const translate = state.translate;
+	if (!translate) return;
+	const event = ctx ?? current$1();
+	const locale = useLocale$1(event).get();
+	if (locale === void 0) return;
+	const scope = readScope(event);
+	const translateCtx = translateContext(event, locale, scope);
+	const generation = state.generation;
+	const partition = typeof scope === "string" ? `${locale}:${scope}` : locale;
+	const key = state.locales.includes(locale) && (scope === void 0 || scope !== null && admitted(scope)) ? `${generation}:${partition}` : void 0;
+	const t = (id, params, fallback) => callTranslator(translate, id, params, translateCtx) ?? untranslated(id, params, fallback);
+	const messages = () => {
+		if (key === void 0 || state.generation !== generation) return translateTemplates(translate, translateCtx);
+		let out = state.memo.get(key);
+		if (!out) {
+			out = translateTemplates(translate, translateCtx);
+			state.memo.set(key, out);
+		}
+		return out;
+	};
+	return {
+		locale,
+		partition,
+		key,
+		t,
+		messages
+	};
+}
+function translateContext(event, locale, scope) {
+	return typeof scope === "string" ? {
+		locale,
+		scope,
+		event
+	} : {
+		locale,
+		event
+	};
+}
+/**
+* The event's scope (`opts.scope`): `undefined` without one, `null` when the scope function
+* threw (logged once) — translated unscoped then, and not memoized.
+*/ function readScope(event) {
+	const scoping = state.scoping;
+	if (!scoping || scoping.translate !== state.translate) return;
+	try {
+		const { get } = scoping;
+		const scope = tryGetCurrent() === event ? get() : run$1(event, get);
+		return typeof scope === "string" ? scope : typeof scope === "number" && Number.isFinite(scope) ? String(scope) : void 0;
+	} catch (error) {
+		logOnce("scopeFailureLogged", event, "The translation scope threw — translating unscoped, without memoizing (logged once)", error);
+		return null;
+	}
+}
+/** Whether `scope` gets memo keys: one of the first {@link MAX_SCOPES} of the generation. */ function admitted(scope) {
+	if (state.admittedScopes?.generation !== state.generation) state.admittedScopes = {
+		generation: state.generation,
+		names: /* @__PURE__ */ new Set()
+	};
+	const { names } = state.admittedScopes;
+	if (names.size < MAX_SCOPES) names.add(scope);
+	return names.has(scope);
+}
+/** Logs a failure of the translator or the scope function once per `setTranslator`. */ function logOnce(flag, event, message, error) {
+	if (!state[flag]) {
+		state[flag] = true;
+		useLogger$1("i18n", event).error(message, error);
+	}
+}
+/**
+* Returns a translated copy of an error body (`{ message, code?, params?, errors? }`) in the
+* event's locale — the body itself when there is no translation ({@link useTranslation}).
+*
+* - each entry of `errors` (and of its entries' `details`): by its `code` (unless `custom`),
+*   else by its message text, its English `message` being the fallback;
+* - the top `message`: by `code` when the body has one; else, when it is the first entry's
+*   message (`path: message`), the first entry's translation; else by its text.
+*
+* `MoostHttp` applies it to every error body when it creates the HTTP app.
+*/ function translateErrorBody(body, ctx) {
+	const event = ctx ?? current$1();
+	if (!state.translate || useLocale$1(event).get() === void 0) return body;
+	const t = useTranslate(event);
+	const source = Array.isArray(body.errors) ? body.errors : void 0;
+	const errors = source && translateEntries(source, t);
+	let message;
+	if (typeof body.code === "string" && body.code) message = t(body.code, body.params, body.message);
+	else if (source && errors && isEntry(source[0]) && body.message === topMessage(source[0])) message = topMessage(errors[0]);
+	else message = t(body.message, body.params, body.message);
+	return errors ? {
+		...body,
+		message,
+		errors
+	} : {
+		...body,
+		message
+	};
+}
+function mapTranslator(map) {
+	return (id, params, { locale }) => {
+		const texts = locale !== void 0 && Object.hasOwn(map, locale) ? map[locale] : void 0;
+		return texts && Object.hasOwn(texts, id) ? formatMessage(texts[id], params) : void 0;
+	};
+}
+/** The translator's text, `undefined` if it has none or throws (logged once per `setTranslator`). */ function callTranslator(translate, id, params, ctx) {
+	try {
+		const out = translate(id, params, ctx);
+		return typeof out === "string" ? out : void 0;
+	} catch (error) {
+		logOnce("failureLogged", ctx.event, `The translator threw for "${id}" — using the untranslated text (logged once)`, error);
+		return;
+	}
+}
+/** The registered templates translated with placeholder params, if they differ. */ function translateTemplates(translate, ctx) {
+	const out = {};
+	for (const [code, template] of state.templates) {
+		let params;
+		for (const [placeholder, name] of template.matchAll(PLACEHOLDER)) (params ?? (params = {}))[name] = placeholder;
+		const translated = callTranslator(translate, code, params, ctx);
+		if (translated !== void 0 && translated !== template) out[code] = translated;
+	}
+	return Object.freeze(out);
+}
+function isEntry(value) {
+	return typeof value === "object" && value !== null && typeof value.message === "string";
+}
+function translateEntries(entries, t) {
+	return entries.map((entry) => {
+		if (!isEntry(entry)) return entry;
+		const id = typeof entry.code === "string" && entry.code && entry.custom !== true ? entry.code : entry.message;
+		const out = {
+			...entry,
+			message: t(id, entry.params, entry.message)
+		};
+		if (Array.isArray(entry.details)) out.details = translateEntries(entry.details, t);
+		return out;
+	});
+}
+function topMessage(entry) {
+	return typeof entry.path === "string" && entry.path ? `${entry.path}: ${entry.message}` : entry.message;
+}
 
 //#endregion
-export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, ContextInjector, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, Locale, LoggerTopic, MOOST_ADAPTER_BRAND, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, ProstoLogger, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, cached, clearGlobalWooks, createEventContext, createLogger, createProvideRegistry, createReplaceRegistry, current, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, detachedKind, disposeInstances, eventTypeKey, forkEventContext, getClassKey, getConstructor, getContextInjector, getGlobalWooks, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, getTranslator, globalKey, isConstructor, isThenable, key, loggerConsoleTransport, mergeSorted, registerEventScope, replaceContextInjector, resetContextInjector, resolvePipe, run, setControllerContext, setInfactLoggingOptions, setInterceptOriginal, setInterceptResult, setOvertake, setTranslator, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptOriginal, useInterceptResult, useLocale, useLogger, useOvertake, useScopeId, useTranslate, withControllerContext };
+export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, ContextInjector, Controller, Description, HandlerPaths, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoost, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, Locale, LoggerTopic, MOOST_ADAPTER_BRAND, MOOST_MODULE_IDENTITY_KEY, Moost, MoostDispose, MoostInit, OnError, Optional, Overtake, Param, Params, Pipe, ProstoLogger, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, cached, clearGlobalWooks, createEventContext, createLogger, createProvideRegistry, createReplaceRegistry, current, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, detachedKind, disposeInstances, eventTypeKey, forkEventContext, formatMessage, getClassKey, getConstructor, getContextInjector, getGlobalWooks, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, getTranslator, getTranslatorLocales, globalKey, isConstructor, isThenable, key, loggerConsoleTransport, mergeSorted, registerEventScope, registerMessages, replaceContextInjector, resetContextInjector, resolvePipe, run, setControllerContext, setInfactLoggingOptions, setInterceptOriginal, setInterceptResult, setOvertake, setTranslator, stampModuleIdentity, stampOnce, translateErrorBody, useControllerContext, useHandlerPaths, useInterceptOriginal, useInterceptResult, useLocale, useLogger, useOvertake, useScopeId, useTranslate, useTranslation, withControllerContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moost",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "moost",
   "keywords": [
     "composables",
@@ -41,15 +41,15 @@
     "@prostojs/infact": "^0.6.1",
     "@prostojs/logger": "^0.4.3",
     "@prostojs/mate": "^0.5.1",
-    "@wooksjs/event-core": "^0.8.0",
+    "@wooksjs/event-core": "^0.8.1",
     "hookable": "^5.5.3",
-    "wooks": "^0.8.0"
+    "wooks": "^0.8.1"
   },
   "devDependencies": {
-    "@wooksjs/event-http": "^0.8.0",
-    "@wooksjs/http-body": "^0.8.0",
+    "@wooksjs/event-http": "^0.8.1",
+    "@wooksjs/http-body": "^0.8.1",
     "vitest": "4.1.12",
-    "@moostjs/event-http": "^0.7.2"
+    "@moostjs/event-http": "^0.7.4"
   },
   "scripts": {
     "pub": "pnpm publish --access public",