decorator-dependency-injection 1.0.2 → 1.0.4

package/README.md

@@ -1,11 +1,15 @@
 # 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)
+[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen)](https://github.com/mallocator/decorator-dependency-injection)
 
 ## 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 +17,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 +52,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, Inject} from 'decorator-dependency-injection';
 
-@Singleton
-class Dependency {}
+@Singleton()
+class Dependency {
+}
 
 class Consumer {
   @Inject(Dependency) dependency // creates an instance only once
@@ -65,25 +75,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, Inject} from 'decorator-dependency-injection';
 
-@Factory
-class Dependency {}
+@Factory()
+class Dependency {
+}
 
 class Consumer {
   @Inject(Dependency) dependency // creates a new instance each time a new Consumer is created
 }
 ```
 
+### InjectLazy
+
+```@Inject``` annotated properties are evaluated during instance initialization. That means that all properties should
+be accessible in the constructor. That also means that we're creating an instance no matter if you access the property
+or not. If you want to only create an instance when you access the property, you can use the ```@InjectLazy```
+decorator. This will create the instance only when the property is accessed for the first time. Note that this also
+works from the constructor, same as the regular ```@Inject```.  
+
+```javascript
+import {Singleton, InjectLazy} from 'decorator-dependency-injection';
+
+@Singleton()
+class Dependency {
+}
+
+class Consumer {
+  @InjectLazy(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,16 +131,17 @@ 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, resetMock} from 'decorator-dependency-injection'
 
-@Factory
+@Factory()
 class Dependency {
   method() {
     return 'real'
@@ -138,12 +172,35 @@ 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 { Factory, Inject, Mock } from 'decorator-dependency-injection'
+import {resetMock, resetMocks} from 'decorator-dependency-injection';
 
-@Factory
+resetMock(Dependency); // Restores the original Dependency implementation
+resetMocks(); // Restores all mocked dependencies
+```
+
+### Clearing the Container
+
+For complete test isolation, you can clear all registered instances from the container:
+
+```javascript
+import {clearContainer} from 'decorator-dependency-injection';
+
+clearContainer(); // Removes all registered singletons, factories, and mocks
+```
+
+You can also use the ```@Mock``` decorator as a proxy instead of a full mock. Any method calls not implemented in the
+mock will be passed to the real dependency.
+
+```javascript
+import {Factory, Inject, Mock, resetMock} from 'decorator-dependency-injection'
+
+@Factory()
 class Dependency {
   method() {
     return 'real'
@@ -180,6 +237,45 @@ const consumer = new Consumer()  // prints 'real other'
 
 For more examples, see the tests in the ```test``` directory.
 
+## Advanced Usage
+
+### Using Isolated Containers
+
+For advanced scenarios like parallel test execution or module isolation, you can create separate containers:
+
+```javascript
+import {Container} from 'decorator-dependency-injection';
+
+const container1 = new Container();
+const container2 = new Container();
+
+class MyService {}
+
+// Register the same class in different containers
+container1.registerSingleton(MyService);
+container2.registerSingleton(MyService);
+
+// Each container maintains its own singleton instance
+const ctx1 = container1.getContext(MyService);
+const ctx2 = container2.getContext(MyService);
+
+const instance1 = container1.getInstance(ctx1, []);
+const instance2 = container2.getInstance(ctx2, []);
+
+console.log(instance1 === instance2); // false - different containers
+```
+
+### Accessing the Default Container
+
+You can access the default global container for programmatic registration:
+
+```javascript
+import {getContainer} from 'decorator-dependency-injection';
+
+const container = getContainer();
+console.log(container.has(MyService)); // Check if a class is registered
+```
+
 ## Running the tests
 
 To run the tests, run the following command in the project root.
@@ -192,4 +288,6 @@ 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 @InjectLazy decorator
+- 1.0.4 - Added Container abstraction, clearContainer(), TypeScript definitions, improved proxy support

package/eslint.config.js

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

package/index.d.ts

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