@navios/di 0.4.1 → 0.5.0

package/src/utils/get-injectors.mts

@@ -4,22 +4,45 @@ import type { FactoryContext } from '../factory-context.mjs'
 import type {
   BoundInjectionToken,
   ClassType,
+  ClassTypeWithArgument,
+  ClassTypeWithoutArguments,
   FactoryInjectionToken,
   InjectionToken,
   InjectionTokenSchemaType,
 } from '../injection-token.mjs'
-import type { Factorable } from '../interfaces/factory.interface.mjs'
-import type { InjectState, Join, UnionToArray } from './types.mjs'
+import type {
+  Factorable,
+  FactorableWithArgs,
+} from '../interfaces/factory.interface.mjs'
+import type {
+  InjectRequest,
+  InjectState,
+  Join,
+  UnionToArray,
+} from './types.mjs'
 
 import { InjectableTokenMeta } from '../symbols/index.mjs'
 
 export interface Injectors {
   // #1 Simple class
-  asyncInject<T extends ClassType>(
+  asyncInject<T extends ClassTypeWithoutArguments>(
     token: T,
   ): InstanceType<T> extends Factorable<infer R>
     ? Promise<R>
     : Promise<InstanceType<T>>
+  asyncInject<Args, T extends ClassTypeWithArgument<Args>>(
+    token: T,
+    args: Args,
+  ): Promise<InstanceType<T>>
+  asyncInject<
+    Schema extends InjectionTokenSchemaType,
+    R,
+    T extends FactorableWithArgs<R, Schema>,
+  >(
+    token: T,
+    args: z.input<Schema>,
+  ): Promise<R>
+
   // #2 Token with required Schema
   asyncInject<T, S extends InjectionTokenSchemaType>(
     token: InjectionToken<T, S>,
@@ -41,9 +64,22 @@ export interface Injectors {
   asyncInject<T>(token: BoundInjectionToken<T, any>): Promise<T>
   asyncInject<T>(token: FactoryInjectionToken<T, any>): Promise<T>
 
-  inject<T extends ClassType>(
+  inject<T extends ClassTypeWithoutArguments>(
     token: T,
   ): InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>
+  inject<Args, T extends ClassTypeWithArgument<Args>>(
+    token: T,
+    args: Args,
+  ): InstanceType<T>
+  inject<
+    Schema extends InjectionTokenSchemaType,
+    R,
+    T extends FactorableWithArgs<R, Schema>,
+  >(
+    token: T,
+    args: z.input<Schema>,
+  ): R
+
   inject<T, S extends InjectionTokenSchemaType>(
     token: InjectionToken<T, S>,
     args: z.input<S>,
@@ -63,6 +99,45 @@ export interface Injectors {
   inject<T>(token: BoundInjectionToken<T, any>): T
   inject<T>(token: FactoryInjectionToken<T, any>): T
 
+  /**
+   * Optional injection that returns null if the service fails to initialize
+   * or is not available. This is useful when you want to inject a service
+   * that may not be configured or may fail gracefully.
+   *
+   * @example
+   * ```ts
+   * class MyService {
+   *   constructor() {
+   *     const optionalService = optional(OptionalServiceToken)
+   *     // optionalService will be null if initialization fails
+   *     if (optionalService) {
+   *       optionalService.doSomething()
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  optional<T extends ClassType>(
+    token: T,
+  ): (InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>) | null
+  optional<T, S extends InjectionTokenSchemaType>(
+    token: InjectionToken<T, S>,
+    args: z.input<S>,
+  ): T | null
+  optional<T, S extends InjectionTokenSchemaType, R extends boolean>(
+    token: InjectionToken<T, S, R>,
+  ): R extends false
+    ? T | null
+    : S extends ZodType<infer Type>
+      ? `Error: Your token requires args: ${Join<
+          UnionToArray<keyof Type>,
+          ', '
+        >}`
+      : 'Error: Your token requires args'
+  optional<T>(token: InjectionToken<T, undefined>): T | null
+  optional<T>(token: BoundInjectionToken<T, any>): T | null
+  optional<T>(token: FactoryInjectionToken<T, any>): T | null
+
   wrapSyncInit(
     cb: () => any,
   ): (injectState?: InjectState) => [any, Promise<any>[], InjectState]
@@ -92,17 +167,10 @@ export function getInjectors() {
   let promiseCollector: null | ((promise: Promise<any>) => void) = null
   let injectState: InjectState | null = null
 
-  function asyncInject(
-    token:
-      | ClassType
-      | InjectionToken<any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
-    args?: unknown,
-  ) {
+  function getRequest(token: InjectionToken<any>, args?: unknown) {
     if (!injectState) {
       throw new Error(
-        '[Injector] Trying to access inject outside of a injectable context',
+        '[Injector] Trying to make a request outside of a injectable context',
       )
     }
     if (injectState.isFrozen) {
@@ -113,17 +181,59 @@ export function getInjectors() {
           `[Injector] Wrong token order. Expected ${request.token.toString()} but got ${token.toString()}`,
         )
       }
-      return request.promise
+      return request
     }
-
-    const promise = getFactoryContext().inject(token as any, args as any)
-    injectState.requests.push({
+    let result: any = null
+    let error: Error | null = null
+    const promise = getFactoryContext()
+      .inject(token as any, args as any)
+      .then((r) => {
+        result = r
+        return r
+      })
+      .catch((e) => {
+        // We don't throw here because we have a mechanism to handle errors
+        error = e
+      })
+    const request: InjectRequest = {
       token,
       promise,
-    })
+      get result() {
+        return result
+      },
+      get error() {
+        return error
+      },
+    }
+    injectState.requests.push(request)
     injectState.currentIndex++
 
-    return promise
+    return request
+  }
+
+  function asyncInject(
+    token:
+      | ClassType
+      | InjectionToken<any>
+      | BoundInjectionToken<any, any>
+      | FactoryInjectionToken<any, any>,
+    args?: unknown,
+  ) {
+    if (!injectState) {
+      throw new Error(
+        '[Injector] Trying to access inject outside of a injectable context',
+      )
+    }
+    // @ts-expect-error In case we have a class
+    const realToken = token[InjectableTokenMeta] ?? token
+    const request = getRequest(realToken, args)
+    return request.promise.then((result) => {
+      if (request.error) {
+        // We throw here because we want to fail the asyncInject call if the dependency fails to initialize
+        throw request.error
+      }
+      return result
+    })
   }
 
   function wrapSyncInit(cb: () => any) {
@@ -166,23 +276,33 @@ export function getInjectors() {
     // @ts-expect-error In case we have a class
     const realToken = token[InjectableTokenMeta] ?? token
 
+    if (!injectState) {
+      throw new Error(
+        '[Injector] Trying to access inject outside of a injectable context',
+      )
+    }
+
     const instance = getFactoryContext().locator.getSyncInstance(
       realToken,
       args,
     )
     if (!instance) {
+      const request = getRequest(realToken, args)
+      if (request.error) {
+        throw request.error
+      } else if (request.result) {
+        return request.result
+      }
       if (promiseCollector) {
-        const promise = getFactoryContext().inject(realToken, args)
-        promiseCollector(promise)
-      } else {
-        throw new Error(`[Injector] Cannot initiate ${realToken.toString()}`)
+        promiseCollector(request.promise)
       }
+      // Return a dynamic proxy that looks up the instance when accessed
       return new Proxy(
         {},
         {
           get() {
             throw new Error(
-              `[Injector] Trying to access ${realToken.toString()} before it's initialized, please use asyncInject() instead of inject() or do not use the value outside of class methods`,
+              `[Injector] Trying to access ${realToken.toString()} before it's initialized, please move the code to a onServiceInit method`,
             )
           },
         },
@@ -191,9 +311,26 @@ export function getInjectors() {
     return instance as unknown as T
   }
 
+  function optional<
+    T,
+    Token extends
+      | InjectionToken<T>
+      | BoundInjectionToken<T, any>
+      | FactoryInjectionToken<T, any>,
+    S extends ZodObject | unknown = Token['schema'],
+  >(token: Token, args?: S extends ZodObject ? z.input<S> : never): T | null {
+    try {
+      return inject(token, args)
+    } catch {
+      // If injection fails, return null instead of throwing
+      return null
+    }
+  }
+
   const injectors: Injectors = {
     asyncInject,
     inject,
+    optional,
     wrapSyncInit,
     provideFactoryContext,
   } as Injectors

package/src/utils/index.mts

@@ -1,4 +1,3 @@
 export * from './get-injectors.mjs'
 export * from './get-injectable-token.mjs'
-export * from './defer.mjs'
 export * from './types.mjs'

package/src/utils/types.mts

@@ -37,16 +37,20 @@ export type UnionToArray<T, A extends unknown[] = []> =
     ? UnionToArray<Exclude<T, PopUnion<T>>, [PopUnion<T>, ...A]>
     : [T, ...A]
 
+export type InjectRequest = {
+  token:
+    | InjectionToken<any>
+    | BoundInjectionToken<any, any>
+    | FactoryInjectionToken<any, any>
+    | ClassType
+  promise: Promise<any>
+  readonly result: any
+  readonly error: Error | null
+}
+
 // InjectState interface for managing injection state
 export interface InjectState {
   currentIndex: number
   isFrozen: boolean
-  requests: {
-    token:
-      | InjectionToken<any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>
-      | ClassType
-    promise: Promise<any>
-  }[]
+  requests: InjectRequest[]
 }

package/tsup.config.mts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsup'
 
 export default defineConfig({
-  entry: ['src/index.mts'],
+  entry: ['src/index.mts', 'src/testing/index.mts'],
   outDir: 'lib',
   format: ['esm', 'cjs'],
   clean: true,

package/src/__tests__/defer.spec.mts

@@ -1,166 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { createDeferred, Deferred } from '../utils/defer.mjs'
-
-describe('Deferred', () => {
-  describe('constructor', () => {
-    it('should create a deferred promise', () => {
-      const deferred = new Deferred<string>()
-
-      expect(deferred.promise).toBeInstanceOf(Promise)
-      expect(deferred.isResolved).toBe(false)
-      expect(deferred.isRejected).toBe(false)
-      expect(deferred.isSettled).toBe(false)
-    })
-  })
-
-  describe('resolve', () => {
-    it('should resolve the promise with given value', async () => {
-      const deferred = new Deferred<string>()
-      const testValue = 'test value'
-
-      deferred.resolve(testValue)
-      const result = await deferred.promise
-
-      expect(result).toBe(testValue)
-      expect(deferred.isResolved).toBe(true)
-      expect(deferred.isRejected).toBe(false)
-      expect(deferred.isSettled).toBe(true)
-    })
-
-    it('should throw error if already resolved', () => {
-      const deferred = new Deferred<string>()
-
-      deferred.resolve('test')
-
-      expect(() => {
-        deferred.resolve('test2')
-      }).toThrow('Deferred promise has already been resolved or rejected')
-    })
-
-    it('should throw error if already rejected', async () => {
-      const deferred = new Deferred<string>()
-
-      deferred.reject(new Error('test error'))
-
-      // Catch the rejection to avoid unhandled promise rejection
-      try {
-        await deferred.promise
-      } catch (error) {
-        // Expected to fail
-      }
-
-      expect(() => {
-        deferred.resolve('test')
-      }).toThrow('Deferred promise has already been resolved or rejected')
-    })
-  })
-
-  describe('reject', () => {
-    it('should reject the promise with given reason', async () => {
-      const deferred = new Deferred<string>()
-      const testError = new Error('test error')
-
-      deferred.reject(testError)
-
-      await expect(deferred.promise).rejects.toThrow('test error')
-      expect(deferred.isResolved).toBe(false)
-      expect(deferred.isRejected).toBe(true)
-      expect(deferred.isSettled).toBe(true)
-    })
-
-    it('should reject with string reason', async () => {
-      const deferred = new Deferred<string>()
-
-      deferred.reject('string error')
-
-      try {
-        await deferred.promise
-        expect.fail('Should have rejected')
-      } catch (error) {
-        expect(error).toBe('string error')
-      }
-    })
-
-    it('should throw error if already resolved', () => {
-      const deferred = new Deferred<string>()
-
-      deferred.resolve('test')
-
-      expect(() => {
-        deferred.reject(new Error('test error'))
-      }).toThrow('Deferred promise has already been resolved or rejected')
-    })
-
-    it('should throw error if already rejected', async () => {
-      const deferred = new Deferred<string>()
-
-      deferred.reject(new Error('first error'))
-
-      // Catch the rejection to avoid unhandled promise rejection
-      try {
-        await deferred.promise
-      } catch (error) {
-        // Expected to fail
-      }
-
-      expect(() => {
-        deferred.reject(new Error('second error'))
-      }).toThrow('Deferred promise has already been resolved or rejected')
-    })
-  })
-
-  describe('status getters', () => {
-    it('should return correct status for unresolved promise', () => {
-      const deferred = new Deferred<string>()
-
-      expect(deferred.isResolved).toBe(false)
-      expect(deferred.isRejected).toBe(false)
-      expect(deferred.isSettled).toBe(false)
-    })
-
-    it('should return correct status after resolve', () => {
-      const deferred = new Deferred<string>()
-
-      deferred.resolve('test')
-
-      expect(deferred.isResolved).toBe(true)
-      expect(deferred.isRejected).toBe(false)
-      expect(deferred.isSettled).toBe(true)
-    })
-
-    it('should return correct status after reject', async () => {
-      const deferred = new Deferred<string>()
-
-      deferred.reject(new Error('test'))
-
-      // Catch the rejection to avoid unhandled promise rejection
-      try {
-        await deferred.promise
-      } catch (error) {
-        // Expected to fail
-      }
-
-      expect(deferred.isResolved).toBe(false)
-      expect(deferred.isRejected).toBe(true)
-      expect(deferred.isSettled).toBe(true)
-    })
-  })
-})
-
-describe('createDeferred', () => {
-  it('should create a new Deferred instance', () => {
-    const deferred = createDeferred<string>()
-
-    expect(deferred).toBeInstanceOf(Deferred)
-    expect(deferred.promise).toBeInstanceOf(Promise)
-  })
-
-  it('should create independent instances', () => {
-    const deferred1 = createDeferred<string>()
-    const deferred2 = createDeferred<string>()
-
-    expect(deferred1).not.toBe(deferred2)
-    expect(deferred1.promise).not.toBe(deferred2.promise)
-  })
-})

package/src/errors/errors.enum.mts

@@ -1,8 +0,0 @@
-export enum ErrorsEnum {
-  InstanceExpired = 'InstanceExpired',
-  InstanceNotFound = 'InstanceNotFound',
-  InstanceDestroying = 'InstanceDestroying',
-  UnknownError = 'UnknownError',
-  FactoryNotFound = 'FactoryNotFound',
-  FactoryTokenNotResolved = 'FactoryTokenNotResolved',
-}

package/src/errors/factory-not-found.mts

@@ -1,8 +0,0 @@
-import { ErrorsEnum } from './errors.enum.mjs'
-
-export class FactoryNotFound extends Error {
-  code = ErrorsEnum.FactoryNotFound
-  constructor(public name: string) {
-    super(`Factory ${name} not found`)
-  }
-}

package/src/errors/factory-token-not-resolved.mts

@@ -1,10 +0,0 @@
-import type { ClassType } from '../injection-token.mjs'
-
-import { ErrorsEnum } from './errors.enum.mjs'
-
-export class FactoryTokenNotResolved extends Error {
-  code = ErrorsEnum.FactoryTokenNotResolved
-  constructor(name: string | symbol | ClassType) {
-    super(`Factory token not resolved: ${name.toString()}`)
-  }
-}

package/src/errors/instance-destroying.mts

@@ -1,8 +0,0 @@
-import { ErrorsEnum } from './errors.enum.mjs'
-
-export class InstanceDestroying extends Error {
-  code = ErrorsEnum.InstanceDestroying
-  constructor(public name: string) {
-    super(`Instance ${name} destroying`)
-  }
-}

package/src/errors/instance-expired.mts

@@ -1,8 +0,0 @@
-import { ErrorsEnum } from './errors.enum.mjs'
-
-export class InstanceExpired extends Error {
-  code = ErrorsEnum.InstanceExpired
-  constructor(public name: string) {
-    super(`Instance ${name} expired`)
-  }
-}

package/src/errors/instance-not-found.mts

@@ -1,8 +0,0 @@
-import { ErrorsEnum } from './errors.enum.mjs'
-
-export class InstanceNotFound extends Error {
-  code = ErrorsEnum.InstanceNotFound
-  constructor(public name: string) {
-    super(`Instance ${name} not found`)
-  }
-}

package/src/errors/unknown-error.mts

@@ -1,15 +0,0 @@
-import { ErrorsEnum } from './errors.enum.mjs'
-
-export class UnknownError extends Error {
-  code = ErrorsEnum.UnknownError
-  parent?: Error
-
-  constructor(message: string | Error) {
-    if (message instanceof Error) {
-      super(message.message)
-      this.parent = message
-      return
-    }
-    super(message)
-  }
-}

package/src/utils/defer.mts

@@ -1,73 +0,0 @@
-/**
- * Creates a deferred promise that can be resolved or rejected externally.
- * This is useful for creating stub holders that can be fulfilled later.
- */
-export class Deferred<T> {
-  public readonly promise: Promise<T>
-  private _resolve!: (value: T) => void
-  private _reject!: (reason?: any) => void
-  private _isResolved = false
-  private _isRejected = false
-
-  constructor() {
-    this.promise = new Promise<T>((resolve, reject) => {
-      this._resolve = resolve
-      this._reject = reject
-    })
-  }
-
-  /**
-   * Resolves the deferred promise with the given value.
-   * @param value The value to resolve with
-   * @throws Error if the promise has already been resolved or rejected
-   */
-  resolve(value: T): void {
-    if (this._isResolved || this._isRejected) {
-      throw new Error('Deferred promise has already been resolved or rejected')
-    }
-    this._isResolved = true
-    this._resolve(value)
-  }
-
-  /**
-   * Rejects the deferred promise with the given reason.
-   * @param reason The reason for rejection
-   * @throws Error if the promise has already been resolved or rejected
-   */
-  reject(reason?: any): void {
-    if (this._isResolved || this._isRejected) {
-      throw new Error('Deferred promise has already been resolved or rejected')
-    }
-    this._isRejected = true
-    this._reject(reason)
-  }
-
-  /**
-   * Returns true if the promise has been resolved.
-   */
-  get isResolved(): boolean {
-    return this._isResolved
-  }
-
-  /**
-   * Returns true if the promise has been rejected.
-   */
-  get isRejected(): boolean {
-    return this._isRejected
-  }
-
-  /**
-   * Returns true if the promise has been settled (resolved or rejected).
-   */
-  get isSettled(): boolean {
-    return this._isResolved || this._isRejected
-  }
-}
-
-/**
- * Creates a new deferred promise.
- * @returns A new Deferred instance
- */
-export function createDeferred<T>(): Deferred<T> {
-  return new Deferred<T>()
-}