@nexus-ioc/core 0.6.1 → 0.7.0

package/dist/types/core/modules/container.d.ts

@@ -1,4 +1,14 @@
-import type { ContainerInterface, DynamicModule, HashUtilInterface, InjectionToken, Module, ModuleContainerInterface, ModuleGraphInterface } from "../../interfaces";
+import "reflect-metadata";
+import type { ContainerInterface, DynamicModule, GraphSegment, HashUtilInterface, LazyModule, ModuleContainerInterface, ModuleGraphInterface, ParentLink, ProviderToken, Type, UnloadResult } from "../../interfaces";
+/**
+ * Called by `Container.unload` with the module tokens about to be destroyed.
+ * Reports how many child applications it closed and, if any of them failed
+ * to close, the error to rethrow once the unload has finished.
+ */
+export type UnloadingHook = (destroyedModules: string[]) => Promise<{
+    closed: number;
+    error?: unknown;
+}>;
 /**
  * Container is the core IoC (Inversion of Control) container that manages
  * modules, providers, and dependency injection.
@@ -13,7 +23,7 @@ import type { ContainerInterface, DynamicModule, HashUtilInterface, InjectionTok
  * ```typescript
  * const container = new Container(hashUtils);
  * await container.run(AppModule);
- * const service = await container.get(MyService);
+ * const service = container.get(MyService);
  * ```
  */
 export declare class Container implements ContainerInterface {
@@ -21,6 +31,23 @@ export declare class Container implements ContainerInterface {
     private readonly modulesContainer;
     private _graph;
     private moduleGraphResolver;
+    /** The parent chain of a child container; kept for runtime resolution. */
+    private link;
+    private closed;
+    private readonly segments;
+    /**
+     * Root module token of every currently loaded segment, by ref id. Used
+     * to compute `protectedRoots` for `unload`; set once a segment's
+     * compile succeeds, cleared once it is unloaded.
+     */
+    private readonly loadedSegments;
+    /**
+     * Tail of the segment compilation chain. Loader functions run in parallel,
+     * but the graph mutation that follows each of them runs one at a time.
+     */
+    private compileQueue;
+    /** See `onUnloading`. */
+    private unloadingHook;
     /**
      * Creates a new Container instance.
      *
@@ -43,7 +70,7 @@ export declare class Container implements ContainerInterface {
      * await container.addModule(DatabaseModule.forRoot({ host: 'localhost' }));
      * ```
      */
-    addModule(module: Module | DynamicModule): Promise<ModuleContainerInterface>;
+    addModule(module: Type | DynamicModule): Promise<ModuleContainerInterface>;
     /**
      * Replaces an existing module with a new module.
      *
@@ -59,7 +86,7 @@ export declare class Container implements ContainerInterface {
      * await container.replaceModule(OldDatabaseModule, NewDatabaseModule);
      * ```
      */
-    replaceModule(moduleToReplace: Module, newModule: Module): Promise<ModuleContainerInterface>;
+    replaceModule(moduleToReplace: Type, newModule: Type): Promise<ModuleContainerInterface>;
     /**
      * Retrieves a module container by its module class.
      *
@@ -71,27 +98,46 @@ export declare class Container implements ContainerInterface {
      * const moduleContainer = await container.getModule(DatabaseModule);
      * ```
      */
-    getModule(module: Module): Promise<ModuleContainerInterface | undefined>;
+    getModule(module: Type): Promise<ModuleContainerInterface | undefined>;
+    /**
+     * True iff the graph has a provider node for the token.
+     */
+    hasProvider(token: ProviderToken): boolean;
     /**
-     * Resolves and returns an instance of a provider by its injection token.
+     * Synchronously returns an already-created singleton.
      *
-     * This is the main method for retrieving dependencies from the container.
-     * The instance is created according to its scope:
-     * - Singleton: Same instance returned every time
-     * - Request: New instance for each get() call
-     * - Transient: New instance every time, even within the same dependency tree
+     * @throws {ProviderNotFoundError} If no provider has this token
+     * @throws {ProviderScopeError} If the provider is Transient
+     * @throws {ProviderNotInstantiatedError} If the singleton is not created yet
      *
-     * @template T - The type of the provider to resolve
-     * @param token - The injection token (class, string, or symbol)
-     * @returns A promise that resolves to the provider instance, or undefined if not found
+     * @example
+     * ```typescript
+     * await container.run(AppModule);
+     * const userService = container.get(UserService);
+     * ```
+     */
+    get<T>(token: ProviderToken<T>): T;
+    /**
+     * Resolves an instance of a provider, creating it according to its scope.
+     *
+     * @throws {ProviderNotFoundError} If no provider has this token
      *
      * @example
      * ```typescript
-     * const userService = await container.get(UserService);
-     * const config = await container.get('CONFIG');
+     * const userService = await container.resolve(UserService);
      * ```
      */
-    get<T>(token: InjectionToken): Promise<T | undefined>;
+    resolve<T>(token: ProviderToken<T>): Promise<T>;
+    /**
+     * Pre-instantiates every singleton provider named by `tokens` (other
+     * tokens are skipped). Uses the resolver directly, without the closed
+     * guard, so a load that was already in flight when `close()` started can
+     * still finish its warm-up; those singletons are destroyed by the
+     * teardown that follows.
+     *
+     * @throws {ContainerNotCompiledError} If run() has not been called yet
+     */
+    instantiateSingletons(tokens: Iterable<ProviderToken>): Promise<void>;
     /**
      * Initializes and runs the container with the specified root module.
      *
@@ -104,6 +150,10 @@ export declare class Container implements ContainerInterface {
      * This method must be called before using get() to resolve dependencies.
      *
      * @param rootModule - The root module of the application
+     * @param internalModules - Framework-provided global modules compiled before
+     *   the user root, so their exports are visible to every user module
+     * @param options.link - The parent chain of a child container. Dependencies
+     *   not visible locally but provided by the link compile as external edges.
      * @returns A promise that resolves when initialization is complete
      * @throws {Error} If there are circular dependencies or missing providers
      *
@@ -114,7 +164,52 @@ export declare class Container implements ContainerInterface {
      * // Now you can use container.get() to resolve dependencies
      * ```
      */
-    run(rootModule: Module): Promise<void>;
+    run(rootModule: Type | DynamicModule, internalModules?: DynamicModule[], options?: {
+        link?: ParentLink;
+    }): Promise<void>;
+    /**
+     * Loads a lazy module into this container: runs its loader, registers the
+     * module and compiles only the new part of the graph. Idempotent per ref;
+     * concurrent calls share one in-flight load. A failed load is not cached,
+     * so the caller may retry.
+     *
+     * @param lazyModule - The lazy module reference, created via `lazy()`
+     * @returns A promise that resolves to the graph segment added by this load
+     * @throws {ContainerNotCompiledError} If run() has not been called yet
+     * @throws {LazyModuleLoadError} If the loader rejects or does not return a @Module() class
+     * @throws {LazyModuleGraphError} If the loaded module fails to compile
+     */
+    load(lazyModule: LazyModule): Promise<GraphSegment>;
+    /**
+     * Runs `fn` after every previously enqueued task has settled, so segment
+     * registration and compilation never interleave. A rejected task does not
+     * break the chain for the tasks behind it.
+     */
+    private enqueueCompile;
+    private loadSegment;
+    /**
+     * Unloads a previously loaded lazy segment: destroys every singleton and
+     * module nothing else still needs, and leaves the rest untouched (a
+     * shared module, a `@Global()` module another segment depends on, a
+     * nested lazy module loaded from inside this one). Runs on the same
+     * compile queue as `load`, so it never interleaves with a concurrent
+     * load or unload of a different ref. Waits for an in-flight load of the
+     * same ref to settle first. A ref that was never loaded is a no-op.
+     * Concurrent `unload()` calls for the *same* ref are also safe, but only
+     * because `ModuleGraph.unloadSegment` is idempotent (a second call
+     * against an already-unloaded placeholder is a no-op) — `Container.unload`
+     * itself does not enforce this, so a future change to `unloadSegment`
+     * must preserve that idempotency or this guarantee silently breaks.
+     */
+    unload(lazyModule: LazyModule): Promise<UnloadResult>;
+    /**
+     * Registers the hook `unload` calls once the graph has dropped a segment
+     * and before that segment's providers are destroyed, with the tokens of
+     * the modules being destroyed. The application closes the child
+     * applications those modules declared there. One hook per container; a
+     * later call replaces it.
+     */
+    onUnloading(hook: UnloadingHook): void;
     /**
      * Gets the dependency graph.
      *
@@ -151,4 +246,25 @@ export declare class Container implements ContainerInterface {
      * ```
      */
     get errors(): import("@nexus-ioc/shared").GraphError[];
+    /** Whether run() has built the graph, so get()/resolve() can be used. */
+    get isCompiled(): boolean;
+    /** Whether the container has been closed (or is closing). */
+    get isClosed(): boolean;
+    private assertOpen;
+    /**
+     * Synchronously marks the container closed: every later public
+     * `get`/`resolve`/`load`/`unload` call throws `ContainerClosedError`.
+     * Work already in flight (a load past its guard, its singleton warm-up)
+     * is not interrupted. `close()` calls this too; callers that need the
+     * flag set before they drain their own work call it first.
+     */
+    markClosed(): void;
+    /**
+     * Closes the container and cleans up resources: marks it closed, waits
+     * for in-flight segment loads, then destroys every created provider on
+     * the compile queue.
+     *
+     * @returns A promise that resolves when the container is closed
+     */
+    close(): Promise<void>;
 }

package/dist/types/core/modules/module-container-factory.d.ts

@@ -1,9 +1,9 @@
 import "reflect-metadata";
-import type { ContainerBaseInterface, DynamicModule, Module, ModuleContainerFactoryInterface, ModuleContainerInterface, ModuleTokenFactoryInterface } from "../../interfaces";
+import type { ContainerBaseInterface, DynamicModule, ModuleContainerFactoryInterface, ModuleContainerInterface, ModuleTokenFactoryInterface, Type } from "../../interfaces";
 export declare class ModuleContainerFactory implements ModuleContainerFactoryInterface {
     private readonly moduleTokenFactory;
     constructor(moduleTokenFactory: ModuleTokenFactoryInterface);
-    create(module: Module | DynamicModule, container: ContainerBaseInterface): Promise<ModuleContainerInterface>;
-    getModuleToken(module: Module | DynamicModule): Promise<string>;
+    create(module: Type | DynamicModule, container: ContainerBaseInterface, resolveReplacement?: (module: Type) => Type): Promise<ModuleContainerInterface>;
+    getModuleToken(module: Type | DynamicModule): Promise<string>;
     getModuleContainerImports(module: ModuleContainerInterface): Promise<ModuleContainerInterface[]>;
 }

package/dist/types/core/modules/module-container.d.ts

@@ -1,16 +1,55 @@
 import "reflect-metadata";
-import type { ContainerBaseInterface, DynamicModule, InjectionToken, Module, ModuleContainerInterface, Provider } from "../../interfaces";
+import type { ContainerBaseInterface, DynamicModule, GetOptions, LazyModule, ModuleContainerInterface, Provider, ProviderToken, Type } from "../../interfaces";
 export declare class ModuleContainer implements ModuleContainerInterface {
     private readonly _metatype;
     private readonly container;
+    private readonly resolveReplacement;
     private _token;
-    constructor(_metatype: Module | DynamicModule, container: ContainerBaseInterface);
+    constructor(_metatype: Type | DynamicModule, container: ContainerBaseInterface, resolveReplacement?: (module: Type) => Type);
     get token(): string;
     set token(value: string);
-    get metatype(): Module | DynamicModule;
+    get metatype(): DynamicModule | Type<any>;
+    private get declaredImports();
+    private _resolvedImports;
+    get resolvedImports(): ModuleContainerInterface[] | undefined;
     get imports(): Promise<ModuleContainerInterface[]>;
+    get lazyImports(): LazyModule[];
+    /**
+     * Children declared by the module class's `@Module` decorator. A dynamic
+     * module literal cannot declare children, but one built from a class that
+     * declares them (`forX()`, extra child providers) keeps them.
+     */
+    get children(): readonly (Type | LazyModule)[];
     get providers(): Provider[];
-    get exports(): InjectionToken[];
-    get<T>(token: InjectionToken): Promise<T | undefined>;
+    get exports(): ProviderToken[];
+    /**
+     * Synchronously returns an already-created singleton, with the same
+     * contract as `Test.get()`.
+     *
+     * @throws {ProviderNotFoundError} If no provider has this token (unless optional)
+     * @throws {ProviderScopeError} If the provider is Transient; use resolve()
+     * @throws {ProviderNotInstantiatedError} If the singleton is not created yet; use resolve()
+     */
+    get<T>(token: ProviderToken<T>): T;
+    get<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): T | undefined;
+    get<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): T;
+    get<T>(token: ProviderToken<T>, options: GetOptions): T | undefined;
+    /**
+     * Resolves a provider asynchronously, creating it according to its scope.
+     *
+     * @throws {ProviderNotFoundError} If no provider has this token (unless optional)
+     */
+    resolve<T>(token: ProviderToken<T>): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): Promise<T | undefined>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: GetOptions): Promise<T | undefined>;
     get errors(): import("@nexus-ioc/shared").GraphError[];
 }

