decorator-dependency-injection 1.0.7 → 1.1.0

package/src/Container.js

@@ -17,48 +17,27 @@ export class Container {
   /** @type {Map<string|Function, InstanceContext>} */
   #instances = new Map()
 
-  /** @type {boolean} Enable debug logging */
   #debug = false
 
-  /**
-   * Custom string tag for better debugging.
-   * Shows as [object Container] in console.
-   */
   get [Symbol.toStringTag]() {
     return 'Container'
   }
 
-  /**
-   * Make the container iterable.
-   * Yields registration info for each registered class.
-   * @yields {RegistrationInfo}
-   */
+  /** @yields {RegistrationInfo} */
   *[Symbol.iterator]() {
     yield* this.list()
   }
 
-  /**
-   * Get the number of registrations in the container.
-   * @returns {number}
-   */
+  /** @returns {number} */
   get size() {
     return this.#instances.size
   }
 
-  /**
-   * Enable or disable debug logging.
-   * When enabled, logs when instances are created.
-   * @param {boolean} enabled Whether to enable debug mode
-   */
+  /** @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}`)
@@ -66,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)) {
@@ -103,68 +73,52 @@ 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) {
     const context = this.#instances.get(clazzOrName)
     if (context) {
       return context
     }
+    
+    const name = clazzOrName?.name ?? clazzOrName
+    const nameStr = String(name)
     const available = [...this.#instances.keys()]
       .map(k => typeof k === 'string' ? k : k.name)
       .join(', ')
     
-    const name = clazzOrName?.name || clazzOrName
-    const nameStr = String(name)
-    
     // 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_')
     
-    let errorMessage = `Cannot find injection source for "${name}". ` +
-      `Available: [${available}]`
-    
-    if (looksLikeMock) {
-      errorMessage += `\n\nHint: The class name "${name}" suggests this may be a mock created by a module mocking system. ` +
+    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(errorMessage)
+    throw new Error(
+      `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)
   }
 
-  /**
-   * Check if a class or name has a mock registered.
-   * @param {string|Function} clazzOrName The class or name to check
-   * @returns {boolean} true if a mock is registered, false otherwise
-   */
+  /** @param {string|Function} clazzOrName */
   isMocked(clazzOrName) {
     return !!this.#instances.get(clazzOrName)?.originalClazz
   }
 
   /**
-   * 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
-   * container.unregister(MyService) // Returns true if was registered
+   * @param {string|Function} clazzOrName
+   * @returns {boolean} true if removed
    */
   unregister(clazzOrName) {
     const removed = this.#instances.delete(clazzOrName)
@@ -174,17 +128,7 @@ export class Container {
     return removed
   }
 
-  /**
-   * List all registrations in the container.
-   * Useful for debugging and introspection.
-   * 
-   * @returns {Array<{key: string|Function, type: 'singleton'|'factory', isMocked: boolean, hasInstance: boolean}>}
-   * 
-   * @example
-   * container.list().forEach(reg => {
-   *   console.log(`${reg.key}: ${reg.type}, mocked: ${reg.isMocked}`)
-   * })
-   */
+  /** @returns {Array<{key: string|Function, name: string, type: 'singleton'|'factory', isMocked: boolean, hasInstance: boolean}>} */
   list() {
     return [...this.#instances.entries()].map(([key, context]) => ({
       key,
@@ -196,13 +140,10 @@ export class Container {
   }
 
   /**
-   * 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)
@@ -210,10 +151,9 @@ 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.instance) {
@@ -221,14 +161,14 @@ export class Container {
       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.`
         )
       }
@@ -248,10 +188,9 @@ 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)
@@ -262,48 +201,20 @@ export class Container {
       originalClazz: instanceContext.clazz,
       clazz: mockClazz,
       proxy: useProxy,
-      instance: undefined // Clear cached instance so the mock takes effect on next resolve
+      instance: undefined
     })
     this.#log(`Mocked ${targetClazzOrName?.name ?? targetClazzOrName} with ${mockClazz.name}${useProxy ? ' (proxy)' : ''}`)
   }
 
   /**
-   * Remove a specific mock and restore the original class.
-   * This completely removes the mock - it does NOT just clear mock call history.
-   * 
-   * @param {string|Function} clazzOrName The class or name to restore
-   * @throws {Error} If the class or name is not registered
-   * 
-   * @example
-   * // After this call, resolve(MyService) returns the original class, not the mock
-   * container.removeMock(MyService)
+   * Remove mock and restore original. Does NOT clear mock call history.
+   * @param {string|Function} clazzOrName
    */
   removeMock(clazzOrName) {
     this.#restoreOriginal(this.#instances.get(clazzOrName), clazzOrName)
   }
 
-  /**
-   * @deprecated Use removeMock() instead. This method will be removed in a future version.
-   * 
-   * Note: This does NOT reset mock call history like vi.fn().mockClear().
-   * It completely removes the mock and restores the original class.
-   * 
-   * @param {string|Function} clazzOrName The class or name to restore
-   * @throws {Error} If the class or name is not registered
-   */
-  resetMock(clazzOrName) {
-    console.warn(
-      '[DI] resetMock() is deprecated and will be removed in a future version. ' +
-      'Use removeMock() instead. Note: This removes the mock entirely, ' +
-      'it does NOT clear mock call history.'
-    )
-    this.removeMock(clazzOrName)
-  }
-
-  /**
-   * Remove all mocks and restore original classes.
-   * This completely removes all mocks - it does NOT just clear mock call history.
-   */
+  /** Remove all mocks. Does NOT clear mock call history. */
   removeAllMocks() {
     for (const instanceContext of this.#instances.values()) {
       this.#restoreOriginal(instanceContext)
@@ -311,44 +222,15 @@ export class Container {
   }
 
   /**
-   * @deprecated Use removeAllMocks() instead. This method will be removed in a future version.
-   * 
-   * Note: This does NOT reset mock call history.
-   * It completely removes all mocks and restores original classes.
-   */
-  resetAllMocks() {
-    console.warn(
-      '[DI] resetAllMocks() is deprecated and will be removed in a future version. ' +
-      'Use removeAllMocks() instead. Note: This removes all mocks entirely, ' +
-      'it does NOT clear mock call history.'
-    )
-    this.removeAllMocks()
-  }
-
-  /**
-   * 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.
-   * 
-   * @param {Object} [options] Options for resetting
-   * @param {boolean} [options.preserveMocks=true] If true, keeps mock registrations intact.
-   *                                                If false, also removes mocks (same as clear()).
-   * 
-   * @example
-   * // Clear singleton instances but keep mocks registered
-   * container.resetSingletons()
-   * 
-   * // Clear singleton instances AND remove mocks
-   * container.resetSingletons({ preserveMocks: false })
+   * Clear cached singleton instances. They'll be recreated on next resolve.
+   * @param {Object} [options]
+   * @param {boolean} [options.preserveMocks=true]
    */
   resetSingletons(options = {}) {
     const { preserveMocks = true } = options
     
     for (const instanceContext of this.#instances.values()) {
-      // Clear the cached singleton instance
       delete instanceContext.instance
-      
-      // Optionally remove mock registrations
       if (!preserveMocks && instanceContext.originalClazz) {
         this.#restoreOriginal(instanceContext)
       }
@@ -357,27 +239,14 @@ export class Container {
   }
 
   /**
-   * Clear all registered instances and mocks.
-   * Useful for complete test isolation between test suites.
-   * 
-   * Note: By default this removes ALL registrations including @Singleton and @Factory classes.
-   * For clearing just singleton instances while keeping registrations, use resetSingletons().
-   * 
-   * @param {Object} [options] Options for clearing
-   * @param {boolean} [options.preserveRegistrations=false] If true, keeps all registrations but clears cached instances.
-   * 
-   * @example
-   * // Remove everything (full reset)
-   * container.clear()
-   * 
-   * // Clear cached instances but keep all registrations (including mocks)
-   * container.clear({ preserveRegistrations: true })
+   * Clear all registrations. Use resetSingletons() to keep registrations.
+   * @param {Object} [options]
+   * @param {boolean} [options.preserveRegistrations=false]
    */
   clear(options = {}) {
     const { preserveRegistrations = false } = options
     
     if (preserveRegistrations) {
-      // Just clear cached instances, keep all registrations
       for (const instanceContext of this.#instances.values()) {
         delete instanceContext.instance
       }
@@ -389,25 +258,11 @@ export class Container {
   }
 
   /**
-   * Get the mock instance for a mocked class.
-   * This is useful when you need to configure mock behavior dynamically in tests.
-   * 
    * @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
-   * @Mock(UserService)
-   * class MockUserService {
-   *   getUser = vi.fn()
-   * }
-   * 
-   * // In test:
-   * const mockInstance = container.getMockInstance(UserService)
-   * mockInstance.getUser.mockReturnValue({ id: 1, name: 'Test' })
+   * @param {string|Function} clazzOrName
+   * @param {...*} params
+   * @returns {T}
+   * @throws {Error} If not mocked
    */
   getMockInstance(clazzOrName, ...params) {
     const instanceContext = this.getContext(clazzOrName)
@@ -422,13 +277,6 @@ export class Container {
     return this.getInstance(instanceContext, params)
   }
 
-  /**
-   * 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
-   */
   #restoreOriginal(instanceContext, clazzOrName) {
     if (!instanceContext) {
       const name = clazzOrName?.name || clazzOrName || 'unknown'
@@ -439,7 +287,6 @@ export class Container {
         clazz: instanceContext.originalClazz,
         instance: undefined,
         originalClazz: undefined,
-        originalInstance: 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))
+  }
+}