@velajs/vela 1.8.8 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.10.0 (2026-07-01)
+
+### Added
+
+- **WebSocket support** (`@velajs/vela/websocket` + `@velajs/vela/websocket-node`): `@WebSocketGateway`, `@SubscribeMessage`, gateways run through the same global guard/pipe/interceptor/filter tiers as HTTP (`RouteManager.getGlobalComponents()`).
+
+- **`ConfigurableModuleBuilder`** (NestJS-parity) + the lower-level `defineConfigurableModule` engine. Generates `forRoot`/`forRootAsync` (with `key`, `global`, `useClass`/`useExisting` async options, and the options token) from a tiny spec, so a new module is just its tokens + options type + service + a `@Module({...})` bag — while keeping vela's module encapsulation and multi-instance `key` dedup. `CacheModule`, `ConfigModule`, `ThrottlerModule`, and `HttpModule` are migrated onto it; `@velajs/cloudflare`'s binding modules reuse the engine.
+- **Opt-in ambient request access**: `getCurrentContainer()` / `getCurrentRequestContext()` + `enableAmbientContainer()`, wired via `VelaFactory.create(module, { ambientContainer: true })`. Backed by Hono's `hono/context-storage` (no `node:async_hooks` import in core); OFF by default, explicit child-container path unchanged. On Cloudflare Workers it requires the `nodejs_als` (or `nodejs_compat`) flag — validated on real workerd.
+- **Container + application disposal**: `Container.dispose()` (LIFO; `Symbol.asyncDispose`/`Symbol.dispose`/`.dispose()`, idempotent), `VelaApplication.dispose()` and `Symbol.asyncDispose` (enables `await using`). The root disposes shared singletons; the per-request child container is disposed automatically at the end of each HTTP request — streaming-safe (deferred until the response body drains) and zero-overhead when a request has no request-scoped disposables.
+- **Async cache stores (additive, non-breaking).** New `AsyncCacheStore` interface + `TieredCacheStore` (read-through + backfill + write-through over N sync/async tiers) in core, and `KVCacheStore` in `@velajs/cloudflare`, for a memory→KV cache. The existing synchronous `CacheStore`/`CacheService`/`CacheInterceptor` are **unchanged**; `CacheModuleOptions` gains an optional sync `store`. Use the async stores programmatically (inject under your own token).
+- **i18n** at the `@velajs/vela/i18n` subpath (keeps core lean; `intl-messageformat` is an optional peer dep): `I18nModule.forRoot()` + `registerMessages()` (deep-merged, HMR-safe globalThis registry), ICU formatting, header/query/cookie locale detection. `I18nService` is request-scoped and reads the per-request locale; injecting it into a controller is safe thanks to request-scope bubbling (no `ambientContainer` flag needed).
+- **Storage abstractions** at the `@velajs/vela/storage` subpath (dep-free, Web Crypto only): the `StorageDriver` contract, `expandPathTemplate`/`joinStoragePath`, and HMAC `signUrl`/`verifySignedUrl`. `@velajs/cloudflare` builds on them with a multi-disk `StorageModule` over R2 (`StorageService.put/get/delete/exists/url`, per-disk roots with `{date}`/`{year}`/… templates, bucket-by-name via `EnvService`) plus a signature-gated `StorageController` presign-proxy (R2 has no native presign).
+- **Seeders** at the `@velajs/vela/seeder` subpath: `@Seeder({ order })`, `SeederModule` (`forRoot({ seeders })`), and `SeederRegistry`/`runSeeders(app)` — decorator discovery at bootstrap (mirrors `ScheduleRegistry`), each seeder run in a request-scoped child. Paired with the **new `@velajs/cli` package** (clipanion) providing `vela db seed` driven by a `vela.config.{js,mjs,ts}` app factory (Node-side; kept out of the Worker bundle).
+
+### Changed
+
+- **Request-scope bubbling.** A provider (including controllers, which are singletons) that transitively depends on a request-scoped provider is now automatically treated as request-scoped — rebuilt per request instead of capturing the first request's instance. Matches NestJS; computed once at bootstrap (`Container.computeEffectiveScopes`), governs caching + eager instantiation. Fixes the captive-dependency hazard for request-scoped services injected into controllers.
+- **HMR-safe `MetadataRegistry`**: all backing state is now anchored on `globalThis` via `Symbol.for('vela:registry:v1')`, so a Vite dev re-eval reuses the state classes were decorated against (no split-brain: lost routes / spurious "not @Injectable" warnings / duplicated globals). No API change.
+- **`CacheModule`** now accepts an optional custom sync `store` in its options.
+
 ## 1.8.1 (2026-05-14)
 
 ### Revert

