decorator-dependency-injection 1.0.6 → 1.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "decorator-dependency-injection",
-  "version": "1.0.6",
-  "description": "A simple library for dependency injection using decorators",
+  "version": "1.1.0",
+  "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,20 +16,38 @@
     "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",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
+    },
+    "./middleware": {
+      "types": "./src/integrations/middleware.d.ts",
+      "import": "./src/integrations/middleware.js"
     }
   },
   "scripts": {

package/src/Container.js

@@ -4,7 +4,6 @@
  * @property {Function} clazz - The class constructor for the instance.
  * @property {Function} [originalClazz] - The original class if this is a mock.
  * @property {Object} [instance] - The singleton instance, if created.
- * @property {Object} [originalInstance] - The original instance if this is a mock.
  * @property {boolean} [proxy=false] - If true, the mock will proxy to the original class for undefined methods/properties.
  */
 
@@ -18,23 +17,27 @@ 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
-   */
+  get [Symbol.toStringTag]() {
+    return 'Container'
+  }
+
+  /** @yields {RegistrationInfo} */
+  *[Symbol.iterator]() {
+    yield* this.list()
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.#instances.size
+  }
+
+  /** @param {boolean} enabled */
   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}`)
@@ -42,30 +45,21 @@ export class Container {
   }
 
   /**
-   * Register a class as a singleton.
-   * @param {Function} clazz The class constructor
-   * @param {string} [name] Optional name key
+   * @param {Function} clazz
+   * @param {string} [name]
    */
   registerSingleton(clazz, name) {
     this.#register(clazz, 'singleton', name)
   }
 
   /**
-   * Register a class as a factory.
-   * @param {Function} clazz The class constructor
-   * @param {string} [name] Optional name key
+   * @param {Function} clazz
+   * @param {string} [name]
    */
   registerFactory(clazz, name) {
     this.#register(clazz, 'factory', name)
   }
 
-  /**
-   * Internal registration logic.
-   * @param {Function} clazz The class constructor
-   * @param {'singleton'|'factory'} type The registration type
-   * @param {string} [name] Optional name key
-   * @private
-   */
   #register(clazz, type, name) {
     const key = name ?? clazz
     if (this.#instances.has(key)) {
@@ -79,41 +73,77 @@ export class Container {
   }
 
   /**
-   * Get the context for a given class or name.
-   * @param {string|Function} clazzOrName The class or name to look up
+   * @param {string|Function} clazzOrName
    * @returns {InstanceContext}
-   * @throws {Error} If the context is not found
+   * @throws {Error} If not found
    */
   getContext(clazzOrName) {
-    if (this.#instances.has(clazzOrName)) {
-      return this.#instances.get(clazzOrName)
+    const context = this.#instances.get(clazzOrName)
+    if (context) {
+      return context
     }
-    const available = Array.from(this.#instances.keys())
+    
+    const name = clazzOrName?.name ?? clazzOrName
+    const nameStr = String(name)
+    const available = [...this.#instances.keys()]
       .map(k => typeof k === 'string' ? k : k.name)
       .join(', ')
+    
+    // Detect if this looks like a mock class from a module mocking system
+    const looksLikeMock = /^Mock[A-Z]|mock/i.test(nameStr) || 
+                          nameStr.includes('Mock') ||
+                          nameStr.startsWith('vi_') ||
+                          nameStr.startsWith('jest_')
+    
+    const hint = looksLikeMock
+      ? `\n\nHint: The class name "${name}" suggests this may be a mock created by a module mocking system. ` +
+        `If you're using module mocking (e.g., vi.mock() or jest.mock()), consider using @Mock(OriginalService) instead, ` +
+        `which properly registers with the DI container.`
+      : ''
+    
     throw new Error(
-      `Cannot find injection source for "${clazzOrName?.name || clazzOrName}". ` +
-      `Available: [${available}]`
+      `Cannot find injection source for "${name}". Available: [${available}]${hint}`
     )
   }
 
