decorator-dependency-injection 1.0.1 → 1.0.3

package/.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Create Release
+name: Release
 
 on:
   push:
@@ -48,12 +48,19 @@ jobs:
           TAG_EXISTS=$(git ls-remote --tags origin "v${VERSION}" | wc -l)
           echo "TAG_EXISTS=${TAG_EXISTS}" >> $GITHUB_ENV
 
+      - name: Get commit messages
+        id: commit_messages
+        run: |
+          COMMITS=$(git log --pretty=format:"%h - %s" $(git describe --tags --abbrev=0 @^)..@ | while read -r hash msg; do echo "[${hash}](https://github.com/${{ github.repository }}/commit/${hash}) - ${msg}"; done)
+          echo "COMMITS=${COMMITS}" >> $GITHUB_ENV
+
       - name: Create Tag and Release
         uses: actions/github-script@v7
         with:
           script: |
             const version = process.env.VERSION
             const tag = `v${version}`
+            const commits = process.env.COMMITS
             const { data: tags } = await github.rest.repos.listTags({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -72,7 +79,7 @@ jobs:
                 repo: context.repo.repo,
                 tag_name: tag,
                 name: `Release ${tag}`,
-                body: `Automated release of version ${tag}`,
+                body: `Automated release of version ${tag}\n\nCommits:\n${commits}`,
                 draft: false,
                 prerelease: false,
               })
@@ -101,7 +108,7 @@ jobs:
       - name: Check if version exists on npm
         id: check_npm_version
         run: |
-          if npm show ${{ github.repository }}@${{ env.VERSION }} > /dev/null 2>&1; then
+          if npm show decorator-dependency-injection@${{ env.VERSION }} > /dev/null 2>&1; then
             echo "VERSION_EXISTS=true" >> $GITHUB_ENV
           else
             echo "VERSION_EXISTS=false" >> $GITHUB_ENV
@@ -109,14 +116,12 @@ jobs:
 
       - name: Publish to npm
         if: env.VERSION_EXISTS == 'false'
-        run: npm publish --access public
+        run: | 
+          npm publish --access public
+          echo "::notice::Published new version ${{ env.VERSION }} to npm."
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      - name: Notice Publish Status
-        if: env.VERSION_EXISTS == 'false'
-        run: echo "::notice::Published new version ${{ env.VERSION }} to npm."
-
       - name: Notice Publish Status
         if: env.VERSION_EXISTS == 'true'
         run: echo "::notice::Version ${{ env.VERSION }} already exists on npm. No new version published."

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,31 +74,54 @@ 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 {
   constructor(param1, param2) {
-    this.param1 = param1;
-    this.param2 = param2;
+    this.param1 = param1
+    this.param2 = param2
   }
 }
 
