@nexus-ioc/core 0.4.2 → 0.6.2

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

@@ -0,0 +1,154 @@
+import type { ContainerInterface, DynamicModule, HashUtilInterface, InjectionToken, Module, ModuleContainerInterface, ModuleGraphInterface } from "../../interfaces";
+/**
+ * Container is the core IoC (Inversion of Control) container that manages
+ * modules, providers, and dependency injection.
+ *
+ * The Container is responsible for:
+ * - Registering and managing modules
+ * - Building the dependency graph
+ * - Resolving dependencies and creating instances
+ * - Managing the lifecycle of providers
+ *
+ * @example
+ * ```typescript
+ * const container = new Container(hashUtils);
+ * await container.run(AppModule);
+ * const service = await container.get(MyService);
+ * ```
+ */
+export declare class Container implements ContainerInterface {
+    private readonly hashUtils;
+    private readonly modulesContainer;
+    private _graph;
+    private moduleGraphResolver;
+    /**
+     * Creates a new Container instance.
+     *
+     * @param hashUtils - Utility for generating unique hashes for modules
+     */
+    constructor(hashUtils: HashUtilInterface);
+    /**
+     * Adds a module to the container.
+     *
+     * This method registers a module and all its providers, imports, and exports
+     * in the container. The module can be either a static module class or a
+     * dynamic module with runtime configuration.
+     *
+     * @param module - The module to add (static or dynamic)
+     * @returns A promise that resolves to the module container
+     *
+     * @example
+     * ```typescript
+     * await container.addModule(AppModule);
+     * await container.addModule(DatabaseModule.forRoot({ host: 'localhost' }));
+     * ```
+     */
+    addModule(module: Module | DynamicModule): Promise<ModuleContainerInterface>;
+    /**
+     * Replaces an existing module with a new module.
+     *
+     * This is useful for hot module replacement or testing scenarios where
+     * you need to swap out a module implementation.
+     *
+     * @param moduleToReplace - The module to be replaced
+     * @param newModule - The new module to use instead
+     * @returns A promise that resolves to the new module container
+     *
+     * @example
+     * ```typescript
+     * await container.replaceModule(OldDatabaseModule, NewDatabaseModule);
+     * ```
+     */
+    replaceModule(moduleToReplace: Module, newModule: Module): Promise<ModuleContainerInterface>;
+    /**
+     * Retrieves a module container by its module class.
+     *
+     * @param module - The module class to look up
+     * @returns A promise that resolves to the module container, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const moduleContainer = await container.getModule(DatabaseModule);
+     * ```
+     */
+    getModule(module: Module): Promise<ModuleContainerInterface | undefined>;
+    /**
+     * Resolves and returns an instance of a provider by its injection token.
+     *
+     * 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
+     *
+     * @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
+     * const userService = await container.get(UserService);
+     * const config = await container.get('CONFIG');
+     * ```
+     */
+    get<T>(token: InjectionToken): Promise<T | undefined>;
+    /**
+     * Initializes and runs the container with the specified root module.
+     *
+     * This method:
+     * 1. Registers the root module and all its dependencies
+     * 2. Builds the dependency graph
+     * 3. Validates the graph for circular dependencies and missing providers
+     * 4. Initializes all providers with lifecycle hooks
+     *
+     * This method must be called before using get() to resolve dependencies.
+     *
+     * @param rootModule - The root module of the application
+     * @returns A promise that resolves when initialization is complete
+     * @throws {Error} If there are circular dependencies or missing providers
+     *
+     * @example
+     * ```typescript
+     * const container = new Container(hashUtils);
+     * await container.run(AppModule);
+     * // Now you can use container.get() to resolve dependencies
+     * ```
+     */
+    run(rootModule: Module): Promise<void>;
+    /**
+     * Gets the dependency graph.
+     *
+     * The graph contains all modules, providers, and their dependencies.
+     * It can be used for introspection and debugging.
+     *
+     * @returns The module graph
+     * @throws {Error} If the graph is not initialized (run() not called yet)
+     *
+     * @example
+     * ```typescript
+     * await container.run(AppModule);
+     * const graph = container.graph;
+     * console.log(graph.getAllNodes());
+     * ```
+     */
+    get graph(): ModuleGraphInterface;
+    /**
+     * Gets all errors that occurred during graph compilation.
+     *
+     * Errors can include:
+     * - Circular dependencies
+     * - Missing providers
+     * - Unreachable dependencies
+     *
+     * @returns An array of graph errors
+     *
+     * @example
+     * ```typescript
+     * await container.run(AppModule);
+     * if (container.errors.length > 0) {
+     *   console.error('Graph errors:', container.errors);
+     * }
+     * ```
+     */
+    get errors(): import("@nexus-ioc/shared").GraphError[];
+}

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

