@khapu2906/treasure-chest 1.0.3 → 1.2.0

package/dist/esm/Container.js

@@ -0,0 +1,446 @@
+/**
+ * Container class for dependency injection
+ *
+ * @module Container
+ */
+import { Lazy } from './Lazy';
+import { Scope } from './Scope';
+/**
+ * Container class for dependency injection
+ * Manages service bindings, instances, and resolution logic
+ *
+ * @example
+ * ```typescript
+ * const container = new Container();
+ * container.bind('logger', () => new Logger());
+ * const logger = container.resolve<Logger>('logger');
+ * ```
+ */
+export class Container {
+    /**
+     * Create a new container
+     * @param parent Optional parent container for hierarchy
+     */
+    constructor(parent) {
+        /** Map-based storage for bindings - O(1) lookup */
+        this.bindings = new Map();
+        /** Cache for singleton instances */
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.instances = new Map();
+        /** Mapping of aliases to original keys */
+        this.aliases = new Map();
+        /** Cache for resolved bindings - performance optimization */
+        this.bindingCache = new Map();
+        /** Resolution stack for circular dependency detection */
+        this.resolutionStack = [];
+        this.parent = parent;
+    }
+    /**
+     * Register a transient binding (new instance on each resolve)
+     *
+     * @template T The type of service being bound
+     * @param key The unique identifier for this service
+     * @param factory Factory function that creates the service instance
+     * @param condition Optional condition function for conditional binding
+     *
+     * @example
+     * ```typescript
+     * container.bind('database', (c) => new Database());
+     * container.bind('cache', (c) => new Cache(), (c) => process.env.CACHE_ENABLED === 'true');
+     * ```
+     */
+    bind(key, factory, condition) {
+        const existing = this.bindings.get(key) || [];
+        existing.push({ key, factory, lifecycle: 'transient', condition });
+        this.bindings.set(key, existing);
+        this.bindingCache.clear(); // Invalidate cache
+    }
+    /**
+     * Register a singleton binding (single instance shared across all resolves)
+     *
+     * @template T The type of service being bound
+     * @param key The unique identifier for this service
+     * @param factory Factory function that creates the service instance
+     * @param condition Optional condition function for conditional binding
+     *
+     * @example
+     * ```typescript
+     * container.singleton('config', (c) => new Config());
+     * ```
+     */
+    singleton(key, factory, condition) {
+        const existing = this.bindings.get(key) || [];
+        existing.push({ key, factory, lifecycle: 'singleton', condition });
+        this.bindings.set(key, existing);
+        this.bindingCache.clear();
+    }
+    /**
+     * Register a scoped binding (single instance per scope)
+     *
+     * @template T The type of service being bound
+     * @param key The unique identifier for this service
+     * @param factory Factory function that creates the service instance
+     * @param dispose Optional disposal function for cleanup
+     *
+     * @example
+     * ```typescript
+     * container.scoped('dbConnection', (c) => new DbConnection(), () => {
+     *   console.log('Closing connection');
+     * });
+     * ```
+     */
+    scoped(key, factory, dispose) {
+        const existing = this.bindings.get(key) || [];
+        existing.push({ key, factory, lifecycle: 'scoped', dispose });
+        this.bindings.set(key, existing);
+        this.bindingCache.clear();
+    }
+    /**
+     * Register a lazy binding (deferred initialization)
+     *
+     * @template T The type of service being bound
+     * @param key The unique identifier for this service
+     * @param factory Factory function that creates the service instance
+     * @param lifecycle The lifecycle type (default: singleton)
+     *
+     * @example
+     * ```typescript
+     * container.lazy('heavyService', (c) => new HeavyService());
+     * const lazy = container.resolve<Lazy<HeavyService>>('heavyService');
+     * // Not initialized yet
+     * const service = lazy.value; // Initialized now
+     * ```
+     */
+    lazy(key, factory, lifecycle = 'singleton') {
+        const existing = this.bindings.get(key) || [];
+        existing.push({ key, factory, lifecycle, lazy: true });
+        this.bindings.set(key, existing);
+        this.bindingCache.clear();
+    }
+    /**
+     * Create an alias for an existing service key
+     *
+     * @param aliasKey The new alias name
+     * @param originalKey The original service key to alias
+     *
+     * @example
+     * ```typescript
+     * container.bind('UserRepository', () => new UserRepo());
+     * container.alias('UserRepo', 'UserRepository');
+     * // Both keys now resolve to the same binding
+     * ```
+     */
+    alias(aliasKey, originalKey) {
+        this.aliases.set(aliasKey, originalKey);
+    }
+    /**
+     * Create a child container that inherits from this container
+     *
+     * @returns A new child container
+     *
+     * @example
+     * ```typescript
+     * const parent = new Container();
+     * parent.singleton('config', () => new Config());
+     *
+     * const child = parent.createChild();
+     * child.bind('logger', () => new Logger());
+     *
+     * // Child can resolve both parent and own bindings
+     * const config = child.resolve('config'); // From parent
+     * const logger = child.resolve('logger'); // From child
+     * ```
+     */
+    createChild() {
+        return new Container(this);
+    }
+    /**
+     * Create a new scope for scoped instances
+     *
+     * @returns A new scope
+     *
+     * @example
+     * ```typescript
+     * const scope = container.createScope();
+     * container.scoped('request', () => new Request());
+     *
+     * const req1 = container.resolve('request'); // Same instance within scope
+     * const req2 = container.resolve('request'); // Same as req1
+     *
+     * await scope.dispose(); // Clean up scoped instances
+     * ```
+     */
+    createScope() {
+        const scope = new Scope();
+        this.currentScope = scope;
+        return scope;
+    }
+    /**
+     * Execute a callback with a temporary scope
+     * Auto-disposes the scope when done (like C# using statement)
+     *
+     * @param callback Function to execute within the scope
+     * @returns The result of the callback
+     *
+     * @example
+     * ```typescript
+     * await container.withScope(async (scope) => {
+     *   const db = container.resolve('dbConnection');
+     *   await db.query('...');
+     *   // Auto-disposed when callback completes
+     * });
+     * ```
+     */
+    async withScope(callback) {
+        const scope = this.createScope();
+        try {
+            return await callback(scope);
+        }
+        finally {
+            await scope.dispose();
+        }
+    }
+    /**
+     * Find the appropriate binding for a given key and context
+     * Searches in current container and parent containers
+     * Uses cached result when possible for performance
+     *
+     * @private
+     * @param key The service key to find
+     * @param context Optional context for contextual binding
+     * @returns The matching binding or undefined
+     */
+    findBinding(key, context) {
+        const realKey = this.aliases.get(key) || key;
+        const cacheKey = context ? `${realKey}::${context}` : realKey;
+        // Check cache first
+        if (this.bindingCache.has(cacheKey)) {
+            return this.bindingCache.get(cacheKey);
+        }
+        // O(1) Map lookup instead of O(n) array filter
+        const bindings = this.bindings.get(realKey);
+        if (bindings && bindings.length > 0) {
+            // Priority:
+            // 1. Binding with context and condition true
+            // 2. Binding without context but condition true
+            // 3. Binding default first
+            const match = bindings.find((b) => b.context === context && (!b.condition || b.condition(this))) ||
+                bindings.find((b) => !b.context && (!b.condition || b.condition(this))) ||
+                bindings[0];
+            // Cache the result only if no conditions (conditions are dynamic)
+            if (match && !match.condition) {
+                this.bindingCache.set(cacheKey, match);
+            }
+            return match;
+        }
+        // Try parent container
+        if (this.parent) {
+            return this.parent.findBinding(key, context);
+        }
+        return undefined;
+    }
+    /**
+     * Resolve a service instance from the container
+     * Handles transient, singleton, scoped, and lazy bindings
+     *
+     * @template T The expected type of the resolved service
+     * @param key The service key to resolve
+     * @param context Optional context for contextual resolution
+     * @returns The resolved service instance
+     * @throws Error if no binding exists for the key
+     * @throws Error if circular dependency is detected
+     *
+     * @example
+     * ```typescript
+     * const logger = container.resolve<Logger>('logger');
+     * const userRepo = container.resolve('UserRepo', 'UserService');
+     * ```
+     */
+    resolve(key, context) {
+        const realKey = this.aliases.get(key) || key;
+        // Circular dependency detection
+        if (this.resolutionStack.includes(realKey)) {
+            const chain = [...this.resolutionStack, realKey].join(' -> ');
+            throw new Error(`Circular dependency detected: ${chain}`);
+        }
+        const prevContext = this.currentContext;
+        this.currentContext = context || key;
+        const binding = this.findBinding(key, this.currentContext);
+        if (!binding) {
+            throw new Error(`No binding found for key: ${realKey}`);
+        }
+        // Add to resolution stack
+        this.resolutionStack.push(realKey);
+        try {
+            // Handle lazy binding
+            if (binding.lazy) {
+                const instance = this.resolveLazy(binding, realKey);
+                return instance;
+            }
+            // Handle different lifecycles
+            switch (binding.lifecycle) {
+                case 'singleton':
+                    return this.resolveSingleton(binding, realKey);
+                case 'scoped':
+                    return this.resolveScoped(binding, realKey);
+                case 'transient':
+                default:
+                    return this.resolveTransient(binding);
+            }
+        }
+        finally {
+            // Remove from resolution stack
+            this.resolutionStack.pop();
+            this.currentContext = prevContext;
+        }
+    }
+    /**
+     * Resolve a transient instance
+     * @private
+     */
+    resolveTransient(binding) {
+        return binding.factory(this);
+    }
+    /**
+     * Resolve a singleton instance
+     * @private
+     */
+    resolveSingleton(binding, cacheKey) {
+        const fullCacheKey = binding.context
+            ? `${cacheKey}::${binding.context}`
+            : cacheKey;
+        if (this.instances.has(fullCacheKey)) {
+            return this.instances.get(fullCacheKey);
+        }
+        const instance = binding.factory(this);
+        this.instances.set(fullCacheKey, instance);
+        return instance;
+    }
+    /**
+     * Resolve a scoped instance
+     * @private
+     */
+    resolveScoped(binding, key) {
+        if (!this.currentScope) {
+            throw new Error(`No active scope for scoped binding: ${key}. Call createScope() first.`);
+        }
+        if (this.currentScope.has(key)) {
+            return this.currentScope.get(key);
+        }
+        const instance = binding.factory(this);
+        this.currentScope.set(key, instance, binding.dispose);
+        return instance;
+    }
+    /**
+     * Resolve a lazy instance
+     * @private
+     */
+    resolveLazy(binding, cacheKey) {
+        const fullCacheKey = `lazy::${cacheKey}`;
+        if (this.instances.has(fullCacheKey)) {
+            return this.instances.get(fullCacheKey);
+        }
+        const lazy = new Lazy(() => binding.factory(this));
+        if (binding.lifecycle === 'singleton') {
+            this.instances.set(fullCacheKey, lazy);
+        }
+        return lazy;
+    }
+    /**
+     * Create a contextual binding (different implementations based on context)
+     * Provides a fluent API for defining context-specific dependencies
+     *
+     * @param context The context identifier (usually a service name)
+     * @returns A fluent API object with needs() method
+     *
+     * @example
+     * ```typescript
+     * // UserService will receive MockUserRepo
+     * container.when('UserService').needs('UserRepo').give(() => new MockUserRepo());
+     *
+     * // OrderService will receive RealUserRepo
+     * container.when('OrderService').needs('UserRepo').give(() => new RealUserRepo());
+     * ```
+     */
+    when(context) {
+        return {
+            needs: (depKey) => ({
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                give: (factory) => {
+                    const existing = this.bindings.get(depKey) || [];
+                    existing.push({
+                        key: depKey,
+                        factory,
+                        lifecycle: 'transient',
+                        context,
+                    });
+                    this.bindings.set(depKey, existing);
+                    this.bindingCache.clear();
+                },
+            }),
+        };
+    }
+    /**
+     * Check if a binding exists for a key
+     *
+     * @param key The service key to check
+     * @returns True if binding exists
+     *
+     * @example
+     * ```typescript
+     * if (container.has('logger')) {
+     *   const logger = container.resolve('logger');
+     * }
+     * ```
+     */
+    has(key) {
+        return this.findBinding(key) !== undefined;
+    }
+    /**
+     * Get all registered service keys
+     *
+     * @returns Array of service keys
+     *
+     * @example
+     * ```typescript
+     * const keys = container.keys();
+     * console.log('Registered services:', keys);
+     * ```
+     */
+    keys() {
+        const ownKeys = Array.from(this.bindings.keys());
+        const parentKeys = this.parent ? this.parent.keys() : [];
+        return [...new Set([...ownKeys, ...parentKeys])];
+    }
+    /**
+     * Reset the container to its initial state
+     * Clears all bindings, instances, aliases, and context
+     * Useful for testing scenarios
+     *
+     * @example
+     * ```typescript
+     * afterEach(() => {
+     *   container.reset();
+     * });
+     * ```
+     */
+    reset() {
+        this.bindings.clear();
+        this.instances.clear();
+        this.aliases.clear();
+        this.bindingCache.clear();
+        this.currentContext = undefined;
+        this.currentScope = undefined;
+        this.resolutionStack = [];
+    }
+    /**
+     * Dispose the container and all its scoped instances
+     */
+    async dispose() {
+        if (this.currentScope) {
+            await this.currentScope.dispose();
+        }
+        this.reset();
+    }
+}
+//# sourceMappingURL=Container.js.map

