decorator-dependency-injection 1.0.2 → 1.0.4

package/index.js

@@ -1,37 +1,37 @@
 /**
- * @typedef {Object} InstanceContext
- * @property {string} type The type of the instance, either 'singleton' or 'factory'
- * @property {Class} clazz The class of the instance
- * @property {Class} [originalClazz] The original class if it is a mock
- * @property {Object} [instance] The instance if it is a singleton
- * @property {Object} [originalInstance] The original instance if it is a mock
- * @property {boolean} [proxy=false] If true, the mock if the injection instance will be a proxy to the original class
+ * 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(*, *): 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
- * @throws {Error} If a singleton with the same name is already defined
- * @throws {Error} If a factory with the same name is already defined
+ * @throws {Error} If a singleton or factory with the same name is already defined
+ * @throws {Error} If the target is not a class constructor
  */
 export function Singleton(name) {
   return function (clazz, context) {
-    if (context.kind !== "class") {
+    if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
-    if (instances.has(name ?? clazz)) {
-      throw new Error('Instance with that name or class already instantiated')
+    if (typeof clazz !== 'function' || !clazz.prototype) {
+      throw new Error('Target must be a class constructor')
     }
-    instances.set(name ?? clazz, { clazz, type: 'singleton' })
+    defaultContainer.registerSingleton(clazz, name)
   }
 }
 
@@ -40,22 +40,22 @@ 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(*, *): 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
- * @throws {Error} If a factory with the same name is already defined
- * @throws {Error} If a singleton with the same name is already defined
+ * @throws {Error} If a factory or singleton with the same name is already defined
+ * @throws {Error} If the target is not a class constructor
  */
 export function Factory(name) {
   return function (clazz, context) {
-    if (context.kind !== "class") {
+    if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
-    if (instances.has(name ?? clazz)) {
-      throw new Error('Instance with that name or class already instantiated')
+    if (typeof clazz !== 'function' || !clazz.prototype) {
+      throw new Error('Target must be a class constructor')
     }
-    instances.set(name ?? clazz, { clazz, type: 'factory' })
+    defaultContainer.registerFactory(clazz, name)
   }
 }
 
@@ -63,95 +63,85 @@ 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(*): 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) {
-    if (context.kind === "field") {
-      return function(initialValue) {
-        if (initialValue) {
-          throw new Error('Cannot assign value to injected field')
-        }
-        const instanceContext = getContext(clazzOrName)
-
-        if (instanceContext.instance) {
-          return instanceContext.instance
-        }
-
-        const instance = new instanceContext.clazz(...params)
-
-        if (instanceContext.type === 'singleton') {
-          if (instanceContext.originalClazz && instanceContext.proxy) {
-            instanceContext.instance = getProxy(instance, new instanceContext.originalClazz(...params))
-          } else {
-            instanceContext.instance = instance
-          }
-          return instanceContext.instance
-        }
-
-        if (instanceContext.type === 'factory') {
-          if (instanceContext.originalClazz && instanceContext.proxy) {
-            return getProxy(instance, new instanceContext.originalClazz(...params))
-          } else {
-            return instance
-          }
-        }
-
-        throw new Error('Unexpected injection type')
-      }
-    } else {
+  return function (_, context) {
+    if (context.kind !== 'field') {
       throw new Error('Invalid injection target')
     }
+    return function (initialValue) {
+      if (initialValue) {
+        throw new Error('Cannot assign value to injected field')
+      }
+      const instanceContext = defaultContainer.getContext(clazzOrName)
+      return defaultContainer.getInstance(instanceContext, params)
+    }
   }
 }
 
-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)
+/**
+ * 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|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
+ * @throws {Error} If the injected field is assigned a value
+ */
+export function InjectLazy(clazzOrName, ...params) {
+  const cache = new WeakMap()
+  return (_, context) => {
+    if (context.kind !== 'field') {
+      throw new Error('Invalid injection target')
     }
-  })
+    context.addInitializer(function () {
+      Object.defineProperty(this, context.name, {
+        get() {
+          if (!cache.has(this)) {
+            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
+      })
+    })
+  }
 }
 
 /**
  * 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(*, *): 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
  */
 export function Mock(mockedClazzOrName, proxy = false) {
-  return function(clazz, context) {
-    if (context.kind !== "class") {
+  return function (clazz, context) {
+    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
-  }
-}
-
-function getContext(mockedClazzOrName) {
-  if (instances.has(mockedClazzOrName)) {
-    return instances.get(mockedClazzOrName)
-  } else {
-    throw new Error('Cannot find injection source with the provided name')
+    defaultContainer.registerMock(mockedClazzOrName, clazz, proxy)
   }
 }
 
@@ -159,32 +149,38 @@ function getContext(mockedClazzOrName) {
  * Reset all mocks to their original classes.
  */
 export function resetMocks() {
-  for (const instanceContext of instances.values()) {
-    reset(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) {
-  reset(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 reset(instanceContext) {
-  if (!instanceContext) {
-    throw new Error('Cannot find injection source with the provided name')
-  }
-  if (instanceContext.originalClazz) {
-    instanceContext.clazz = instanceContext.originalClazz
-    instanceContext.instance = instanceContext.originalInstance
-    delete instanceContext.originalClazz
-    delete instanceContext.originalInstance
-  }
+export function clearContainer() {
+  defaultContainer.clear()
+}
+
+/**
+ * Get the default container instance.
+ * Useful for advanced use cases or testing the container itself.
+ *
+ * @returns {Container} The default container
+ */
+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'

package/package.json

@@ -1,34 +1,73 @@
 {
   "name": "decorator-dependency-injection",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A simple library for dependency injection using decorators",
   "author": "Ravi Gairola <mallox@pyxzl.net>",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mallocator/decorator-dependency-injection.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mallocator/decorator-dependency-injection/issues"
+  },
+  "homepage": "https://github.com/mallocator/decorator-dependency-injection#readme",
   "keywords": [
     "dependency-injection",
     "di",
     "decorators",
-    "mocking"
+    "mocking",
+    "singleton",
+    "factory"
   ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "main": "index.js",
+  "types": "index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
   "scripts": {
     "start": "babel-node index.js",
-    "test": "jest"
+    "test": "jest --no-watchman",
+    "test:coverage": "jest --no-watchman --coverage",
+    "typecheck": "tsc test/types.check.ts --noEmit --esModuleInterop --skipLibCheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "jest": {
     "transform": {
       "^.+\\.js$": "babel-jest"
-    }
+    },
+    "coverageThreshold": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    },
+    "collectCoverageFrom": [
+      "index.js",
+      "src/**/*.js"
+    ]
   },
   "devDependencies": {
     "@babel/cli": "^7.26.4",
     "@babel/core": "^7.26.9",
+    "@babel/eslint-parser": "^7.28.6",
     "@babel/plugin-proposal-decorators": "^7.25.9",
-    "@babel/polyfill": "^7.12.1",
     "@babel/preset-env": "^7.26.9",
     "@babel/register": "^7.25.9",
+    "@eslint/js": "^9.39.2",
     "@types/jest": "^29.5.14",
-    "jest": "^29.7.0"
+    "eslint": "^9.39.2",
+    "jest": "^29.7.0",
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/Container.js

@@ -0,0 +1,184 @@
+/**
+ * @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.
+ */
+
+import {createProxy} from './proxy.js'
+
+/**
+ * A dependency injection container that manages singleton and factory instances.
+ * Supports mocking for testing purposes.
+ */
+export class Container {
+  /** @type {Map<string|Function, InstanceContext>} */
+  #instances = new Map()
+
+  /**
+   * Register a class as a singleton.
+   * @param {Function} clazz The class constructor
+   * @param {string} [name] Optional name key
+   */
+  registerSingleton(clazz, name) {
+    this.#register(clazz, 'singleton', name)
+  }
+
+  /**
+   * Register a class as a factory.
+   * @param {Function} clazz The class constructor
+   * @param {string} [name] Optional name key
+   */
+  registerFactory(clazz, name) {
+    this.#register(clazz, 'factory', name)
+  }
+
+  /**
+   * Internal registration logic.
+   * @param {Function} clazz The class constructor
+   * @param {'singleton'|'factory'} type The registration type
+   * @param {string} [name] Optional name key
+   * @private
+   */
+  #register(clazz, type, name) {
+    const key = name ?? clazz
+    if (this.#instances.has(key)) {
+      throw new Error(
+        'A different class is already registered under this name. ' +
+        'This may be a circular dependency. Try using @InjectLazy'
+      )
+    }
+    this.#instances.set(key, {clazz, type})
+  }
+
+  /**
+   * Get the context for a given class or name.
+   * @param {string|Function} clazzOrName The class or name to look up
+   * @returns {InstanceContext}
+   * @throws {Error} If the context is not found
+   */
+  getContext(clazzOrName) {
+    if (this.#instances.has(clazzOrName)) {
+      return this.#instances.get(clazzOrName)
+    }
+    const available = Array.from(this.#instances.keys())
+      .map(k => typeof k === 'string' ? k : k.name)
+      .join(', ')
+    throw new Error(
+      `Cannot find injection source for "${clazzOrName?.name || clazzOrName}". ` +
+      `Available: [${available}]`
+    )
+  }
+
+  /**
+   * Check if a class or name is registered.
+   * @param {string|Function} clazzOrName The class or name to check
+   * @returns {boolean}
+   */
+  has(clazzOrName) {
+    return this.#instances.has(clazzOrName)
+  }
+
+  /**
+   * Get or create an instance based on the context.
+   * @param {InstanceContext} instanceContext The instance context
+   * @param {Array} params Constructor parameters
+   * @returns {Object} The instance
+   */
+  getInstance(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 = createProxy(instance, originalInstance)
+    }
+
+    if (instanceContext.type === 'singleton') {
+      instanceContext.instance = instance
+    }
+
+    return instance
+  }
+
+  /**
+   * Register a mock for an existing class.
+   * @param {string|Function} targetClazzOrName The class or name to mock
+   * @param {Function} mockClazz The mock class
+   * @param {boolean} [useProxy=false] Whether to proxy unmocked methods to original
+   */
+  registerMock(targetClazzOrName, mockClazz, useProxy = false) {
+    const instanceContext = this.getContext(targetClazzOrName)
+    if (instanceContext.originalClazz) {
+      throw new Error('Mock already defined, reset before mocking again')
+    }
+    instanceContext.originalClazz = instanceContext.clazz
+    instanceContext.proxy = useProxy
+    instanceContext.clazz = mockClazz
+  }
+
+  /**
+   * Reset a specific mock to its original class.
+   * @param {string|Function} clazzOrName The class or name to reset
+   * @throws {Error} If the class or name is not registered
+   */
+  resetMock(clazzOrName) {
+    const key = typeof clazzOrName === 'string' ? clazzOrName : clazzOrName
+    this.#restoreOriginal(this.#instances.get(key), clazzOrName)
+  }
+
+  /**
+   * Reset all mocks to their original classes.
+   */
+  resetAllMocks() {
+    for (const instanceContext of this.#instances.values()) {
+      this.#restoreOriginal(instanceContext)
+    }
+  }
+
+  /**
+   * Clear all registered instances and mocks.
+   * Useful for test isolation.
+   */
+  clear() {
+    this.#instances.clear()
+  }
+
+  /**
+   * Internal function to restore an instance context to its original.
+   * @param {InstanceContext} instanceContext The instance context to reset
+   * @param {string|Function} [clazzOrName] Optional identifier for error messages
+   * @throws {Error} If instanceContext is null or undefined
+   * @private
+   */
+  #restoreOriginal(instanceContext, clazzOrName) {
+    if (!instanceContext) {
+      const name = clazzOrName?.name || clazzOrName || 'unknown'
+      throw new Error(`Cannot reset mock for "${name}": not registered`)
+    }
+    if (instanceContext.originalClazz) {
+      instanceContext.clazz = instanceContext.originalClazz
+      delete instanceContext.instance
+      delete instanceContext.originalClazz
+      delete instanceContext.originalInstance
+      delete instanceContext.proxy
+    }
+  }
+}

package/src/proxy.js

@@ -0,0 +1,42 @@
+/**
+ * Create a proxy that delegates to the mock first, then falls back to the original.
+ * This allows partial mocking where only specific methods are overridden.
+ *
+ * @param {Object} mock The mock instance
+ * @param {Object} original The original instance to fall back to
+ * @returns {Proxy} A proxy that delegates appropriately
+ */
+export function createProxy(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, original)
+    },
+
+    set(target, prop, value, receiver) {
+      if (prop in target) {
+        return Reflect.set(target, prop, value, receiver)
+      }
+      return Reflect.set(original, prop, value, original)
+    },
+
+    has(target, prop) {
+      return prop in target || prop in original
+    },
+
+    ownKeys(target) {
+      const mockKeys = Reflect.ownKeys(target)
+      const originalKeys = Reflect.ownKeys(original)
+      return [...new Set([...mockKeys, ...originalKeys])]
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      if (prop in target) {
+        return Reflect.getOwnPropertyDescriptor(target, prop)
+      }
+      return Reflect.getOwnPropertyDescriptor(original, prop)
+    }
+  })
+}