@velajs/vela 1.9.0 → 1.12.0

package/dist/module/define-module.js

@@ -0,0 +1,227 @@
+import { InjectionToken } from "../container/types.js";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
+import { stableHash } from "./stable-hash.js";
+const DEFAULT_EXTRAS = {
+    isGlobal: false
+};
+const DEFAULT_TRANSFORM = (def, extras)=>extras.isGlobal ? {
+        ...def,
+        global: true
+    } : def;
+const GLOBAL_SLOT_TOKENS = {
+    guards: APP_GUARD,
+    pipes: APP_PIPE,
+    interceptors: APP_INTERCEPTOR,
+    filters: APP_FILTER,
+    middleware: APP_MIDDLEWARE
+};
+/** Lower a `global:` slot to `APP_*` provider registrations. */ function lowerGlobalSlot(slot) {
+    const out = [];
+    for (const kind of Object.keys(GLOBAL_SLOT_TOKENS)){
+        for (const component of slot[kind] ?? []){
+            const token = GLOBAL_SLOT_TOKENS[kind];
+            if (typeof component === 'function') {
+                out.push(component, {
+                    provide: token,
+                    useExisting: component
+                });
+            } else {
+                out.push({
+                    provide: token,
+                    useValue: component
+                });
+            }
+        }
+    }
+    return out;
+}
+const ASYNC_OPTION_KEYS = new Set([
+    'key',
+    'imports',
+    'inject',
+    'useFactory',
+    'useClass',
+    'useExisting'
+]);
+/**
+ * The one blessed module-authoring engine. Generates `forRoot` AND
+ * `forRootAsync` statics with: `stableHash` key derivation (multi-instance
+ * dedup that survives HMR), typed `inject` tuple inference on the async
+ * factory, an `isGlobal` extra, and — the piece `ConfigurableModuleBuilder`
+ * could not express — providers/controllers/imports/exports/global components
+ * computed **as functions of the options**.
+ *
+ * ```ts
+ * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = defineModule<CorsOptions>({
+ *   name: 'Cors',
+ *   setup: ({ OPTIONS }) => ({
+ *     providers: [{
+ *       provide: APP_MIDDLEWARE,
+ *       useFactory: (o: CorsOptions) => buildCorsMiddleware(o),
+ *       inject: [OPTIONS],
+ *     }],
+ *     exports: [OPTIONS],
+ *   }),
+ * });
+ * export class CorsModule extends ConfigurableModuleClass {}
+ * ```
+ *
+ * `ConfigurableModuleBuilder` remains supported (NestJS parity) and is a thin
+ * adapter over this engine.
+ */ export function defineModule(spec) {
+    const optionsToken = spec.optionsToken ?? new InjectionToken(`${spec.name}_MODULE_OPTIONS`);
+    const syncName = spec.methodName ?? 'forRoot';
+    const asyncName = `${syncName}Async`;
+    const factoryMethodName = spec.factoryMethodName ?? 'create';
+    const extrasDefaults = spec.extras ?? DEFAULT_EXTRAS;
+    const transform = spec.transform ?? DEFAULT_TRANSFORM;
+    const deriveKey = (explicit, structural)=>explicit ?? spec.key?.(structural) ?? stableHash(structural);
+    const applyContributions = (definition, structural, key)=>{
+        if (!spec.setup) return definition;
+        const contributions = spec.setup({
+            OPTIONS: optionsToken,
+            options: structural,
+            key
+        });
+        const providers = [
+            ...definition.providers ?? [],
+            ...contributions.providers ?? [],
+            ...contributions.global ? lowerGlobalSlot(contributions.global) : []
+        ];
+        return {
+            ...definition,
+            providers,
+            controllers: [
+                ...definition.controllers ?? [],
+                ...contributions.controllers ?? []
+            ],
+            imports: [
+                ...definition.imports ?? [],
+                ...contributions.imports ?? []
+            ],
+            exports: [
+                ...definition.exports ?? [],
+                ...contributions.exports ?? []
+            ]
+        };
+    };
+    let GeneratedModuleClass = class GeneratedModuleClass {
+    };
+    Object.defineProperty(GeneratedModuleClass, 'name', {
+        value: `${spec.name}ModuleHost`
+    });
+    Object.defineProperty(GeneratedModuleClass, syncName, {
+        configurable: true,
+        writable: true,
+        enumerable: false,
+        value (options = {}) {
+            const { key: explicitKey, ...rest } = options;
+            const key = deriveKey(explicitKey, rest);
+            const definition = {
+                module: this,
+                key,
+                providers: [
+                    {
+                        provide: optionsToken,
+                        useValue: rest
+                    }
+                ]
+            };
+            return transform(applyContributions(definition, rest, key), {
+                ...extrasDefaults,
+                ...rest
+            });
+        }
+    });
+    Object.defineProperty(GeneratedModuleClass, asyncName, {
+        configurable: true,
+        writable: true,
+        enumerable: false,
+        value (options = {}) {
+            const bag = options;
+            const structural = {};
+            for (const [k, v] of Object.entries(bag)){
+                if (!ASYNC_OPTION_KEYS.has(k)) structural[k] = v;
+            }
+            const key = deriveKey(bag.key, // Async factories aren't structurally hashable in a useful way, so the
+            // default key hashes the async wiring + structural fields — same
+            // instance-identity semantics ConfigurableModuleBuilder always had.
+            spec.key ? structural : {
+                inject: bag.inject,
+                useFactory: bag.useFactory,
+                useClass: bag.useClass,
+                useExisting: bag.useExisting,
+                ...structural
+            });
+            const definition = {
+                module: this,
+                key,
+                imports: bag.imports ?? [],
+                providers: buildAsyncOptionsProviders(optionsToken, factoryMethodName, bag, structural)
+            };
+            return transform(applyContributions(definition, structural, key), {
+                ...extrasDefaults,
+                ...structural
+            });
+        }
+    });
+    return {
+        ConfigurableModuleClass: GeneratedModuleClass,
+        MODULE_OPTIONS_TOKEN: optionsToken,
+        // Type-only sentinels — never read at runtime.
+        OPTIONS_TYPE: undefined,
+        ASYNC_OPTIONS_TYPE: undefined
+    };
+}
+/**
+ * Lower `useFactory`/`useClass`/`useExisting` async options into provider
+ * registrations. Structural fields from the call site merge UNDER the resolved
+ * options (`{ ...structural, ...resolved }`) so sync-declared fields act as
+ * defaults and the factory stays authoritative.
+ */ export function buildAsyncOptionsProviders(optionsToken, factoryMethodName, async, structural = {}) {
+    const hasStructural = Object.keys(structural).length > 0;
+    const merge = (resolved)=>resolved instanceof Promise ? resolved.then((o)=>({
+                ...structural,
+                ...o
+            })) : {
+            ...structural,
+            ...resolved
+        };
+    if (async.useFactory) {
+        const factory = async.useFactory;
+        return [
+            {
+                provide: optionsToken,
+                // No structural fields → pass the caller's factory through untouched
+                // (function identity preserved; nothing to merge).
+                useFactory: hasStructural ? (...deps)=>merge(factory(...deps)) : factory,
+                inject: async.inject ?? []
+            }
+        ];
+    }
+    if (async.useClass) {
+        const factoryClass = async.useClass;
+        return [
+            factoryClass,
+            {
+                provide: optionsToken,
+                useFactory: (instance)=>merge(instance[factoryMethodName]()),
+                inject: [
+                    factoryClass
+                ]
+            }
+        ];
+    }
+    if (async.useExisting) {
+        return [
+            {
+                provide: optionsToken,
+                useFactory: (instance)=>merge(instance[factoryMethodName]()),
+                inject: [
+                    async.useExisting
+                ]
+            }
+        ];
+    }
+    throw new Error('Async module options require one of `useFactory`, `useClass`, or `useExisting`.');
+}

