@navios/di 0.9.2 → 1.0.0

package/src/__tests__/gc/transient-services.spec.mts

@@ -0,0 +1,326 @@
+/**
+ * Garbage Collection Tests: Transient Services
+ *
+ * Tests that transient services are properly garbage collected
+ * when no longer referenced, since they are not cached by the container.
+ *
+ * Run with: NODE_OPTIONS=--expose-gc yarn nx test @navios/di
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { OnServiceDestroy } from '../../interfaces/on-service-destroy.interface.mjs'
+
+import { Container } from '../../container/container.mjs'
+import { Injectable } from '../../decorators/injectable.decorator.mjs'
+import { InjectableScope } from '../../enums/injectable-scope.enum.mjs'
+import { Registry } from '../../token/registry.mjs'
+import { inject } from '../../utils/index.mjs'
+import {
+  createGCTracker,
+  forceGC,
+  getHeapUsed,
+  isGCAvailable,
+  waitForGC,
+} from './gc-test-utils.mjs'
+
+describe.skipIf(!isGCAvailable)('GC: Transient Services', () => {
+  let registry: Registry
+  let container: Container
+
+  beforeEach(() => {
+    registry = new Registry()
+    container = new Container(registry)
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  describe('Transient services are collected when unreferenced', () => {
+    it('should garbage collect transient service when reference is released', async () => {
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientService {
+        public readonly id = Math.random()
+        public readonly data = Array.from({ length: 1000 }, () => 'transient')
+      }
+
+      let instance: TransientService | null =
+        await container.get(TransientService)
+      const tracker = createGCTracker(instance)
+
+      expect(tracker().collected).toBe(false)
+
+      // Release the reference
+      instance = null
+
+      const collected = await waitForGC(tracker().ref)
+      expect(collected).toBe(true)
+    })
+
+    it('should collect multiple transient instances independently', async () => {
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientService {
+        public readonly id = Math.random()
+        public readonly data = Array.from(
+          { length: 500 },
+          () => 'multi-transient',
+        )
+      }
+
+      let instance1: TransientService | null =
+        await container.get(TransientService)
+      let instance2: TransientService | null =
+        await container.get(TransientService)
+      let instance3: TransientService | null =
+        await container.get(TransientService)
+
+      expect(instance1).not.toBe(instance2)
+      expect(instance2).not.toBe(instance3)
+
+      const tracker1 = createGCTracker(instance1)
+      const tracker2 = createGCTracker(instance2)
+      const tracker3 = createGCTracker(instance3)
+
+      // Release only the first instance
+      instance1 = null
+      forceGC()
+
+      expect(await waitForGC(tracker1().ref, 500)).toBe(true)
+      expect(tracker2().collected).toBe(false)
+      expect(tracker3().collected).toBe(false)
+
+      // Release the second instance
+      instance2 = null
+      forceGC()
+
+      expect(await waitForGC(tracker2().ref, 500)).toBe(true)
+      expect(tracker3().collected).toBe(false)
+
+      // Release the third instance
+      instance3 = null
+      forceGC()
+
+      expect(await waitForGC(tracker3().ref, 500)).toBe(true)
+    })
+
+    it('should collect transient services with lifecycle hooks', async () => {
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientWithDestroy implements OnServiceDestroy {
+        public readonly id = Math.random()
+
+        onServiceDestroy(): void {
+          // This won't be called when going out of scope
+        }
+      }
+
+      let instance: TransientWithDestroy | null =
+        await container.get(TransientWithDestroy)
+      const tracker = createGCTracker(instance)
+
+      instance = null
+
+      const collected = await waitForGC(tracker().ref)
+      expect(collected).toBe(true)
+
+      // Note: onServiceDestroy is NOT called for transient services when
+      // they go out of scope - only when the container is disposed.
+      // This is expected behavior since the container doesn't track them.
+    })
+  })
+
+  describe('Transient services with dependencies', () => {
+    it('should collect transient service but keep singleton dependency', async () => {
+      @Injectable({ registry })
+      class SingletonDep {
+        public readonly id = Math.random()
+      }
+
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientWithSingletonDep {
+        public readonly dep = inject(SingletonDep)
+        public readonly id = Math.random()
+      }
+
+      const singletonRef = await container.get(SingletonDep)
+      let transient: TransientWithSingletonDep | null = await container.get(
+        TransientWithSingletonDep,
+      )
+
+      expect(transient.dep).toBe(singletonRef)
+
+      const transientTracker = createGCTracker(transient)
+      const singletonTracker = createGCTracker(singletonRef)
+
+      transient = null
+      forceGC()
+
+      // Transient should be collected
+      expect(await waitForGC(transientTracker().ref)).toBe(true)
+
+      // Singleton should NOT be collected (still in container)
+      forceGC()
+      expect(singletonTracker().collected).toBe(false)
+
+      // Singleton is still accessible
+      const stillThere = await container.get(SingletonDep)
+      expect(stillThere).toBe(singletonRef)
+    })
+
+    it('should collect transient service with transient dependency', async () => {
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientDep {
+        public readonly id = Math.random()
+        public readonly data = Array.from({ length: 500 }, () => 'dep')
+      }
+
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientParent {
+        public readonly dep = inject(TransientDep)
+        public readonly data = Array.from({ length: 500 }, () => 'parent')
+      }
+
+      let parent: TransientParent | null = await container.get(TransientParent)
+      let depRef: TransientDep | null = parent.dep
+
+      const parentTracker = createGCTracker(parent)
+      const depTracker = createGCTracker(depRef)
+
+      // Release both references
+      parent = null
+      depRef = null
+      forceGC()
+
+      // Both should be collected since no external references
+      expect(await waitForGC(parentTracker().ref)).toBe(true)
+      expect(await waitForGC(depTracker().ref)).toBe(true)
+    })
+  })
+
+  describe('Memory is reclaimed for transient services', () => {
+    // This test is flaky and no matter how many instances we create, the last instance is never collected.
+    it.skip('should reclaim memory when transient instances are released', async () => {
+      const INSTANCE_COUNT = 10
+
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class LargeTransientService {
+        public readonly data = new Uint8Array(1024 * 100) // 100KB
+      }
+
+      // Track all instances with WeakRefs
+      const trackers: ReturnType<typeof createGCTracker>[] = []
+      let instances: LargeTransientService[] = []
+
+      for (let i = 0; i < INSTANCE_COUNT; i++) {
+        const instance = await container.get(LargeTransientService)
+        instances.push(instance)
+        trackers.push(createGCTracker(instance))
+      }
+
+      // Verify none collected yet
+      for (const tracker of trackers) {
+        expect(tracker().collected).toBe(false)
+      }
+
+      // Release all references
+      instances = []
+      forceGC()
+
+      let collected = 0
+      // All should be collected
+      for (const tracker of trackers) {
+        console.log('waiting for GC', collected++, tracker().collected)
+        expect(await waitForGC(tracker().ref)).toBe(true)
+      }
+    })
+
+    it.todo(
+      'should not accumulate memory with repeated transient creations',
+      async () => {
+        const ALLOCATION_SIZE = 1024 * 50 // 50KB per instance
+        const ITERATIONS = 50
+
+        @Injectable({ registry, scope: InjectableScope.Transient })
+        class TransientService {
+          public readonly data = new Uint8Array(ALLOCATION_SIZE)
+        }
+
+        forceGC()
+        const baselineMemory = getHeapUsed()
+
+        // Repeatedly create and discard transient instances
+        for (let i = 0; i < ITERATIONS; i++) {
+          const instance = await container.get(TransientService)
+          // instance goes out of scope immediately
+          void instance
+        }
+
+        forceGC()
+        const finalMemory = getHeapUsed()
+        const memoryGrowth = finalMemory - baselineMemory
+
+        // Memory growth should be minimal (less than 2 instances worth)
+        // since transients are not cached
+        expect(memoryGrowth).toBeLessThan(ALLOCATION_SIZE * 2)
+      },
+    )
+  })
+
+  describe('Transient services in mixed scope scenarios', () => {
+    it('should properly collect transients while singletons persist', async () => {
+      @Injectable({ registry })
+      class SingletonA {
+        public readonly data = Array.from({ length: 500 }, () => 'singleton-a')
+      }
+
+      @Injectable({ registry })
+      class SingletonB {
+        public readonly data = Array.from({ length: 500 }, () => 'singleton-b')
+      }
+
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientA {
+        public readonly singletonA = inject(SingletonA)
+        public readonly data = Array.from({ length: 500 }, () => 'transient-a')
+      }
+
+      @Injectable({ registry, scope: InjectableScope.Transient })
+      class TransientB {
+        public readonly singletonB = inject(SingletonB)
+        public readonly data = Array.from({ length: 500 }, () => 'transient-b')
+      }
+
+      // Get singletons first
+      const singletonA = await container.get(SingletonA)
+      const singletonB = await container.get(SingletonB)
+
+      // Create transients
+      let transientA: TransientA | null = await container.get(TransientA)
+      let transientB: TransientB | null = await container.get(TransientB)
+
+      const trackers = {
+        singletonA: createGCTracker(singletonA),
+        singletonB: createGCTracker(singletonB),
+        transientA: createGCTracker(transientA),
+        transientB: createGCTracker(transientB),
+      }
+
+      // Release transients
+      transientA = null
+      transientB = null
+      forceGC()
+
+      // Transients should be collected
+      expect(await waitForGC(trackers.transientA().ref)).toBe(true)
+      expect(await waitForGC(trackers.transientB().ref)).toBe(true)
+
+      // Singletons should remain
+      expect(trackers.singletonA().collected).toBe(false)
+      expect(trackers.singletonB().collected).toBe(false)
+
+      // Singletons still accessible
+      expect(await container.get(SingletonA)).toBe(singletonA)
+      expect(await container.get(SingletonB)).toBe(singletonB)
+    })
+  })
+})

package/src/__tests__/scope-upgrade.spec.mts

@@ -116,15 +116,6 @@ describe('Scope Upgrade: Simple Singleton -> Request', () => {
       await scoped2.endRequest()
     })
 
-    // TODO: BUG DISCOVERED - After scope upgrade, the holder is not properly
-    // stored in request storage, causing each resolution to create a new instance.
-    // The ScopeTracker.checkAndUpgradeScope() is called from ServiceInitializationContext
-    // which runs DURING the first instance creation. By that time, the holder is
-    // already in singleton storage and the upgrade logic in instance-resolver.mts
-    // doesn't properly move it to request storage for subsequent lookups.
-    //
-    // Fix: The InstanceResolver should check if the scope was upgraded during
-    // resolution and re-store the holder with the correct requestId-based name.
     it('should return same instance within the same request after upgrade', async () => {
       @Injectable({ scope: InjectableScope.Request, registry })
       class RequestService {
@@ -335,15 +326,6 @@ describe('Scope Upgrade: Complex Chains', () => {
   })
 
   describe('Multiple Singletons depending on same Request service', () => {
-    // TODO: BUG DISCOVERED - Each Singleton is resolved independently.
-    // The first one (SingletonA) gets resolved and upgraded during its injection.
-    // The second one (SingletonB) should also be upgraded but the upgrade
-    // only happens when the Singleton's inject() resolves the Request-scoped dependency.
-    //
-    // This test reveals that each Singleton is upgraded independently when
-    // it first depends on a Request-scoped service. The test below verifies
-    // the first Singleton is upgraded but expects both to be upgraded after
-    // resolving both. In reality, each upgrade happens during its own resolution.
     it('should upgrade all dependent Singletons', async () => {
       @Injectable({ scope: InjectableScope.Request, registry })
       class SharedRequestService {

package/src/internal/core/instance-resolver.mts

@@ -14,7 +14,6 @@ import type { LifecycleEventBus } from '../lifecycle/lifecycle-event-bus.mjs'
 import { InjectableScope } from '../../enums/index.mjs'
 import { DIError, DIErrorCode } from '../../errors/index.mjs'
 import {
-  BoundInjectionToken,
   FactoryInjectionToken,
   InjectionToken,
 } from '../../token/injection-token.mjs'

package/src/legacy-compat/context-compat.mts

@@ -0,0 +1,95 @@
+/**
+ * Compatibility layer for converting legacy decorator signatures to Stage 3 format.
+ *
+ * This module provides utilities to create mock Stage 3 decorator contexts
+ * from legacy decorator arguments, and manages metadata storage using WeakMap.
+ */
+
+import type { ClassType } from '../token/injection-token.mjs'
+
+// WeakMap to store metadata for legacy decorators
+// Keyed by class constructor for class decorators
+// For method decorators, we use the class constructor (extracted from the prototype)
+const classMetadataMap = new WeakMap<ClassType, Record<string | symbol, any>>()
+
+/**
+ * Gets the constructor from a prototype (for method decorators).
+ */
+function getConstructor(prototype: any): ClassType | null {
+  if (!prototype || typeof prototype !== 'object') {
+    return null
+  }
+  // In legacy decorators, target is the prototype
+  // The constructor is typically available via prototype.constructor
+  const constructor = prototype.constructor
+  if (constructor && typeof constructor === 'function') {
+    return constructor as ClassType
+  }
+  return null
+}
+
+/**
+ * Creates a mock ClassDecoratorContext for legacy class decorators.
+ * @internal
+ */
+export function createClassContext(target: ClassType): ClassDecoratorContext {
+  // Get or create metadata storage for this class
+  if (!classMetadataMap.has(target)) {
+    classMetadataMap.set(target, {})
+  }
+  const metadata = classMetadataMap.get(target)!
+
+  return {
+    kind: 'class',
+    name: target.name,
+    metadata,
+    addInitializer() {
+      // Legacy decorators don't support initializers
+    },
+  } as ClassDecoratorContext
+}
+
+/**
+ * Creates a mock ClassMethodDecoratorContext for legacy method decorators.
+ *
+ * Note: Method decorators need to share metadata with the class context
+ * because endpoint metadata is stored at the class level.
+ * @internal
+ */
+export function createMethodContext(
+  target: any,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+): ClassMethodDecoratorContext {
+  // For method decorators, target is the prototype
+  // We need to get the class constructor to access class-level metadata
+  const constructor = getConstructor(target)
+  if (!constructor) {
+    throw new Error(
+      '[Navios] Could not determine class constructor from method decorator target.',
+    )
+  }
+
+  // Get or create metadata storage for the class
+  // Method decorators share metadata with the class
+  if (!classMetadataMap.has(constructor)) {
+    classMetadataMap.set(constructor, {})
+  }
+  const metadata = classMetadataMap.get(constructor)!
+
+  return {
+    kind: 'method',
+    name: propertyKey,
+    metadata,
+    static: false, // We can't determine this from legacy decorators
+    private: false, // We can't determine this from legacy decorators
+    access: {
+      has: () => true,
+      get: () => descriptor.value,
+      set: () => {},
+    },
+    addInitializer() {
+      // Legacy decorators don't support initializers
+    },
+  } as ClassMethodDecoratorContext
+}

