moost 0.7.3 → 0.7.4

package/dist/index.cjs

@@ -48,7 +48,7 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.7.3",
+		version: "0.7.4",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
@@ -3187,6 +3187,7 @@ function _define_property(obj, key, value) {
 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 +3217,14 @@ 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
+	};
 	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 +3250,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 +3285,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 +3301,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,11 +3318,52 @@ 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}).
@@ -3332,9 +3375,9 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 *
 * `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)();
+	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;
@@ -3361,10 +3404,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;
 	}
 }

package/dist/index.d.ts

@@ -1771,10 +1771,15 @@ 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;
 }
@@ -1792,6 +1797,23 @@ 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;
+}
 /** `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 +1821,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 +1864,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). */
@@ -1901,4 +1929,4 @@ declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogge
 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 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.3",
+		version: "0.7.4",
 		path: typeof __filename === "string" ? __filename : import.meta.url
 	});
 }
@@ -3186,6 +3186,7 @@ function _define_property(obj, key, value) {
 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 +3216,14 @@ 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
+	};
 	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 +3249,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 +3284,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 +3300,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,11 +3317,52 @@ 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}).
@@ -3331,9 +3374,9 @@ const PLACEHOLDER = /\{(\w+)\}/g;
 *
 * `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();
+	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;
@@ -3360,10 +3403,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;
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moost",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "moost",
   "keywords": [
     "composables",
@@ -49,7 +49,7 @@
     "@wooksjs/event-http": "^0.8.1",
     "@wooksjs/http-body": "^0.8.1",
     "vitest": "4.1.12",
-    "@moostjs/event-http": "^0.7.3"
+    "@moostjs/event-http": "^0.7.4"
   },
   "scripts": {
     "pub": "pnpm publish --access public",