moost 0.7.3 → 0.7.5

package/dist/index.cjs

@@ -48,7 +48,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.7.3",
+		version: "0.7.5",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
@@ -3182,11 +3182,44 @@ function _define_property(obj, key, value) {
 	return getHandlerPaths(moost, getController(), method ?? getMethod() ?? "", opts);
 }
 
+//#endregion
+//#region packages/moost/src/wooks-owner.ts
+/** Per Wooks instance: the first claim of each adapter (by `name`) bound into it. */ const owners = /* @__PURE__ */ new WeakMap();
+/** Wooks instances already warned about: the warning is logged once per instance. */ const warned = /* @__PURE__ */ new WeakSet();
+/**
+* Records that `app` binds the handlers of its `adapter` (the adapter's `name`) into `wooks`
+* (the Wooks instance its routes go to: `wooksApp.getWooks()`). Adapters call it from `onInit`.
+*
+* Adapters created without a Wooks app of their own share the process-wide global Wooks, so two
+* apps in one process (typically in tests) route through one router. When another app already
+* bound handlers of the same adapter into `wooks`, and either adapter created its Wooks app
+* (`opts.created`), it warns — once per Wooks instance, with the app's logger. Apps that share
+* a Wooks app they pass in on purpose stay silent; re-initialising the same app does not warn.
+* A disposed app still counts: `dispose()` does not remove its routes.
+*/ function claimWooks(app, wooks, adapter, opts) {
+	const created = opts?.created === true;
+	let byAdapter = owners.get(wooks);
+	if (!byAdapter) {
+		byAdapter = /* @__PURE__ */ new Map();
+		owners.set(wooks, byAdapter);
+	}
+	const owner = byAdapter.get(adapter);
+	if (owner === void 0) byAdapter.set(adapter, {
+		app,
+		created
+	});
+	else if (owner.app !== app && (created || owner.created) && !warned.has(wooks)) {
+		warned.add(wooks);
+		app.getLogger().warn(`[moost] A second Moost app binds "${adapter}" handlers into the Wooks instance another app already uses (adapters created without their own Wooks app share the process-wide global one). Both apps' routes now live in one router: an event on a route both register runs the first app's handler chain, and when that throws, its error is swallowed and the next app's chain runs instead. Call clearGlobalWooks() before creating each app (e.g. in a test's beforeEach): the next adapter then gets a fresh Wooks. (Logged once per Wooks instance.)`);
+	}
+}
+
 //#endregion
 //#region packages/moost/src/i18n.ts
 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);
@@ -3216,9 +3249,15 @@ const state = (_globalThis = globalThis)[_STATE = STATE] ?? (_globalThis[_STATE]
 */ 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
+	};
+	state.noPathPrefix = opts?.pathPrefix === false ? state.translate : void 0;
 	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() {
@@ -3244,7 +3283,7 @@ const state = (_globalThis = globalThis)[_STATE = STATE] ?? (_globalThis[_STATE]
 	}
 	if (changed) newGeneration();
 }
-/** The only invalidation: drops everything derived from the translator and the templates. */ function newGeneration() {
+/** Drops everything derived from the translator and the templates. */ function newGeneration() {
 	state.generation++;
 	state.memo.clear();
 }
@@ -3279,10 +3318,7 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 	let translateCtx;
 	return (id, params, fallback) => {
 		const translate = state.translate;
-		return (translate ? callTranslator(translate, id, params, translateCtx ?? (translateCtx = {
-			locale: (0, _wooksjs_event_core.useLocale)(event).get(),
-			event
-		})) : void 0) ?? untranslated(id, params, fallback);
+		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) {
@@ -3298,12 +3334,11 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 	const event = ctx ?? (0, _wooksjs_event_core.current)();
 	const locale = (0, _wooksjs_event_core.useLocale)(event).get();
 	if (locale === void 0) return;
-	const translateCtx = {
-		locale,
-		event
-	};
+	const scope = readScope(event);
+	const translateCtx = translateContext(event, locale, scope);
 	const generation = state.generation;
-	const key = state.locales.includes(locale) ? `${generation}:${locale}` : void 0;
+	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);
@@ -3316,31 +3351,82 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 	};
 	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.