package/dist/__tests__/workers-als/entry-als.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+    fetch(request: Request): Promise<Response>;
+};
+export default _default;
+declare global {
+    interface ExportedHandler<Env = unknown> {
+        fetch?(request: Request, env: Env, ctx: unknown): Response | Promise<Response>;
+    }
+}

package/dist/application.d.ts

@@ -9,6 +9,7 @@ export declare class VelaApplication {
     private readonly routeManager;
     private instances;
     private honoApp;
+    private disposed;
     constructor(container: Container, routeManager: RouteManager);
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */
     initRoutes(): Promise<void>;
@@ -44,4 +45,13 @@ export declare class VelaApplication {
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
     close(signal?: string): Promise<void>;
+    /**
+     * Full teardown: run shutdown lifecycle hooks ({@link close}) then dispose
+     * container-held instances (LIFO) and clear cached singletons. Use for
+     * graceful shutdown and dev HMR so old and new DI graphs never coexist.
+     *
+     * On runtimes/TS supporting explicit resource management this is also exposed
+     * as `Symbol.asyncDispose`, enabling `await using app = await VelaFactory.create(...)`.
+     */
+    dispose(signal?: string): Promise<void>;
 }

package/dist/application.js

@@ -7,6 +7,7 @@ export class VelaApplication {
     routeManager;
     instances = [];
     honoApp = null;
+    disposed = false;
     constructor(container, routeManager){
         this.container = container;
         this.routeManager = routeManager;
@@ -157,4 +158,28 @@ export class VelaApplication {
             }
         }
     }
+    /**
+   * Full teardown: run shutdown lifecycle hooks ({@link close}) then dispose
+   * container-held instances (LIFO) and clear cached singletons. Use for
+   * graceful shutdown and dev HMR so old and new DI graphs never coexist.
+   *
+   * On runtimes/TS supporting explicit resource management this is also exposed
+   * as `Symbol.asyncDispose`, enabling `await using app = await VelaFactory.create(...)`.
+   */ async dispose(signal) {
+        // Idempotent: `await using` + an explicit dispose(), or repeated shutdown
+        // signals, must not re-run shutdown lifecycle hooks.
+        if (this.disposed) return;
+        this.disposed = true;
+        await this.close(signal);
+        await this.container.dispose();
+    }
+}
+// Attach the well-known async-dispose symbol at runtime (it is not in the
+// ES2022 lib the project compiles against) so `await using` works where
+// supported, without a type dependency on esnext.disposable.
+const ASYNC_DISPOSE = Symbol.asyncDispose;
+if (ASYNC_DISPOSE) {
+    VelaApplication.prototype[ASYNC_DISPOSE] = function() {
+        return this.dispose();
+    };
 }

package/dist/cache/cache.module.d.ts

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

package/dist/cache/cache.module.js

@@ -1,80 +1,58 @@
-import { stableHash } from "../module/stable-hash.js";
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { Module } from "../module/decorators.js";
+import { ConfigurableModuleBuilder } from "../module/configurable-module.builder.js";
 import { APP_INTERCEPTOR } from "../pipeline/tokens.js";
 import { CacheInterceptor } from "./cache.interceptor.js";
 import { CacheService } from "./cache.service.js";
 import { MemoryCacheStore } from "./cache.store.js";
 import { CACHE_MANAGER, CACHE_MODULE_OPTIONS } from "./cache.tokens.js";
