@nexus-ioc/core 0.6.1 → 0.7.0

package/dist/esm/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/esm/utils/forward-ref.js

@@ -0,0 +1,10 @@
+export function forwardRef(fn) {
+    return { forwardRef: fn };
+}
+export function isForwardRef(token) {
+    return (typeof token === "object" &&
+        token !== null &&
+        "forwardRef" in token &&
+        typeof token.forwardRef === "function");
+}
+//# sourceMappingURL=forward-ref.js.map

package/dist/esm/utils/forward-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-ref.js","sourceRoot":"","sources":["../../../src/utils/forward-ref.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,UAAU,CAAc,EAAW;IAClD,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IAC1C,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,YAAY,IAAI,KAAK;QACrB,OAAQ,KAAoB,CAAC,UAAU,KAAK,UAAU,CACtD,CAAC;AACH,CAAC"}

package/dist/esm/utils/helpers.js

@@ -1,4 +1,5 @@
 import "reflect-metadata";
+import { InvalidScopeError } from "../errors/provider-errors.js";
 import { INJECTABLE_OPTIONS, INJECTABLE_WATERMARK, MODULE_GLOBAL_WATERMARK, Scope, } from "../interfaces/index.js";
 export function isFunctionProvider(target) {
     return typeof target === "function";
@@ -47,17 +48,26 @@ export function getModuleLabel(module) {
     return module.name;
 }
 export function getProviderScope(target) {
+    const scope = declaredScope(target) ?? Scope.Singleton;
+    if (scope !== Scope.Singleton && scope !== Scope.Transient) {
+        throw new InvalidScopeError(getProviderToken(target), scope);
+    }
+    return scope;
+}
+/** The scope a provider declares, or undefined when it declares none. */
+function declaredScope(target) {
     if (isFactoryProvider(target)) {
-        return target.scope || Scope.Singleton;
+        return target.scope;
     }
     if (isClassProvider(target)) {
+        // A Singleton (0) on the class falls through to the provider object,
+        // so `{ useClass, scope: Scope.Transient }` overrides it.
         return (Reflect.getMetadata(INJECTABLE_OPTIONS, target.useClass)?.scope ||
-            target.scope ||
-            Scope.Singleton);
+            target.scope);
     }
     if (isValueProvider(target)) {
         return Scope.Singleton;
     }
-    return (Reflect.getMetadata(INJECTABLE_OPTIONS, target)?.scope || Scope.Singleton);
+    return Reflect.getMetadata(INJECTABLE_OPTIONS, target)?.scope;
 }
 //# sourceMappingURL=helpers.js.map

package/dist/esm/utils/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAIN,kBAAkB,EAClB,oBAAoB,EAEpB,uBAAuB,EAGvB,KAAK,GAGL,MAAM,eAAe,CAAC;AAEvB,MAAM,UAAU,kBAAkB,CAAC,MAAgB;IAClD,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAA+B;IACvD,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAsB;IACrD,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC/C,OAAO,CAAC,CAAE,MAAwB,CAAC,QAAQ,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC/C,2EAA2E;IAC3E,OAAO,UAAU,IAAK,MAAiB,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAgB;IACjD,OAAO,CAAC,CAAE,MAA0B,CAAC,UAAU,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAgB;IAChD,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC;IACf,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,QAAkB;IAC5C,OAAO,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,QAAQ,CAAC,IAAI,KAAK,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAgB;IAClD,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC;IACf,CAAC;IAED,OAAO,MAAmC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,eAAe,CAC9B,MAA8B;IAE9B,OAAO,QAAQ,IAAI,MAAM,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC5C,OAAO,OAAO,CAAC,WAAW,CAAC,uBAAuB,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAA8B;IAC5D,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAgB;IAChD,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS,CAAC;IACxC,CAAC;IAED,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,CACN,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK;YAC/D,MAAM,CAAC,KAAK;YACZ,KAAK,CAAC,SAAS,CACf,CAAC;IACH,CAAC;IAED,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,OAAO,CACN,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,EAAE,KAAK,IAAI,KAAK,CAAC,SAAS,CACzE,CAAC;AACH,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/lazy-module.js

