decorator-dependency-injection 1.0.3 → 1.0.5

package/src/Container.js

@@ -0,0 +1,211 @@
+/**
+ * @typedef {Object} InstanceContext
+ * @property {'singleton'|'factory'} type - The type of the instance.
+ * @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.
+ */
+
+import {createProxy} from './proxy.js'
+
+/**
+ * A dependency injection container that manages singleton and factory instances.
+ * Supports mocking for testing purposes.
+ */
+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
+   * @param {string} [name] Optional name key
+   */
+  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
+   */
+  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)) {
+      throw new Error(
+        'A different class is already registered under this name. ' +
+        'This may be a circular dependency. Try using @InjectLazy'
+      )
+    }
+    this.#instances.set(key, {clazz, type})
+    this.#log(`Registered ${type}: ${name || clazz.name}`)
+  }
+
+  /**
+   * Get the context for a given class or name.
+   * @param {string|Function} clazzOrName The class or name to look up
+   * @returns {InstanceContext}
+   * @throws {Error} If the context is not found
+   */
+  getContext(clazzOrName) {
+    if (this.#instances.has(clazzOrName)) {
+      return this.#instances.get(clazzOrName)
+    }
+    const available = Array.from(this.#instances.keys())
+      .map(k => typeof k === 'string' ? k : k.name)
+      .join(', ')
+    throw new Error(
+      `Cannot find injection source for "${clazzOrName?.name || clazzOrName}". ` +
+      `Available: [${available}]`
+    )
+  }
+
+  /**
+   * Check if a class or name is registered.
+   * @param {string|Function} clazzOrName The class or name to check
+   * @returns {boolean}
+   */
+  has(clazzOrName) {
+    return this.#instances.has(clazzOrName)
+  }
+
+  /**
+   * Get or create an instance based on the context.
+   * @param {InstanceContext} instanceContext The instance context
+   * @param {Array} params Constructor parameters
+   * @returns {Object} The instance
+   */
+  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) {
+        throw new Error(
+          `Circular dependency detected for ${instanceContext.clazz.name || instanceContext.clazz}. ` +
+          `Use @InjectLazy to break the cycle.`
+        )
+      }
+      throw err
+    }
+
+    if (instanceContext.proxy && instanceContext.originalClazz) {
+      const originalInstance = new instanceContext.originalClazz(...params)
+      instance = createProxy(instance, originalInstance)
+    }
+
+    if (instanceContext.type === 'singleton') {
+      instanceContext.instance = instance
+    }
+
+    return instance
+  }
+
+  /**
+   * 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
+   */
+  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)' : ''}`)
+  }
+
+  /**
+   * 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
+   */
+  resetMock(clazzOrName) {
+    this.#restoreOriginal(this.#instances.get(clazzOrName), clazzOrName)
+  }
+
+  /**
+   * Reset all mocks to their original classes.
+   */
+  resetAllMocks() {
+    for (const instanceContext of this.#instances.values()) {
+      this.#restoreOriginal(instanceContext)
+    }
+  }
+
+  /**
+   * Clear all registered instances and mocks.
+   * Useful for test isolation.
+   */
+  clear() {
+    this.#instances.clear()
+  }
+
+  /**
+   * 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'
+      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
+    }
+  }
+}

package/src/proxy.js

@@ -0,0 +1,42 @@
+/**
+ * Create a proxy that delegates to the mock first, then falls back to the original.
+ * This allows partial mocking where only specific methods are overridden.
+ *
+ * @param {Object} mock The mock instance
+ * @param {Object} original The original instance to fall back to
+ * @returns {Proxy} A proxy that delegates appropriately
+ */
+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)
+    },
+
+    set(target, prop, value, receiver) {
+      if (prop in target) {
+        return Reflect.set(target, prop, value, receiver)
+      }
+      return Reflect.set(original, prop, value, original)
+    },
+
+    has(target, prop) {
+      return prop in target || prop in original
+    },
+
+    ownKeys(target) {
+      const mockKeys = Reflect.ownKeys(target)
+      const originalKeys = Reflect.ownKeys(original)
+      return [...new Set([...mockKeys, ...originalKeys])]
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      if (prop in target) {
+        return Reflect.getOwnPropertyDescriptor(target, prop)
+      }
+      return Reflect.getOwnPropertyDescriptor(original, prop)
+    }
+  })
+}