@@ -98,40 +130,97 @@ 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 {
   method() {
-    return 'real';
+    return 'real'
   }
 }
 
 class Consumer {
   @Inject(Dependency) dependency
 
-  test() {
-    return this.dependency.method();
+  constructor() {
+    console.log(this.dependency.method())
   }
 }
 
-@Mock
+// Test Code
+
+@Mock(Dependency)
 class MockDependency {
   method() {
-    return 'mock';
+    return 'mock'
   }
 }
 
-const consumer = new Consumer();
+const consumer = new Consumer()  // prints 'mock'
+
+resetMock(Dependency)
+
+const consumer = new Consumer()  // prints 'real'
+```
+
+### Resetting Mocks
 
-consumer.test(); // returns 'real'
+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'
+
+@Factory
+class Dependency {
+  method() {
+    return 'real'
+  }
+
+  otherMethod() {
+    return 'other'
+  }
+}
+
+class Consumer {
+  @Inject(Dependency) dependency
+
+  constructor() {
+    console.log(this.dependency.method(), this.dependency.otherMethod())
+  }
+}
+
+// Test Code
+
+@Mock(Dependency, true)
+class MockDependency {
+  method() {
+    return 'mock'
+  }
+}
+
+const consumer = new Consumer()  // prints 'mock other'
+
+resetMock(Dependency)
+
+const consumer = new Consumer()  // prints 'real other'
 ```
 
 For more examples, see the tests in the ```test``` directory.
@@ -142,4 +231,11 @@ To run the tests, run the following command in the project root.
 
 ```bash
 npm test
-```
+```
+
+## Version History
+
+- 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

package/index.js

@@ -1,39 +1,41 @@
 /**
  * @typedef {Object} InstanceContext
- * @property {Class} clazz The class of the instance
- * @property {Object} [instance] The instance if it is a singleton
- * @property {Class} [original] The original class if it is a mock
+ * @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>} */
-const singletons = new Map()
-/** @type {Map<string|Class, InstanceContext>} */
-const factories = new Map()
+const instances = new Map()
 
 /**
  * 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)|*}
+ * @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 (singletons.has(name ?? clazz)) {
-      throw new Error('Singleton already defined')
+    if (typeof clazz !== 'function' || !clazz.prototype) {
+      throw new Error('Target must be a class constructor')
     }
-    if (factories.has(name ?? clazz)) {
-      throw new Error('Factory with the same name already defined')
+    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')
     }
-    singletons.set(name ?? clazz, { clazz })
+    instances.set(key, {clazz, type: 'singleton'})
   }
 }
 
@@ -42,25 +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 (factories.has(name ?? clazz)) {
-      throw new Error('Factory already defined')
+    if (typeof clazz !== 'function' || !clazz.prototype) {
+      throw new Error('Target must be a class constructor')
     }
-    if (singletons.has(name ?? clazz)) {
-      throw new Error('Singleton with the same name already defined')
+    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')
     }
-    factories.set(name ?? clazz, { clazz })
+    instances.set(key, {clazz, type: 'factory'})
   }
 }
 
@@ -69,70 +72,120 @@ export function Factory(name) {
  * 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
- * @return {(function(*): void)|*}
+ * @param {*} params Parameters to pass to the constructor. Recommended to use only with factories.
+ * @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')
-        }
-        if (singletons.has(clazzOrName)) {
-          const instanceContext = singletons.get(clazzOrName)
-          if (!instanceContext.instance) {
-            singletons.set(clazzOrName, {clazz: clazzOrName, instance: new instanceContext.clazz(...params), original: instanceContext.original})
-          }
-          return singletons.get(clazzOrName).instance
-        } else if (factories.has(clazzOrName)) {
-          const factoryClass = factories.get(clazzOrName).clazz
-          return new factoryClass(...params)
-        } else {
-          throw new Error('Cannot find injection source with the provided name')
-        }
+  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) {
+      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
- * @return {(function(*, *): void)|*}
+ * @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)}
  * @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) {
-  return function(clazz, context) {
-    if (context.kind !== "class") {
+export function Mock(mockedClazzOrName, proxy = false) {
+  return function (clazz, context) {
+    if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
-    if (singletons.has(mockedClazzOrName)) {
-      const instanceContext = singletons.get(mockedClazzOrName)
-      if (instanceContext.original) {
-        throw new Error('Mock already defined, reset before mocking again')
-      }
-      instanceContext.original = instanceContext.clazz
-      instanceContext.clazz = clazz
-    } else if (factories.has(mockedClazzOrName)) {
-      const instanceContext = factories.get(mockedClazzOrName)
-      if (instanceContext.original) {
-        throw new Error('Mock already defined, reset before mocking again')
-      }
-      instanceContext.original = instanceContext.clazz
-      instanceContext.clazz = clazz
-    } else {
-      throw new Error('Cannot find injection source with the provided name')
+    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}]`
+    )
   }
 }
 
@@ -140,11 +193,8 @@ export function Mock(mockedClazzOrName) {
  * Reset all mocks to their original classes.
  */
 export function resetMocks() {
-  for (const instanceContext of singletons.values()) {
-    reset(instanceContext)
-  }
-  for (const instanceContext of factories.values()) {
-    reset(instanceContext)
+  for (const instanceContext of instances.values()) {
+    restoreOriginal(instanceContext)
   }
 }
 
@@ -153,8 +203,7 @@ export function resetMocks() {
  * @param {string|Class} clazzOrName The singleton or factory class or name to reset
  */
 export function resetMock(clazzOrName) {
-  const instanceContext = singletons.get(clazzOrName) ?? factories.get(clazzOrName)
-  reset(instanceContext)
+  restoreOriginal(getContext(clazzOrName))
 }
 
 /**
@@ -162,13 +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.original) {
-    instanceContext.clazz = instanceContext.original
-    delete instanceContext.original
+  if (instanceContext.originalClazz) {
+    instanceContext.clazz = instanceContext.originalClazz
     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.1",
+  "version": "1.0.3",
   "description": "A simple library for dependency injection using decorators",
   "author": "Ravi Gairola <mallox@pyxzl.net>",
   "license": "Apache-2.0",