decorator-dependency-injection 1.0.2 → 1.0.3

package/.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Create Release
+name: Release
 
 on:
   push:

package/README.md

@@ -1,11 +1,14 @@
 # Decorator Dependency Injection
-[![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/node.js.yml/badge.svg)](https://github.com/mallocator/decorator-dependency-injection/actions/workflows/node.js.yml)
 
+[![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)
 
 ## Description
 
-With [TC39](https://github.com/tc39/proposal-decorators) reaching stage 3 on the decorators proposal, it's time to start thinking about how we can use them in our projects. One of the most common patterns in JavaScript is dependency injection. This pattern is used to make our code more testable and maintainable. This library provides simple decorators to help you inject dependencies into your classes and mock them for testing.
+With the [TC39 proposal-decorators](https://github.com/tc39/proposal-decorators) reaching stage 3, it's time to start
+thinking about how we can use them in our projects. One of the most common patterns in JavaScript is dependency
+injection. This pattern is used to make our code more testable and maintainable. This library provides simple decorators
+to help you inject dependencies into your classes and mock them for testing.
 
 ## Installation
 
@@ -13,21 +16,26 @@ With [TC39](https://github.com/tc39/proposal-decorators) reaching stage 3 on the
 npm install decorator-dependency-injection
 ```
 
-Until we reach stage 4, you will need to enable the decorators proposal in your project. You can do this by adding the following babel transpiler options to your `.babelrc` file.
+Until we reach stage 4, you will need to enable the decorators proposal in your project. You can do this by adding the
+following babel transpiler options to your `.babelrc` file.
 
 ```json
 {
-  "plugins": ["@babel/plugin-proposal-decorators"]
+  "plugins": [
+    "@babel/plugin-proposal-decorators"
+  ]
 }
 ```
 
-To run your project with decorators enabled you will need to use the babel transpiler. You can do this by running the following command in your project root.
+To run your project with decorators enabled, you will need to use the babel transpiler. You can do this by running the
+following command in your project root.
 
 ```bash
 npx babel-node index.js
 ```
 
-Finally, for running tests with decorators enabled you will need to use the babel-jest package. You can do this by adding the following configuration to your `package.json` file.
+Finally, for running tests with decorators enabled, you will need to use the babel-jest package. You can do this by
+adding the following configuration to your `package.json` file.
 
 ```json
 {
@@ -43,20 +51,21 @@ Other testing frameworks may require a different configuration.
 
 For a full example of how to set up a project with decorators, see this project's ```package.json``` file.
 
-
 ## Usage
 
-There are 2 ways of specifying injectable dependencies: ```@Singleton``` and ```@Factory```:
+There are two ways of specifying injectable dependencies: ```@Singleton``` and ```@Factory```:
 
 ### Singleton
 
-The ```@Singleton``` decorator is used to inject a single instance of a dependency into a class. This is useful when you want to share the same instance of a class across multiple classes.
+The ```@Singleton``` decorator is used to inject a single instance of a dependency into a class. This is useful when you
+want to share the same instance of a class across multiple classes.
 
 ```javascript
-import { Singleton } from 'decorator-dependency-injection';
+import {Singleton} from 'decorator-dependency-injection';
 
 @Singleton
-class Dependency {}
+class Dependency {
+}
 
 class Consumer {
   @Inject(Dependency) dependency // creates an instance only once
@@ -65,25 +74,48 @@ class Consumer {
 
 ### Factory
 
-The ```@Factory``` decorator is used to inject a new instance of a dependency into a class each time it is requested. This is useful when you want to create a new instance of a class each time it is injected.
+The ```@Factory``` decorator is used to inject a new instance of a dependency into a class each time it is requested.
+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} from 'decorator-dependency-injection';
 
 @Factory
-class Dependency {}
+class Dependency {
+}
 
 class Consumer {
   @Inject(Dependency) dependency // creates a new instance each time a new Consumer is created
 }
 ```
 
+### LazyInject
+
+```@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```
+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```.
+
+```javascript
+import {LazyInject} from 'decorator-dependency-injection';
+
+@Singleton
+class Dependency {
+}
+
+class Consumer {
+  @LazyInject(Dependency) dependency // creates an instance only when the property is accessed
+}
+```
+
 ## Passing parameters to a dependency
 
-You can pass parameters to a dependency by using the ```@Inject``` decorator with a function that returns the dependency.
+You can pass parameters to a dependency by using the ```@Inject``` decorator with a function that returns the
+dependency.
 
 ```javascript
-import { Factory, Inject } from 'decorator-dependency-injection';
+import {Factory, Inject} from 'decorator-dependency-injection';
 
 @Factory
 class Dependency {
@@ -98,14 +130,15 @@ class Consumer {
 }
 ```
 
-While this is most useful for Factory dependencies, it can also be used with Singleton dependencies. However, parameters will only be passed to the dependency the first time it is created.
+While this is most useful for Factory dependencies, it can also be used with Singleton dependencies. However, parameters
+will only be passed to the dependency the first time it is created.
 
 ## Mocking dependencies for testing
 
 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} from 'decorator-dependency-injection'
 
 @Factory
 class Dependency {
@@ -138,10 +171,22 @@ resetMock(Dependency)
 const consumer = new Consumer()  // prints 'real'
 ```
 
-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.
+### Resetting Mocks
+
+The `resetMock` utility function allows you to remove any active mock for a dependency and restore the original
+implementation. This is useful for cleaning up after tests or switching between real and mock dependencies.
+
+```javascript
+import {resetMock} from 'decorator-dependency-injection';
+
+resetMock(Dependency); // Restores the original Dependency implementation
+```
+
+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} from 'decorator-dependency-injection'
 
 @Factory
 class Dependency {
@@ -192,4 +237,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.2 - Added proxy option to @Mock decorator
+- 1.0.3 - Added @LazyInject decorator

package/index.js

@@ -1,11 +1,11 @@
 /**
  * @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
+ * @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.
  */
 
 /** @type {Map<string|Class, InstanceContext>} */
@@ -16,22 +16,26 @@ const instances = new 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)|*}
+ * @return {(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' })
+    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'})
   }
 }
 
@@ -40,22 +44,26 @@ 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)|*}
+ * @return {(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')
+    }
+    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(name ?? clazz, { clazz, type: 'factory' })
+    instances.set(key, {clazz, type: 'factory'})
   }
 }
 
@@ -65,52 +73,67 @@ export function Factory(name) {
  *
  * @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)|*}
+ * @return {(function(*, {kind: string, name: string}): void)}
  * @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')
+  return function (initialValue, 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')
       }
-    } else {
+      const instanceContext = getContext(clazzOrName)
+      return getInjectedInstance(instanceContext, 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)}
+ * @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 (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
+      })
+    })
   }
 }
 
