moost 0.5.33 → 0.6.1

package/dist/index.d.ts

@@ -1,24 +1,53 @@
-import { useEventLogger } from '@wooksjs/event-core';
-export { ContextInjector, EventLogger, THook, getContextInjector, replaceContextInjector, useAsyncEventContext, useEventLogger } from '@wooksjs/event-core';
+import * as _wooksjs_event_core from '@wooksjs/event-core';
+import { EventContext, Logger } 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';
 import { TProvideRegistry, Infact, TReplaceRegistry, TProvideFn } from '@prostojs/infact';
 export { TProvideRegistry, createProvideRegistry, createReplaceRegistry } from '@prostojs/infact';
+import * as _prostojs_mate from '@prostojs/mate';
+import { TMateParamMeta, Mate } from '@prostojs/mate';
+export { Mate, TMateParamMeta, getConstructor, isConstructor } from '@prostojs/mate';
 import * as _prostojs_logger from '@prostojs/logger';
 import { TConsoleBase, TProstoLoggerOptions, ProstoLogger } from '@prostojs/logger';
 export { ProstoLogger, TConsoleBase } from '@prostojs/logger';
 import { Hookable } from 'hookable';
-import * as _prostojs_mate from '@prostojs/mate';
-import { TMateParamMeta, Mate } from '@prostojs/mate';
-export { Mate, TMateParamMeta, getConstructor, isConstructor } from '@prostojs/mate';
 export { clearGlobalWooks, getGlobalWooks } from 'wooks';
 
+/** Escape-hatch type alias for `any`. */
 type TAny = any;
+/** Generic function signature accepting any arguments. */
 type TAnyFn = (...a: TAny[]) => unknown;
+/** Alias for `object`. */
 type TObject = object;
+/** Alias for `Function`. */
 type TFunction = Function;
+/** Generic class constructor type. */
 type TClassConstructor<T = unknown> = new (...args: TAny[]) => T;
+/** Empty object interface used as a default generic constraint. */
 interface TEmpty {
 }
+/** Union of primitive type name strings (mirrors `typeof` results). */
+type TPrimitives = 'undefined' | 'boolean' | 'number' | 'bigint' | 'string' | 'symbol';
+/** Minimal logger interface required by Moost internals. */
+interface TLogger {
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+}
 
+/**
+ * Marks a constructor parameter dependency as circular.
+ * The resolver function is called lazily to break the circular reference.
+ *
+ * @param resolver - Factory that returns the class constructor (e.g. `() => MyService`).
+ *
+ * @example
+ * ```ts
+ * class ServiceA {
+ *   constructor(@Circular(() => ServiceB) private b: ServiceB) {}
+ * }
+ * ```
+ */
 declare function Circular<T = unknown>(resolver: () => TClassConstructor<T>): ParameterDecorator;
 
 /**
@@ -110,17 +139,33 @@ declare function ImportController(prefix: string, controller: TFunction | TObjec
  */
 declare const Inherit: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