-  /**
-   * Check if a class or name is registered.
-   * @param {string|Function} clazzOrName The class or name to check
-   * @returns {boolean}
-   */
+  /** @param {string|Function} clazzOrName */
   has(clazzOrName) {
     return this.#instances.has(clazzOrName)
   }
 
+  /** @param {string|Function} clazzOrName */
+  isMocked(clazzOrName) {
+    return !!this.#instances.get(clazzOrName)?.originalClazz
+  }
+
+  /**
+   * @param {string|Function} clazzOrName
+   * @returns {boolean} true if removed
+   */
+  unregister(clazzOrName) {
+    const removed = this.#instances.delete(clazzOrName)
+    if (removed) {
+      this.#log(`Unregistered: ${clazzOrName?.name ?? clazzOrName}`)
+    }
+    return removed
+  }
+
+  /** @returns {Array<{key: string|Function, name: string, type: 'singleton'|'factory', isMocked: boolean, hasInstance: boolean}>} */
+  list() {
+    return [...this.#instances.entries()].map(([key, context]) => ({
+      key,
+      name: typeof key === 'string' ? key : key.name,
+      type: context.type,
+      isMocked: !!context.originalClazz,
+      hasInstance: !!context.instance
+    }))
+  }
+
   /**
-   * 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
+   * @param {string|Function} clazzOrName
+   * @param {...*} params
+   * @returns {T}
    */
   resolve(clazzOrName, ...params) {
     const instanceContext = this.getContext(clazzOrName)
@@ -121,25 +151,24 @@ export class Container {
   }
 
   /**
-   * Get or create an instance based on the context.
-   * @param {InstanceContext} instanceContext The instance context
-   * @param {Array} params Constructor parameters
-   * @returns {Object} The instance
+   * @param {InstanceContext} instanceContext
+   * @param {Array} params
+   * @returns {Object}
    */
   getInstance(instanceContext, params) {
-    if (instanceContext.type === 'singleton' && !instanceContext.originalClazz && instanceContext.instance) {
+    if (instanceContext.type === 'singleton' && instanceContext.instance) {
       this.#log(`Returning cached singleton: ${instanceContext.clazz.name}`)
       return instanceContext.instance
     }
 
+    this.#log(`Creating ${instanceContext.type}: ${instanceContext.clazz.name}`)
     let instance
     try {
-      this.#log(`Creating ${instanceContext.type}: ${instanceContext.clazz.name}`)
       instance = new instanceContext.clazz(...params)
     } catch (err) {
       if (err instanceof RangeError) {
         throw new Error(
-          `Circular dependency detected for ${instanceContext.clazz.name || instanceContext.clazz}. ` +
+          `Circular dependency detected for ${instanceContext.clazz.name ?? instanceContext.clazz}. ` +
           `Use @InjectLazy to break the cycle.`
         )
       }
@@ -159,67 +188,107 @@ export class Container {
   }
 
   /**
-   * Register a mock for an existing class.
-   * @param {string|Function} targetClazzOrName The class or name to mock
-   * @param {Function} mockClazz The mock class
-   * @param {boolean} [useProxy=false] Whether to proxy unmocked methods to original
+   * @param {string|Function} targetClazzOrName
+   * @param {Function} mockClazz
+   * @param {boolean} [useProxy=false]
    */
   registerMock(targetClazzOrName, mockClazz, useProxy = false) {
     const instanceContext = this.getContext(targetClazzOrName)
     if (instanceContext.originalClazz) {
       throw new Error('Mock already defined, reset before mocking again')
     }
-    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)' : ''}`)
+    Object.assign(instanceContext, {
+      originalClazz: instanceContext.clazz,
+      clazz: mockClazz,
+      proxy: useProxy,
+      instance: undefined
+    })
+    this.#log(`Mocked ${targetClazzOrName?.name ?? targetClazzOrName} with ${mockClazz.name}${useProxy ? ' (proxy)' : ''}`)
   }
 
   /**
-   * Reset a specific mock to its original class.
-   * @param {string|Function} clazzOrName The class or name to reset
-   * @throws {Error} If the class or name is not registered
+   * Remove mock and restore original. Does NOT clear mock call history.
+   * @param {string|Function} clazzOrName
    */
-  resetMock(clazzOrName) {
+  removeMock(clazzOrName) {
     this.#restoreOriginal(this.#instances.get(clazzOrName), clazzOrName)
   }
 
+  /** Remove all mocks. Does NOT clear mock call history. */
+  removeAllMocks() {
+    for (const instanceContext of this.#instances.values()) {
+      this.#restoreOriginal(instanceContext)
+    }
+  }
+
   /**
-   * Reset all mocks to their original classes.
+   * Clear cached singleton instances. They'll be recreated on next resolve.
+   * @param {Object} [options]
+   * @param {boolean} [options.preserveMocks=true]
    */
-  resetAllMocks() {
+  resetSingletons(options = {}) {
+    const { preserveMocks = true } = options
+    
     for (const instanceContext of this.#instances.values()) {
-      this.#restoreOriginal(instanceContext)
+      delete instanceContext.instance
+      if (!preserveMocks && instanceContext.originalClazz) {
+        this.#restoreOriginal(instanceContext)
+      }
     }
+    this.#log(`Reset singletons (preserveMocks: ${preserveMocks})`)
   }
 
   /**
-   * Clear all registered instances and mocks.
-   * Useful for test isolation.
+   * Clear all registrations. Use resetSingletons() to keep registrations.
+   * @param {Object} [options]
+   * @param {boolean} [options.preserveRegistrations=false]
    */
-  clear() {
-    this.#instances.clear()
+  clear(options = {}) {
+    const { preserveRegistrations = false } = options
+    
+    if (preserveRegistrations) {
+      for (const instanceContext of this.#instances.values()) {
+        delete instanceContext.instance
+      }
+      this.#log('Cleared instances (preserved registrations)')
+    } else {
+      this.#instances.clear()
+      this.#log('Cleared all registrations')
+    }
   }
 
   /**
-   * Internal function to restore an instance context to its original.
-   * @param {InstanceContext} instanceContext The instance context to reset
-   * @param {string|Function} [clazzOrName] Optional identifier for error messages
-   * @throws {Error} If instanceContext is null or undefined
-   * @private
+   * @template T
+   * @param {string|Function} clazzOrName
+   * @param {...*} params
+   * @returns {T}
+   * @throws {Error} If not mocked
    */
+  getMockInstance(clazzOrName, ...params) {
+    const instanceContext = this.getContext(clazzOrName)
+    
+    if (!instanceContext.originalClazz) {
+      const name = clazzOrName?.name ?? clazzOrName
+      throw new Error(
+        `"${name}" is not mocked. Use @Mock(${name}) to register a mock first.`
+      )
+    }
+    
+    return this.getInstance(instanceContext, params)
+  }
+
   #restoreOriginal(instanceContext, clazzOrName) {
     if (!instanceContext) {
       const name = clazzOrName?.name || clazzOrName || 'unknown'
       throw new Error(`Cannot reset mock for "${name}": not registered`)
     }
     if (instanceContext.originalClazz) {
-      instanceContext.clazz = instanceContext.originalClazz
-      delete instanceContext.instance
-      delete instanceContext.originalClazz
-      delete instanceContext.originalInstance
-      delete instanceContext.proxy
+      Object.assign(instanceContext, {
+        clazz: instanceContext.originalClazz,
+        instance: undefined,
+        originalClazz: undefined,
+        proxy: undefined
+      })
     }
   }
 }

package/src/integrations/middleware.d.ts

@@ -0,0 +1,40 @@
+import { Container, InjectionToken } from '../../index'
+
+export type ContainerScope = 'request' | 'global'
+
+export function getGlobalContainer(): Container
+export function getContainer(): Container
+
+export interface ResolveOptions {
+  scope?: ContainerScope
+  params?: any[]
+}
+
+export function resolve<T>(clazzOrName: InjectionToken<T>, options?: ResolveOptions): T
+
+export function runWithContainer<T>(
+  container: Container, 
+  fn: () => T,
+  options?: { scope?: ContainerScope }
+): T
+
+export interface MiddlewareOptions {
+  scope?: ContainerScope
+  debug?: boolean
+}
+
+export interface ContainerRequest {
+  di: Container
+}
+
+export function containerMiddleware(
+  options?: MiddlewareOptions
+): (req: any, res: any, next: () => void) => void
+
+export function koaContainerMiddleware(
+  options?: MiddlewareOptions
+): (ctx: any, next: () => Promise<void>) => Promise<void>
+
+export function withContainer<T extends (...args: any[]) => any>(
+  options?: MiddlewareOptions
+): (handler: T) => T

package/src/integrations/middleware.js

@@ -0,0 +1,171 @@
+/**
+ * Server middleware integration for decorator-dependency-injection.
+ * 
+ * Provides request-scoped containers using AsyncLocalStorage, enabling
+ * automatic per-request isolation without manual container management.
+ * 
+ * IMPORTANT: When using this module, `resolve()` behaves differently than 
+ * the main module's resolve:
+ * - Inside a request: Returns instances from the request-scoped container
+ *   (singletons are isolated per-request, preventing data leaks between users)
+ * - Outside a request: Falls back to the global container
+ * 
+ * @module decorator-dependency-injection/middleware
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { Container } from '../Container.js'
+import { defaultContainer as mainDefaultContainer } from '../../index.js'
+
+/** @type {AsyncLocalStorage<{container: Container, scope: string}>} */
+const requestContext = new AsyncLocalStorage()
+
+/** @type {Container} */
+const globalContainer = mainDefaultContainer
+
+/** @returns {Container|null} */
+export function getGlobalContainer() {
+  return globalContainer
+}
+
+function getRequestContext() {
+  return requestContext.getStore()
+}
+
+/** @returns {Container} */
+export function getContainer() {
+  return getRequestContext()?.container ?? globalContainer
+}
+
+/**
+ * Request-aware resolve. Uses request-scoped container inside requests,
+ * falls back to global container outside. Auto-registers from global container.
+ * 
+ * @template T
+ * @param {string|Function} clazzOrName
+ * @param {Object} [options]
+ * @param {'request'|'global'} [options.scope]
+ * @param {Array} [options.params]
+ * @returns {T}
+ */
+export function resolve(clazzOrName, options = {}) {
+  const { scope, params = [] } = options
+  const ctx = getRequestContext()
+  
+  if (scope === 'global' || ctx?.scope === 'global') {
+    return globalContainer.resolve(clazzOrName, ...params)
+  }
+  
+  if (!ctx) {
+    if (scope === 'request') {
+      console.warn(
+        `[DI] resolve() called with scope='request' but no request context exists. ` +
+        `Did you forget to use containerMiddleware()? Falling back to global container.`
+      )
+    }
+    return globalContainer.resolve(clazzOrName, ...params)
+  }
+  
+  const requestContainer = ctx.container
+  
+  if (!requestContainer.has(clazzOrName) && globalContainer?.has(clazzOrName)) {
+    const globalContext = globalContainer.getContext(clazzOrName)
+    if (globalContext.type === 'singleton') {
+      requestContainer.registerSingleton(globalContext.clazz, 
+        typeof clazzOrName === 'string' ? clazzOrName : undefined)
+    } else {
+      requestContainer.registerFactory(globalContext.clazz,
+        typeof clazzOrName === 'string' ? clazzOrName : undefined)
+    }
+  }
+  
+  return requestContainer.resolve(clazzOrName, ...params)
+}
+
+/**
+ * @template T
+ * @param {Container} container
+ * @param {function(): T} fn
+ * @param {Object} [options]
+ * @param {'request'|'global'} [options.scope='request']
+ * @returns {T}
+ */
+export function runWithContainer(container, fn, options = {}) {
+  const { scope = 'request' } = options
+  return requestContext.run({ container, scope }, fn)
+}
+
+/**
+ * @typedef {Object} MiddlewareOptions
+ * @property {'request'|'global'} [scope='request'] - Container scope mode:
+ *   - 'request': Each request gets its own container with isolated singletons (default, SSR-safe)
+ *   - 'global': All requests share the global container (use only for stateless services)
+ * @property {boolean} [debug=false] - Enable debug logging
+ */
+
+/**
+ * Express/Connect middleware. scope='request' gives each request isolated singletons (SSR-safe).
+ * @param {MiddlewareOptions} [options={}]
+ * @returns {function(req, res, next): void}
+ */
+export function containerMiddleware(options = {}) {
+  const { scope = 'request', debug = false } = options
+
+  return (req, res, next) => {
+    if (scope === 'global') {
+      requestContext.run({ container: globalContainer, scope: 'global' }, () => {
+        req.di = globalContainer
+        next()
+      })
+      return
+    }
+
+    const container = new Container()
+    if (debug) container.setDebug(true)
+    req.di = container
+    requestContext.run({ container, scope: 'request' }, () => next())
+  }
+}
+
+/**
+ * Koa middleware. See containerMiddleware() for scope behavior.
+ * @param {MiddlewareOptions} [options={}]
+ * @returns {function(ctx, next): Promise<void>}
+ */
+export function koaContainerMiddleware(options = {}) {
+  const { scope = 'request', debug = false } = options
+
+  return async (ctx, next) => {
+    if (scope === 'global') {
+      await requestContext.run({ container: globalContainer, scope: 'global' }, async () => {
+        ctx.di = globalContainer
+        await next()
+      })
+      return
+    }
+
+    const container = new Container()
+    if (debug) container.setDebug(true)
+    ctx.di = container
+    await requestContext.run({ container, scope: 'request' }, () => next())
+  }
+}
+
+/**
+ * Hono/Fastify-style handler wrapper. See containerMiddleware() for scope behavior.
+ * @param {MiddlewareOptions} [options={}]
+ * @returns {function(handler): function}
+ */
+export function withContainer(options = {}) {
+  const { scope = 'request', debug = false } = options
+
+  return (handler) => (...args) => {
+    if (scope === 'global') {
+      return requestContext.run({ container: globalContainer, scope: 'global' }, () => handler(...args))
+    }
+
+    const container = new Container()
+    if (debug) container.setDebug(true)
+    return requestContext.run({ container, scope: 'request' }, () => handler(...args))
+  }
+}

package/src/proxy.js

@@ -9,17 +9,15 @@
 export function createProxy(mock, original) {
   return new Proxy(mock, {
     get(target, prop, receiver) {
-      if (prop in target) {
-        return Reflect.get(target, prop, receiver)
-      }
-      return Reflect.get(original, prop, original)
+      return prop in target
+        ? Reflect.get(target, prop, receiver)
+        : Reflect.get(original, prop, original)
     },
 
     set(target, prop, value, receiver) {
-      if (prop in target) {
-        return Reflect.set(target, prop, value, receiver)
-      }
-      return Reflect.set(original, prop, value, original)
+      return prop in target
+        ? Reflect.set(target, prop, value, receiver)
+        : Reflect.set(original, prop, value, original)
     },
 
     has(target, prop) {
@@ -27,16 +25,18 @@ export function createProxy(mock, original) {
     },
 
     ownKeys(target) {
-      const mockKeys = Reflect.ownKeys(target)
-      const originalKeys = Reflect.ownKeys(original)
-      return [...new Set([...mockKeys, ...originalKeys])]
+      return [...new Set([...Reflect.ownKeys(target), ...Reflect.ownKeys(original)])]
     },
 
     getOwnPropertyDescriptor(target, prop) {
-      if (prop in target) {
-        return Reflect.getOwnPropertyDescriptor(target, prop)
-      }
-      return Reflect.getOwnPropertyDescriptor(original, prop)
+      return prop in target
+        ? Reflect.getOwnPropertyDescriptor(target, prop)
+        : Reflect.getOwnPropertyDescriptor(original, prop)
+    },
+
+    getPrototypeOf() {
+      // Return original's prototype so instanceof checks work
+      return Object.getPrototypeOf(original)
     }
   })
 }