@navios/di 0.2.0 → 0.3.0

package/src/utils/defer.mts

@@ -0,0 +1,73 @@
+/**
+ * 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>()
+}

package/src/utils/get-injectors.mts

@@ -1,5 +1,6 @@
 import type { z, ZodObject, ZodType } from 'zod/v4'
 
+import type { FactoryContext } from '../factory-context.mjs'
 import type {
   BoundInjectionToken,
   ClassType,
@@ -7,52 +8,25 @@ import type {
   InjectionToken,
   InjectionTokenSchemaType,
 } from '../injection-token.mjs'
-import type { ServiceLocator } from '../service-locator.mjs'
+import type { Factorable } from '../interfaces/factory.interface.mjs'
+import type { InjectState, Join, UnionToArray } from './types.mjs'
 
 import { InjectableTokenMeta } from '../symbols/index.mjs'
 
-export interface CreateInjectorsOptions {
-  baseLocator: ServiceLocator
-}
-type Join<TElements, TSeparator extends string> =
-  TElements extends Readonly<[infer First, ...infer Rest]>
-    ? Rest extends ReadonlyArray<string>
-      ? First extends string
-        ? `${First}${Rest extends [] ? '' : TSeparator}${Join<Rest, TSeparator>}`
-        : never
-      : never
-    : ''
-// credits goes to https://stackoverflow.com/a/50375286
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
-  k: infer I,
-) => void
-  ? I
-  : never
-
-// Converts union to overloaded function
-type UnionToOvlds<U> = UnionToIntersection<
-  U extends any ? (f: U) => void : never
->
-
-type PopUnion<U> = UnionToOvlds<U> extends (a: infer A) => void ? A : never
-
-type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true
-
-type UnionToArray<T, A extends unknown[] = []> =
-  IsUnion<T> extends true
-    ? UnionToArray<Exclude<T, PopUnion<T>>, [PopUnion<T>, ...A]>
-    : [T, ...A]
-
 export interface Injectors {
   // #1 Simple class
-  inject<T extends ClassType>(token: T): Promise<InstanceType<T>>
+  asyncInject<T extends ClassType>(
+    token: T,
+  ): InstanceType<T> extends Factorable<infer R>
+    ? Promise<R>
+    : Promise<InstanceType<T>>
   // #2 Token with required Schema
-  inject<T, S extends InjectionTokenSchemaType>(
+  asyncInject<T, S extends InjectionTokenSchemaType>(
     token: InjectionToken<T, S>,
     args: z.input<S>,
   ): Promise<T>
   // #3 Token with optional Schema
-  inject<T, S extends InjectionTokenSchemaType, R extends boolean>(
+  asyncInject<T, S extends InjectionTokenSchemaType, R extends boolean>(
     token: InjectionToken<T, S, R>,
   ): R extends false
     ? Promise<T>
@@ -63,17 +37,19 @@ export interface Injectors {
         >}`
       : 'Error: Your token requires args'
   // #4 Token with no Schema
-  inject<T>(token: InjectionToken<T, undefined>): Promise<T>
-  inject<T>(token: BoundInjectionToken<T, any>): Promise<T>
-  inject<T>(token: FactoryInjectionToken<T, any>): Promise<T>
+  asyncInject<T>(token: InjectionToken<T, undefined>): Promise<T>
+  asyncInject<T>(token: BoundInjectionToken<T, any>): Promise<T>
+  asyncInject<T>(token: FactoryInjectionToken<T, any>): Promise<T>
 
-  syncInject<T extends ClassType>(token: T): InstanceType<T>
-  syncInject<T, S extends InjectionTokenSchemaType>(
+  inject<T extends ClassType>(
+    token: T,
+  ): InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>
+  inject<T, S extends InjectionTokenSchemaType>(
     token: InjectionToken<T, S>,
     args: z.input<S>,
   ): T
   // #3 Token with optional Schema
-  syncInject<T, S extends InjectionTokenSchemaType, R extends boolean>(
+  inject<T, S extends InjectionTokenSchemaType, R extends boolean>(
     token: InjectionToken<T, S, R>,
   ): R extends false
     ? T
@@ -83,38 +59,40 @@ export interface Injectors {
           ', '
         >}`
       : 'Error: Your token requires args'
-  syncInject<T>(token: InjectionToken<T, undefined>): T
-  syncInject<T>(token: BoundInjectionToken<T, any>): T
-  syncInject<T>(token: FactoryInjectionToken<T, any>): T
+  inject<T>(token: InjectionToken<T, undefined>): T
+  inject<T>(token: BoundInjectionToken<T, any>): T
+  inject<T>(token: FactoryInjectionToken<T, any>): T
 
-  wrapSyncInit(cb: () => any): () => [any, Promise<any>[]]
+  wrapSyncInit(
+    cb: () => any,
+  ): (injectState?: InjectState) => [any, Promise<any>[], InjectState]
 
-  provideServiceLocator(locator: ServiceLocator): ServiceLocator
+  provideFactoryContext(context: FactoryContext | null): FactoryContext | null
 }
 
-export const InjectorsBase = new Map<ServiceLocator, Injectors>()
+export function getInjectors() {
+  let currentFactoryContext: FactoryContext | null = null
 
-export function getInjectors({ baseLocator }: CreateInjectorsOptions) {
-  if (InjectorsBase.has(baseLocator)) {
-    return InjectorsBase.get(baseLocator)!
+  function provideFactoryContext(
+    context: FactoryContext,
+  ): FactoryContext | null {
+    const original = currentFactoryContext
+    currentFactoryContext = context
+    return original
   }
-  let currentLocator: ServiceLocator = baseLocator
-
-  function getServiceLocator() {
-    if (!currentLocator) {
+  function getFactoryContext(): FactoryContext {
+    if (!currentFactoryContext) {
       throw new Error(
-        '[Injector] Service locator is not initialized. Please provide the service locator before using the @Injectable decorator.',
+        '[Injector] Trying to access injection context outside of a injectable context',
       )
     }
-    return currentLocator
-  }
-  function provideServiceLocator(locator: ServiceLocator): ServiceLocator {
-    const original = currentLocator
-    currentLocator = locator
-    return original
+    return currentFactoryContext
   }
 
-  function inject(
+  let promiseCollector: null | ((promise: Promise<any>) => void) = null
+  let injectState: InjectState | null = null
+
+  function asyncInject(
     token:
       | ClassType
       | InjectionToken<any>
@@ -122,43 +100,79 @@ export function getInjectors({ baseLocator }: CreateInjectorsOptions) {
       | FactoryInjectionToken<any, any>,
     args?: unknown,
   ) {
-    // @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',
+      )
+    }
+    if (injectState.isFrozen) {
+      const idx = injectState.currentIndex++
+      const request = injectState.requests[idx]
+      if (request.token !== token) {
+        throw new Error(
+          `[Injector] Wrong token order. Expected ${request.token.toString()} but got ${token.toString()}`,
+        )
+      }
+      return request.promise
+    }
 
-    // @ts-expect-error We check the type in overload
-    return getServiceLocator().getOrThrowInstance(realToken, args)
-  }
+    const promise = getFactoryContext().inject(token as any, args as any)
+    injectState.requests.push({
+      token,
+      promise,
+    })
+    injectState.currentIndex++
 
-  let promiseCollector: null | ((promise: Promise<any>) => void) = null
+    return promise
+  }
 
   function wrapSyncInit(cb: () => any) {
-    return () => {
+    return (previousState?: InjectState) => {
       const promises: Promise<any>[] = []
       const originalPromiseCollector = promiseCollector
+      const originalInjectState = injectState
+      injectState = previousState
+        ? {
+            ...previousState,
+            currentIndex: 0,
+          }
+        : {
+            currentIndex: 0,
+            isFrozen: false,
+            requests: [],
+          }
       promiseCollector = (promise) => {
         promises.push(promise)
       }
       const result = cb()
       promiseCollector = originalPromiseCollector
-      return [result, promises]
+      const newInjectState = {
+        ...injectState,
+        isFrozen: true,
+      }
+      injectState = originalInjectState
+      return [result, promises, newInjectState]
     }
   }
 
-  function syncInject<
+  function inject<
     T,
     Token extends
       | InjectionToken<T>
       | BoundInjectionToken<T, any>
       | FactoryInjectionToken<T, any>,
-    S extends ZodObject<any> | unknown = Token['schema'],
-  >(token: Token, args?: S extends ZodObject<any> ? z.input<S> : never): T {
+    S extends ZodObject | unknown = Token['schema'],
+  >(token: Token, args?: S extends ZodObject ? z.input<S> : never): T {
     // @ts-expect-error In case we have a class
     const realToken = token[InjectableTokenMeta] ?? token
 
-    const instance = getServiceLocator().getSyncInstance(realToken, args)
+    const instance = getFactoryContext().locator.getSyncInstance(
+      realToken,
+      args,
+    )
     if (!instance) {
       if (promiseCollector) {
-        const promise = getServiceLocator().getInstance(realToken, args)
+        const promise = getFactoryContext().inject(realToken, args)
         promiseCollector(promise)
       } else {
         throw new Error(`[Injector] Cannot initiate ${realToken.toString()}`)
@@ -168,7 +182,7 @@ export function getInjectors({ baseLocator }: CreateInjectorsOptions) {
         {
           get() {
             throw new Error(
-              `[Injector] Trying to access ${realToken.toString()} before it's initialized, please use inject() instead of syncInject() or do not use the value outside of class methods`,
+              `[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`,
             )
           },
         },
@@ -178,12 +192,11 @@ export function getInjectors({ baseLocator }: CreateInjectorsOptions) {
   }
 
   const injectors: Injectors = {
+    asyncInject,
     inject,
-    syncInject,
     wrapSyncInit,
-    provideServiceLocator,
+    provideFactoryContext,
   } as Injectors
-  InjectorsBase.set(baseLocator, injectors)
 
   return injectors
 }

package/src/utils/index.mts

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

package/src/utils/types.mts

@@ -0,0 +1,52 @@
+import type {
+  BoundInjectionToken,
+  ClassType,
+  FactoryInjectionToken,
+  InjectionToken,
+} from '../injection-token.mjs'
+
+// Utility types for string manipulation and union handling
+export type Join<TElements, TSeparator extends string> =
+  TElements extends Readonly<[infer First, ...infer Rest]>
+    ? Rest extends ReadonlyArray<string>
+      ? First extends string
+        ? `${First}${Rest extends [] ? '' : TSeparator}${Join<Rest, TSeparator>}`
+        : never
+      : never
+    : ''
+
+// credits goes to https://stackoverflow.com/a/50375286
+export type UnionToIntersection<U> = (
+  U extends any ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never
+
+// Converts union to overloaded function
+export type UnionToOvlds<U> = UnionToIntersection<
+  U extends any ? (f: U) => void : never
+>
+
+export type PopUnion<U> =
+  UnionToOvlds<U> extends (a: infer A) => void ? A : never
+
+export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true
+
+export type UnionToArray<T, A extends unknown[] = []> =
+  IsUnion<T> extends true
+    ? UnionToArray<Exclude<T, PopUnion<T>>, [PopUnion<T>, ...A]>
+    : [T, ...A]
+
+// 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>
+  }[]
+}

package/docs/concepts/injectable.md

@@ -1,182 +0,0 @@
-# @Injectable decorator
-
-The `@Injectable` decorator is used to define a class or a factory class as an injectable service.
-
-## Parameters
-
-The `@Injectable` decorator accepts the following fields in its options:
-
-- `token`: The injection token to use for the service. If not provided, will create a new token using the class itself.
-- `scope`: The lifetime of the service. Accepts `InjectableScope.Singleton` or `InjectableScope.Instance`. By default, it will be `InjectableScope.Singleton`.
-- `type`: The type of the service. Accepts `InjectableType.Class` or `InjectableType.Factory`. By default, it will be `InjectableType.Class`.
-- `registry`: The registry to use for the service. Uses the default registry if not provided.
-
-## Usage
-
-Injectable can be used as a class decorator or a factory decorator.
-
-Inside a class that you're decorating with `@Injectable` you can use `inject` and `syncInject` functions to inject the services.
-
-```ts
-@Injectable()
-class GreeterService {
-  sayHello(name: string) {
-    return `Hello ${name}`
-  }
-}
-
-@Injectable()
-class UserService {
-  private readonly greeterService = syncInject(GreeterService)
-
-  makeGreeting(name: string) {
-    return this.greeterService.sayHello(name)
-  }
-}
-```
-
-Please note that `syncInject` can be used only with services that are created with `InjectableScope.Singleton`.
-
-If you need to inject a service that is created with `InjectableScope.Instance`, you can use `inject` function. and it will return a Promise.
-
-For example:
-
-```ts
-@Injectable({ scope: InjectableScope.Instance })
-class GreeterService {
-  private readonly createdAt = new Date()
-
-  sayHello(name: string) {
-    return `Hello ${name} ${this.createdAt.toISOString()}`
-  }
-}
-
-@Injectable()
-class UserService {
-  private readonly greeterService = inject(GreeterService)
-
-  async makeGreeting(name: string) {
-    const service = await this.greeterService
-    return service.sayHello(name)
-  }
-}
-```
-
-## Examples
-
-### Simple class
-
-```ts
-@Injectable()
-class GreeterService {
-  sayHello(name: string) {
-    return `Hello ${name}`
-  }
-}
-
-const greeterService = await inject(GreeterService)
-console.log(greeterService.sayHello('John'))
-```
-
-### Simple Factory
-
-```ts
-@Injectable({ type: InjectableType.Factory })
-class GreeterServiceFactory {
-  create() {
-    return new GreeterService()
-  }
-}
-
-const greeterService = await inject(GreeterServiceFactory)
-console.log(greeterService.sayHello('John'))
-```
-
-### Class with token
-
-```ts
-export interface GreeterServiceInterface {
-  sayHello(name: string): string
-}
-
-const GreeterServiceParams = z.object({
-  context: z.string(),
-})
-
-export const GREETER_SERVICE = InjectionToken.create<
-  GreeterServiceInterface,
-  typeof GreeterServiceParams
->('GreeterService', GreeterServiceParams)
-
-@Injectable({ token: GREETER_SERVICE })
-class GreeterService {
-  constructor(private readonly config: z.infer<typeof GreeterServiceParams>) {}
-
-  sayHello(name: string) {
-    return `Hello ${name} ${this.config.context}`
-  }
-}
-
-const greeterService = await inject(GREETER_SERVICE, { context: 'World' })
-console.log(greeterService.sayHello('John'))
-```
-
-### Factory with token
-
-```ts
-export interface GreeterServiceInterface {
-  sayHello(name: string): string
-}
-
-const GreeterServiceParams = z.object({
-  context: z.string(),
-})
-
-export const GREETER_SERVICE = InjectionToken.create<
-  GreeterServiceInterface,
-  typeof GreeterServiceParams
->('GreeterService', GreeterServiceParams)
-
-@Injectable({ type: InjectableType.Factory, token: GREETER_SERVICE })
-class GreeterServiceFactory {
-  create(ctx: FactoryContext, args: z.infer<typeof GreeterServiceParams>) {
-    return new GreeterService(args)
-  }
-}
-
-const greeterService = await inject(GREETER_SERVICE, { context: 'World' })
-console.log(greeterService.sayHello('John'))
-```
-
-## InjectableScope
-
-The `InjectableScope` enum defines the scope of the service.
-
-- `InjectableScope.Singleton`: The service will be created once and reused.
-- `InjectableScope.Instance`: The service will be created every time it is injected.
-
-## InjectableType
-
-The `InjectableType` enum defines the type of the service.
-
-- `InjectableType.Class`: The service will be a class.
-- `InjectableType.Factory`: The service will be a factory.
-
-## Registry
-
-The `Registry` is the registry of the service. It is used to store the service and its dependencies.
-
-## FactoryContext
-
-The `FactoryContext` is the context of the factory. It is used to add additional information to the factory.
-
-Context API:
-
-- `inject`: Injects the service, same as global inject, but additionally it will track the dependencies of the service.
-- `on`: Adds a listener to the service locator event bus.
-- `getDependencies`: Returns the dependencies of the service.
-- `invalidate`: Invalidates self and all the services that depend on it.
-- `addEffect`: Adds an effect to the service. Effect is a function that will be called when the service is invalidated.
-- `setTtl`: Sets the ttl of the service.
-- `getTtl`: Returns the ttl of the service.
-- `locator`: Returns the service locator you are currently in.