decorator-dependency-injection 1.0.4 → 1.0.6

package/README.md

@@ -110,6 +110,165 @@ class Consumer {
 }
 ```
 
+### 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
@@ -194,6 +353,113 @@ import {clearContainer} from 'decorator-dependency-injection';
 clearContainer(); // Removes all registered singletons, factories, and mocks
 ```
 
+### Resolving Dependencies Without Decorators
+
+The `resolve` function allows non-class code (plain functions, modules, callbacks, etc.) to retrieve instances from the DI container:
+
+```javascript
+import {Singleton, Factory, resolve} from 'decorator-dependency-injection';
+
+@Singleton()
+class UserService {
+  getUser(id) {
+    return { id, name: 'John' }
+  }
+}
+
+@Factory()
+class Logger {
+  constructor(prefix) {
+    this.prefix = prefix
+  }
+  log(msg) {
+    console.log(`[${this.prefix}] ${msg}`)
+  }
+}
+
+// Use in plain functions
+function handleRequest(req) {
+  const userService = resolve(UserService)
+  return userService.getUser(req.userId)
+}
+
+// Use with factory parameters
+function createLogger(moduleName) {
+  return resolve(Logger, moduleName)
+}
+
+// Use with named registrations
+const db = resolve('databaseConnection')
+```
+
+This is useful when:
+- Integrating with frameworks that don't support decorators
+- Writing utility functions that need DI access
+- Bridging between decorator-based and non-decorator code
+- Testing or debugging the container directly
+
+### 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.
 
@@ -276,6 +542,23 @@ 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.
@@ -290,4 +573,6 @@ npm test
 - 1.0.1 - Automated release with GitHub Actions
 - 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
+- 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
+- 1.0.6 - Added resolve() function for non-decorator code

package/eslint.config.js

@@ -66,8 +66,12 @@ export default defineConfig([
       }
     },
     rules: {
-      // In tests, decorated classes are used by the decorator system, not directly
-      "no-unused-vars": ["warn", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }]
+      // 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

@@ -2,6 +2,17 @@
  * 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
  */