-export class CacheModule {
-    static forRoot(options = {}) {
-        const { ttl = 5, max = 100, isGlobal = false } = options;
-        const store = new MemoryCacheStore(ttl, max);
-        const providers = [
-            {
-                provide: CACHE_MANAGER,
-                useValue: store
-            },
+// Reuse the public CACHE_MODULE_OPTIONS token so its identity (and the
+// index.ts export) is unchanged. `isGlobal` here means "register the interceptor
+// globally as APP_INTERCEPTOR" — NOT `DynamicModule.global` — so the extras
+// transform is customized rather than using the default isGlobal→global.
+const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = new ConfigurableModuleBuilder({
+    moduleName: 'Cache',
+    optionsInjectionToken: CACHE_MODULE_OPTIONS
+}).setExtras({
+    isGlobal: false
+}, (definition, { isGlobal })=>isGlobal ? {
+        ...definition,
+        providers: [
+            ...definition.providers ?? [],
             {
-                provide: CACHE_MODULE_OPTIONS,
-                useValue: options
-            },
-            CacheService,
-            CacheInterceptor
-        ];
-        if (isGlobal) {
-            providers.push({
                 provide: APP_INTERCEPTOR,
                 useExisting: CacheInterceptor
-            });
-        }
-        return {
-            module: CacheModule,
-            key: stableHash(options),
-            providers,
-            exports: [
-                CACHE_MANAGER,
-                CACHE_MODULE_OPTIONS,
-                CacheService,
-                CacheInterceptor
-            ]
-        };
-    }
-    static forRootAsync(options) {
-        const providers = [
-            {
-                provide: CACHE_MODULE_OPTIONS,
-                useFactory: options.useFactory,
-                inject: options.inject ?? []
-            },
+            }
+        ]
+    } : definition).build();
+export class CacheModule extends ConfigurableModuleClass {
+}
+CacheModule = _ts_decorate([
+    Module({
+        providers: [
+            CacheService,
+            CacheInterceptor,
+            // One options-injecting provider serves BOTH forRoot and forRootAsync.
+            // A custom `store` (e.g. TieredCacheStore / KVCacheStore) overrides the
+            // default in-memory store.
             {
                 provide: CACHE_MANAGER,
-                useFactory: (opts)=>new MemoryCacheStore(opts.ttl ?? 5, opts.max ?? 100),
+                useFactory: (options)=>options.store ?? new MemoryCacheStore(options.ttl ?? 5, options.max ?? 100),
                 inject: [
-                    CACHE_MODULE_OPTIONS
+                    MODULE_OPTIONS_TOKEN
                 ]
-            },
+            }
+        ],
+        exports: [
+            CACHE_MANAGER,
+            CACHE_MODULE_OPTIONS,
             CacheService,
             CacheInterceptor
-        ];
-        if (options.isGlobal) {
-            providers.push({
-                provide: APP_INTERCEPTOR,
-                useExisting: CacheInterceptor
-            });
-        }
-        return {
-            module: CacheModule,
-            key: options.key ?? stableHash({
-                inject: options.inject,
-                useFactory: options.useFactory
-            }),
-            imports: options.imports ?? [],
-            providers,
-            exports: [
-                CACHE_MANAGER,
-                CACHE_MODULE_OPTIONS,
-                CacheService,
-                CacheInterceptor
-            ]
-        };
-    }
-}
+        ]
+    })
+], CacheModule);

package/dist/cache/cache.types.d.ts

@@ -1,14 +1,40 @@
+/** A value that may be returned synchronously or as a promise. */
+export type Awaitable<T> = T | Promise<T>;
 export interface CacheModuleOptions {
     ttl?: number;
     max?: number;
     isGlobal?: boolean;
+    /**
+     * Custom SYNC backing store (replaces the default in-memory store). For async
+     * (KV/tiered) caching use {@link AsyncCacheStore} + `TieredCacheStore`
+     * programmatically — the interceptor/CacheService path is synchronous.
+     */
+    store?: CacheStore;
 }
+/**
+ * Synchronous cache backing store. This is the original, stable contract used by
+ * `CacheService` and `CacheInterceptor` — unchanged.
+ */
 export interface CacheStore {
     get<T = unknown>(key: string): T | undefined;
     set<T = unknown>(key: string, value: T, ttl?: number): void;
     del(key: string): void;
     clear(): void;
 }
