moost 0.6.53 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import * as _wooksjs_event_core from '@wooksjs/event-core';
 import { EventContext, Logger, Accessor, Key } from '@wooksjs/event-core';
-export { Cached, ContextInjector, EventContext, EventContextOptions, Key, Logger, cached, createEventContext, current, eventTypeKey, getContextInjector, key, replaceContextInjector, resetContextInjector, run, useLogger } from '@wooksjs/event-core';
+export { Cached, ContextInjector, EventContext, EventContextOptions, Key, Logger, TLocaleInput, cached, createEventContext, current, eventTypeKey, getContextInjector, key, replaceContextInjector, resetContextInjector, run, useLocale, useLogger } from '@wooksjs/event-core';
 import { TProvideRegistry, TReplaceRegistry, Infact, TProvideFn } from '@prostojs/infact';
 export { TProvideRegistry, createProvideRegistry, createReplaceRegistry, getClassKey } from '@prostojs/infact';
 import * as _prostojs_mate from '@prostojs/mate';
@@ -280,8 +281,19 @@ interface TPipeData {
 declare const resolvePipe: TPipeFn<TEmpty>;
 
 type TInterceptorBeforeFn = (reply: (response: TAny) => void) => void | Promise<void>;
-type TInterceptorAfterFn = (response: TAny, reply: (response: TAny) => void) => void | Promise<void>;
-type TInterceptorErrorFn = (error: Error, reply: (response: TAny) => void) => void | Promise<void>;
+/**
+ * After hook: runs when the CURRENT value of the after/error chain is not an `Error`.
+ * `response` is the handler result as replaced by the hooks that ran before this one;
+ * `original` is the value that entered the chain. A throw, or a `reply()` with an `Error`,
+ * switches the rest of the chain to error hooks.
+ */
+type TInterceptorAfterFn = (response: TAny, reply: (response: TAny) => void, original?: TAny) => void | Promise<void>;
+/**
+ * Error hook: runs when the CURRENT value of the after/error chain is an `Error` — raised by
+ * the handler, a before hook, or an after/error hook that ran before this one. `original` is
+ * the value that entered the chain. A `reply()` with a non-Error value recovers the chain.
+ */
+type TInterceptorErrorFn = (error: Error, reply: (response: TAny) => void, original?: TAny) => void | Promise<void>;
 /**
  * Object-based interceptor definition.
  *
@@ -296,7 +308,7 @@ type TInterceptorErrorFn = (error: Error, reply: (response: TAny) => void) => vo
  *   after(response, reply) {
  *     reply(transform(response))
  *   },
- *   error(error, reply) {
+ *   error(error, reply, original) {
  *     reply(formatError(error))
  *   },
  * }
@@ -529,6 +541,16 @@ interface TDisposeOptions {
      */
     onError?: 'warn' | 'throw';
 }
+/**
+ * @internal One dispose hook: `instance[method]`, or `fn` for a plain-function hook
+ * (`Moost.addDisposeHook`, where `instance`/`method` only identify it in failures).
+ */
+interface TDisposeHook {
+    instance: object;
+    method: string | symbol;
+    priority: number;
+    fn?: () => unknown;
+}
 /**
  * Runs the dispose hooks of every given instance, once per instance, ever.
  *
@@ -548,6 +570,17 @@ interface TDisposeOptions {
  */
 declare function disposeInstances(instances: Iterable<object>, opts?: TDisposeOptions): Promise<TDisposeResult>;
 
