@velajs/vela 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.6.0]
+
+The exception-filter chain now reaches into attached middlewares for full NestJS parity, and a new `createLazyParamDecorator` helper closes the parameter-decorator-vs-guard ordering hazard at the public-API surface.
+
+### Added
+
+- **`createLazyParamDecorator((data, ctx) => T)`.** Custom parameter decorators whose factory runs the *first time the handler reads a property on the resolved value* — not during argument extraction. Vela's argument resolver runs before guards by design (`extract args → guards → handler`), which means a `createParamDecorator` factory that depends on guard-populated state observes an empty slot. The lazy variant returns a `Proxy` whose traps invoke the factory on demand; the `get` trap short-circuits `prop === 'then'` so `await value` does not consider the proxy a thenable and therefore does not trigger eager resolution. Method results are auto-bound to the resolved real target so detached calls keep `this`; `ownKeys` + `getOwnPropertyDescriptor` are implemented so `JSON.stringify(value)` works after one access. Exported from the root barrel and from `@velajs/vela/internal` via the same surface as `createParamDecorator`. Documented in README under *Custom parameter decorators with deferred resolution*.
+
+### Changed
+
+- **Exception-filter chain now catches errors thrown inside vela-attached middlewares.** Previously the `APP_FILTER` / `@UseFilters` chain only handled errors thrown from `@Controller` handler methods; errors from middlewares (global, `MiddlewareConsumer.apply(...).forRoutes(...)`, and per-route attached) bypassed the chain and surfaced as Hono's outer 500. They now flow through the same filter resolution as handler exceptions, with a synthesized `ExecutionContext` whose `getClass()` returns the `VelaMiddlewareHost` marker and whose `getHandler()` returns the `Symbol.for('vela.middleware')` sentinel — `getType()` stays `'http'` for NestJS parity. Only global filters apply at the middleware boundary (per-handler `@UseFilters` requires a controller call frame); for thrown `HttpException`s with no catching filter, the chain renders the exception's own response/status (matching handler-thrown semantics). Non-`HttpException` throws with no catching filter re-throw to preserve the existing default-500 path. Non-throwing middleware paths (returning a `Response`, calling `await next()`, resolving a promise) are byte-identical to before.
+
 ## Unreleased
 
 A sanctioned per-request injectable lands as a framework primitive, the metadata-store unification finally has its regression tests, and dynamic module identity becomes consistent — closing the last open audit item.

package/README.md

@@ -143,6 +143,51 @@ class MyModule {
 
 `forRootAsync` callers should pass `key` explicitly when the same module needs multiple async instances — factories aren't structurally hashable.
 
+## Custom parameter decorators with deferred resolution
+
+Vela's argument resolver runs **before** guards (`extract args → guards → handler`). A custom parameter decorator built with `createParamDecorator` therefore observes any state populated by a guard as still empty — its factory has already fired by the time the guard runs.
+
+When a parameter's value depends on guard output (a `REQUEST_CONTEXT`-stored user, a tenant resolved from a JWT, etc.), use `createLazyParamDecorator` instead. The factory does not run during argument extraction; it runs the first time the handler reads a property on the resolved value:
+
+```ts
+import {
+  createLazyParamDecorator,
+  Inject,
+  Injectable,
+  REQUEST_CONTEXT,
+  Scope,
+  UseGuards,
+} from '@velajs/vela';
+import type { CanActivate, ExecutionContext, RequestContext } from '@velajs/vela';
+
+const USER_KEY = Symbol.for('app.user');
+
+@Injectable({ scope: Scope.REQUEST })
+class AuthGuard implements CanActivate {
+  constructor(@Inject(REQUEST_CONTEXT) private readonly ctx: RequestContext) {}
+  canActivate(_e: ExecutionContext): boolean {
+    this.ctx.set(USER_KEY, { id: 'u-1', name: 'ada' });   // populated here
+    return true;
+  }
+}
+
+const CurrentUser = createLazyParamDecorator((_data, ctx: ExecutionContext) => {
+  const reqCtx = ctx
+    .getContext()
+    .get('container')
+    .resolve<RequestContext>(REQUEST_CONTEXT);
+  return reqCtx.get(USER_KEY);
+});
+
+@UseGuards(AuthGuard)
+@Get('/me')
+me(@CurrentUser() user: { id: string; name: string }) {
+  return { id: user.id };           // factory runs here, AFTER AuthGuard
+}
+```
+
+The proxy short-circuits `then` on its `get` trap so `await value` returns the proxy itself rather than triggering eager resolution. Method results are auto-bound to the resolved real target, so detached method calls keep `this`. `JSON.stringify(value)` works after one access (the proxy implements `ownKeys` + `getOwnPropertyDescriptor`).
+
 ## Companion packages
 
 | Package | Purpose |

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

@@ -2,3 +2,7 @@ import type { Context } from 'hono';
 import type { Type } from '../container/types';
 import type { ExecutionContext } from '../pipeline/types';
 export declare function buildExecutionContext(c: Context, controller: Type, handlerName: string | symbol): ExecutionContext;
+export declare class VelaMiddlewareHost {
+}
+export declare const VELA_MIDDLEWARE_HANDLER: unique symbol;
+export declare function buildMiddlewareExecutionContext(c: Context): ExecutionContext;

package/dist/http/execution-context.js

@@ -13,3 +13,20 @@ export function buildExecutionContext(c, controller, handlerName) {
             })
     };
 }