+/**
+ * Asynchronous cache backing store (additive). Implemented by remote/tiered
+ * stores (`TieredCacheStore`, and `KVCacheStore` in `@velajs/cloudflare`) where
+ * reads/writes are inherently async. Use it programmatically — inject the store
+ * under your own token — rather than as the synchronous `CACHE_MANAGER`.
+ */
+export interface AsyncCacheStore {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** A store that may be sync or async (used to compose tiers). */
+export type AnyCacheStore = CacheStore | AsyncCacheStore;
 export interface CacheEntry<T = unknown> {
     value: T;
     expiresAt: number;

package/dist/cache/cache.types.js

@@ -1 +1 @@
-export { };
+/** A value that may be returned synchronously or as a promise. */ export { };

package/dist/cache/index.d.ts

@@ -2,6 +2,7 @@ export { CacheModule } from './cache.module';
 export { CacheService } from './cache.service';
 export { CacheInterceptor } from './cache.interceptor';
 export { MemoryCacheStore } from './cache.store';
+export { TieredCacheStore } from './tiered-cache.store';
 export { CacheKey, CacheTTL } from './cache.decorators';
 export { CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA } from './cache.tokens';
-export type { CacheModuleOptions, CacheStore, CacheEntry } from './cache.types';
+export type { Awaitable, CacheModuleOptions, CacheStore, AsyncCacheStore, AnyCacheStore, CacheEntry, } from './cache.types';

package/dist/cache/index.js

@@ -2,5 +2,6 @@ export { CacheModule } from "./cache.module.js";
 export { CacheService } from "./cache.service.js";
 export { CacheInterceptor } from "./cache.interceptor.js";
 export { MemoryCacheStore } from "./cache.store.js";
+export { TieredCacheStore } from "./tiered-cache.store.js";
 export { CacheKey, CacheTTL } from "./cache.decorators.js";
 export { CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA } from "./cache.tokens.js";

package/dist/cache/tiered-cache.store.d.ts

@@ -0,0 +1,19 @@
+import type { AnyCacheStore, AsyncCacheStore } from './cache.types';
+/**
+ * Composes an ordered list of cache tiers (fastest first, e.g. in-memory L1 →
+ * KV L2). Tiers may be sync ({@link CacheStore}) or async ({@link AsyncCacheStore}) —
+ * results are awaited uniformly. Reads are read-through: the first tier with a
+ * hit wins, and nearer tiers that missed are backfilled. Writes/deletes/clears
+ * fan out to all tiers. Always async ({@link AsyncCacheStore}).
+ *
+ * Runtime-agnostic — the concrete tiers (memory here, KV in `@velajs/cloudflare`)
+ * live wherever fits.
+ */
+export declare class TieredCacheStore implements AsyncCacheStore {
+    private readonly tiers;
+    constructor(tiers: AnyCacheStore[]);
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/cache/tiered-cache.store.js

@@ -0,0 +1,40 @@
+/**
+ * Composes an ordered list of cache tiers (fastest first, e.g. in-memory L1 →
+ * KV L2). Tiers may be sync ({@link CacheStore}) or async ({@link AsyncCacheStore}) —
+ * results are awaited uniformly. Reads are read-through: the first tier with a
+ * hit wins, and nearer tiers that missed are backfilled. Writes/deletes/clears
+ * fan out to all tiers. Always async ({@link AsyncCacheStore}).
+ *
+ * Runtime-agnostic — the concrete tiers (memory here, KV in `@velajs/cloudflare`)
+ * live wherever fits.
+ */ export class TieredCacheStore {
+    tiers;
+    constructor(tiers){
+        if (tiers.length === 0) {
+            throw new Error('TieredCacheStore requires at least one tier.');
+        }
+        this.tiers = tiers;
+    }
+    async get(key) {
+        for(let i = 0; i < this.tiers.length; i++){
+            const value = await this.tiers[i].get(key);
+            if (value !== undefined) {
+                // Backfill nearer (faster) tiers that missed.
+                for(let j = 0; j < i; j++){
+                    await this.tiers[j].set(key, value);
+                }
+                return value;
+            }
+        }
+        return undefined;
+    }
+    async set(key, value, ttl) {
+        await Promise.all(this.tiers.map((tier)=>tier.set(key, value, ttl)));
+    }
+    async del(key) {
+        await Promise.all(this.tiers.map((tier)=>tier.del(key)));
+    }
+    async clear() {
+        await Promise.all(this.tiers.map((tier)=>tier.clear()));
+    }
+}

package/dist/config/config.module.d.ts

@@ -1,11 +1,12 @@
-import type { AsyncModuleOptions, DynamicModule } from '../module/types';
+import type { DynamicModule } from '../module/types';
 import type { ConfigModuleOptions } from './config.types';
-export declare class ConfigModule {
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<ConfigModuleOptions<Record<string, unknown>>, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class ConfigModule extends ConfigurableModuleClass {
     static forRoot<T extends Record<string, unknown>>(options: ConfigModuleOptions<T> & {
-        key?: string;
-    }): DynamicModule;
-    static forRootAsync<T extends Record<string, unknown>>(options: AsyncModuleOptions<ConfigModuleOptions<T>> & {
         isGlobal?: boolean;
         key?: string;
     }): DynamicModule;
 }
+export {};

package/dist/config/config.module.js

@@ -1,54 +1,51 @@
-import { stableHash } from "../module/stable-hash.js";
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { Module } from "../module/decorators.js";
+import { ConfigurableModuleBuilder } from "../module/configurable-module.builder.js";
 import { ConfigService } from "./config.service.js";
 import { CONFIG_OPTIONS } from "./config.tokens.js";
-export class ConfigModule {
+// MODULE_OPTIONS_TOKEN carries the RAW options; CONFIG_OPTIONS stays the
+// distinct validated-record token, derived in @Module. The derived provider
+// validates the forRootAsync path lazily (its factory is deferred); forRoot
+// validates eagerly at call time (see the override below), matching the
+// long-standing contract, and passes an already-validated config through.
+const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = new ConfigurableModuleBuilder({
+    moduleName: 'Config'
+}).build();
+export class ConfigModule extends ConfigurableModuleClass {
+    // Preserve (a) per-call generic inference over the config record and (b) the
+    // eager-validation contract: forRoot validates at call time so bad config
+    // fails fast. `super.forRoot` runs the generated static with `this === ConfigModule`.
     static forRoot(options) {
-        const config = options.validate ? options.validate(options.config) : options.config;
-        return {
-            module: ConfigModule,
-            key: options.key ?? stableHash(options.config),
-            providers: [
-                {
-                    provide: CONFIG_OPTIONS,
-                    useValue: config
-                },
-                ConfigService
-            ],
-            exports: [
-                ConfigService,
-                CONFIG_OPTIONS
-            ],
-            ...options.isGlobal ? {
-                global: true
-            } : {}
-        };
-    }
-    static forRootAsync(options) {
-        return {
-            module: ConfigModule,
-            key: options.key ?? stableHash({
-                inject: options.inject,
-                useFactory: options.useFactory
-            }),
-            imports: options.imports ?? [],
-            providers: [
-                {
-                    provide: CONFIG_OPTIONS,
-                    useFactory: async (...args)=>{
-                        const opts = await options.useFactory(...args);
-                        return opts.validate ? opts.validate(opts.config) : opts.config;
-                    },
-                    inject: options.inject ?? []
-                },
-                ConfigService
-            ],
-            exports: [
-                ConfigService,
-                CONFIG_OPTIONS
-            ],
-            ...options.isGlobal ? {
-                global: true
-            } : {}
-        };
+        const validated = options.validate ? options.validate(options.config) : options.config;
+        // Strip `validate` so the derived CONFIG_OPTIONS provider is a passthrough
+        // (no double validation) for the already-validated config.
+        const { validate: _validate, ...rest } = options;
+        return super.forRoot({
+            ...rest,
+            config: validated
+        });
     }
 }
+ConfigModule = _ts_decorate([
+    Module({
+        providers: [
+            ConfigService,
+            {
+                provide: CONFIG_OPTIONS,
+                useFactory: (options)=>options.validate ? options.validate(options.config) : options.config,
+                inject: [
+                    MODULE_OPTIONS_TOKEN
+                ]
+            }
+        ],
+        exports: [
+            ConfigService,
+            CONFIG_OPTIONS
+        ]
+    })
+], ConfigModule);

package/dist/container/container.d.ts

@@ -17,6 +17,8 @@ export declare class Container {
     private scopes;
     private globals;
     private diagnostics;
+    private root;
+    private disposables;
     constructor(options?: ContainerOptions);
     register<T>(provider: Type<T> | ProviderOptions<T>, declaringModuleId?: string): this;
     private registerClass;
@@ -52,6 +54,24 @@ export declare class Container {
     hasInScope(token: Token, moduleId: string): boolean;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
+    /**
+     * 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(): unknown[];
+    /**
+     * 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(): void;
+    /** The dependency tokens a registration would resolve when constructed. */
+    private dependencyTokensOf;
+    private tryFindRegistration;
     /**
      * Create a child container for request-scoped resolution.
      * The child shares the parent's providers but caches REQUEST-scoped
@@ -60,6 +80,19 @@ export declare class Container {
     createChild(): Container;
     createDetached(): Container;
     clear(): void;
+    /** Whether this container has any tracked disposables (cheap request-path check). */
+    hasDisposables(): boolean;
+    /**
+     * 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).
+     */
+    dispose(): Promise<void>;
     private resolveRegistration;
     private resolveClass;
     private resolveFactory;