@@ -22,44 +33,57 @@ export interface InstanceContext {
  * 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(clazz: new (...args: any[]) => any, name?: string): void
+  registerSingleton<T>(clazz: Constructor<T>, name?: string): void
 
   /**
    * Register a class as a factory.
    */
-  registerFactory(clazz: new (...args: any[]) => any, name?: string): void
+  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(clazzOrName: string | (new (...args: any[]) => any)): InstanceContext
+  getContext<T>(clazzOrName: InjectionToken<T>): InstanceContext
 
   /**
    * Check if a class or name is registered.
    */
-  has(clazzOrName: string | (new (...args: any[]) => any)): boolean
+  has<T>(clazzOrName: InjectionToken<T>): boolean
+
+  /**
+   * Resolve and return an instance by class or name.
+   * This allows non-decorator code to retrieve instances from the container.
+   */
+  resolve<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
 
   /**
    * Get or create an instance based on the context.
    */
-  getInstance(instanceContext: InstanceContext, params: any[]): any
+  getInstance<T>(instanceContext: InstanceContext, params: any[]): T
 
   /**
    * Register a mock for an existing class.
    */
-  registerMock(
-    targetClazzOrName: string | (new (...args: any[]) => any),
-    mockClazz: new (...args: any[]) => any,
+  registerMock<T>(
+    targetClazzOrName: InjectionToken<T>,
+    mockClazz: Constructor<T>,
     useProxy?: boolean
   ): void
 
   /**
    * Reset a specific mock to its original class.
    */
-  resetMock(clazzOrName: string | (new (...args: any[]) => any)): void
+  resetMock<T>(clazzOrName: InjectionToken<T>): void
 
   /**
    * Reset all mocks to their original classes.
@@ -85,33 +109,72 @@ export declare function Singleton(name?: string): ClassDecorator
 export declare function Factory(name?: string): ClassDecorator
 
 /**
- * Inject a singleton or factory instance into a class field.
+ * 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: string | (new (...args: any[]) => T),
+  clazzOrName: InjectionToken<T>,
   ...params: any[]
-): PropertyDecorator
+): FieldOrAccessorDecorator
 
 /**
- * Inject a singleton or factory instance lazily into a class field.
+ * 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: string | (new (...args: any[]) => T),
+  clazzOrName: InjectionToken<T>,
   ...params: any[]
-): PropertyDecorator
+): 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(
-  mockedClazzOrName: string | (new (...args: any[]) => any),
+export declare function Mock<T>(
+  mockedClazzOrName: InjectionToken<T>,
   proxy?: boolean
 ): ClassDecorator
 
@@ -124,7 +187,7 @@ 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
+export declare function resetMock<T>(clazzOrName: InjectionToken<T>): void
 
 /**
  * Clear all registered instances and mocks from the container.
@@ -136,6 +199,53 @@ export declare function clearContainer(): void
  */
 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
+
+/**
+ * Resolve and return an instance by class or name.
+ * This allows non-decorator code (plain functions, modules, etc.) to retrieve
+ * instances from the DI container.
+ *
+ * @param clazzOrName The class or name to resolve
+ * @param params Optional parameters to pass to the constructor
+ * @returns The resolved instance
+ * @throws Error if the class or name is not registered
+ *
+ * @example
+ * // In a plain function:
+ * function handleRequest(req: Request) {
+ *   const userService = resolve(UserService)
+ *   return userService.getUser(req.userId)
+ * }
+ *
+ * @example
+ * // With a named registration:
+ * const db = resolve<Database>('database')
+ */
+export declare function resolve<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
+
 /**
  * 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.

package/index.js

@@ -11,6 +11,34 @@ import {Container} from './src/Container.js'
 /** @type {Container} The default global container */
 const defaultContainer = new Container()
 
+/**
+ * Creates a lazy accessor descriptor with WeakMap-based caching.
+ * @param {WeakMap} cache - WeakMap for per-instance caching
+ * @param {Function} getValue - Factory function to create the value
+ * @param {string} name - The accessor name for error messages
+ * @returns {{init: Function, get: Function, set: Function}} Accessor descriptor
+ * @private
+ */
+function createLazyAccessor(cache, getValue, name) {
+  return {
+    init(initialValue) {
+      if (initialValue) {
+        throw new Error(`Cannot assign value to injected accessor "${name}"`)
+      }
+      return undefined
+    },
+    get() {
+      if (!cache.has(this)) {
+        cache.set(this, getValue())
+      }
+      return cache.get(this)
+    },
+    set() {
+      throw new Error(`Cannot assign value to injected accessor "${name}"`)
+    }
+  }
+}
+
 /**
  * Register a class as a singleton. If a name is provided, it will be used as the key in the singleton map.
  * Singleton instances only ever have one instance created via the @Inject decorator.
@@ -63,26 +91,44 @@ export function Factory(name) {
  * Inject a singleton or factory instance into a class field. You can also provide parameters to the constructor.
  * If the instance is a singleton, it will only be created once with the first set of parameters it encounters.
  *
+ * Supports:
+ * - Public fields: @Inject(MyClass) myField
+ * - Private fields: @Inject(MyClass) #myField
+ * - Accessors: @Inject(MyClass) accessor myField
+ * - Private accessors: @Inject(MyClass) accessor #myField
+ *
  * @param {string|Function} clazzOrName The singleton or factory class or name
  * @param {...*} params Parameters to pass to the constructor. Recommended to use only with factories.
  * @returns {(function(*, {kind: string, name: string}): function(): Object)}
  * @example @Inject(MySingleton) mySingleton
  * @example @Inject("myCustomName") myFactory
- * @throws {Error} If the injection target is not a field
+ * @example @Inject(MyService) #privateService
+ * @example @Inject(MyService) accessor myService
+ * @throws {Error} If the injection target is not a field or accessor
  * @throws {Error} If the injected field is assigned a value
  */
 export function Inject(clazzOrName, ...params) {
   return function (_, 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')
-      }
+    const getValue = () => {
       const instanceContext = defaultContainer.getContext(clazzOrName)
       return defaultContainer.getInstance(instanceContext, params)
     }
+
+    if (context.kind === 'field') {
+      return function (initialValue) {
+        if (initialValue) {
+          throw new Error(`Cannot assign value to injected field "${context.name}"`)
+        }
+        return getValue()
+      }
+    }
+
+    if (context.kind === 'accessor') {
+      const cache = new WeakMap()
+      return createLazyAccessor(cache, getValue, context.name)
+    }
+
+    throw new Error('Invalid injection target: @Inject can only be used on fields or accessors')
   }
 }
 
@@ -90,37 +136,74 @@ export function Inject(clazzOrName, ...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.
  *
+ * The lazy injection defers instantiation until the field is first accessed. This is useful for:
+ * - Breaking circular dependencies
+ * - Deferring expensive initializations
+ *
+ * Supports:
+ * - Public fields: @InjectLazy(MyClass) myField
+ * - Private fields: @InjectLazy(MyClass) #myField
+ * - Accessors: @InjectLazy(MyClass) accessor myField
+ * - Private accessors: @InjectLazy(MyClass) accessor #myField
+ *
+ * Note: For private fields, the lazy behavior is achieved through the field initializer
+ * returning a getter-based proxy. For accessors, it's achieved through the accessor's
+ * get/set methods directly.
+ *
  * @param {string|Function} clazzOrName The singleton or factory class or name
  * @param {...*} params Parameters to pass to the constructor. Recommended to use only with factories.
  * @returns {(function(*, {kind: string, name: string, addInitializer: Function}): void)}
  * @example @InjectLazy(MySingleton) mySingleton
  * @example @InjectLazy("myCustomName") myFactory
- * @throws {Error} If the injection target is not a field
+ * @example @InjectLazy(MyService) #privateService
+ * @throws {Error} If the injection target is not a field or accessor
  * @throws {Error} If the injected field is assigned a value
  */
 export function InjectLazy(clazzOrName, ...params) {
   const cache = new WeakMap()
+
+  const getValue = () => {
+    const instanceContext = defaultContainer.getContext(clazzOrName)
+    return defaultContainer.getInstance(instanceContext, params)
+  }
+
   return (_, 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 = defaultContainer.getContext(clazzOrName)
-            const value = defaultContainer.getInstance(instanceContext, params)
-            cache.set(this, value)
+    if (context.kind === 'field') {
+      // For private fields, we cannot use Object.defineProperty to create a lazy getter.
+      // Instead, we eagerly create the value. For true lazy behavior, use accessor syntax.
+      if (context.private) {
+        return function (initialValue) {
+          if (initialValue) {
+            throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
           }
-          return cache.get(this)
-        },
-        set() {
-          throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
-        },
-        configurable: true,
-        enumerable: true
+          return getValue()
+        }
+      }
+
+      // For public fields, use Object.defineProperty for true lazy behavior
+      context.addInitializer(function () {
+        Object.defineProperty(this, context.name, {
+          get() {
+            if (!cache.has(this)) {
+              cache.set(this, getValue())
+            }
+            return cache.get(this)
+          },
+          set() {
+            throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
+          },
+          configurable: true,
+          enumerable: true
+        })
       })
-    })
+      return
+    }
+
+    if (context.kind === 'accessor') {
+      return createLazyAccessor(cache, getValue, context.name)
+    }
+
+    throw new Error('Invalid injection target: @InjectLazy can only be used on fields or accessors')
   }
 }
 