+// Sentinel marker exposed via `ExecutionContext.getClass()` when the host is a
+// vela-attached middleware rather than a controller handler. Filters that
+// branch on the calling class (rare) can detect the middleware origin without
+// introducing a separate `getType()` value — `getType()` stays `'http'` for
+// NestJS parity.
+export class VelaMiddlewareHost {
+}
+// Synthesizes an ExecutionContext for an exception thrown inside a
+// vela-attached middleware. There is no controller class or handler method
+// on the call stack at that point, so `getClass()` returns the
+// `VelaMiddlewareHost` marker and `getHandler()` returns the
+// `vela.middleware` symbol — both stable, comparable values that filter
+// authors can pattern-match against if needed.
+export const VELA_MIDDLEWARE_HANDLER = Symbol.for('vela.middleware');
+export function buildMiddlewareExecutionContext(c) {
+    return buildExecutionContext(c, VelaMiddlewareHost, VELA_MIDDLEWARE_HANDLER);
+}

package/dist/http/index.d.ts

@@ -3,4 +3,5 @@ export type { RouteManagerOptions } from './route.manager';
 export { MiddlewareBuilder } from '../module/middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, RouteInfo, NestModule, MiddlewareRouteDefinition } from '../module/middleware';
 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, isController, } from './decorators';
+export { createLazyParamDecorator } from './lazy-param.decorator';
 export type { RouteMetadata, ControllerMetadata, ControllerOptions, ParamMetadata, ControllerRegistration, } from './types';

package/dist/http/index.js

@@ -1,3 +1,4 @@
 export { RouteManager } from "./route.manager.js";
 export { MiddlewareBuilder } from "../module/middleware.js";
 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, isController } from "./decorators.js";
+export { createLazyParamDecorator } from "./lazy-param.decorator.js";

package/dist/http/lazy-param.decorator.d.ts