@@ -12,5 +12,5 @@ export declare class ModuleContainer implements ModuleContainerInterface {
     get providers(): Provider[];
     get exports(): InjectionToken[];
     get<T>(token: InjectionToken): Promise<T | undefined>;
-    get errors(): import("../../interfaces").GraphError[];
+    get errors(): import("@nexus-ioc/shared").GraphError[];
 }

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

@@ -1,13 +1,21 @@
 import type { InjectionToken, Module, NexusApplicationInterface, ScannerPluginInterface } from "../interfaces";
+/**
+ * @deprecated
+ * It will be removed in version 1.0.0.
+ * these classes work the same way. For the new behavior, use @NexusApplications
+ */
 export declare class NexusApplicationsBrowser implements NexusApplicationInterface {
     private readonly rootModule;
     private readonly hashUtil;
     private readonly scannerPlugins;
     private readonly container;
+    private _parentContainer;
     private constructor();
     static create(rootModule: Module): NexusApplicationsBrowser;
     bootstrap(): Promise<this>;
     addScannerPlugin(scanner: ScannerPluginInterface | ScannerPluginInterface[]): this;
     get<T>(token: InjectionToken): Promise<T | undefined>;
-    get errors(): import("../interfaces").GraphError[];
+    get errors(): import("@nexus-ioc/shared").GraphError[];
+    async(): this;
+    setParent(parentContainer: NexusApplicationInterface): this;
 }

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

@@ -0,0 +1,160 @@
+import { type HashUtilInterface, type InjectionToken, type Module, type NexusApplicationInterface, type ScannerPluginInterface } from "../interfaces";
+/**
+ * NexusApplications is the main application class that provides a high-level
+ * API for creating and managing IoC containers.
+ *
+ * This class wraps the Container and provides additional features:
+ * - Automatic singleton initialization
+ * - Scanner plugin support for custom metadata processing
+ * - Parent-child container hierarchies
+ * - Async/sync container modes
+ *
+ * @example
+ * ```typescript
+ * const app = NexusApplications.create(AppModule);
+ * await app.bootstrap();
+ * const service = await app.get(MyService);
+ * ```
+ */
+export declare class NexusApplications implements NexusApplicationInterface {
+    private readonly rootModule;
+    private hashUtil;
+    private isAsyncContainer;
+    private readonly container;
+    private readonly scannerPlugins;
+    private _parentContainer;
+    /**
+     * Creates a new NexusApplications instance.
+     *
+     * @param rootModule - The root module of the application
+     * @param options - Optional configuration
+     * @param options.hashFn - Custom hash function for module identification
+     */
+    private constructor();
+    /**
+     * Creates a new NexusApplications instance.
+     *
+     * This is the main entry point for creating an application.
+     *
+     * @param rootModule - The root module of the application
+     * @param options - Optional configuration
+     * @param options.hashFn - Custom hash function for module identification
+     * @returns A new NexusApplications instance
+     *
+     * @example
+     * ```typescript
+     * const app = NexusApplications.create(AppModule);
+     * await app.bootstrap();
+     * ```
+     */
+    static create(rootModule: Module, options?: {
+        hashFn: new () => HashUtilInterface;
+    }): NexusApplications;
+    /**
+     * Bootstraps the application by initializing the container and all providers.
+     *
+     * This method:
+     * 1. Runs the container with the root module
+     * 2. Executes all registered scanner plugins
+     * 3. Pre-instantiates all singleton providers (unless async mode is enabled)
+     *
+     * @returns A promise that resolves to this instance for method chaining
+     * @throws {Error} If there are circular dependencies or missing providers
+     *
+     * @example
+     * ```typescript
+     * const app = NexusApplications.create(AppModule);
+     * await app.bootstrap();
+     * // Application is now ready to use
+     * ```
+     */
+    bootstrap(): Promise<this>;
+    /**
+     * Adds one or more scanner plugins to the application.
+     *
+     * Scanner plugins are executed after the dependency graph is built
+     * and can be used to process custom metadata, validate the graph,
+     * or perform other initialization tasks.
+     *
+     * @param scanner - A single scanner plugin or an array of scanner plugins
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const app = NexusApplications.create(AppModule)
+     *   .addScannerPlugin(new CustomScanner())
+     *   .addScannerPlugin([new Scanner1(), new Scanner2()]);
+     * await app.bootstrap();
+     * ```
+     */
+    addScannerPlugin(scanner: ScannerPluginInterface | ScannerPluginInterface[]): this;
+    /**
+     * Resolves and returns an instance of a provider by its injection token.
+     *
+     * If the provider is not found in this container, it will attempt to
+     * resolve it from the parent container (if set).
+     *
+     * @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
+     * const app = await NexusApplications.create(AppModule).bootstrap();
+     * const userService = await app.get(UserService);
+     * const config = await app.get('CONFIG');
+     * ```
+     */
+    get<T>(token: InjectionToken): Promise<T | undefined>;
+    /**
+     * Gets all errors that occurred during graph compilation.
+     *
+     * @returns An array of graph errors
+     *
+     * @example
+     * ```typescript
+     * const app = await NexusApplications.create(AppModule).bootstrap();
+     * if (app.errors.length > 0) {
+     *   console.error('Application errors:', app.errors);
+     * }
+     * ```
+     */
+    get errors(): import("@nexus-ioc/shared").GraphError[];
+    /**
+     * Enables async mode for the container.
+     *
+     * In async mode, singleton providers are NOT pre-instantiated during
+     * bootstrap. They will be created lazily on first access via get().
+     * This can improve startup time for large applications.
+     *
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const app = NexusApplications.create(AppModule)
+     *   .async();
+     * await app.bootstrap(); // Singletons are NOT created yet
+     * const service = await app.get(MyService); // Created on first access
+     * ```
+     */
+    async(): this;
+    /**
+     * Sets a parent container for this application.
+     *
+     * When a provider is not found in this container, it will be looked up
+     * in the parent container. This enables hierarchical container structures.
+     *
+     * @param parentContainer - The parent container
+     * @returns This instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const parentApp = await NexusApplications.create(ParentModule).bootstrap();
+     * const childApp = await NexusApplications.create(ChildModule)
+     *   .setParent(parentApp)
+     *   .bootstrap();
+     * // childApp can access providers from parentApp
+     * ```
+     */
+    setParent(parentContainer: NexusApplicationInterface): this;
+}

