decorator-dependency-injection 1.0.6 → 1.1.0

package/eslint.config.js

@@ -62,7 +62,10 @@ export default defineConfig([
         beforeEach: "readonly",
         afterEach: "readonly",
         jest: "readonly",
-        fail: "readonly"
+        fail: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly",
+        Promise: "readonly"
       }
     },
     rules: {

package/index.d.ts

@@ -1,256 +1,67 @@
-/**
- * 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 interface RegistrationInfo {
+  key: string | Constructor
+  name: string
+  type: 'singleton' | 'factory'
+  isMocked: boolean
+  hasInstance: boolean
+}
+
 export declare class Container {
-  /**
-   * Enable or disable debug logging.
-   * When enabled, logs when instances are created.
-   */
+  readonly [Symbol.toStringTag]: 'Container'
+  [Symbol.iterator](): IterableIterator<RegistrationInfo>
+  readonly size: number
   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
-
-  /**
-   * Resolve and return an instance by class or name.
-   * This allows non-decorator code to retrieve instances from the container.
-   */
+  isMocked<T>(clazzOrName: InjectionToken<T>): boolean
+  unregister<T>(clazzOrName: InjectionToken<T>): boolean
+  list(): RegistrationInfo[]
   resolve<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
-
-  /**
-   * 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
+  registerMock<T>(targetClazzOrName: InjectionToken<T>, mockClazz: Constructor<Partial<T>>, useProxy?: boolean): void
+  getMockInstance<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
+  removeMock<T>(clazzOrName: InjectionToken<T>): void
+  removeAllMocks(): void
+  resetSingletons(options?: { preserveMocks?: boolean }): void
+  clear(options?: { preserveRegistrations?: boolean }): 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 Singleton(name?: string): ClassDecorator
+export declare function Factory(name?: string): ClassDecorator
+export declare function Inject<T>(clazzOrName: InjectionToken<T>, ...params: any[]): FieldOrAccessorDecorator
+export declare function InjectLazy<T>(clazzOrName: InjectionToken<T>, ...params: any[]): FieldOrAccessorDecorator
+export declare function Mock<T>(mockedClazzOrName: InjectionToken<T>, proxy?: boolean): ClassDecorator
+
+export declare function removeAllMocks(): void
+export declare function removeMock<T>(clazzOrName: InjectionToken<T>): void
+export declare function resetSingletons(options?: { preserveMocks?: boolean }): void
+export declare function clearContainer(options?: { preserveRegistrations?: boolean }): 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 isMocked<T>(clazzOrName: InjectionToken<T>): boolean
+export declare function getMockInstance<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
+export declare function unregister<T>(clazzOrName: InjectionToken<T>): boolean
+export declare function listRegistrations(): RegistrationInfo[]
 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.
- *
- * @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
+export declare const defaultContainer: Container

package/index.js

@@ -1,31 +1,15 @@
-/**
- * Decorator Dependency Injection
- *
- * A simple library for dependency injection using TC39 Stage 3 decorators.
- *
- * @module decorator-dependency-injection
- */
-
 import {Container} from './src/Container.js'
 
-/** @type {Container} The default global container */
+/** @type {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
- */
+/** @private */
 function createLazyAccessor(cache, getValue, name) {
   return {
     init(initialValue) {
-      if (initialValue) {
+      if (initialValue !== undefined) {
         throw new Error(`Cannot assign value to injected accessor "${name}"`)
       }
-      return undefined
     },
     get() {
       if (!cache.has(this)) {
@@ -39,20 +23,9 @@ function createLazyAccessor(cache, getValue, 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.
- *
- * @param {string} [name] The name of the singleton. If not provided, the class will be used as the key.
- * @returns {(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 or factory with the same name is already defined
- * @throws {Error} If the target is not a class constructor
- */
+/** @param {string} [name] */
 export function Singleton(name) {
-  return function (clazz, context) {
+  return (clazz, context) => {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
@@ -63,20 +36,9 @@ export function Singleton(name) {
   }
 }
 
-/**
- * Register a class as a factory. If a name is provided, it will be used as the key in the factory map.
- * 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.
- * @returns {(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 or singleton with the same name is already defined
- * @throws {Error} If the target is not a class constructor
- */
+/** @param {string} [name] */
 export function Factory(name) {
-  return function (clazz, context) {
+  return (clazz, context) => {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
@@ -88,35 +50,19 @@ 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
- * @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
+ * @param {string|Function} clazzOrName
+ * @param {...*} params
  */
 export function Inject(clazzOrName, ...params) {
-  return function (_, context) {
+  return (_, context) => {
     const getValue = () => {
       const instanceContext = defaultContainer.getContext(clazzOrName)
       return defaultContainer.getInstance(instanceContext, params)
     }
 
     if (context.kind === 'field') {
-      return function (initialValue) {
-        if (initialValue) {
+      return (initialValue) => {
+        if (initialValue !== undefined) {
           throw new Error(`Cannot assign value to injected field "${context.name}"`)
         }
         return getValue()
@@ -133,31 +79,9 @@ 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
- * @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
+ * Defers instantiation until first access. For private fields, use accessor syntax for true lazy behavior.
+ * @param {string|Function} clazzOrName
+ * @param {...*} params
  */
 export function InjectLazy(clazzOrName, ...params) {
   const cache = new WeakMap()
@@ -172,8 +96,8 @@ export function InjectLazy(clazzOrName, ...params) {
       // 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) {
+        return (initialValue) => {
+          if (initialValue !== undefined) {
             throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
           }
           return getValue()
@@ -208,19 +132,11 @@ export function InjectLazy(clazzOrName, ...params) {
 }
 
 /**
- * Mark a class as a mock. This will replace the class with a mock instance when injected.
- *
- * @param {string|Function} mockedClazzOrName The singleton or factory class or name to be mocked
- * @param {boolean} [proxy=false] If true, the mock will proxy to the original class.
- *                                Any methods not defined in the mock will be called on the original class.
- * @returns {(function(Function, {kind: string}): void)}
- * @example @Mock(MySingleton) class MyMock {}
- * @example @Mock("myCustomName", true) class MyMock {}
- * @throws {Error} If the injection target is not a class
- * @throws {Error} If the injection source is not found
+ * @param {string|Function} mockedClazzOrName
+ * @param {boolean} [proxy=false] If true, unmocked methods delegate to the original
  */
 export function Mock(mockedClazzOrName, proxy = false) {
-  return function (clazz, context) {
+  return (clazz, context) => {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
@@ -228,120 +144,97 @@ export function Mock(mockedClazzOrName, proxy = false) {
   }
 }
 
-/**
- * Reset all mocks to their original classes.
- */
-export function resetMocks() {
-  defaultContainer.resetAllMocks()
+/** Remove all mocks and restore originals. Does NOT clear mock call history. */
+export function removeAllMocks() {
+  defaultContainer.removeAllMocks()
 }
 
-/**
- * Reset a specific mock to its original class.
- *
- * @param {string|Function} clazzOrName The singleton or factory class or name to reset
- */
-export function resetMock(clazzOrName) {
-  defaultContainer.resetMock(clazzOrName)
+/** @param {string|Function} clazzOrName */
+export function removeMock(clazzOrName) {
+  defaultContainer.removeMock(clazzOrName)
 }
 
-/**
- * Clear all registered instances and mocks from the container.
- * Useful for complete test isolation between test suites.
- */
-export function clearContainer() {
-  defaultContainer.clear()
+/** @param {{preserveMocks?: boolean}} [options] */
+export function resetSingletons(options) {
+  defaultContainer.resetSingletons(options)
 }
 
-/**
- * Get the default container instance.
- * Useful for advanced use cases or testing the container itself.
- *
- * @returns {Container} The default container
- */
+/** @param {{preserveRegistrations?: boolean}} [options] */
+export function clearContainer(options) {
+  defaultContainer.clear(options)
+}
+
+/** @returns {Container} */
 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
- */
+/** @param {boolean} enabled */
 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!')
- * }
+ * @param {string|Function} clazzOrName
+ * @returns {boolean}
  */
 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')
- */
+/** @param {...(string|Function)} tokens */
 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.`
-    )
-  }
+  if (missing.length === 0) return
+  
+  const names = missing.map(t => t?.name ?? t).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')
+ * @param {string|Function} clazzOrName
+ * @param {...*} params
+ * @returns {T}
  */
 export function resolve(clazzOrName, ...params) {
   return defaultContainer.resolve(clazzOrName, ...params)
 }
 
-// Export Container class for advanced use cases (e.g., isolated containers)
-export {Container}
+/**
+ * @template T
+ * @param {string|Function} clazzOrName
+ * @param {...*} params
+ * @returns {T}
+ */
+export function getMockInstance(clazzOrName, ...params) {
+  return defaultContainer.getMockInstance(clazzOrName, ...params)
+}
+
+/**
+ * @param {string|Function} clazzOrName
+ * @returns {boolean}
+ */
+export function isMocked(clazzOrName) {
+  return defaultContainer.isMocked(clazzOrName)
+}
+
+/**
+ * @param {string|Function} clazzOrName
+ * @returns {boolean}
+ */
+export function unregister(clazzOrName) {
+  return defaultContainer.unregister(clazzOrName)
+}
 
-// Export createProxy for advanced proxy use cases
+/** @returns {Array<{key: string|Function, name: string, type: 'singleton'|'factory', isMocked: boolean, hasInstance: boolean}>} */
+export function listRegistrations() {
+  return defaultContainer.list()
+}
+
+export {Container}
+export {defaultContainer}
 export {createProxy} from './src/proxy.js'