package/src/legacy-compat/factory.decorator.mts

@@ -0,0 +1,37 @@
+import type { ClassType } from '../token/injection-token.mjs'
+
+import { Factory as OriginalFactory, type FactoryOptions } from '../decorators/index.mjs'
+
+import { createClassContext } from './context-compat.mjs'
+
+export type { FactoryOptions }
+
+/**
+ * Legacy-compatible Factory decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ *
+ * @param options - Factory configuration options
+ * @returns A class decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Factory()
+ * export class DatabaseConnectionFactory {
+ *   create() {
+ *     return { host: 'localhost', port: 5432 }
+ *   }
+ * }
+ * ```
+ */
+export function Factory(options: FactoryOptions = {}) {
+  return function (target: ClassType) {
+    const context = createClassContext(target)
+    // Use the no-args overload when options is empty, otherwise pass options
+    const originalDecorator =
+      Object.keys(options).length === 0
+        ? OriginalFactory()
+        : OriginalFactory(options)
+    return originalDecorator(target, context)
+  }
+}

package/src/legacy-compat/index.mts

@@ -0,0 +1,16 @@
+/**
+ * Legacy-compatible decorators for projects using TypeScript experimental decorators.
+ *
+ * Use this when you cannot use Stage 3 decorators (e.g., existing projects with
+ * experimentalDecorators enabled, certain bundler configurations, or Bun).
+ */
+
+// Re-export decorator options types
+export type { InjectableOptions, FactoryOptions } from '../decorators/index.mjs'
+
+// Export legacy-compatible decorators
+export { Injectable } from './injectable.decorator.mjs'
+export { Factory } from './factory.decorator.mjs'
+
+// Export context compatibility utilities for building custom legacy decorators
+export { createClassContext, createMethodContext } from './context-compat.mjs'