package/.github/workflows/release.yml

@@ -1,129 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [22.x, 23.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
-    steps:
-      - uses: actions/checkout@v4
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run build --if-present
-      - run: npm test
-
-  release:
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Install Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-
-      - name: Get package.json version
-        id: package_version
-        run: echo "VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_ENV
-
-      - name: Check if tag exists
-        id: check_tag
-        run: |
-          TAG_EXISTS=$(git ls-remote --tags origin "v${VERSION}" | wc -l)
-          echo "TAG_EXISTS=${TAG_EXISTS}" >> $GITHUB_ENV
-
-      - name: Get commit messages
-        id: commit_messages
-        run: |
-          COMMITS=$(git log --pretty=format:"%h - %s" $(git describe --tags --abbrev=0 @^)..@ | while read -r hash msg; do echo "[${hash}](https://github.com/${{ github.repository }}/commit/${hash}) - ${msg}"; done)
-          echo "COMMITS=${COMMITS}" >> $GITHUB_ENV
-
-      - name: Create Tag and Release
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const version = process.env.VERSION
-            const tag = `v${version}`
-            const commits = process.env.COMMITS
-            const { data: tags } = await github.rest.repos.listTags({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-            })
-            
-            if (!tags.find(t => t.name === tag)) {
-              await github.rest.git.createRef({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                ref: `refs/tags/${tag}`,
-                sha: context.sha,
-              })
-            
-              await github.rest.repos.createRelease({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                tag_name: tag,
-                name: `Release ${tag}`,
-                body: `Automated release of version ${tag}\n\nCommits:\n${commits}`,
-                draft: false,
-                prerelease: false,
-              })
-              core.notice(`Release ${tag} created.`)
-            } else {
-              core.notice(`Release ${tag} already exists. No new release created.`)
-            }
-
-  publish:
-    needs: release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Install Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org/'
-
-      - name: Get package.json version
-        id: package_version
-        run: echo "VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_ENV
-
-      - name: Check if version exists on npm
-        id: check_npm_version
-        run: |
-          if npm show decorator-dependency-injection@${{ env.VERSION }} > /dev/null 2>&1; then
-            echo "VERSION_EXISTS=true" >> $GITHUB_ENV
-          else
-            echo "VERSION_EXISTS=false" >> $GITHUB_ENV
-          fi
-
-      - name: Publish to npm
-        if: env.VERSION_EXISTS == 'false'
-        run: | 
-          npm publish --access public
-          echo "::notice::Published new version ${{ env.VERSION }} to npm."
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Notice Publish Status
-        if: env.VERSION_EXISTS == 'true'
-        run: echo "::notice::Version ${{ env.VERSION }} already exists on npm. No new version published."
-
-

package/babel.config.json

@@ -1,6 +0,0 @@
-{
-  "presets": ["@babel/preset-env"],
-  "plugins": [
-    ["@babel/plugin-proposal-decorators", { "version": "2023-11" }]
-  ]
-}

package/test/injection.test.js

@@ -1,309 +0,0 @@
-import {Factory, Inject, resetMocks, Singleton} from '../index.js'
-
-describe('Injection via fields', () => {
-  @Singleton()
-  class TestSingleton {
-    static calls = 0
-
-    constructor() {
-      TestSingleton.calls++
-    }
-  }
-
-  it('should inject singleton', () => {
-    class TestInjection {
-      @Inject(TestSingleton) testSingleton
-
-      constructor() {
-        expect(this.testSingleton).toBeInstanceOf(TestSingleton)
-        expect(TestSingleton.calls).toBe(1)
-      }
-    }
-
-    class TestInjection2 {
-      @Inject(TestSingleton) testSingleton
-
-      constructor() {
-        expect(this.testSingleton).toBeInstanceOf(TestSingleton)
-        expect(TestSingleton.calls).toBe(1)
-      }
-    }
-
-    new TestInjection()
-    new TestInjection2()
-  })
-
-  @Factory()
-  class TestFactory {
-    static calls = 0
-    params
-
-    @Inject(TestSingleton) testSingleton
-
-    constructor(...params) {
-      TestFactory.calls++
-      this.params = params
-    }
-  }
-
-  afterEach(() => {
-    TestFactory.calls = 0
-    TestSingleton.calls = 0
-    resetMocks()
-  })
-
-  it('should inject factory', () => {
-    class TestInjectionFactory {
-      @Inject(TestFactory) testFactory
-
-      constructor() {
-        expect(this.testFactory).toBeInstanceOf(TestFactory)
-        expect(TestFactory.calls).toBe(1)
-      }
-    }
-
-    class TestInjectionFactory2 {
-      @Inject(TestFactory) testFactory
-
-      constructor() {
-        expect(this.testFactory).toBeInstanceOf(TestFactory)
-        expect(TestFactory.calls).toBe(2)
-      }
-    }
-
-    const result = new TestInjectionFactory()
-    new TestInjectionFactory2()
-    expect(result.testFactory.testSingleton).toBeInstanceOf(TestSingleton)
-  })
-
-  it('should inject factory with parameters', () => {
-    class TestInjectionFactoryParams {
-      @Inject(TestFactory, 'param1', 'param2') testFactory
-
-      constructor() {
-        expect(this.testFactory).toBeInstanceOf(TestFactory)
-        expect(this.testFactory.params).toEqual(['param1', 'param2'])
-      }
-    }
-
-    new TestInjectionFactoryParams()
-  })
-
-  it('should cache factory instance on repeated accesses', () => {
-    class TestRepeatedFactoryAccess {
-      @Inject(TestFactory) testFactory
-
-      constructor() {
-        const instance1 = this.testFactory
-        const instance2 = this.testFactory
-        expect(instance1).toBe(instance2)
-      }
-    }
-
-    new TestRepeatedFactoryAccess()
-  })
-
-  it('should create distinct factory instances for different fields in the same object', () => {
-    class TestMultipleFactoryInjection {
-      @Inject(TestFactory) testFactory1
-      @Inject(TestFactory) testFactory2
-
-      constructor() {
-        // Access both properties to trigger initialization.
-        const one = this.testFactory1
-        const two = this.testFactory2
-        expect(one).not.toBe(two)
-      }
-    }
-
-    new TestMultipleFactoryInjection()
-  })
-
-  it('should inject the same singleton instance for different fields in the same object', () => {
-    class TestMultipleSingletonInjection {
-      @Inject(TestSingleton) testSingleton1
-      @Inject(TestSingleton) testSingleton2
-
-      constructor() {
-        // Access both properties to trigger initialization.
-        const one = this.testSingleton1
-        const two = this.testSingleton2
-        expect(one).toBe(two)
-      }
-    }
-
-    new TestMultipleSingletonInjection()
-  })
-
-  @Singleton('named')
-  class NamedSingleton {
-    static calls = 0
-
-    constructor() {
-      NamedSingleton.calls++
-    }
-  }
-
-  it('should inject named singleton', () => {
-    class TestInjectionNamedSingleton {
-      @Inject('named') namedSingleton
-
-      constructor() {
-        expect(this.namedSingleton).toBeInstanceOf(NamedSingleton)
-        expect(NamedSingleton.calls).toBe(1)
-      }
-    }
-
-    class TestInjectionNamedSingleton2 {
-      @Inject('named') namedSingleton
-
-      constructor() {
-        expect(this.namedSingleton).toBeInstanceOf(NamedSingleton)
-        expect(NamedSingleton.calls).toBe(1)
-      }
-    }
-
-    new TestInjectionNamedSingleton()
-    new TestInjectionNamedSingleton2()
-  })
-
-  @Factory('named2')
-  class NamedFactory {
-    static calls = 0
-    params
-
-    constructor(...params) {
-      NamedFactory.calls++
-      this.params = params
-    }
-  }
-
-  it('should inject named factory', () => {
-    class TestInjectionNamedFactory {
-      @Inject('named2') namedFactory
-
-      constructor() {
-        expect(this.namedFactory).toBeInstanceOf(NamedFactory)
-        expect(NamedFactory.calls).toBe(1)
-      }
-    }
-
-    class TestInjectionNamedFactory2 {
-      @Inject('named2') namedFactory
-
-      constructor() {
-        expect(this.namedFactory).toBeInstanceOf(NamedFactory)
-        expect(NamedFactory.calls).toBe(2)
-      }
-    }
-
-    const result = new TestInjectionNamedFactory()
-    new TestInjectionNamedFactory2()
-    expect(result.namedFactory.params).toEqual([])
-  })
-
-  it('should cache named factory instance on repeated accesses', () => {
-    class TestRepeatedNamedFactoryAccess {
-      @Inject('named2') namedFactory
-
-      constructor() {
-        const instance1 = this.namedFactory
-        const instance2 = this.namedFactory
-        expect(instance1).toBe(instance2)
-      }
-    }
-
-    new TestRepeatedNamedFactoryAccess()
-  })
-
-  it('should throw if @Inject is applied to a method', () => {
-    expect(() => {
-      // noinspection JSUnusedLocalSymbols
-      class BadInjection {
-        @Inject('something')
-        someMethod() {
-        }
-      }
-    }).toThrow()
-  })
-
-  it('should handle circular dependencies gracefully', () => {
-    @Singleton()
-    class A {
-      @Inject('B') b
-    }
-
-    @Singleton('B')
-    class B {
-      @Inject(A) a
-    }
-
-    expect(() => new A()).toThrow(/Circular dependency detected.*@InjectLazy/)
-  })
-
-  it('should throw if decorator is used on non-class object', () => {
-    expect(() => {
-      const obj = {}
-      Inject('something')(obj, 'field')
-    }).toThrow()
-  })
-
-  it('should throw a helpful error for eager circular dependencies', () => {
-    @Factory()
-    class A2 {
-      @Inject('B2') b
-    }
-
-    @Singleton('B2')
-    class B2 {
-      @Inject(A2) a
-    }
-
-    expect(() => new A2()).toThrow(/Circular dependency detected.*@InjectLazy/)
-  })
-
-  it('should inject into symbol-named fields', () => {
-    const sym = Symbol('sym')
-
-    @Singleton()
-    class S {
-    }
-
-    class Test {
-      @Inject(S) [sym]
-    }
-
-    const t = new Test()
-    expect(t[sym]).toBeInstanceOf(S)
-  })
-
-  it('should not leak injected properties to prototype', () => {
-    @Singleton()
-    class S {
-    }
-
-    class Test {
-      @Inject(S) dep
-    }
-
-    // noinspection JSUnusedLocalSymbols
-    const t = new Test()
-    expect(Object.prototype.hasOwnProperty.call(Test.prototype, 'dep')).toBe(false)
-  })
-
-  it('should handle undefined/null/complex params in factory', () => {
-    @Factory()
-    class F {
-      constructor(...params) {
-        this.params = params
-      }
-    }
-
-    class Test {
-      @Inject(F, undefined, null, {a: 1}) dep
-    }
-
-    const t = new Test()
-    expect(t.dep.params).toEqual([undefined, null, {a: 1}])
-  })
-})