@@ -179,6 +262,84 @@ export function getContainer() {
   return defaultContainer
 }
 
+/**
+ * Enable or disable debug logging for dependency injection.
+ * When enabled, logs when instances are registered, created, and mocked.
+ *
+ * @param {boolean} enabled Whether to enable debug mode
+ * @example
+ * setDebug(true)
+ * // [DI] Registered singleton: UserService
+ * // [DI] Creating singleton: UserService
+ */
+export function setDebug(enabled) {
+  defaultContainer.setDebug(enabled)
+}
+
+/**
+ * Check if a class or name is registered in the default container.
+ * Useful for validation before injection.
+ *
+ * @param {string|Function} clazzOrName The class or name to check
+ * @returns {boolean} true if registered, false otherwise
+ * @example
+ * if (!isRegistered(MyService)) {
+ *   console.warn('MyService not registered!')
+ * }
+ */
+export function isRegistered(clazzOrName) {
+  return defaultContainer.has(clazzOrName)
+}
+
+/**
+ * Validate that all provided injection tokens are registered.
+ * Throws an error with details about missing registrations.
+ * Useful for fail-fast validation at application startup.
+ *
+ * @param {...(string|Function)} tokens Classes or names to validate
+ * @throws {Error} If any token is not registered
+ * @example
+ * // At app startup:
+ * validateRegistrations(UserService, AuthService, 'databaseConnection')
+ */
+export function validateRegistrations(...tokens) {
+  const missing = tokens.filter(token => !defaultContainer.has(token))
+  if (missing.length > 0) {
+    const names = missing.map(t => typeof t === 'string' ? t : t.name).join(', ')
+    throw new Error(
+      `Missing registrations: [${names}]. ` +
+      `Ensure these classes are decorated with @Singleton() or @Factory() before use.`
+    )
+  }
+}
+
+/**
+ * Resolve and return an instance by class or name.
+ * This allows non-decorator code (plain functions, modules, etc.) to retrieve
+ * instances from the DI container.
+ *
+ * @template T
+ * @param {string|Function} clazzOrName The class or name to resolve
+ * @param {...*} params Parameters to pass to the constructor
+ * @returns {T} The resolved instance
+ * @throws {Error} If the class or name is not registered
+ * @example
+ * // In a plain function:
+ * function handleRequest(req) {
+ *   const userService = resolve(UserService)
+ *   return userService.getUser(req.userId)
+ * }
+ * @example
+ * // With a named registration:
+ * const db = resolve('database')
+ * @example
+ * // With factory parameters:
+ * const logger = resolve(Logger, 'my-module')
+ */
+export function resolve(clazzOrName, ...params) {
+  return defaultContainer.resolve(clazzOrName, ...params)
+}
+
 // Export Container class for advanced use cases (e.g., isolated containers)
 export {Container}
 

