decorator-dependency-injection 1.0.3 → 1.0.5

package/index.js

@@ -1,22 +1,50 @@
 /**
- * @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()
+
+/**
+ * Creates a lazy accessor descriptor with WeakMap-based caching.
+ * @param {WeakMap} cache - WeakMap for per-instance caching
+ * @param {Function} getValue - Factory function to create the value
+ * @param {string} name - The accessor name for error messages
+ * @returns {{init: Function, get: Function, set: Function}} Accessor descriptor
+ * @private
+ */
+function createLazyAccessor(cache, getValue, name) {
+  return {
+    init(initialValue) {
+      if (initialValue) {
+        throw new Error(`Cannot assign value to injected accessor "${name}"`)
+      }
+      return undefined
+    },
+    get() {
+      if (!cache.has(this)) {
+        cache.set(this, getValue())
+      }
+      return cache.get(this)
+    },
+    set() {
+      throw new Error(`Cannot assign value to injected accessor "${name}"`)
+    }
+  }
+}
 
 /**
  * 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 +59,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 +68,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 +83,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,87 +91,131 @@ 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)}
+ * Supports:
+ * - Public fields: @Inject(MyClass) myField
+ * - Private fields: @Inject(MyClass) #myField
+ * - Accessors: @Inject(MyClass) accessor myField
+ * - Private accessors: @Inject(MyClass) accessor #myField
+ *
+ * @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
+ * @example @Inject(MyService) #privateService
+ * @example @Inject(MyService) accessor myService
+ * @throws {Error} If the injection target is not a field or accessor
  * @throws {Error} If the injected field is assigned a value
  */
 export function Inject(clazzOrName, ...params) {
-  return function (initialValue, context) {
-    if (context.kind !== 'field') {
-      throw new Error('Invalid injection target')
+  return function (_, context) {
+    const getValue = () => {
+      const instanceContext = defaultContainer.getContext(clazzOrName)
+      return defaultContainer.getInstance(instanceContext, params)
     }
-    return function (initialValue) {
-      if (initialValue) {
-        throw new Error('Cannot assign value to injected field')
+
+    if (context.kind === 'field') {
+      return function (initialValue) {
+        if (initialValue) {
+          throw new Error(`Cannot assign value to injected field "${context.name}"`)
+        }
+        return getValue()
       }
-      const instanceContext = getContext(clazzOrName)
-      return getInjectedInstance(instanceContext, params)
     }
+
+    if (context.kind === 'accessor') {
+      const cache = new WeakMap()
+      return createLazyAccessor(cache, getValue, context.name)
+    }
+
+    throw new Error('Invalid injection target: @Inject can only be used on fields or accessors')
   }
 }
 
 /**
  * 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)}
+ *
+ * The lazy injection defers instantiation until the field is first accessed. This is useful for:
+ * - Breaking circular dependencies
+ * - Deferring expensive initializations
+ *
+ * Supports:
+ * - Public fields: @InjectLazy(MyClass) myField
+ * - Private fields: @InjectLazy(MyClass) #myField
+ * - Accessors: @InjectLazy(MyClass) accessor myField
+ * - Private accessors: @InjectLazy(MyClass) accessor #myField
+ *
+ * Note: For private fields, the lazy behavior is achieved through the field initializer
+ * returning a getter-based proxy. For accessors, it's achieved through the accessor's
+ * get/set methods directly.
+ *
+ * @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
+ * @example @InjectLazy(MyService) #privateService
+ * @throws {Error} If the injection target is not a field or accessor
  * @throws {Error} If the injected field is assigned a value
  */
 export function InjectLazy(clazzOrName, ...params) {
   const cache = new WeakMap()
-  return (initialValue, 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 = getContext(clazzOrName)
-            const value = getInjectedInstance(instanceContext, params)
-            cache.set(this, value)
-          }
-          return cache.get(this)
-        },
-        configurable: true,
-        enumerable: true
-      })
-    })
+
+  const getValue = () => {
+    const instanceContext = defaultContainer.getContext(clazzOrName)
+    return defaultContainer.getInstance(instanceContext, 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 (_, context) => {
+    if (context.kind === 'field') {
+      // For private fields, we cannot use Object.defineProperty to create a lazy getter.
+      // Instead, we eagerly create the value. For true lazy behavior, use accessor syntax.
+      if (context.private) {
+        return function (initialValue) {
+          if (initialValue) {
+            throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
+          }
+          return getValue()
+        }
       }
-      return Reflect.get(original, prop, receiver)
+
+      // For public fields, use Object.defineProperty for true lazy behavior
+      context.addInitializer(function () {
+        Object.defineProperty(this, context.name, {
+          get() {
+            if (!cache.has(this)) {
+              cache.set(this, getValue())
+            }
+            return cache.get(this)
+          },
+          set() {
+            throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
+          },
+          configurable: true,
+          enumerable: true
+        })
+      })
+      return
+    }
+
+    if (context.kind === 'accessor') {
+      return createLazyAccessor(cache, getValue, context.name)
     }
-  })
+
+    throw new Error('Invalid injection target: @InjectLazy can only be used on fields or accessors')
+  }
 }
 
 /**
  * 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,97 +224,97 @@ 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
+    defaultContainer.registerMock(mockedClazzOrName, clazz, proxy)
   }
 }
 
 /**
- * Internal: Get the context for a given class or name.
+ * Reset all mocks to their original classes.
+ */
+export function resetMocks() {
+  defaultContainer.resetAllMocks()
+}
+
+/**
+ * Reset a specific mock to its original class.
  *
- * @param {string|Class} mockedClazzOrName - The class or name to look up.
- * @returns {InstanceContext}
- * @throws {Error} If the context is not found.
+ * @param {string|Function} clazzOrName The singleton or factory class or name to reset
  */