+*   else by its message text, its English `message` being the fallback; the translator gets the
+*   entry's `path`, `code` and `custom` ({@link TTranslateContext});
+* - the top `message`: by `code` when the body has one (the translator gets that `code`); else,
+*   when it is the first entry's message (`path: message`), the first entry's translation
+*   (`path: ` dropped with `setTranslator(t, { pathPrefix: false })`); else by its text.
 *
 * `MoostHttp` applies it to every error body when it creates the HTTP app.
 */ function translateErrorBody(body, ctx) {
-	const translation = useTranslation(ctx);
-	if (!translation) return body;
-	const { t } = translation;
+	const event = ctx ?? (0, _wooksjs_event_core.current)();
+	const translate = state.translate;
+	const locale = (0, _wooksjs_event_core.useLocale)(event).get();
+	if (!translate || locale === void 0) return body;
+	const base = translateContext(event, locale, readScope(event));
+	const t = (id, params, fallback, entry) => callTranslator(translate, id, params, entry ? entryContext(base, entry) : base) ?? untranslated(id, params, fallback);
 	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);
+	if (typeof body.code === "string" && body.code) message = callTranslator(translate, body.code, body.params, {
+		...base,
+		code: body.code
+	}) ?? untranslated(body.code, body.params, body.message);
+	else if (source && errors && isEntry(source[0]) && body.message === topMessage(source[0])) {
+		const first = errors[0];
+		message = state.noPathPrefix === translate ? first.message : topMessage(first);
+	} else message = t(body.message, body.params, body.message);
 	return errors ? {
 		...body,
 		message,
@@ -3361,10 +3447,7 @@ function mapTranslator(map) {
 		const out = translate(id, params, ctx);
 		return typeof out === "string" ? out : void 0;
 	} catch (error) {
-		if (!state.failureLogged) {
-			state.failureLogged = true;
-			(0, _wooksjs_event_core.useLogger)("i18n", ctx.event).error(`The translator threw for "${id}" — using the untranslated text (logged once)`, error);
-		}
+		logOnce("failureLogged", ctx.event, `The translator threw for "${id}" — using the untranslated text (logged once)`, error);
 		return;
 	}
 }
@@ -3381,13 +3464,22 @@ function mapTranslator(map) {
 function isEntry(value) {
 	return typeof value === "object" && value !== null && typeof value.message === "string";
 }
+/** `base` with the entry's `path` and `code` (each only when a string) and `custom: true`. */ function entryContext(base, { path, code, custom }) {
+	const hasCode = typeof code === "string" && code !== "";
+	if (typeof path !== "string" && !hasCode && custom !== true) return base;
+	const out = { ...base };
+	if (typeof path === "string") out.path = path;
+	if (hasCode) out.code = code;
+	if (custom === true) out.custom = true;
+	return out;
+}
 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)
+			message: t(id, entry.params, entry.message, entry)
 		};
 		if (Array.isArray(entry.details)) out.details = translateEntries(entry.details, t);
 		return out;
@@ -3460,6 +3552,7 @@ Object.defineProperty(exports, 'cached', {
     return _wooksjs_event_core.cached;
   }
 });