+/**
+ * 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) {
@@ -126,20 +149,20 @@ function getProxy(mock, original) {
  * 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)|*}
+ * @return {(function(Function, {kind: string}): void)}
  * @example @Mock(MySingleton) class MyMock {}
  * @example @Mock("myCustomName") 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')
+      throw new Error('Mock already defined, reset before mocking again')
     }
     instanceContext.originalClazz = instanceContext.clazz
     instanceContext.proxy = proxy
@@ -147,11 +170,22 @@ export function Mock(mockedClazzOrName, proxy = false) {
   }
 }
 
+/**
+ * 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 {
-    throw new Error('Cannot find injection source with the provided name')
+    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}]`
+    )
   }
 }
 
@@ -160,7 +194,7 @@ function getContext(mockedClazzOrName) {
  */
 export function resetMocks() {
   for (const instanceContext of instances.values()) {
-    reset(instanceContext)
+    restoreOriginal(instanceContext)
   }
 }
 
@@ -169,7 +203,7 @@ export function resetMocks() {
  * @param {string|Class} clazzOrName The singleton or factory class or name to reset
  */
 export function resetMock(clazzOrName) {
-  reset(getContext(clazzOrName))
+  restoreOriginal(getContext(clazzOrName))
 }
 
 /**
@@ -177,14 +211,46 @@ export function resetMock(clazzOrName) {
  * @param {InstanceContext} instanceContext The instance context to reset
  * @private
  */
-function reset(instanceContext) {
+function restoreOriginal(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.instance
     delete instanceContext.originalClazz
     delete instanceContext.originalInstance
   }
 }
+
+/**
+ * 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
+ */
+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
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "decorator-dependency-injection",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A simple library for dependency injection using decorators",
   "author": "Ravi Gairola <mallox@pyxzl.net>",
   "license": "Apache-2.0",

package/test/injection.test.js

@@ -1,4 +1,4 @@
-import {Factory, Inject, Singleton} from '../index.js'
+import {Factory, Inject, resetMocks, Singleton} from '../index.js'
 
 describe('Injection via fields', () => {
   @Singleton()
@@ -46,6 +46,12 @@ describe('Injection via fields', () => {
     }
   }
 
+  afterEach(() => {
+    TestFactory.calls = 0
+    TestSingleton.calls = 0
+    resetMocks()
+  })
+
   it('should inject factory', () => {
     class TestInjectionFactory {
       @Inject(TestFactory) testFactory
@@ -83,7 +89,53 @@ describe('Injection via fields', () => {
     new TestInjectionFactoryParams()
   })
 
-  @Singleton("named")
+  it('should cache factory instance on repeated accesses', () => {
+    class TestRepeatedFactoryAccess {
+      @Inject(TestFactory) testFactory
+
+      constructor() {
+        const instance1 = this.testFactory
+        const instance2 = this.testFactory
+        expect(instance1).toBe(instance2)
+      }
+    }
+
+    new TestRepeatedFactoryAccess()
+  })
+
+  it('should create distinct factory instances for different fields in the same object', () => {
+    class TestMultipleFactoryInjection {
+      @Inject(TestFactory) testFactory1
+      @Inject(TestFactory) testFactory2
+
+      constructor() {
+        // Access both properties to trigger initialization.
+        const one = this.testFactory1
+        const two = this.testFactory2
+        expect(one).not.toBe(two)
+      }
+    }
+
+    new TestMultipleFactoryInjection()
+  })
+
+  it('should inject the same singleton instance for different fields in the same object', () => {
+    class TestMultipleSingletonInjection {
+      @Inject(TestSingleton) testSingleton1
+      @Inject(TestSingleton) testSingleton2
+
+      constructor() {
+        // Access both properties to trigger initialization.
+        const one = this.testSingleton1
+        const two = this.testSingleton2
+        expect(one).toBe(two)
+      }
+    }
+
+    new TestMultipleSingletonInjection()
+  })
+
+  @Singleton('named')
   class NamedSingleton {
     static calls = 0
 
@@ -94,7 +146,7 @@ describe('Injection via fields', () => {
 
   it('should inject named singleton', () => {
     class TestInjectionNamedSingleton {
-      @Inject("named") namedSingleton
+      @Inject('named') namedSingleton
 
       constructor() {
         expect(this.namedSingleton).toBeInstanceOf(NamedSingleton)
@@ -103,7 +155,7 @@ describe('Injection via fields', () => {
     }
 
     class TestInjectionNamedSingleton2 {
-      @Inject("named") namedSingleton
+      @Inject('named') namedSingleton
 
       constructor() {
         expect(this.namedSingleton).toBeInstanceOf(NamedSingleton)
@@ -115,7 +167,7 @@ describe('Injection via fields', () => {
     new TestInjectionNamedSingleton2()
   })
 
-  @Factory("named2")
+  @Factory('named2')
   class NamedFactory {
     static calls = 0
     params
@@ -128,7 +180,7 @@ describe('Injection via fields', () => {
 
   it('should inject named factory', () => {
     class TestInjectionNamedFactory {
-      @Inject("named2") namedFactory
+      @Inject('named2') namedFactory
 
       constructor() {
         expect(this.namedFactory).toBeInstanceOf(NamedFactory)
@@ -137,7 +189,7 @@ describe('Injection via fields', () => {
     }
 
     class TestInjectionNamedFactory2 {
-      @Inject("named2") namedFactory
+      @Inject('named2') namedFactory
 
       constructor() {
         expect(this.namedFactory).toBeInstanceOf(NamedFactory)
@@ -149,4 +201,109 @@ describe('Injection via fields', () => {
     new TestInjectionNamedFactory2()
     expect(result.namedFactory.params).toEqual([])
   })
+
+  it('should cache named factory instance on repeated accesses', () => {
+    class TestRepeatedNamedFactoryAccess {
+      @Inject('named2') namedFactory
+
+      constructor() {
+        const instance1 = this.namedFactory
+        const instance2 = this.namedFactory
+        expect(instance1).toBe(instance2)
+      }
+    }
+
+    new TestRepeatedNamedFactoryAccess()
+  })
+
+  it('should throw if @Inject is applied to a method', () => {
+    expect(() => {
+      // noinspection JSUnusedLocalSymbols
+      class BadInjection {
+        @Inject('something')
+        someMethod() {
+        }
+      }
+    }).toThrow()
+  })
+
+  it('should handle circular dependencies gracefully', () => {
+    @Singleton()
+    class A {
+      @Inject('B') b
+    }
+
+    @Singleton('B')
+    class B {
+      @Inject(A) a
+    }
+
+    expect(() => new A()).toThrow(/Circular dependency detected.*@InjectLazy/)
+  })
+
+  it('should throw if decorator is used on non-class object', () => {
+    expect(() => {
+      const obj = {}
+      Inject('something')(obj, 'field')
+    }).toThrow()
+  })
+
+  it('should throw a helpful error for eager circular dependencies', () => {
+    @Factory()
+    class A2 {
+      @Inject('B2') b
+    }
+
+    @Singleton('B2')
+    class B2 {
+      @Inject(A2) a
+    }
+
+    expect(() => new A2()).toThrow(/Circular dependency detected.*@InjectLazy/)
+  })
+
+  it('should inject into symbol-named fields', () => {
+    const sym = Symbol('sym')
+
+    @Singleton()
+    class S {
+    }
+
+    class Test {
+      @Inject(S) [sym]
+    }
+
+    const t = new Test()
+    expect(t[sym]).toBeInstanceOf(S)
+  })
+
+  it('should not leak injected properties to prototype', () => {
+    @Singleton()
+    class S {
+    }
+
+    class Test {
+      @Inject(S) dep
+    }
+
+    // noinspection JSUnusedLocalSymbols
+    const t = new Test()
+    expect(Object.prototype.hasOwnProperty.call(Test.prototype, 'dep')).toBe(false)
+  })
+
+  it('should handle undefined/null/complex params in factory', () => {
+    @Factory()
+    class F {
+      constructor(...params) {
+        this.params = params
+      }
+    }
+
+    class Test {
+      @Inject(F, undefined, null, {a: 1}) dep
+    }
+
+    const t = new Test()
+    expect(t.dep.params).toEqual([undefined, null, {a: 1}])
+  })
 })

package/test/injectionLazy.test.js

@@ -0,0 +1,249 @@
+import {Factory, InjectLazy, resetMocks, Singleton} from '../index.js'
+
+describe('Lazy Injection via fields', () => {
+  @Singleton()
+  class TestLazySingleton {
+    static calls = 0
+
+    constructor() {
+      TestLazySingleton.calls++
+    }
+  }
+
+  it('should lazily inject singleton', () => {
+    class TestLazySingletonInjection {
+      @InjectLazy(TestLazySingleton) testSingleton
+
+      constructor() {
+      }
+    }
+
+    const instance = new TestLazySingletonInjection()
+    expect(TestLazySingleton.calls).toBe(0) // Not constructed until access
+    const first = instance.testSingleton
+    expect(first).toBeInstanceOf(TestLazySingleton)
+    expect(TestLazySingleton.calls).toBe(1)
+    // Repeated access returns the same instance.
+    const second = instance.testSingleton
+    expect(first).toBe(second)
+  })
+
+  @Factory()
+  class TestLazyFactory {
+    static calls = 0
+    params
+
+    constructor(...params) {
+      TestLazyFactory.calls++
+      this.params = params
+    }
+  }
+
+  afterEach(() => {
+    TestLazyFactory.calls = 0
+    TestLazySingleton.calls = 0
+    resetMocks()
+  })
+
+  it('should lazily inject factory with caching on first access per field', () => {
+    class TestLazyFactoryInjection {
+      @InjectLazy(TestLazyFactory) testFactory
+
+      constructor() {
+      }
+    }
+
+    const inst = new TestLazyFactoryInjection()
+    expect(TestLazyFactory.calls).toBe(0)
+    const first = inst.testFactory
+    expect(first).toBeInstanceOf(TestLazyFactory)
+    expect(TestLazyFactory.calls).toBe(1)
+    expect(inst.testFactory).toBe(first)
+  })
+
+  it('should create distinct factory instances for different fields', () => {
+    class TestMultipleLazyFactoryInjection {
+      @InjectLazy(TestLazyFactory) testFactory1
+      @InjectLazy(TestLazyFactory) testFactory2
+
+      constructor() {
+      }
+    }
+
+    const instance = new TestMultipleLazyFactoryInjection()
+    expect(TestLazyFactory.calls).toBe(0)
+    const one = instance.testFactory1
+    const two = instance.testFactory2
+    expect(one).toBeInstanceOf(TestLazyFactory)
+    expect(two).toBeInstanceOf(TestLazyFactory)
+    expect(one).not.toBe(two)
+  })
+
+  it('should pass constructor parameters when using lazy injection', () => {
+    class TestLazyFactoryParamsInjection {
+      @InjectLazy(TestLazyFactory, 'param1', 'param2') testFactory
+
+      constructor() {
+      }
+    }
+
+    TestLazyFactory.calls = 0
+    const instance = new TestLazyFactoryParamsInjection()
+    expect(TestLazyFactory.calls).toBe(0)
+    const factoryInst = instance.testFactory
+    expect(factoryInst).toBeInstanceOf(TestLazyFactory)
+    expect(factoryInst.params).toEqual(['param1', 'param2'])
+  })
+
+  it('should not initialize dependency if property is never accessed', () => {
+    class TestNeverAccess {
+      @InjectLazy(TestLazySingleton) testSingleton
+
+      constructor() {
+      }
+    }
+
+    TestLazySingleton.calls = 0
+    new TestNeverAccess() // Do not access testSingleton.
+    expect(TestLazySingleton.calls).toBe(0)
+  })
+
+  @Singleton('lazyNamedSingleton')
+  class NamedLazySingleton {
+    static calls = 0
+
+    constructor() {
+      NamedLazySingleton.calls++
+    }
+  }
+
+  it('should lazily inject named singleton', () => {
+    class TestLazyNamedSingletonInjection {
+      @InjectLazy('lazyNamedSingleton') namedSingleton
+
+      constructor() {
+      }
+    }
+
+    const instance = new TestLazyNamedSingletonInjection()
+    expect(NamedLazySingleton.calls).toBe(0)
+    const first = instance.namedSingleton
+    expect(first).toBeInstanceOf(NamedLazySingleton)
+    expect(NamedLazySingleton.calls).toBe(1)
+    expect(instance.namedSingleton).toBe(first)
+  })
+
+  @Factory('lazyNamedFactory')
+  class NamedLazyFactory {
+    static calls = 0
+    params
+
+    constructor(...params) {
+      NamedLazyFactory.calls++
+      this.params = params
+    }
+  }
+
+  it('should lazily inject named factory', () => {
+    class TestLazyNamedFactoryInjection {
+      @InjectLazy('lazyNamedFactory') namedFactory
+
+      constructor() {
+      }
+    }
+
+    NamedLazyFactory.calls = 0
+    const instance = new TestLazyNamedFactoryInjection()
+    expect(NamedLazyFactory.calls).toBe(0)
+    const first = instance.namedFactory
+    expect(first).toBeInstanceOf(NamedLazyFactory)
+    expect(NamedLazyFactory.calls).toBe(1)
+    expect(instance.namedFactory).toBe(first)
+  })
+
+  it('should not expose any internal caching artifacts', () => {
+    class TestLazyEnum {
+      @InjectLazy(TestLazySingleton) lazyProp
+
+      constructor() {
+      }
+    }
+
+    const inst = new TestLazyEnum()
+    // noinspection JSUnusedLocalSymbols: Force lazy initialization.
+    const _ = inst.lazyProp
+    const keys = Object.keys(inst)
+    expect(keys).toContain('lazyProp')
+    expect(keys.length).toBe(1)
+    const symbols = Object.getOwnPropertySymbols(inst)
+    expect(symbols.length).toBe(0)
+  })
+
+  it('should throw if @InjectLazy is applied to a method', () => {
+    expect(() => {
+      // noinspection JSUnusedLocalSymbols
+      class BadLazy {
+        @InjectLazy('something')
+        someMethod() {
+        }
+      }
+    }).toThrow()
+  })
+
+  it('should handle circular dependencies (lazy)', () => {
+    @Singleton()
+    class A {
+      @InjectLazy('B') b
+    }
+
+    @Singleton('B')
+    class B {
+      @InjectLazy(A) a
+    }
+
+    expect(() => new A()).not.toThrow()
+  })
+
+  it('should inject into symbol-named fields (lazy)', () => {
+    const sym = Symbol('sym')
+
+    @Singleton()
+    class S {
+    }
+
+    class Test {
+      @InjectLazy(S) [sym]
+    }
+
+    const t = new Test()
+    expect(t[sym]).toBeInstanceOf(S)
+  })
+
+  it('should not leak lazy injected properties to prototype', () => {
+    @Singleton()
+    class S {
+    }
+
+    class Test {
+      @InjectLazy(S) dep
+    }
+
+    // noinspection JSUnusedLocalSymbols
+    const t = new Test()
+    expect(Object.prototype.hasOwnProperty.call(Test.prototype, 'dep')).toBe(false)
+  })
+
+  it('should allow circular dependencies with lazy injection', () => {
+    @Singleton()
+    class A1 {
+      @InjectLazy('B1') b
+    }
+
+    @Factory('B1')
+    class B1 {
+      @InjectLazy(A1) a
+    }
+
+    expect(() => new A1()).not.toThrow()
+  })
+})

package/test/mock.test.js

@@ -1,4 +1,4 @@
-import {resetMocks, Inject, Mock, Singleton, Factory} from '../index.js'
+import {Factory, Inject, InjectLazy, Mock, resetMock, resetMocks, Singleton} from '../index.js'
 
 describe('Mocking', () => {
   @Singleton()
@@ -24,12 +24,12 @@ describe('Mocking', () => {
     @Mock(ToBeMockedSingleton)
     class MockedSingleton {
       op() {
-        return 'mocked'
+        return 'mocked1'
       }
     }
 
     const result = new TestInjection()
-    expect(result.toBeMockedSingleton.op()).toBe('mocked')
+    expect(result.toBeMockedSingleton.op()).toBe('mocked1')
     expect(result.toBeMockedSingleton.op2).toBe.undefined
 
     resetMocks()
@@ -38,6 +38,30 @@ describe('Mocking', () => {
     expect(result2.toBeMockedSingleton.op2()).toBe('original2')
   })
 
+  // New tests for lazy injection with mocks (non-proxied)
+  it('should inject a lazy mock singleton', () => {
+    @Mock(ToBeMockedSingleton)
+    class MockedSingletonLazy {
+      op() {
+        return 'mocked2'
+      }
+    }
+
+    class TestInjectionLazy {
+      @InjectLazy(ToBeMockedSingleton) lazyMockedSingleton
+    }
+
+    const instance = new TestInjectionLazy()
+    const result = instance.lazyMockedSingleton
+    expect(result.op()).toBe('mocked2')
+    expect(result.op2).toBe.undefined
+
+    resetMocks()
+    const instance2 = new TestInjectionLazy()
+    expect(instance2.lazyMockedSingleton.op()).toBe('original')
+    expect(instance2.lazyMockedSingleton.op2()).toBe('original2')
+  })
+
   @Factory()
   class ToBeMockedFactory {
     op() {
@@ -65,13 +89,207 @@ describe('Mocking', () => {
     expect(result2.toBeMockedFactory.op()).toBe('original')
   })
 
+  // New tests for lazy injection with mock factory
+  it('should inject a lazy mock factory', () => {
+    @Mock(ToBeMockedFactory)
+    class MockedFactoryLazy {
+      op() {
+        return 'mocked'
+      }
+    }
+
+    class TestInjectionFactoryLazy {
+      @InjectLazy(ToBeMockedFactory) lazyMockedFactory
+    }
+
+    const instance = new TestInjectionFactoryLazy()
+    const result = instance.lazyMockedFactory
+    expect(result.op()).toBe('mocked')
+
+    resetMocks()
+    const instance2 = new TestInjectionFactoryLazy()
+    expect(instance2.lazyMockedFactory.op()).toBe('original')
+  })
+
   it('should throw an error if a mock is not a singleton or factory', () => {
     expect(() => {
       @Mock(ToBeMockedFactory)
-      class Mocked1 {}
+      class Mocked1 {
+      }
 
       @Mock(ToBeMockedFactory)
-      class Mocked2 {}
+      class Mocked2 {
+      }
     }).toThrow('Mock already defined, reset before mocking again')
   })
-})
+
+  // Edge case: Resetting specific mocks
+  it('should reset only the specified mock', () => {
+    @Singleton()
+    class A {
+      value() {
+        return 'A'
+      }
+    }
+
+    @Singleton()
+    class B {
+      value() {
+        return 'B'
+      }
+    }
+
+    @Mock(A)
+    class MockA {
+      value() {
+        return 'mockA'
+      }
+    }
+
+    @Mock(B)
+    class MockB {
+      value() {
+        return 'mockB'
+      }
+    }
+
+    class Test {
+      @Inject(A) a
+      @Inject(B) b
+    }
+
+    const t = new Test()
+    expect(t.a.value()).toBe('mockA')
+    expect(t.b.value()).toBe('mockB')
+
+    resetMock(A)
+    const t2 = new Test()
+    expect(t2.a.value()).toBe('A')
+    expect(t2.b.value()).toBe('mockB')
+  })
+
+  it('should use the latest mock when multiple mocks are applied', () => {
+    @Singleton()
+    class Original {
+    }
+
+    @Mock(Original)
+    class Mock1 {
+    }
+
+    resetMock(Original)
+
+    @Mock(Original)
+    class Mock2 {
+    }
+
+    class Test {
+      @Inject(Original) dep
+    }
+
+    const t = new Test()
+    expect(t.dep).toBeInstanceOf(Mock2)
+  })
+
+  it('should restore the original after unmocking', () => {
+    @Singleton()
+    class Orig {
+    }
+
+    @Mock(Orig)
+    class Mocked {
+    }
+
+    resetMock(Orig)
+
+    class Test {
+      @Inject(Orig) dep
+    }
+
+    const t = new Test()
+    expect(t.dep).toBeInstanceOf(Orig)
+  })
+
+  it('should inject subclass correctly', () => {
+    @Singleton()
+    class Base {
+    }
+
+    class Sub extends Base {
+    }
+
+    @Mock(Base)
+    class SubMock extends Sub {
+    }
+
+    class Test {
+      @Inject(Base) dep
+    }
+
+    const t = new Test()
+    expect(t.dep).toBeInstanceOf(Sub)
+  })
+
+  it('should use latest mock for lazy injection', () => {
+    @Singleton()
+    class Orig {
+    }
+
+    @Mock(Orig)
+    class Mock1 {
+    }
+
+    resetMock(Orig)
+
+    @Mock(Orig)
+    class Mock2 {
+    }
+
+    class Test {
+      @InjectLazy(Orig) dep
+    }
+
+    const t = new Test()
+    expect(t.dep).toBeInstanceOf(Mock2)
+  })
+
+  it('should restore original after unmocking (lazy)', () => {
+    @Singleton()
+    class Orig {
+    }
+
+    @Mock(Orig)
+    class Mocked {
+    }
+
+    resetMock(Orig)
+
+    class Test {
+      @InjectLazy(Orig) dep
+    }
+
+    const t = new Test()
+    expect(t.dep).toBeInstanceOf(Orig)
+  })
+
+  it('should inject subclass correctly (lazy)', () => {
+    @Singleton()
+    class Base {
+    }
+
+    class Sub extends Base {
+    }
+
+    @Mock(Base)
+    class SubMock extends Sub {
+    }
+
+    class Test {
+      @InjectLazy(Base) dep
+    }
+
+    const t = new Test()
+    expect(t.dep).toBeInstanceOf(Sub)
+  })
+})
+

package/test/proxy.test.js

@@ -1,4 +1,4 @@
-import {resetMocks, Inject, Mock, Singleton, Factory} from '../index.js'
+import {Factory, Inject, InjectLazy, Mock, resetMocks, Singleton} from '../index.js'
 
 describe('Proxy Mocking', () => {
   @Singleton()
@@ -70,4 +70,61 @@ describe('Proxy Mocking', () => {
     expect(result2.toBeProxiedFactory.op()).toBe('original')
     expect(result2.toBeProxiedFactory.op2()).toBe('original2')
   })
-})
+
+  it('should inject a lazy proxy singleton', () => {
+    @Mock(ToBeProxiedSingleton, true)
+    class ProxiedSingletonLazy {
+      op() {
+        return 'mocked'
+      }
+    }
+
+    class TestInjectionLazy {
+      @InjectLazy(ToBeProxiedSingleton) lazyProxiedSingleton
+    }
+
+    const instance = new TestInjectionLazy()
+    const result = instance.lazyProxiedSingleton
+    expect(result.op()).toBe('mocked')
+    expect(result.op2()).toBe('original2')
+
+    resetMocks()
+    const instance2 = new TestInjectionLazy()
+    expect(instance2.lazyProxiedSingleton.op()).toBe('original')
+    expect(instance2.lazyProxiedSingleton.op2()).toBe('original2')
+  })
+
+  it('should inject a lazy proxy factory', () => {
+    @Factory()
+    class ToBeProxiedFactoryLazy {
+      op() {
+        return 'original'
+      }
+
+      op2() {
+        return 'original2'
+      }
+    }
+
+    class TestInjectionFactoryLazy {
+      @InjectLazy(ToBeProxiedFactoryLazy) lazyProxiedFactory
+    }
+
+    @Mock(ToBeProxiedFactoryLazy, true)
+    class ProxiedFactoryLazy {
+      op() {
+        return 'mocked'
+      }
+    }
+
+    const instance = new TestInjectionFactoryLazy()
+    const result = instance.lazyProxiedFactory
+    expect(result.op()).toBe('mocked')
+    expect(result.op2()).toBe('original2')
+
+    resetMocks()
+    const instance2 = new TestInjectionFactoryLazy()
+    expect(instance2.lazyProxiedFactory.op()).toBe('original')
+    expect(instance2.lazyProxiedFactory.op2()).toBe('original2')
+  })
+})