-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}]`
-    )
-  }
+export function resetMock(clazzOrName) {
+  defaultContainer.resetMock(clazzOrName)
 }
 
 /**
- * Reset all mocks to their original classes.
+ * Clear all registered instances and mocks from the container.
+ * Useful for complete test isolation between test suites.
  */
-export function resetMocks() {
-  for (const instanceContext of instances.values()) {
-    restoreOriginal(instanceContext)
-  }
+export function clearContainer() {
+  defaultContainer.clear()
 }
 
 /**
- * Reset a specific mock to its original class.
- * @param {string|Class} clazzOrName The singleton or factory class or name to reset
+ * Get the default container instance.
+ * Useful for advanced use cases or testing the container itself.
+ *
+ * @returns {Container} The default container
  */
-export function resetMock(clazzOrName) {
-  restoreOriginal(getContext(clazzOrName))
+export function getContainer() {
+  return defaultContainer
 }
 
 /**
- * Internal function to reset an instance context to its original.
- * @param {InstanceContext} instanceContext The instance context to reset
- * @private
+ * Enable or disable debug logging for dependency injection.
+ * When enabled, logs when instances are registered, created, and mocked.
+ *
+ * @param {boolean} enabled Whether to enable debug mode
+ * @example
+ * setDebug(true)
+ * // [DI] Registered singleton: UserService
+ * // [DI] Creating singleton: UserService
  */
-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 setDebug(enabled) {
+  defaultContainer.setDebug(enabled)
 }
 
 /**
- * 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
+ * Check if a class or name is registered in the default container.
+ * Useful for validation before injection.
+ *
+ * @param {string|Function} clazzOrName The class or name to check
+ * @returns {boolean} true if registered, false otherwise
+ * @example
+ * if (!isRegistered(MyService)) {
+ *   console.warn('MyService not registered!')
+ * }
  */
-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
+export function isRegistered(clazzOrName) {
+  return defaultContainer.has(clazzOrName)
+}
+
+/**
+ * Validate that all provided injection tokens are registered.
+ * Throws an error with details about missing registrations.
+ * Useful for fail-fast validation at application startup.
+ *
+ * @param {...(string|Function)} tokens Classes or names to validate
+ * @throws {Error} If any token is not registered
+ * @example
+ * // At app startup:
+ * validateRegistrations(UserService, AuthService, 'databaseConnection')
+ */
+export function validateRegistrations(...tokens) {
+  const missing = tokens.filter(token => !defaultContainer.has(token))
+  if (missing.length > 0) {
+    const names = missing.map(t => typeof t === 'string' ? t : t.name).join(', ')
+    throw new Error(
+      `Missing registrations: [${names}]. ` +
+      `Ensure these classes are decorated with @Singleton() or @Factory() before use.`
+    )
   }
-  return instance
 }
+
+// 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.3",
+  "version": "1.0.5",
   "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"
   }
-}
+}