@@ -0,0 +1,37 @@
+import type { PipeType } from '../registry/types';
+import type { ExecutionContext } from '../pipeline/types';
+/**
+ * Factory for parameter decorators whose value materializes lazily — the
+ * factory does not run during argument extraction; it runs the first time
+ * the handler reads a property on the resolved value.
+ *
+ * Why this exists: vela's argument resolver runs *before* guards
+ * (handler-executor order: extract args → guards → handler). A custom
+ * `createParamDecorator` factory that depends on guard-populated state
+ * (e.g. a value a guard places into `REQUEST_CONTEXT`) therefore observes
+ * an empty slot. `createLazyParamDecorator` defers factory execution to
+ * first property access on the proxied result, by which point guards have
+ * run and the slot is populated.
+ *
+ * The proxy explicitly short-circuits `prop === 'then'` so `await value`
+ * does not consider the proxy a thenable, which would otherwise trigger
+ * eager resolution. This single invariant is what makes the helper safe to
+ * pass through `async` boundaries without surprise.
+ *
+ * @example
+ * ```ts
+ * const CurrentUser = createLazyParamDecorator(
+ *   (_data: unknown, ctx: ExecutionContext) => {
+ *     const reqCtx = ctx.getContext().get('container').resolve(REQUEST_CONTEXT);
+ *     return reqCtx.get('user');     // populated by AuthGuard
+ *   },
+ * );
+ *
+ * @UseGuards(AuthGuard)
+ * @Get('/me')
+ * me(@CurrentUser() user: User) {
+ *   return { id: user.id };          // factory runs here, after AuthGuard
+ * }
+ * ```
+ */
+export declare function createLazyParamDecorator<TData = unknown>(factory: (data: TData, ctx: ExecutionContext) => unknown): (data?: TData, ...pipes: PipeType[]) => ParameterDecorator;

package/dist/http/lazy-param.decorator.js

@@ -0,0 +1,117 @@
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { buildExecutionContext } from "./execution-context.js";
+const CUSTOM_PARAM_TYPE = 'custom';
+/**
+ * Factory for parameter decorators whose value materializes lazily — the
+ * factory does not run during argument extraction; it runs the first time
+ * the handler reads a property on the resolved value.
+ *
+ * Why this exists: vela's argument resolver runs *before* guards
+ * (handler-executor order: extract args → guards → handler). A custom
+ * `createParamDecorator` factory that depends on guard-populated state
+ * (e.g. a value a guard places into `REQUEST_CONTEXT`) therefore observes
+ * an empty slot. `createLazyParamDecorator` defers factory execution to
+ * first property access on the proxied result, by which point guards have
+ * run and the slot is populated.
+ *
+ * The proxy explicitly short-circuits `prop === 'then'` so `await value`
+ * does not consider the proxy a thenable, which would otherwise trigger
+ * eager resolution. This single invariant is what makes the helper safe to
+ * pass through `async` boundaries without surprise.
+ *
+ * @example
+ * ```ts
+ * const CurrentUser = createLazyParamDecorator(
+ *   (_data: unknown, ctx: ExecutionContext) => {
+ *     const reqCtx = ctx.getContext().get('container').resolve(REQUEST_CONTEXT);
+ *     return reqCtx.get('user');     // populated by AuthGuard
+ *   },
+ * );
+ *
+ * @UseGuards(AuthGuard)
+ * @Get('/me')
+ * me(@CurrentUser() user: User) {
+ *   return { id: user.id };          // factory runs here, after AuthGuard
+ * }
+ * ```
+ */ export function createLazyParamDecorator(factory) {
+    return (data, ...pipes)=>{
+        return (target, propertyKey, parameterIndex)=>{
+            if (propertyKey === undefined) {
+                throw new Error('Parameter decorators can only be used on method parameters');
+            }
+            MetadataRegistry.addParameter(target.constructor, propertyKey, {
+                index: parameterIndex,
+                type: CUSTOM_PARAM_TYPE,
+                name: undefined,
+                factory: (_unused, ctx)=>{
+                    const honoCtx = ctx;
+                    const execCtx = buildExecutionContext(honoCtx, target.constructor, propertyKey);
+                    return createLazyProxy(()=>factory(data, execCtx));
+                },
+                ...pipes.length > 0 ? {
+                    pipes
+                } : {}
+            });
+        };
+    };
+}
+// Single-shot resolution: the factory runs at most once; subsequent reads
+// share the cached real value. The proxy's traps all funnel through
+// `materialize` to keep that invariant in one place.
+function createLazyProxy(produce) {
+    let resolved = false;
+    let value;
+    const materialize = ()=>{
+        if (!resolved) {
+            value = produce();
+            resolved = true;
+        }
+        return value;
+    };
+    // Target is an empty null-prototype object — proxies still need a
+    // backing target for the runtime to forward to, but using a real object
+    // would leak its own properties (`hasOwnProperty`, etc.) into trap
+    // results. `Object.create(null)` keeps the namespace clean.
+    const target = Object.create(null);
+    const handler = {
+        get (_t, prop, receiver) {
+            // Critical: do NOT report the proxy as thenable. If we let the JS
+            // runtime read `then` (during `await proxy`), the engine would
+            // observe a function-shaped value, treat the proxy as a promise,
+            // call `then(resolve, reject)` and trigger eager resolution before
+            // the consumer ever touches a real property. Returning `undefined`
+            // here makes `await proxy` return the proxy itself, untouched.
+            if (prop === 'then') return undefined;
+            const real = materialize();
+            if (real === null || real === undefined) return undefined;
+            const descriptor = Reflect.get(real, prop, receiver);
+            // Bind functions back to the real target so `this` works as the
+            // consumer expects on instance methods.
+            if (typeof descriptor === 'function') {
+                return descriptor.bind(real);
+            }
+            return descriptor;
+        },
+        has (_t, prop) {
+            const real = materialize();
+            return real !== null && real !== undefined && Reflect.has(real, prop);
+        },
+        ownKeys () {
+            const real = materialize();
+            if (real === null || real === undefined) return [];
+            return Reflect.ownKeys(real);
+        },
+        getOwnPropertyDescriptor (_t, prop) {
+            const real = materialize();
+            if (real === null || real === undefined) return undefined;
+            const descriptor = Reflect.getOwnPropertyDescriptor(real, prop);
+            // Proxy invariants require returned descriptors to be configurable
+            // when the underlying target lacks the property, which is always
+            // true for our null-prototype empty target.
+            if (descriptor) descriptor.configurable = true;
+            return descriptor;
+        }
+    };
+    return new Proxy(target, handler);
+}

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