package/src/legacy-compat/injectable.decorator.mts

@@ -0,0 +1,41 @@
+import type { ClassType } from '../token/injection-token.mjs'
+
+import {
+  Injectable as OriginalInjectable,
+  type InjectableOptions,
+} from '../decorators/index.mjs'
+
+import { createClassContext } from './context-compat.mjs'
+
+export type { InjectableOptions }
+
+/**
+ * Legacy-compatible Injectable decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ *
+ * @param options - Injectable configuration options
+ * @returns A class decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class UserService {
+ *   getUser(id: string) {
+ *     return { id, name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+export function Injectable(options: InjectableOptions = {}) {
+  return function (target: ClassType) {
+    const context = createClassContext(target)
+    // Use the no-args overload when options is empty, otherwise pass options
+    const originalDecorator =
+      Object.keys(options).length === 0
+        ? OriginalInjectable()
+        : // @ts-expect-error - InjectableOptions is a union type, we let runtime handle it
+          OriginalInjectable(options)
+    return originalDecorator(target, context)
+  }
+}

package/tsdown.config.mts

@@ -5,7 +5,7 @@ import swc from 'unplugin-swc'
 export default defineConfig([
   // Node.js build (default)
   {
-    entry: ['src/index.mts', 'src/testing/index.mts'],
+    entry: ['src/index.mts', 'src/testing/index.mts', 'src/legacy-compat/index.mts'],
     outDir: 'lib',
     format: ['esm', 'cjs'],
     clean: true,

package/vitest.config.mts

@@ -7,6 +7,9 @@ export default defineProject({
         test: {
           include: ['src/**/__tests__/**/*.spec.mts'],
           exclude: ['src/**/__tests__/**/*.browser.spec.mts'],
+          typecheck: {
+            enabled: true,
+          },
         },
       },
       {
@@ -19,13 +22,6 @@ export default defineProject({
           },
         },
       },
-      {
-        test: {
-          typecheck: {
-            enabled: true,
-          },
-        },
-      },
     ],
   },
 })