package/dist/esm/Container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Container.js","sourceRoot":"","sources":["../../src/Container.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IA0BpB;;;OAGG;IACH,YAAY,MAAkB;QA7B9B,mDAAmD;QAC3C,aAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;QAEhD,oCAAoC;QACpC,8DAA8D;QACtD,cAAS,GAAG,IAAI,GAAG,EAAe,CAAC;QAE3C,0CAA0C;QAClC,YAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE5C,6DAA6D;QACrD,iBAAY,GAAG,IAAI,GAAG,EAAmB,CAAC;QAWlD,yDAAyD;QACjD,oBAAe,GAAa,EAAE,CAAC;QAOrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAI,GAAW,EAAE,OAAqB,EAAE,SAAuB;QACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,mBAAmB;IAChD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,SAAS,CAAI,GAAW,EAAE,OAAqB,EAAE,SAAuB;QACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAI,GAAW,EAAE,OAAqB,EAAE,OAAmB;QAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CACF,GAAW,EACX,OAAqB,EACrB,YAAuB,WAAW;QAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,QAAgB,EAAE,WAAmB;QACzC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW;QACT,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,WAAW;QACT,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,SAAS,CAAI,QAA0C;QAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;gBAAS,CAAC;YACT,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACK,WAAW,CAAC,GAAW,EAAE,OAAgB;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAE9D,oBAAoB;QACpB,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;QAED,+CAA+C;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE5C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,YAAY;YACZ,6CAA6C;YAC7C,gDAAgD;YAChD,2BAA2B;YAC3B,MAAM,KAAK,GACT,QAAQ,CAAC,IAAI,CACX,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CACpE;gBACD,QAAQ,CAAC,IAAI,CACX,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CACzD;gBACD,QAAQ,CAAC,CAAC,CAAC,CAAC;YAEd,kEAAkE;YAClE,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;gBAC9B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;YAED,OAAO,KAAK,CAAC;QACf,CAAC;QAED,uBAAuB;QACvB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAI,GAAW,EAAE,OAAgB;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAE7C,gCAAgC;QAChC,IAAI,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC;QACxC,IAAI,CAAC,cAAc,GAAG,OAAO,IAAI,GAAG,CAAC;QAErC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAE3D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,0BAA0B;QAC1B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEnC,IAAI,CAAC;YACH,sBAAsB;YACtB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACpD,OAAO,QAAa,CAAC;YACvB,CAAC;YAED,8BAA8B;YAC9B,QAAQ,OAAO,CAAC,SAAS,EAAE,CAAC;gBAC1B,KAAK,WAAW;oBACd,OAAO,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACjD,KAAK,QAAQ;oBACX,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,KAAK,WAAW,CAAC;gBACjB;oBACE,OAAO,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,+BAA+B;YAC/B,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,CAAC;YAC3B,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,gBAAgB,CAAI,OAAmB;QAC7C,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACK,gBAAgB,CAAI,OAAmB,EAAE,QAAgB;QAC/D,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO;YAClC,CAAC,CAAC,GAAG,QAAQ,KAAK,OAAO,CAAC,OAAO,EAAE;YACnC,CAAC,CAAC,QAAQ,CAAC;QAEb,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;OAGG;IACK,aAAa,CAAI,OAAmB,EAAE,GAAW;QACvD,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,uCAAuC,GAAG,6BAA6B,CACxE,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACtD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;OAGG;IACK,WAAW,CAAI,OAAmB,EAAE,QAAgB;QAC1D,MAAM,YAAY,GAAG,SAAS,QAAQ,EAAE,CAAC;QAEzC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAEnD,IAAI,OAAO,CAAC,SAAS,KAAK,WAAW,EAAE,CAAC;YACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,OAAe;QAClB,OAAO;YACL,KAAK,EAAE,CAAC,MAAc,EAAE,EAAE,CAAC,CAAC;gBAC1B,8DAA8D;gBAC9D,IAAI,EAAE,CAAC,OAAuB,EAAE,EAAE;oBAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;oBACjD,QAAQ,CAAC,IAAI,CAAC;wBACZ,GAAG,EAAE,MAAM;wBACX,OAAO;wBACP,SAAS,EAAE,WAAW;wBACtB,OAAO;qBACR,CAAC,CAAC;oBACH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;oBACpC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;gBAC5B,CAAC;aACF,CAAC;SACH,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;OAUG;IACH,IAAI;QACF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;CACF"}

