@velajs/vela 1.12.0 → 1.14.0

package/dist/index.js

@@ -48,7 +48,7 @@ export { registerRouteContributor, getRouteContributors } from "./http/route-con
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
 // Built-in Pipes
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipeline/index.js";
 // Errors

package/dist/module/decorators.js

@@ -16,7 +16,8 @@ export function Module(options = {}) {
             providers: options.providers,
             controllers: options.controllers,
             exports: options.exports,
-            isGlobal: options.isGlobal
+            isGlobal: options.isGlobal,
+            lazy: options.lazy
         });
     };
 }
@@ -40,6 +41,7 @@ export function getModuleMetadata(target) {
         controllers: options.controllers ?? [],
         imports: options.imports ?? [],
         exports: options.exports ?? [],
-        isGlobal: options.isGlobal === true
+        isGlobal: options.isGlobal === true,
+        lazy: options.lazy === true
     };
 }

package/dist/module/define-module.d.ts

@@ -66,6 +66,13 @@ export interface DefineModuleSpec<Opts, Extras extends ConfigurableModuleExtras
     methodName?: MethodKey;
     /** Method a `useClass`/`useExisting` options factory must implement (default `create`). */
     factoryMethodName?: FactoryMethodKey;
+    /**
+     * Default every generated module instance to deferred (first-use)
+     * materialization. Call sites can also opt in per instance by passing
+     * `lazy: true` alongside the options (recognized like `isGlobal`).
+     * See MODULE_AUTHORING.md "Lazy modules".
+     */
+    lazy?: boolean;
 }
 /**
  * The one blessed module-authoring engine. Generates `forRoot` AND

package/dist/module/define-module.js

@@ -76,6 +76,11 @@ const ASYNC_OPTION_KEYS = new Set([
     const extrasDefaults = spec.extras ?? DEFAULT_EXTRAS;
     const transform = spec.transform ?? DEFAULT_TRANSFORM;
     const deriveKey = (explicit, structural)=>explicit ?? spec.key?.(structural) ?? stableHash(structural);
+    // Laziness is OR-composed: the spec defaults it, a call site can add it.
+    const applyLazy = (definition, callSiteLazy)=>spec.lazy === true || callSiteLazy === true ? {
+            ...definition,
+            lazy: true
+        } : definition;
     const applyContributions = (definition, structural, key)=>{
         if (!spec.setup) return definition;
         const contributions = spec.setup({
@@ -127,10 +132,10 @@ const ASYNC_OPTION_KEYS = new Set([
                     }
                 ]
             };
-            return transform(applyContributions(definition, rest, key), {
+            return applyLazy(transform(applyContributions(definition, rest, key), {
                 ...extrasDefaults,
                 ...rest
-            });
+            }), rest.lazy);
         }
     });
     Object.defineProperty(GeneratedModuleClass, asyncName, {
@@ -159,10 +164,10 @@ const ASYNC_OPTION_KEYS = new Set([
                 imports: bag.imports ?? [],
                 providers: buildAsyncOptionsProviders(optionsToken, factoryMethodName, bag, structural)
             };
-            return transform(applyContributions(definition, structural, key), {
+            return applyLazy(transform(applyContributions(definition, structural, key), {
                 ...extrasDefaults,
                 ...structural
-            });
+            }), structural.lazy);
         }
     });
     return {

package/dist/module/lazy-modules.d.ts

@@ -0,0 +1,82 @@
+import type { Container } from '../container/container';
+import type { LazyResolutionHook, Token } from '../container/types';
+/** One lazy module instance's deferral unit: its own tokens, in registration order. */
+export interface LazyModuleGroup {
+    moduleId: string;
+    tokens: Token[];
+    /**
+     * A class provider's prototype declares `collectEntrypoints` — the module
+     * must be materialized before the entrypoint registry snapshot or its
+     * computed contributions would be silently absent.
+     */
+    hasEntrypointContributor: boolean;
+}
+/**
+ * Owns deferred-module state for one application: which module instances are
+ * still pending, which have been claimed by a container trigger, and how
+ * claimed groups get completed (construction + lifecycle-hook replay).
+ *
+ * Phases:
+ * - `'bootstrap'` (until the end of `callOnApplicationBootstrap`): completed
+ *   groups are *absorbed* — their instances queue up for the application's
+ *   normal hook phases, so a lazy module dragged in by an eager consumer gets
+ *   today-identical semantics.
+ * - `'live'`: hooks replay at drain time (memoized, exactly once), then the
+ *   instances are handed to the application for shutdown-hook symmetry.
+ *
+ * Sync/async duality: sync drains throw a descriptive error when a member
+ * factory or hook yields a thenable — lazy modules with async providers or
+ * hooks must be reached through an async seam (`materializeLazyModules()`,
+ * `resolveAsync`) or stay eager.
+ */
+export declare class LazyModuleManager implements LazyResolutionHook {
+    private readonly container;
+    private readonly pending;
+    private readonly claimed;
+    private readonly absorbed;
+    private phase;
+    private draining;
+    private drainPromise?;
+    private onMaterialized?;
+    constructor(container: Container);
+    registerGroup(group: LazyModuleGroup): void;
+    /** Application sink for live-phase materializations (shutdown symmetry). */
+    setOnMaterialized(sink: (instances: unknown[]) => void): void;
+    setPhaseLive(): void;
+    isPending(moduleId: string): boolean;
+    /** Tokens whose owning modules are ALL still pending are deferred. */
+    hasPendingModules(): boolean;
+    claim(moduleId: string): void;
+    hasClaimed(): boolean;
+    /**
+     * A drain loop is running. The container consults this before its
+     * post-resolution drain: `constructGroupAsync` resolves members through
+     * `resolveAsync`, whose end-of-cascade check would otherwise re-enter and
+     * AWAIT the very drain promise it is executing inside — a self-referential
+     * await that never settles (with ≥2 claimed groups). Claims made while
+     * draining are picked up by the running loop instead.
+     */
+    isDraining(): boolean;
+    /** Instances constructed during the bootstrap phase, owed their hooks. */
+    takeAbsorbed(): unknown[];
+    drainSync(): void;
+    drainAsync(): Promise<void>;
+    /**
+     * Materialize every still-pending group whose providers compute entrypoints
+     * (`collectEntrypoints` on a class prototype). Called by the application
+     * right before the entrypoint-registry snapshot so computed contributions
+     * are never silently absent. The cost — those modules are effectively
+     * eager — is the documented price of contributing computed entrypoints.
+     */
+    materializeContributors(): Promise<void>;
+    /** Materialize everything still pending (warmup / tests / node runtimes). */
+    materializeAll(): Promise<void>;
+    private groupTokensToConstruct;
+    private constructGroupSync;
+    private constructGroupAsync;
+    /** Reversed batch = dependency-before-consumer (see drainSync comment). */
+    private orderBatch;
+    private finishBatchSync;
+    private finishBatchAsync;
+    private describeSyncFailure;
+}