-interface TClassFunction<T extends TAnyFn = TAnyFn> {
-    handler: T;
-}
-type TClassFunctionConstructor<T extends TAnyFn = TAnyFn> = new (...a: TAny[]) => TClassFunction<T>;
-type TCallableClassFunction<T extends TAnyFn = TAnyFn> = T | TClassFunctionConstructor;
-
-type TInterceptorBefore = (reply: (response: TAny) => void) => void | Promise<void>;
-type TInterceptorAfter = (response: TAny, reply: (response: TAny) => void) => void | Promise<void>;
-type TInterceptorOnError = (error: Error, reply: (response: TAny) => void) => void | Promise<void>;
-interface TInterceptorFn {
-    (before: (fn: TInterceptorBefore) => void, after: (fn: TInterceptorAfter) => void, onError: (fn: TInterceptorOnError) => void): unknown | Promise<unknown>;
+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>;
+/**
+ * Object-based interceptor definition.
+ *
+ * Declares lifecycle hooks directly instead of registering callbacks via init function.
+ *
+ * @example
+ * ```ts
+ * const myInterceptor: TInterceptorDef = {
+ *   before(reply) {
+ *     if (!isAuthenticated()) reply(new HttpError(401))
+ *   },
+ *   after(response, reply) {
+ *     reply(transform(response))
+ *   },
+ *   error(error, reply) {
+ *     reply(formatError(error))
+ *   },
+ * }
+ * ```
+ */
+interface TInterceptorDef {
+    before?: TInterceptorBeforeFn;
+    after?: TInterceptorAfterFn;
+    error?: TInterceptorErrorFn;
     priority?: TInterceptorPriority;
     _name?: string;
 }
@@ -136,12 +181,12 @@ declare enum TInterceptorPriority {
 /**
  * ## Intercept
  * ### @Decorator
- * Set interceptor
- * @param handler interceptor fn (use defineInterceptorFn)
- * @param priority interceptor priority
- * @returns
+ * Attach an interceptor to a class or method.
+ * @param handler — @Interceptor class constructor or TInterceptorDef object
+ * @param priority — interceptor priority (overrides handler's own priority)
+ * @param name — interceptor name for tracing
  */
-declare function Intercept(handler: TCallableClassFunction<TInterceptorFn>, priority?: TInterceptorPriority, name?: string): ClassDecorator & MethodDecorator;
+declare function Intercept(handler: TClassConstructor | TInterceptorDef, priority?: TInterceptorPriority, name?: string): ClassDecorator & MethodDecorator;
 
 type TDecoratorLevel = 'CLASS' | 'METHOD' | 'PROP' | 'PARAM';
 
@@ -150,7 +195,9 @@ interface TInfactLoggingOptions {
     warn?: true | false;
     error?: true | false;
 }
+/** Configures which Infact DI events are logged (instance creation, warnings, errors). */
 declare function setInfactLoggingOptions(options: TInfactLoggingOptions): void;
+/** Returns the shared Infact DI container used by Moost for dependency injection. */
 declare function getMoostInfact(): Infact<TMoostMetadata<TEmpty>, TMoostMetadata<TEmpty>, TMoostParamsMetadata, TCustom>;
 interface TCustom {
     pipes?: TPipeData[];
@@ -174,6 +221,7 @@ declare function getInfactScopeVars<T extends object>(name: string | symbol): T
  */
 declare function getNewMoostInfact(): Infact<TMoostMetadata<TEmpty>, TMoostMetadata<TEmpty>, TMoostParamsMetadata, TCustom>;
 
+/** Metadata context passed to pipe functions during argument/property resolution. */
 interface TPipeMetas<T extends TObject = TEmpty> {
     classMeta?: TMoostMetadata & T;
     methodMeta?: TMoostMetadata & T;
@@ -187,10 +235,12 @@ interface TPipeMetas<T extends TObject = TEmpty> {
     key: string | symbol;
     instantiate: <T extends TObject>(t: TClassConstructor<T>) => Promise<T>;
 }
+/** A pipe function that transforms, resolves, or validates a value during the pipe pipeline. */
 interface TPipeFn<T extends TObject = TEmpty> {
     (value: unknown, metas: TPipeMetas<T>, level: TDecoratorLevel): unknown | Promise<unknown>;
     priority?: TPipePriority;
 }
+/** Execution priority for pipes. Lower values run first. */
 declare enum TPipePriority {
     BEFORE_RESOLVE = 0,
     RESOLVE = 1,
@@ -202,6 +252,7 @@ declare enum TPipePriority {
     VALIDATE = 7,
     AFTER_VALIDATE = 8
 }
+/** A pipe entry pairing a handler function with its execution priority. */
 interface TPipeData {
     handler: TPipeFn;
     priority: TPipePriority;
@@ -209,26 +260,32 @@ interface TPipeData {
 
 declare const resolvePipe: TPipeFn<TEmpty>;
 
+/** Core metadata shape attached to classes, methods, and properties by Moost decorators. */
 interface TMoostMetadata<H extends TObject = TEmpty> extends TCommonMetaFields, TCommonMoostMeta {
-    requiredProps?: Array<string | symbol>;
+    requiredProps?: (string | symbol)[];
     controller?: {
         prefix?: string;
     };
-    importController?: Array<{
+    importController?: {
         prefix?: string;
         typeResolver?: TClassConstructor | (() => TClassConstructor | TObject | Promise<TClassConstructor | TObject>);
         provide?: TProvideRegistry;
-    }>;
-    properties?: Array<string | symbol>;
+    }[];
+    properties?: (string | symbol)[];
     injectable?: true | TInjectableScope;
+    interceptor?: {
+        priority: TInterceptorPriority;
+    };
+    interceptorHook?: 'before' | 'after' | 'error';
     interceptors?: TInterceptorData[];
-    handlers?: Array<TMoostHandler<H>>;
+    handlers?: TMoostHandler<H>[];
     returnType?: TFunction;
     provide?: TProvideRegistry;
     replace?: TReplaceRegistry;
     loggerTopic?: string;
-    params: Array<TMateParamMeta & TMoostParamsMetadata>;
+    params: (TMateParamMeta & TMoostParamsMetadata)[];
 }
+/** Metadata attached to constructor/method parameters by Moost decorators. */
 interface TMoostParamsMetadata extends TCommonMetaFields, TCommonMoostMeta {
     circular?: () => TAny;
     inject?: string | symbol | TClassConstructor;
@@ -237,20 +294,24 @@ interface TMoostParamsMetadata extends TCommonMetaFields, TCommonMoostMeta {
     paramName?: string;
     fromScope?: string | symbol;
 }
+/** DI scope for injectable classes: per-event or application-wide singleton. */
 type TInjectableScope = 'FOR_EVENT' | 'SINGLETON';
+/** Describes a registered handler (HTTP route, CLI command, workflow step, etc.). */
 type TMoostHandler<T> = {
     type: string;
     path?: string;
 } & T;
+/** Stored interceptor entry attached to a class or method via `@Intercept`. */
 interface TInterceptorData {
-    handler: TCallableClassFunction<TInterceptorFn>;
+    handler: TClassConstructor | TInterceptorDef;
     priority: TInterceptorPriority;
     name: string;
 }
+/** Returns the shared `Mate` instance operating in the `'moost'` metadata workspace. */
 declare function getMoostMate<Class extends TObject = TEmpty, Prop extends TObject = TEmpty, Param extends TObject = TEmpty>(): Mate<TMoostMetadata & Class & {
-    params: Array<Param & TMateParamMeta>;
+    params: (Param & TMateParamMeta)[];
 }, TMoostMetadata & Prop & {
-    params: Array<Param & TMateParamMeta>;
+    params: (Param & TMateParamMeta)[];
 }>;
 interface TCommonMetaFields {
     id?: string;
@@ -278,10 +339,75 @@ interface TCommonMoostMeta {
  */
 declare function Injectable(scope?: true | TInjectableScope): ClassDecorator;
 
+/** Callback used by interceptors to short-circuit and replace the handler response. */
+type TOvertakeFn = (response: TAny) => void;
+/** Stores the overtake (reply) function in the current event context. */
+declare function setOvertake(fn: TOvertakeFn, ctx?: EventContext): void;
+/** Retrieves the overtake (reply) function from the current event context. */
+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. */
+declare function useInterceptResult<T = unknown>(ctx?: EventContext): T;
+
+type TInterceptorDefFactory = () => TInterceptorDef | Promise<TInterceptorDef>;
+/**
+ * ## @Interceptor
+ * ### Class Decorator
+ * Marks a class as a decorator-based interceptor.
+ * Auto-adds @Injectable() if not already present.
+ *
+ * Use @Before(), @After(), and @OnError() method decorators
+ * to register lifecycle hooks.
+ *
+ * @param priority — interceptor priority (default: INTERCEPTOR)
+ * @param scope — DI scope ('FOR_EVENT' | 'SINGLETON' | true)
+ */
+declare function Interceptor(priority?: TInterceptorPriority, scope?: true | TInjectableScope): ClassDecorator;
+/**
+ * ## @Before
+ * ### Method Decorator
+ * Marks a method as a before-phase interceptor hook.
+ * Runs before argument resolution and handler execution.
+ * Use @Overtake() param to get the reply fn for short-circuiting.
+ */
+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.
+ */
+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.
+ */
+declare function OnError(): MethodDecorator;
+/**
+ * ## @Overtake
+ * ### Parameter Decorator
+ * Injects the reply function into an interceptor method parameter.
+ * Call the reply fn to short-circuit the handler or replace the response.
+ */
+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.
+ */
+declare function Response(): ParameterDecorator;
+
 /**
  * Resolves event logger from event context
  * @param topic
- * @returns Resolver to '@wooksjs/event-core' (EventLogger)
+ * @returns Resolver to '@wooksjs/event-core' (Logger)
  */
 declare function InjectEventLogger(topic?: string): ParameterDecorator & PropertyDecorator;
 /**
@@ -382,54 +508,66 @@ declare function Const<T>(value: T, label?: string): ParameterDecorator & Proper
  */
 declare function ConstFactory<T>(factory: () => T | Promise<T>, label?: string): ParameterDecorator & PropertyDecorator;
 
+/** Entry for a single interceptor in the handler chain. */
+interface TInterceptorEntry {
+    handler: TInterceptorDef | TInterceptorDefFactory;
+    name: string;
+    /** Pre-computed span name for ci.with(). */
+    spanName: string;
+}
+/**
+ * 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 handlers: Array<{
-        handler: TInterceptorFn;
-        name: string;
-    }>;
-    constructor(handlers: Array<{
-        handler: TInterceptorFn;
+    protected handlers: TInterceptorEntry[];
+    constructor(handlers: TInterceptorEntry[]);
+    protected after: {
         name: string;
-    }>);
-    protected before: Array<{
+        fn: TInterceptorAfterFn;
+    }[] | undefined;
+    protected onError: {
         name: string;
-        fn: TInterceptorBefore;
-    }>;
-    protected after: Array<{
-        name: string;
-        fn: TInterceptorAfter;
-    }>;
-    protected onError: Array<{
-        name: string;
-        fn: TInterceptorOnError;
-    }>;
+        fn: TInterceptorErrorFn;
+    }[] | undefined;
     response?: unknown;
     responseOverwritten: boolean;
+    protected _boundReplyFn?: (reply: unknown) => void;
+    protected getReplyFn(): (reply: unknown) => void;
     get count(): number;
-    get countBefore(): number;
     get countAfter(): number;
     get countOnError(): number;
-    replyFn(reply: unknown): void;
-    init(): Promise<{} | null | undefined>;
-    fireBefore(response: unknown): Promise<unknown>;
-    fireAfter(response: unknown): Promise<unknown>;
+    /**
+     * Register hooks from a TInterceptorDef.
+     * Returns a pending PromiseLike if `before` went async, or undefined.
+     */
+    private registerDef;
+    before(): unknown;
+    private _beforeAsyncFactory;
+    private _beforeAsyncPending;
+    private _beforeFrom;
+    fireAfter(response: unknown): unknown;
+    private _fireAfterAsync;
 }
 
+/** Options passed to init/end hooks during the event handler lifecycle. */
 interface TMoostEventHandlerHookOptions<T> {
     scopeId: string;
-    logger: ReturnType<typeof useEventLogger>;
+    logger: Logger;
     unscope: () => void;
     instance?: T;
     method?: keyof T;
     getResponse: () => unknown;
     reply: (r: unknown) => void;
 }
+/** Configuration for `defineMoostEventHandler`, describing how to resolve and invoke a handler. */
 interface TMoostEventHandlerOptions<T> {
     contextType?: string | string[];
     loggerTitle: string;
-    getIterceptorHandler: () => Promise<InterceptorHandler> | InterceptorHandler | undefined;
+    getIterceptorHandler: () => InterceptorHandler | undefined;
     getControllerInstance: () => Promise<T> | T | undefined;
     controllerMethod?: keyof T;
+    controllerName?: string;
     callControllerMethod?: (args: unknown[]) => unknown;
     resolveArgs?: () => Promise<unknown[]> | unknown[];
     logErrors?: boolean;
@@ -441,29 +579,55 @@ interface TMoostEventHandlerOptions<T> {
     targetPath: string;
     handlerType: string;
 }
+/** Composable returning the moost scope ID for the current event. Generates on first call, caches for subsequent calls. */
+declare const useScopeId: (ctx?: _wooksjs_event_core.EventContext) => string;
+/** Registers a DI scope for the given ID and returns an unscope function. */
 declare function registerEventScope(scopeId: string): () => void;
-declare function defineMoostEventHandler<T>(options: TMoostEventHandlerOptions<T>): () => Promise<unknown>;
+/**
+ * Creates the complete event handler lifecycle processor used by adapters.
+ * Handles scope registration, controller resolution, interceptors, argument resolution,
+ * handler invocation, and cleanup — optimised for sync-first execution.
+ */
+declare function defineMoostEventHandler<T>(options: TMoostEventHandlerOptions<T>): () => unknown;
+
+/** Returns the own method names of an instance, including inherited methods from parent classes. */
+declare function getInstanceOwnMethods<T = TAny>(instance: T): (keyof T)[];
+/** Returns the own non-method property names of an instance, including inherited properties. */
+declare function getInstanceOwnProps<T = TAny>(instance: T): (keyof T)[];
 
-declare function getInstanceOwnMethods<T = TAny>(instance: T): Array<keyof T>;
-declare function getInstanceOwnProps<T = TAny>(instance: T): Array<keyof T>;
+/**
+ * Checks whether a value is a PromiseLike (thenable).
+ * Single source of truth — import from here instead of duplicating.
+ */
+declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Merges multiple arrays of items with a `priority` field, returning a
+ * single sorted-by-priority array.  Accepts `undefined` entries for convenience.
+ */
+declare function mergeSorted<T extends {
+    priority: number;
+}>(...lists: (T[] | readonly T[] | undefined)[]): T[];
 
+/** Summary of a registered controller, its metadata, prefix, and handlers. */
 interface TControllerOverview {
     meta: TMoostMetadata;
     computedPrefix: string;
     type: TFunction;
     handlers: THandlerOverview[];
 }
+/** Summary of a registered handler method within a controller. */
 interface THandlerOverview {
     meta: TMoostMetadata;
     path?: string;
     type: string;
     method: string;
     handler: TMoostHandler<TEmpty>;
-    registeredAs: Array<{
+    registeredAs: {
         path: string;
         args: string[];
-    }>;
+    }[];
 }
+/** Hook points in the event handler lifecycle where context injectors are invoked. */
 type TContextInjectorHook = 'Event:start' | 'Interceptors:init' | 'Arguments:resolve' | 'Interceptors:before' | 'Handler' | 'Interceptors:after';
 
 interface TMoostOptions {
@@ -528,11 +692,11 @@ declare class Moost extends Hookable {
     protected logger: TConsoleBase;
     protected pipes: TPipeData[];
     protected interceptors: TInterceptorData[];
-    protected adapters: Array<TMoostAdapter<TAny>>;
+    protected adapters: TMoostAdapter<TAny>[];
     protected controllersOverview: TControllerOverview[];
     protected provide: TProvideRegistry;
     protected replace: TReplaceRegistry;
-    protected unregisteredControllers: Array<TObject | TFunction | [string, TObject | TFunction]>;
+    protected unregisteredControllers: (TObject | TFunction | [string, TObject | TFunction])[];
     constructor(options?: TMoostOptions | undefined);
     _fireEventStart(source: TMoostAdapter<unknown>): void;
     _fireEventEnd(source: TMoostAdapter<unknown>): void;
@@ -557,16 +721,16 @@ declare class Moost extends Hookable {
     init(): Promise<void>;
     protected bindControllers(): Promise<void>;
     protected bindController(controller: TFunction | TObject, provide: TProvideRegistry, replace: TReplaceRegistry, globalPrefix: string, replaceOwnPrefix?: string): Promise<void>;
-    applyGlobalPipes(...items: Array<TPipeFn | TPipeData>): this;
-    protected globalInterceptorHandler?: () => Promise<InterceptorHandler>;
+    applyGlobalPipes(...items: (TPipeFn | TPipeData)[]): this;
+    protected globalInterceptorHandler?: () => InterceptorHandler | undefined;
     /**
      * Provides InterceptorHandler with global interceptors and pipes.
      * Used to process interceptors when event handler was not found.
      *
      * @returns IterceptorHandler
      */
-    getGlobalInterceptorHandler(): Promise<InterceptorHandler>;
-    applyGlobalInterceptors(...items: Array<TInterceptorData['handler'] | TInterceptorData>): this;
+    getGlobalInterceptorHandler(): InterceptorHandler | undefined;
+    applyGlobalInterceptors(...items: (TClassConstructor | TInterceptorDef | TInterceptorData)[]): this;
     /**
      * Register new entries to provide as dependency injections
      * @param provide - Provide Registry (use createProvideRegistry from '\@prostojs/infact')
@@ -584,17 +748,18 @@ declare class Moost extends Hookable {
      * @param controllers - list of target controllers (instances)
      * @returns
      */
-    registerControllers(...controllers: Array<TObject | TFunction | [string, TObject | TFunction]>): this;
+    registerControllers(...controllers: (TObject | TFunction | [string, TObject | TFunction])[]): this;
     logMappedHandler(eventName: string, classConstructor: Function, method: string, stroke?: boolean, prefix?: string): void;
 }
 interface TMoostAdapterOptions<H, T> {
     prefix: string;
     fakeInstance: T;
-    getInstance: () => Promise<T>;
+    getInstance: () => Promise<T> | T;
     method: keyof T;
-    handlers: Array<TMoostHandler<H>>;
-    getIterceptorHandler: () => Promise<InterceptorHandler>;
-    resolveArgs: () => Promise<unknown[]>;
+    handlers: TMoostHandler<H>[];
+    getIterceptorHandler: () => InterceptorHandler | undefined;
+    resolveArgs?: () => Promise<unknown[]> | unknown[];
+    controllerName?: string;
     logHandler: (eventName: string) => void;
     register: (handler: TMoostHandler<TEmpty>, path: string, args: string[]) => void;
 }
@@ -605,10 +770,18 @@ interface TMoostAdapter<H> {
     getProvideRegistry?: () => TProvideRegistry;
 }
 
-declare function setControllerContext<T>(controller: T, method: keyof T, route: string): void;
-declare function useControllerContext<T extends object>(): {
+/**
+ * Sets the controller context for the current event scope.
+ * Called internally by adapters when dispatching events to handlers.
+ */
+declare function setControllerContext<T>(controller: T, method: keyof T, route: string, ctx?: EventContext): void;
+/**
+ * Provides access to the current controller context within an event handler.
+ * Returns utilities for accessing the controller instance, method metadata, and DI.
+ */
+declare function useControllerContext<T extends object>(ctx?: EventContext): {
     instantiate: <TT>(c: TClassConstructor<TT>) => Promise<TT>;
-    getRoute: () => string | undefined;
+    getRoute: () => string;
     getController: () => T;
     getMethod: () => string | undefined;
     getControllerMeta: <TT extends object>() => (TMoostMetadata<TEmpty> & TT & {
@@ -634,53 +807,60 @@ declare function useControllerContext<T extends object>(): {
 };
 
 /**
- * ### Define Interceptor Function
+ * Define a before-phase interceptor.
+ *
+ * Runs before argument resolution and handler execution.
+ * Call `reply(value)` to short-circuit the handler and respond early.
  *
+ * @example
  * ```ts
- * defineInterceptorFn((before, after, onError) => {
- *         //init
- *         before(() => {
- *              // before handler
- *         })
- *         after((response, reply) => {
- *              // after handler
- *         })
- *         onError((error, reply) => {
- *              // when error occured
- *         })
- *     },
- *     TInterceptorPriority.INTERCEPTOR,
- * )
+ * const authGuard = defineBeforeInterceptor((reply) => {
+ *   if (!isAuthenticated()) reply(new HttpError(401))
+ * }, TInterceptorPriority.GUARD)
  * ```
+ */
+declare function defineBeforeInterceptor(fn: TInterceptorBeforeFn, priority?: TInterceptorPriority): TInterceptorDef;
+/**
+ * Define an after-phase interceptor.
  *
- * @param fn interceptor function
- * @param priority priority of the interceptor where BEFORE_ALL = 0, BEFORE_GUARD = 1, GUARD = 2, AFTER_GUARD = 3, INTERCEPTOR = 4, CATCH_ERROR = 5, AFTER_ALL = 6
- * @returns
+ * Runs after successful handler execution.
+ * Call `reply(value)` to transform/replace the response.
+ *
+ * @example
+ * ```ts
+ * const setHeader = defineAfterInterceptor(() => {
+ *   useResponse().setHeader('x-server', 'my-server')
+ * }, TInterceptorPriority.AFTER_ALL)
+ * ```
  */
-declare function defineInterceptorFn(fn: TInterceptorFn, priority?: TInterceptorPriority): TInterceptorFn;
+declare function defineAfterInterceptor(fn: TInterceptorAfterFn, priority?: TInterceptorPriority): TInterceptorDef;
 /**
- * Class based interceptor interface
+ * Define an error-phase interceptor.
  *
- * Use it to create class-based interceptors and don't forget to make it **@Injectable()**
+ * Runs when the handler throws or returns an Error.
+ * Call `reply(value)` to recover from the error with a replacement response.
  *
  * @example
- * "@Injectable()
- * export class MyInterceptor implements TInterceptorClass {
- *     static priority = TInterceptorPriority.INTERCEPTOR
- *     handler: TInterceptorClass['handler'] = (before, after, onError) => {
- *         before((reply) => {
- *             console.log('before')
- *         })
- *         after((response, reply) => {
- *             console.log('after')
- *         })
- *         onError((error, reply) => {
- *             console.log('error')
- *         })
- *     }
- * }
+ * ```ts
+ * const errorFormatter = defineErrorInterceptor((error, reply) => {
+ *   reply({ message: error.message, status: 500 })
+ * }, TInterceptorPriority.CATCH_ERROR)
+ * ```
+ */
+declare function defineErrorInterceptor(fn: TInterceptorErrorFn, priority?: TInterceptorPriority): TInterceptorDef;
+/**
+ * Define a full interceptor with multiple lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * const myInterceptor = defineInterceptor({
+ *   before(reply) { ... },
+ *   after(response, reply) { ... },
+ *   error(error, reply) { ... },
+ * }, TInterceptorPriority.INTERCEPTOR)
+ * ```
  */
-type TInterceptorClass = TClassFunction<TInterceptorFn>;
+declare function defineInterceptor(def: TInterceptorDef, priority?: TInterceptorPriority): TInterceptorDef;
 /**
  * ### Define Pipe Function
  *
@@ -693,14 +873,16 @@ type TInterceptorClass = TClassFunction<TInterceptorFn>;
  * )
  * ```
  *
- * @param fn interceptor function
- * @param priority priority of the pipe where BEFORE_RESOLVE = 0, RESOLVE = 1, AFTER_RESOLVE = 2, BEFORE_TRANSFORM = 3, TRANSFORM = 4, AFTER_TRANSFORM = 5, BEFORE_VALIDATE = 6, VALIDATE = 7, AFTER_VALIDATE = 8
+ * @param fn pipe function
+ * @param priority priority of the pipe
  * @returns
  */
 declare function definePipeFn<T extends TObject = TEmpty>(fn: TPipeFn<T>, priority?: TPipePriority): TPipeFn<T>;
 
+/** Creates a new `ProstoLogger` instance with sensible defaults (level 4, colored console). */
 declare function createLogger(opts?: Partial<TProstoLoggerOptions>): ProstoLogger;
+/** Default colored console transport used by Moost loggers. */
 declare const loggerConsoleTransport: _prostojs_logger.TProstoLoggerTransportFn<any>;
 
-export { ApplyDecorators, Circular, Const, ConstFactory, Controller, Description, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, InterceptorHandler, Label, LoggerTopic, Moost, Optional, Param, Params, Pipe, Provide, Replace, Required, Resolve, TInterceptorPriority, TPipePriority, Value, createLogger, defineInfactScope, defineInterceptorFn, defineMoostEventHandler, definePipeFn, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, loggerConsoleTransport, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, useControllerContext };
-export type { TCallableClassFunction, TClassConstructor, TClassFunction, TContextInjectorHook, TControllerOverview, TInjectableScope, TInterceptorAfter, TInterceptorBefore, TInterceptorClass, TInterceptorData, TInterceptorFn, TInterceptorOnError, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostOptions, TMoostParamsMetadata, TPipeData, TPipeFn, TPipeMetas };
+export { After, ApplyDecorators, Before, Circular, Const, ConstFactory, Controller, Description, Id, ImportController, Inherit, Inject, InjectEventLogger, InjectFromScope, InjectMoostLogger, InjectScopeVars, Injectable, Intercept, Interceptor, InterceptorHandler, Label, LoggerTopic, Moost, OnError, Optional, Overtake, Param, Params, Pipe, Provide, Replace, Required, Resolve, Response, TInterceptorPriority, TPipePriority, Value, createLogger, defineAfterInterceptor, defineBeforeInterceptor, defineErrorInterceptor, defineInfactScope, defineInterceptor, defineMoostEventHandler, definePipeFn, getInfactScopeVars, getInstanceOwnMethods, getInstanceOwnProps, getMoostInfact, getMoostMate, getNewMoostInfact, isThenable, loggerConsoleTransport, mergeSorted, registerEventScope, resolvePipe, setControllerContext, setInfactLoggingOptions, setInterceptResult, setOvertake, useControllerContext, useInterceptResult, useOvertake, useScopeId };
+export type { TAny, TAnyFn, TClassConstructor, TContextInjectorHook, TControllerOverview, TEmpty, TFunction, TInjectableScope, TInterceptorAfterFn, TInterceptorBeforeFn, TInterceptorData, TInterceptorDef, TInterceptorDefFactory, TInterceptorEntry, TInterceptorErrorFn, TLogger, TMoostAdapter, TMoostAdapterOptions, TMoostEventHandlerHookOptions, TMoostEventHandlerOptions, TMoostHandler, TMoostMetadata, TMoostOptions, TMoostParamsMetadata, TObject, TOvertakeFn, TPipeData, TPipeFn, TPipeMetas, TPrimitives };