@velajs/vela 1.8.8 → 1.10.0

package/dist/container/container.js

@@ -1,4 +1,5 @@
 import { Scope } from "../constants.js";
+import { disposeInstance, isDisposable } from "./disposable.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
 import { ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
 const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
@@ -25,6 +26,13 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
     scopes = new Map();
     globals = new Set();
     diagnostics;
+    // The root container that owns shared state; a request child points back here
+    // so container-constructed SINGLETONs are tracked (and disposed) at the root,
+    // never by the ephemeral child that happened to first resolve them.
+    root = this;
+    // Container-constructed instances in creation order, for LIFO disposal.
+    // useValue providers are never tracked (they return before construction).
+    disposables = [];
     constructor(options = {}){
         this.diagnostics = options.diagnostics ?? 'log';
     }
@@ -285,7 +293,7 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         if (!exporters) return undefined;
         for (const owner of exporters){
             const reg = this.providers.get(owner)?.get(token);
-            if (reg) return reg.scope;
+            if (reg) return reg.effectiveScope ?? reg.scope;
         }
         return undefined;
     }
@@ -299,6 +307,95 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         ];
     }
     /**
+   * Every statically-provided (useValue) instance across ALL module buckets.
+   * Unlike resolving a token (which yields only the first bucket's registration),
+   * this surfaces per-instance values — e.g. one BindingRef per multi-instance
+   * binding module — so framework adapters can initialize all of them.
+   */ getUseValues() {
+        const out = [];
+        for (const bucket of this.providers.values()){
+            for (const reg of bucket.values()){
+                if (reg.useValue !== undefined) out.push(reg.useValue);
+            }
+        }
+        return out;
+    }
+    /**
+   * Compute request-scope bubbling for every registration (call once at
+   * bootstrap, after all providers are registered). A provider whose declared
+   * scope is not REQUEST but which (transitively) depends on a request-scoped
+   * provider is marked `effectiveScope = REQUEST`, so it is rebuilt per request
+   * instead of capturing the first request's instance — matching NestJS.
+   */ computeEffectiveScopes() {
+        // Reverse-propagation worklist: seed with every declared-REQUEST provider,
+        // then flood "request-ness" to consumers transitively. This is order- and
+        // cycle-independent (a node flips to REQUEST at most once), avoiding the
+        // finalize-during-in-progress-cycle hazard of a recursive DFS.
+        const regs = [];
+        for (const bucket of this.providers.values()){
+            for (const reg of bucket.values()){
+                reg.effectiveScope = reg.scope;
+                regs.push(reg);
+            }
+        }
+        // Build reverse edges: dependency registration -> registrations that consume it.
+        const consumers = new Map();
+        for (const reg of regs){
+            for (const depToken of this.dependencyTokensOf(reg)){
+                const depReg = this.tryFindRegistration(depToken, reg.declaringModuleId);
+                if (!depReg) continue;
+                const list = consumers.get(depReg);
+                if (list) list.push(reg);
+                else consumers.set(depReg, [
+                    reg
+                ]);
+            }
+        }
+        const queue = regs.filter((r)=>r.effectiveScope === Scope.REQUEST);
+        while(queue.length > 0){
+            const dep = queue.pop();
+            for (const consumer of consumers.get(dep) ?? []){
+                if (consumer.effectiveScope !== Scope.REQUEST) {
+                    consumer.effectiveScope = Scope.REQUEST;
+                    queue.push(consumer);
+                }
+            }
+        }
+    }
+    /** The dependency tokens a registration would resolve when constructed. */ dependencyTokensOf(reg) {
+        if (reg.useExisting) return [
+            reg.useExisting
+        ];
+        if (reg.useFactory) {
+            return (reg.inject ?? []).map((t)=>t instanceof ForwardRef ? t.factory() : t);
+        }
+        const cls = reg.useClass ?? (typeof reg.provide === 'function' ? reg.provide : undefined);
+        if (!cls) return [];
+        const paramTypes = getConstructorDependencies(cls);
+        const injectMetadata = getInjectMetadata(cls);
+        const injectMap = new Map(injectMetadata.map((m)=>[
+                m.index,
+                m
+            ]));
+        const arity = Math.max(paramTypes.length, injectMetadata.reduce((max, m)=>Math.max(max, m.index + 1), 0));
+        const tokens = [];
+        for(let i = 0; i < arity; i++){
+            const raw = injectMap.get(i)?.token;
+            const token = raw instanceof ForwardRef ? raw.factory() : raw ?? paramTypes[i];
+            if (token && !isErasedTypeToken(token)) tokens.push(token);
+        }
+        return tokens;
+    }
+    tryFindRegistration(token, requestingModuleId) {
+        try {
+            return this.findRegistration(token, requestingModuleId);
+        } catch  {
+            // Ambiguous (MultipleProvidersFoundError) or unreachable — treat as
+            // unknown for scope computation; real resolution will surface any error.
+            return undefined;
+        }
+    }
+    /**
    * Create a child container for request-scoped resolution.
    * The child shares the parent's providers but caches REQUEST-scoped
    * instances separately per child (per request).
@@ -312,6 +409,9 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         child.exporterIndex = this.exporterIndex;
         child.scopes = this.scopes;
         child.globals = this.globals;
+        // SINGLETON disposal is owned by the root; the child keeps only its own
+        // REQUEST-scoped disposables (cleared when the request ends).
+        child.root = this.root;
         return child;
     }
     createDetached() {
@@ -343,6 +443,44 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         this.requestInstances.clear();
         this.scopes.clear();
         this.globals.clear();
+        this.disposables = [];
+    }
+    /** Whether this container has any tracked disposables (cheap request-path check). */ hasDisposables() {
+        return this.disposables.length > 0;
+    }
+    /**
+   * Dispose container-constructed instances (Symbol.asyncDispose /
+   * Symbol.dispose / .dispose()) in reverse creation order (LIFO). Errors are
+   * logged and skipped so one bad teardown never blocks the rest.
+   *
+   * A REQUEST child disposes only its own request-scoped instances; the root
+   * disposes shared SINGLETONs and clears their cached instance so a dev HMR
+   * generation cannot leak a stale graph. Shared provider maps are left intact
+   * for a request child (they belong to the root).
+   */ async dispose() {
+        const pending = this.disposables;
+        this.disposables = [];
+        for(let i = pending.length - 1; i >= 0; i--){
+            try {
+                await disposeInstance(pending[i]);
+            } catch (error) {
+                if (this.diagnostics !== 'silent') {
+                    console.error('Error disposing instance:', error);
+                }
+            }
+        }
+        this.requestInstances.clear();
+        if (this.root === this) {
+            // Drop cached singleton instances (except useValue, which the app owns)
+            // so a rebuilt graph starts clean.
+            for (const bucket of this.providers.values()){
+                for (const registration of bucket.values()){
+                    if (registration.scope === Scope.SINGLETON && registration.useValue === undefined) {
+                        registration.instance = undefined;
+                    }
+                }
+            }
+        }
     }
     resolveRegistration(registration, requestingModuleId) {
         if (registration.useValue !== undefined) {
@@ -352,12 +490,16 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             // Pass through the original requester to catch alias leaks
             return this.resolve(registration.useExisting, requestingModuleId);
         }
+        // Effective scope accounts for request-scope bubbling: a SINGLETON that
+        // (transitively) depends on a request-scoped provider is treated as REQUEST
+        // so it is rebuilt per request instead of capturing the first one.
+        const scope = registration.effectiveScope ?? registration.scope;
         // Singleton: return cached from registration (shared across all containers)
-        if (registration.scope === Scope.SINGLETON && registration.instance !== undefined) {
+        if (scope === Scope.SINGLETON && registration.instance !== undefined) {
             return registration.instance;
         }
         // Request: return cached from this child's requestInstances
-        if (registration.scope === Scope.REQUEST) {
+        if (scope === Scope.REQUEST) {
             const cached = this.requestInstances.get(registration.provide);
             if (cached !== undefined) {
                 return cached;
@@ -384,10 +526,14 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             } else {
                 throw new Error(`Invalid provider registration for: ${this.tokenToString(registration.provide)}`);
             }
-            if (registration.scope === Scope.SINGLETON) {
+            if (scope === Scope.SINGLETON) {
                 registration.instance = instance;
-            } else if (registration.scope === Scope.REQUEST) {
+                // Track for disposal on the ROOT — a singleton outlives the request
+                // child that may have first constructed it.
+                if (isDisposable(instance)) this.root.disposables.push(instance);
+            } else if (scope === Scope.REQUEST) {
                 this.requestInstances.set(registration.provide, instance);
+                if (isDisposable(instance)) this.disposables.push(instance);
             }
             return instance;
         } finally{
@@ -468,7 +614,8 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
             throw new Error(`No provider found for token: ${this.tokenToString(token)}`);
         }
         if (registration.useFactory) {
-            if (registration.scope === Scope.SINGLETON && registration.instance !== undefined) {
+            const scope = registration.effectiveScope ?? registration.scope;
+            if (scope === Scope.SINGLETON && registration.instance !== undefined) {
                 return registration.instance;
             }
             // Factory inject deps resolve without a requester (same escape hatch as
@@ -478,8 +625,10 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
                 return this.resolveAsync(resolved);
             }));
             const instance = await registration.useFactory(...dependencies);
-            if (registration.scope === Scope.SINGLETON) {
+            if (scope === Scope.SINGLETON) {
                 registration.instance = instance;
+                // Track for disposal on the ROOT, matching the sync resolveRegistration path.
+                if (isDisposable(instance)) this.root.disposables.push(instance);
             }
             return instance;
         }

package/dist/container/disposable.d.ts

@@ -0,0 +1,5 @@
+export interface Disposable {
+    dispose?(): void | Promise<void>;
+}
+export declare function isDisposable(value: unknown): boolean;
+export declare function disposeInstance(value: unknown): Promise<void>;

package/dist/container/disposable.js

@@ -0,0 +1,33 @@
+// Edge-safe disposal contract (mirrors stratal's). Precedence:
+//   Symbol.asyncDispose > Symbol.dispose > .dispose()
+// Symbol.asyncDispose/Symbol.dispose are resolved at runtime (they are not in
+// the ES2022 lib the project targets), so nothing here depends on the
+// esnext.disposable typings.
+const ASYNC_DISPOSE = Symbol.asyncDispose;
+const SYNC_DISPOSE = Symbol.dispose;
+function asRecord(value) {
+    if (value === null) return undefined;
+    return typeof value === 'object' || typeof value === 'function' ? value : undefined;
+}
+export function isDisposable(value) {
+    const obj = asRecord(value);
+    if (!obj) return false;
+    if (ASYNC_DISPOSE && typeof obj[ASYNC_DISPOSE] === 'function') return true;
+    if (SYNC_DISPOSE && typeof obj[SYNC_DISPOSE] === 'function') return true;
+    return typeof obj.dispose === 'function';
+}
+export async function disposeInstance(value) {
+    const obj = asRecord(value);
+    if (!obj) return;
+    if (ASYNC_DISPOSE && typeof obj[ASYNC_DISPOSE] === 'function') {
+        await obj[ASYNC_DISPOSE].call(obj);
+        return;
+    }
+    if (SYNC_DISPOSE && typeof obj[SYNC_DISPOSE] === 'function') {
+        obj[SYNC_DISPOSE].call(obj);
+        return;
+    }
+    if (typeof obj.dispose === 'function') {
+        await obj.dispose.call(obj);
+    }
+}

package/dist/container/types.d.ts

@@ -57,7 +57,15 @@ export interface ProviderOptions<T = unknown> {
 }
 export interface ProviderRegistration<T = unknown> {
     provide: Token<T>;
+    /** The declared scope (from `@Injectable`/`@Controller`/provider options). */
     scope: Scope;
+    /**
+     * Scope after request-scope bubbling: `REQUEST` if this provider (transitively)
+     * depends on a request-scoped provider, else the declared scope. Computed once
+     * at bootstrap (`Container.computeEffectiveScopes`); falls back to `scope`
+     * until then. Governs caching + eager instantiation.
+     */
+    effectiveScope?: Scope;
     /**
      * Module that owns this registration. Used by `resolveClass` to determine
      * the POV from which the class's dependencies resolve. Sandbox/bootstrap

package/dist/factory/bootstrap.js

@@ -54,6 +54,13 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
     });
     container.markGlobalToken(REQUEST_CONTEXT);
     const routeManager = new RouteManager(container, options);
+    // Resolvable so non-HTTP transports (the WebSocket dispatcher) can read the
+    // same global-tier components (APP_* + app.useGlobalX()).
+    container.register({
+        provide: RouteManager,
+        useValue: routeManager
+    });
+    container.markGlobalToken(RouteManager);
     ComponentManager.init(container);
     const loader = new ModuleLoader(container, routeManager);
     loader.load(rootModule);
@@ -68,6 +75,9 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
         };
         routeManager.useGlobalMiddleware(mw);
     }
+    // All providers are registered — compute request-scope bubbling so effective
+    // scopes are known before eager instantiation and request resolution.
+    container.computeEffectiveScopes();
     return {
         container,
         routeManager,

package/dist/fetch/fetch.module.d.ts

@@ -1,8 +1,7 @@
-import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { HttpModuleOptions } from './fetch.types';
-export declare class HttpModule {
-    static forRoot(options?: HttpModuleOptions): DynamicModule;
-    static forRootAsync(options: AsyncModuleOptions<HttpModuleOptions> & {
-        key?: string;
-    }): DynamicModule;
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<HttpModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class HttpModule extends ConfigurableModuleClass {
 }
+export {};

package/dist/fetch/fetch.module.js

@@ -5,52 +5,18 @@ function _ts_decorate(decorators, target, key, desc) {
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 import { Module } from "../module/decorators.js";
-import { stableHash } from "../module/stable-hash.js";
+import { ConfigurableModuleBuilder } from "../module/configurable-module.builder.js";
 import { HttpService, HTTP_MODULE_OPTIONS } from "./fetch.service.js";
-export class HttpModule {
-    static forRoot(options = {}) {
-        return {
-            module: HttpModule,
-            key: stableHash(options),
-            providers: [
-                {
-                    provide: HTTP_MODULE_OPTIONS,
-                    useValue: options
-                },
-                HttpService
-            ],
-            exports: [
-                HttpService,
-                HTTP_MODULE_OPTIONS
-            ]
-        };
-    }
-    static forRootAsync(options) {
-        return {
-            module: HttpModule,
-            key: options.key ?? stableHash({
-                inject: options.inject,
-                useFactory: options.useFactory
-            }),
-            imports: options.imports ?? [],
-            providers: [
-                {
-                    provide: HTTP_MODULE_OPTIONS,
-                    useFactory: options.useFactory,
-                    inject: options.inject ?? []
-                },
-                HttpService
-            ],
-            exports: [
-                HttpService,
-                HTTP_MODULE_OPTIONS
-            ]
-        };
-    }
+const { ConfigurableModuleClass } = new ConfigurableModuleBuilder({
+    moduleName: 'Http',
+    optionsInjectionToken: HTTP_MODULE_OPTIONS
+}).build();
+export class HttpModule extends ConfigurableModuleClass {
 }
 HttpModule = _ts_decorate([
     Module({
         providers: [
+            // Default for bare `imports: [HttpModule]`; forRoot(options) overrides via merge.
             {
                 provide: HTTP_MODULE_OPTIONS,
                 useValue: {}
@@ -58,7 +24,8 @@ HttpModule = _ts_decorate([
             HttpService
         ],
         exports: [
-            HttpService
+            HttpService,
+            HTTP_MODULE_OPTIONS
         ]
     })
 ], HttpModule);

package/dist/http/ambient.d.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareHandler } from 'hono';
+import type { Container } from '../container/container';
+import { type RequestContext } from './request-context';
+/**
+ * Returns Hono's `contextStorage()` middleware. Register it as the FIRST global
+ * middleware so `getCurrentContainer()` works everywhere downstream. When using
+ * `VelaFactory.create(module, { ambientContainer: true })` this is wired
+ * automatically — call this only for manual/raw Hono setups.
+ */
+export declare function enableAmbientContainer(): MiddlewareHandler;
+/**
+ * The current request's DI container. Throws with actionable guidance if
+ * ambient access isn't enabled or this runs outside a request.
+ */
+export declare function getCurrentContainer(): Container;
+/** The current request's {@link RequestContext} (via the ambient container). */
+export declare function getCurrentRequestContext(): RequestContext;

package/dist/http/ambient.js

@@ -0,0 +1,44 @@
+import { contextStorage, getContext } from "hono/context-storage";
+import { REQUEST_CONTEXT } from "./request-context.js";
+// Opt-in ambient access to the per-request DI container / RequestContext,
+// for deep code that lacks the Hono `Context` (services, standalone helpers).
+//
+// Portable across vela's target runtimes because the `node:async_hooks`
+// dependency lives inside Hono's `contextStorage()` middleware — vela's own
+// source never imports `node:*`. Uses only the workerd-safe ALS subset
+// (`run()`/`getStore()`); no `enterWith`, no cross-thenable propagation.
+//
+// Default path is unchanged: request scope is still carried by the per-request
+// child container (see RouteManager.getRequestContainer). This is a second
+// READ path, active only when enabled.
+/**
+ * Returns Hono's `contextStorage()` middleware. Register it as the FIRST global
+ * middleware so `getCurrentContainer()` works everywhere downstream. When using
+ * `VelaFactory.create(module, { ambientContainer: true })` this is wired
+ * automatically — call this only for manual/raw Hono setups.
+ */ export function enableAmbientContainer() {
+    return contextStorage();
+}
+function tryGetContext() {
+    try {
+        return getContext();
+    } catch  {
+        // Thrown when called outside the contextStorage() middleware (i.e. ambient
+        // access not enabled, or outside a request).
+        return undefined;
+    }
+}
+/**
+ * The current request's DI container. Throws with actionable guidance if
+ * ambient access isn't enabled or this runs outside a request.
+ */ export function getCurrentContainer() {
+    const context = tryGetContext();
+    const container = context?.get('container');
+    if (!container) {
+        throw new Error('getCurrentContainer() is unavailable: enable ambient access via ' + "VelaFactory.create(module, { ambientContainer: true }) (or app.use(enableAmbientContainer())) " + 'and only call it within a request.');
+    }
+    return container;
+}
+/** The current request's {@link RequestContext} (via the ambient container). */ export function getCurrentRequestContext() {
+    return getCurrentContainer().resolve(REQUEST_CONTEXT);
+}

package/dist/http/execution-context.js

@@ -10,7 +10,10 @@ export function buildExecutionContext(c, controller, handlerName) {
         switchToHttp: ()=>({
                 getRequest: ()=>c.req.raw,
                 getResponse: ()=>c
-            })
+            }),
+        switchToWs: ()=>{
+            throw new Error('switchToWs() called on an HTTP ExecutionContext. This handler runs over HTTP, not a WebSocket gateway.');
+        }
     };
 }
 // Sentinel marker exposed via `ExecutionContext.getClass()` when the host is a

package/dist/http/index.d.ts

@@ -4,4 +4,5 @@ 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 { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './ambient';
 export type { RouteMetadata, ControllerMetadata, ControllerOptions, ParamMetadata, ControllerRegistration, } from './types';

package/dist/http/index.js

@@ -2,3 +2,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";
+export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext } from "./ambient.js";

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

@@ -9,6 +9,12 @@ export interface RouteManagerOptions {
     getClientIp?: (c: Context) => string | null;
     middleware?: MiddlewareHandler[];
     globalPrefix?: string;
+    /**
+     * Opt into ambient request-container access (`getCurrentContainer()` /
+     * `getCurrentRequestContext()`). Registers Hono's `contextStorage()` as the
+     * first middleware. Off by default — the explicit child container is unchanged.
+     */
+    ambientContainer?: boolean;
 }
 export declare class RouteManager {
     private container;
@@ -22,7 +28,20 @@ export declare class RouteManager {
     private globalPrefix;
     private consumerMiddlewareDefinitions;
     private readonly handlerExecutor;
+    private readonly ambientContainer;
     constructor(container: Container, options?: RouteManagerOptions);
+    /**
+     * The global-tier components (`APP_*` provider tokens + imperative
+     * `app.useGlobalX()` instances). Exposed so non-HTTP transports (the
+     * WebSocket dispatcher) can apply the same app-wide guards/pipes/interceptors/
+     * filters as HTTP routes, read live so late registrations propagate.
+     */
+    getGlobalComponents(): {
+        guards: Array<GuardType | Token<CanActivate>>;
+        pipes: Array<PipeType | Token<PipeTransform>>;
+        interceptors: Array<InterceptorType | Token<NestInterceptor>>;
+        filters: Array<FilterType | Token<ExceptionFilter>>;
+    };
     registerConsumerMiddleware(definitions: MiddlewareRouteDefinition[]): this;
     setGlobalPrefix(prefix: string): this;
     useGlobalMiddleware(...middleware: MiddlewareType[]): this;

package/dist/http/route.manager.js

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { contextStorage } from "hono/context-storage";
 import { HttpMethod } from "../constants.js";
 import { HttpException } from "../errors/http-exception.js";
 import { getMetadata } from "../metadata.js";
@@ -14,6 +15,39 @@ 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;
+// Mirror a response body stream, invoking `onDone` exactly once when it is fully
+// read, errors, or is cancelled. Lets request-scoped resources be disposed only
+// after the body has drained — never mid-stream.
+function disposeStreamWhenDone(body, onDone) {
+    const reader = body.getReader();
+    let finished = false;
+    const finish = ()=>{
+        if (!finished) {
+            finished = true;
+            onDone();
+        }
+    };
+    return new ReadableStream({
+        async pull (controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    controller.close();
+                    finish();
+                    return;
+                }
+                controller.enqueue(value);
+            } catch (error) {
+                controller.error(error);
+                finish();
+            }
+        },
+        cancel (reason) {
+            finish();
+            return reader.cancel(reason);
+        }
+    });
+}
 export class RouteManager {
     container;
     static METHOD_REGISTRAR = new Map([
@@ -59,8 +93,10 @@ export class RouteManager {
     globalPrefix = '';
     consumerMiddlewareDefinitions = [];
     handlerExecutor;
+    ambientContainer;
     constructor(container, options = {}){
         this.container = container;
+        this.ambientContainer = options.ambientContainer ?? false;
         const argumentResolver = new ArgumentResolver(options.getClientIp ?? defaultGetClientIp);
         this.handlerExecutor = new HandlerExecutor(argumentResolver, ()=>({
                 guards: this.globalGuards,
@@ -69,6 +105,19 @@ export class RouteManager {
                 filters: this.globalFilters
             }), (c)=>this.getRequestContainer(c));
     }
+    /**
+   * The global-tier components (`APP_*` provider tokens + imperative
+   * `app.useGlobalX()` instances). Exposed so non-HTTP transports (the
+   * WebSocket dispatcher) can apply the same app-wide guards/pipes/interceptors/
+   * filters as HTTP routes, read live so late registrations propagate.
+   */ getGlobalComponents() {
+        return {
+            guards: this.globalGuards,
+            pipes: this.globalPipes,
+            interceptors: this.globalInterceptors,
+            filters: this.globalFilters
+        };
+    }
     registerConsumerMiddleware(definitions) {
         this.consumerMiddlewareDefinitions.push(...definitions);
         return this;
@@ -221,6 +270,41 @@ export class RouteManager {
     }
     async build() {
         const app = new Hono();
+        // Outermost: dispose the per-request child container once the request is
+        // fully done. Fast-paths out when the child has no request-scoped
+        // disposables (the common case → zero overhead / no behavior change).
+        // Streaming-safe: when a response body is present, disposal is deferred
+        // until the body is fully read (or errors/cancels), never mid-stream.
+        app.use('*', async (c, next)=>{
+            let threw = false;
+            try {
+                await next();
+            } catch (error) {
+                threw = true;
+                throw error;
+            } finally{
+                const child = c.get('container');
+                if (child?.hasDisposables()) {
+                    const body = threw ? null : c.res?.body ?? null;
+                    if (body) {
+                        // Defer disposal to when the runtime finishes reading the body.
+                        c.res = new Response(disposeStreamWhenDone(body, ()=>void child.dispose()), {
+                            status: c.res.status,
+                            statusText: c.res.statusText,
+                            headers: c.res.headers
+                        });
+                    } else {
+                        // No body (or error path) — nothing streaming, dispose now.
+                        await child.dispose();
+                    }
+                }
+            }
+        });
+        // Opt-in ambient container: contextStorage() must be an early middleware so
+        // getContext() is available to everything downstream.
+        if (this.ambientContainer) {
+            app.use('*', contextStorage());
+        }
         // Sort global middleware by priority (lower runs first) with insertion
         // index as tiebreaker so equal priorities preserve registration order.
         const sortedGlobal = this.globalMiddleware.map((entry, index)=>({

package/dist/i18n/deep-merge.d.ts

@@ -0,0 +1,2 @@
+/** Deep-merge two message trees; source overrides target at the leaf level. */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

package/dist/i18n/deep-merge.js

@@ -0,0 +1,15 @@
+/** Deep-merge two message trees; source overrides target at the leaf level. */ export function deepMerge(target, source) {
+    const result = {
+        ...target
+    };
+    for (const key of Object.keys(source)){
+        const targetValue = target[key];
+        const sourceValue = source[key];
+        if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'object' && sourceValue !== null && !Array.isArray(sourceValue)) {
+            result[key] = deepMerge(targetValue, sourceValue);
+        } else {
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}