package/dist/module/lazy-modules.js

@@ -0,0 +1,231 @@
+import { Scope } from "../constants.js";
+import { hasOnApplicationBootstrap, hasOnModuleInit } from "../lifecycle/index.js";
+function isThenable(x) {
+    return x !== null && (typeof x === 'object' || typeof x === 'function') && typeof x.then === 'function';
+}
+/**
+ * Owns deferred-module state for one application: which module instances are
+ * still pending, which have been claimed by a container trigger, and how
+ * claimed groups get completed (construction + lifecycle-hook replay).
+ *
+ * Phases:
+ * - `'bootstrap'` (until the end of `callOnApplicationBootstrap`): completed
+ *   groups are *absorbed* — their instances queue up for the application's
+ *   normal hook phases, so a lazy module dragged in by an eager consumer gets
+ *   today-identical semantics.
+ * - `'live'`: hooks replay at drain time (memoized, exactly once), then the
+ *   instances are handed to the application for shutdown-hook symmetry.
+ *
+ * Sync/async duality: sync drains throw a descriptive error when a member
+ * factory or hook yields a thenable — lazy modules with async providers or
+ * hooks must be reached through an async seam (`materializeLazyModules()`,
+ * `resolveAsync`) or stay eager.
+ */ export class LazyModuleManager {
+    container;
+    pending = new Map();
+    claimed = [];
+    absorbed = [];
+    phase = 'bootstrap';
+    draining = false;
+    // In-flight async drain: concurrent drainAsync callers must await the SAME
+    // completion (the running loop picks their claims up), never resolve early
+    // with a group's hooks still pending.
+    drainPromise;
+    onMaterialized;
+    constructor(container){
+        this.container = container;
+    }
+    registerGroup(group) {
+        this.pending.set(group.moduleId, group);
+    }
+    /** Application sink for live-phase materializations (shutdown symmetry). */ setOnMaterialized(sink) {
+        this.onMaterialized = sink;
+    }
+    setPhaseLive() {
+        this.phase = 'live';
+    }
+    isPending(moduleId) {
+        return this.pending.has(moduleId);
+    }
+    /** Tokens whose owning modules are ALL still pending are deferred. */ hasPendingModules() {
+        return this.pending.size > 0;
+    }
+    claim(moduleId) {
+        const group = this.pending.get(moduleId);
+        if (!group) return;
+        this.pending.delete(moduleId);
+        this.claimed.push(group);
+    }
+    hasClaimed() {
+        return this.claimed.length > 0;
+    }
+    /**
+   * A drain loop is running. The container consults this before its
+   * post-resolution drain: `constructGroupAsync` resolves members through
+   * `resolveAsync`, whose end-of-cascade check would otherwise re-enter and
+   * AWAIT the very drain promise it is executing inside — a self-referential
+   * await that never settles (with ≥2 claimed groups). Claims made while
+   * draining are picked up by the running loop instead.
+   */ isDraining() {
+        return this.draining;
+    }
+    /** Instances constructed during the bootstrap phase, owed their hooks. */ takeAbsorbed() {
+        if (this.absorbed.length === 0) return [];
+        return this.absorbed.splice(0, this.absorbed.length);
+    }
+    drainSync() {
+        if (this.draining) return;
+        this.draining = true;
+        try {
+            // Construct-all-then-hook, batch by batch: a cascade's groups arrive in
+            // consumer-before-dependency claim order (the consumer's token resolves
+            // first; constructing it claims its deps), so hook phases run over the
+            // REVERSED batch — dependency-before-consumer, matching what the eager
+            // bootstrap would have produced. Hooks can claim further groups
+            // (discovery cascades) → outer loop.
+            while(this.claimed.length > 0){
+                const batch = [];
+                while(this.claimed.length > 0){
+                    const group = this.claimed.shift();
+                    batch.push({
+                        group,
+                        instances: this.constructGroupSync(group)
+                    });
+                }
+                this.finishBatchSync(batch);
+            }
+        } finally{
+            this.draining = false;
+        }
+    }
+    drainAsync() {
+        if (this.draining) {
+            // External concurrent callers await the in-flight completion (its loop
+            // picks their claims up). Callers INSIDE the drain's own await chain
+            // never reach here — the container skips its post-resolution drain
+            // while isDraining() (self-await would deadlock).
+            return this.drainPromise ?? Promise.resolve();
+        }
+        this.draining = true;
+        const run = (async ()=>{
+            try {
+                while(this.claimed.length > 0){
+                    const batch = [];
+                    while(this.claimed.length > 0){
+                        const group = this.claimed.shift();
+                        batch.push({
+                            group,
+                            instances: await this.constructGroupAsync(group)
+                        });
+                    }
+                    await this.finishBatchAsync(batch);
+                }
+            } finally{
+                this.draining = false;
+                this.drainPromise = undefined;
+            }
+        })();
+        this.drainPromise = run;
+        return run;
+    }
+    /**
+   * Materialize every still-pending group whose providers compute entrypoints
+   * (`collectEntrypoints` on a class prototype). Called by the application
+   * right before the entrypoint-registry snapshot so computed contributions
+   * are never silently absent. The cost — those modules are effectively
+   * eager — is the documented price of contributing computed entrypoints.
+   */ async materializeContributors() {
+        for (const group of [
+            ...this.pending.values()
+        ]){
+            if (group.hasEntrypointContributor) this.claim(group.moduleId);
+        }
+        await this.drainAsync();
+    }
+    /** Materialize everything still pending (warmup / tests / node runtimes). */ async materializeAll() {
+        for (const moduleId of [
+            ...this.pending.keys()
+        ])this.claim(moduleId);
+        await this.drainAsync();
+    }
+    groupTokensToConstruct(group) {
+        return group.tokens.filter((token)=>this.container.getProviderScope(token) !== Scope.REQUEST);
+    }
+    constructGroupSync(group) {
+        const out = new Set();
+        for (const token of this.groupTokensToConstruct(group)){
+            try {
+                out.add(this.container.resolve(token, group.moduleId));
+            } catch (error) {
+                // Only the sync-resolution-of-async-factory error is a seam problem;
+                // genuine provider failures must surface untouched.
+                if (error instanceof Error && error.message.includes('returned a Promise')) {
+                    throw this.describeSyncFailure(group.moduleId, error);
+                }
+                throw error;
+            }
+        }
+        return [
+            ...out
+        ];
+    }
+    async constructGroupAsync(group) {
+        const out = new Set();
+        for (const token of this.groupTokensToConstruct(group)){
+            out.add(await this.container.resolveAsync(token, group.moduleId));
+        }
+        return [
+            ...out
+        ];
+    }
+    /** Reversed batch = dependency-before-consumer (see drainSync comment). */ orderBatch(batch) {
+        return [
+            ...batch
+        ].reverse();
+    }
+    finishBatchSync(batch) {
+        const ordered = this.orderBatch(batch);
+        if (this.phase === 'bootstrap') {
+            for (const { instances } of ordered)this.absorbed.push(...instances);
+            return;
+        }
+        for (const { group, instances } of ordered){
+            for (const instance of instances){
+                if (hasOnModuleInit(instance) && isThenable(instance.onModuleInit())) {
+                    throw this.describeSyncFailure(group.moduleId);
+                }
+            }
+        }
+        for (const { group, instances } of ordered){
+            for (const instance of instances){
+                if (hasOnApplicationBootstrap(instance) && isThenable(instance.onApplicationBootstrap())) {
+                    throw this.describeSyncFailure(group.moduleId);
+                }
+            }
+        }
+        this.onMaterialized?.(ordered.flatMap((b)=>b.instances));
+    }
+    async finishBatchAsync(batch) {
+        const ordered = this.orderBatch(batch);
+        if (this.phase === 'bootstrap') {
+            for (const { instances } of ordered)this.absorbed.push(...instances);
+            return;
+        }
+        for (const { instances } of ordered){
+            for (const instance of instances){
+                if (hasOnModuleInit(instance)) await instance.onModuleInit();
+            }
+        }
+        for (const { instances } of ordered){
+            for (const instance of instances){
+                if (hasOnApplicationBootstrap(instance)) await instance.onApplicationBootstrap();
+            }
+        }
+        this.onMaterialized?.(ordered.flatMap((b)=>b.instances));
+    }
+    describeSyncFailure(moduleId, cause) {
+        return new Error(`[vela] lazy module '${moduleId}' has async providers or lifecycle hooks and was ` + `triggered through a synchronous resolution path. Reach it through an async seam ` + `first (app.materializeLazyModules(), an async provider) or remove lazy: true.`, cause !== undefined ? {
+            cause
+        } : undefined);
+    }
+}