package/dist/{core → types/core}/nexus-applications.server.d.ts

@@ -1,13 +1,21 @@
 import type { InjectionToken, Module, NexusApplicationInterface, ScannerPluginInterface } from "../interfaces";
+/**
+ * @deprecated
+ * It will be removed in version 1.0.0.
+ * these classes work the same way. For the new behavior, use @NexusApplications
+ */
 export declare class NexusApplicationsServer implements NexusApplicationInterface {
     private readonly rootModule;
     private readonly hashUtil;
     private readonly container;
     private readonly scannerPlugins;
+    private _parentContainer;
     private constructor();
     static create(rootModule: Module): NexusApplicationsServer;
     bootstrap(): Promise<this>;
     addScannerPlugin(scanner: ScannerPluginInterface | ScannerPluginInterface[]): this;
     get<T>(token: InjectionToken): Promise<T | undefined>;
-    get errors(): import("../interfaces").GraphError[];
+    get errors(): import("@nexus-ioc/shared").GraphError[];
+    async(): this;
+    setParent(parentContainer: NexusApplicationInterface): this;
 }

package/dist/types/decorators/inject.d.ts

@@ -0,0 +1,42 @@
+import "reflect-metadata";
+import { type Type } from "../interfaces";
+/**
+ * Explicitly specifies the injection token for a constructor parameter or property.
+ *
+ * This decorator is used when:
+ * - You need to inject a provider by a string or symbol token
+ * - TypeScript's reflection cannot determine the type (e.g., interfaces, circular dependencies)
+ * - You want to inject a different implementation than the declared type
+ *
+ * @param token - The injection token (class, string, or symbol)
+ * @returns A decorator that can be applied to constructor parameters or properties
+ * @throws {Error} If the token is undefined (often due to circular dependencies)
+ *
+ * @example
+ * ```typescript
+ * // Constructor parameter injection
+ * @Injectable()
+ * class UserService {
+ *   constructor(
+ *     @Inject('DATABASE_CONFIG') private config: DatabaseConfig,
+ *     @Inject(Logger) private logger: Logger
+ *   ) {}
+ * }
+ *
+ * // Property injection
+ * @Injectable()
+ * class ProductService {
+ *   @Inject('CACHE_MANAGER')
+ *   private cache: CacheManager;
+ * }
+ *
+ * // Resolving circular dependencies
+ * @Injectable()
+ * class ServiceA {
+ *   constructor(
+ *     @Inject(forwardRef(() => ServiceB)) private serviceB: ServiceB
+ *   ) {}
+ * }
+ * ```
+ */
+export declare function Inject(token: Type | symbol | string): PropertyDecorator & ParameterDecorator;

package/dist/types/decorators/injectable.d.ts

