@nexus-ioc/core 0.4.2 → 0.6.1

package/dist/cjs/core/nexus-applications.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NexusApplications = void 0;
+const interfaces_1 = require("../interfaces");
+const hash_utils_1 = require("../utils/hash-utils");
+const container_1 = require("./modules/container");
+/**
+ * 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);
+ * ```
+ */
+class NexusApplications {
+    /**
+     * 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
+     */
+    constructor(rootModule, options) {
+        this.rootModule = rootModule;
+        this.hashUtil = new hash_utils_1.HashUtil();
+        this.isAsyncContainer = false;
+        this.container = new container_1.Container(this.hashUtil);
+        this.scannerPlugins = [];
+        this._parentContainer = null;
+        if (options?.hashFn && typeof options?.hashFn === "function") {
+            this.hashUtil = new options.hashFn();
+        }
+    }
+    /**
+     * 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, options) {
+        return new NexusApplications(rootModule, options);
+    }
+    /**
+     * 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
+     * ```
+     */
+    async bootstrap() {
+        await this.container.run(this.rootModule);
+        for (const scannerPlugin of this.scannerPlugins) {
+            await scannerPlugin.scan(this.container.graph);
+        }
+        if (!this.isAsyncContainer) {
+            for (const [token, node] of this.container.graph.nodes) {
+                if (node.type === interfaces_1.NodeTypeEnum.PROVIDER &&
+                    node.scope === interfaces_1.Scope.Singleton) {
+                    await this.container.get(token);
+                }
+            }
+        }
+        return 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) {
+        const plugins = Array.isArray(scanner) ? scanner : [scanner];
+        this.scannerPlugins.push(...plugins);
+        return 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');
+     * ```
+     */
+    async get(token) {
+        const dependency = await this.container.get(token);
+        // Check for undefined specifically, not falsy values (null, 0, false, etc. are valid)
+        if (dependency === undefined) {
+            return this._parentContainer?.get(token);
+        }
+        return dependency;
+    }
+    /**
+     * 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() {
+        return this.container.errors;
+    }
+    /**
+     * 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.isAsyncContainer = true;
+        return 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) {
+        this._parentContainer = parentContainer;
+        return this;
+    }
+}
+exports.NexusApplications = NexusApplications;
+//# sourceMappingURL=nexus-applications.js.map

package/dist/cjs/core/nexus-applications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-applications.js","sourceRoot":"","sources":["../../../src/core/nexus-applications.ts"],"names":[],"mappings":"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"}

package/dist/{core → cjs/core}/nexus-applications.server.js

@@ -3,12 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NexusApplicationsServer = void 0;
 const hash_utils_server_1 = require("../utils/hash-utils.server");
 const container_1 = require("./modules/container");
+/**
+ * @deprecated
+ * It will be removed in version 1.0.0.
+ * these classes work the same way. For the new behavior, use @NexusApplications
+ */
 class NexusApplicationsServer {
     constructor(rootModule) {
         this.rootModule = rootModule;
         this.hashUtil = new hash_utils_server_1.HashUtilsServer();
         this.container = new container_1.Container(this.hashUtil);
         this.scannerPlugins = [];
+        this._parentContainer = null;
     }
     static create(rootModule) {
         return new NexusApplicationsServer(rootModule);
@@ -25,12 +31,23 @@ class NexusApplicationsServer {
         this.scannerPlugins.push(...plugins);
         return this;
     }
-    get(token) {
-        return this.container.get(token);
+    async get(token) {
+        const dependency = await this.container.get(token);
+        if (!dependency) {
+            return this._parentContainer?.get(token);
+        }
+        return dependency;
     }
     get errors() {
         return this.container.errors;
     }
+    async() {
+        return this;
+    }
+    setParent(parentContainer) {
+        this._parentContainer = parentContainer;
+        return this;
+    }
 }
 exports.NexusApplicationsServer = NexusApplicationsServer;
 //# sourceMappingURL=nexus-applications.server.js.map

package/dist/cjs/core/nexus-applications.server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-applications.server.js","sourceRoot":"","sources":["../../../src/core/nexus-applications.server.ts"],"names":[],"mappings":";;;AAMA,kEAA6D;AAC7D,mDAAgD;AAEhD;;;;GAIG;AACH,MAAa,uBAAuB;IAMnC,YAAqC,UAAkB;QAAlB,eAAU,GAAV,UAAU,CAAQ;QALtC,aAAQ,GAAG,IAAI,mCAAe,EAAE,CAAC;QACjC,cAAS,GAAG,IAAI,qBAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,mBAAc,GAA6B,EAAE,CAAC;QACvD,qBAAgB,GAAqC,IAAI,CAAC;IAER,CAAC;IAE3D,MAAM,CAAC,MAAM,CAAC,UAAkB;QAC/B,OAAO,IAAI,uBAAuB,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IAEM,KAAK,CAAC,SAAS;QACrB,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAE1C,KAAK,MAAM,aAAa,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACjD,MAAM,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAEM,gBAAgB,CACtB,OAA0D;QAE1D,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACb,CAAC;IAEM,KAAK,CAAC,GAAG,CAAI,KAAqB;QACxC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAI,KAAK,CAAC,CAAC;QAEtD,IAAI,CAAC,UAAU,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,gBAAgB,EAAE,GAAG,CAAI,KAAK,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,UAAU,CAAC;IACnB,CAAC;IAED,IAAW,MAAM;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,KAAK;QACJ,OAAO,IAAI,CAAC;IACb,CAAC;IAEM,SAAS,CAAC,eAA0C;QAC1D,IAAI,CAAC,gBAAgB,GAAG,eAAe,CAAC;QACxC,OAAO,IAAI,CAAC;IACb,CAAC;CACD;AApDD,0DAoDC"}

package/dist/{core → cjs/core}/resolver/providers-container.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProvidersContainer = void 0;
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+// biome-ignore lint/suspicious/noExplicitAny: providers container
 class ProvidersContainer extends Map {
 }
 exports.ProvidersContainer = ProvidersContainer;

package/dist/cjs/core/resolver/providers-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers-container.js","sourceRoot":"","sources":["../../../../src/core/resolver/providers-container.ts"],"names":[],"mappings":";;;AAEA,kEAAkE;AAClE,MAAa,kBAAmB,SAAQ,GAAwB;CAAG;AAAnE,gDAAmE"}

package/dist/{core → cjs/core}/resolver/resolver.js

@@ -14,18 +14,32 @@ class Resolver {
         this.providersContainer = new providers_container_1.ProvidersContainer();
     }
     async resolveProvider(token, resolveCache = new providers_container_1.ProvidersContainer(), isCircularDependency = false) {
-        if (this.providersContainer.has(token)) {
-            return this.providersContainer.get(token);
-        }
         const node = this.graph.getNode(token);
         if (!node) {
-            throw new Error(`Provider not found: ${token.toString()}`);
+            return undefined;
+        }
+        // Get the scope of the provider
+        const scope = node.scope;
+        // For Transient scope, always create a new instance (no caching at all)
+        if (scope === interfaces_1.Scope.Transient) {
+            const [instance] = await this.createInstance(node, resolveCache, isCircularDependency);
+            return instance;
         }
+        // For Singleton scope, check global cache first
+        if (scope === interfaces_1.Scope.Singleton && this.providersContainer.has(token)) {
+            return this.providersContainer.get(token);
+        }
+        // For Request and Singleton scopes, check resolve cache (within current resolution tree)
         if (resolveCache.has(token)) {
             return resolveCache.get(token);
         }
         const [instance, saveInCache] = await this.createInstance(node, resolveCache, isCircularDependency);
-        resolveCache.set(token, instance);
+        // Add to resolve cache for current resolution context (for Request and Singleton)
+        // This ensures same instance is used within a single dependency resolution tree
+        if (scope === interfaces_1.Scope.Singleton || scope === interfaces_1.Scope.Request) {
+            resolveCache.set(token, instance);
+        }
+        // Only save to global cache for Singleton scope
         if (saveInCache) {
             this.providersContainer.set(token, instance);
         }
@@ -61,23 +75,21 @@ class Resolver {
             prev[1].push(depToken);
             return prev;
         }, [[], []]);
-        // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+        // biome-ignore lint/suspicious/noExplicitAny: dependency resolution
         let resolvedDependencies = [];
         for (const depToken of dependencies) {
             if (isCircularDependencyFn(depToken)) {
-                // @ts-ignore
                 if (isCircularDependency) {
                     resolvedDependencies.push(depToken);
                     continue;
                 }
                 const instance = await this.resolveProvider(
-                // @ts-ignore
+                // @ts-expect-error
                 depToken.dependencyName, resolveCache, true);
                 resolvedDependencies.push(instance);
                 continue;
             }
             const instance = await this.resolveProvider(depToken, resolveCache);
-            this.providersContainer.set(depToken, instance);
             resolvedDependencies.push(instance);
         }
         resolvedDependencies = resolvedDependencies.map((dependency, index) => {
@@ -86,28 +98,55 @@ class Resolver {
             }
             return dependency;
         });
-        // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+        // biome-ignore lint/suspicious/noExplicitAny: instance creation
         let instance;
         let saveInCache = true;
         const deps = resolvedDependencies.map((depToken) => isCircularDependencyFn(depToken) ? depToken() : depToken);
         if ((0, helpers_1.isClassProvider)(provider)) {
             instance = new provider.useClass(...deps);
             await this.injectPropertyDependencies(instance, node, resolveCache);
-            if (node.scope === interfaces_1.Scope.Request) {
-                saveInCache = false;
-            }
+            // Determine caching strategy based on scope
+            const scope = node.scope;
+            saveInCache = scope === interfaces_1.Scope.Singleton;
         }
         else if ((0, helpers_1.isValueProvider)(provider)) {
             instance = provider.useValue;
+            // Value providers are always singleton
+            saveInCache = true;
         }
         else if ((0, helpers_1.isFactoryProvider)(provider)) {
             instance = await provider.useFactory(...deps);
+            // Check scope for factory providers
+            const scope = node.scope;
+            saveInCache = scope === interfaces_1.Scope.Singleton;
         }
         else {
             instance = new provider(...deps);
             await this.injectPropertyDependencies(instance, node, resolveCache);
+            // Check scope for function providers
+            const scope = node.scope;
+            saveInCache = scope === interfaces_1.Scope.Singleton;
+        }
+        // Call lifecycle hook with error handling
+        if (instance?.onModuleInit) {
+            try {
+                await instance.onModuleInit();
+            }
+            catch (error) {
+                // Re-throw with additional context about which provider failed
+                const providerName = typeof provider === "function"
+                    ? provider.name
+                    : provider.provide?.toString() ||
+                        "Unknown";
+                const errorMessage = `Failed to initialize provider "${providerName}": ${error instanceof Error ? error.message : String(error)}`;
+                const wrappedError = new Error(errorMessage);
+                // Preserve original error stack if available
+                if (error instanceof Error && error.stack) {
+                    wrappedError.stack = `${wrappedError.stack}\nCaused by: ${error.stack}`;
+                }
+                throw wrappedError;
+            }
         }
-        instance?.onModuleInit?.();
         return [instance, saveInCache];
     }
     async injectPropertyDependencies(instance, node, resolveCache) {

package/dist/cjs/core/resolver/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../../src/core/resolver/resolver.ts"],"names":[],"mappings":"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"}

package/dist/{decorators → cjs/decorators}/global.js

@@ -4,7 +4,7 @@ exports.Global = Global;
 require("reflect-metadata");
 const interfaces_1 = require("../interfaces");
 function Global() {
-    // biome-ignore lint/complexity/noBannedTypes: <explanation>
+    // biome-ignore lint/complexity/noBannedTypes: Function type needed for decorator
     return (target) => {
         Reflect.defineMetadata(interfaces_1.MODULE_GLOBAL_WATERMARK, true, target);
     };

package/dist/cjs/decorators/global.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global.js","sourceRoot":"","sources":["../../../src/decorators/global.ts"],"names":[],"mappings":";;AAGA,wBAKC;AARD,4BAA0B;AAC1B,8CAAwD;AAExD,SAAgB,MAAM;IACrB,iFAAiF;IACjF,OAAO,CAAC,MAAgB,EAAE,EAAE;QAC3B,OAAO,CAAC,cAAc,CAAC,oCAAuB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC,CAAC;AACH,CAAC"}

package/dist/{decorators → cjs/decorators}/inject.js

@@ -3,6 +3,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Inject = Inject;
 require("reflect-metadata");
 const interfaces_1 = require("../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
+ *   ) {}
+ * }
+ * ```
+ */
 function Inject(token) {
     return (target, propertyKey, parameterIndex) => {
         Reflect.defineMetadata(interfaces_1.INJECT_WATERMARK, true, target);

package/dist/cjs/decorators/inject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject.js","sourceRoot":"","sources":["../../../src/decorators/inject.ts"],"names":[],"mappings":";;AA+CA,wBAuCC;AAtFD,4BAA0B;AAC1B,8CAKuB;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,MAAM,CACrB,KAA6B;IAE7B,OAAO,CACN,MAAc,EACd,WAA6B,EAC7B,cAAuB,EACtB,EAAE;QACH,OAAO,CAAC,cAAc,CAAC,6BAAgB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAEvD,MAAM,IAAI,GACT,KAAK;YACL,OAAO,CAAC,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,WAAqB,CAAC,CAAC;QAEnE,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC;mCACgB,cAAc;yEACwB,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,UAAU,GACb,OAAO,CAAC,WAAW,CAAC,mCAAsB,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YAE3D,UAAU,GAAG,CAAC,GAAG,UAAU,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,OAAO,CAAC,cAAc,CACrB,mCAAsB,EACtB,UAAU,EACV,MAAM,CAAC,WAAW,CAClB,CAAC;YACF,OAAO;QACR,CAAC;QAED,IAAI,YAAY,GACf,OAAO,CAAC,WAAW,CAAC,wCAA2B,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAEhE,YAAY,GAAG,CAAC,GAAG,YAAY,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,OAAO,CAAC,cAAc,CAAC,wCAA2B,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC,CAAC;AACH,CAAC"}

package/dist/cjs/decorators/injectable.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Injectable = Injectable;
+require("reflect-metadata");
+const interfaces_1 = require("../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();
+ * }
+ * ```
+ */
+function Injectable(options = { scope: interfaces_1.Scope.Singleton }) {
+    return (target) => {
+        Reflect.defineMetadata(interfaces_1.INJECTABLE_OPTIONS, options, target);
+        Reflect.defineMetadata(interfaces_1.INJECTABLE_WATERMARK, true, target);
+    };
+}
+//# sourceMappingURL=injectable.js.map

package/dist/cjs/decorators/injectable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.js","sourceRoot":"","sources":["../../../src/decorators/injectable.ts"],"names":[],"mappings":";;AAsCA,gCAOC;AA7CD,4BAA0B;AAE1B,8CAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,UAAU,CACzB,UAA6B,EAAE,KAAK,EAAE,kBAAK,CAAC,SAAS,EAAE;IAEvD,OAAO,CAAC,MAAM,EAAE,EAAE;QACjB,OAAO,CAAC,cAAc,CAAC,+BAAkB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5D,OAAO,CAAC,cAAc,CAAC,iCAAoB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC,CAAC;AACH,CAAC"}

package/dist/cjs/decorators/nsModule.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NsModule = NsModule;
+require("reflect-metadata");
+const interfaces_1 = require("../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 {}
+ * ```
+ */
+function NsModule(metadata) {
+    const propsKeys = Object.keys(metadata);
+    (0, interfaces_1.validateModuleKeys)(propsKeys);
+    return (target) => {
+        Reflect.defineMetadata(interfaces_1.MODULE_WATERMARK, true, target);
+        Reflect.defineMetadata(interfaces_1.MODULE_METADATA.IMPORTS, metadata.imports || [], target);
+        Reflect.defineMetadata(interfaces_1.MODULE_METADATA.EXPORTS, metadata.exports || [], target);
+        Reflect.defineMetadata(interfaces_1.MODULE_METADATA.PROVIDERS, metadata.providers || [], target);
+    };
+}
+//# sourceMappingURL=nsModule.js.map

package/dist/cjs/decorators/nsModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nsModule.js","sourceRoot":"","sources":["../../../src/decorators/nsModule.ts"],"names":[],"mappings":";;AAiDA,4BAsBC;AAvED,4BAA0B;AAE1B,8CAIuB;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,SAAgB,QAAQ,CAAC,QAAwB;IAChD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAA,+BAAkB,EAAC,SAAS,CAAC,CAAC;IAE9B,OAAO,CAAC,MAAM,EAAE,EAAE;QACjB,OAAO,CAAC,cAAc,CAAC,6BAAgB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACvD,OAAO,CAAC,cAAc,CACrB,4BAAe,CAAC,OAAO,EACvB,QAAQ,CAAC,OAAO,IAAI,EAAE,EACtB,MAAM,CACN,CAAC;QACF,OAAO,CAAC,cAAc,CACrB,4BAAe,CAAC,OAAO,EACvB,QAAQ,CAAC,OAAO,IAAI,EAAE,EACtB,MAAM,CACN,CAAC;QACF,OAAO,CAAC,cAAc,CACrB,4BAAe,CAAC,SAAS,EACzB,QAAQ,CAAC,SAAS,IAAI,EAAE,EACxB,MAAM,CACN,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}

package/dist/cjs/decorators/optional.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Optional = Optional;
+require("reflect-metadata");
+const interfaces_1 = require("../interfaces");
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+function Optional() {
+    return (target, propertyKey, parameterIndex) => {
+        Reflect.defineMetadata(interfaces_1.OPTIONAL_WATERMARK, true, target);
+        if (parameterIndex === undefined) {
+            let properties = Reflect.getMetadata(interfaces_1.PROPERTY_OPTIONAL_DEPS_METADATA, target) || [];
+            properties = [...properties, { key: propertyKey }];
+            Reflect.defineMetadata(interfaces_1.PROPERTY_OPTIONAL_DEPS_METADATA, properties, target.constructor);
+            return;
+        }
+        let properties = Reflect.getMetadata(interfaces_1.SELF_DECLARED_OPTIONAL_DEPS_METADATA, target) || [];
+        properties = [...properties, { index: parameterIndex }];
+        Reflect.defineMetadata(interfaces_1.SELF_DECLARED_OPTIONAL_DEPS_METADATA, properties, target);
+    };
+}
+//# sourceMappingURL=optional.js.map

package/dist/cjs/decorators/optional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional.js","sourceRoot":"","sources":["../../../src/decorators/optional.ts"],"names":[],"mappings":";;AA+CA,4BA+BC;AA9ED,4BAA0B;AAC1B,8CAIuB;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,SAAgB,QAAQ;IACvB,OAAO,CACN,MAAc,EACd,WAA6B,EAC7B,cAAuB,EACtB,EAAE;QACH,OAAO,CAAC,cAAc,CAAC,+BAAkB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAEzD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,UAAU,GACb,OAAO,CAAC,WAAW,CAAC,4CAA+B,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YAEpE,UAAU,GAAG,CAAC,GAAG,UAAU,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;YACnD,OAAO,CAAC,cAAc,CACrB,4CAA+B,EAC/B,UAAU,EACV,MAAM,CAAC,WAAW,CAClB,CAAC;YACF,OAAO;QACR,CAAC;QAED,IAAI,UAAU,GACb,OAAO,CAAC,WAAW,CAAC,iDAAoC,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAEzE,UAAU,GAAG,CAAC,GAAG,UAAU,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,cAAc,CACrB,iDAAoC,EACpC,UAAU,EACV,MAAM,CACN,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}