@@ -0,0 +1,29 @@
+/**
+ * Declares a lazily loaded module import.
+ *
+ * @example
+ * ```typescript
+ * export const FeatureLazy = lazy(() =>
+ *   import("./feature/feature.module").then((m) => m.FeatureModule),
+ * );
+ *
+ * @Module({ imports: [CoreModule, FeatureLazy] })
+ * class AppModule {}
+ * ```
+ */
+export function lazy(loader, options = {}) {
+    const name = options.name ?? "LazyModule";
+    return Object.freeze({
+        id: Symbol(name),
+        name,
+        load: loader,
+    });
+}
+export function isLazyModule(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.id === "symbol" &&
+        typeof value.load === "function" &&
+        typeof value.name === "string");
+}
+//# sourceMappingURL=lazy-module.js.map

package/dist/esm/utils/lazy-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-module.js","sourceRoot":"","sources":["../../../src/utils/lazy-module.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,IAAI,CACnB,MAAwC,EACxC,UAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC;IAC1C,OAAO,MAAM,CAAC,MAAM,CAAC;QACpB,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC;QAChB,IAAI;QACJ,IAAI,EAAE,MAAM;KACZ,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IAC1C,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAoB,CAAC,EAAE,KAAK,QAAQ;QAC5C,OAAQ,KAAoB,CAAC,IAAI,KAAK,UAAU;QAChD,OAAQ,KAAoB,CAAC,IAAI,KAAK,QAAQ,CAC9C,CAAC;AACH,CAAC"}

package/dist/types/browser.d.ts

@@ -1 +1 @@
-export { NexusApplicationsBrowser } from "./core/nexus-applications.browser";
+export { NexusApplicationBrowser } from "./core/nexus-applications.browser";

package/dist/types/core/child-module.d.ts

@@ -0,0 +1,8 @@
+import "reflect-metadata";
+import { type DynamicModule, type Provider, type Type } from "../interfaces";
+/**
+ * Returns `module` with `providers` appended to its root providers, as a
+ * `DynamicModule`. A `Type` keeps its decorator imports and exports. Returns
+ * `module` itself when there is nothing to add.
+ */
+export declare function withExtraProviders(module: Type | DynamicModule, providers: Provider[] | undefined): Type | DynamicModule;

package/dist/types/core/graph/analyze-lazy-module.d.ts

@@ -0,0 +1,28 @@
+import { type LazyModule, NodeTypeEnum } from "../../interfaces";
+/**
+ * Placeholder graph node for a `lazy()` import. It carries no providers.
+ * `isProviderExported` never looks through it, so eager providers cannot
+ * depend on anything the lazy module will provide.
+ */
+export declare class AnalyzeLazyModule {
+    private readonly _lazyModule;
+    private _loaded;
+    private _moduleToken;
+    constructor(_lazyModule: LazyModule);
+    get type(): NodeTypeEnum.LAZY;
+    get id(): symbol;
+    get label(): string;
+    get lazyModule(): LazyModule;
+    get loaded(): boolean;
+    /** Token of the real module node once loaded; null before. */
+    get moduleToken(): string | null;
+    markLoaded(moduleToken: string): void;
+    markUnloaded(): void;
+    get node(): {
+        type: NodeTypeEnum.LAZY;
+        id: symbol;
+        label: string;
+        loaded: boolean;
+        moduleToken: string | null;
+    };
+}

package/dist/types/core/graph/analyze-module.d.ts

@@ -1,4 +1,4 @@
-import { EdgeTypeEnum, type ModuleContainerInterface, NodeTypeEnum } from "../../interfaces";
+import { type Edge, EdgeTypeEnum, type ModuleContainerInterface, NodeTypeEnum } from "../../interfaces";
 export declare class AnalyzeModule {
     private readonly _module;
     private readonly _isDynamic;
@@ -29,8 +29,10 @@ export declare class AnalyzeModule {
             isCircular: boolean;
         };
     }[]>;
+    get lazyImports(): import("@nexus-ioc/shared").LazyModule<import("@nexus-ioc/shared").Module>[];
+    get lazyEdges(): Edge[];
     get providers(): import("@nexus-ioc/shared").Provider[];
     get isGlobal(): boolean;
     get imports(): Promise<ModuleContainerInterface[]>;
-    get exports(): (import("@nexus-ioc/shared").Module | import("@nexus-ioc/shared").InjectionToken)[];
+    get exports(): (import("@nexus-ioc/shared").ProviderToken | import("@nexus-ioc/shared").Module)[];
 }

package/dist/types/core/graph/analyze-provider.d.ts

