@velajs/vela 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.

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/index.d.ts

@@ -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/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.6.0",
+  "version": "1.8.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",