package/dist/types/core/modules/module-token-factory.d.ts

@@ -1,11 +1,11 @@
-import type { DynamicModule, HashUtilInterface, Module, ModuleTokenFactoryInterface } from "../../interfaces";
+import type { DynamicModule, HashUtilInterface, ModuleTokenFactoryInterface, Type } from "../../interfaces";
 export declare class ModuleTokenFactory implements ModuleTokenFactoryInterface {
     private readonly hashUtils;
     private readonly moduleTokenCache;
     private readonly moduleTokens;
     private readonly moduleIdsCache;
     constructor(hashUtils: HashUtilInterface);
-    create(metatype: Module | DynamicModule): Promise<string>;
+    create(metatype: Type | DynamicModule): Promise<string>;
     private getStaticModuleToken;
     private getMetatypeId;
     private getModuleName;

package/dist/types/core/modules/modules-container.d.ts

@@ -1,16 +1,35 @@
 import "reflect-metadata";
-import { type ContainerInterface, type DynamicModule, type HashUtilInterface, type Module, type ModuleContainerInterface, type ModulesContainerInterface } from "../../interfaces";
+import { type ContainerInterface, type DynamicModule, type HashUtilInterface, type ModuleContainerInterface, type ModulesContainerInterface, type Type } from "../../interfaces";
 export type Token = string;
 export declare class ModulesContainer implements ModulesContainerInterface {
     private readonly hashUtils;
     private readonly container;
     private readonly containers;
+    /**
+     * Modules registered through `replaceModule`, keyed by the replaced class.
+     * Every lookup of a replaced module (`addModule`, `getModule`) is redirected
+     * to its replacement, even when the replaced module was not registered yet.
+     * Modules that were not replaced are never affected. This holds for
+     * everything this container adds later too, lazy modules included.
+     */
+    private readonly replacements;
     private readonly moduleTokenFactory;
     private readonly moduleContainerFactory;
     constructor(hashUtils: HashUtilInterface, container: ContainerInterface);
-    addModule(module: Module | DynamicModule): Promise<ModuleContainerInterface>;
-    getModule(module: Module | DynamicModule): ModuleContainerInterface | undefined;
-    replaceModule(moduleToReplace: Module, newModule: Module): Promise<ModuleContainerInterface>;
+    addModule(module: Type | DynamicModule): Promise<ModuleContainerInterface>;
+    getModule(module: Type | DynamicModule): ModuleContainerInterface | undefined;
+    removeModule(token: Token): void;
+    replaceModule(moduleToReplace: Type, newModule: Type): Promise<ModuleContainerInterface>;
+    /**
+     * Maps a module through the replacements. The chain is followed
+     * (`A -> B -> C` gives `C`) and stops at a cycle (`A -> B`, `B -> A`).
+     *
+     * A `DynamicModule` whose `module` class is replaced is swapped for the
+     * replacement class used as a plain static module: the replacement is a
+     * class, so the dynamic module's own providers, imports and exports (meant
+     * for the replaced class) are dropped.
+     */
+    private applyReplacement;
     private setModule;
     private getModuleFromCache;
 }

package/dist/types/core/nexus-applications.browser.d.ts

@@ -1,21 +1,43 @@
-import type { InjectionToken, Module, NexusApplicationInterface, ScannerPluginInterface } from "../interfaces";
+import type { CreateChildOptions, DynamicModule, GetOptions, LazyModule, NexusApplicationInterface, ProviderToken, ScannerPluginInterface, Type, UnloadResult } from "../interfaces";
+import { ModuleRef } from "./module-ref";
 /**
  * @deprecated
  * It will be removed in version 1.0.0.
- * these classes work the same way. For the new behavior, use @NexusApplications
+ * these classes work the same way. For the new behavior, use @NexusApplication
  */
-export declare class NexusApplicationsBrowser implements NexusApplicationInterface {
+export declare class NexusApplicationBrowser implements NexusApplicationInterface {
     private readonly rootModule;
     private readonly hashUtil;
     private readonly scannerPlugins;
     private readonly container;
-    private _parentContainer;
+    private closePromise;
     private constructor();
-    static create(rootModule: Module): NexusApplicationsBrowser;
+    static create(rootModule: Type): NexusApplicationBrowser;
     bootstrap(): Promise<this>;
     addScannerPlugin(scanner: ScannerPluginInterface | ScannerPluginInterface[]): this;
-    get<T>(token: InjectionToken): Promise<T | undefined>;
+    get<T>(token: ProviderToken<T>): T;
+    get<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): T | undefined;
+    get<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): T;
+    get<T>(token: ProviderToken<T>, options: GetOptions): T | undefined;
+    resolve<T>(token: ProviderToken<T>): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): Promise<T | undefined>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: GetOptions): Promise<T | undefined>;
     get errors(): import("@nexus-ioc/shared").GraphError[];
-    async(): this;
-    setParent(parentContainer: NexusApplicationInterface): this;
+    load(lazyModule: LazyModule): Promise<ModuleRef>;
+    unload(ref: ModuleRef): Promise<UnloadResult>;
+    lazy(): this;
+    close(): Promise<void>;
+    get isClosed(): boolean;
+    private assertOpen;
+    private assertUsable;
+    createChild(_child: Type | DynamicModule | LazyModule, _options?: CreateChildOptions): Promise<NexusApplicationInterface>;
 }