moost 0.6.52 → 0.7.0

package/dist/index.cjs

@@ -48,12 +48,24 @@ let stamped = false;
 	if (stamped) return;
 	stamped = true;
 	stampModuleIdentity({
-		version: "0.6.52",
+		version: "0.7.0",
 		path: typeof __filename === "string" ? __filename : require("url").pathToFileURL(__filename).href
 	});
 }
 stampOnce();
 
+//#endregion
+//#region packages/moost/src/announce.ts
+/**
+* @internal Tells the context injector (instrumentation, e.g. OpenTelemetry) which handler an
+* event runs: `Handler:routed` with its `route` (when the adapter's router did not already),
+* then `Controller:registered` once the controller context is set.
+*/ function announceHandler(ci, kind, route) {
+	if (!ci) return;
+	if (route !== void 0) ci.hook(kind, "Handler:routed", route);
+	ci.hook(kind, "Controller:registered");
+}
+
 //#endregion
 //#region packages/moost/src/adapter-brand.ts
 /**
@@ -572,7 +584,7 @@ function formatNewInstanceArg(a) {
 //#endregion
 //#region packages/moost/src/composables/global-key.ts
 var _g;
-const registry = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PURE__ */ new Map());
+const registry$1 = (_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
@@ -580,8 +592,8 @@ const registry = (_g = globalThis).__moost_keys ?? (_g.__moost_keys = /* @__PURE
 *
 * @param name - Debug label AND the registry lookup key; must be unique per slot.
 */ function globalKey(name) {
-	if (!registry.has(name)) registry.set(name, (0, _wooksjs_event_core.key)(name));
-	return registry.get(name);
+	if (!registry$1.has(name)) registry$1.set(name, (0, _wooksjs_event_core.key)(name));
+	return registry$1.get(name);
 }
 
 //#endregion
@@ -664,6 +676,7 @@ const controllerContextKey = globalKey("controller.context");
 //#region packages/moost/src/composables/interceptor.composable.ts
 const overtakeKey = globalKey("interceptor.overtake");
 const interceptResultKey = globalKey("interceptor.result");
+const interceptOriginalKey = globalKey("interceptor.original");
 /** Stores the overtake (reply) function in the current event context. */ function setOvertake(fn, ctx) {
 	(ctx || (0, _wooksjs_event_core.current)()).set(overtakeKey, fn);
 }
@@ -673,9 +686,22 @@ const interceptResultKey = globalKey("interceptor.result");
 /** Stores the interceptor result value in the current event context. */ function setInterceptResult(value, ctx) {
 	(ctx || (0, _wooksjs_event_core.current)()).set(interceptResultKey, value);
 }
-/** Retrieves the interceptor result value from the current event context. */ function useInterceptResult(ctx) {
+/**
+* Retrieves the interceptor result value from the current event context: in an after/error
+* hook, the CURRENT value of the chain — the handler result or error as replaced by the
+* hooks that ran before this one.
+*/ function useInterceptResult(ctx) {
 	return (ctx || (0, _wooksjs_event_core.current)()).get(interceptResultKey);
 }
+/** Stores the value that entered the after/error chain in the current event context. */ function setInterceptOriginal(value, ctx) {
+	(ctx || (0, _wooksjs_event_core.current)()).set(interceptOriginalKey, value);
+}
+/**
+* In an after/error hook: the value that entered the after/error chain — the handler result,
+* the error it raised, or a before hook's reply — before any hook replaced it.
+*/ function useInterceptOriginal(ctx) {
+	return (ctx || (0, _wooksjs_event_core.current)()).get(interceptOriginalKey);
+}
 
 //#endregion
 //#region packages/moost/src/adapter-utils.ts
@@ -772,7 +798,7 @@ const noop = () => {};
 		function afterInstance(instance) {
 			if (instance) {
 				setControllerContext(instance, options.controllerMethod || "", options.targetPath, { prefix: options.controllerPrefix });
-				ci?.hook(options.handlerType, "Controller:registered");
+				announceHandler(ci, options.handlerType);
 			}
 			interceptorHandler = options.getIterceptorHandler();
 			if (interceptorHandler?.count) try {
@@ -837,21 +863,17 @@ const noop = () => {};
 			return cleanup();
 		}
 		function cleanup() {
-			if (interceptorHandler?.countAfter || interceptorHandler?.countOnError) {
-				const raisedResponse = response;
-				const afterResult = ci ? ci.with("Interceptors:after", () => interceptorHandler?.fireAfter(response)) : interceptorHandler?.fireAfter(response);
-				if (isThenable(afterResult)) return afterResult.then((r) => {
-					response = r;
-					if (raise && response !== raisedResponse) raise = false;
-					return finalize();
-				}, (error) => {
-					if (options.logErrors) getLogger().error(String(error));
-					throw error;
-				});
-				response = afterResult;
-				if (raise && response !== raisedResponse) raise = false;
-			}
-			return finalize();
+			const handler = interceptorHandler;
+			if (!handler?.countHooks) return finalize();
+			const original = response;
+			const settle = () => {
+				response = handler.response;
+				if (handler.raised && response !== original && options.logErrors) getLogger().error(String(response));
+				raise = handler.raised;
+				return finalize();
+			};
+			const chain = ci ? ci.with("Interceptors:after", () => handler.fireAfter(original, raise)) : handler.fireAfter(original, raise);
+			return isThenable(chain) ? chain.then(settle) : settle();
 		}
 		function finalize() {
 			releaseLifecycle();
@@ -981,7 +1003,7 @@ const disposeSymbol = typeof Symbol.dispose === "symbol" ? Symbol.dispose : void
 	}] : [];
 }
 async function runHook(hook, errors, opts) {
-	const fn = hook.instance[hook.method];
+	const fn = hook.fn ?? hook.instance[hook.method];
 	try {
 		await fn.call(hook.instance);
 	} catch (error) {
@@ -1009,7 +1031,13 @@ async function runHook(hook, errors, opts) {
 *
 * Instances already disposed (by an earlier call, or by `Moost.dispose()`) are
 * skipped, so passing overlapping sets is safe.
-*/ async function disposeInstances(instances, opts) {
+*/ function disposeInstances(instances, opts) {
+	return disposeWithHooks(instances, [], opts);
+}
+/**
+* @internal {@link disposeInstances} plus function hooks, all in one pass by ascending
+* `priority` (instance hooks first on ties).
+*/ async function disposeWithHooks(instances, fnHooks, opts) {
 	const hooks = [];
 	const disposed = [];
 	for (const instance of instances) {
@@ -1021,6 +1049,7 @@ async function runHook(hook, errors, opts) {
 			hooks.push(...own);
 		}
 	}
+	hooks.push(...fnHooks);
 	const errors = [];
 	for (const hook of hooks.toSorted((a, b) => a.priority - b.priority)) await runHook(hook, errors, opts);
 	if (opts?.onError === "throw" && errors.length > 0) throw new AggregateError(errors.map((e) => e.error), formatDisposeErrors(errors));
@@ -1262,6 +1291,19 @@ function ImportController(prefix, controller, provide) {
 	return getMoostMate().apply(getMoostMate().decorate("paramSource", "ROUTE"), Resolve(() => (0, _wooksjs_event_core.useRouteParams)().params, "params"));
 }
 /**
+* Get the locale of the current event (`useLocale().get()`), for any event kind.
+*
+* Moost only carries the locale: the app decides how it is chosen (for HTTP, the
+* `resolveLocale` option of `MoostHttp`, typically with `useAcceptLanguage().negotiate()`;
+* or `useLocale().set()` in an interceptor) and how text is translated (see `setTranslator`).
+* A workflow or other child event reads the locale of the event that started it.
+* Resolves `undefined` when no locale is set.
+* @decorator
+* @paramType string | undefined
+*/ function Locale() {
+	return Resolve(() => (0, _wooksjs_event_core.useLocale)().get(), "locale");
+}
+/**
 * Provide Const Value
 * @decorator
 * @param value - provided value
@@ -1449,8 +1491,11 @@ var TInterceptorPriority = /* @__PURE__ */ function(TInterceptorPriority) {
 * ## @After
 * ### Method Decorator
 * Marks a method as an after-phase interceptor hook.
-* Runs after successful handler execution.
-* Use @Response() param for the handler result, @Overtake() for the reply fn.
+* Runs when the current value of the after/error chain is not an Error.
+* Use @Response() param for the current value, @Overtake() for the reply fn,
+* `useInterceptOriginal()` for the value that entered the chain.
+* Throwing (or replying with an Error) hands the error to the error hooks
+* of the interceptors that run after this one.
 */ function After() {
 	return getMoostMate().decorate("interceptorHook", "after");
 }
@@ -1458,8 +1503,10 @@ var TInterceptorPriority = /* @__PURE__ */ function(TInterceptorPriority) {
 * ## @OnError
 * ### Method Decorator
 * Marks a method as an error-phase interceptor hook.
-* Runs when the handler throws or returns an Error.
-* Use @Response() param for the error, @Overtake() for the reply fn.
+* Runs when the current value of the after/error chain is an Error — the handler
+* threw or returned one, or an earlier after/error hook raised or replied one.
+* Use @Response() param for the error, @Overtake() for the reply fn
+* (a non-Error reply recovers the chain).
 */ function OnError() {
 	return getMoostMate().decorate("interceptorHook", "error");
 }
@@ -1474,9 +1521,9 @@ var TInterceptorPriority = /* @__PURE__ */ function(TInterceptorPriority) {
 /**
 * ## @Response
 * ### Parameter Decorator
-* Injects the handler result into an interceptor method parameter.
-* In @After methods, this is the successful response.
-* In @OnError methods, this is the Error that was thrown.
+* Injects the current value of the after/error chain into an interceptor method parameter:
+* the handler result (or error) as replaced by the hooks that ran before this one.
+* In @After methods, this is the response; in @OnError methods, the Error.
 */ function Response() {
 	return Resolve(() => useInterceptResult(), "response");
 }
@@ -1751,28 +1798,23 @@ const ON_ERROR_STAGE = { "moost.interceptor.stage": "onError" };
 		return this._boundReplyFn ?? (this._boundReplyFn = (reply) => {
 			this.response = reply;
 			this.responseOverwritten = true;
+			if (!(reply instanceof Error)) this.raised = false;
 		});
 	}
 	get count() {
 		return this.handlers.length;
 	}
-	get countAfter() {
-		return this.after?.length ?? 0;
-	}
-	get countOnError() {
-		return this.onError?.length ?? 0;
+	/** Number of registered interceptors with an after and/or error hook. */ get countHooks() {
+		return this.hooks?.length ?? 0;
 	}
 	/**
 	* Register hooks from a TInterceptorDef.
 	* Returns a pending PromiseLike if `before` went async, or undefined.
 	*/ registerDef(def, entry, ci) {
-		if (def.after) (this.after ?? (this.after = [])).unshift({
+		if (def.after || def.error) (this.hooks ?? (this.hooks = [])).unshift({
 			spanName: entry.spanName,
-			fn: def.after
-		});
-		if (def.error) (this.onError ?? (this.onError = [])).unshift({
-			spanName: entry.spanName,
-			fn: def.error
+			after: def.after,
+			error: def.error
 		});
 		if (def.before) {
 			const result = ci ? ci.with(entry.spanName, BEFORE_STAGE, () => def.before?.(this.getReplyFn())) : def.before(this.getReplyFn());
@@ -1822,39 +1864,68 @@ const ON_ERROR_STAGE = { "moost.interceptor.stage": "onError" };
 			if (this.responseOverwritten) return this.response;
 		}
 	}
-	fireAfter(response) {
+	/**
+	* Runs the after/error hooks as ONE chain over the current value, innermost interceptor
+	* first. Each hook sees the current value (the previous hook's reply) and the `original`
+	* value that entered the chain: a raised value or an `Error` runs the hook's `error` fn,
+	* anything else its `after` fn. A hook that throws (anything), or replies with an `Error`,
+	* switches the rest of the chain to error mode; a non-Error reply recovers it.
+	*
+	* `raised` tells whether `response` was thrown (by the handler or a before hook) rather than
+	* returned; read {@link raised} afterwards for the final value's state.
+	*/ fireAfter(response, raised = false) {
 		this.response = response;
-		const isError = response instanceof Error;
-		const handlers = isError ? this.onError : this.after;
-		if (!handlers) return this.response;
+		this.raised = raised;
+		const hooks = this.hooks;
+		if (!hooks) return response;
 		const ci = (0, _wooksjs_event_core.getContextInjector)();
-		const stage = isError ? ON_ERROR_STAGE : AFTER_STAGE;
-		for (let i = 0; i < handlers.length; i++) {
-			const { spanName, fn } = handlers[i];
-			const result = ci ? ci.with(spanName, stage, () => fn(response, this.getReplyFn())) : fn(response, this.getReplyFn());
-			if (isThenable(result)) return this._fireAfterAsync({
-				ci,
-				handlers,
-				stage,
-				response
-			}, result, i);
+		for (let i = 0; i < hooks.length; i++) {
+			const pending = this.runHook(ci, hooks[i], response);
+			if (pending) return this._fireAfterAsync(ci, response, pending, i);
 		}
 		return this.response;
 	}
-	async _fireAfterAsync(ctx, pending, startIndex) {
-		await pending;
-		for (let i = startIndex + 1; i < ctx.handlers.length; i++) {
-			const { spanName, fn } = ctx.handlers[i];
-			if (ctx.ci) await ctx.ci.with(spanName, ctx.stage, () => fn(ctx.response, this.getReplyFn()));
-			else await fn(ctx.response, this.getReplyFn());
+	/**
+	* Runs one interceptor's hook for the current value: its `error` fn while the chain is in
+	* error mode (a raised value — even a thrown non-Error — or an `Error`), else its `after` fn.
+	* A sync throw switches the chain to error mode; an async hook's promise is returned for the
+	* caller to await (its rejection switches to error mode there).
+	*/ runHook(ci, hook, original) {
+		const value = this.response;
+		const isError = this.raised || value instanceof Error;
+		const fn = isError ? hook.error : hook.after;
+		if (!fn) return;
+		let result;
+		try {
+			result = ci ? ci.with(hook.spanName, isError ? ON_ERROR_STAGE : AFTER_STAGE, () => fn(value, this.getReplyFn(), original)) : fn(value, this.getReplyFn(), original);
+		} catch (error) {
+			this.raise(error);
+			return;
+		}
+		return isThenable(result) ? result : void 0;
+	}
+	/** A hook threw: the error becomes the current value, raised. */ raise(error) {
+		this.response = error;
+		this.raised = true;
+	}
+	async _fireAfterAsync(ci, original, pending, startIndex) {
+		const hooks = this.hooks;
+		let current = pending;
+		for (let i = startIndex + 1;; i++) {
+			if (current) try {
+				await current;
+			} catch (error) {
+				this.raise(error);
+			}
+			if (i >= hooks.length) return this.response;
+			current = this.runHook(ci, hooks[i], original);
 		}
-		return this.response;
 	}
 	constructor(handlers) {
 		this.handlers = handlers;
-		this.after = void 0;
-		this.onError = void 0;
+		this.hooks = void 0;
 		this.response = void 0;
+		this.raised = false;
 		this.responseOverwritten = false;
 		this._boundReplyFn = void 0;
 	}
@@ -1919,18 +1990,22 @@ function createClassInterceptorFactory(opts) {
 		if (opts.methods.after) {
 			const methodName = opts.methods.after;
 			const resolveArgs = opts.resolvers[methodName];
-			def.after = (response, reply) => {
-				setOvertake(reply);
-				setInterceptResult(response);
+			def.after = (response, reply, original) => {
+				const ctx = (0, _wooksjs_event_core.current)();
+				setOvertake(reply, ctx);
+				setInterceptResult(response, ctx);
+				setInterceptOriginal(original, ctx);
 				return callMethod(instance, methodName, resolveArgs);
 			};
 		}
 		if (opts.methods.error) {
 			const methodName = opts.methods.error;
 			const resolveArgs = opts.resolvers[methodName];
-			def.error = (error, reply) => {
-				setOvertake(reply);
-				setInterceptResult(error);
+			def.error = (error, reply, original) => {
+				const ctx = (0, _wooksjs_event_core.current)();
+				setOvertake(reply, ctx);
+				setInterceptResult(error, ctx);
+				setInterceptOriginal(original, ctx);
 				return callMethod(instance, methodName, resolveArgs);
 			};
 		}
@@ -2306,6 +2381,10 @@ function _define_property(obj, key, value) {
 	return obj;
 }
 /**
+* Event kind of a run started with {@link Moost.runDetached} (`eventTypeKey` = `'DETACHED'`).
+* Its own event, with no request: HTTP composables are not available inside.
+*/ const detachedKind = (0, _wooksjs_event_core.defineEventKind)("DETACHED", {});
+/**
 * Detects the object registration form of `registerControllers`: a plain
 * object (no class prototype) carrying a `controllers` array. Controller
 * instances are class instances and never match, so all pre-existing
@@ -2520,6 +2599,72 @@ function _define_property(obj, key, value) {
 		this.initHooks.push(hook);
 	}
 	/**
+	* ### addDisposeHook
+	* Programmatic counterpart of `@MoostDispose`: runs `fn(app)` once on
+	* {@link dispose} — after every adapter's `onDispose` (no new work comes in), in the
+	* same pass as the `@MoostDispose` instance hooks, by ascending `priority`
+	* (default 0; instance hooks first on ties). Awaited; a failure is collected into
+	* the `AggregateError` `dispose()` rejects with, after the other hooks ran.
+	*
+	* Use it for resources the app itself owns — a timer, a periodic sweep, a queue
+	* consumer started in an init hook.
+	*
+	* Hooks registered after `dispose()` was called do not run.
+	*
+	* ```ts
+	* app.addInitHook(() => {
+	*   const timer = setInterval(() => void app.runDetached('sweep', sweepExpired), 60_000)
+	*   app.addDisposeHook(() => clearInterval(timer))
+	* })
+	* ```
+	*/ addDisposeHook(fn, opts) {
+		this.disposeHooks.push({
+			instance: this,
+			method: `addDisposeHook(${fn.name || "anonymous"})`,
+			priority: opts?.priority ?? 0,
+			fn: () => fn(this)
+		});
+	}
+	/**
+	* ### runDetached
+	* Runs `fn` as its own event, detached from the caller: a fresh ROOT event context
+	* (kind {@link detachedKind}, not a child of the calling request, so nothing it does is tied
+	* to the request's lifetime), with its own `FOR_EVENT` DI scope — released when `fn`
+	* settles — and the app as controller context (`useControllerContext().instantiate()` works).
+	* Context-injector instrumentation (OpenTelemetry) sees it as a `DETACHED` event.
+	*
+	* Call it from a handler to do work after the response, without awaiting it. The returned
+	* promise resolves with `fn`'s result, or `undefined` when it fails — a failure is logged
+	* (`opts.logger`, default the app logger topic `name`) and never rejects, so a forgotten
+	* `await` cannot crash the process. It is not a job queue: nothing persists or retries it.
+	*
+	* ```ts
+	* @Post('signup')
+	* signup(@Body() user: TUser) {
+	*   void this.app.runDetached('welcome-mail', () => this.mailer.sendWelcome(user.email))
+	*   return { ok: true }
+	* }
+	* ```
+	*/ runDetached(name, fn, opts) {
+		const logger = opts?.logger ?? this.getLogger(name);
+		const run = (0, _wooksjs_event_core.createEventContext)({ logger }, detachedKind, {}, async () => {
+			const release = holdEventScopeLazily(getEventScope());
+			setControllerContext(this, "runDetached", "", { prefix: "" });
+			announceHandler((0, _wooksjs_event_core.getContextInjector)(), detachedKind.name, name);
+			try {
+				return await fn();
+			} catch (error) {
+				logger.error(`Detached run "${name}" failed: ${errorMessage(error)}`, error);
+				return;
+			} finally {
+				release();
+			}
+		});
+		this.detachedRuns.add(run);
+		run.finally(() => this.detachedRuns.delete(run));
+		return run;
+	}
+	/**
 	* ### dispose
 	* Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
 	* hook of every singleton this app can reach — DI registry singletons
@@ -2528,7 +2673,8 @@ function _define_property(obj, key, value) {
 	* `[Symbol.dispose]()` method is disposed through that.
 	*
 	* Order: every adapter's `onDispose` in registration order (stop taking new
-	* work first), then instance hooks by ascending `priority`. Everything is
+	* work first), then the {@link runDetached} runs in flight are awaited, then
+	* instance hooks and {@link addDisposeHook} functions by ascending `priority`. Everything is
 	* awaited, failures never stop the run — once all hooks have run, a failed
 	* disposal rejects the returned promise with an `AggregateError` naming each
 	* failing `Class.method`.
@@ -2588,8 +2734,10 @@ function _define_property(obj, key, value) {
 		return errors;
 	}
 	/** The one-shot body behind {@link Moost.dispose} (see its docs for the contract). */ async runDispose() {
+		const fnHooks = [...this.disposeHooks];
 		const errors = await this.disposeAdapters();
-		const result = await disposeInstances([...getInfactSingletonInstances(), ...this.singletonInstances], {
+		await Promise.allSettled(this.detachedRuns);
+		const result = await disposeWithHooks([...getInfactSingletonInstances(), ...this.singletonInstances], fnHooks, {
 			logger: this.logger,
 			onError: "warn"
 		});
@@ -2877,7 +3025,7 @@ function _define_property(obj, key, value) {
 		this.logger.info(`${prefix || ""}${c}${eventName} ${"\x1B[0m\x1B[2m\x1B[32m" + c}→ ${classConstructor.name}.${"\x1B[36m" + c}${method}()${coff}`);
 	}
 	constructor(options) {
-		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "initHookPhase", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "defaultProvide", void 0), _define_property(this, "defaultReplace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "singletonInstances", void 0), _define_property(this, "disposePromise", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.initHookPhase = "pending", this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.defaultProvide = {}, this.defaultReplace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set();
+		super(), _define_property(this, "options", void 0), _define_property(this, "logger", void 0), _define_property(this, "pipes", void 0), _define_property(this, "interceptors", void 0), _define_property(this, "adapters", void 0), _define_property(this, "controllersOverview", void 0), _define_property(this, "handlerOverviewIndex", void 0), _define_property(this, "initHooks", void 0), _define_property(this, "initHookPhase", void 0), _define_property(this, "provide", void 0), _define_property(this, "replace", void 0), _define_property(this, "defaultProvide", void 0), _define_property(this, "defaultReplace", void 0), _define_property(this, "unregisteredControllers", void 0), _define_property(this, "paramAuditFindings", void 0), _define_property(this, "paramAuditMode", void 0), _define_property(this, "inheritanceAuditMode", void 0), _define_property(this, "initialized", void 0), _define_property(this, "singletonInstances", void 0), _define_property(this, "disposePromise", void 0), _define_property(this, "disposeHooks", void 0), _define_property(this, "detachedRuns", void 0), _define_property(this, "globalInterceptorHandler", void 0), this.options = options, this.pipes = Array.from(sharedPipes), this.interceptors = [], this.adapters = [], this.controllersOverview = [], this.initHooks = [], this.initHookPhase = "pending", this.provide = (0, _prostojs_infact.createProvideRegistry)([_prostojs_infact.Infact, getMoostInfact], [_prostojs_mate.Mate, getMoostMate]), this.replace = {}, this.defaultProvide = {}, this.defaultReplace = {}, this.unregisteredControllers = [], this.paramAuditFindings = [], this.initialized = false, this.singletonInstances = /* @__PURE__ */ new Set(), this.disposeHooks = [], this.detachedRuns = /* @__PURE__ */ new Set();
 		this.paramAuditMode = resolveParamAuditMode(options?.diagnostics?.paramTypes);
 		this.inheritanceAuditMode = options?.diagnostics?.inheritance || "warn";
 		this.logger = options?.logger || getDefaultLogger(`moost`);
@@ -2954,6 +3102,51 @@ function _define_property(obj, key, value) {
 	return getHandlerPaths(moost, getController(), method ?? getMethod() ?? "", opts);
 }
 
+//#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.
+*
+* @example
+* ```ts
+* const messages = { de: { 'Name taken': 'Name vergeben' } }
+* setTranslator((text, params, { locale }) => messages[locale ?? '']?.[text])
+* ```
+*/ 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];
+}
+/**
+* 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).
+*
+* @example
+* ```ts
+* const t = useTranslate()
+* throw new HttpError(409, { message: t('Name taken'), code: 'NAME_TAKEN' })
+* ```
+*/ 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;
+	};
+}
+
 //#endregion
 exports.After = After;
 exports.ApplyDecorators = ApplyDecorators;
@@ -2984,6 +3177,7 @@ exports.Intercept = Intercept;
 exports.Interceptor = Interceptor;
 exports.InterceptorHandler = InterceptorHandler;
 exports.Label = Label;
+exports.Locale = Locale;
 exports.LoggerTopic = LoggerTopic;
 exports.MOOST_ADAPTER_BRAND = MOOST_ADAPTER_BRAND;
 exports.MOOST_MODULE_IDENTITY_KEY = MOOST_MODULE_IDENTITY_KEY;
@@ -3054,6 +3248,7 @@ exports.defineInfactScope = defineInfactScope;
 exports.defineInterceptor = defineInterceptor;
 exports.defineMoostEventHandler = defineMoostEventHandler;
 exports.definePipeFn = definePipeFn;
+exports.detachedKind = detachedKind;
 exports.disposeInstances = disposeInstances;
 Object.defineProperty(exports, 'eventTypeKey', {
   enumerable: true,
@@ -3094,6 +3289,7 @@ exports.getInstanceOwnProps = getInstanceOwnProps;
 exports.getMoostInfact = getMoostInfact;
 exports.getMoostMate = getMoostMate;
 exports.getNewMoostInfact = getNewMoostInfact;
+exports.getTranslator = getTranslator;
 exports.globalKey = globalKey;
 Object.defineProperty(exports, 'isConstructor', {
   enumerable: true,
@@ -3132,13 +3328,22 @@ Object.defineProperty(exports, 'run', {
 });
 exports.setControllerContext = setControllerContext;
 exports.setInfactLoggingOptions = setInfactLoggingOptions;
+exports.setInterceptOriginal = setInterceptOriginal;
 exports.setInterceptResult = setInterceptResult;
 exports.setOvertake = setOvertake;
+exports.setTranslator = setTranslator;
 exports.stampModuleIdentity = stampModuleIdentity;
 exports.stampOnce = stampOnce;
 exports.useControllerContext = useControllerContext;
 exports.useHandlerPaths = useHandlerPaths;
+exports.useInterceptOriginal = useInterceptOriginal;
 exports.useInterceptResult = useInterceptResult;
+Object.defineProperty(exports, 'useLocale', {
+  enumerable: true,
+  get: function () {
+    return _wooksjs_event_core.useLocale;
+  }
+});
 Object.defineProperty(exports, 'useLogger', {
   enumerable: true,
   get: function () {
@@ -3147,4 +3352,5 @@ Object.defineProperty(exports, 'useLogger', {
 });
 exports.useOvertake = useOvertake;
 exports.useScopeId = useScopeId;
+exports.useTranslate = useTranslate;
 exports.withControllerContext = withControllerContext;