+exports.claimWooks = claimWooks;
 Object.defineProperty(exports, 'clearGlobalWooks', {
   enumerable: true,
   get: function () {

package/dist/index.d.ts

@@ -1649,6 +1649,27 @@ declare function mergeSorted<T extends {
     priority: number;
 }>(...lists: (T[] | readonly T[] | undefined)[]): T[];
 
+/** The options of {@link claimWooks}. */
+interface TClaimWooksOptions {
+    /**
+     * The adapter created its Wooks app itself (none was passed in), so it routes through the
+     * process-wide global Wooks. Default `false`: an app passed in — sharing it is deliberate.
+     */
+    created?: boolean;
+}
+/**
+ * Records that `app` binds the handlers of its `adapter` (the adapter's `name`) into `wooks`
+ * (the Wooks instance its routes go to: `wooksApp.getWooks()`). Adapters call it from `onInit`.
+ *
+ * Adapters created without a Wooks app of their own share the process-wide global Wooks, so two
+ * apps in one process (typically in tests) route through one router. When another app already
+ * bound handlers of the same adapter into `wooks`, and either adapter created its Wooks app
+ * (`opts.created`), it warns — once per Wooks instance, with the app's logger. Apps that share
+ * a Wooks app they pass in on purpose stay silent; re-initialising the same app does not warn.
+ * A disposed app still counts: `dispose()` does not remove its routes.
+ */
+declare function claimWooks(app: Moost, wooks: object, adapter: string, opts?: TClaimWooksOptions): void;
+
 /**
  * Sets the controller context for the current event scope.
  * Called internally by adapters when dispatching events to handlers.
@@ -1771,12 +1792,40 @@ 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 —
+ * plus, when an error body is translated ({@link translateErrorBody}), the entry's `path` and
+ * `code`.
+ */
 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 field path (`'items.0.name'`, `''` for the root) of the error entry being
+     * translated — word a message per field. Only set by {@link translateErrorBody}, for its
+     * `errors` entries (and their `details`); error bodies are never memoized, while the memoized
+     * {@link TTranslation.messages} never carry a path.
+     */
+    path?: string;
+    /**
+     * The code of the error entry (or error body) being translated — also when `text` is the
+     * entry's own message (an entry marked `custom`, or one translated by its text). Only set by
+     * {@link translateErrorBody}.
+     */
+    code?: string;
+    /**
+     * `true` when the error entry carries the app's own message (`custom: true`, e.g. from
+     * `@expect.message`): `text` is that message — keep it unless you translate it as text. Only
+     * set by {@link translateErrorBody}.
+     */
+    custom?: boolean;
 }
 /**
  * The app's translator. `text` is a message id: an error/message code (`WF_EXPIRED`,
@@ -1792,6 +1841,30 @@ type TTranslate = (text: string, params: Record<string, unknown> | undefined, ct
  * 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;
+    /**
+     * `false`: a translated error body's top `message` that repeats its first entry is just that
+     * entry's text, without the `path: ` prefix ({@link translateErrorBody}) — also when the entry
+     * has no translation (its English text). Bodies of events without a locale are not touched.
+     * Default `true`: `path: <translated>`, like the untranslated message.
+     */
+    pathPrefix?: boolean;
+}
 /** `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}. */
@@ -1799,9 +1872,17 @@ interface TTranslation {
     /** The event's locale. */
     locale: string;
     /**
-     * A memo key for anything derived from this translation: 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` — don't memoize then.
+     * 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. */
@@ -1834,9 +1915,7 @@ interface TTranslation {
  * )
  * ```
  */
-declare function setTranslator(translate: TTranslate | TTranslations | undefined, opts?: {
-    locales?: readonly string[];
-}): void;
+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;
 /** The locales of the registered translator, the default first (empty without a translator). */
@@ -1882,9 +1961,11 @@ declare function useTranslation(ctx?: EventContext): TTranslation | undefined;
  * 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.
+ *   else by its message text, its English `message` being the fallback; the translator gets the
+ *   entry's `path`, `code` and `custom` ({@link TTranslateContext});
+ * - the top `message`: by `code` when the body has one (the translator gets that `code`); else,
+ *   when it is the first entry's message (`path: message`), the first entry's translation
+ *   (`path: ` dropped with `setTranslator(t, { pathPrefix: false })`); else by its text.
  *
  * `MoostHttp` applies it to every error body when it creates the HTTP app.
  */
@@ -1900,5 +1981,5 @@ declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogge
 /** 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, 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, 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, claimWooks, 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, TClaimWooksOptions, 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.3",
+		version: "0.7.5",
 		path: typeof __filename === "string" ? __filename : import.meta.url
 	});
 }
@@ -3181,11 +3181,44 @@ function _define_property(obj, key, value) {
 	return getHandlerPaths(moost, getController(), method ?? getMethod() ?? "", opts);
 }
 
+//#endregion
+//#region packages/moost/src/wooks-owner.ts
+/** Per Wooks instance: the first claim of each adapter (by `name`) bound into it. */ const owners = /* @__PURE__ */ new WeakMap();
+/** Wooks instances already warned about: the warning is logged once per instance. */ const warned = /* @__PURE__ */ new WeakSet();
+/**
+* Records that `app` binds the handlers of its `adapter` (the adapter's `name`) into `wooks`
+* (the Wooks instance its routes go to: `wooksApp.getWooks()`). Adapters call it from `onInit`.
+*
+* Adapters created without a Wooks app of their own share the process-wide global Wooks, so two
+* apps in one process (typically in tests) route through one router. When another app already
+* bound handlers of the same adapter into `wooks`, and either adapter created its Wooks app
+* (`opts.created`), it warns — once per Wooks instance, with the app's logger. Apps that share
+* a Wooks app they pass in on purpose stay silent; re-initialising the same app does not warn.
+* A disposed app still counts: `dispose()` does not remove its routes.
+*/ function claimWooks(app, wooks, adapter, opts) {
+	const created = opts?.created === true;
+	let byAdapter = owners.get(wooks);
+	if (!byAdapter) {
+		byAdapter = /* @__PURE__ */ new Map();
+		owners.set(wooks, byAdapter);
+	}
+	const owner = byAdapter.get(adapter);
+	if (owner === void 0) byAdapter.set(adapter, {
+		app,
+		created
+	});
+	else if (owner.app !== app && (created || owner.created) && !warned.has(wooks)) {
+		warned.add(wooks);
+		app.getLogger().warn(`[moost] A second Moost app binds "${adapter}" handlers into the Wooks instance another app already uses (adapters created without their own Wooks app share the process-wide global one). Both apps' routes now live in one router: an event on a route both register runs the first app's handler chain, and when that throws, its error is swallowed and the next app's chain runs instead. Call clearGlobalWooks() before creating each app (e.g. in a test's beforeEach): the next adapter then gets a fresh Wooks. (Logged once per Wooks instance.)`);
+	}
+}
+
 //#endregion
 //#region packages/moost/src/i18n.ts
 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);
@@ -3215,9 +3248,15 @@ const state = (_globalThis = globalThis)[_STATE = STATE] ?? (_globalThis[_STATE]
 */ 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
+	};
+	state.noPathPrefix = opts?.pathPrefix === false ? state.translate : void 0;
 	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() {
@@ -3243,7 +3282,7 @@ const state = (_globalThis = globalThis)[_STATE = STATE] ?? (_globalThis[_STATE]
 	}
 	if (changed) newGeneration();
 }
-/** The only invalidation: drops everything derived from the translator and the templates. */ function newGeneration() {
+/** Drops everything derived from the translator and the templates. */ function newGeneration() {
 	state.generation++;
 	state.memo.clear();
 }
@@ -3278,10 +3317,7 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 	let translateCtx;
 	return (id, params, fallback) => {
 		const translate = state.translate;
-		return (translate ? callTranslator(translate, id, params, translateCtx ?? (translateCtx = {
-			locale: useLocale$1(event).get(),
-			event
-		})) : void 0) ?? untranslated(id, params, fallback);
+		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) {
@@ -3297,12 +3333,11 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 	const event = ctx ?? current$1();
 	const locale = useLocale$1(event).get();
 	if (locale === void 0) return;
-	const translateCtx = {
-		locale,
-		event
-	};
+	const scope = readScope(event);
+	const translateCtx = translateContext(event, locale, scope);
 	const generation = state.generation;
-	const key = state.locales.includes(locale) ? `${generation}:${locale}` : void 0;
+	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);
@@ -3315,31 +3350,82 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 	};
 	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.
+*   else by its message text, its English `message` being the fallback; the translator gets the
+*   entry's `path`, `code` and `custom` ({@link TTranslateContext});
+* - the top `message`: by `code` when the body has one (the translator gets that `code`); else,
+*   when it is the first entry's message (`path: message`), the first entry's translation
+*   (`path: ` dropped with `setTranslator(t, { pathPrefix: false })`); else by its text.
 *
 * `MoostHttp` applies it to every error body when it creates the HTTP app.
 */ function translateErrorBody(body, ctx) {
-	const translation = useTranslation(ctx);
-	if (!translation) return body;
-	const { t } = translation;
+	const event = ctx ?? current$1();
+	const translate = state.translate;
+	const locale = useLocale$1(event).get();
+	if (!translate || locale === void 0) return body;
+	const base = translateContext(event, locale, readScope(event));
+	const t = (id, params, fallback, entry) => callTranslator(translate, id, params, entry ? entryContext(base, entry) : base) ?? untranslated(id, params, fallback);
 	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);
+	if (typeof body.code === "string" && body.code) message = callTranslator(translate, body.code, body.params, {
+		...base,
+		code: body.code
+	}) ?? untranslated(body.code, body.params, body.message);
+	else if (source && errors && isEntry(source[0]) && body.message === topMessage(source[0])) {
+		const first = errors[0];
+		message = state.noPathPrefix === translate ? first.message : topMessage(first);
+	} else message = t(body.message, body.params, body.message);
 	return errors ? {
 		...body,
 		message,
@@ -3360,10 +3446,7 @@ function mapTranslator(map) {
 		const out = translate(id, params, ctx);
 		return typeof out === "string" ? out : void 0;
 	} catch (error) {
-		if (!state.failureLogged) {
-			state.failureLogged = true;
-			useLogger$1("i18n", ctx.event).error(`The translator threw for "${id}" — using the untranslated text (logged once)`, error);
-		}
+		logOnce("failureLogged", ctx.event, `The translator threw for "${id}" — using the untranslated text (logged once)`, error);
 		return;
 	}
 }
@@ -3380,13 +3463,22 @@ function mapTranslator(map) {
 function isEntry(value) {
 	return typeof value === "object" && value !== null && typeof value.message === "string";
 }
+/** `base` with the entry's `path` and `code` (each only when a string) and `custom: true`. */ function entryContext(base, { path, code, custom }) {
+	const hasCode = typeof code === "string" && code !== "";
+	if (typeof path !== "string" && !hasCode && custom !== true) return base;
+	const out = { ...base };
+	if (typeof path === "string") out.path = path;
+	if (hasCode) out.code = code;
+	if (custom === true) out.custom = true;
+	return out;
+}
 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)
+			message: t(id, entry.params, entry.message, entry)
 		};
 		if (Array.isArray(entry.details)) out.details = translateEntries(entry.details, t);
 		return out;
@@ -3397,4 +3489,4 @@ function topMessage(entry) {
 }
 
 //#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, 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 };
+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, claimWooks, 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.3",
+  "version": "0.7.5",
   "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.1",
+    "@wooksjs/event-core": "^0.8.2",
     "hookable": "^5.5.3",
-    "wooks": "^0.8.1"
+    "wooks": "^0.8.2"
   },
   "devDependencies": {
-    "@wooksjs/event-http": "^0.8.1",
-    "@wooksjs/http-body": "^0.8.1",
+    "@wooksjs/event-http": "^0.8.2",
+    "@wooksjs/http-body": "^0.8.2",
     "vitest": "4.1.12",
-    "@moostjs/event-http": "^0.7.3"
+    "@moostjs/event-http": "^0.7.5"
   },
   "scripts": {
     "pub": "pnpm publish --access public",