@@ -37,6 +37,8 @@ export declare class RouteManager {
     useGlobalFilterTokens(...filterTokens: Array<Token<ExceptionFilter>>): this;
     private getMiddlewarePriority;
     private getRequestContainer;
+    private wrapMiddlewareWithFilters;
+    private mapMiddlewareError;
     registerController(controller: Type): this;
     build(): Promise<Hono>;
     private registerRoute;

package/dist/http/route.manager.js

@@ -1,12 +1,16 @@
 import { Hono } from "hono";
 import { HttpMethod } from "../constants.js";
+import { HttpException } from "../errors/http-exception.js";
 import { getMetadata } from "../metadata.js";
 import { joinPaths } from "../registry/paths.js";
 import { ArgumentResolver } from "./argument-resolver.js";
+import { buildMiddlewareExecutionContext } from "./execution-context.js";
 import { HandlerExecutor } from "./handler-executor.js";
 import { instantiate, instantiateMany } from "./instantiate.js";
 import { REQUEST_CONTEXT, createRequestContext } from "./request-context.js";
+import { mapResponse } from "./response-mapper.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
+import { shouldFilterCatch } from "../pipeline/decorators.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 const defaultGetClientIp = (c)=>c.req.raw.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? c.req.raw.headers.get('x-real-ip') ?? null;
 export class RouteManager {
@@ -146,6 +150,54 @@ export class RouteManager {
         c.set('container', child);
         return child;
     }
+    // Wraps an attached middleware so a thrown error flows through the
+    // exception-filter chain instead of bypassing it on the way to Hono's
+    // outer error handler. Mirrors the catch tail in HandlerExecutor — global
+    // filters are the only scope reachable here, since per-handler filters
+    // require a controller call frame that the middleware boundary lacks.
+    // Non-throwing middleware paths (returning a Response, calling `next()`,
+    // resolving a promise) are byte-identical to before — the wrapper only
+    // intercepts thrown / rejected values.
+    wrapMiddlewareWithFilters(handler) {
+        return async (c, next)=>{
+            try {
+                return await handler(c, next);
+            } catch (error) {
+                const response = await this.mapMiddlewareError(c, error);
+                // Force-replace any handler-set response. A middleware that throws
+                // *after* `await next()` has the handler's body already attached
+                // to `c.res`; without overwriting it, Hono would emit the
+                // pre-throw success response and the filter's render would be
+                // dropped.
+                c.res = response;
+                return response;
+            }
+        };
+    }
+    async mapMiddlewareError(c, error) {
+        const requestContainer = this.getRequestContainer(c);
+        const filters = instantiateMany(this.globalFilters, requestContainer);
+        const host = buildMiddlewareExecutionContext(c);
+        for (const filter of filters){
+            if (shouldFilterCatch(filter, error)) {
+                try {
+                    const filtered = await filter.catch(error, host);
+                    return mapResponse(c, filtered);
+                } catch  {
+                    break;
+                }
+            }
+        }
+        if (error instanceof HttpException) {
+            const response = error.getResponse();
+            const status = error.getStatus();
+            return c.json(response, status);
+        }
+        // Non-HttpException with no catching filter: re-throw so Hono's
+        // outer error handler produces the same default-500 response it
+        // produced before this wrapping was introduced.
+        throw error;
+    }
     registerController(controller) {
         const prefix = MetadataRegistry.getControllerPath(controller);
         const options = MetadataRegistry.getControllerOptions(controller);
@@ -176,11 +228,11 @@ export class RouteManager {
                 priority: this.getMiddlewarePriority(entry)
             })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
         for (const { entry } of sortedGlobal){
-            app.use('*', (c, next)=>{
+            app.use('*', this.wrapMiddlewareWithFilters((c, next)=>{
                 const requestContainer = this.getRequestContainer(c);
                 const resolved = instantiate(entry, requestContainer);
                 return resolved.use(c, next);
-            });
+            }));
         }
         const sortedConsumer = this.consumerMiddlewareDefinitions.map((def, index)=>({
                 def,
@@ -190,7 +242,7 @@ export class RouteManager {
         for (const { def } of sortedConsumer){
             const matchRoute = this.compileRouteMatcher(def.routes);
             const matchExclude = this.compileRouteMatcher(def.excludes);
-            app.use('*', (c, next)=>{
+            app.use('*', this.wrapMiddlewareWithFilters((c, next)=>{
                 const path = c.req.path;
                 const method = c.req.method;
                 if (!matchRoute(path, method) || matchExclude(path, method)) return next();
@@ -202,7 +254,7 @@ export class RouteManager {
                     return instance.use(c, ()=>runChain(index + 1)).then(()=>{});
                 };
                 return runChain(0);
-            });
+            }));
         }
         // First pass: register all custom routes (must come before CRUD /:id routes).
         for (const { controller, metadata, routes } of this.controllers){
@@ -215,11 +267,11 @@ export class RouteManager {
                     const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
                     for (const fullPath of versionedPaths){
                         for (const middlewareItem of middlewareItems){
-                            app.use(fullPath, (c, next)=>{
+                            app.use(fullPath, this.wrapMiddlewareWithFilters((c, next)=>{
                                 const requestContainer = this.getRequestContainer(c);
                                 const resolved = instantiate(middlewareItem, requestContainer);
                                 return resolved.use(c, next);
-                            });
+                            }));
                         }
                         this.registerRoute(app, route.method, fullPath, handler);
                     }

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter,
 export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, } from './container/index';
 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 { 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, createLazyParamDecorator, applyDecorators, } from './http/index';
 export { REQUEST_CONTEXT } from './http/request-context';
 export type { RequestContext } from './http/request-context';
 export { Logger, LogLevel } from './services/index';

package/dist/index.js

@@ -11,7 +11,7 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 // Constants
 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";
+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, createLazyParamDecorator, applyDecorators } from "./http/index.js";
 // Request-scoped context primitive
 export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Services

package/package.json

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