@navios/di 0.2.0 → 0.3.0

package/src/service-locator.mts

@@ -4,12 +4,16 @@ import type { z, ZodObject, ZodOptional } from 'zod/v4'
 
 import type { FactoryContext } from './factory-context.mjs'
 import type {
+  AnyInjectableType,
   BaseInjectionTokenSchemaType,
   InjectionTokenSchemaType,
+  InjectionTokenType,
   OptionalInjectionTokenSchemaType,
 } from './injection-token.mjs'
 import type { Registry } from './registry.mjs'
+import type { RequestContextHolder } from './request-context-holder.mjs'
 import type { ServiceLocatorInstanceHolder } from './service-locator-instance-holder.mjs'
+import type { Injectors } from './utils/index.mjs'
 
 import { InjectableScope } from './enums/index.mjs'
 import {
@@ -23,363 +27,575 @@ import {
   FactoryInjectionToken,
   InjectionToken,
 } from './injection-token.mjs'
+import { defaultInjectors } from './injector.mjs'
 import { globalRegistry } from './registry.mjs'
+import { DefaultRequestContextHolder } from './request-context-holder.mjs'
+import { ServiceInstantiator } from './service-instantiator.mjs'
 import { ServiceLocatorEventBus } from './service-locator-event-bus.mjs'
-import {
-  ServiceLocatorInstanceHolderKind,
-  ServiceLocatorInstanceHolderStatus,
-} from './service-locator-instance-holder.mjs'
+import { ServiceLocatorInstanceHolderStatus } from './service-locator-instance-holder.mjs'
 import { ServiceLocatorManager } from './service-locator-manager.mjs'
 import { getInjectableToken } from './utils/index.mjs'
 
 export class ServiceLocator {
   private readonly eventBus: ServiceLocatorEventBus
   private readonly manager: ServiceLocatorManager
+  private readonly serviceInstantiator: ServiceInstantiator
+  private readonly requestContexts = new Map<string, RequestContextHolder>()
+  private currentRequestContext: RequestContextHolder | null = null
 
   constructor(
     private readonly registry: Registry = globalRegistry,
     private readonly logger: Console | null = null,
+    private readonly injectors: Injectors = defaultInjectors,
   ) {
     this.eventBus = new ServiceLocatorEventBus(logger)
     this.manager = new ServiceLocatorManager(logger)
+    this.serviceInstantiator = new ServiceInstantiator(injectors)
   }
 
+  // ============================================================================
+  // PUBLIC METHODS
+  // ============================================================================
+
   getEventBus() {
     return this.eventBus
   }
 
-  public storeInstance<Instance>(
-    instance: Instance,
-    token: BoundInjectionToken<Instance, any>,
-  ): void
-  public storeInstance<Instance>(
-    instance: Instance,
-    token: FactoryInjectionToken<Instance, any>,
-  ): void
-  public storeInstance<Instance>(
-    instance: Instance,
-    token: InjectionToken<Instance, undefined>,
-  ): void
-  public storeInstance<
-    Instance,
-    Schema extends ZodObject<any> | ZodOptional<ZodObject<any>>,
-  >(
-    instance: Instance,
-    token: InjectionToken<Instance, Schema>,
-    args: z.input<Schema>,
-  ): void
-  public storeInstance(
-    instance: any,
-    token:
-      | InjectionToken<any, any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
-    args?: any,
-  ): void {
-    // @ts-expect-error We should redefine the instance name type
-    const instanceName = this.getInstanceIdentifier(token, args)
-    this.manager.set(instanceName, {
-      name: instanceName,
-      instance,
-      status: ServiceLocatorInstanceHolderStatus.Created,
-      kind: ServiceLocatorInstanceHolderKind.Instance,
-      createdAt: Date.now(),
-      ttl: Infinity,
-      deps: [],
-      destroyListeners: [],
-      effects: [],
-      destroyPromise: null,
-      creationPromise: null,
-    })
-    this.notifyListeners(instanceName)
+  getManager() {
+    return this.manager
   }
 
-  public removeInstance<Instance>(
-    token: BoundInjectionToken<Instance, any>,
-  ): void
-  public removeInstance<Instance>(
-    token: FactoryInjectionToken<Instance, any>,
-  ): void
-  public removeInstance<Instance>(
-    token: InjectionToken<Instance, undefined>,
-  ): void
-  public removeInstance<Instance, Schema extends BaseInjectionTokenSchemaType>(
-    token: InjectionToken<Instance, Schema>,
-    args: z.input<Schema>,
-  ): void
-  public removeInstance<
-    Instance,
-    Schema extends OptionalInjectionTokenSchemaType,
-  >(token: InjectionToken<Instance, Schema>, args?: z.input<Schema>): void
-
-  public removeInstance(
-    token:
-      | InjectionToken<any, any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
+  public getInstanceIdentifier(token: AnyInjectableType, args?: any): string {
+    const [err, { actualToken, validatedArgs }] =
+      this.validateAndResolveTokenArgs(token, args)
+    if (err) {
+      throw err
+    }
+    return this.generateInstanceName(actualToken, validatedArgs)
+  }
+
+  public async getInstance(
+    token: AnyInjectableType,
     args?: any,
+    onPrepare?: (data: {
+      instanceName: string
+      actualToken: InjectionTokenType
+      validatedArgs?: any
+    }) => void,
   ) {
-    // @ts-expect-error We should redefine the instance name type
-    const instanceName = this.getInstanceIdentifier(token, args)
-    return this.invalidate(instanceName)
+    const [err, data] = await this.resolveTokenAndPrepareInstanceName(
+      token,
+      args,
+    )
+    if (err) {
+      return [err]
+    }
+    const { instanceName, validatedArgs, actualToken, realToken } = data
+    if (onPrepare) {
+      onPrepare({ instanceName, actualToken, validatedArgs })
+    }
+    const [error, holder] = await this.retrieveOrCreateInstanceByInstanceName(
+      instanceName,
+      realToken,
+      validatedArgs,
+    )
+    if (error) {
+      return [error]
+    }
+    return [undefined, holder.instance]
   }
 
-  private resolveTokenArgs<
-    Instance,
-    Schema extends BaseInjectionTokenSchemaType,
-  >(
-    token: InjectionToken<Instance, Schema>,
-    args: z.input<Schema>,
-  ): [undefined, z.output<Schema>] | [UnknownError]
-  private resolveTokenArgs<
+  public async getOrThrowInstance<Instance>(
+    token: AnyInjectableType,
+    args: any,
+  ): Promise<Instance> {
+    const [error, instance] = await this.getInstance(token, args)
+    if (error) {
+      throw error
+    }
+    return instance
+  }
+
+  public getSyncInstance<
     Instance,
-    Schema extends OptionalInjectionTokenSchemaType,
+    Schema extends InjectionTokenSchemaType | undefined,
   >(
-    token: InjectionToken<Instance, Schema>,
-    args?: z.input<Schema>,
-  ): [undefined, z.output<Schema>] | [UnknownError]
-  private resolveTokenArgs<Instance, Schema extends InjectionTokenSchemaType>(
-    token: BoundInjectionToken<Instance, Schema>,
-  ): [undefined, z.output<Schema>] | [UnknownError]
-  private resolveTokenArgs<Instance, Schema extends InjectionTokenSchemaType>(
-    token: FactoryInjectionToken<Instance, Schema>,
-  ): [undefined, z.output<Schema>] | [FactoryTokenNotResolved | UnknownError]
-  private resolveTokenArgs(
-    token:
-      | InjectionToken<any, any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
+    token: AnyInjectableType,
+    args: Schema extends ZodObject
+      ? z.input<Schema>
+      : Schema extends ZodOptional<ZodObject>
+        ? z.input<Schema> | undefined
+        : undefined,
+  ): Instance | null {
+    const [err, { actualToken, validatedArgs }] =
+      this.validateAndResolveTokenArgs(token, args)
+    if (err) {
+      return null
+    }
+    const instanceName = this.generateInstanceName(actualToken, validatedArgs)
+    if (this.currentRequestContext) {
+      const requestHolder = this.currentRequestContext.getHolder(instanceName)
+      if (requestHolder) {
+        return requestHolder.instance as Instance
+      }
+    }
+    const [error, holder] = this.manager.get(instanceName)
+    if (error) {
+      return null
+    }
+    return holder.instance as Instance
+  }
+
+  invalidate(service: string, round = 1): Promise<any> {
+    this.logger?.log(
+      `[ServiceLocator]#invalidate(): Starting Invalidating process of ${service}`,
+    )
+    const toInvalidate = this.manager.filter(
+      (holder) => holder.name === service || holder.deps.has(service),
+    )
+    const promises = []
+    for (const [key, holder] of toInvalidate.entries()) {
+      if (holder.status === ServiceLocatorInstanceHolderStatus.Destroying) {
+        this.logger?.trace(
+          `[ServiceLocator]#invalidate(): ${key} is already being destroyed`,
+        )
+        promises.push(holder.destroyPromise)
+        continue
+      }
+      if (holder.status === ServiceLocatorInstanceHolderStatus.Creating) {
+        this.logger?.trace(
+          `[ServiceLocator]#invalidate(): ${key} is being created, waiting for creation to finish`,
+        )
+        promises.push(
+          holder.creationPromise?.then(() => {
+            if (round > 3) {
+              this.logger?.error(
+                `[ServiceLocator]#invalidate(): ${key} creation is triggering a new invalidation round, but it is still not created`,
+              )
+              return
+            }
+            return this.invalidate(key, round + 1)
+          }),
+        )
+        continue
+      }
+      // @ts-expect-error TS2322 we are changing the status
+      holder.status = ServiceLocatorInstanceHolderStatus.Destroying
+      this.logger?.log(
+        `[ServiceLocator]#invalidate(): Invalidating ${key} and notifying listeners`,
+      )
+      // @ts-expect-error TS2322 we are changing the status
+      holder.destroyPromise = Promise.all(
+        holder.destroyListeners.map((listener) => listener()),
+      ).then(async () => {
+        this.manager.delete(key)
+        await this.emitInstanceEvent(key, 'destroy')
+      })
+      promises.push(holder.destroyPromise)
+    }
+    return Promise.all(promises)
+  }
+
+  async ready() {
+    return Promise.all(
+      Array.from(this.manager.filter(() => true)).map(([, holder]) => {
+        if (holder.status === ServiceLocatorInstanceHolderStatus.Creating) {
+          return holder.creationPromise?.then(() => null)
+        }
+        if (holder.status === ServiceLocatorInstanceHolderStatus.Destroying) {
+          return holder.destroyPromise.then(() => null)
+        }
+        return Promise.resolve(null)
+      }),
+    ).then(() => null)
+  }
+
+  // ============================================================================
+  // REQUEST CONTEXT MANAGEMENT
+  // ============================================================================
+
+  /**
+   * Begins a new request context with the given parameters.
+   * @param requestId Unique identifier for this request
+   * @param metadata Optional metadata for the request
+   * @param priority Priority for resolution (higher = more priority)
+   * @returns The created request context holder
+   */
+  beginRequest(
+    requestId: string,
+    metadata?: Record<string, any>,
+    priority: number = 100,
+  ): RequestContextHolder {
+    if (this.requestContexts.has(requestId)) {
+      throw new Error(
+        `[ServiceLocator] Request context ${requestId} already exists`,
+      )
+    }
+
+    const contextHolder = new DefaultRequestContextHolder(
+      requestId,
+      priority,
+      metadata,
+    )
+    this.requestContexts.set(requestId, contextHolder)
+    this.currentRequestContext = contextHolder
+
+    this.logger?.log(`[ServiceLocator] Started request context: ${requestId}`)
+    return contextHolder
+  }
+
+  /**
+   * Ends a request context and cleans up all associated instances.
+   * @param requestId The request ID to end
+   */
+  async endRequest(requestId: string): Promise<void> {
+    const contextHolder = this.requestContexts.get(requestId)
+    if (!contextHolder) {
+      this.logger?.warn(
+        `[ServiceLocator] Request context ${requestId} not found`,
+      )
+      return
+    }
+
+    this.logger?.log(`[ServiceLocator] Ending request context: ${requestId}`)
+
+    // Clean up all request-scoped instances
+    const cleanupPromises: Promise<any>[] = []
+    for (const [, holder] of contextHolder.holders) {
+      if (holder.destroyListeners.length > 0) {
+        cleanupPromises.push(
+          Promise.all(holder.destroyListeners.map((listener) => listener())),
+        )
+      }
+    }
+
+    await Promise.all(cleanupPromises)
+
+    // Clear the context
+    contextHolder.clear()
+    this.requestContexts.delete(requestId)
+
+    // Reset current context if it was the one being ended
+    if (this.currentRequestContext === contextHolder) {
+      this.currentRequestContext =
+        Array.from(this.requestContexts.values()).at(-1) ?? null
+    }
+
+    this.logger?.log(`[ServiceLocator] Request context ${requestId} ended`)
+  }
+
+  /**
+   * Gets the current request context.
+   * @returns The current request context holder or null
+   */
+  getCurrentRequestContext(): RequestContextHolder | null {
+    return this.currentRequestContext
+  }
+
+  /**
+   * Sets the current request context.
+   * @param requestId The request ID to set as current
+   */
+  setCurrentRequestContext(requestId: string): void {
+    const contextHolder = this.requestContexts.get(requestId)
+    if (!contextHolder) {
+      throw new Error(`[ServiceLocator] Request context ${requestId} not found`)
+    }
+    this.currentRequestContext = contextHolder
+  }
+
+  // ============================================================================
+  // PRIVATE METHODS
+  // ============================================================================
+
+  /**
+   * Validates and resolves token arguments, handling factory token resolution and validation.
+   */
+  private validateAndResolveTokenArgs(
+    token: AnyInjectableType,
     args?: any,
-  ) {
+  ): [
+    FactoryTokenNotResolved | UnknownError | undefined,
+    { actualToken: InjectionTokenType; validatedArgs?: any },
+  ] {
+    let actualToken = token as InjectionToken<any, any>
+    if (typeof token === 'function') {
+      actualToken = getInjectableToken(token)
+    }
     let realArgs = args
-    if (token instanceof BoundInjectionToken) {
-      realArgs = token.value
-    } else if (token instanceof FactoryInjectionToken) {
-      if (token.resolved) {
-        realArgs = token.value
+    if (actualToken instanceof BoundInjectionToken) {
+      realArgs = actualToken.value
+    } else if (actualToken instanceof FactoryInjectionToken) {
+      if (actualToken.resolved) {
+        realArgs = actualToken.value
       } else {
-        return [new FactoryTokenNotResolved(token.name)]
+        return [new FactoryTokenNotResolved(token.name), { actualToken }]
       }
     }
-    if (!token.schema) {
-      return [undefined, realArgs]
+    if (!actualToken.schema) {
+      return [undefined, { actualToken, validatedArgs: realArgs }]
     }
-    const validatedArgs = token.schema?.safeParse(realArgs)
+    const validatedArgs = actualToken.schema?.safeParse(realArgs)
     if (validatedArgs && !validatedArgs.success) {
       this.logger?.error(
-        `[ServiceLocator]#resolveTokenArgs(): Error validating args for ${token.name.toString()}`,
+        `[ServiceLocator]#validateAndResolveTokenArgs(): Error validating args for ${actualToken.name.toString()}`,
         validatedArgs.error,
       )
-      return [new UnknownError(validatedArgs.error)]
+      return [new UnknownError(validatedArgs.error), { actualToken }]
     }
-    return [undefined, validatedArgs?.data]
+    return [undefined, { actualToken, validatedArgs: validatedArgs?.data }]
   }
 
-  public getInstanceIdentifier<
-    Instance,
-    Schema extends BaseInjectionTokenSchemaType,
-  >(token: InjectionToken<Instance, Schema>, args: z.input<Schema>): string
-  public getInstanceIdentifier<
-    Instance,
-    Schema extends OptionalInjectionTokenSchemaType,
-  >(token: InjectionToken<Instance, Schema>, args?: z.input<Schema>): string
-  public getInstanceIdentifier<Instance>(
-    token: InjectionToken<Instance, undefined>,
-  ): string
-  public getInstanceIdentifier<Instance>(
-    token: BoundInjectionToken<Instance, any>,
-  ): string
-  public getInstanceIdentifier<Instance>(
-    token: FactoryInjectionToken<Instance, any>,
-  ): string
-  public getInstanceIdentifier(
-    token:
-      | InjectionToken<any, any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
-    args?: any,
-  ): string {
-    const [err, realArgs] = this.resolveTokenArgs(
-      token as InjectionToken<any>,
-      args,
-    )
-    if (err) {
-      throw err
-    }
-    return this.makeInstanceName(token as InjectionToken<any>, realArgs)
-  }
-
-  public getInstance<Instance, Schema extends BaseInjectionTokenSchemaType>(
-    token: InjectionToken<Instance, Schema>,
-    args: z.input<Schema>,
-  ): Promise<[undefined, Instance] | [UnknownError | FactoryNotFound]>
-  public getInstance<Instance, Schema extends OptionalInjectionTokenSchemaType>(
-    token: InjectionToken<Instance, Schema>,
-    args?: z.input<Schema>,
-  ): Promise<[undefined, Instance] | [UnknownError | FactoryNotFound]>
-  public getInstance<Instance>(
-    token: InjectionToken<Instance, undefined>,
-  ): Promise<[undefined, Instance] | [UnknownError | FactoryNotFound]>
-  public getInstance<Instance>(
-    token: BoundInjectionToken<Instance, any>,
-  ): Promise<[undefined, Instance] | [UnknownError | FactoryNotFound]>
-  public getInstance<Instance>(
-    token: FactoryInjectionToken<Instance, any>,
-  ): Promise<[undefined, Instance] | [UnknownError | FactoryNotFound]>
-
-  public async getInstance(
-    token:
-      | InjectionToken<any, any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
+  /**
+   * Internal method to resolve token args and create instance name.
+   * Handles factory token resolution and validation.
+   */
+  private async resolveTokenAndPrepareInstanceName(
+    token: AnyInjectableType,
     args?: any,
-  ) {
-    const [err, realArgs] = this.resolveTokenArgs(token as any, args)
+  ): Promise<
+    | [
+        undefined,
+        {
+          instanceName: string
+          validatedArgs: any
+          actualToken: InjectionTokenType
+          realToken: InjectionToken<any, any>
+        },
+      ]
+    | [UnknownError | FactoryTokenNotResolved]
+  > {
+    const [err, { actualToken, validatedArgs }] =
+      this.validateAndResolveTokenArgs(token, args)
     if (err instanceof UnknownError) {
       return [err]
     } else if (
       (err as any) instanceof FactoryTokenNotResolved &&
-      token instanceof FactoryInjectionToken
+      actualToken instanceof FactoryInjectionToken
     ) {
       this.logger?.log(
-        `[ServiceLocator]#getInstance() Factory token not resolved, resolving it`,
+        `[ServiceLocator]#resolveTokenAndPrepareInstanceName() Factory token not resolved, resolving it`,
       )
-      await token.resolve()
-      return this.getInstance(token)
+      await actualToken.resolve(this.createFactoryContext())
+      return this.resolveTokenAndPrepareInstanceName(token)
+    }
+    const instanceName = this.generateInstanceName(actualToken, validatedArgs)
+    // Determine the real token (the actual InjectionToken that will be used for resolution)
+    const realToken =
+      actualToken instanceof BoundInjectionToken ||
+      actualToken instanceof FactoryInjectionToken
+        ? actualToken.token
+        : actualToken
+    return [undefined, { instanceName, validatedArgs, actualToken, realToken }]
+  }
+
+  /**
+   * Gets an instance by its instance name, handling all the logic after instance name creation.
+   */
+  private async retrieveOrCreateInstanceByInstanceName(
+    instanceName: string,
+    realToken: InjectionToken<any, any>,
+    realArgs: any,
+  ): Promise<
+    | [undefined, ServiceLocatorInstanceHolder<any>]
+    | [UnknownError | FactoryNotFound]
+  > {
+    // Check if this is a request-scoped service and we have a current request context
+    if (this.registry.has(realToken)) {
+      const record = this.registry.get(realToken)
+      if (record.scope === InjectableScope.Request) {
+        if (!this.currentRequestContext) {
+          this.logger?.log(
+            `[ServiceLocator]#retrieveOrCreateInstanceByInstanceName() No current request context available for request-scoped service ${instanceName}`,
+          )
+          return [new UnknownError(ErrorsEnum.InstanceNotFound)]
+        }
+        const requestHolder = this.currentRequestContext.getHolder(instanceName)
+        if (requestHolder) {
+          if (
+            requestHolder.status === ServiceLocatorInstanceHolderStatus.Creating
+          ) {
+            await requestHolder.creationPromise
+            return this.retrieveOrCreateInstanceByInstanceName(
+              instanceName,
+              realToken,
+              realArgs,
+            )
+          } else if (
+            requestHolder.status ===
+            ServiceLocatorInstanceHolderStatus.Destroying
+          ) {
+            return [new UnknownError(ErrorsEnum.InstanceDestroying)]
+          }
+          return [undefined, requestHolder]
+        }
+      }
     }
-    const instanceName = this.makeInstanceName(token, realArgs)
+
     const [error, holder] = this.manager.get(instanceName)
     if (!error) {
       if (holder.status === ServiceLocatorInstanceHolderStatus.Creating) {
-        return holder.creationPromise
+        await holder.creationPromise
+        return this.retrieveOrCreateInstanceByInstanceName(
+          instanceName,
+          realToken,
+          realArgs,
+        )
       } else if (
         holder.status === ServiceLocatorInstanceHolderStatus.Destroying
       ) {
         // Should never happen
         return [new UnknownError(ErrorsEnum.InstanceDestroying)]
       }
-      return [undefined, holder.instance]
+      return [undefined, holder]
     }
     switch (error.code) {
       case ErrorsEnum.InstanceDestroying:
         this.logger?.log(
-          `[ServiceLocator]#getInstance() TTL expired for ${holder?.name}`,
+          `[ServiceLocator]#retrieveOrCreateInstanceByInstanceName() TTL expired for ${holder?.name}`,
         )
         await holder?.destroyPromise
         //Maybe we already have a new instance
-        // @ts-expect-error We should redefine the instance name type
-        return this.getInstance(token, args)
+        return this.retrieveOrCreateInstanceByInstanceName(
+          instanceName,
+          realToken,
+          realArgs,
+        )
 
       case ErrorsEnum.InstanceExpired:
         this.logger?.log(
-          `[ServiceLocator]#getInstance() TTL expired for ${holder?.name}`,
+          `[ServiceLocator]#retrieveOrCreateInstanceByInstanceName() TTL expired for ${holder?.name}`,
         )
         await this.invalidate(instanceName)
         //Maybe we already have a new instance
-        // @ts-expect-error We should redefine the instance name type
-        return this.getInstance(token, args)
+        return this.retrieveOrCreateInstanceByInstanceName(
+          instanceName,
+          realToken,
+          realArgs,
+        )
       case ErrorsEnum.InstanceNotFound:
         break
       default:
         return [error]
     }
-    // @ts-expect-error TS2322 It's validated
-    return this.createInstance(instanceName, token, realArgs)
-  }
-
-  public async getOrThrowInstance<
-    Instance,
-    Schema extends InjectionTokenSchemaType | undefined,
-  >(
-    token: InjectionToken<Instance, Schema>,
-    args: Schema extends ZodObject<any>
-      ? z.input<Schema>
-      : Schema extends ZodOptional<ZodObject<any>>
-        ? z.input<Schema> | undefined
-        : undefined,
-  ): Promise<Instance> {
-    const [error, instance] = await this.getInstance(token, args)
-    if (error) {
-      throw error
+    const result = await this.createNewInstance(
+      instanceName,
+      realToken,
+      realArgs,
+    )
+    if (result[0]) {
+      return [result[0]]
     }
-    return instance
+    if (result[1].status === ServiceLocatorInstanceHolderStatus.Creating) {
+      await result[1].creationPromise
+    }
+    if (result[1].status === ServiceLocatorInstanceHolderStatus.Error) {
+      return [result[1].instance] as [UnknownError | FactoryNotFound]
+    }
+    return [undefined, result[1]]
   }
 
-  private notifyListeners(
+  /**
+   * Emits events to listeners for instance lifecycle events.
+   */
+  private emitInstanceEvent(
     name: string,
     event: 'create' | 'destroy' = 'create',
   ) {
     this.logger?.log(
-      `[ServiceLocator]#notifyListeners() Notifying listeners for ${name} with event ${event}`,
+      `[ServiceLocator]#emitInstanceEvent() Notifying listeners for ${name} with event ${event}`,
     )
     return this.eventBus.emit(name, event)
   }
 
-  private async createInstance<
+  /**
+   * Creates a new instance for the given token and arguments.
+   */
+  private async createNewInstance<
     Instance,
     Schema extends InjectionTokenSchemaType | undefined,
   >(
     instanceName: string,
-    token: InjectionToken<Instance, Schema>,
-    args: Schema extends ZodObject<any>
-      ? z.input<Schema>
-      : Schema extends ZodOptional<ZodObject<any>>
-        ? z.input<Schema> | undefined
+    realToken: InjectionToken<Instance, Schema>,
+    args: Schema extends ZodObject
+      ? z.output<Schema>
+      : Schema extends ZodOptional<ZodObject>
+        ? z.output<Schema> | undefined
         : undefined,
-  ): Promise<[undefined, Instance] | [FactoryNotFound | UnknownError]> {
+  ): Promise<
+    | [undefined, ServiceLocatorInstanceHolder<Instance>]
+    | [FactoryNotFound | UnknownError]
+  > {
     this.logger?.log(
-      `[ServiceLocator]#createInstance() Creating instance for ${instanceName}`,
+      `[ServiceLocator]#createNewInstance() Creating instance for ${instanceName}`,
     )
-    let realToken =
-      token instanceof BoundInjectionToken ||
-      token instanceof FactoryInjectionToken
-        ? token.token
-        : token
     if (this.registry.has(realToken)) {
-      return this.resolveInstance(instanceName, realToken, args)
+      return this.instantiateServiceFromRegistry<Instance, Schema, any>(
+        instanceName,
+        realToken,
+        args,
+      )
     } else {
       return [new FactoryNotFound(realToken.name.toString())]
     }
   }
 
-  private resolveInstance<
+  /**
+   * Instantiates a service from the registry using the service instantiator.
+   */
+  private instantiateServiceFromRegistry<
     Instance,
     Schema extends InjectionTokenSchemaType | undefined,
     Args extends Schema extends BaseInjectionTokenSchemaType
-      ? z.input<Schema>
+      ? z.output<Schema>
       : Schema extends OptionalInjectionTokenSchemaType
-        ? z.input<Schema> | undefined
+        ? z.output<Schema> | undefined
         : undefined,
   >(
     instanceName: string,
     token: InjectionToken<Instance, Schema>,
     args: Args,
-  ): Promise<[undefined, Instance] | [FactoryNotFound]> {
+  ): Promise<[undefined, ServiceLocatorInstanceHolder<Instance>]> {
     this.logger?.log(
-      `[ServiceLocator]#resolveInstance(): Creating instance for ${instanceName} from abstract factory`,
+      `[ServiceLocator]#instantiateServiceFromRegistry(): Creating instance for ${instanceName} from abstract factory`,
+    )
+    const ctx = this.createFactoryContext(
+      this.currentRequestContext || undefined,
     )
-    const ctx = this.createFactoryContext(instanceName)
-    let { factory, scope } = this.registry.get<Instance, Schema>(token)
-    const holder: ServiceLocatorInstanceHolder<Instance> = {
-      name: instanceName,
-      instance: null,
-      status: ServiceLocatorInstanceHolderStatus.Creating,
-      kind: ServiceLocatorInstanceHolderKind.AbstractFactory,
-      // @ts-expect-error TS2322 This is correct type
-      creationPromise: factory(ctx, args)
-        .then(async (instance: Instance) => {
+    let record = this.registry.get<Instance, Schema>(token)
+    let { scope, type } = record
+
+    // Use createCreatingHolder from manager
+    const [deferred, holder] = this.manager.createCreatingHolder<Instance>(
+      instanceName,
+      type,
+      scope,
+      ctx.deps,
+      Infinity,
+    )
+
+    // Start the instantiation process
+    this.serviceInstantiator
+      .instantiateService(ctx, record, args)
+      .then(async ([error, instance]) => {
+        holder.destroyListeners = ctx.getDestroyListeners()
+        holder.creationPromise = null
+        if (error) {
+          this.logger?.error(
+            `[ServiceLocator]#instantiateServiceFromRegistry(): Error creating instance for ${instanceName}`,
+            error,
+          )
+          holder.status = ServiceLocatorInstanceHolderStatus.Error
+          holder.instance = error
+          if (scope === InjectableScope.Singleton) {
+            setTimeout(() => this.invalidate(instanceName), 10)
+          }
+          deferred.reject(error)
+        } else {
           holder.instance = instance
           holder.status = ServiceLocatorInstanceHolderStatus.Created
-          holder.deps = ctx.getDependencies()
-          holder.destroyListeners = ctx.getDestroyListeners()
-          holder.ttl = ctx.getTtl()
-          if (holder.deps.length > 0) {
-            this.logger?.log(
-              `[ServiceLocator]#createInstanceFromAbstractFactory(): Adding subscriptions for ${instanceName} dependencies for their invalidations: ${holder.deps.join(
-                ', ',
-              )}`,
-            )
-            holder.deps.forEach((dependency) => {
+          if (ctx.deps.size > 0) {
+            ctx.deps.forEach((dependency) => {
               holder.destroyListeners.push(
                 this.eventBus.on(dependency, 'destroy', () =>
                   this.invalidate(instanceName),
@@ -387,189 +603,128 @@ export class ServiceLocator {
               )
             })
           }
-          if (holder.ttl === 0 || scope === InjectableScope.Instance) {
-            // One time instance
-            await this.invalidate(instanceName)
-          }
-          await this.notifyListeners(instanceName)
-          return [undefined, instance as Instance]
-        })
-        .catch((error) => {
-          this.logger?.error(
-            `[ServiceLocator]#createInstanceFromAbstractFactory(): Error creating instance for ${instanceName}`,
-            error,
-          )
-          return [new UnknownError(error)]
-        }),
-      effects: [],
-      deps: [],
-      destroyListeners: [],
-      createdAt: Date.now(),
-      ttl: Infinity,
-    }
+          await this.emitInstanceEvent(instanceName)
+          deferred.resolve([undefined, instance])
+        }
+      })
+      .catch((error) => {
+        this.logger?.error(
+          `[ServiceLocator]#instantiateServiceFromRegistry(): Unexpected error creating instance for ${instanceName}`,
+          error,
+        )
+        holder.status = ServiceLocatorInstanceHolderStatus.Error
+        holder.instance = error
+        holder.creationPromise = null
+        if (scope === InjectableScope.Singleton) {
+          setTimeout(() => this.invalidate(instanceName), 10)
+        }
+        deferred.reject(error)
+      })
 
     if (scope === InjectableScope.Singleton) {
       this.logger?.debug(
-        `[ServiceLocator]#resolveInstance(): Setting instance for ${instanceName}`,
+        `[ServiceLocator]#instantiateServiceFromRegistry(): Setting instance for ${instanceName}`,
       )
       this.manager.set(instanceName, holder)
+    } else if (
+      scope === InjectableScope.Request &&
+      this.currentRequestContext
+    ) {
+      this.logger?.debug(
+        `[ServiceLocator]#instantiateServiceFromRegistry(): Setting request-scoped instance for ${instanceName}`,
+      )
+      // For request-scoped services, we don't store them in the global manager
+      // They will be managed by the request context holder
+      this.currentRequestContext.addInstance(
+        instanceName,
+        holder.instance,
+        holder,
+      )
     }
     // @ts-expect-error TS2322 This is correct type
-    return holder.creationPromise
+    return [undefined, holder]
   }
 
-  private createFactoryContext(instanceName: string): FactoryContext {
-    const dependencies = new Set<string>()
+  /**
+   * Creates a factory context for dependency injection during service instantiation.
+   * @param contextHolder Optional request context holder for priority-based resolution
+   */
+  private createFactoryContext(
+    contextHolder?: RequestContextHolder,
+  ): FactoryContext & {
+    getDestroyListeners: () => (() => void)[]
+    deps: Set<string>
+  } {
     const destroyListeners = new Set<() => void>()
+    const deps = new Set<string>()
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const self = this
 
-    function invalidate(name = instanceName) {
-      return self.invalidate(name)
-    }
-    function addEffect(listener: () => void) {
+    function addDestroyListener(listener: () => void) {
       destroyListeners.add(listener)
     }
-    let ttl = Infinity
-    function setTtl(value: number) {
-      ttl = value
-    }
-    function getTtl() {
-      return ttl
-    }
 
-    function on(key: string, event: string, listener: (event: string) => void) {
-      destroyListeners.add(self.eventBus.on(key, event, listener))
+    function getDestroyListeners() {
+      return Array.from(destroyListeners)
     }
 
     return {
       // @ts-expect-error This is correct type
       async inject(token, args) {
-        let injectionToken = token
-        if (typeof token === 'function') {
-          injectionToken = getInjectableToken(token)
+        // 1. Check RequestContextHolder first (if provided and has higher priority)
+        if (contextHolder && contextHolder.priority > 0) {
+          const instanceName = self.generateInstanceName(token, args)
+          const prePreparedInstance = contextHolder.getInstance(instanceName)
+          if (prePreparedInstance !== undefined) {
+            self.logger?.debug(
+              `[ServiceLocator] Using pre-prepared instance ${instanceName} from request context ${contextHolder.requestId}`,
+            )
+            deps.add(instanceName)
+            return prePreparedInstance
+          }
         }
-        if (injectionToken) {
-          const [err, validatedArgs] = self.resolveTokenArgs(
-            injectionToken,
-            args,
-          )
-          if (err) {
-            throw err
+
+        // 2. Check current request context (if different from provided contextHolder)
+        if (
+          self.currentRequestContext &&
+          self.currentRequestContext !== contextHolder
+        ) {
+          const instanceName = self.generateInstanceName(token, args)
+          const prePreparedInstance =
+            self.currentRequestContext.getInstance(instanceName)
+          if (prePreparedInstance !== undefined) {
+            self.logger?.debug(
+              `[ServiceLocator] Using pre-prepared instance ${instanceName} from current request context ${self.currentRequestContext.requestId}`,
+            )
+            deps.add(instanceName)
+            return prePreparedInstance
           }
-          const instanceName = self.makeInstanceName(token, validatedArgs)
-          dependencies.add(instanceName)
-          return self.getOrThrowInstance(injectionToken, args as any)
         }
-        throw new Error(
-          `[ServiceLocator]#inject(): Invalid token type: ${typeof token}. Expected a class or an InjectionToken.`,
+
+        // 3. Fall back to normal resolution
+        const [error, instance] = await self.getInstance(
+          token,
+          args,
+          ({ instanceName }) => {
+            deps.add(instanceName)
+          },
         )
+        if (error) {
+          throw error
+        }
+        return instance
       },
-      invalidate,
-      on: on as ServiceLocatorEventBus['on'],
-      getDependencies: () => Array.from(dependencies),
-      addEffect,
-      getDestroyListeners: () => Array.from(destroyListeners),
-      setTtl,
-      getTtl,
+      addDestroyListener,
+      getDestroyListeners,
       locator: self,
+      deps,
     }
   }
 
-  public getSyncInstance<
-    Instance,
-    Schema extends InjectionTokenSchemaType | undefined,
-  >(
-    token: InjectionToken<Instance, Schema>,
-    args: Schema extends ZodObject<any>
-      ? z.input<Schema>
-      : Schema extends ZodOptional<ZodObject<any>>
-        ? z.input<Schema> | undefined
-        : undefined,
-  ): Instance | null {
-    const [err, realArgs] = this.resolveTokenArgs(token, args)
-    if (err) {
-      return null
-    }
-    const instanceName = this.makeInstanceName(token, realArgs)
-    const [error, holder] = this.manager.get(instanceName)
-    if (error) {
-      return null
-    }
-    return holder.instance as Instance
-  }
-
-  invalidate(service: string, round = 1): Promise<any> {
-    this.logger?.log(
-      `[ServiceLocator]#invalidate(): Starting Invalidating process of ${service}`,
-    )
-    const toInvalidate = this.manager.filter(
-      (holder) => holder.name === service || holder.deps.includes(service),
-    )
-    const promises = []
-    for (const [key, holder] of toInvalidate.entries()) {
-      if (holder.status === ServiceLocatorInstanceHolderStatus.Destroying) {
-        this.logger?.trace(
-          `[ServiceLocator]#invalidate(): ${key} is already being destroyed`,
-        )
-        promises.push(holder.destroyPromise)
-        continue
-      }
-      if (holder.status === ServiceLocatorInstanceHolderStatus.Creating) {
-        this.logger?.trace(
-          `[ServiceLocator]#invalidate(): ${key} is being created, waiting for creation to finish`,
-        )
-        promises.push(
-          holder.creationPromise?.then(() => {
-            if (round > 3) {
-              this.logger?.error(
-                `[ServiceLocator]#invalidate(): ${key} creation is triggering a new invalidation round, but it is still not created`,
-              )
-              return
-            }
-            return this.invalidate(key, round + 1)
-          }),
-        )
-        continue
-      }
-      // @ts-expect-error TS2322 we are changing the status
-      holder.status = ServiceLocatorInstanceHolderStatus.Destroying
-      this.logger?.log(
-        `[ServiceLocator]#invalidate(): Invalidating ${key} and notifying listeners`,
-      )
-      // @ts-expect-error TS2322 we are changing the status
-      holder.destroyPromise = Promise.all(
-        holder.destroyListeners.map((listener) => listener()),
-      ).then(async () => {
-        this.manager.delete(key)
-        await this.notifyListeners(key, 'destroy')
-      })
-      promises.push(holder.destroyPromise)
-    }
-    return Promise.all(promises)
-  }
-
-  async ready() {
-    return Promise.all(
-      Array.from(this.manager.filter(() => true)).map(([, holder]) => {
-        if (holder.status === ServiceLocatorInstanceHolderStatus.Creating) {
-          return holder.creationPromise?.then(() => null)
-        }
-        if (holder.status === ServiceLocatorInstanceHolderStatus.Destroying) {
-          return holder.destroyPromise.then(() => null)
-        }
-        return Promise.resolve(null)
-      }),
-    ).then(() => null)
-  }
-
-  makeInstanceName(
-    token:
-      | InjectionToken<any, any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
-    args: any,
-  ) {
+  /**
+   * Generates a unique instance name based on token and arguments.
+   */
+  private generateInstanceName(token: InjectionTokenType, args: any) {
     const formattedArgs = args
       ? ':' +
         Object.entries(args ?? {})