package/dist/module/module-loader.d.ts

@@ -2,6 +2,12 @@ import type { Container } from "../container/container";
 import type { Token, Type } from "../container/types";
 import type { RouteManager } from "../http/route.manager";
 import type { MiddlewareRouteDefinition } from "./middleware";
+/** What the loader records per lazy module instance (see LazyModuleManager). */
+export interface LazyModuleGroupSpec {
+    moduleId: string;
+    tokens: Token[];
+    hasEntrypointContributor: boolean;
+}
 export declare class ModuleLoader {
     private container;
     private router;
@@ -16,6 +22,8 @@ export declare class ModuleLoader {
     private appProviderTokens;
     private moduleIdByClassKey;
     private seenModuleIds;
+    private lazyModuleIds;
+    private lazyGroups;
     constructor(container: Container, router: RouteManager);
     load(rootModule: Type): void;
     private getModuleId;
@@ -25,6 +33,7 @@ export declare class ModuleLoader {
     private cacheExports;
     private processModule;
     private warnOnMixedDefaultAndKeyed;
+    /** Registers the provider and returns the token it was registered under. */
     private registerProvider;
     private isAppToken;
     private buildExportSet;
@@ -32,6 +41,18 @@ export declare class ModuleLoader {
     getRegisteredProviders(): Token[];
     getAppProviderTokens(token: Token): Token[];
     getConsumerMiddlewareDefinitions(): MiddlewareRouteDefinition[];
+    /**
+     * Every lazy module instance recorded during load. Handed to the
+     * LazyModuleManager at bootstrap; empty when no module opted in.
+     */
+    getLazyGroups(): LazyModuleGroupSpec[];
+    /**
+     * A token is deferred iff EVERY module bucket holding it belongs to a lazy
+     * module instance — a token also registered by a non-lazy module stays on
+     * the eager pass (and resolving it there claims the lazy sibling, which is
+     * the "any use = init" semantic, not a bug).
+     */
+    private isLazyOnlyToken;
     resolveAllInstances(): Promise<unknown[]>;
     private routeError;
 }

package/dist/module/module-loader.js

@@ -4,6 +4,7 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { getOrCreateArray } from "../registry/util.js";
 import { getModuleMetadata, isModule } from "./decorators.js";
+import { LazyModuleManager } from "./lazy-modules.js";
 import { MiddlewareBuilder } from "./middleware.js";
 const APP_TOKENS = new Set([
     APP_GUARD,
@@ -13,6 +14,16 @@ const APP_TOKENS = new Set([
     APP_MIDDLEWARE
 ]);
 const DEFAULT_KEY = "default";
+/**
+ * Structural check for `ContributesEntrypoints` on a provider's class —
+ * deliberately string-coupled to the interface's method name so the loader
+ * does not import from `entrypoint/` (layering).
+ */ function declaresEntrypointContributor(provider) {
+    const cls = typeof provider === "function" ? provider : provider.useClass;
+    if (typeof cls !== "function") return false;
+    const proto = cls.prototype;
+    return typeof proto?.collectEntrypoints === "function";
+}
 function isDynamicModule(value) {
     // TS 4.9+ narrows `'module' in value` so `value.module` is typed `unknown`
     // — no cast required for the typeof check below.
@@ -78,6 +89,10 @@ export class ModuleLoader {
     // (class, key) → composed moduleId (cached for stable identity within a load)
     moduleIdByClassKey = new Map();
     seenModuleIds = new Set();
+    // Lazy (deferred-init) module instances: moduleId → its own tokens in
+    // registration order. Consumed by LazyModuleManager via getLazyGroups().
+    lazyModuleIds = new Set();
+    lazyGroups = new Map();
     constructor(container, router){
         this.container = container;
         this.router = router;
@@ -87,6 +102,23 @@ export class ModuleLoader {
         for (const controller of this.collectedControllers){
             this.router.registerController(controller);
         }
+        // Arm the deferred-init seam HERE — at the end of load(), not in
+        // bootstrap() — so every consumer of the loader gets identical lazy
+        // semantics, including hand-rolled bootstrap paths that never call
+        // bootstrap() (@velajs/testing's TestingModuleBuilder.compile builds its
+        // own container). Still after all module-load-time resolutions
+        // (NestModule.configure), so load-time resolution never claims a group.
+        // Registered as a provider so VelaApplication can drive the phase
+        // transitions from any of those paths.
+        const lazyManager = new LazyModuleManager(this.container);
+        for (const group of this.getLazyGroups()){
+            lazyManager.registerGroup(group);
+        }
+        this.container.setLazyHook(lazyManager);
+        this.container.register({
+            provide: LazyModuleManager,
+            useValue: lazyManager
+        });
     }
     getModuleId(moduleClass, key) {
         let perClass = this.moduleIdByClassKey.get(moduleClass);
@@ -238,21 +270,38 @@ export class ModuleLoader {
             // include it in its own scope.
             localProviders.add(moduleClass);
             const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
+            const isLazy = metadata.lazy || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.lazy === true;
             this.container.registerScope({
                 moduleId,
                 localProviders,
                 importedModules: importedModuleIds,
                 exportedTokens: new Set(allExports),
-                isGlobal
+                isGlobal,
+                lazy: isLazy
             });
+            const lazyTokens = [];
+            let hasEntrypointContributor = false;
             for (const provider of allProviders){
-                this.registerProvider(provider, moduleId);
+                const registered = this.registerProvider(provider, moduleId);
+                if (isLazy && registered !== undefined) {
+                    lazyTokens.push(registered);
+                    hasEntrypointContributor ||= declaresEntrypointContributor(provider);
+                }
             }
             for (const controller of allControllers){
                 // Register the controller in its owning module's bucket so its
                 // dependencies resolve from the module's POV (vs `__root__`'s).
                 this.container.register(controller, moduleId);
                 this.collectedControllers.add(controller);
+                if (isLazy) lazyTokens.push(controller);
+            }
+            if (isLazy) {
+                this.lazyModuleIds.add(moduleId);
+                this.lazyGroups.set(moduleId, {
+                    moduleId,
+                    tokens: lazyTokens,
+                    hasEntrypointContributor
+                });
             }
             // Propagate module-level Use* decorators (@UseGuards, @UseInterceptors, etc.) to each controller
             for (const controller of allControllers){
@@ -293,35 +342,36 @@ export class ModuleLoader {
             console.warn(message);
         }
     }
-    registerProvider(provider, moduleId) {
+    /** Registers the provider and returns the token it was registered under. */ registerProvider(provider, moduleId) {
         if (typeof provider === "function") {
             // Per-module bucket: the same class can be registered in multiple
             // modules' buckets simultaneously without collision.
             this.container.register(provider, moduleId);
             this.registeredProviders.push(provider);
-        } else {
-            const token = provider.provide;
-            if (!token) {
-                this.container.register(provider, moduleId);
-                return;
-            }
-            if (this.isAppToken(token)) {
-                // Multiple APP_* providers within the same module bucket need
-                // distinct tokens so they don't overwrite each other in the bucket
-                // Map. Across buckets, `container.resolveAll(APP_GUARD)` walks
-                // every bucket — no need to mark synthetic tokens global.
-                const syntheticToken = new InjectionToken(`${token.toString()}:${this.appProviderCounter++}`);
-                this.container.register({
-                    ...provider,
-                    provide: syntheticToken
-                }, moduleId);
-                this.registeredProviders.push(syntheticToken);
-                getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
-                return;
-            }
+            return provider;
+        }
+        const token = provider.provide;
+        if (!token) {
             this.container.register(provider, moduleId);
-            this.registeredProviders.push(token);
+            return undefined;
         }
+        if (this.isAppToken(token)) {
+            // Multiple APP_* providers within the same module bucket need
+            // distinct tokens so they don't overwrite each other in the bucket
+            // Map. Across buckets, `container.resolveAll(APP_GUARD)` walks
+            // every bucket — no need to mark synthetic tokens global.
+            const syntheticToken = new InjectionToken(`${token.toString()}:${this.appProviderCounter++}`);
+            this.container.register({
+                ...provider,
+                provide: syntheticToken
+            }, moduleId);
+            this.registeredProviders.push(syntheticToken);
+            getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
+            return syntheticToken;
+        }
+        this.container.register(provider, moduleId);
+        this.registeredProviders.push(token);
+        return token;
     }
     isAppToken(token) {
         return APP_TOKENS.has(token);
@@ -364,6 +414,25 @@ export class ModuleLoader {
             ...this.consumerMiddlewareDefinitions
         ];
     }
+    /**
+   * Every lazy module instance recorded during load. Handed to the
+   * LazyModuleManager at bootstrap; empty when no module opted in.
+   */ getLazyGroups() {
+        return [
+            ...this.lazyGroups.values()
+        ];
+    }
+    /**
+   * A token is deferred iff EVERY module bucket holding it belongs to a lazy
+   * module instance — a token also registered by a non-lazy module stays on
+   * the eager pass (and resolving it there claims the lazy sibling, which is
+   * the "any use = init" semantic, not a bug).
+   */ isLazyOnlyToken(token) {
+        if (this.lazyModuleIds.size === 0) return false;
+        const owners = this.container.getOwnerModuleIds(token);
+        if (owners.length === 0) return false;
+        return owners.every((id)=>this.lazyModuleIds.has(id));
+    }
     async resolveAllInstances() {
         const instanceSet = new Set();
         for (const token of this.registeredProviders){
@@ -371,6 +440,9 @@ export class ModuleLoader {
                 if (this.container.getProviderScope(token) === Scope.REQUEST) {
                     continue;
                 }
+                if (this.isLazyOnlyToken(token)) {
+                    continue;
+                }
                 const instance = await this.container.resolveAsync(token);
                 instanceSet.add(instance);
             } catch (err) {
@@ -385,6 +457,9 @@ export class ModuleLoader {
                 if (this.container.getProviderScope(controller) === Scope.REQUEST) {
                     continue;
                 }
+                if (this.isLazyOnlyToken(controller)) {
+                    continue;
+                }
                 const instance = await this.container.resolveAsync(controller);
                 instanceSet.add(instance);
             } catch (err) {

package/dist/pipeline/index.d.ts

@@ -1,6 +1,8 @@
 export { ComponentManager } from './component.manager';
 export { PipelineRunner } from './pipeline-runner';
 export type { PipelineRunOptions } from './pipeline-runner';
+export { resolveScopedComponents } from './scoped-components';
+export type { ResolvedComponentMap } from './scoped-components';
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch, } from './decorators';
 export { SetMetadata, Reflector } from './reflector';
 export type { ReflectableDecorator, CreateDecoratorOptions } from './reflector';

package/dist/pipeline/index.js

@@ -1,5 +1,6 @@
 export { ComponentManager } from "./component.manager.js";
 export { PipelineRunner } from "./pipeline-runner.js";
+export { resolveScopedComponents } from "./scoped-components.js";
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch } from "./decorators.js";
 export { SetMetadata, Reflector } from "./reflector.js";
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./tokens.js";