@@ -7,18 +7,18 @@ export declare abstract class AnalyzeProvider {
     private readonly _scope;
     constructor(provider: Provider, module: ModuleContainerInterface);
     get type(): NodeTypeEnum.PROVIDER;
-    get id(): import("../..").InjectionToken;
+    get id(): import("@nexus-ioc/shared").ProviderToken;
     get label(): string;
     get metatype(): Provider;
     get moduleContainer(): ModuleContainerInterface;
-    get scope(): import("../..").Scope;
+    get scope(): import("@nexus-ioc/shared").Scope;
     get node(): {
         type: NodeTypeEnum.PROVIDER;
-        id: import("../..").InjectionToken;
+        id: import("@nexus-ioc/shared").ProviderToken;
         label: string;
         metatype: Provider;
         moduleContainer: ModuleContainerInterface;
-        scope: import("../..").Scope;
+        scope: import("@nexus-ioc/shared").Scope;
     };
     get edge(): Edge;
 }

package/dist/types/core/graph/module-graph.d.ts

@@ -1,30 +1,223 @@
-import { type Edge, type GraphError, type InjectionToken, type ModuleContainerInterface, type ModuleGraphInterface, type Node } from "../../interfaces";
+import { type Edge, type GraphError, type GraphSegment, type LazyModule, type ModuleContainerInterface, type ModuleGraphInterface, type ModuleGraphOptions, type Node, type ProviderToken, type SegmentUnloadResult, type Type } from "../../interfaces";
 export declare class ModuleGraph implements ModuleGraphInterface {
     private readonly _root;
+    private readonly _internalRoots;
+    private readonly options;
     private _nodes;
     private _edges;
     private _globalModules;
+    /** Module token -> its own declared provider tokens. */
+    private readonly _moduleProviders;
+    /**
+     * Module token -> the other module tokens that need it alive: every
+     * module that imports it, plus every module owning a provider that
+     * depends (via a resolved `DEPENDENCY` edge, including one resolved
+     * through a `@Global()` module) on one of its providers.
+     */
+    private readonly _moduleReferrers;
+    /**
+     * Late-bound edge index: target token -> source provider token -> whether
+     * the edge is bound. A `lateBound` edge is an `@Optional()` static edge
+     * whose target was not visible from the source's module when it was
+     * compiled (it may not have existed yet). The resolver injects its target
+     * only while the target exists and is visible. "Bound" means that held
+     * when a segment added the target (or a global module exposing it), so
+     * the source's module was recorded as a referrer of the target's module;
+     * only a bound edge counts in `moduleDependencies`, which keeps the
+     * referrer purge symmetric with the recording.
+     */
+    private readonly _lateBound;
+    /**
+     * Child declaration index: the child's module class (or the `LazyModule.id`
+     * symbol of a lazy ref) -> the token of the one module declaring it.
+     */
+    private readonly _childDeclarations;
     private readonly _errors;
-    constructor(_root: ModuleContainerInterface);
-    get nodes(): Map<InjectionToken, Node>;
-    get edges(): Map<InjectionToken, Edge[]>;
+    /**
+     * While a segment compiles, its errors are collected here instead of in
+     * `_errors`, so they are never mixed with (or mistaken for) errors of the
+     * eager graph or of another segment.
+     */
+    private _errorSink;
+    /** See `version`. */
+    private _version;
+    constructor(_root: ModuleContainerInterface, _internalRoots?: ModuleContainerInterface[], options?: ModuleGraphOptions);
+    get nodes(): Map<ProviderToken, Node>;
+    get edges(): Map<ProviderToken, Edge[]>;
     get errors(): GraphError[];
+    get rootToken(): string;
+    get internalRootTokens(): string[];
+    /**
+     * Bumped whenever `compile`, `compileSegment` or `unloadSegment` may have
+     * changed which providers exist or which modules see them. A cache of
+     * `isProviderVisible` results is valid while this number is unchanged.
+     */
+    get version(): number;
+    /** Records a graph error in the active sink, or in the shared list. */
+    private pushError;
+    /**
+     * Compiles the eager graph. Internal roots are added before the user root so
+     * `_globalModules` already contains the internal modules when user providers
+     * are checked by `isProviderExported`.
+     */
     compile(): Promise<void>;
-    getNode(token: InjectionToken): Node | undefined;
-    getEdge(token: InjectionToken): Edge[];
+    /**
+     * Compiles the part of the graph reachable from `root` that is not already
+     * registered, attributing it to the `lazyModule` placeholder node.
+     *
+     * The pass is atomic: if it produces any error the segment is rolled back
+     * (every node, edge, global registration and LAZY placeholder it created is
+     * removed) and the placeholder stays unloaded. On success the placeholder is
+     * marked loaded. A placeholder that already existed before the segment
+     * started is never removed.
+     *
+     * The segment's errors are collected in a segment-local sink and never
+     * reach `this.errors`, so they cannot be attributed to the eager graph or
+     * to another segment. The caller (`Container.load`) runs one segment at a
+     * time, which is what makes the sink and the graph mutations safe under
+     * concurrent loads of different refs.
+     */
+    compileSegment(root: ModuleContainerInterface, lazyModule: LazyModule): Promise<GraphSegment>;
+    /**
+     * Binds the late-bound edges (see `_lateBound`) whose target this
+     * segment made visible to the edge's source, recording the referrer the
+     * resolver's injection now implies. The same visibility check as the
+     * resolver's, so bookkeeping and injection always agree.
+     *
+     * Only two things can make a late-bound target visible to an existing
+     * source: the target's node being added (looked up per added provider)
+     * or a new `@Global()` module exposing it (compiled modules' imports
+     * never change). Only a segment adding a global module rechecks every
+     * indexed target; the index holds only late-bound edges, so it is small.
+     *
+     * Once bound, an edge keeps the target's module pinned for the consumer
+     * module's lifetime, even after the global module that exposed it
+     * unloads. This is deliberately safe: instances created meanwhile may
+     * still hold the target.
+     */
+    private bindLateEdges;
+    /**
+     * Drops removed sources from the late-bound index and unbinds edges
+     * whose target was removed (a later load of the target binds them
+     * again). Runs after `purgeModuleIndexes`, which reads the bound state.
+     */
+    private purgeLateBound;
+    /**
+     * Rolls back a segment that failed validation: removes every node, edge
+     * and global registration it created (module, provider and LAZY
+     * placeholder tokens are all passed in together). Also purges
+     * `_moduleProviders`/`_moduleReferrers` index entries for `tokens` via
+     * `purgeModuleIndexes` — without this, a referrer entry recorded by
+     * `addModuleImports` before the rollback (pointing at a module token
+     * that no longer exists) would survive and could later be mistaken by
+     * `rescueCandidates` for a live outside referrer of a module reused by a
+     * different, successful segment.
+     */
+    private removeTokens;
+    /**
+     * Unloads a loaded lazy segment. Scoped to the segment's own subgraph,
+     * not the whole live graph: collects everything reachable from the
+     * segment's root (pruned at any module in `protectedRoots` — the eager
+     * root, internal roots, and every *other* currently loaded segment's
+     * root), then rescues back anything a survivor still needs. Returns the
+     * modules and providers that were actually destroyed; a no-op (empty
+     * result) if the ref is not currently loaded.
+     */
+    unloadSegment(lazyModule: LazyModule, protectedRoots: Set<string>): SegmentUnloadResult;
+    /** A module's own `IMPORT` targets, plus the declaring modules of
+     * whatever its own providers depend on in another module. Shared by
+     * candidate collection, rescue propagation and teardown cleanup. */
+    private moduleDependencies;
+    private collectCandidates;
+    /**
+     * A candidate survives if something outside the candidate set still
+     * needs it (a "seed"), or if it is only reachable through a candidate
+     * that survives. A plain per-node check for the first case alone is not
+     * enough — see the "rescues a module only reachable through a surviving
+     * sibling candidate" test.
+     */
+    private rescueCandidates;
+    private removeModuleTokens;
+    /**
+     * Purges `_moduleProviders`/`_moduleReferrers` index entries for
+     * `tokens`, and removes each of them from any surviving module's
+     * referrer set. Shared by `removeModuleTokens` (destroying a live
+     * segment) and `removeTokens` (rolling back a failed one).
+     *
+     * `tokens` may freely mix module tokens with provider or LAZY
+     * placeholder tokens: both indexes are keyed by module tokens only, so a
+     * lookup or delete with a non-module key is a harmless no-op.
+     *
+     * Must run before the tokens' own `_edges` entries (and, for a removed
+     * module, its `_moduleProviders` entry) are deleted — `moduleDependencies`
+     * reads both to determine what each token itself depended on.
+     */
+    private purgeModuleIndexes;
+    addRuntimeDependency(source: ProviderToken, target: ProviderToken): void;
+    findChildDeclaration(child: Type | LazyModule): ModuleContainerInterface | undefined;
+    getNode(token: ProviderToken): Node | undefined;
+    getEdge(token: ProviderToken): Edge[];
     getAllEdges(): Edge[][];
     getAllNodes(): Node[];
     private addModules;
     private addModule;
+    /**
+     * Records the module's declared children. Children are never compiled into
+     * this graph; only the declaration is indexed. A child declared by a second
+     * module is a graph error and keeps its first declarer.
+     */
+    private indexChildren;
+    private moduleLabel;
+    /**
+     * @returns the ids of the LAZY placeholder nodes this call created, so a
+     * rolled back segment can remove them again. Placeholders that already
+     * existed are not reported and must never be removed.
+     */
     private addModuleImports;
     private addModuleProviders;
     private addEdge;
     private addNode;
+    private addModuleProvider;
+    private addModuleReferrer;
+    /**
+     * Bookkeeping for a static `DEPENDENCY` edge just added: a late-bound
+     * edge is indexed (its referrer is recorded by `bindLateEdges` once the
+     * target is visible), any other edge records its referrer now.
+     */
+    private recordStaticDependency;
+    /**
+     * Records that `consumerToken` (a provider) keeps `dependencyToken`'s
+     * declaring module alive, when the two providers are declared in
+     * different modules. Called after every `DEPENDENCY` edge is added,
+     * regardless of how the dependency was resolved (own module, import, or
+     * `@Global()` fallback) — the edge already reflects that, so this needs
+     * no help from `isProviderExported`.
+     *
+     * @param countsAsReferrer - False for an edge that keeps nothing in this
+     *   graph alive: an unreached dependency, or an external one (resolved
+     *   through the parent link, so its target lives in another container).
+     */
+    private recordCrossModuleReferrer;
     private addDependencies;
     private addClassDependency;
     private addClassProviderDependency;
     private addFactoryProviderDependency;
-    private isProviderExported;
+    /**
+     * How a dependency of a provider declared in `moduleContainer` is
+     * satisfied: locally (own module, imports, globals), by the parent
+     * container chain, or not at all. Optional dependencies count as
+     * satisfied; a parent that can provide one is still preferred. An
+     * optional dependency satisfied only by being optional is `lateBound`:
+     * the resolver injects it only once it exists and is visible.
+     */
+    private reachDependency;
+    isProviderExported(moduleContainer: ModuleContainerInterface, dependencyToken: ProviderToken): Promise<boolean>;
+    isProviderVisible(moduleContainer: ModuleContainerInterface, dependencyToken: ProviderToken): boolean;
+    /**
+     * Whether `dependencyToken` is among `exports`, following module-class
+     * re-exports through the modules' own exports.
+     */
+    private exportsReach;
     private detectCircularDependencies;
     private detectCircularImports;
     private getConstructorDependencies;

package/dist/types/core/graph/providers/analyze-class-provider.d.ts

@@ -2,6 +2,6 @@ import type { ClassProvider } from "../../../interfaces";
 import { AnalyzeProvider } from "../analyze-provider";
 export declare class AnalyzeClassProvider extends AnalyzeProvider {
     get metatype(): ClassProvider;
-    get provide(): import("../../..").InjectionToken;
+    get provide(): import("@nexus-ioc/shared").ProviderToken;
     get useClass(): import("../../..").Type<any>;
 }

package/dist/types/core/graph/providers/analyze-factory-provider.d.ts

@@ -2,6 +2,6 @@ import type { FactoryProvider } from "../../../interfaces";
 import { AnalyzeProvider } from "../analyze-provider";
 export declare class AnalyzeFactoryProvider extends AnalyzeProvider {
     get metatype(): FactoryProvider;
-    get provide(): import("../../..").InjectionToken;
-    get inject(): import("../../..").InjectionToken[] | undefined;
+    get provide(): import("@nexus-ioc/shared").ProviderToken;
+    get inject(): (import("../../..").ForwardRef<unknown> | import("@nexus-ioc/shared").ProviderToken)[] | undefined;
 }

package/dist/types/core/graph/providers/analyze-value-provider.d.ts

@@ -2,6 +2,6 @@ import type { ValueProvider } from "../../../interfaces";
 import { AnalyzeProvider } from "../analyze-provider";
 export declare class AnalyzeValueProvider extends AnalyzeProvider {
     get metatype(): ValueProvider;
-    get provide(): import("../../..").InjectionToken;
+    get provide(): import("@nexus-ioc/shared").ProviderToken;
     get useValue(): any;
 }

package/dist/types/core/injection/injection-context.d.ts

@@ -0,0 +1,29 @@
+import type { ProviderToken } from "../../interfaces";
+export interface InjectOptions {
+    /** Return undefined instead of throwing when the token is not available. */
+    optional?: boolean;
+}
+export interface InjectionContext {
+    inject(token: ProviderToken, options: InjectOptions): unknown;
+}
+/**
+ * Runs `fn` with `ctx` as the current injection context (`null` = none)
+ * and restores the previous one afterwards, even if `fn` throws.
+ *
+ * @internal Not exported from the package entry point.
+ */
+export declare function withInjectionContext<R>(ctx: InjectionContext | null, fn: () => R): R;
+/**
+ * Returns the provider for `token` from the container that is currently
+ * creating an instance. Callable only synchronously during creation: in
+ * field initializers, constructor bodies and factory functions.
+ *
+ * @throws {InjectionContextError} When called outside of an injection context
+ * @throws {ProviderNotFoundError} When the token is not visible to the requester and `optional` is not set
+ * @throws {CircularInjectionError} When the token is already being created in this resolution
+ */
+export declare function inject<T>(token: ProviderToken<T>): T;
+export declare function inject<T>(token: ProviderToken<T>, options: {
+    optional: true;
+}): T | undefined;
+export declare function inject<T>(token: ProviderToken<T>, options: InjectOptions): T | undefined;

package/dist/types/core/lazy-module-loader.d.ts

@@ -0,0 +1,17 @@
+import "reflect-metadata";
+import type { DynamicModule, LazyModule, UnloadResult } from "../interfaces";
+import type { ModuleRef } from "./module-ref";
+/**
+ * Built-in provider that lets any service load a lazy module on demand.
+ * Registered automatically by `NexusApplication`; inject it with
+ * `@Inject(LazyModuleLoader)`.
+ */
+export declare class LazyModuleLoader {
+    private readonly loadFn;
+    private readonly unloadFn;
+    constructor(loadFn: (lazyModule: LazyModule) => Promise<ModuleRef>, unloadFn: (ref: ModuleRef) => Promise<UnloadResult>);
+    load(lazyModule: LazyModule): Promise<ModuleRef>;
+    unload(ref: ModuleRef): Promise<UnloadResult>;
+}
+/** Global module carrying the application's built-in providers. */
+export declare function createInternalModule(loader: LazyModuleLoader): DynamicModule;

package/dist/types/core/module-ref.d.ts

@@ -0,0 +1,34 @@
+import type { ContainerInterface, GraphSegment, ProviderToken, Type, UnloadResult } from "../interfaces";
+export interface ModuleRefGetOptions {
+    /**
+     * `true` (default): only tokens the module can see — its own providers and
+     * providers exported to it by its imports or by global modules.
+     * `false`: any token in the container.
+     */
+    strict?: boolean;
+}
+/**
+ * Handle to a lazily loaded module. Providers physically live in the
+ * application's single container; `get()` and `resolve()` only scope what is
+ * visible. `get()` is synchronous and returns already-created singletons;
+ * `resolve()` is async and creates transient/scoped/uncreated providers on demand.
+ */
+export declare class ModuleRef {
+    private readonly container;
+    private readonly segment;
+    private _loaded;
+    constructor(container: ContainerInterface, segment: GraphSegment);
+    get name(): string;
+    get module(): Type;
+    /** `false` once `unload()` has run; a later `load()` of the same ref
+     * returns a new `ModuleRef` instead of reactivating this one. */
+    get loaded(): boolean;
+    get<T>(token: ProviderToken<T>, options?: ModuleRefGetOptions): T | undefined;
+    resolve<T>(token: ProviderToken<T>, options?: ModuleRefGetOptions): Promise<T | undefined>;
+    private canSee;
+    /**
+     * Unloads this segment: destroys every singleton and module nothing else
+     * still needs. A no-op if already unloaded.
+     */
+    unload(): Promise<UnloadResult>;
+}