package/dist/module/index.d.ts

@@ -1,5 +1,9 @@
 export { Global, Module, isModule, getModuleMetadata, defineDynamicModule, } from './decorators';
 export { stableHash } from './stable-hash';
+export { ConfigurableModuleBuilder, defineConfigurableModule, moduleKey, } from './configurable-module.builder';
+export { defineModule, buildAsyncOptionsProviders, type DefineModuleSpec, type GlobalComponentSlot, type ModuleContributions, type ModuleSetupContext, } from './define-module';
+export { lazyProvider, moduleToken, provideGlobal, sideEffectModule, type LazyProviderSpec, } from './lazy-provider';
+export type { ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, } from './configurable-module.types';
 export { ModuleLoader } from './module-loader';
 export { MiddlewareBuilder } from './middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, MiddlewareRouteDefinition, NestModule, RouteInfo, } from './middleware';

package/dist/module/index.js

@@ -1,4 +1,7 @@
 export { Global, Module, isModule, getModuleMetadata, defineDynamicModule } from "./decorators.js";
 export { stableHash } from "./stable-hash.js";
+export { ConfigurableModuleBuilder, defineConfigurableModule, moduleKey } from "./configurable-module.builder.js";
+export { defineModule, buildAsyncOptionsProviders } from "./define-module.js";
+export { lazyProvider, moduleToken, provideGlobal, sideEffectModule } from "./lazy-provider.js";
 export { ModuleLoader } from "./module-loader.js";
 export { MiddlewareBuilder } from "./middleware.js";