+/**
+ * Event kind of a run started with {@link Moost.runDetached} (`eventTypeKey` = `'DETACHED'`).
+ * Its own event, with no request: HTTP composables are not available inside.
+ */
+declare const detachedKind: _wooksjs_event_core.EventKind<{}>;
+/** Options for {@link Moost.runDetached}. */
+interface TRunDetachedOptions {
+    /** Logger of the run (`useLogger()` inside, and where a failure is logged). Default: `app.getLogger(name)`. */
+    logger?: TConsoleBase;
+}
+
 interface TMoostOptions {
     /**
      * Global path prefix — mounts the whole app under one path segment.
@@ -734,6 +767,10 @@ declare class Moost extends Hookable {
     protected singletonInstances: Set<object>;
     /** In-flight/settled `dispose()` run — makes disposal idempotent. */
     protected disposePromise?: Promise<void>;
+    /** Functions registered with {@link addDisposeHook}. */
+    protected disposeHooks: TDisposeHook[];
+    /** Detached runs in flight — {@link dispose} waits for them before the instance hooks. */
+    protected detachedRuns: Set<Promise<unknown>>;
     constructor(options?: TMoostOptions | undefined);
     _fireEventStart(source: TMoostAdapter<unknown>): void;
     _fireEventEnd(source: TMoostAdapter<unknown>): void;
@@ -803,6 +840,51 @@ declare class Moost extends Hookable {
     addInitHook(fn: (app: this) => unknown, opts?: {
         priority?: number;
     }): void;
+    /**
+     * ### 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: (app: this) => unknown, opts?: {
+        priority?: number;
+    }): void;
+    /**
+     * ### 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<R>(name: string, fn: () => R | Promise<R>, opts?: TRunDetachedOptions): Promise<Awaited<R> | undefined>;
     /**
      * ### dispose
      * Graceful shutdown: stops the adapters, then runs every `@MoostDispose`
@@ -812,7 +894,8 @@ declare class Moost extends Hookable {
      * `[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`.
@@ -1139,8 +1222,19 @@ declare function setOvertake(fn: TOvertakeFn, ctx?: EventContext): void;
 declare function useOvertake(ctx?: EventContext): TOvertakeFn;
 /** Stores the interceptor result value in the current event context. */
 declare function setInterceptResult(value: unknown, ctx?: EventContext): void;
-/** Retrieves the interceptor result value from the current event context. */
+/**
+ * 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.
+ */
 declare function useInterceptResult<T = unknown>(ctx?: EventContext): T;
+/** Stores the value that entered the after/error chain in the current event context. */
+declare function setInterceptOriginal(value: unknown, ctx?: EventContext): void;
+/**
+ * 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.
+ */
+declare function useInterceptOriginal<T = unknown>(ctx?: EventContext): T;
 
 type TInterceptorDefFactory = () => TInterceptorDef | Promise<TInterceptorDef>;
 /**
@@ -1168,16 +1262,21 @@ declare function Before(): MethodDecorator;
  * ## @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.
  */
 declare function After(): MethodDecorator;
 /**
  * ## @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).
  */
 declare function OnError(): MethodDecorator;
 /**
@@ -1190,9 +1289,9 @@ declare function Overtake(): ParameterDecorator;
 /**
  * ## @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.
  */
 declare function Response(): ParameterDecorator;
 
@@ -1292,6 +1391,18 @@ declare function Param(name: string): MethodDecorator & ClassDecorator & Paramet
  * @paramType object
  */
 declare function Params(): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * 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
+ */
+declare function Locale(): ParameterDecorator & PropertyDecorator;
 /**
  * Provide Const Value
  * @decorator
@@ -1316,28 +1427,33 @@ interface TInterceptorEntry {
     /** Pre-computed span name for ci.with(). */
     spanName: string;
 }
-/** A registered after/onError hook of one event. */
-interface TRegisteredHook<F> {
+/** The after/error hooks of one interceptor def, registered for one event. */
+interface TRegisteredHooks {
     /** Pre-computed span name for ci.with(). */
     spanName: string;
-    fn: F;
+    after?: TInterceptorAfterFn;
+    error?: TInterceptorErrorFn;
 }
 /**
  * Manages the before/after/error interceptor lifecycle for a single event.
  * Optimised for the common sync path — only allocates promises when an interceptor goes async.
  */
 declare class InterceptorHandler {
-    protected after: TRegisteredHook<TInterceptorAfterFn>[] | undefined;
-    protected onError: TRegisteredHook<TInterceptorErrorFn>[] | undefined;
+    protected hooks: TRegisteredHooks[] | undefined;
     response?: unknown;
+    /**
+     * After {@link fireAfter}: whether the final value is raised (thrown) rather than returned.
+     * Set by a hook that throws; cleared by a hook replying a non-Error value.
+     */
+    raised: boolean;
     responseOverwritten: boolean;
     protected _boundReplyFn?: (reply: unknown) => void;
     protected handlers: TInterceptorEntry[];
     constructor(handlers: TInterceptorEntry[]);
     protected getReplyFn(): (reply: unknown) => void;
     get count(): number;
-    get countAfter(): number;
-    get countOnError(): number;
+    /** Number of registered interceptors with an after and/or error hook. */
+    get countHooks(): number;
     /**
      * Register hooks from a TInterceptorDef.
      * Returns a pending PromiseLike if `before` went async, or undefined.
@@ -1347,7 +1463,26 @@ declare class InterceptorHandler {
     private _beforeAsyncFactory;
     private _beforeAsyncPending;
     private _beforeFrom;
-    fireAfter(response: unknown): unknown;
+    /**
+     * 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: unknown, raised?: boolean): unknown;
+    /**
+     * 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).
+     */
+    private runHook;
+    /** A hook threw: the error becomes the current value, raised. */
+    private raise;
     private _fireAfterAsync;
 }
 
@@ -1630,10 +1765,54 @@ 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. */
+interface TTranslateContext {
+    /** `useLocale().get()` of the event the text is translated for. */
+    locale: string | undefined;
+    /** 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.
+ *
+ * Moost never translates on its own: plug in any i18n library (vue-i18n, i18next, FormatJS)
+ * or a plain map here.
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * const messages = { de: { 'Name taken': 'Name vergeben' } }
+ * setTranslator((text, params, { locale }) => messages[locale ?? '']?.[text])
+ * ```
+ */
+declare function setTranslator(translate: TTranslate | undefined): void;
+/** The registered translator, or `undefined` (e.g. to skip a per-locale variant entirely). */
+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).
+ *
+ * @example
+ * ```ts
+ * const t = useTranslate()
+ * throw new HttpError(409, { message: t('Name taken'), code: 'NAME_TAKEN' })
+ * ```
+ */
+declare function useTranslate(ctx?: EventContext): (text: string, params?: Record<string, unknown>) => string;
+
 /** 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, 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, disposeInstances, forkEventContext, getHandlerPaths, getInfactScopeVars, getInfactSingletonInstances, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, globalKey, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, stampModuleIdentity, stampOnce, useControllerContext, useHandlerPaths, useInterceptResult, useOvertake, useScopeId, 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, 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, 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 };