@@ -0,0 +1,37 @@
+import "reflect-metadata";
+import type { InjectableOptions } from "../interfaces";
+/**
+ * Marks a class as injectable, making it available for dependency injection.
+ *
+ * This decorator must be applied to any class that you want to use as a provider
+ * in the IoC container. It configures the scope and other options for the provider.
+ *
+ * @param options - Configuration options for the injectable
+ * @param options.scope - The lifecycle scope of the provider:
+ *   - `Scope.Singleton` (default): One instance shared across the entire application
+ *   - `Scope.Request`: New instance for each container.get() call
+ *   - `Scope.Transient`: New instance every time, even within the same dependency tree
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * // Singleton scope (default)
+ * @Injectable()
+ * class UserService {
+ *   constructor(private db: Database) {}
+ * }
+ *
+ * // Request scope
+ * @Injectable({ scope: Scope.Request })
+ * class RequestContext {
+ *   requestId = Math.random();
+ * }
+ *
+ * // Transient scope
+ * @Injectable({ scope: Scope.Transient })
+ * class Logger {
+ *   timestamp = Date.now();
+ * }
+ * ```
+ */
+export declare function Injectable(options?: InjectableOptions): ClassDecorator;

package/dist/types/decorators/nsModule.d.ts

@@ -0,0 +1,44 @@
+import "reflect-metadata";
+import type { ModuleMetadata } from "../interfaces";
+/**
+ * Defines a module in the application.
+ *
+ * A module is a class annotated with @NsModule() decorator that organizes
+ * the application structure. Modules can:
+ * - Declare providers that will be instantiated by the container
+ * - Import other modules to use their exported providers
+ * - Export providers to make them available to other modules
+ *
+ * @param metadata - Module configuration
+ * @param metadata.imports - Modules whose exported providers should be available in this module
+ * @param metadata.providers - Providers that belong to this module
+ * @param metadata.exports - Providers or modules to export (make available to importing modules)
+ * @returns A class decorator
+ * @throws {Error} If invalid metadata keys are provided
+ *
+ * @example
+ * ```typescript
+ * // Basic module
+ * @NsModule({
+ *   providers: [UserService, UserRepository],
+ *   exports: [UserService]
+ * })
+ * class UserModule {}
+ *
+ * // Module with imports
+ * @NsModule({
+ *   imports: [DatabaseModule, LoggerModule],
+ *   providers: [ProductService],
+ *   exports: [ProductService]
+ * })
+ * class ProductModule {}
+ *
+ * // Root module
+ * @NsModule({
+ *   imports: [UserModule, ProductModule],
+ *   providers: [AppService]
+ * })
+ * class AppModule {}
+ * ```
+ */
+export declare function NsModule(metadata: ModuleMetadata): ClassDecorator;

package/dist/types/decorators/optional.d.ts

@@ -0,0 +1,42 @@
+import "reflect-metadata";
+/**
+ * Marks a dependency as optional.
+ *
+ * When a dependency is marked as optional, the container will not throw an error
+ * if the provider is not found. Instead, it will inject `undefined`.
+ *
+ * This is useful for:
+ * - Optional features that may not be available in all configurations
+ * - Graceful degradation when certain services are not registered
+ * - Testing scenarios where you want to omit certain dependencies
+ *
+ * @returns A decorator that can be applied to constructor parameters or properties
+ *
+ * @example
+ * ```typescript
+ * // Optional constructor parameter
+ * @Injectable()
+ * class UserService {
+ *   constructor(
+ *     private db: Database,
+ *     @Optional() private cache?: CacheService
+ *   ) {
+ *     // cache will be undefined if CacheService is not registered
+ *   }
+ * }
+ *
+ * // Optional property injection
+ * @Injectable()
+ * class ProductService {
+ *   @Optional()
+ *   @Inject('ANALYTICS')
+ *   private analytics?: AnalyticsService;
+ *
+ *   trackEvent(event: string) {
+ *     // Only track if analytics service is available
+ *     this.analytics?.track(event);
+ *   }
+ * }
+ * ```
+ */
+export declare function Optional(): PropertyDecorator & ParameterDecorator;

package/dist/{index.d.ts → types/index.d.ts}

@@ -1,7 +1,10 @@
-export * from "./interfaces";
-export { NsModule } from "./decorators/nsModule";
+export { ContainerNotCompiledError } from "@nexus-ioc/shared";
+export { Container } from "./core/modules/container";
+export { NexusApplications } from "./core/nexus-applications";
+export { Global } from "./decorators/global";
 export { Inject } from "./decorators/inject";
 export { Injectable } from "./decorators/injectable";
-export { Global } from "./decorators/global";
+export { NsModule } from "./decorators/nsModule";
 export { Optional } from "./decorators/optional";
+export * from "./interfaces";
 export * from "./utils/helpers";