@velajs/vela 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+A sanctioned per-request injectable lands as a framework primitive, and the metadata-store unification finally has its regression tests.
+
+### New
+
+- **`REQUEST_CONTEXT` injectable.** A request-scoped primitive carrying a stable `id` (mirrored from inbound `x-request-id` if present, else `crypto.randomUUID()`), `receivedAt`, the raw `Request`, the Hono `Context`, and a typed `set/get/has` bag for cross-cutting metadata. Seeded by `RouteManager` into each per-request child container; resolves through `@Inject(REQUEST_CONTEXT)` from any request-scoped service. No `AsyncLocalStorage` — edge-runtime contract intact (verified live under workerd via `pnpm test:workers`).
+
+  ```ts
+  import { Inject, Injectable, Scope, REQUEST_CONTEXT } from '@velajs/vela';
+  import type { RequestContext } from '@velajs/vela';
+
+  @Injectable({ scope: Scope.REQUEST })
+  class TenantResolver {
+    constructor(@Inject(REQUEST_CONTEXT) private readonly ctx: RequestContext) {}
+    resolve() {
+      return this.ctx.hono.req.header('x-tenant') ?? 'default';
+    }
+  }
+  ```
+
+### Internal cleanup
+
+- **Metadata stacking + funnel coverage** (audit #8 follow-up). New `metadata-stacking.test.ts` asserts `appendCustomHandlerMeta` is order-deterministic, `Reflect.defineMetadata` round-trips through `MetadataRegistry`'s typed slots, `MetadataRegistry.reset()` clears `classMeta`/`handlerMeta`, and class+handler `@SetMetadata` on the same key remain independent.
+- **`NestModule.configure()` regression coverage** (audit #4 follow-up). New `configure-resolution.test.ts` asserts configure-time DI works (modules can constructor-inject providers from their own scope), synchronous errors thrown from `configure()` propagate, and unresolvable constructor deps fail loudly rather than silently skipping middleware setup.
+- **Edge-safe contract documented** (audit #7 follow-up). README now states the contract explicitly: the main export is edge-safe and audited in CI by `src/__tests__/edge-runtime-audit.test.ts`; `@velajs/vela/schedule-node` is the one opt-in Node/Bun carve-out.
+- **`RouteManager` split into focused units** (audit #9 follow-up). New files `argument-resolver.ts`, `handler-executor.ts`, `response-mapper.ts`, and `instantiate.ts` carry parameter extraction, the per-request orchestration closure, response/redirect mapping, and the container-aware factory. `RouteManager` is now focused on Hono route registration and path composition. Internal-only refactor — no public API change, no behavior change.
+- **Stale `WeakMap` comment removed** from `MetadataRegistry.reset()` — the WeakMap fallback was retired in 1.1.0; the comment was documentation drift.
+- **`Container.setRequestInstance(token, value)`** — public method to pre-seed the per-request cache. Used by `RouteManager` to populate `REQUEST_CONTEXT` before any handler resolution runs.
+
+## 1.3.0
+
 Module boundaries are enforced. NestJS-shape: a service cannot resolve dependencies from a module it didn't import. Bootstrap is consolidated into a single primitive, discovery failures are diagnostically routed, and a generic plugin composer is included.
 
 ### New

package/README.md

@@ -73,6 +73,19 @@ Vela runs on any runtime that supports the Web Standards API:
 
 No Node.js-specific APIs (`node:fs`, `Buffer`, `process`) are used.
 
+### Edge-safe contract
+
+The **main export** (`@velajs/vela`) is edge-safe by contract — no `node:*` imports, no `Buffer`, no `process`, no `setInterval`, no `Bun.serve`. This is enforced in CI by [`src/__tests__/edge-runtime-audit.test.ts`](src/__tests__/edge-runtime-audit.test.ts), which fails the build if any file under `src/` references a forbidden API.
+
+One subpath, **`@velajs/vela/schedule-node`**, is an opt-in Node/Bun adapter for `setInterval`-based job execution. It uses runtime-specific APIs by design and is **excluded from the edge-runtime audit**. Edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge) should not import it — use platform cron triggers instead (e.g., `@velajs/cloudflare` ≥ 0.2.0 dispatches `@Cron` jobs via the Workers `scheduled()` handler).
+
+```ts
+// Node / Bun only — opt-in
+import { ScheduleNodeModule } from '@velajs/vela/schedule-node';
+```
+
+The other subpaths (`@velajs/vela/internal`, `@velajs/vela/streaming`) follow the main export's edge-safe contract.
+
 ## Dynamic modules
 
 Configurable modules use `forRoot` (sync) and `forRootAsync` (DI-resolved):

package/dist/container/container.d.ts

@@ -15,6 +15,7 @@ export declare class Container {
     private recordOrigin;
     registerScope(scope: ModuleScope): void;
     markGlobalToken(token: Token): void;
+    setRequestInstance(token: Token, value: unknown): void;
     getDiagnostics(): Diagnostics;
     resolve<T>(token: Token<T>, requestingModuleId?: string): T;
     resolveAll<T>(token: Token<T>, requestingModuleId?: string): T[];

package/dist/container/container.js

@@ -86,6 +86,14 @@ export class Container {
     markGlobalToken(token) {
         this.globals.add(token);
     }
+    // Pre-seed the per-request cache. Only meaningful on a child container
+    // produced by createChild() — the root's requestInstances map is unused.
+    // Used by RouteManager to populate framework-provided request-scope
+    // values (REQUEST_CONTEXT) before any handler resolution runs, so the
+    // provider's factory never fires on the request path.
+    setRequestInstance(token, value) {
+        this.requestInstances.set(token, value);
+    }
     getDiagnostics() {
         return this.diagnostics;
     }

package/dist/factory/bootstrap.js

@@ -1,5 +1,7 @@
+import { Scope } from "../constants.js";
 import { Container } from "../container/container.js";
 import { ModuleRef } from "../container/module-ref.js";
+import { REQUEST_CONTEXT } from "../http/request-context.js";
 import { RouteManager } from "../http/route.manager.js";
 import { ModuleLoader } from "../module/module-loader.js";
 import { bindAppProviders } from "../pipeline/app-providers.js";
@@ -39,6 +41,18 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
     ]){
         container.markGlobalToken(t);
     }
+    // REQUEST_CONTEXT is seeded into each request-scoped child by RouteManager
+    // before any handler resolves it (see route.manager.ts:getRequestContainer).
+    // The factory throws so misuse outside the request path surfaces immediately
+    // instead of materializing a phantom context.
+    container.register({
+        provide: REQUEST_CONTEXT,
+        scope: Scope.REQUEST,
+        useFactory: ()=>{
+            throw new Error('REQUEST_CONTEXT can only be resolved inside a request — ' + 'it is seeded by RouteManager when the request enters the pipeline.');
+        }
+    });
+    container.markGlobalToken(REQUEST_CONTEXT);
     const routeManager = new RouteManager(container, options);
     ComponentManager.init(container);
     const loader = new ModuleLoader(container, routeManager);

package/dist/http/argument-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from 'hono';
+import type { Container } from '../container/container';
+import type { PipeTransform } from '../pipeline/types';
+import type { ParamMetadata } from './types';
+export declare class ArgumentResolver {
+    private readonly ipExtractor;
+    constructor(ipExtractor: (c: Context) => string | null);
+    extract(c: Context, paramMetadata: ParamMetadata[], pipes: PipeTransform[], requestContainer: Container, paramTypes?: unknown[]): Promise<unknown[]>;
+    private extractParam;
+}

package/dist/http/argument-resolver.js

@@ -0,0 +1,89 @@
+import { getCookie } from "hono/cookie";
+import { ParamType } from "../constants.js";
+import { instantiate } from "./instantiate.js";
+const PARAM_EXTRACTORS = new Map([
+    [
+        ParamType.PARAM,
+        (c, p)=>p.name ? c.req.param(p.name) : c.req.param()
+    ],
+    [
+        ParamType.QUERY,
+        (c, p)=>p.name ? c.req.query(p.name) : c.req.query()
+    ],
+    [
+        ParamType.BODY,
+        async (c, p)=>{
+            let body;
+            try {
+                body = await c.req.json();
+            } catch  {
+                return undefined;
+            }
+            return p.name && body !== null && typeof body === 'object' ? body[p.name] : body;
+        }
+    ],
+    [
+        ParamType.HEADERS,
+        (c, p)=>p.name ? c.req.header(p.name) : c.req.header()
+    ],
+    [
+        ParamType.REQUEST,
+        (c)=>c
+    ],
+    [
+        ParamType.RESPONSE,
+        (c)=>c
+    ],
+    [
+        ParamType.COOKIE,
+        (c, p)=>p.name ? getCookie(c, p.name) : getCookie(c)
+    ],
+    [
+        ParamType.RAW_BODY,
+        async (c)=>new Uint8Array(await c.req.arrayBuffer())
+    ]
+]);
+// Pulls handler arguments from the request, applies shared pipes (global +
+// controller + method) and then per-param pipes. Empty paramMetadata returns
+// `[c]` to match the old direct-Hono-handler shape — a back-compat behavior
+// the framework's tests rely on.
+export class ArgumentResolver {
+    ipExtractor;
+    constructor(ipExtractor){
+        this.ipExtractor = ipExtractor;
+    }
+    async extract(c, paramMetadata, pipes, requestContainer, paramTypes) {
+        if (paramMetadata.length === 0) {
+            return [
+                c
+            ];
+        }
+        const maxIndex = paramMetadata.at(-1).index;
+        const args = new Array(maxIndex + 1).fill(undefined);
+        for (const param of paramMetadata){
+            let value = await this.extractParam(c, param);
+            const metadata = {
+                type: param.type,
+                data: param.name,
+                metatype: paramTypes?.[param.index]
+            };
+            for (const pipe of pipes){
+                value = await pipe.transform(value, metadata);
+            }
+            if (param.pipes && param.pipes.length > 0) {
+                for (const paramPipe of param.pipes){
+                    const pipeInstance = instantiate(paramPipe, requestContainer);
+                    value = await pipeInstance.transform(value, metadata);
+                }
+            }
+            args[param.index] = value;
+        }
+        return args;
+    }
+    extractParam(c, param) {
+        if (param.type === ParamType.IP) return this.ipExtractor(c);
+        const extractor = PARAM_EXTRACTORS.get(param.type);
+        if (extractor) return extractor(c, param);
+        return param.factory ? param.factory(param.name, c) : undefined;
+    }
+}

package/dist/http/handler-executor.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from 'hono';
+import type { Container } from '../container/container';
+import type { Token, Type } from '../container/types';
+import type { CanActivate, ExceptionFilter, NestInterceptor, PipeTransform } from '../pipeline/types';
+import type { FilterType, GuardType, InterceptorType, ParameterMetadata, PipeType } from '../registry/types';
+import type { ArgumentResolver } from './argument-resolver';
+import type { RouteMetadata } from './types';
+export interface HandlerGlobals {
+    guards: Array<GuardType | Token<CanActivate>>;
+    pipes: Array<PipeType | Token<PipeTransform>>;
+    interceptors: Array<InterceptorType | Token<NestInterceptor>>;
+    filters: Array<FilterType | Token<ExceptionFilter>>;
+}
+export declare class HandlerExecutor {
+    private readonly argumentResolver;
+    private readonly getGlobals;
+    private readonly getRequestContainer;
+    constructor(argumentResolver: ArgumentResolver, getGlobals: () => HandlerGlobals, getRequestContainer: (c: Context) => Container);
+    create(route: RouteMetadata, controller: Type, allParamMetadata: Map<string | symbol, ParameterMetadata[]>): (c: Context) => Promise<Response>;
+}

package/dist/http/handler-executor.js

@@ -0,0 +1,108 @@
+import { ForbiddenException, HttpException } from "../errors/http-exception.js";
+import { ComponentManager } from "../pipeline/component.manager.js";
+import { shouldFilterCatch } from "../pipeline/decorators.js";
+import { getHttpCode, getRedirect, getResponseHeaders } from "./decorators.js";
+import { buildExecutionContext } from "./execution-context.js";
+import { instantiateMany } from "./instantiate.js";
+import { applyResponseHeaders, mapRedirect, mapResponse } from "./response-mapper.js";
+// Builds the per-request closure that runs guards, pipes, interceptors, the
+// handler itself, and exception filters. Pure orchestration — Hono route
+// registration stays in RouteManager. Globals are read via a callback so
+// post-create additions (`useGlobalGuards`, etc.) propagate to subsequent
+// requests without rebuilding routes.
+export class HandlerExecutor {
+    argumentResolver;
+    getGlobals;
+    getRequestContainer;
+    constructor(argumentResolver, getGlobals, getRequestContainer){
+        this.argumentResolver = argumentResolver;
+        this.getGlobals = getGlobals;
+        this.getRequestContainer = getRequestContainer;
+    }
+    create(route, controller, allParamMetadata) {
+        const paramMetadata = (allParamMetadata.get(route.handlerName) || []).sort((a, b)=>a.index - b.index);
+        // Read param types once at build time for metatype population.
+        // Routed via Reflect so the polyfill funnels both src-level and dist-level
+        // consumers to the same registry (matters in tests that import from dist).
+        const paramTypes = Reflect.getMetadata('design:paramtypes', controller.prototype, route.handlerName);
+        const methodGuards = ComponentManager.getComponents('guard', controller, route.handlerName);
+        const methodPipes = ComponentManager.getComponents('pipe', controller, route.handlerName);
+        const methodInterceptors = ComponentManager.getComponents('interceptor', controller, route.handlerName);
+        // Filters: reverse order (handler → controller → global) — closest to handler runs first
+        const methodFilters = [
+            ...ComponentManager.getComponents('filter', controller, route.handlerName)
+        ].reverse();
+        const httpCode = getHttpCode(controller, route.handlerName);
+        const responseHeaders = getResponseHeaders(controller, route.handlerName);
+        const redirect = getRedirect(controller, route.handlerName);
+        return async (c)=>{
+            // Combine global + method at request time so post-create registrations propagate.
+            const requestContainer = this.getRequestContainer(c);
+            const globals = this.getGlobals();
+            const guards = [
+                ...instantiateMany(globals.guards, requestContainer),
+                ...instantiateMany(methodGuards, requestContainer)
+            ];
+            const pipes = [
+                ...instantiateMany(globals.pipes, requestContainer),
+                ...instantiateMany(methodPipes, requestContainer)
+            ];
+            const interceptors = [
+                ...instantiateMany(globals.interceptors, requestContainer),
+                ...instantiateMany(methodInterceptors, requestContainer)
+            ];
+            const filters = [
+                ...instantiateMany(methodFilters, requestContainer),
+                ...instantiateMany(globals.filters, requestContainer)
+            ];
+            const executionContext = buildExecutionContext(c, controller, route.handlerName);
+            try {
+                const instance = requestContainer.resolve(controller);
+                // 1. Extract args + run pipes (vela order: args before guards).
+                const args = await this.argumentResolver.extract(c, paramMetadata, pipes, requestContainer, paramTypes);
+                // 2. Guards (fail-fast).
+                for (const guard of guards){
+                    const canActivate = await guard.canActivate(executionContext);
+                    if (!canActivate) {
+                        throw new ForbiddenException();
+                    }
+                }
+                // 3. Get handler method.
+                const method = Reflect.get(instance, route.handlerName);
+                if (typeof method !== 'function') {
+                    throw new Error(`Method ${String(route.handlerName)} not found on controller`);
+                }
+                // 4. Build core handler.
+                const coreHandler = async ()=>Reflect.apply(method, instance, args);
+                // 5. Run interceptor chain.
+                const result = await ComponentManager.runInterceptorChain(interceptors, executionContext, coreHandler);
+                if (redirect) {
+                    return mapRedirect(c, result, redirect);
+                }
+                const response = mapResponse(c, result, httpCode);
+                applyResponseHeaders(response, responseHeaders);
+                return response;
+            } catch (error) {
+                for (const filter of filters){
+                    if (shouldFilterCatch(filter, error)) {
+                        try {
+                            const filtered = await filter.catch(error, executionContext);
+                            return mapResponse(c, filtered);
+                        } catch  {
+                            break;
+                        }
+                    }
+                }
+                if (error instanceof HttpException) {
+                    const response = error.getResponse();
+                    const status = error.getStatus();
+                    return c.json(response, status);
+                }
+                return c.json({
+                    statusCode: 500,
+                    message: 'Internal Server Error'
+                }, 500);
+            }
+        };
+    }
+}

package/dist/http/instantiate.d.ts

@@ -0,0 +1,4 @@
+import type { Container } from '../container/container';
+import type { Token, Type } from '../container/types';
+export declare function instantiate<T>(classOrInstance: Type<T> | Token<T> | T, container: Container): T;
+export declare function instantiateMany<T>(items: Array<Type<T> | Token<T> | T>, container: Container): T[];

package/dist/http/instantiate.js

@@ -0,0 +1,18 @@
+// Resolve a class/token through the container if registered, otherwise treat
+// the input as a plain instance. Used by RouteManager and HandlerExecutor to
+// materialize middleware, guards, pipes, interceptors, and filters per request.
+export function instantiate(classOrInstance, container) {
+    if (typeof classOrInstance === 'function') {
+        if (container.has(classOrInstance)) {
+            return container.resolve(classOrInstance);
+        }
+        return new classOrInstance();
+    }
+    if (container.has(classOrInstance)) {
+        return container.resolve(classOrInstance);
+    }
+    return classOrInstance;
+}
+export function instantiateMany(items, container) {
+    return items.map((item)=>instantiate(item, container));
+}

package/dist/http/request-context.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from 'hono';
+import { InjectionToken } from '../container/types';
+export interface RequestContext {
+    readonly id: string;
+    readonly receivedAt: Date;
+    readonly request: Request;
+    readonly hono: Context;
+    set<T>(key: string | symbol, value: T): void;
+    get<T>(key: string | symbol): T | undefined;
+    has(key: string | symbol): boolean;
+}
+export declare const REQUEST_CONTEXT: InjectionToken<RequestContext>;
+export declare function createRequestContext(c: Context): RequestContext;

package/dist/http/request-context.js

@@ -0,0 +1,22 @@
+import { InjectionToken } from "../container/types.js";
+export const REQUEST_CONTEXT = new InjectionToken('vela.RequestContext');
+export function createRequestContext(c) {
+    const bag = new Map();
+    const inboundId = c.req.raw.headers.get('x-request-id');
+    const id = inboundId && inboundId.length > 0 ? inboundId : crypto.randomUUID();
+    return {
+        id,
+        receivedAt: new Date(),
+        request: c.req.raw,
+        hono: c,
+        set (key, value) {
+            bag.set(key, value);
+        },
+        get (key) {
+            return bag.get(key);
+        },
+        has (key) {
+            return bag.has(key);
+        }
+    };
+}

package/dist/http/response-mapper.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from 'hono';
+export interface ResponseRedirect {
+    url: string;
+    statusCode: number;
+}
+export declare function mapResponse(c: Context, result: unknown, statusCode?: number): Response;
+export declare function mapRedirect(c: Context, result: unknown, redirect: ResponseRedirect): Response;
+export declare function applyResponseHeaders(response: Response, headers: Iterable<readonly [string, string]>): void;

package/dist/http/response-mapper.js

@@ -0,0 +1,42 @@
+// A handler returning `{ url, statusCode? }` may override the @Redirect-decorator
+// destination — kept identical to the previous inline behavior.
+function parseRedirectResult(result) {
+    if (typeof result !== 'object' || result === null) return undefined;
+    if (!('url' in result)) return undefined;
+    const obj = result;
+    if (typeof obj.url !== 'string') return undefined;
+    return {
+        url: obj.url,
+        ...typeof obj.statusCode === 'number' ? {
+            statusCode: obj.statusCode
+        } : {}
+    };
+}
+// Maps a controller return value to a Hono Response. `null`/`undefined` → 204
+// (empty body); strings → text; anything else → JSON. A pre-built Response
+// passes through unchanged.
+export function mapResponse(c, result, statusCode) {
+    if (result instanceof Response) {
+        return result;
+    }
+    if (result === null || result === undefined) {
+        return c.body(null, statusCode ?? 204);
+    }
+    if (typeof result === 'string') {
+        return c.text(result, statusCode ?? 200);
+    }
+    return c.json(result, statusCode ?? 200);
+}
+// Honors @Redirect on the handler. If the handler returned `{ url, statusCode? }`,
+// those override the decorator's defaults; otherwise the decorator wins.
+export function mapRedirect(c, result, redirect) {
+    const overrides = parseRedirectResult(result);
+    const finalUrl = overrides?.url ?? redirect.url;
+    const finalStatus = overrides?.statusCode ?? redirect.statusCode;
+    return c.redirect(finalUrl, finalStatus);
+}
+export function applyResponseHeaders(response, headers) {
+    for (const [name, value] of headers){
+        response.headers.set(name, value);
+    }
+}

package/dist/http/route.manager.d.ts

@@ -13,7 +13,6 @@ export interface RouteManagerOptions {
 export declare class RouteManager {
     private container;
     private static readonly METHOD_REGISTRAR;
-    private static readonly PARAM_EXTRACTORS;
     private controllers;
     private globalMiddleware;
     private globalPipes;
@@ -22,7 +21,7 @@ export declare class RouteManager {
     private globalFilters;
     private globalPrefix;
     private consumerMiddlewareDefinitions;
-    private readonly ipExtractor;
+    private readonly handlerExecutor;
     constructor(container: Container, options?: RouteManagerOptions);
     registerConsumerMiddleware(definitions: MiddlewareRouteDefinition[]): this;
     setGlobalPrefix(prefix: string): this;
@@ -36,17 +35,10 @@ export declare class RouteManager {
     useGlobalInterceptorTokens(...interceptorTokens: Array<Token<NestInterceptor>>): this;
     useGlobalFilters(...filters: FilterType[]): this;
     useGlobalFilterTokens(...filterTokens: Array<Token<ExceptionFilter>>): this;
-    private instantiate;
-    private instantiateMany;
     private getMiddlewarePriority;
     private getRequestContainer;
     registerController(controller: Type): this;
     build(): Promise<Hono>;
-    private createExecutionContext;
-    private createHandler;
-    private extractArguments;
-    private extractParam;
-    private createResponse;
     private registerRoute;
     private buildVersionedPaths;
     private compilePathMatcher;

package/dist/http/route.manager.js

@@ -1,27 +1,14 @@
 import { Hono } from "hono";
-import { getCookie } from "hono/cookie";
-import { HttpMethod, ParamType } from "../constants.js";
+import { HttpMethod } from "../constants.js";
 import { getMetadata } from "../metadata.js";
 import { joinPaths } from "../registry/paths.js";
-import { buildExecutionContext } from "./execution-context.js";
-import { ForbiddenException, HttpException } from "../errors/http-exception.js";
+import { ArgumentResolver } from "./argument-resolver.js";
+import { HandlerExecutor } from "./handler-executor.js";
+import { instantiate, instantiateMany } from "./instantiate.js";
+import { REQUEST_CONTEXT, createRequestContext } from "./request-context.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
-import { shouldFilterCatch } from "../pipeline/decorators.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
-import { getHttpCode, getRedirect, getResponseHeaders } from "./decorators.js";
 const defaultGetClientIp = (c)=>c.req.raw.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? c.req.raw.headers.get('x-real-ip') ?? null;
-function parseRedirectResult(result) {
-    if (typeof result !== 'object' || result === null) return undefined;
-    if (!('url' in result)) return undefined;
-    const obj = result;
-    if (typeof obj.url !== 'string') return undefined;
-    return {
-        url: obj.url,
-        ...typeof obj.statusCode === 'number' ? {
-            statusCode: obj.statusCode
-        } : {}
-    };
-}
 export class RouteManager {
     container;
     static METHOD_REGISTRAR = new Map([
@@ -58,48 +45,6 @@ export class RouteManager {
             (app, p, h)=>app.all(p, h)
         ]
     ]);
-    static PARAM_EXTRACTORS = new Map([
-        [
-            ParamType.PARAM,
-            (c, p)=>p.name ? c.req.param(p.name) : c.req.param()
-        ],
-        [
-            ParamType.QUERY,
-            (c, p)=>p.name ? c.req.query(p.name) : c.req.query()
-        ],
-        [
-            ParamType.BODY,
-            async (c, p)=>{
-                let body;
-                try {
-                    body = await c.req.json();
-                } catch  {
-                    return undefined;
-                }
-                return p.name && body !== null && typeof body === 'object' ? body[p.name] : body;
-            }
-        ],
-        [
-            ParamType.HEADERS,
-            (c, p)=>p.name ? c.req.header(p.name) : c.req.header()
-        ],
-        [
-            ParamType.REQUEST,
-            (c)=>c
-        ],
-        [
-            ParamType.RESPONSE,
-            (c)=>c
-        ],
-        [
-            ParamType.COOKIE,
-            (c, p)=>p.name ? getCookie(c, p.name) : getCookie(c)
-        ],
-        [
-            ParamType.RAW_BODY,
-            async (c)=>new Uint8Array(await c.req.arrayBuffer())
-        ]
-    ]);
     controllers = [];
     globalMiddleware = [];
     globalPipes = [];
@@ -108,10 +53,16 @@ export class RouteManager {
     globalFilters = [];
     globalPrefix = '';
     consumerMiddlewareDefinitions = [];
-    ipExtractor;
+    handlerExecutor;
     constructor(container, options = {}){
         this.container = container;
-        this.ipExtractor = options.getClientIp ?? defaultGetClientIp;
+        const argumentResolver = new ArgumentResolver(options.getClientIp ?? defaultGetClientIp);
+        this.handlerExecutor = new HandlerExecutor(argumentResolver, ()=>({
+                guards: this.globalGuards,
+                pipes: this.globalPipes,
+                interceptors: this.globalInterceptors,
+                filters: this.globalFilters
+            }), (c)=>this.getRequestContainer(c));
     }
     registerConsumerMiddleware(definitions) {
         this.consumerMiddlewareDefinitions.push(...definitions);
@@ -161,21 +112,6 @@ export class RouteManager {
         this.globalFilters.push(...filterTokens);
         return this;
     }
-    instantiate(classOrInstance, container) {
-        if (typeof classOrInstance === 'function') {
-            if (container.has(classOrInstance)) {
-                return container.resolve(classOrInstance);
-            }
-            return new classOrInstance();
-        }
-        if (container.has(classOrInstance)) {
-            return container.resolve(classOrInstance);
-        }
-        return classOrInstance;
-    }
-    instantiateMany(items, container) {
-        return items.map((item)=>this.instantiate(item, container));
-    }
     getMiddlewarePriority(entry) {
         if (entry == null) return 0;
         if (typeof entry === 'function') {
@@ -188,7 +124,7 @@ export class RouteManager {
             if (typeof inst.constructor?.priority === 'number') return inst.constructor.priority;
         }
         try {
-            const resolved = this.instantiate(entry, this.container);
+            const resolved = instantiate(entry, this.container);
             if (resolved && typeof resolved === 'object') {
                 const p = resolved.priority;
                 if (typeof p === 'number') return p;
@@ -206,6 +142,7 @@ export class RouteManager {
             return existing;
         }
         const child = this.container.createChild();
+        child.setRequestInstance(REQUEST_CONTEXT, createRequestContext(c));
         c.set('container', child);
         return child;
     }
@@ -235,21 +172,18 @@ export class RouteManager {
                 index,
                 priority: this.getMiddlewarePriority(entry)
             })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
-        // Register global middleware on the Hono app
         for (const { entry } of sortedGlobal){
             app.use('*', (c, next)=>{
                 const requestContainer = this.getRequestContainer(c);
-                const resolved = this.instantiate(entry, requestContainer);
+                const resolved = instantiate(entry, requestContainer);
                 return resolved.use(c, next);
             });
         }
-        // Sort consumer middleware with the same stable-by-index rule.
         const sortedConsumer = this.consumerMiddlewareDefinitions.map((def, index)=>({
                 def,
                 index,
                 priority: def.priority ?? 0
             })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
-        // Register MiddlewareConsumer-configured middleware
         for (const { def } of sortedConsumer){
             const matchRoute = this.compileRouteMatcher(def.routes);
             const matchExclude = this.compileRouteMatcher(def.excludes);
@@ -260,30 +194,27 @@ export class RouteManager {
                 const requestContainer = this.getRequestContainer(c);
                 const runChain = (index)=>{
                     if (index >= def.middleware.length) return next();
-                    const instance = this.instantiate(def.middleware[index], requestContainer);
+                    const instance = instantiate(def.middleware[index], requestContainer);
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     return instance.use(c, ()=>runChain(index + 1)).then(()=>{});
                 };
                 return runChain(0);
             });
         }
-        // First pass: register all custom routes (must come before CRUD /:id routes)
+        // First pass: register all custom routes (must come before CRUD /:id routes).
         for (const { controller, metadata, routes } of this.controllers){
             if (routes.length > 0) {
                 const allParamMetadata = MetadataRegistry.getParameters(controller);
                 for (const route of routes){
-                    // Determine effective version: route-level overrides controller-level
                     const effectiveVersion = route.version ?? metadata.version;
-                    // Build versioned paths
                     const versionedPaths = this.buildVersionedPaths(this.globalPrefix, metadata.prefix, route.path, effectiveVersion);
-                    // Register per-route middleware as Hono middleware before the handler
                     const middlewareItems = ComponentManager.getComponents('middleware', controller, route.handlerName);
-                    const handler = this.createHandler(route, controller, allParamMetadata);
+                    const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
                     for (const fullPath of versionedPaths){
                         for (const middlewareItem of middlewareItems){
                             app.use(fullPath, (c, next)=>{
                                 const requestContainer = this.getRequestContainer(c);
-                                const resolved = this.instantiate(middlewareItem, requestContainer);
+                                const resolved = instantiate(middlewareItem, requestContainer);
                                 return resolved.use(c, next);
                             });
                         }
@@ -292,7 +223,7 @@ export class RouteManager {
                 }
             }
         }
-        // Second pass: mount CRUD sub-apps (/:id routes registered last)
+        // Second pass: mount CRUD sub-apps (/:id routes registered last).
         for (const { controller, metadata } of this.controllers){
             const crudConfig = getMetadata('vela:crud', controller);
             if (crudConfig) {
@@ -301,7 +232,7 @@ export class RouteManager {
                     const { buildCrudRoutes } = await import(pkg);
                     await buildCrudRoutes(app, controller, metadata.prefix, crudConfig, {
                         globalPrefix: this.globalPrefix,
-                        globalGuards: this.instantiateMany(this.globalGuards, this.container),
+                        globalGuards: instantiateMany(this.globalGuards, this.container),
                         joinPaths
                     });
                 } catch (err) {
@@ -313,155 +244,6 @@ export class RouteManager {
         }
         return app;
     }
-    createExecutionContext(c, controller, route) {
-        return buildExecutionContext(c, controller, route.handlerName);
-    }
-    createHandler(route, controller, allParamMetadata) {
-        const paramMetadata = (allParamMetadata.get(route.handlerName) || []).sort((a, b)=>a.index - b.index);
-        // Read param types once at build time for metatype population.
-        // Routed via Reflect so the polyfill funnels both src-level and dist-level
-        // consumers to the same registry (matters in tests that import from dist).
-        const paramTypes = Reflect.getMetadata('design:paramtypes', controller.prototype, route.handlerName);
-        // Collect controller + method level components at build time
-        const methodGuards = ComponentManager.getComponents('guard', controller, route.handlerName);
-        const methodPipes = ComponentManager.getComponents('pipe', controller, route.handlerName);
-        const methodInterceptors = ComponentManager.getComponents('interceptor', controller, route.handlerName);
-        // Filters: reverse order (handler → controller → global) — closest to handler runs first
-        const methodFilters = [
-            ...ComponentManager.getComponents('filter', controller, route.handlerName)
-        ].reverse();
-        // Read response decorators at build time
-        const httpCode = getHttpCode(controller, route.handlerName);
-        const responseHeaders = getResponseHeaders(controller, route.handlerName);
-        const redirect = getRedirect(controller, route.handlerName);
-        return async (c)=>{
-            // Combine global + method at request time (allows post-create registration)
-            const requestContainer = this.getRequestContainer(c);
-            const guards = [
-                ...this.instantiateMany(this.globalGuards, requestContainer),
-                ...this.instantiateMany(methodGuards, requestContainer)
-            ];
-            const pipes = [
-                ...this.instantiateMany(this.globalPipes, requestContainer),
-                ...this.instantiateMany(methodPipes, requestContainer)
-            ];
-            const interceptors = [
-                ...this.instantiateMany(this.globalInterceptors, requestContainer),
-                ...this.instantiateMany(methodInterceptors, requestContainer)
-            ];
-            const filters = [
-                ...this.instantiateMany(methodFilters, requestContainer),
-                ...this.instantiateMany(this.globalFilters, requestContainer)
-            ];
-            const executionContext = this.createExecutionContext(c, controller, route);
-            try {
-                const instance = requestContainer.resolve(controller);
-                // 1. Extract args + run pipes
-                const args = await this.extractArguments(c, paramMetadata, pipes, requestContainer, paramTypes);
-                // 2. Guards (fail-fast)
-                for (const guard of guards){
-                    const canActivate = await guard.canActivate(executionContext);
-                    if (!canActivate) {
-                        throw new ForbiddenException();
-                    }
-                }
-                // 3. Get handler method
-                const method = Reflect.get(instance, route.handlerName);
-                if (typeof method !== 'function') {
-                    throw new Error(`Method ${String(route.handlerName)} not found on controller`);
-                }
-                // 4. Build core handler
-                const coreHandler = async ()=>Reflect.apply(method, instance, args);
-                // 5. Run interceptor chain
-                const result = await ComponentManager.runInterceptorChain(interceptors, executionContext, coreHandler);
-                // Handle @Redirect
-                if (redirect) {
-                    const overrides = parseRedirectResult(result);
-                    const finalUrl = overrides?.url ?? redirect.url;
-                    const finalStatus = overrides?.statusCode ?? redirect.statusCode;
-                    return c.redirect(finalUrl, finalStatus);
-                }
-                // Build response with @HttpCode and @Header support
-                const response = this.createResponse(c, result, httpCode);
-                // Apply @Header decorators
-                for (const [headerName, headerValue] of responseHeaders){
-                    response.headers.set(headerName, headerValue);
-                }
-                return response;
-            } catch (error) {
-                // Run exception filters
-                for (const filter of filters){
-                    if (shouldFilterCatch(filter, error)) {
-                        try {
-                            const result = await filter.catch(error, executionContext);
-                            return this.createResponse(c, result);
-                        } catch  {
-                            break;
-                        }
-                    }
-                }
-                // Default HttpException handling
-                if (error instanceof HttpException) {
-                    const response = error.getResponse();
-                    const status = error.getStatus();
-                    return c.json(response, status);
-                }
-                // Default 500
-                return c.json({
-                    statusCode: 500,
-                    message: 'Internal Server Error'
-                }, 500);
-            }
-        };
-    }
-    async extractArguments(c, paramMetadata, pipes, requestContainer, paramTypes) {
-        if (paramMetadata.length === 0) {
-            return [
-                c
-            ];
-        }
-        const maxIndex = paramMetadata.at(-1).index;
-        const args = new Array(maxIndex + 1).fill(undefined);
-        for (const param of paramMetadata){
-            let value = await this.extractParam(c, param);
-            const metadata = {
-                type: param.type,
-                data: param.name,
-                metatype: paramTypes?.[param.index]
-            };
-            // Run shared pipes (global + controller + method)
-            for (const pipe of pipes){
-                value = await pipe.transform(value, metadata);
-            }
-            // Run param-level pipes
-            if (param.pipes && param.pipes.length > 0) {
-                for (const paramPipe of param.pipes){
-                    const pipeInstance = this.instantiate(paramPipe, requestContainer);
-                    value = await pipeInstance.transform(value, metadata);
-                }
-            }
-            args[param.index] = value;
-        }
-        return args;
-    }
-    extractParam(c, param) {
-        if (param.type === ParamType.IP) return this.ipExtractor(c);
-        const extractor = RouteManager.PARAM_EXTRACTORS.get(param.type);
-        if (extractor) return extractor(c, param);
-        return param.factory ? param.factory(param.name, c) : undefined;
-    }
-    createResponse(c, result, statusCode) {
-        if (result instanceof Response) {
-            return result;
-        }
-        if (result === null || result === undefined) {
-            return c.body(null, statusCode ?? 204);
-        }
-        if (typeof result === 'string') {
-            return c.text(result, statusCode ?? 200);
-        }
-        return c.json(result, statusCode ?? 200);
-    }
     registerRoute(app, method, path, handler) {
         const normalizedPath = path || '/';
         const registrar = RouteManager.METHOD_REGISTRAR.get(method);

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 export type { Type, Token, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, } from './http/index';
+export { REQUEST_CONTEXT } from './http/request-context';
+export type { RequestContext } from './http/request-context';
 export { Logger, LogLevel } from './services/index';
 export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
 export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';

package/dist/index.js

@@ -12,6 +12,8 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators } from "./http/index.js";
+// Request-scoped context primitive
+export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config

package/dist/registry/metadata.registry.js

@@ -265,6 +265,5 @@ export class MetadataRegistry {
             this.handlerComponents[type].clear();
         }
         this.globalComponents = emptyComponentStore();
-    // reflectMeta is a WeakMap — entries die with their targets.
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",