@velajs/vela 1.10.0 → 1.13.0

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

@@ -0,0 +1,65 @@
+import { InjectionToken, type InferTokens, type ProviderOptions, type Token, type Type } from '../container/types';
+import type { ComponentType, DynamicModule } from '../registry/types';
+import type { ModuleContributions } from './define-module';
+export interface LazyProviderSpec<T, Inject extends readonly Token<unknown>[]> {
+    /** Token under which the memoized thunk `() => T` is provided. */
+    provide: Token<() => T>;
+    inject?: Inject;
+    useFactory: (...deps: InferTokens<Inject>) => T;
+    /** Memoize the first call's result (default true). */
+    memoize?: boolean;
+}
+/**
+ * Provide a zero-arg thunk `() => T` whose factory runs on FIRST CALL, not at
+ * provider construction — for values that don't exist yet when the module
+ * graph is built (Cloudflare bindings are only live at request time).
+ *
+ * The shared primitive replacing the hand-rolled
+ * `useFactory: (...deps) => () => build(...deps)` closure that auth and
+ * storage each copy-pasted.
+ *
+ * ```ts
+ * lazyProvider({
+ *   provide: STORAGE_DRIVER_BUILDER,
+ *   inject: [MODULE_OPTIONS_TOKEN],
+ *   useFactory: (options) => options.driver(),
+ * })
+ * ```
+ */
+export declare function lazyProvider<T, const Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]>(spec: LazyProviderSpec<T, Inject>): ProviderOptions;
+/**
+ * The one idiom for registering an app-wide component from a module's
+ * providers. Returns registrations to spread:
+ *
+ * ```ts
+ * providers: [MyService, ...provideGlobal('guard', AuthGuard)]
+ * ```
+ *
+ * Class components are registered as providers and wired via `useExisting`
+ * (so DI constructs them with their dependencies); instances via `useValue`.
+ * Inside `defineModule`, prefer the equivalent `global:` contribution slot.
+ */
+export declare function provideGlobal(kind: ComponentType, component: Type | object): Array<Type | ProviderOptions>;
+/**
+ * A first-class side-effect-only module: contributes providers/exports without
+ * being a configurable module — the supported form of the "empty marker
+ * module" trick (i18n's `registerMessages`). Content-derived `key` makes
+ * identical contributions dedup (HMR-idempotent) while distinct ones coexist.
+ *
+ * ```ts
+ * export function registerMessages(messages: Messages): DynamicModule {
+ *   return sideEffectModule('I18nMessages', {
+ *     providers: [{ provide: I18N_MESSAGES, useValue: messages }],
+ *     exports: [I18N_MESSAGES],
+ *   });
+ * }
+ * ```
+ */
+export declare function sideEffectModule(name: string, contributions?: Omit<ModuleContributions, 'global'> & {
+    key?: string;
+}): DynamicModule;
+/**
+ * Blessed token-minting convention: always an `InjectionToken` (never a raw
+ * string), named for diagnostics. Namespace it `'<pkg>:<area>:<thing>'`.
+ */
+export declare function moduleToken<T>(name: string): InjectionToken<T>;

package/dist/module/lazy-provider.js

@@ -0,0 +1,111 @@
+import { InjectionToken } from "../container/types.js";
+import { Module } from "./decorators.js";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
+import { stableHash } from "./stable-hash.js";
+/**
+ * Provide a zero-arg thunk `() => T` whose factory runs on FIRST CALL, not at
+ * provider construction — for values that don't exist yet when the module
+ * graph is built (Cloudflare bindings are only live at request time).
+ *
+ * The shared primitive replacing the hand-rolled
+ * `useFactory: (...deps) => () => build(...deps)` closure that auth and
+ * storage each copy-pasted.
+ *
+ * ```ts
+ * lazyProvider({
+ *   provide: STORAGE_DRIVER_BUILDER,
+ *   inject: [MODULE_OPTIONS_TOKEN],
+ *   useFactory: (options) => options.driver(),
+ * })
+ * ```
+ */ export function lazyProvider(spec) {
+    const memoize = spec.memoize ?? true;
+    return {
+        provide: spec.provide,
+        inject: [
+            ...spec.inject ?? []
+        ],
+        useFactory: (...deps)=>{
+            const build = ()=>spec.useFactory(...deps);
+            if (!memoize) return build;
+            let cached;
+            return ()=>(cached ??= {
+                    value: build()
+                }).value;
+        }
+    };
+}
+const GLOBAL_COMPONENT_TOKENS = {
+    guard: APP_GUARD,
+    pipe: APP_PIPE,
+    interceptor: APP_INTERCEPTOR,
+    filter: APP_FILTER,
+    middleware: APP_MIDDLEWARE
+};
+/**
+ * The one idiom for registering an app-wide component from a module's
+ * providers. Returns registrations to spread:
+ *
+ * ```ts
+ * providers: [MyService, ...provideGlobal('guard', AuthGuard)]
+ * ```
+ *
+ * Class components are registered as providers and wired via `useExisting`
+ * (so DI constructs them with their dependencies); instances via `useValue`.
+ * Inside `defineModule`, prefer the equivalent `global:` contribution slot.
+ */ export function provideGlobal(kind, component) {
+    const token = GLOBAL_COMPONENT_TOKENS[kind];
+    if (typeof component === 'function') {
+        return [
+            component,
+            {
+                provide: token,
+                useExisting: component
+            }
+        ];
+    }
+    return [
+        {
+            provide: token,
+            useValue: component
+        }
+    ];
+}
+/**
+ * A first-class side-effect-only module: contributes providers/exports without
+ * being a configurable module — the supported form of the "empty marker
+ * module" trick (i18n's `registerMessages`). Content-derived `key` makes
+ * identical contributions dedup (HMR-idempotent) while distinct ones coexist.
+ *
+ * ```ts
+ * export function registerMessages(messages: Messages): DynamicModule {
+ *   return sideEffectModule('I18nMessages', {
+ *     providers: [{ provide: I18N_MESSAGES, useValue: messages }],
+ *     exports: [I18N_MESSAGES],
+ *   });
+ * }
+ * ```
+ */ export function sideEffectModule(name, contributions = {}) {
+    const { key, ...rest } = contributions;
+    // Computed-property-name idiom: mints a class whose .name is `name` without
+    // dynamic code evaluation (edge-safe; no `new Function`).
+    const moduleClass = {
+        [name]: class {
+        }
+    }[name];
+    Module({})(moduleClass);
+    return {
+        module: moduleClass,
+        key: key ?? stableHash(rest),
+        providers: rest.providers ?? [],
+        controllers: rest.controllers ?? [],
+        imports: rest.imports ?? [],
+        exports: rest.exports ?? []
+    };
+}
+/**
+ * Blessed token-minting convention: always an `InjectionToken` (never a raw
+ * string), named for diagnostics. Namespace it `'<pkg>:<area>:<thing>'`.
+ */ export function moduleToken(name) {
+    return new InjectionToken(name);
+}

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) {