package/dist/module/lazy-provider.d.ts

@@ -0,0 +1,65 @@
+import { InjectionToken, type InferTokens, type ProviderOptions, type Token, type Type } from '../container/types';
+import type { ComponentType, DynamicModule } from '../registry/types';
+import type { ModuleContributions } from './define-module';
+export interface LazyProviderSpec<T, Inject extends readonly Token<unknown>[]> {
+    /** Token under which the memoized thunk `() => T` is provided. */
+    provide: Token<() => T>;
+    inject?: Inject;
+    useFactory: (...deps: InferTokens<Inject>) => T;
+    /** Memoize the first call's result (default true). */
+    memoize?: boolean;
+}
+/**
+ * Provide a zero-arg thunk `() => T` whose factory runs on FIRST CALL, not at
+ * provider construction — for values that don't exist yet when the module
+ * graph is built (Cloudflare bindings are only live at request time).
+ *
+ * The shared primitive replacing the hand-rolled
+ * `useFactory: (...deps) => () => build(...deps)` closure that auth and
+ * storage each copy-pasted.
+ *
+ * ```ts
+ * lazyProvider({
+ *   provide: STORAGE_DRIVER_BUILDER,
+ *   inject: [MODULE_OPTIONS_TOKEN],
+ *   useFactory: (options) => options.driver(),
+ * })
+ * ```
+ */
+export declare function lazyProvider<T, const Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]>(spec: LazyProviderSpec<T, Inject>): ProviderOptions;
+/**
+ * The one idiom for registering an app-wide component from a module's
+ * providers. Returns registrations to spread:
+ *
+ * ```ts
+ * providers: [MyService, ...provideGlobal('guard', AuthGuard)]
+ * ```
+ *
+ * Class components are registered as providers and wired via `useExisting`
+ * (so DI constructs them with their dependencies); instances via `useValue`.
+ * Inside `defineModule`, prefer the equivalent `global:` contribution slot.
+ */
+export declare function provideGlobal(kind: ComponentType, component: Type | object): Array<Type | ProviderOptions>;
+/**
+ * A first-class side-effect-only module: contributes providers/exports without
+ * being a configurable module — the supported form of the "empty marker
+ * module" trick (i18n's `registerMessages`). Content-derived `key` makes
+ * identical contributions dedup (HMR-idempotent) while distinct ones coexist.
+ *
+ * ```ts
+ * export function registerMessages(messages: Messages): DynamicModule {
+ *   return sideEffectModule('I18nMessages', {
+ *     providers: [{ provide: I18N_MESSAGES, useValue: messages }],
+ *     exports: [I18N_MESSAGES],
+ *   });
+ * }
+ * ```
+ */
+export declare function sideEffectModule(name: string, contributions?: Omit<ModuleContributions, 'global'> & {
+    key?: string;
+}): DynamicModule;
+/**
+ * Blessed token-minting convention: always an `InjectionToken` (never a raw
+ * string), named for diagnostics. Namespace it `'<pkg>:<area>:<thing>'`.
+ */
+export declare function moduleToken<T>(name: string): InjectionToken<T>;

