@navios/di 0.3.0 → 0.4.0

package/src/__tests__/service-locator-manager.spec.mts

@@ -0,0 +1,370 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { InjectableScope, InjectableType } from '../enums/index.mjs'
+import {
+  InstanceDestroying,
+  InstanceExpired,
+  InstanceNotFound,
+} from '../errors/index.mjs'
+import { ServiceLocatorInstanceHolderStatus } from '../service-locator-instance-holder.mjs'
+import { ServiceLocatorManager } from '../service-locator-manager.mjs'
+
+describe('ServiceLocatorManager', () => {
+  let manager: ServiceLocatorManager
+  let mockLogger: Console
+
+  beforeEach(() => {
+    mockLogger = {
+      log: vi.fn(),
+    } as any as Console
+    manager = new ServiceLocatorManager(mockLogger)
+  })
+
+  describe('constructor', () => {
+    it('should create manager without logger', () => {
+      const managerWithoutLogger = new ServiceLocatorManager()
+      expect(managerWithoutLogger).toBeDefined()
+    })
+
+    it('should create manager with logger', () => {
+      expect(manager).toBeDefined()
+    })
+  })
+
+  describe('get', () => {
+    it('should return InstanceNotFound for non-existent instance', () => {
+      const result = manager.get('non-existent')
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toBeInstanceOf(InstanceNotFound)
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        '[ServiceLocatorManager]#getInstanceHolder() Instance non-existent not found',
+      )
+    })
+
+    it('should return valid holder for existing instance', () => {
+      const holder = manager.storeCreatedHolder(
+        'test-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      const result = manager.get('test-instance')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeUndefined()
+      expect(result[1]).toBe(holder)
+    })
+
+    it('should return InstanceExpired for expired instance with TTL', () => {
+      const holder = manager.storeCreatedHolder(
+        'expired-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+        new Set(),
+        100, // 100ms TTL
+      )
+
+      // Manually set creation time to past
+      holder.createdAt = Date.now() - 200
+
+      const result = manager.get('expired-instance')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeInstanceOf(InstanceExpired)
+      expect(result[1]).toBe(holder)
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        '[ServiceLocatorManager]#getInstanceHolder() TTL expired for expired-instance',
+      )
+    })
+
+    it('should return InstanceDestroying for destroying instance', () => {
+      const holder = manager.storeCreatedHolder(
+        'destroying-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      // Manually set status to destroying
+      holder.status = ServiceLocatorInstanceHolderStatus.Destroying
+
+      const result = manager.get('destroying-instance')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeInstanceOf(InstanceDestroying)
+      expect(result[1]).toBe(holder)
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        '[ServiceLocatorManager]#getInstanceHolder() Instance destroying-instance is destroying',
+      )
+    })
+
+    it('should return error for instance in error state', () => {
+      const holder = manager.storeCreatedHolder(
+        'error-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      // Manually set status to error with an error instance
+      holder.status = ServiceLocatorInstanceHolderStatus.Error
+      const errorInstance = new InstanceNotFound('error-instance')
+      holder.instance = errorInstance
+
+      const result = manager.get('error-instance')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeInstanceOf(InstanceNotFound)
+      expect(result[1]).toBe(holder)
+      expect(mockLogger.log).toHaveBeenCalledWith(
+        '[ServiceLocatorManager]#getInstanceHolder() Instance error-instance is in error state',
+      )
+    })
+
+    it('should handle instance with infinite TTL correctly', () => {
+      const holder = manager.storeCreatedHolder(
+        'infinite-ttl-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+        new Set(),
+        Infinity,
+      )
+
+      const result = manager.get('infinite-ttl-instance')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeUndefined()
+      expect(result[1]).toBe(holder)
+    })
+  })
+
+  describe('set', () => {
+    it('should store holder with given name', () => {
+      const holder = manager.storeCreatedHolder(
+        'test-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      manager.set('new-name', holder)
+
+      const result = manager.get('new-name')
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeUndefined()
+      expect(result[1]).toBe(holder)
+    })
+  })
+
+  describe('has', () => {
+    it('should return false for non-existent instance', () => {
+      const result = manager.has('non-existent')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeUndefined()
+      expect(result[1]).toBe(false)
+    })
+
+    it('should return true for existing instance', () => {
+      manager.storeCreatedHolder(
+        'test-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      const result = manager.has('test-instance')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toBeUndefined()
+      expect(result[1]).toBe(true)
+    })
+
+    it('should return error for expired instance', () => {
+      const holder = manager.storeCreatedHolder(
+        'expired-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+        new Set(),
+        100,
+      )
+
+      holder.createdAt = Date.now() - 200
+
+      const result = manager.has('expired-instance')
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toBeInstanceOf(InstanceExpired)
+    })
+
+    it('should return error for destroying instance', () => {
+      const holder = manager.storeCreatedHolder(
+        'destroying-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      holder.status = ServiceLocatorInstanceHolderStatus.Destroying
+
+      const result = manager.has('destroying-instance')
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toBeInstanceOf(InstanceDestroying)
+    })
+  })
+
+  describe('delete', () => {
+    it('should delete existing instance and return true', () => {
+      manager.storeCreatedHolder(
+        'test-instance',
+        { value: 'test' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      const result = manager.delete('test-instance')
+      expect(result).toBe(true)
+
+      const getResult = manager.get('test-instance')
+      expect(getResult).toHaveLength(1)
+      expect(getResult[0]).toBeInstanceOf(InstanceNotFound)
+    })
+
+    it('should return false for non-existent instance', () => {
+      const result = manager.delete('non-existent')
+      expect(result).toBe(false)
+    })
+  })
+
+  describe('filter', () => {
+    it('should filter instances by predicate', () => {
+      manager.storeCreatedHolder(
+        'instance1',
+        { value: 'test1' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+      manager.storeCreatedHolder(
+        'instance2',
+        { value: 'test2' },
+        InjectableType.Factory,
+        InjectableScope.Transient,
+      )
+
+      const result = manager.filter(
+        (holder) => holder.type === InjectableType.Class,
+      )
+
+      expect(result.size).toBe(1)
+      expect(result.has('instance1')).toBe(true)
+      expect(result.has('instance2')).toBe(false)
+    })
+
+    it('should return empty map when no instances match', () => {
+      manager.storeCreatedHolder(
+        'instance1',
+        { value: 'test1' },
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      const result = manager.filter(
+        (holder) => holder.type === InjectableType.Factory,
+      )
+
+      expect(result.size).toBe(0)
+    })
+  })
+
+  describe('createCreatingHolder', () => {
+    it('should create holder with Creating status and deferred promise', () => {
+      const [deferred, holder] = manager.createCreatingHolder(
+        'test-instance',
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      expect(deferred).toBeDefined()
+      expect(deferred.promise).toBeInstanceOf(Promise)
+      expect(holder.status).toBe(ServiceLocatorInstanceHolderStatus.Creating)
+      expect(holder.name).toBe('test-instance')
+      expect(holder.instance).toBeNull()
+      expect(holder.creationPromise).toBe(deferred.promise)
+      expect(holder.type).toBe(InjectableType.Class)
+      expect(holder.scope).toBe(InjectableScope.Singleton)
+      expect(holder.deps).toEqual(new Set())
+      expect(holder.ttl).toBe(Infinity)
+    })
+
+    it('should create holder with custom dependencies and TTL', () => {
+      const deps = new Set(['dep1', 'dep2'])
+      const ttl = 5000
+
+      const [deferred, holder] = manager.createCreatingHolder(
+        'test-instance',
+        InjectableType.Factory,
+        InjectableScope.Request,
+        deps,
+        ttl,
+      )
+
+      expect(holder.deps).toBe(deps)
+      expect(holder.ttl).toBe(ttl)
+      expect(holder.type).toBe(InjectableType.Factory)
+      expect(holder.scope).toBe(InjectableScope.Request)
+    })
+  })
+
+  describe('storeCreatedHolder', () => {
+    it('should create and store holder with Created status', () => {
+      const instance = { value: 'test' }
+      const holder = manager.storeCreatedHolder(
+        'test-instance',
+        instance,
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      expect(holder.status).toBe(ServiceLocatorInstanceHolderStatus.Created)
+      expect(holder.name).toBe('test-instance')
+      expect(holder.instance).toBe(instance)
+      expect(holder.creationPromise).toBeNull()
+      expect(holder.type).toBe(InjectableType.Class)
+      expect(holder.scope).toBe(InjectableScope.Singleton)
+      expect(holder.deps).toEqual(new Set())
+      expect(holder.ttl).toBe(Infinity)
+
+      // Verify it's stored
+      const getResult = manager.get('test-instance')
+      expect(getResult).toHaveLength(2)
+      expect(getResult[0]).toBeUndefined()
+      expect(getResult[1]).toBe(holder)
+    })
+
+    it('should create holder with custom dependencies and TTL', () => {
+      const deps = new Set(['dep1', 'dep2'])
+      const ttl = 5000
+      const instance = { value: 'test' }
+
+      const holder = manager.storeCreatedHolder(
+        'test-instance',
+        instance,
+        InjectableType.Factory,
+        InjectableScope.Request,
+        deps,
+        ttl,
+      )
+
+      expect(holder.deps).toBe(deps)
+      expect(holder.ttl).toBe(ttl)
+      expect(holder.type).toBe(InjectableType.Factory)
+      expect(holder.scope).toBe(InjectableScope.Request)
+    })
+  })
+})

package/src/__tests__/unified-api.spec.mts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest'
+
+import { InjectableScope, InjectableType } from '../enums/index.mjs'
+import { DefaultRequestContextHolder } from '../request-context-holder.mjs'
+import { ServiceLocatorManager } from '../service-locator-manager.mjs'
+
+describe('Unified API', () => {
+  describe('Common methods between ServiceLocatorManager and RequestContextHolder', () => {
+    it('should have the same basic API surface', () => {
+      const serviceManager = new ServiceLocatorManager()
+      const requestContext = new DefaultRequestContextHolder(
+        'test-request',
+        100,
+      )
+
+      // Both should have the same common methods
+      expect(typeof serviceManager.size).toBe('function')
+      expect(typeof requestContext.size).toBe('function')
+
+      expect(typeof serviceManager.isEmpty).toBe('function')
+      expect(typeof requestContext.isEmpty).toBe('function')
+
+      expect(typeof serviceManager.filter).toBe('function')
+      expect(typeof requestContext.filter).toBe('function')
+
+      expect(typeof serviceManager.clear).toBe('function')
+      expect(typeof requestContext.clear).toBe('function')
+
+      expect(typeof serviceManager.delete).toBe('function')
+      expect(typeof requestContext.delete).toBe('function')
+
+      expect(typeof serviceManager.getAllNames).toBe('function')
+      expect(typeof requestContext.getAllNames).toBe('function')
+
+      expect(typeof serviceManager.getAllHolders).toBe('function')
+      expect(typeof requestContext.getAllHolders).toBe('function')
+
+      expect(typeof serviceManager.createCreatingHolder).toBe('function')
+      expect(typeof requestContext.createCreatingHolder).toBe('function')
+    })
+
+    it('should work with the same holder creation patterns', () => {
+      const serviceManager = new ServiceLocatorManager()
+      const requestContext = new DefaultRequestContextHolder(
+        'test-request',
+        100,
+      )
+
+      // Both should be able to create holders the same way
+      const [deferred1, holder1] = serviceManager.createCreatingHolder(
+        'Service1',
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      const [deferred2, holder2] = requestContext.createCreatingHolder(
+        'Service2',
+        InjectableType.Class,
+        InjectableScope.Request,
+      )
+
+      expect(holder1.name).toBe('Service1')
+      expect(holder1.scope).toBe(InjectableScope.Singleton)
+      expect(holder2.name).toBe('Service2')
+      expect(holder2.scope).toBe(InjectableScope.Request)
+
+      // Both should be able to store holders
+      serviceManager.set('Service1', holder1)
+      requestContext.set('Service2', holder2)
+
+      expect(serviceManager.size()).toBe(1)
+      expect(requestContext.size()).toBe(1)
+    })
+
+    it('should support the same filtering patterns', () => {
+      const serviceManager = new ServiceLocatorManager()
+      const requestContext = new DefaultRequestContextHolder(
+        'test-request',
+        100,
+      )
+
+      // Create and store different types of holders
+      const singletonHolder = serviceManager.storeCreatedHolder(
+        'Singleton',
+        {},
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
+      // Create a holder first, then add it to the request context
+      const [, transientHolderTemp] = requestContext.createCreatingHolder(
+        'Transient',
+        InjectableType.Class,
+        InjectableScope.Transient,
+      )
+      requestContext.set('Transient', transientHolderTemp)
+      const transientHolder = transientHolderTemp
+
+      // Both should support the same filtering API
+      const singletons = serviceManager.filter(
+        (holder) => holder.scope === InjectableScope.Singleton,
+      )
+      const transients = requestContext.filter(
+        (holder) => holder.scope === InjectableScope.Transient,
+      )
+
+      expect(singletons.size).toBe(1)
+      expect(transients.size).toBe(1)
+      expect(singletons.get('Singleton')).toBe(singletonHolder)
+      expect(transients.get('Transient')).toBe(transientHolder)
+    })
+
+    it('should maintain their specific behaviors while sharing common API', () => {
+      const serviceManager = new ServiceLocatorManager()
+      const requestContext = new DefaultRequestContextHolder(
+        'test-request',
+        100,
+      )
+
+      // ServiceLocatorManager has specific error handling
+      const [notFound] = serviceManager.get('NonExistent')
+      expect(notFound).toBeDefined()
+
+      // RequestContextHolder has specific request features
+      expect(requestContext.requestId).toBe('test-request')
+      expect(requestContext.priority).toBe(100)
+      expect(requestContext.metadata).toBeInstanceOf(Map)
+    })
+  })
+})

package/src/base-instance-holder-manager.mts

@@ -0,0 +1,175 @@
+import type { ServiceLocatorInstanceHolder } from './service-locator-instance-holder.mjs'
+
+import { InjectableScope, InjectableType } from './enums/index.mjs'
+import { ServiceLocatorInstanceHolderStatus } from './service-locator-instance-holder.mjs'
+import { createDeferred } from './utils/defer.mjs'
+
+/**
+ * Abstract base class that provides common functionality for managing ServiceLocatorInstanceHolder objects.
+ * This class contains shared patterns used by both RequestContextHolder and ServiceLocatorManager.
+ */
+export abstract class BaseInstanceHolderManager {
+  protected readonly _holders: Map<string, ServiceLocatorInstanceHolder>
+
+  constructor(protected readonly logger: Console | null = null) {
+    this._holders = new Map()
+  }
+
+  /**
+   * Protected getter for accessing the holders map from subclasses.
+   */
+  protected get holders(): Map<string, ServiceLocatorInstanceHolder> {
+    return this._holders
+  }
+
+  /**
+   * Abstract method to get a holder by name. Each implementation defines its own return type
+   * based on their specific error handling and validation needs.
+   */
+  abstract get(name: string): any
+
+  /**
+   * Abstract method to set a holder by name. Each implementation may have different validation logic.
+   */
+  abstract set(name: string, holder: ServiceLocatorInstanceHolder): void
+
+  /**
+   * Abstract method to check if a holder exists. Each implementation may have different validation logic.
+   */
+  abstract has(name: string): any
+
+  /**
+   * Deletes a holder by name.
+   * @param name The name of the holder to delete
+   * @returns true if the holder was deleted, false if it didn't exist
+   */
+  delete(name: string): boolean {
+    return this._holders.delete(name)
+  }
+
+  /**
+   * Filters holders based on a predicate function.
+   * @param predicate Function to test each holder
+   * @returns A new Map containing only the holders that match the predicate
+   */
+  filter(
+    predicate: (
+      value: ServiceLocatorInstanceHolder<any>,
+      key: string,
+    ) => boolean,
+  ): Map<string, ServiceLocatorInstanceHolder> {
+    return new Map(
+      [...this._holders].filter(([key, value]) => predicate(value, key)),
+    )
+  }
+
+  /**
+   * Clears all holders from this manager.
+   */
+  clear(): void {
+    this._holders.clear()
+  }
+
+  /**
+   * Gets the number of holders currently managed.
+   */
+  size(): number {
+    return this._holders.size
+  }
+
+  /**
+   * Creates a new holder with Creating status and a deferred creation promise.
+   * This is useful for creating placeholder holders that can be fulfilled later.
+   * @param name The name of the instance
+   * @param type The injectable type
+   * @param scope The injectable scope
+   * @param deps Optional set of dependencies
+   * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
+   * @returns A tuple containing the deferred promise and the holder
+   */
+  createCreatingHolder<Instance>(
+    name: string,
+    type: InjectableType,
+    scope: InjectableScope,
+    deps: Set<string> = new Set(),
+    ttl: number = Infinity,
+  ): [
+    ReturnType<typeof createDeferred<[undefined, Instance]>>,
+    ServiceLocatorInstanceHolder<Instance>,
+  ] {
+    const deferred = createDeferred<[undefined, Instance]>()
+
+    const holder: ServiceLocatorInstanceHolder<Instance> = {
+      status: ServiceLocatorInstanceHolderStatus.Creating,
+      name,
+      instance: null,
+      creationPromise: deferred.promise,
+      destroyPromise: null,
+      type,
+      scope,
+      deps,
+      destroyListeners: [],
+      createdAt: Date.now(),
+      ttl,
+    }
+
+    return [deferred, holder]
+  }
+
+  /**
+   * Creates a new holder with Created status and an actual instance.
+   * This is useful for creating holders that already have their instance ready.
+   * @param name The name of the instance
+   * @param instance The actual instance to store
+   * @param type The injectable type
+   * @param scope The injectable scope
+   * @param deps Optional set of dependencies
+   * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
+   * @returns The created holder
+   */
+  protected createCreatedHolder<Instance>(
+    name: string,
+    instance: Instance,
+    type: InjectableType,
+    scope: InjectableScope,
+    deps: Set<string> = new Set(),
+    ttl: number = Infinity,
+  ): ServiceLocatorInstanceHolder<Instance> {
+    const holder: ServiceLocatorInstanceHolder<Instance> = {
+      status: ServiceLocatorInstanceHolderStatus.Created,
+      name,
+      instance,
+      creationPromise: null,
+      destroyPromise: null,
+      type,
+      scope,
+      deps,
+      destroyListeners: [],
+      createdAt: Date.now(),
+      ttl,
+    }
+
+    return holder
+  }
+
+  /**
+   * Gets all holder names currently managed.
+   */
+  getAllNames(): string[] {
+    return Array.from(this._holders.keys())
+  }
+
+  /**
+   * Gets all holders currently managed.
+   */
+  getAllHolders(): ServiceLocatorInstanceHolder[] {
+    return Array.from(this._holders.values())
+  }
+
+  /**
+   * Checks if this manager has any holders.
+   */
+  isEmpty(): boolean {
+    return this._holders.size === 0
+  }
+}

package/src/index.mts

@@ -3,6 +3,7 @@ export * from './enums/index.mjs'
 export * from './errors/index.mjs'
 export * from './interfaces/index.mjs'
 export * from './utils/index.mjs'
+export * from './base-instance-holder-manager.mjs'
 export * from './event-emitter.mjs'
 export * from './factory-context.mjs'
 export * from './injection-token.mjs'