decorator-dependency-injection 1.0.5 → 1.0.7

package/index.d.ts

@@ -29,10 +29,43 @@ export interface InstanceContext {
   proxy?: boolean
 }
 
+/**
+ * Registration info returned by list()
+ */
+export interface RegistrationInfo {
+  /** The registration key (class or string name) */
+  key: string | Constructor
+  /** Human-readable name */
+  name: string
+  /** Registration type */
+  type: 'singleton' | 'factory'
+  /** Whether this registration is mocked */
+  isMocked: boolean
+  /** Whether a cached instance exists */
+  hasInstance: boolean
+}
+
 /**
  * A dependency injection container that manages singleton and factory instances.
  */
 export declare class Container {
+  /**
+   * Custom string tag for better debugging.
+   * Shows as [object Container] in console.
+   */
+  readonly [Symbol.toStringTag]: 'Container'
+
+  /**
+   * Make the container iterable.
+   * Yields registration info for each registered class.
+   */
+  [Symbol.iterator](): IterableIterator<RegistrationInfo>
+
+  /**
+   * Get the number of registrations in the container.
+   */
+  readonly size: number
+
   /**
    * Enable or disable debug logging.
    * When enabled, logs when instances are created.
@@ -60,6 +93,28 @@ export declare class Container {
    */
   has<T>(clazzOrName: InjectionToken<T>): boolean
 
+  /**
+   * Check if a class or name has a mock registered.
+   */
+  isMocked<T>(clazzOrName: InjectionToken<T>): boolean
+
+  /**
+   * Unregister a class or name from the container.
+   * @returns true if the registration was removed, false if it wasn't registered
+   */
+  unregister<T>(clazzOrName: InjectionToken<T>): boolean
+
+  /**
+   * List all registrations in the container.
+   */
+  list(): RegistrationInfo[]
+
+  /**
+   * 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.
    */
@@ -68,26 +123,49 @@ export declare class Container {
   /**
    * Register a mock for an existing class.
    */
-  registerMock<T>(
-    targetClazzOrName: InjectionToken<T>,
-    mockClazz: Constructor<T>,
-    useProxy?: boolean
-  ): void
+  registerMock<T>(targetClazzOrName: InjectionToken<T>, mockClazz: Constructor<Partial<T>>, useProxy?: boolean): void
+
+  /**
+   * Get the mock instance for a mocked class.
+   * @throws Error if the class is not mocked
+   */
+  getMockInstance<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
+
+  /**
+   * Remove a specific mock and restore the original class.
+   * This completely removes the mock - it does NOT clear mock call history.
+   */
+  removeMock<T>(clazzOrName: InjectionToken<T>): void
 
   /**
-   * Reset a specific mock to its original class.
+   * Remove all mocks and restore original classes.
+   * This completely removes all mocks - it does NOT clear mock call history.
+   */
+  removeAllMocks(): void
+
+  /**
+   * @deprecated Use removeMock() instead. This will be removed in a future version.
+   * WARNING: This removes the mock, it does NOT clear mock call history.
    */
   resetMock<T>(clazzOrName: InjectionToken<T>): void
 
   /**
-   * Reset all mocks to their original classes.
+   * @deprecated Use removeAllMocks() instead. This will be removed in a future version.
+   * WARNING: This removes all mocks, it does NOT clear mock call history.
    */
   resetAllMocks(): void
 
+  /**
+   * Reset singleton instances without removing registrations.
+   * Mock registrations are preserved by default.
+   */
+  resetSingletons(options?: { preserveMocks?: boolean }): void
+
   /**
    * Clear all registered instances and mocks.
+   * @param options.preserveRegistrations If true, keeps all registrations but clears cached instances.
    */
-  clear(): void
+  clear(options?: { preserveRegistrations?: boolean }): void
 }
 
 /**
@@ -164,8 +242,33 @@ export declare function InjectLazy<T>(
 
 /**
  * Mark a class as a mock for another class.
+ * The mock class can implement only the methods you need (Partial<T>).
+ * 
  * @param mockedClazzOrName The class or name to mock
- * @param proxy If true, unmocked methods delegate to the original
+ * @param proxy If true, unmocked methods delegate to the original implementation
+ * 
+ * @example Basic mocking
+ * ```ts
+ * @Mock(UserService)
+ * class MockUserService {
+ *   // Only implement methods you need to mock
+ *   getUser() { return { id: 1, name: 'Test' } }
+ * }
+ * ```
+ * 
+ * @example With hoisted mock functions (Vitest/Jest)
+ * ```ts
+ * const mockGetUser = vi.hoisted(() => vi.fn())
+ * 
+ * @Mock(UserService)
+ * class MockUserService {
+ *   getUser = mockGetUser
+ * }
+ * 
+ * beforeEach(() => {
+ *   mockGetUser.mockClear() // Clear call history, not removeMock()
+ * })
+ * ```
  */
 export declare function Mock<T>(
   mockedClazzOrName: InjectionToken<T>,
@@ -173,20 +276,46 @@ export declare function Mock<T>(
 ): ClassDecorator
 
 /**
- * Reset all mocks to their original classes.
+ * Remove all mocks and restore original classes.
+ * This completely removes all mocks - it does NOT clear mock call history.
+ */
+export declare function removeAllMocks(): void
+
+/**
+ * Remove a specific mock and restore the original class.
+ * This completely removes the mock - it does NOT clear mock call history.
+ * @param clazzOrName The class or name to restore
+ */
+export declare function removeMock<T>(clazzOrName: InjectionToken<T>): void
+
+/**
+ * @deprecated Use removeAllMocks() instead. This will be removed in a future version.
+ * WARNING: This removes all mocks, it does NOT clear mock call history.
  */
 export declare function resetMocks(): void
 
 /**
- * Reset a specific mock to its original class.
- * @param clazzOrName The class or name to reset
+ * @deprecated Use removeMock() instead. This will be removed in a future version.
+ * WARNING: This removes the mock, it does NOT clear mock call history.
+ * @param clazzOrName The class or name to restore
  */
 export declare function resetMock<T>(clazzOrName: InjectionToken<T>): void
 
+/**
+ * Reset singleton instances without removing registrations.
+ * Mock registrations are preserved by default.
+ * 
+ * Ideal for test isolation where you want fresh instances but keep mocks.
+ * 
+ * @param options.preserveMocks If true (default), keeps mock registrations
+ */
+export declare function resetSingletons(options?: { preserveMocks?: boolean }): void
+
 /**
  * Clear all registered instances and mocks from the container.
+ * @param options.preserveRegistrations If true, keeps all registrations but clears cached instances.
  */
-export declare function clearContainer(): void
+export declare function clearContainer(options?: { preserveRegistrations?: boolean }): void
 
 /**
  * Get the default container instance.
@@ -208,6 +337,43 @@ export declare function setDebug(enabled: boolean): void
  */
 export declare function isRegistered<T>(clazzOrName: InjectionToken<T>): boolean
 
+/**
+ * Check if a class or name has a mock registered.
+ * @param clazzOrName The class or name to check
+ * @returns true if mocked, false otherwise
+ */
+export declare function isMocked<T>(clazzOrName: InjectionToken<T>): boolean
+
+/**
+ * Get the mock instance for a mocked class.
+ * Useful for configuring mock behavior dynamically in tests.
+ * 
+ * @param clazzOrName The original class or name that was mocked
+ * @param params Parameters to pass to the constructor
+ * @returns The mock instance
+ * @throws Error if the class is not mocked
+ * 
+ * @example
+ * ```ts
+ * const mock = getMockInstance(UserService)
+ * mock.getUser.mockReturnValue({ id: 1 })
+ * ```
+ */
+export declare function getMockInstance<T>(clazzOrName: InjectionToken<T>, ...params: any[]): T
+
+/**
+ * Unregister a class or name from the container.
+ * @param clazzOrName The class or name to unregister
+ * @returns true if the registration was removed, false if it wasn't registered
+ */
+export declare function unregister<T>(clazzOrName: InjectionToken<T>): boolean
+
+/**
+ * List all registrations in the container.
+ * Useful for debugging and introspection.
+ */
+export declare function listRegistrations(): RegistrationInfo[]
+
 /**
  * Validate that all provided injection tokens are registered.
  * Throws an error with details about missing registrations.
@@ -217,6 +383,29 @@ export declare function isRegistered<T>(clazzOrName: InjectionToken<T>): boolean
  */
 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

@@ -28,10 +28,7 @@ function createLazyAccessor(cache, getValue, name) {
       return undefined
     },
     get() {
-      if (!cache.has(this)) {
-        cache.set(this, getValue())
-      }
-      return cache.get(this)
+      return cache.get(this) ?? (cache.set(this, getValue()), cache.get(this))
     },
     set() {
       throw new Error(`Cannot assign value to injected accessor "${name}"`)
@@ -52,7 +49,7 @@ function createLazyAccessor(cache, getValue, name) {
  * @throws {Error} If the target is not a class constructor
  */
 export function Singleton(name) {
-  return function (clazz, context) {
+  return (clazz, context) => {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
@@ -76,7 +73,7 @@ export function Singleton(name) {
  * @throws {Error} If the target is not a class constructor
  */
 export function Factory(name) {
-  return function (clazz, context) {
+  return (clazz, context) => {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
@@ -108,14 +105,14 @@ export function Factory(name) {
  * @throws {Error} If the injected field is assigned a value
  */
 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) {
+      return (initialValue) => {
         if (initialValue) {
           throw new Error(`Cannot assign value to injected field "${context.name}"`)
         }
@@ -172,7 +169,7 @@ 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) {
+        return (initialValue) => {
           if (initialValue) {
             throw new Error(`Cannot assign value to lazy-injected field "${context.name}"`)
           }
@@ -208,19 +205,70 @@ export function InjectLazy(clazzOrName, ...params) {
 }
 
 /**
- * Mark a class as a mock. This will replace the class with a mock instance when injected.
+ * Mark a class as a mock. This will replace the original class with the mock when injected.
+ * The mock registration persists until explicitly removed with removeMock() or removeAllMocks().
  *
  * @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 {}
+ * 
+ * @example Basic mocking
+ * ```js
+ * @Mock(MySingleton)
+ * class MockedSingleton {
+ *   doSomething() { return 'mocked result' }
+ * }
+ * ```
+ * 
+ * @example Proxy mocking (partial mock)
+ * ```js
+ * // Only override specific methods, others delegate to original
+ * @Mock(MySingleton, true)
+ * class PartialMock {
+ *   onlyThisMethod() { return 'mocked' }
+ *   // All other methods call the original implementation
+ * }
+ * ```
+ * 
+ * @example Testing pattern with hoisted mock functions
+ * ```js
+ * // Hoist mock functions for per-test configuration
+ * const mockMethod = vi.hoisted(() => vi.fn())
+ * 
+ * @Mock(MyService)
+ * class MockMyService {
+ *   doSomething = mockMethod
+ * }
+ * 
+ * beforeEach(() => {
+ *   // Clear call history - NOT removeMock() which removes the mock entirely
+ *   mockMethod.mockClear()
+ * })
+ * 
+ * it('should call the service', () => {
+ *   mockMethod.mockReturnValue('test value')
+ *   // ... your test
+ *   expect(mockMethod).toHaveBeenCalled()
+ * })
+ * ```
+ * 
+ * @example Cleanup in afterEach
+ * ```js
+ * afterEach(() => {
+ *   // Option 1: Remove all mocks and restore originals
+ *   removeAllMocks()
+ *   
+ *   // Option 2: Just clear singleton instances, keep mocks registered
+ *   resetSingletons()
+ * })
+ * ```
+ * 
  * @throws {Error} If the injection target is not a class
  * @throws {Error} If the injection source is not found
  */
 export function Mock(mockedClazzOrName, proxy = false) {
-  return function (clazz, context) {
+  return (clazz, context) => {
     if (context.kind !== 'class') {
       throw new Error('Invalid injection target')
     }
@@ -229,27 +277,118 @@ export function Mock(mockedClazzOrName, proxy = false) {
 }
 
 /**
- * Reset all mocks to their original classes.
+ * Remove all mocks and restore original classes.
+ * This completely removes all mocks - it does NOT clear mock call history.
+ * 
+ * If you want to clear call history on mock functions without removing the mock,
+ * call mockClear() on your mock functions instead.
+ * 
+ * @example
+ * ```js
+ * afterEach(() => {
+ *   removeAllMocks() // Restores original classes
+ * })
+ * ```
+ */
+export function removeAllMocks() {
+  defaultContainer.removeAllMocks()
+}
+
+/**
+ * Remove a specific mock and restore the original class.
+ * This completely removes the mock - it does NOT clear mock call history.
+ *
+ * @param {string|Function} clazzOrName The singleton or factory class or name to restore
+ * 
+ * @example
+ * ```js
+ * removeMock(UserService) // Restores original UserService
+ * ```
+ */
+export function removeMock(clazzOrName) {
+  defaultContainer.removeMock(clazzOrName)
+}
+
+/**
+ * @deprecated Use removeAllMocks() instead. This will be removed in a future version.
+ * 
+ * WARNING: Despite the name, this does NOT reset mock call history like mockClear().
+ * It completely removes all mocks and restores the original classes.
  */
 export function resetMocks() {
-  defaultContainer.resetAllMocks()
+  console.warn(
+    '[DI] resetMocks() is deprecated. Use removeAllMocks() instead. ' +
+    'Note: This removes mocks entirely, NOT clearing call history.'
+  )
+  defaultContainer.removeAllMocks()
 }
 
 /**
- * Reset a specific mock to its original class.
+ * @deprecated Use removeMock() instead. This will be removed in a future version.
+ * 
+ * WARNING: Despite the name, this does NOT reset mock call history like mockClear().
+ * It completely removes the mock and restores the original class.
  *
- * @param {string|Function} clazzOrName The singleton or factory class or name to reset
+ * @param {string|Function} clazzOrName The singleton or factory class or name to restore
  */
 export function resetMock(clazzOrName) {
-  defaultContainer.resetMock(clazzOrName)
+  console.warn(
+    '[DI] resetMock() is deprecated. Use removeMock() instead. ' +
+    'Note: This removes the mock entirely, NOT clearing call history.'
+  )
+  defaultContainer.removeMock(clazzOrName)
+}
+
+/**
+ * Reset singleton instances without removing registrations.
+ * This clears cached singleton instances so they will be recreated on next resolve.
+ * Mock registrations are preserved by default.
+ * 
+ * This is ideal for test isolation where you want:
+ * - Fresh singleton instances per test
+ * - Mock registrations to remain intact
+ * 
+ * @param {Object} [options] Options for resetting
+ * @param {boolean} [options.preserveMocks=true] If true, keeps mock registrations.
+ *                                                If false, also removes mocks.
+ * 
+ * @example
+ * ```js
+ * beforeEach(() => {
+ *   // Each test gets fresh singleton instances
+ *   // but mocks remain registered
+ *   resetSingletons()
+ * })
+ * ```
+ */
+export function resetSingletons(options) {
+  defaultContainer.resetSingletons(options)
 }
 
 /**
  * Clear all registered instances and mocks from the container.
- * Useful for complete test isolation between test suites.
+ * 
+ * By default, this removes ALL registrations including @Singleton and @Factory classes.
+ * For just clearing singleton instances without removing any registrations,
+ * use resetSingletons() instead.
+ * 
+ * @param {Object} [options] Options for clearing
+ * @param {boolean} [options.preserveRegistrations=false] If true, keeps all registrations but clears cached instances.
+ * 
+ * @example
+ * ```js
+ * // Complete reset - removes everything
+ * clearContainer()
+ * 
+ * // Clear cached instances but keep registrations (including mocks)
+ * clearContainer({ preserveRegistrations: true })
+ * 
+ * // Just clear singleton instances (preferred for test isolation)
+ * resetSingletons()
+ * ```
  */
-export function clearContainer() {
-  defaultContainer.clear()
+export function clearContainer(options) {
+  defaultContainer.clear(options)
 }
 
 /**
@@ -313,6 +452,119 @@ export function validateRegistrations(...tokens) {
   }
 }
 
+/**
+ * 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)
+}
+
+/**
+ * Get the mock instance for a mocked class.
+ * This is useful when you need to access or configure mock behavior dynamically in tests.
+ * 
+ * Unlike resolve(), this explicitly checks that the class is mocked and provides
+ * better error messages if it's not.
+ *
+ * @template T
+ * @param {string|Function} clazzOrName The original class or name that was mocked
+ * @param {...*} params Parameters to pass to the constructor
+ * @returns {T} The mock instance
+ * @throws {Error} If the class is not registered
+ * @throws {Error} If the class is not mocked
+ * 
+ * @example
+ * ```js
+ * @Mock(UserService)
+ * class MockUserService {
+ *   getUser = vi.fn()
+ * }
+ * 
+ * it('should get user', () => {
+ *   const mock = getMockInstance(UserService)
+ *   mock.getUser.mockReturnValue({ id: 1, name: 'Test' })
+ *   
+ *   // ... test code that uses UserService
+ *   
+ *   expect(mock.getUser).toHaveBeenCalledWith(1)
+ * })
+ * ```
+ */
+export function getMockInstance(clazzOrName, ...params) {
+  return defaultContainer.getMockInstance(clazzOrName, ...params)
+}
+
+/**
+ * Check if a class or name has a mock registered.
+ * Useful for conditional test logic or debugging.
+ *
+ * @param {string|Function} clazzOrName The class or name to check
+ * @returns {boolean} true if a mock is registered, false otherwise
+ * 
+ * @example
+ * ```js
+ * if (isMocked(UserService)) {
+ *   console.log('UserService is mocked')
+ * }
+ * ```
+ */
+export function isMocked(clazzOrName) {
+  return defaultContainer.isMocked(clazzOrName)
+}
+
+/**
+ * Unregister a class or name from the container.
+ * This removes the registration entirely, including any mock.
+ * 
+ * @param {string|Function} clazzOrName The class or name to unregister
+ * @returns {boolean} true if the registration was removed, false if it wasn't registered
+ * 
+ * @example
+ * ```js
+ * unregister(MyService) // Returns true if was registered
+ * ```
+ */
+export function unregister(clazzOrName) {
+  return defaultContainer.unregister(clazzOrName)
+}
+
+/**
+ * List all registrations in the container.
+ * Useful for debugging and introspection.
+ * 
+ * @returns {Array<{key: string|Function, name: string, type: 'singleton'|'factory', isMocked: boolean, hasInstance: boolean}>}
+ * 
+ * @example
+ * ```js
+ * listRegistrations().forEach(reg => {
+ *   console.log(`${reg.name}: ${reg.type}, mocked: ${reg.isMocked}`)
+ * })
+ * ```
+ */
+export function listRegistrations() {
+  return defaultContainer.list()
+}
+
 // Export Container class for advanced use cases (e.g., isolated containers)
 export {Container}
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "decorator-dependency-injection",
-  "version": "1.0.5",
-  "description": "A simple library for dependency injection using decorators",
+  "version": "1.0.7",
+  "description": "Lightweight dependency injection (DI) library using native TC39 Stage 3 decorators. Zero dependencies, built-in mocking, TypeScript support.",
   "author": "Ravi Gairola <mallox@pyxzl.net>",
   "license": "Apache-2.0",
   "repository": {
@@ -16,12 +16,25 @@
     "dependency-injection",
     "di",
     "decorators",
-    "mocking",
+    "tc39-decorators",
+    "stage-3-decorators",
+    "inject",
+    "injectable",
     "singleton",
-    "factory"
+    "factory",
+    "ioc",
+    "inversion-of-control",
+    "container",
+    "mocking",
+    "mock",
+    "testing",
+    "jest",
+    "vitest",
+    "typescript",
+    "service-locator"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "main": "index.js",
   "types": "index.d.ts",