package/dist/module/lazy-provider.js

@@ -0,0 +1,111 @@
+import { InjectionToken } from "../container/types.js";
+import { Module } from "./decorators.js";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
+import { stableHash } from "./stable-hash.js";
+/**
+ * Provide a zero-arg thunk `() => T` whose factory runs on FIRST CALL, not at
+ * provider construction — for values that don't exist yet when the module
+ * graph is built (Cloudflare bindings are only live at request time).
+ *
+ * The shared primitive replacing the hand-rolled
+ * `useFactory: (...deps) => () => build(...deps)` closure that auth and
+ * storage each copy-pasted.
+ *
+ * ```ts
+ * lazyProvider({
+ *   provide: STORAGE_DRIVER_BUILDER,
+ *   inject: [MODULE_OPTIONS_TOKEN],
+ *   useFactory: (options) => options.driver(),
+ * })
+ * ```
+ */ export function lazyProvider(spec) {
+    const memoize = spec.memoize ?? true;
+    return {
+        provide: spec.provide,
+        inject: [
+            ...spec.inject ?? []
+        ],
+        useFactory: (...deps)=>{
+            const build = ()=>spec.useFactory(...deps);
+            if (!memoize) return build;
+            let cached;
+            return ()=>(cached ??= {
+                    value: build()
+                }).value;
+        }
+    };
+}
+const GLOBAL_COMPONENT_TOKENS = {
+    guard: APP_GUARD,
+    pipe: APP_PIPE,
+    interceptor: APP_INTERCEPTOR,
+    filter: APP_FILTER,
+    middleware: APP_MIDDLEWARE
+};
+/**
+ * The one idiom for registering an app-wide component from a module's
+ * providers. Returns registrations to spread:
+ *
+ * ```ts
+ * providers: [MyService, ...provideGlobal('guard', AuthGuard)]
+ * ```
+ *
+ * Class components are registered as providers and wired via `useExisting`
+ * (so DI constructs them with their dependencies); instances via `useValue`.
+ * Inside `defineModule`, prefer the equivalent `global:` contribution slot.
+ */ export function provideGlobal(kind, component) {
+    const token = GLOBAL_COMPONENT_TOKENS[kind];
+    if (typeof component === 'function') {
+        return [
+            component,
+            {
+                provide: token,
+                useExisting: component
+            }
+        ];
+    }
+    return [
+        {
+            provide: token,
+            useValue: component
+        }
+    ];
+}
+/**
+ * A first-class side-effect-only module: contributes providers/exports without
+ * being a configurable module — the supported form of the "empty marker
+ * module" trick (i18n's `registerMessages`). Content-derived `key` makes
+ * identical contributions dedup (HMR-idempotent) while distinct ones coexist.
+ *
+ * ```ts
+ * export function registerMessages(messages: Messages): DynamicModule {
+ *   return sideEffectModule('I18nMessages', {
+ *     providers: [{ provide: I18N_MESSAGES, useValue: messages }],
+ *     exports: [I18N_MESSAGES],
+ *   });
+ * }
+ * ```
+ */ export function sideEffectModule(name, contributions = {}) {
+    const { key, ...rest } = contributions;
+    // Computed-property-name idiom: mints a class whose .name is `name` without
+    // dynamic code evaluation (edge-safe; no `new Function`).
+    const moduleClass = {
+        [name]: class {
+        }
+    }[name];
+    Module({})(moduleClass);
+    return {
+        module: moduleClass,
+        key: key ?? stableHash(rest),
+        providers: rest.providers ?? [],
+        controllers: rest.controllers ?? [],
+        imports: rest.imports ?? [],
+        exports: rest.exports ?? []
+    };
+}
+/**
+ * Blessed token-minting convention: always an `InjectionToken` (never a raw
+ * string), named for diagnostics. Namespace it `'<pkg>:<area>:<thing>'`.
+ */ export function moduleToken(name) {
+    return new InjectionToken(name);
+}