package/dist/esm/Lazy.js

@@ -0,0 +1,42 @@
+/**
+ * Lazy wrapper for deferred initialization
+ *
+ * @module Lazy
+ */
+/**
+ * Lazy wrapper for deferred initialization
+ * Delays the creation of an instance until it's actually accessed
+ *
+ * @template T The type of the lazy value
+ *
+ * @example
+ * ```typescript
+ * const lazy = new Lazy(() => new ExpensiveService());
+ * console.log(lazy.isInitialized); // false
+ * const service = lazy.value; // NOW it's created
+ * console.log(lazy.isInitialized); // true
+ * ```
+ */
+export class Lazy {
+    constructor(factory) {
+        this.factory = factory;
+        this._initialized = false;
+    }
+    /**
+     * Get the lazy value, initializing it if necessary
+     */
+    get value() {
+        if (!this._initialized) {
+            this._value = this.factory();
+            this._initialized = true;
+        }
+        return this._value;
+    }
+    /**
+     * Check if the lazy value has been initialized
+     */
+    get isInitialized() {
+        return this._initialized;
+    }
+}
+//# sourceMappingURL=Lazy.js.map

package/dist/esm/Lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lazy.js","sourceRoot":"","sources":["../../src/Lazy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,IAAI;IAIf,YAAoB,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;QAF5B,iBAAY,GAAG,KAAK,CAAC;IAEU,CAAC;IAExC;;OAEG;IACH,IAAI,KAAK;QACP,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC,MAAO,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/esm/Scope.js

