@velajs/vela 1.5.1 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.7.0 (2026-05-14)
+
+### New
+
+- **`OnFirstRequest` lifecycle hook.** Fires exactly once on the first incoming HTTP request, AFTER user-supplied middleware (so runtime adapters like `@velajs/cloudflare`'s binding-init can run first) and BEFORE route handlers. Bridges module-load and request-time semantics — the canonical seam for state that depends on values only available at request time (Cloudflare D1/KV/R2 bindings, Deno Deploy env, etc.). Auto-fired by a global middleware vela installs after user middleware; non-HTTP consumers can trigger it manually via `app.callOnFirstRequest()`. Concurrency-safe: vela memoizes the promise so parallel first requests share a single fire.
+
+### Notes
+
+- Edge-clean addition — no `node:*`, no `Buffer`, no `setInterval`; the hook is just `() => void | Promise<void>` wired into Hono's middleware chain.
+- Backwards-compatible. Existing apps unaffected: the new middleware only fires hooks if any registered instance implements `OnFirstRequest`, and the implementation is a no-op otherwise.
+
+## [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/application.d.ts

@@ -9,6 +9,7 @@ export declare class VelaApplication {
     private readonly routeManager;
     private instances;
     private honoApp;
+    private firstRequestPromise;
     constructor(container: Container, routeManager: RouteManager);
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */
     initRoutes(): Promise<void>;
@@ -36,5 +37,14 @@ export declare class VelaApplication {
     mountOpenApi(options: MountOpenApiOptions): this;
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
+    /**
+     * Fire `OnFirstRequest` hooks exactly once across the application's
+     * lifetime. Auto-invoked by a global middleware on the first HTTP request;
+     * also safe to call manually from non-HTTP entry points (CLI, tests).
+     *
+     * Concurrent calls share the same in-flight promise — vela guarantees
+     * each instance's `onFirstRequest()` runs at most once.
+     */
+    callOnFirstRequest(): Promise<void>;
     close(signal?: string): Promise<void>;
 }

package/dist/application.js

@@ -1,10 +1,13 @@
-import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
+import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnFirstRequest, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
 import { renderScalarUi } from "./openapi/scalar-ui.js";
 export class VelaApplication {
     container;
     routeManager;
     instances = [];
     honoApp = null;
+    // Memoizes the first-request hook fire. Concurrent first requests share
+    // this promise so the hook runs exactly once.
+    firstRequestPromise;
     constructor(container, routeManager){
         this.container = container;
         this.routeManager = routeManager;
@@ -89,6 +92,25 @@ export class VelaApplication {
             }
         }
     }
+    /**
+   * Fire `OnFirstRequest` hooks exactly once across the application's
+   * lifetime. Auto-invoked by a global middleware on the first HTTP request;
+   * also safe to call manually from non-HTTP entry points (CLI, tests).
+   *
+   * Concurrent calls share the same in-flight promise — vela guarantees
+   * each instance's `onFirstRequest()` runs at most once.
+   */ callOnFirstRequest() {
+        if (!this.firstRequestPromise) {
+            this.firstRequestPromise = (async ()=>{
+                for (const instance of this.instances){
+                    if (hasOnFirstRequest(instance)) {
+                        await instance.onFirstRequest();
+                    }
+                }
+            })();
+        }
+        return this.firstRequestPromise;
+    }
     async close(signal) {
         const reversed = [
             ...this.instances

package/dist/factory.js

@@ -6,6 +6,18 @@ export const VelaFactory = {
         const app = new VelaApplication(container, routeManager);
         const instances = await loader.resolveAllInstances();
         app.setInstances(instances);
+        // Register the first-request middleware AFTER user-supplied middleware
+        // (registered by bootstrap from `options.middleware`). Ordering matters:
+        // runtime adapters like `@velajs/cloudflare` install binding-init
+        // middleware that must run BEFORE OnFirstRequest hooks read those
+        // bindings. Vela's middleware is appended last → fires after all user
+        // middleware, before route handlers (which are registered separately).
+        routeManager.useGlobalMiddleware({
+            use: async (_c, next)=>{
+                await app.callOnFirstRequest();
+                await next();
+            }
+        });
         await app.callOnModuleInit();
         await app.callOnApplicationBootstrap();
         // Build routes (async — supports CRUD integration with dynamic imports)

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';
@@ -41,7 +41,7 @@ export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType,
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipeline/index';
 export type { ParseUUIDPipeOptions, ParseArrayPipeOptions } from './pipeline/index';
 export { HttpException, BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, GoneException, PayloadTooLargeException, UnsupportedMediaTypeException, UnprocessableEntityException, TooManyRequestsException, InternalServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, GatewayTimeoutException, } from './errors/index';
-export type { OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, OnApplicationShutdown, BeforeApplicationShutdown, } from './lifecycle/index';
+export type { OnModuleInit, OnApplicationBootstrap, OnFirstRequest, OnModuleDestroy, OnApplicationShutdown, BeforeApplicationShutdown, } from './lifecycle/index';
 export { MetadataRegistry } from './registry/metadata.registry';
 export { createZodDto, ValidationPipe } from './validation/index';
 export type { CreateZodDtoOptions } from './validation/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/dist/lifecycle/index.d.ts

@@ -4,6 +4,25 @@ export interface OnModuleInit {
 export interface OnApplicationBootstrap {
     onApplicationBootstrap(): void | Promise<void>;
 }
+/**
+ * Fires exactly once, on the first incoming HTTP request, AFTER user-supplied
+ * middleware (so binding initializers like `@velajs/cloudflare`'s env capture
+ * run first) and BEFORE route handlers. The hook bridges module-load and
+ * request-time semantics — use it for state that depends on values only
+ * available at request time (Cloudflare bindings, Deno Deploy env, etc.).
+ *
+ * Concurrency: vela memoizes the call. Concurrent first requests all await
+ * the same promise; the hook runs exactly once.
+ *
+ * Non-HTTP consumers (CLI, tests) can trigger it manually via
+ * `app.callOnFirstRequest()`.
+ *
+ * Edge-safe: the hook itself is just `() => void | Promise<void>`. The
+ * runtime contract is async/Promise — no Node-only APIs are involved.
+ */
+export interface OnFirstRequest {
+    onFirstRequest(): void | Promise<void>;
+}
 export interface OnModuleDestroy {
     onModuleDestroy(): void | Promise<void>;
 }
@@ -15,6 +34,7 @@ export interface BeforeApplicationShutdown {
 }
 export declare function hasOnModuleInit(instance: unknown): instance is OnModuleInit;
 export declare function hasOnApplicationBootstrap(instance: unknown): instance is OnApplicationBootstrap;
+export declare function hasOnFirstRequest(instance: unknown): instance is OnFirstRequest;
 export declare function hasOnModuleDestroy(instance: unknown): instance is OnModuleDestroy;
 export declare function hasBeforeApplicationShutdown(instance: unknown): instance is BeforeApplicationShutdown;
 export declare function hasOnApplicationShutdown(instance: unknown): instance is OnApplicationShutdown;

package/dist/lifecycle/index.js

@@ -4,6 +4,9 @@ export function hasOnModuleInit(instance) {
 export function hasOnApplicationBootstrap(instance) {
     return instance !== null && typeof instance === 'object' && typeof instance.onApplicationBootstrap === 'function';
 }
+export function hasOnFirstRequest(instance) {
+    return instance !== null && typeof instance === 'object' && typeof instance.onFirstRequest === 'function';
+}
 export function hasOnModuleDestroy(instance) {
     return instance !== null && typeof instance === 'object' && typeof instance.onModuleDestroy === 'function';
 }

package/package.json

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