package/dist/openapi/document.js

@@ -1,5 +1,5 @@
-import { METADATA_KEYS, ParamType } from "../constants.js";
-import { getCrudBridge } from "../http/crud-bridge.js";
+import { ParamType } from "../constants.js";
+import { getRouteContributors } from "../http/route-contributor.js";
 import { getMetadata } from "../metadata.js";
 import { collectControllers } from "../module/graph.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
@@ -215,25 +215,26 @@ export function createOpenApiDocument(rootModule, options = {}) {
             paths[pathString] = pathItem;
         }
     }
-    // Second pass: include `@Crud()`-generated routes via the registered
-    // CrudBridge. The bridge knows how to turn its own metadata config into
-    // OpenAPI path items; this loop is silent when no bridge is registered or
-    // no controller carries `vela:crud` metadata, so consumers without
-    // `@velajs/crud` see no behavioral change.
-    const bridge = getCrudBridge();
-    if (bridge) {
+    // Second pass: include contributor-generated routes (e.g. `@Crud()` via
+    // `@velajs/crud`'s registered RouteContributor). Silent when no contributor
+    // is registered or no controller carries claiming metadata, so consumers
+    // without contributor packages see no behavioral change.
+    for (const contributor of getRouteContributors()){
+        if (!contributor.buildOpenApiPaths) continue;
         for (const controller of controllers){
-            const crudConfig = getMetadata(METADATA_KEYS.CRUD, controller);
-            if (!crudConfig) continue;
+            const meta = getMetadata(contributor.claimsMetaKey, controller);
+            if (meta === undefined) continue;
             const controllerPrefix = MetadataRegistry.getControllerPath(controller);
-            const crudPaths = bridge.buildOpenApiPaths(controller, crudConfig, {
+            const contributedPaths = contributor.buildOpenApiPaths({
+                controller: controller,
+                meta,
                 globalPrefix,
                 controllerPrefix
             });
-            for (const [pathKey, pathItem] of Object.entries(crudPaths)){
+            for (const [pathKey, pathItem] of Object.entries(contributedPaths)){
                 // Verb-level merge: a hand-written `@Get('/')` on the same controller
-                // is preserved when the bridge contributes `post`/`patch`/etc. on
-                // the same path key.
+                // is preserved when the contributor adds `post`/`patch`/etc. on the
+                // same path key.
                 paths[pathKey] = {
                     ...paths[pathKey] ?? {},
                     ...pathItem

package/dist/pipeline/component.manager.d.ts

@@ -1,19 +1,25 @@
 import type { Container } from '../container/container';
 import type { ComponentType, ComponentTypeMap, Constructor, FilterType, GuardType, InterceptorType, MiddlewareType, PipeType } from '../registry/types';
 import type { ArgumentMetadata, CanActivate, ExceptionFilter, ExecutionContext, NestInterceptor, NestMiddleware, PipeTransform } from './types';
+/**
+ * Component registration + resolution for the controller/handler tiers.
+ * App-wide (global) components have exactly ONE source: the per-app
+ * `RouteManager` (`APP_*` provider tokens + `useGlobalX()`) — callers merge
+ * `routeManager.getGlobalComponents()` with {@link getScopedComponents}.
+ *
+ * Stateless by design: no process-global container (two apps in one process
+ * never cross-talk) — every `resolve*` takes the resolving container.
+ */
 export declare class ComponentManager {
-    private static container;
-    static init(container: Container): void;
-    static registerGlobal<T extends ComponentType>(type: T, ...components: ComponentTypeMap[T][]): void;
     static registerController<T extends ComponentType>(type: T, controller: Constructor, ...components: ComponentTypeMap[T][]): void;
     static registerHandler<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol, ...components: ComponentTypeMap[T][]): void;
-    static getComponents<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol): ComponentTypeMap[T][];
+    static getScopedComponents<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol): ComponentTypeMap[T][];
     private static resolveAll;
-    static resolveMiddleware(items: MiddlewareType[]): NestMiddleware[];
-    static resolveGuards(items: GuardType[]): CanActivate[];
-    static resolvePipes(items: PipeType[]): PipeTransform[];
-    static resolveInterceptors(items: InterceptorType[]): NestInterceptor[];
-    static resolveFilters(items: FilterType[]): ExceptionFilter[];
+    static resolveMiddleware(items: MiddlewareType[], container: Container): NestMiddleware[];
+    static resolveGuards(items: GuardType[], container: Container): CanActivate[];
+    static resolvePipes(items: PipeType[], container: Container): PipeTransform[];
+    static resolveInterceptors(items: InterceptorType[], container: Container): NestInterceptor[];
+    static resolveFilters(items: FilterType[], container: Container): ExceptionFilter[];
     static executePipes(value: unknown, metadata: ArgumentMetadata, pipes: PipeTransform[]): Promise<unknown>;
     static runInterceptorChain(interceptors: NestInterceptor[], context: ExecutionContext, coreHandler: () => Promise<unknown>): Promise<unknown>;
 }

package/dist/pipeline/component.manager.js

@@ -1,18 +1,18 @@
 import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { PipelineRunner } from "./pipeline-runner.js";
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
-export class ComponentManager {
-    static container;
-    static init(container) {
-        this.container = container;
-    }
-    // 3-level registration
-    static registerGlobal(type, ...components) {
-        for (const component of components){
-            MetadataRegistry.registerGlobal(type, component);
-        }
-    }
+/**
+ * Component registration + resolution for the controller/handler tiers.
+ * App-wide (global) components have exactly ONE source: the per-app
+ * `RouteManager` (`APP_*` provider tokens + `useGlobalX()`) — callers merge
+ * `routeManager.getGlobalComponents()` with {@link getScopedComponents}.
+ *
+ * Stateless by design: no process-global container (two apps in one process
+ * never cross-talk) — every `resolve*` takes the resolving container.
+ */ export class ComponentManager {
+    // Scoped registration: controller → handler
     static registerController(type, controller, ...components) {
         for (const component of components){
             MetadataRegistry.registerController(type, controller, component);
@@ -23,34 +23,32 @@ export class ComponentManager {
             MetadataRegistry.registerHandler(type, controller, handlerName, component);
         }
     }
-    // 3-level resolution: global → controller → handler
-    static getComponents(type, controller, handlerName) {
-        const controllerComponents = MetadataRegistry.getController(type, controller);
-        const handlerComponents = MetadataRegistry.getHandler(type, controller, handlerName);
+    // Scoped resolution: controller → handler. App-wide components come from
+    // RouteManager (APP_* tokens + useGlobalX()) — merged by the caller.
+    static getScopedComponents(type, controller, handlerName) {
         return [
-            ...MetadataRegistry.getGlobal(type),
-            ...controllerComponents,
-            ...handlerComponents
+            ...MetadataRegistry.getController(type, controller),
+            ...MetadataRegistry.getHandler(type, controller, handlerName)
         ];
     }
-    // Type-specific resolvers
-    static resolveAll(items, methodKey) {
-        return items.map((item)=>isObject(item) && methodKey in item ? item : this.container.resolve(item));
+    // Type-specific resolvers — explicit container, always.
+    static resolveAll(items, methodKey, container) {
+        return items.map((item)=>isObject(item) && methodKey in item ? item : container.resolve(item));
     }
-    static resolveMiddleware(items) {
-        return this.resolveAll(items, 'use');
+    static resolveMiddleware(items, container) {
+        return this.resolveAll(items, 'use', container);
     }
-    static resolveGuards(items) {
-        return this.resolveAll(items, 'canActivate');
+    static resolveGuards(items, container) {
+        return this.resolveAll(items, 'canActivate', container);
     }
-    static resolvePipes(items) {
-        return this.resolveAll(items, 'transform');
+    static resolvePipes(items, container) {
+        return this.resolveAll(items, 'transform', container);
     }
-    static resolveInterceptors(items) {
-        return this.resolveAll(items, 'intercept');
+    static resolveInterceptors(items, container) {
+        return this.resolveAll(items, 'intercept', container);
     }
-    static resolveFilters(items) {
-        return this.resolveAll(items, 'catch');
+    static resolveFilters(items, container) {
+        return this.resolveAll(items, 'catch', container);
     }
     // Pipe execution
     static async executePipes(value, metadata, pipes) {
@@ -60,21 +58,9 @@ export class ComponentManager {
         }
         return transformed;
     }
-    // Interceptor chain (onion pattern)
+    // Interceptor chain (onion pattern) — canonical implementation lives in
+    // PipelineRunner; kept here as a stable alias.
     static async runInterceptorChain(interceptors, context, coreHandler) {
-        if (interceptors.length === 0) {
-            return coreHandler();
-        }
-        let next = {
-            handle: coreHandler
-        };
-        for(let i = interceptors.length - 1; i >= 0; i--){
-            const interceptor = interceptors[i];
-            const currentNext = next;
-            next = {
-                handle: ()=>interceptor.intercept(context, currentNext)
-            };
-        }
-        return next.handle();
+        return PipelineRunner.chainInterceptors(interceptors, context, coreHandler);
     }
 }

package/dist/pipeline/index.d.ts

@@ -1,4 +1,6 @@
 export { ComponentManager } from './component.manager';
+export { PipelineRunner } from './pipeline-runner';
+export type { PipelineRunOptions } from './pipeline-runner';
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch, } from './decorators';
 export { SetMetadata, Reflector } from './reflector';
 export type { ReflectableDecorator, CreateDecoratorOptions } from './reflector';

package/dist/pipeline/index.js

@@ -1,4 +1,5 @@
 export { ComponentManager } from "./component.manager.js";
+export { PipelineRunner } from "./pipeline-runner.js";
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch } from "./decorators.js";
 export { SetMetadata, Reflector } from "./reflector.js";
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./tokens.js";

package/dist/pipeline/pipeline-runner.d.ts

@@ -0,0 +1,31 @@
+import type { CanActivate, ExecutionContext, NestInterceptor } from './types';
+export interface PipelineRunOptions {
+    context: ExecutionContext;
+    /** Pre-merged (global ++ scoped), pre-instantiated. */
+    guards: CanActivate[];
+    interceptors: NestInterceptor[];
+    /** Extract handler arguments (pipes already bound inside the closure). */
+    resolveArgs: () => Promise<unknown[]>;
+    /** Call the actual handler. */
+    invoke: (args: unknown[]) => Promise<unknown>;
+    /**
+     * HTTP runs argument extraction + pipes BEFORE guards (a deliberate vela
+     * deviation — see handler-executor); WebSocket runs guards first. Default
+     * false (guards first).
+     */
+    argsBeforeGuards?: boolean;
+    /** Error thrown when a guard rejects (default `ForbiddenException`). */
+    onGuardReject?: () => Error;
+}
+/**
+ * The transport-agnostic guard → pipe → interceptor execution core shared by
+ * the HTTP `HandlerExecutor` and the WebSocket `WsDispatcher` (and any future
+ * entrypoint dispatcher: queue consumers, scheduled jobs, …). Exception
+ * FILTERS stay with the caller — their terminal behavior is transport-specific
+ * (HTTP maps to a Response, WS sends an error frame).
+ */
+export declare class PipelineRunner {
+    static run(options: PipelineRunOptions): Promise<unknown>;
+    /** Interceptor onion — innermost is the core handler. */
+    static chainInterceptors(interceptors: NestInterceptor[], context: ExecutionContext, coreHandler: () => Promise<unknown>): Promise<unknown>;
+}