package/package.json

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

package/src/Container.js

@@ -18,6 +18,29 @@ export class Container {
   /** @type {Map<string|Function, InstanceContext>} */
   #instances = new Map()
 
+  /** @type {boolean} Enable debug logging */
+  #debug = false
+
+  /**
+   * Enable or disable debug logging.
+   * When enabled, logs when instances are created.
+   * @param {boolean} enabled Whether to enable debug mode
+   */
+  setDebug(enabled) {
+    this.#debug = enabled
+  }
+
+  /**
+   * Log a debug message if debug mode is enabled.
+   * @param {string} message The message to log
+   * @private
+   */
+  #log(message) {
+    if (this.#debug) {
+      console.log(`[DI] ${message}`)
+    }
+  }
+
   /**
    * Register a class as a singleton.
    * @param {Function} clazz The class constructor
@@ -52,6 +75,7 @@ export class Container {
       )
     }
     this.#instances.set(key, {clazz, type})
+    this.#log(`Registered ${type}: ${name || clazz.name}`)
   }
 
   /**
@@ -82,6 +106,20 @@ export class Container {
     return this.#instances.has(clazzOrName)
   }
 
+  /**
+   * Resolve and return an instance by class or name.
+   * This allows non-decorator code to retrieve instances from the container.
+   * @template T
+   * @param {string|Function} clazzOrName The class or name to resolve
+   * @param {...*} params Parameters to pass to the constructor
+   * @returns {T} The resolved instance
+   * @throws {Error} If the class or name is not registered
+   */
+  resolve(clazzOrName, ...params) {
+    const instanceContext = this.getContext(clazzOrName)
+    return this.getInstance(instanceContext, params)
+  }
+
   /**
    * Get or create an instance based on the context.
    * @param {InstanceContext} instanceContext The instance context
@@ -90,11 +128,13 @@ export class Container {
    */
   getInstance(instanceContext, params) {
     if (instanceContext.type === 'singleton' && !instanceContext.originalClazz && instanceContext.instance) {
+      this.#log(`Returning cached singleton: ${instanceContext.clazz.name}`)
       return instanceContext.instance
     }
 
     let instance
     try {
+      this.#log(`Creating ${instanceContext.type}: ${instanceContext.clazz.name}`)
       instance = new instanceContext.clazz(...params)
     } catch (err) {
       if (err instanceof RangeError) {
@@ -132,6 +172,8 @@ export class Container {
     instanceContext.originalClazz = instanceContext.clazz
     instanceContext.proxy = useProxy
     instanceContext.clazz = mockClazz
+    const targetName = typeof targetClazzOrName === 'string' ? targetClazzOrName : targetClazzOrName.name
+    this.#log(`Mocked ${targetName} with ${mockClazz.name}${useProxy ? ' (proxy)' : ''}`)
   }
 
   /**
@@ -140,8 +182,7 @@ export class Container {
    * @throws {Error} If the class or name is not registered
    */
   resetMock(clazzOrName) {
-    const key = typeof clazzOrName === 'string' ? clazzOrName : clazzOrName
-    this.#restoreOriginal(this.#instances.get(key), clazzOrName)
+    this.#restoreOriginal(this.#instances.get(clazzOrName), clazzOrName)
   }
 
   /**