@@ -0,0 +1,89 @@
+/**
+ * Scope management for scoped instances
+ *
+ * @module Scope
+ */
+/**
+ * Scope class for managing scoped instances
+ * A scope contains instances that live for a specific duration (e.g., per HTTP request)
+ *
+ * @example
+ * ```typescript
+ * const scope = container.createScope();
+ * const conn = container.resolve('dbConnection'); // Scoped instance
+ * await scope.dispose(); // Cleanup all scoped resources
+ * ```
+ */
+export class Scope {
+    constructor() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.instances = new Map();
+        this.disposables = [];
+    }
+    /**
+     * Get an instance from this scope
+     * @param key The service key
+     * @returns The instance or undefined
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get(key) {
+        return this.instances.get(key);
+    }
+    /**
+     * Set an instance in this scope with optional cleanup
+     * Auto-detects IDisposable instances
+     *
+     * @param key The service key
+     * @param value The instance to store
+     * @param dispose Optional disposal function
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    set(key, value, dispose) {
+        this.instances.set(key, value);
+        // Auto-detect IDisposable
+        if (!dispose && this.isDisposable(value)) {
+            dispose = () => value.dispose();
+        }
+        if (dispose) {
+            this.disposables.push(dispose);
+        }
+    }
+    /**
+     * Check if instance exists in scope
+     * @param key The service key
+     * @returns True if the instance exists
+     */
+    has(key) {
+        return this.instances.has(key);
+    }
+    /**
+     * Check if value implements IDisposable interface
+     * @private
+     * @param value The value to check
+     * @returns True if the value is disposable
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    isDisposable(value) {
+        return (value !== null &&
+            value !== undefined &&
+            typeof value === 'object' &&
+            typeof value.dispose === 'function');
+    }
+    /**
+     * Dispose all instances in this scope
+     * Calls all registered disposal functions and clears the scope
+     *
+     * @example
+     * ```typescript
+     * await scope.dispose();
+     * ```
+     */
+    async dispose() {
+        for (const disposeFn of this.disposables) {
+            await disposeFn();
+        }
+        this.instances.clear();
+        this.disposables = [];
+    }
+}
+//# sourceMappingURL=Scope.js.map

