decorator-dependency-injection 1.0.3 → 1.0.4

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/decorator-dependency-injection.svg)](http://badge.fury.io/js/decorator-dependency-injection)
 [![Build Status](https://github.com/mallocator/decorator-dependency-injection/actions/workflows/release.yml/badge.svg)](https://github.com/mallocator/decorator-dependency-injection/actions/workflows/release.yml)
+[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen)](https://github.com/mallocator/decorator-dependency-injection)
 
 ## Description
 
@@ -61,9 +62,9 @@ The ```@Singleton``` decorator is used to inject a single instance of a dependen
 want to share the same instance of a class across multiple classes.
 
 ```javascript
-import {Singleton} from 'decorator-dependency-injection';
+import {Singleton, Inject} from 'decorator-dependency-injection';
 
-@Singleton
+@Singleton()
 class Dependency {
 }
 
@@ -78,9 +79,9 @@ The ```@Factory``` decorator is used to inject a new instance of a dependency in
 This is useful when you want to create a new instance of a class each time it is injected.
 
 ```javascript
-import {Factory} from 'decorator-dependency-injection';
+import {Factory, Inject} from 'decorator-dependency-injection';
 
-@Factory
+@Factory()
 class Dependency {
 }
 
@@ -89,23 +90,23 @@ class Consumer {
 }
 ```
 
-### LazyInject
+### InjectLazy
 
 ```@Inject``` annotated properties are evaluated during instance initialization. That means that all properties should
 be accessible in the constructor. That also means that we're creating an instance no matter if you access the property
-or not. If you want to only create an instance when you access the property, you can use the ```@LazyInject```
+or not. If you want to only create an instance when you access the property, you can use the ```@InjectLazy```
 decorator. This will create the instance only when the property is accessed for the first time. Note that this also
-works from the constructor, same as the regular ```@Inject```.
+works from the constructor, same as the regular ```@Inject```.  
 
 ```javascript
-import {LazyInject} from 'decorator-dependency-injection';
+import {Singleton, InjectLazy} from 'decorator-dependency-injection';
 
-@Singleton
+@Singleton()
 class Dependency {
 }
 
 class Consumer {
-  @LazyInject(Dependency) dependency // creates an instance only when the property is accessed
+  @InjectLazy(Dependency) dependency // creates an instance only when the property is accessed
 }
 ```
 
@@ -138,9 +139,9 @@ will only be passed to the dependency the first time it is created.
 You can mock dependencies by using the ```@Mock``` decorator with a function that returns the mock dependency.
 
 ```javascript
-import {Factory, Inject, Mock} from 'decorator-dependency-injection'
+import {Factory, Inject, Mock, resetMock} from 'decorator-dependency-injection'
 
-@Factory
+@Factory()
 class Dependency {
   method() {
     return 'real'
@@ -177,18 +178,29 @@ The `resetMock` utility function allows you to remove any active mock for a depe
 implementation. This is useful for cleaning up after tests or switching between real and mock dependencies.
 
 ```javascript
-import {resetMock} from 'decorator-dependency-injection';
+import {resetMock, resetMocks} from 'decorator-dependency-injection';
 
 resetMock(Dependency); // Restores the original Dependency implementation
+resetMocks(); // Restores all mocked dependencies
+```
+
+### Clearing the Container
+
+For complete test isolation, you can clear all registered instances from the container:
+
+```javascript
+import {clearContainer} from 'decorator-dependency-injection';
+
+clearContainer(); // Removes all registered singletons, factories, and mocks
 ```
 
 You can also use the ```@Mock``` decorator as a proxy instead of a full mock. Any method calls not implemented in the
 mock will be passed to the real dependency.
 
 ```javascript
-import {Factory, Inject, Mock} from 'decorator-dependency-injection'
+import {Factory, Inject, Mock, resetMock} from 'decorator-dependency-injection'
 
-@Factory
+@Factory()
 class Dependency {
   method() {
     return 'real'
@@ -225,6 +237,45 @@ const consumer = new Consumer()  // prints 'real other'
 
 For more examples, see the tests in the ```test``` directory.
 
+## Advanced Usage
+
+### Using Isolated Containers
+
+For advanced scenarios like parallel test execution or module isolation, you can create separate containers:
+
+```javascript
+import {Container} from 'decorator-dependency-injection';
+
+const container1 = new Container();
+const container2 = new Container();
+
+class MyService {}
+
+// Register the same class in different containers
+container1.registerSingleton(MyService);
+container2.registerSingleton(MyService);
+
+// Each container maintains its own singleton instance
+const ctx1 = container1.getContext(MyService);
+const ctx2 = container2.getContext(MyService);
+
+const instance1 = container1.getInstance(ctx1, []);
+const instance2 = container2.getInstance(ctx2, []);
+
+console.log(instance1 === instance2); // false - different containers
+```
+
+### Accessing the Default Container
+
+You can access the default global container for programmatic registration:
+
+```javascript
+import {getContainer} from 'decorator-dependency-injection';
+
+const container = getContainer();
+console.log(container.has(MyService)); // Check if a class is registered
+```
+
 ## Running the tests
 
 To run the tests, run the following command in the project root.
@@ -238,4 +289,5 @@ npm test
 - 1.0.0 - Initial release
 - 1.0.1 - Automated release with GitHub Actions
 - 1.0.2 - Added proxy option to @Mock decorator
-- 1.0.3 - Added @LazyInject decorator
+- 1.0.3 - Added @InjectLazy decorator
+- 1.0.4 - Added Container abstraction, clearContainer(), TypeScript definitions, improved proxy support

package/eslint.config.js

@@ -0,0 +1,73 @@
+import { defineConfig } from "eslint/config";
+import js from "@eslint/js";
+import babelParser from "@babel/eslint-parser";
+
+export default defineConfig([
+  // Recommended base config
+  js.configs.recommended,
+
+  // Global ignores
+  {
+    ignores: ["node_modules/**", "coverage/**", "docs/**", ".history/**"]
+  },
+
+  // Source files configuration
+  {
+    name: "source-files",
+    files: ["index.js", "src/**/*.js"],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: true,
+        babelOptions: {
+          configFile: "./babel.config.json"
+        }
+      },
+      globals: {
+        console: "readonly",
+        process: "readonly"
+      }
+    },
+    rules: {
+      "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+      "prefer-const": "error",
+      "no-var": "error",
+      "eqeqeq": ["error", "always"],
+      "no-throw-literal": "error"
+    }
+  },
+
+  // Test files with relaxed rules and Jest globals
+  {
+    name: "test-files",
+    files: ["test/**/*.js"],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: true,
+        babelOptions: {
+          configFile: "./babel.config.json"
+        }
+      },
+      globals: {
+        console: "readonly",
+        process: "readonly",
+        describe: "readonly",
+        it: "readonly",
+        expect: "readonly",
+        beforeEach: "readonly",
+        afterEach: "readonly",
+        jest: "readonly",
+        fail: "readonly"
+      }
+    },
+    rules: {
+      // In tests, decorated classes are used by the decorator system, not directly
+      "no-unused-vars": ["warn", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }]
+    }
+  }
+]);

package/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Type definitions for decorator-dependency-injection
+ */
+
+/**
+ * Context for registered instances in the container
+ */
+export interface InstanceContext {
+  /** The type of registration */
+  type: 'singleton' | 'factory'
+  /** The current class constructor (may be a mock) */
+  clazz: new (...args: any[]) => any
+  /** The original class constructor if mocked */
+  originalClazz?: new (...args: any[]) => any
+  /** The cached singleton instance */
+  instance?: any
+  /** Whether to use proxy mocking */
+  proxy?: boolean
+}
+
+/**
+ * A dependency injection container that manages singleton and factory instances.
+ */
+export declare class Container {
+  /**
+   * Register a class as a singleton.
+   */
+  registerSingleton(clazz: new (...args: any[]) => any, name?: string): void
+
+  /**
+   * Register a class as a factory.
+   */
+  registerFactory(clazz: new (...args: any[]) => any, name?: string): void
+
+  /**
+   * Get the context for a given class or name.
+   */
+  getContext(clazzOrName: string | (new (...args: any[]) => any)): InstanceContext
+
+  /**
+   * Check if a class or name is registered.
+   */
+  has(clazzOrName: string | (new (...args: any[]) => any)): boolean
+
+  /**
+   * Get or create an instance based on the context.
+   */
+  getInstance(instanceContext: InstanceContext, params: any[]): any
+
+  /**
+   * Register a mock for an existing class.
+   */
+  registerMock(
+    targetClazzOrName: string | (new (...args: any[]) => any),
+    mockClazz: new (...args: any[]) => any,
+    useProxy?: boolean
+  ): void
+
+  /**
+   * Reset a specific mock to its original class.
+   */
+  resetMock(clazzOrName: string | (new (...args: any[]) => any)): void
+
+  /**
+   * Reset all mocks to their original classes.
+   */
+  resetAllMocks(): void
+
+  /**
+   * Clear all registered instances and mocks.
+   */
+  clear(): void
+}
+
+/**
+ * Register a class as a singleton.
+ * @param name Optional name to register the singleton under
+ */
+export declare function Singleton(name?: string): ClassDecorator
+
+/**
+ * Register a class as a factory.
+ * @param name Optional name to register the factory under
+ */
+export declare function Factory(name?: string): ClassDecorator
+
+/**
+ * Inject a singleton or factory instance into a class field.
+ * @param clazzOrName The class or name to inject
+ * @param params Optional parameters to pass to the constructor
+ */
+export declare function Inject<T>(
+  clazzOrName: string | (new (...args: any[]) => T),
+  ...params: any[]
+): PropertyDecorator
+
+/**
+ * Inject a singleton or factory instance lazily into a class field.
+ * The instance is created on first access.
+ * @param clazzOrName The class or name to inject
+ * @param params Optional parameters to pass to the constructor
+ */
+export declare function InjectLazy<T>(
+  clazzOrName: string | (new (...args: any[]) => T),
+  ...params: any[]
+): PropertyDecorator
+
+/**
+ * Mark a class as a mock for another class.
+ * @param mockedClazzOrName The class or name to mock
+ * @param proxy If true, unmocked methods delegate to the original
+ */
+export declare function Mock(
+  mockedClazzOrName: string | (new (...args: any[]) => any),
+  proxy?: boolean
+): ClassDecorator
+
+/**
+ * Reset all mocks to their original classes.
+ */
+export declare function resetMocks(): void
+
+/**
+ * Reset a specific mock to its original class.
+ * @param clazzOrName The class or name to reset
+ */
+export declare function resetMock(clazzOrName: string | (new (...args: any[]) => any)): void
+
+/**
+ * Clear all registered instances and mocks from the container.
+ */
+export declare function clearContainer(): void
+
+/**
+ * Get the default container instance.
+ */
+export declare function getContainer(): Container
+
+/**
+ * Create a proxy that delegates to the mock first, then falls back to the original.
+ * This is an internal utility but exported for advanced use cases.
+ *
+ * @param mock The mock instance
+ * @param original The original instance to fall back to
+ */
+export declare function createProxy<T extends object>(mock: T, original: T): T

package/index.js

@@ -1,22 +1,22 @@
 /**
- * @typedef {Object} InstanceContext
- * @property {'singleton'|'factory'} type - The type of the instance.
- * @property {Function} clazz - The class constructor for the instance.
- * @property {Function} [originalClazz] - The original class if this is a mock.
- * @property {Object} [instance] - The singleton instance, if created.
- * @property {Object} [originalInstance] - The original instance if this is a mock.
- * @property {boolean} [proxy=false] - If true, the mock will proxy to the original class for undefined methods/properties.
+ * Decorator Dependency Injection
+ *
+ * A simple library for dependency injection using TC39 Stage 3 decorators.
+ *
+ * @module decorator-dependency-injection
  */
 
-/** @type {Map<string|Class, InstanceContext>} */
-const instances = new Map()
+import {Container} from './src/Container.js'
+
+/** @type {Container} The default global container */
+const defaultContainer = new Container()
 
 /**
  * Register a class as a singleton. If a name is provided, it will be used as the key in the singleton map.
  * Singleton instances only ever have one instance created via the @Inject decorator.
  *
  * @param {string} [name] The name of the singleton. If not provided, the class will be used as the key.
- * @return {(function(Function, {kind: string}): void)}
+ * @returns {(function(Function, {kind: string}): void)}
  * @example @Singleton() class MySingleton {}
  * @example @Singleton('customName') class MySingleton {}
  * @throws {Error} If the injection target is not a class
@@ -31,11 +31,7 @@ export function Singleton(name) {
     if (typeof clazz !== 'function' || !clazz.prototype) {
       throw new Error('Target must be a class constructor')
     }
-    const key = name ?? clazz
-    if (instances.has(key)) {
-      throw new Error('A different class is already registered under this name. This may be possibly a circular dependency. Try using @InjectLazy')
-    }
-    instances.set(key, {clazz, type: 'singleton'})
+    defaultContainer.registerSingleton(clazz, name)
   }
 }
 
@@ -44,7 +40,7 @@ export function Singleton(name) {
  * Factory instances are created via the @Inject decorator. Each call to the factory will create a new instance.
  *
  * @param {string} [name] The name of the factory. If not provided, the class will be used as the key.
- * @return {(function(Function, {kind: string}): void)}
+ * @returns {(function(Function, {kind: string}): void)}
  * @example @Factory() class MyFactory {}
  * @example @Factory('customName') class MyFactory {}
  * @throws {Error} If the injection target is not a class
@@ -59,11 +55,7 @@ export function Factory(name) {
     if (typeof clazz !== 'function' || !clazz.prototype) {
       throw new Error('Target must be a class constructor')
     }
-    const key = name ?? clazz
-    if (instances.has(key)) {
-      throw new Error('A different class is already registered under this name, This may be possibly a circular dependency. Try using @InjectLazy')
-    }
-    instances.set(key, {clazz, type: 'factory'})
+    defaultContainer.registerFactory(clazz, name)
   }
 }
 
@@ -71,16 +63,16 @@ export function Factory(name) {
  * Inject a singleton or factory instance into a class field. You can also provide parameters to the constructor.
  * If the instance is a singleton, it will only be created once with the first set of parameters it encounters.
  *
- * @param {string|Class} clazzOrName The singleton or factory class or name
- * @param {*} params Parameters to pass to the constructor. Recommended to use only with factories.
- * @return {(function(*, {kind: string, name: string}): void)}
+ * @param {string|Function} clazzOrName The singleton or factory class or name
+ * @param {...*} params Parameters to pass to the constructor. Recommended to use only with factories.
+ * @returns {(function(*, {kind: string, name: string}): function(): Object)}
  * @example @Inject(MySingleton) mySingleton
  * @example @Inject("myCustomName") myFactory
  * @throws {Error} If the injection target is not a field
  * @throws {Error} If the injected field is assigned a value
  */
 export function Inject(clazzOrName, ...params) {
-  return function (initialValue, context) {
+  return function (_, context) {
     if (context.kind !== 'field') {
       throw new Error('Invalid injection target')
     }
@@ -88,8 +80,8 @@ export function Inject(clazzOrName, ...params) {
       if (initialValue) {
         throw new Error('Cannot assign value to injected field')
       }
-      const instanceContext = getContext(clazzOrName)
-      return getInjectedInstance(instanceContext, params)
+      const instanceContext = defaultContainer.getContext(clazzOrName)
+      return defaultContainer.getInstance(instanceContext, params)
     }
   }
 }
@@ -97,9 +89,10 @@ export function Inject(clazzOrName, ...params) {
 /**
  * Inject a singleton or factory instance lazily into a class field. You can also provide parameters to the constructor.
  * If the instance is a singleton, it will only be created once with the first set of parameters it encounters.
- * @param {string|Class} clazzOrName The singleton or factory class or name
- * @param {*} params Parameters to pass to the constructor. Recommended to use only with factories.
- * @return {(function(*, {kind: string, name: string, addInitializer: Function}): void)}
+ *
+ * @param {string|Function} clazzOrName The singleton or factory class or name
+ * @param {...*} params Parameters to pass to the constructor. Recommended to use only with factories.
+ * @returns {(function(*, {kind: string, name: string, addInitializer: Function}): void)}
  * @example @InjectLazy(MySingleton) mySingleton
  * @example @InjectLazy("myCustomName") myFactory
  * @throws {Error} If the injection target is not a field
@@ -107,7 +100,7 @@ export function Inject(clazzOrName, ...params) {
  */
 export function InjectLazy(clazzOrName, ...params) {
   const cache = new WeakMap()
-  return (initialValue, context) => {
+  return (_, context) => {
     if (context.kind !== 'field') {
       throw new Error('Invalid injection target')
     }
@@ -115,12 +108,15 @@ export function InjectLazy(clazzOrName, ...params) {
       Object.defineProperty(this, context.name, {
         get() {
           if (!cache.has(this)) {
-            const instanceContext = getContext(clazzOrName)
-            const value = getInjectedInstance(instanceContext, params)
+            const instanceContext = defaultContainer.getContext(clazzOrName)
+            const value = defaultContainer.getInstance(instanceContext, params)
             cache.set(this, value)
           }
           return cache.get(this)
         },
+        set() {
+          throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
+        },
         configurable: true,
         enumerable: true
       })
@@ -128,30 +124,15 @@ export function InjectLazy(clazzOrName, ...params) {
   }
 }
 
-/**
- * Get a proxy for the mock instance. This allows the mock to call methods on the original class if they are not defined in the mock.
- * @param {Object} mock The mock instance
- * @param {Object} original The original class instance
- * @return {*|object} The proxy instance
- */
-function getProxy(mock, original) {
-  return new Proxy(mock, {
-    get(target, prop, receiver) {
-      if (prop in target) {
-        return Reflect.get(target, prop, receiver)
-      }
-      return Reflect.get(original, prop, receiver)
-    }
-  })
-}
-
 /**
  * Mark a class as a mock. This will replace the class with a mock instance when injected.
- * @param {string|Class} mockedClazzOrName The singleton or factory class or name to be mocked
- * @param {boolean} [proxy=false] If true, the mock will be a proxy to the original class. Any methods not defined in the mock will be called on the original class.
- * @return {(function(Function, {kind: string}): void)}
+ *
+ * @param {string|Function} mockedClazzOrName The singleton or factory class or name to be mocked
+ * @param {boolean} [proxy=false] If true, the mock will proxy to the original class.
+ *                                Any methods not defined in the mock will be called on the original class.
+ * @returns {(function(Function, {kind: string}): void)}
  * @example @Mock(MySingleton) class MyMock {}
- * @example @Mock("myCustomName") class MyMock {}
+ * @example @Mock("myCustomName", true) class MyMock {}
  * @throws {Error} If the injection target is not a class
  * @throws {Error} If the injection source is not found
  */
@@ -160,32 +141,7 @@ export function Mock(mockedClazzOrName, proxy = false) {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
-    const instanceContext = getContext(mockedClazzOrName)
-    if (instanceContext.originalClazz) {
-      throw new Error('Mock already defined, reset before mocking again')
-    }
-    instanceContext.originalClazz = instanceContext.clazz
-    instanceContext.proxy = proxy
-    instanceContext.clazz = clazz
-  }
-}
-
-/**
- * Internal: Get the context for a given class or name.
- *
- * @param {string|Class} mockedClazzOrName - The class or name to look up.
- * @returns {InstanceContext}
- * @throws {Error} If the context is not found.
- */
-function getContext(mockedClazzOrName) {
-  if (instances.has(mockedClazzOrName)) {
-    return instances.get(mockedClazzOrName)
-  } else {
-    const available = Array.from(instances.keys()).map(k => typeof k === 'string' ? k : k.name).join(', ')
-    throw new Error(
-      `Cannot find injection source for "${mockedClazzOrName?.name || mockedClazzOrName}". ` +
-      `Available: [${available}]`
-    )
+    defaultContainer.registerMock(mockedClazzOrName, clazz, proxy)
   }
 }
 
@@ -193,64 +149,38 @@ function getContext(mockedClazzOrName) {
  * Reset all mocks to their original classes.
  */
 export function resetMocks() {
-  for (const instanceContext of instances.values()) {
-    restoreOriginal(instanceContext)
-  }
+  defaultContainer.resetAllMocks()
 }
 
 /**
  * Reset a specific mock to its original class.
- * @param {string|Class} clazzOrName The singleton or factory class or name to reset
+ *
+ * @param {string|Function} clazzOrName The singleton or factory class or name to reset
  */
 export function resetMock(clazzOrName) {
-  restoreOriginal(getContext(clazzOrName))
+  defaultContainer.resetMock(clazzOrName)
 }
 
 /**
- * Internal function to reset an instance context to its original.
- * @param {InstanceContext} instanceContext The instance context to reset
- * @private
+ * Clear all registered instances and mocks from the container.
+ * Useful for complete test isolation between test suites.
  */
-function restoreOriginal(instanceContext) {
-  if (!instanceContext) {
-    throw new Error('Cannot find injection source with the provided name')
-  }
-  if (instanceContext.originalClazz) {
-    instanceContext.clazz = instanceContext.originalClazz
-    delete instanceContext.instance
-    delete instanceContext.originalClazz
-    delete instanceContext.originalInstance
-  }
+export function clearContainer() {
+  defaultContainer.clear()
 }
 
 /**
- * Get the injected instance based on the context and parameters.
- * @param {InstanceContext} instanceContext The instance context
- * @param {Array} params The parameters to pass to the constructor
- * @return {Object} The injected instance
+ * Get the default container instance.
+ * Useful for advanced use cases or testing the container itself.
+ *
+ * @returns {Container} The default container
  */
-function getInjectedInstance(instanceContext, params) {
-  if (instanceContext.type === 'singleton' && !instanceContext.originalClazz && instanceContext.instance) {
-    return instanceContext.instance
-  }
-  let instance
-  try {
-    instance = new instanceContext.clazz(...params)
-  } catch (err) {
-    if (err instanceof RangeError) {
-      throw new Error(
-        `Circular dependency detected for ${instanceContext.clazz.name || instanceContext.clazz}. ` +
-        `Use @InjectLazy to break the cycle.`
-      )
-    }
-    throw err
-  }
-  if (instanceContext.proxy && instanceContext.originalClazz) {
-    const originalInstance = new instanceContext.originalClazz(...params)
-    instance = getProxy(instance, originalInstance)
-  }
-  if (instanceContext.type === 'singleton') {
-    instanceContext.instance = instance
-  }
-  return instance
+export function getContainer() {
+  return defaultContainer
 }
+
+// Export Container class for advanced use cases (e.g., isolated containers)
+export {Container}
+
+// Export createProxy for advanced proxy use cases
+export {createProxy} from './src/proxy.js'