decorator-dependency-injection 1.0.3 → 1.0.5

package/README.md

@@ -2,6 +2,7 @@
 
 [![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
 
@@ -61,9 +62,9 @@ The ```@Singleton``` decorator is used to inject a single instance of a dependen
 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
+@Singleton()
 class Dependency {
 }
 
@@ -78,9 +79,9 @@ The ```@Factory``` decorator is used to inject a new instance of a dependency in
 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
+@Factory()
 class Dependency {
 }
 
@@ -89,26 +90,185 @@ class Consumer {
 }
 ```
 
-### LazyInject
+### 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 ```@LazyInject```
+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```.
+works from the constructor, same as the regular ```@Inject```.  
 
 ```javascript
-import {LazyInject} from 'decorator-dependency-injection';
+import {Singleton, InjectLazy} from 'decorator-dependency-injection';
 
-@Singleton
+@Singleton()
 class Dependency {
 }
 
 class Consumer {
-  @LazyInject(Dependency) dependency // creates an instance only when the property is accessed
+  @InjectLazy(Dependency) dependency // creates an instance only when the property is accessed
+}
+```
+
+### Private Field Injection
+
+Both `@Inject` and `@InjectLazy` support private fields using the `#` syntax:
+
+```javascript
+import {Singleton, Inject} from 'decorator-dependency-injection';
+
+@Singleton()
+class Database {
+  query(sql) { /* ... */ }
+}
+
+class UserService {
+  @Inject(Database) #db  // truly private - not accessible from outside
+  
+  getUser(id) {
+    return this.#db.query(`SELECT * FROM users WHERE id = ${id}`)
+  }
+}
+
+const service = new UserService()
+service.#db  // SyntaxError: Private field '#db' must be declared
+```
+
+### The `accessor` Keyword
+
+The `accessor` keyword (part of the TC39 decorators proposal) creates an auto-accessor - a private backing field with 
+automatic getter/setter. This is particularly useful for **lazy injection with private fields**.
+
+```javascript
+class Example {
+  accessor myField = 'value'
+}
+
+// Roughly equivalent to:
+class Example {
+  #myField = 'value'
+  get myField() { return this.#myField }
+  set myField(v) { this.#myField = v }
+}
+```
+
+#### Using `accessor` with Injection
+
+```javascript
+import {Singleton, Inject, InjectLazy} from 'decorator-dependency-injection';
+
+@Singleton()
+class ExpensiveService {
+  constructor() {
+    console.log('ExpensiveService created')
+  }
+}
+
+class Consumer {
+  // Public accessor - works with both @Inject and @InjectLazy
+  @Inject(ExpensiveService) accessor service
+  
+  // Private accessor - recommended for lazy private injection
+  @InjectLazy(ExpensiveService) accessor #privateService
+  
+  doWork() {
+    // Instance created only when first accessed
+    return this.#privateService.process()
+  }
+}
+```
+
+### Injection Support Matrix
+
+| Decorator | Syntax | Lazy? | Notes |
+|-----------|--------|-------|-------|
+| `@Inject` | `@Inject(Dep) field` | No | Standard injection |
+| `@Inject` | `@Inject(Dep) #field` | No | Private field injection |
+| `@Inject` | `@Inject(Dep) accessor field` | No* | Accessor injection |
+| `@Inject` | `@Inject(Dep) accessor #field` | No* | Private accessor injection |
+| `@Inject` | `@Inject(Dep) static field` | No | Static field injection |
+| `@Inject` | `@Inject(Dep) static #field` | No | Static private field |
+| `@Inject` | `@Inject(Dep) static accessor field` | No* | Static accessor |
+| `@Inject` | `@Inject(Dep) static accessor #field` | No* | Static private accessor |
+| `@InjectLazy` | `@InjectLazy(Dep) field` | ✅ Yes | Lazy public field |
+| `@InjectLazy` | `@InjectLazy(Dep) #field` | ⚠️ No | See caveat below |
+| `@InjectLazy` | `@InjectLazy(Dep) accessor field` | ✅ Yes | Lazy accessor |
+| `@InjectLazy` | `@InjectLazy(Dep) accessor #field` | ✅ Yes | **Recommended for lazy private** |
+| `@InjectLazy` | `@InjectLazy(Dep) static field` | ✅ Yes | Lazy static field |
+| `@InjectLazy` | `@InjectLazy(Dep) static #field` | ⚠️ No | Same caveat as instance private |
+| `@InjectLazy` | `@InjectLazy(Dep) static accessor #field` | ✅ Yes | Lazy static private accessor |
+
+*`@Inject` with accessors caches on first access, which is similar to lazy behavior.
+
+#### Caveat: `@InjectLazy` with Private Fields
+
+Due to JavaScript limitations, `@InjectLazy` on private fields (`#field`) **cannot be truly lazy**. The instance is 
+created at construction time (or class definition time for static fields), not on first access. This is because 
+`Object.defineProperty()` cannot create getters on private fields.
+
+This applies to both instance and static private fields.
+
+**Recommendation:** For true lazy injection with private members, use the `accessor` keyword:
+
+```javascript
+// ❌ Not truly lazy (created at construction)
+@InjectLazy(ExpensiveService) #service
+
+// ✅ Truly lazy (created on first access)
+@InjectLazy(ExpensiveService) accessor #service
+
+// Static fields work the same way:
+// ❌ Not truly lazy (created at class definition)
+@InjectLazy(ExpensiveService) static #service
+
+// ✅ Truly lazy
+@InjectLazy(ExpensiveService) static accessor #service
+```
+
+### Static Field Injection
+
+All injection decorators work with static fields. Static injections are shared across all instances of the class:
+
+```javascript
+import {Factory, Singleton, Inject} from 'decorator-dependency-injection';
+
+@Singleton()
+class SharedConfig {
+  apiUrl = 'https://api.example.com'
 }
+
+@Factory()
+class RequestLogger {
+  static nextId = 0
+  id = ++RequestLogger.nextId
+}
+
+class ApiService {
+  @Inject(SharedConfig) static config  // Shared across all instances
+  @Inject(RequestLogger) logger        // New instance per ApiService
+
+  getUrl() {
+    return ApiService.config.apiUrl
+  }
+}
+
+const a = new ApiService()
+const b = new ApiService()
+console.log(a.logger.id)  // 1
+console.log(b.logger.id)  // 2
+console.log(ApiService.config === ApiService.config)  // true (singleton)
 ```
 
+### Additional Supported Features
+
+The injection decorators also support:
+
+- **Computed property names**: `@Inject(Dep) [dynamicPropertyName]`
+- **Symbol property names**: `@Inject(Dep) [Symbol('key')]`
+- **Inheritance**: Subclasses inherit parent class injections
+- **Multiple decorators**: Combine `@Inject` with other decorators
+- **Nested injection**: Singletons/Factories can have their own injected dependencies
+
 ## Passing parameters to a dependency
 
 You can pass parameters to a dependency by using the ```@Inject``` decorator with a function that returns the
@@ -138,9 +298,9 @@ will only be passed to the dependency the first time it is created.
 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'
@@ -177,18 +337,91 @@ The `resetMock` utility function allows you to remove any active mock for a depe
 implementation. This is useful for cleaning up after tests or switching between real and mock dependencies.
 
 ```javascript
-import {resetMock} from 'decorator-dependency-injection';
+import {resetMock, resetMocks} from 'decorator-dependency-injection';
 
 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
+```
+
+### Validation Helpers
+
+The library provides utilities to validate registrations at runtime, which is useful for catching configuration 
+errors early:
+
+#### `isRegistered(clazzOrName)`
+
+Check if a class or name is registered:
+
+```javascript
+import {Singleton, isRegistered} from 'decorator-dependency-injection';
+
+@Singleton()
+class MyService {}
+
+console.log(isRegistered(MyService));       // true
+console.log(isRegistered('unknownName'));   // false
+```
+
+#### `validateRegistrations(...tokens)`
+
+Validate multiple registrations at once. Throws an error with helpful details if any are missing:
+
+```javascript
+import {validateRegistrations} from 'decorator-dependency-injection';
+
+// At application startup - fail fast if dependencies are missing
+try {
+  validateRegistrations(UserService, AuthService, 'databaseConnection');
+} catch (err) {
+  // Error: Missing registrations: [UserService, databaseConnection]. 
+  //        Ensure these classes are decorated with @Singleton() or @Factory() before use.
+}
+```
+
+This is particularly useful in:
+- Application bootstrap to catch missing dependencies before runtime failures
+- Test setup to ensure mocks are properly configured
+- Module initialization to validate external dependencies
+
+### Debug Mode
+
+Enable debug logging to understand the injection lifecycle:
+
+```javascript
+import {setDebug} from 'decorator-dependency-injection';
+
+setDebug(true);
+
+// Now logs will appear when:
+// - Classes are registered: [DI] Registered singleton: UserService
+// - Instances are created: [DI] Creating singleton: UserService
+// - Cached singletons are returned: [DI] Returning cached singleton: UserService
+// - Mocks are registered: [DI] Mocked UserService with MockUserService
 ```
 
+This is helpful for:
+- Debugging injection order issues
+- Understanding when instances are created (eager vs lazy)
+- Troubleshooting circular dependencies
+- Verifying test mocks are applied correctly
+
 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, resetMock} from 'decorator-dependency-injection'
 
-@Factory
+@Factory()
 class Dependency {
   method() {
     return 'real'
@@ -225,6 +458,62 @@ 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
+```
+
+## TypeScript Support
+
+The library includes TypeScript definitions with helpful type aliases:
+
+```typescript
+import {Constructor, InjectionToken} from 'decorator-dependency-injection';
+
+// Constructor<T> - a class constructor that creates instances of T
+const MyClass: Constructor<MyService> = MyService;
+
+// InjectionToken<T> - either a class or a string name
+const token1: InjectionToken<MyService> = MyService;
+const token2: InjectionToken = 'myServiceName';
+```
+
+All decorator functions and utilities are fully typed with generics for better autocomplete and type safety.
+
 ## Running the tests
 
 To run the tests, run the following command in the project root.
@@ -238,4 +527,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.3 - Added @LazyInject decorator
+- 1.0.3 - Added @InjectLazy decorator
+- 1.0.4 - Added Container abstraction, clearContainer(), TypeScript definitions, improved proxy support
+- 1.0.5 - Added private field and accessor support for @Inject and @InjectLazy, debug mode, validation helpers

package/eslint.config.js

@@ -0,0 +1,77 @@
+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 often "used" by the decorator system (side effects)
+      // rather than being referenced directly. Also allow underscore-prefixed vars.
+      "no-unused-vars": ["warn", { 
+        "argsIgnorePattern": "^_", 
+        "varsIgnorePattern": "^_|Mock|Service|Factory|Singleton|Consumer|Injection|Lazy|^[A-Z]$|^[A-Z][0-9]$"
+      }]
+    }
+  }
+]);

package/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Type definitions for decorator-dependency-injection
+ */
+
+/**
+ * A class constructor type.
+ * @template T The instance type
+ */
+export type Constructor<T = any> = new (...args: any[]) => T
+
+/**
+ * Valid injection target: either a class constructor or a string name.
+ */
+export type InjectionToken<T = any> = string | Constructor<T>
+
+/**
+ * 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 {
+  /**
+   * Enable or disable debug logging.
+   * When enabled, logs when instances are created.
+   */
+  setDebug(enabled: boolean): void
+
+  /**
+   * Register a class as a singleton.
+   */
+  registerSingleton<T>(clazz: Constructor<T>, name?: string): void
+
+  /**
+   * Register a class as a factory.
+   */
+  registerFactory<T>(clazz: Constructor<T>, name?: string): void
+
+  /**
+   * Get the context for a given class or name.
+   * @throws Error if the class/name is not registered
+   */
+  getContext<T>(clazzOrName: InjectionToken<T>): InstanceContext
+
+  /**
+   * Check if a class or name is registered.
+   */
+  has<T>(clazzOrName: InjectionToken<T>): boolean
+
+  /**
+   * Get or create an instance based on the context.
+   */
+  getInstance<T>(instanceContext: InstanceContext, params: any[]): T
+
+  /**
+   * Register a mock for an existing class.
+   */
+  registerMock<T>(
+    targetClazzOrName: InjectionToken<T>,
+    mockClazz: Constructor<T>,
+    useProxy?: boolean
+  ): void
+
+  /**
+   * Reset a specific mock to its original class.
+   */
+  resetMock<T>(clazzOrName: InjectionToken<T>): 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
+
+/**
+ * Decorator return type that works for both fields and accessors.
+ * For fields, returns a function that provides the initial value.
+ * For accessors, returns an object with get/set/init.
+ */
+export type FieldOrAccessorDecorator = (
+  target: undefined,
+  context: ClassFieldDecoratorContext | ClassAccessorDecoratorContext
+) => void | ((initialValue: any) => any) | ClassAccessorDecoratorResult<any, any>
+
+/**
+ * Inject a singleton or factory instance into a class field or accessor.
+ * 
+ * Supports:
+ * - Public fields: `@Inject(MyClass) myField`
+ * - Private fields: `@Inject(MyClass) #myField`
+ * - Public accessors: `@Inject(MyClass) accessor myField`
+ * - Private accessors: `@Inject(MyClass) accessor #myField`
+ * 
+ * @param clazzOrName The class or name to inject
+ * @param params Optional parameters to pass to the constructor
+ * 
+ * @example
+ * class MyService {
+ *   @Inject(Database) db
+ *   @Inject(Logger) #logger  // private field
+ *   @Inject(Cache) accessor cache  // accessor (recommended for lazy-like behavior)
+ * }
+ */
+export declare function Inject<T>(
+  clazzOrName: InjectionToken<T>,
+  ...params: any[]
+): FieldOrAccessorDecorator
+
+/**
+ * Inject a singleton or factory instance lazily into a class field or accessor.
+ * The instance is created on first access.
+ * 
+ * Supports:
+ * - Public fields: `@InjectLazy(MyClass) myField` (true lazy)
+ * - Private fields: `@InjectLazy(MyClass) #myField` (not truly lazy - use accessor instead)
+ * - Public accessors: `@InjectLazy(MyClass) accessor myField` (true lazy)
+ * - Private accessors: `@InjectLazy(MyClass) accessor #myField` (true lazy, recommended)
+ * 
+ * Note: For true lazy injection with private members, use the accessor syntax:
+ * `@InjectLazy(MyClass) accessor #myField`
+ * 
+ * @param clazzOrName The class or name to inject
+ * @param params Optional parameters to pass to the constructor
+ * 
+ * @example
+ * class MyService {
+ *   @InjectLazy(ExpensiveService) accessor #expensiveService
+ * }
+ */
+export declare function InjectLazy<T>(
+  clazzOrName: InjectionToken<T>,
+  ...params: any[]
+): FieldOrAccessorDecorator
+
+/**
+ * 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<T>(
+  mockedClazzOrName: InjectionToken<T>,
+  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<T>(clazzOrName: InjectionToken<T>): 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
+
+/**
+ * Enable or disable debug logging for dependency injection.
+ * When enabled, logs when instances are registered, created, and mocked.
+ * @param enabled Whether to enable debug mode
+ */
+export declare function setDebug(enabled: boolean): void
+
+/**
+ * Check if a class or name is registered in the default container.
+ * Useful for validation before injection.
+ * @param clazzOrName The class or name to check
+ * @returns true if registered, false otherwise
+ */
+export declare function isRegistered<T>(clazzOrName: InjectionToken<T>): boolean
+
+/**
+ * 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 tokens Array of classes or names to validate
+ * @throws Error if any token is not registered
+ */
+export declare function validateRegistrations<T extends InjectionToken[]>(...tokens: T): void
+
+/**
+ * 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