package/dist/esm/Scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scope.js","sourceRoot":"","sources":["../../src/Scope.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,KAAK;IAAlB;QACE,8DAA8D;QACtD,cAAS,GAAqB,IAAI,GAAG,EAAE,CAAC;QACxC,gBAAW,GAAgB,EAAE,CAAC;IA2ExC,CAAC;IAzEC;;;;OAIG;IACH,8DAA8D;IAC9D,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;OAOG;IACH,8DAA8D;IAC9D,GAAG,CAAC,GAAW,EAAE,KAAU,EAAE,OAAmB;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE/B,0BAA0B;QAC1B,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,8DAA8D;IACtD,YAAY,CAAC,KAAU;QAC7B,OAAO,CACL,KAAK,KAAK,IAAI;YACd,KAAK,KAAK,SAAS;YACnB,OAAO,KAAK,KAAK,QAAQ;YACzB,OAAO,KAAK,CAAC,OAAO,KAAK,UAAU,CACpC,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO;QACX,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACzC,MAAM,SAAS,EAAE,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/esm/index.js

@@ -0,0 +1,34 @@
+/**
+ * Treasure Chest - A lightweight TypeScript dependency injection container
+ *
+ * @module treasure-chest
+ * @author Kent Phung
+ * @license DIB
+ *
+ * Features:
+ *  - Transient, Singleton, and Scoped bindings
+ *  - Conditional binding based on runtime conditions
+ *  - Contextual binding for different implementations per context
+ *  - Alias support for service keys
+ *  - Nested dependency resolution
+ *  - Lazy loading with deferred initialization
+ *  - Child containers with hierarchy
+ *  - Circular dependency detection
+ *  - High-performance Map-based storage (v1.2.0)
+ *  - Auto-dispose for IDisposable instances (v1.2.0)
+ *  - Modular architecture (v1.2.0)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@khapu2906/treasure-chest';
+ *
+ * const container = new Container();
+ * container.bind('logger', () => new Logger());
+ * const logger = container.resolve('logger');
+ * ```
+ */
+// Export main classes
+export { Container } from './Container';
+export { Lazy } from './Lazy';
+export { Scope } from './Scope';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,sBAAsB;AACtB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC"}

package/dist/esm/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for Treasure Chest DI Container
+ *
+ * @module types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}