@navios/di 0.4.1 → 0.5.0

package/lib/_tsup-dts-rollup.d.ts

@@ -68,11 +68,10 @@ declare abstract class BaseInstanceHolderManager {
      * @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>, ttl?: number): [
-    ReturnType<typeof createDeferred<[undefined, Instance]>>,
+    createCreatingHolder<Instance>(name: string, type: InjectableType, scope: InjectableScope, deps?: Set<string>): [
+    ReturnType<typeof Promise.withResolvers<[undefined, Instance]>>,
     ServiceLocatorInstanceHolder<Instance>
     ];
     /**
@@ -83,10 +82,9 @@ declare abstract class BaseInstanceHolderManager {
      * @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>, ttl?: number): ServiceLocatorInstanceHolder<Instance>;
+    protected createCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>): ServiceLocatorInstanceHolder<Instance>;
     /**
      * Gets all holder names currently managed.
      */
@@ -145,11 +143,27 @@ declare type ClassTypeWithOptionalArgument<Arg> = new (arg?: Arg) => any;
 export { ClassTypeWithOptionalArgument }
 export { ClassTypeWithOptionalArgument as ClassTypeWithOptionalArgument_alias_1 }
 
+declare type ClassTypeWithoutArguments = new () => any;
+export { ClassTypeWithoutArguments }
+export { ClassTypeWithoutArguments as ClassTypeWithoutArguments_alias_1 }
+
+export declare interface ClearAllOptions {
+    /** Whether to also clear request contexts (default: true) */
+    clearRequestContexts?: boolean;
+    /** Maximum number of invalidation rounds to prevent infinite loops (default: 10) */
+    maxRounds?: number;
+    /** Whether to wait for all services to settle before starting (default: true) */
+    waitForSettlement?: boolean;
+}
+
 /**
  * Container class that provides a simplified public API for dependency injection.
  * It wraps a ServiceLocator instance and provides convenient methods for getting instances.
  */
 declare class Container {
+    protected readonly registry: Registry;
+    protected readonly logger: Console | null;
+    protected readonly injectors: Injectors;
     private readonly serviceLocator;
     constructor(registry?: Registry, logger?: Console | null, injectors?: Injectors);
     private registerSelf;
@@ -171,6 +185,19 @@ declare class Container {
      * Invalidates a service and its dependencies
      */
     invalidate(service: unknown): Promise<void>;
+    /**
+     * Gets a service holder by instance (reverse lookup)
+     */
+    private getHolderByInstance;
+    private getRequestHolderByInstance;
+    /**
+     * Checks if a service is registered in the container
+     */
+    isRegistered(token: any): boolean;
+    /**
+     * Disposes the container and cleans up all resources
+     */
+    dispose(): Promise<void>;
     /**
      * Waits for all pending operations to complete
      */
@@ -198,19 +225,15 @@ declare class Container {
      * @param requestId The request ID to set as current
      */
     setCurrentRequestContext(requestId: string): void;
+    /**
+     * Clears all instances and bindings from the container.
+     * This is useful for testing or resetting the container state.
+     */
+    clear(): Promise<void>;
 }
 export { Container }
 export { Container as Container_alias_1 }
 
-/**
- * Creates a new deferred promise.
- * @returns A new Deferred instance
- */
-declare function createDeferred<T>(): Deferred<T>;
-export { createDeferred }
-export { createDeferred as createDeferred_alias_1 }
-export { createDeferred as createDeferred_alias_2 }
-
 /**
  * Creates a new request context holder with the given parameters.
  */
@@ -255,57 +278,42 @@ declare class DefaultRequestContextHolder extends BaseInstanceHolderManager impl
 export { DefaultRequestContextHolder }
 export { DefaultRequestContextHolder as DefaultRequestContextHolder_alias_1 }
 
-/**
- * Creates a deferred promise that can be resolved or rejected externally.
- * This is useful for creating stub holders that can be fulfilled later.
- */
-declare class Deferred<T> {
-    readonly promise: Promise<T>;
-    private _resolve;
-    private _reject;
-    private _isResolved;
-    private _isRejected;
-    constructor();
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Returns true if the promise has been resolved.
-     */
-    get isResolved(): boolean;
-    /**
-     * Returns true if the promise has been rejected.
-     */
-    get isRejected(): boolean;
-    /**
-     * Returns true if the promise has been settled (resolved or rejected).
-     */
-    get isSettled(): boolean;
+declare class DIError extends Error {
+    readonly code: DIErrorCode;
+    readonly context?: Record<string, unknown>;
+    constructor(code: DIErrorCode, message: string, context?: Record<string, unknown>);
+    static factoryNotFound(name: string): DIError;
+    static factoryTokenNotResolved(token: string | symbol | unknown): DIError;
+    static instanceNotFound(name: string): DIError;
+    static instanceDestroying(name: string): DIError;
+    static unknown(message: string | Error, context?: Record<string, unknown>): DIError;
 }
-export { Deferred }
-export { Deferred as Deferred_alias_1 }
-export { Deferred as Deferred_alias_2 }
-
-declare enum ErrorsEnum {
-    InstanceExpired = "InstanceExpired",
+export { DIError }
+export { DIError as DIError_alias_1 }
+export { DIError as DIError_alias_2 }
+export { DIError as FactoryNotFound }
+export { DIError as FactoryNotFound_alias_1 }
+export { DIError as FactoryTokenNotResolved }
+export { DIError as FactoryTokenNotResolved_alias_1 }
+export { DIError as InstanceDestroying }
+export { DIError as InstanceDestroying_alias_1 }
+export { DIError as InstanceNotFound }
+export { DIError as InstanceNotFound_alias_1 }
+export { DIError as UnknownError }
+export { DIError as UnknownError_alias_1 }
+
+declare enum DIErrorCode {
+    FactoryNotFound = "FactoryNotFound",
+    FactoryTokenNotResolved = "FactoryTokenNotResolved",
     InstanceNotFound = "InstanceNotFound",
     InstanceDestroying = "InstanceDestroying",
-    UnknownError = "UnknownError",
-    FactoryNotFound = "FactoryNotFound",
-    FactoryTokenNotResolved = "FactoryTokenNotResolved"
+    UnknownError = "UnknownError"
 }
-export { ErrorsEnum }
-export { ErrorsEnum as ErrorsEnum_alias_1 }
-export { ErrorsEnum as ErrorsEnum_alias_2 }
+export { DIErrorCode }
+export { DIErrorCode as DIErrorCode_alias_1 }
+export { DIErrorCode as DIErrorCode_alias_2 }
+export { DIErrorCode as ErrorsEnum }
+export { DIErrorCode as ErrorsEnum_alias_1 }
 
 declare class EventEmitter<Events extends EventsConfig = {}> implements EventEmitterInterface<Events> {
     private listeners;
@@ -391,15 +399,6 @@ declare class FactoryInjectionToken<T, S extends InjectionTokenSchemaType> {
 export { FactoryInjectionToken }
 export { FactoryInjectionToken as FactoryInjectionToken_alias_1 }
 
-declare class FactoryNotFound extends Error {
-    name: string;
-    code: ErrorsEnum;
-    constructor(name: string);
-}
-export { FactoryNotFound }
-export { FactoryNotFound as FactoryNotFound_alias_1 }
-export { FactoryNotFound as FactoryNotFound_alias_2 }
-
 declare interface FactoryOptions {
     scope?: InjectableScope;
     token?: InjectionToken<any, any>;
@@ -418,14 +417,6 @@ declare type FactoryRecord<Instance = any, Schema = any> = {
 export { FactoryRecord }
 export { FactoryRecord as FactoryRecord_alias_1 }
 
-declare class FactoryTokenNotResolved extends Error {
-    code: ErrorsEnum;
-    constructor(name: string | symbol | ClassType);
-}
-export { FactoryTokenNotResolved }
-export { FactoryTokenNotResolved as FactoryTokenNotResolved_alias_1 }
-export { FactoryTokenNotResolved as FactoryTokenNotResolved_alias_2 }
-
 declare function getInjectableToken<R>(target: ClassType): R extends {
     create(...args: any[]): infer V;
 } ? InjectionToken<V> : InjectionToken<R>;
@@ -446,16 +437,22 @@ declare const inject: Injectors['inject'];
 export { inject }
 export { inject as inject_alias_1 }
 
-declare function Injectable(): <T extends ClassType>(target: T, context?: ClassDecoratorContext) => T;
+declare function Injectable(): <T extends ClassTypeWithoutArguments>(target: T, context?: ClassDecoratorContext) => T;
 
 declare function Injectable(options: {
     scope?: InjectableScope;
     registry: Registry;
-}): <T extends ClassType>(target: T, context?: ClassDecoratorContext) => T;
+}): <T extends ClassTypeWithoutArguments>(target: T, context?: ClassDecoratorContext) => T;
 
 declare function Injectable(options: {
     scope: InjectableScope;
-}): <T extends ClassType>(target: T, context?: ClassDecoratorContext) => T;
+}): <T extends ClassTypeWithoutArguments>(target: T, context?: ClassDecoratorContext) => T;
+
+declare function Injectable<Schema extends InjectionTokenSchemaType>(options: {
+    scope?: InjectableScope;
+    schema: Schema;
+    registry?: Registry;
+}): <T extends ClassTypeWithArgument<z.output<Schema>>>(target: T, context?: ClassDecoratorContext) => T;
 
 declare function Injectable<Type, Schema>(options: {
     scope?: InjectableScope;
@@ -473,6 +470,7 @@ export { Injectable as Injectable_alias_2 }
 declare interface InjectableOptions {
     scope?: InjectableScope;
     token?: InjectionToken<any, any>;
+    schema?: InjectionTokenSchemaType;
     registry?: Registry;
 }
 export { InjectableOptions }
@@ -537,18 +535,46 @@ export { InjectionTokenType }
 export { InjectionTokenType as InjectionTokenType_alias_1 }
 
 declare interface Injectors {
-    asyncInject<T extends ClassType>(token: T): InstanceType<T> extends Factorable<infer R> ? Promise<R> : Promise<InstanceType<T>>;
+    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>;
     asyncInject<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): Promise<T>;
     asyncInject<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? Promise<T> : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
     asyncInject<T>(token: InjectionToken<T, undefined>): Promise<T>;
     asyncInject<T>(token: BoundInjectionToken<T, any>): Promise<T>;
     asyncInject<T>(token: FactoryInjectionToken<T, any>): Promise<T>;
-    inject<T extends ClassType>(token: T): InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>;
+    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>): T;
     inject<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? T : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
     inject<T>(token: InjectionToken<T, undefined>): T;
     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];
     provideFactoryContext(context: FactoryContext | null): FactoryContext | null;
 }
@@ -556,44 +582,100 @@ export { Injectors }
 export { Injectors as Injectors_alias_1 }
 export { Injectors as Injectors_alias_2 }
 
+declare type InjectRequest = {
+    token: InjectionToken<any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any> | ClassType;
+    promise: Promise<any>;
+    readonly result: any;
+    readonly error: Error | null;
+};
+export { InjectRequest }
+export { InjectRequest as InjectRequest_alias_1 }
+export { InjectRequest as InjectRequest_alias_2 }
+
 declare interface InjectState {
     currentIndex: number;
     isFrozen: boolean;
-    requests: {
-        token: InjectionToken<any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any> | ClassType;
-        promise: Promise<any>;
-    }[];
+    requests: InjectRequest[];
 }
 export { InjectState }
 export { InjectState as InjectState_alias_1 }
 export { InjectState as InjectState_alias_2 }
 
-declare class InstanceDestroying extends Error {
-    name: string;
-    code: ErrorsEnum;
-    constructor(name: string);
-}
-export { InstanceDestroying }
-export { InstanceDestroying as InstanceDestroying_alias_1 }
-export { InstanceDestroying as InstanceDestroying_alias_2 }
-
-declare class InstanceExpired extends Error {
-    name: string;
-    code: ErrorsEnum;
-    constructor(name: string);
-}
-export { InstanceExpired }
-export { InstanceExpired as InstanceExpired_alias_1 }
-export { InstanceExpired as InstanceExpired_alias_2 }
-
-declare class InstanceNotFound extends Error {
-    name: string;
-    code: ErrorsEnum;
-    constructor(name: string);
+/**
+ * InstanceResolver handles instance resolution, creation, and lifecycle management.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export declare class InstanceResolver {
+    private readonly registry;
+    private readonly manager;
+    private readonly serviceInstantiator;
+    private readonly tokenProcessor;
+    private readonly logger;
+    private readonly serviceLocator;
+    constructor(registry: Registry, manager: ServiceLocatorManager, serviceInstantiator: ServiceInstantiator, tokenProcessor: TokenProcessor, logger: (Console | null) | undefined, serviceLocator: ServiceLocator);
+    /**
+     * Resolves an instance for the given token and arguments.
+     */
+    resolveInstance(token: AnyInjectableType, args?: any, requestContext?: RequestContextHolder): Promise<[undefined, any] | [DIError]>;
+    /**
+     * Gets a synchronous instance (for sync operations).
+     */
+    getSyncInstance<Instance, Schema extends InjectionTokenSchemaType | undefined>(token: AnyInjectableType, args: Schema extends ZodObject ? z.input<Schema> : Schema extends ZodOptional<ZodObject> ? z.input<Schema> | undefined : undefined, currentRequestContext: RequestContextHolder | null): Instance | null;
+    /**
+     * Internal method to resolve token args and create instance name.
+     * Handles factory token resolution and validation.
+     */
+    private resolveTokenAndPrepareInstanceName;
+    /**
+     * Gets an instance by its instance name, handling all the logic after instance name creation.
+     */
+    private retrieveOrCreateInstanceByInstanceName;
+    /**
+     * Attempts to retrieve an existing instance, handling request-scoped and singleton instances.
+     * Returns null if no instance exists and a new one should be created.
+     */
+    private tryGetExistingInstance;
+    /**
+     * Attempts to get a request-scoped instance if applicable.
+     */
+    private tryGetRequestScopedInstance;
+    /**
+     * Attempts to get a singleton instance from the manager.
+     */
+    private tryGetSingletonInstance;
+    /**
+     * Waits for an instance holder to be ready and returns the appropriate result.
+     */
+    private waitForInstanceReady;
+    /**
+     * Creates a new instance for the given token and arguments.
+     */
+    private createNewInstance;
+    /**
+     * Instantiates a service from the registry using the service instantiator.
+     */
+    private instantiateServiceFromRegistry;
+    /**
+     * Handles the result of service instantiation.
+     */
+    private handleInstantiationResult;
+    /**
+     * Handles successful service instantiation.
+     */
+    private handleInstantiationSuccess;
+    /**
+     * Handles service instantiation errors.
+     */
+    private handleInstantiationError;
+    /**
+     * Stores an instance holder based on its scope.
+     */
+    private storeInstanceByScope;
+    /**
+     * Creates a factory context for dependency injection during service instantiation.
+     */
+    private createFactoryContext;
 }
-export { InstanceNotFound }
-export { InstanceNotFound as InstanceNotFound_alias_1 }
-export { InstanceNotFound as InstanceNotFound_alias_2 }
 
 declare type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
 export { IsUnion }
@@ -619,6 +701,10 @@ export { OnServiceInit }
 export { OnServiceInit as OnServiceInit_alias_1 }
 export { OnServiceInit as OnServiceInit_alias_2 }
 
+declare const optional: Injectors['optional'];
+export { optional }
+export { optional as optional_alias_1 }
+
 declare type OptionalInjectionTokenSchemaType = ZodOptional<ZodObject> | ZodOptional<ZodRecord>;
 export { OptionalInjectionTokenSchemaType }
 export { OptionalInjectionTokenSchemaType as OptionalInjectionTokenSchemaType_alias_1 }
@@ -718,6 +804,49 @@ declare interface RequestContextHolder {
 export { RequestContextHolder }
 export { RequestContextHolder as RequestContextHolder_alias_1 }
 
+/**
+ * RequestContextManager handles request context lifecycle management.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export declare class RequestContextManager {
+    private readonly logger;
+    private readonly requestContexts;
+    private currentRequestContext;
+    constructor(logger?: Console | null);
+    /**
+     * 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): RequestContextHolder;
+    /**
+     * Ends a request context and cleans up all associated instances.
+     * @param requestId The request ID to end
+     */
+    endRequest(requestId: string): Promise<void>;
+    /**
+     * Gets the current request context.
+     * @returns The current request context holder or null
+     */
+    getCurrentRequestContext(): RequestContextHolder | null;
+    /**
+     * Sets the current request context.
+     * @param requestId The request ID to set as current
+     */
+    setCurrentRequestContext(requestId: string): void;
+    /**
+     * Gets all request contexts.
+     * @returns Map of request contexts
+     */
+    getRequestContexts(): Map<string, RequestContextHolder>;
+    /**
+     * Clears all request contexts.
+     */
+    clearAllRequestContexts(): Promise<void>;
+}
+
 /**
  * ServiceInstantiator handles the instantiation of services based on registry records.
  * It replaces the hard-coded logic in Injectable and Factory decorators.
@@ -753,138 +882,155 @@ declare class ServiceInstantiator {
 export { ServiceInstantiator }
 export { ServiceInstantiator as ServiceInstantiator_alias_1 }
 
-declare class ServiceLocator {
-    private readonly registry;
-    private readonly logger;
-    private readonly injectors;
-    private readonly eventBus;
+/**
+ * ServiceInvalidator handles service invalidation, cleanup, and graceful clearing.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export declare class ServiceInvalidator {
     private readonly manager;
-    private readonly serviceInstantiator;
-    private readonly requestContexts;
-    private currentRequestContext;
-    constructor(registry?: Registry, logger?: Console | null, injectors?: Injectors);
-    getEventBus(): ServiceLocatorEventBus;
-    getManager(): ServiceLocatorManager;
-    getInstanceIdentifier(token: AnyInjectableType, args?: any): string;
-    getInstance(token: AnyInjectableType, args?: any, onPrepare?: (data: {
-        instanceName: string;
-        actualToken: InjectionTokenType;
-        validatedArgs?: any;
-    }) => void): Promise<any[]>;
-    getOrThrowInstance<Instance>(token: AnyInjectableType, args: any): Promise<Instance>;
-    getSyncInstance<Instance, Schema extends InjectionTokenSchemaType | undefined>(token: AnyInjectableType, args: Schema extends ZodObject ? z.input<Schema> : Schema extends ZodOptional<ZodObject> ? z.input<Schema> | undefined : undefined): Instance | null;
-    invalidate(service: string, round?: number): Promise<any>;
+    private readonly requestContextManager;
+    private readonly eventBus;
+    private readonly logger;
+    constructor(manager: ServiceLocatorManager, requestContextManager: RequestContextManager, eventBus: ServiceLocatorEventBus, logger?: Console | null);
     /**
-     * Invalidates a single holder based on its current status.
+     * Invalidates a service and all its dependencies.
      */
-    private invalidateHolder;
+    invalidate(service: string, round?: number): Promise<any>;
     /**
-     * Destroys a holder and cleans up its resources.
+     * Gracefully clears all services in the ServiceLocator using invalidation logic.
+     * This method respects service dependencies and ensures proper cleanup order.
+     * Services that depend on others will be invalidated first, then their dependencies.
      */
-    private destroyHolder;
-    ready(): Promise<void>;
+    clearAll(options?: ClearAllOptions): Promise<void>;
     /**
-     * Waits for a holder to settle (either created, destroyed, or error state).
+     * Waits for all services to settle (either created, destroyed, or error state).
      */
-    private waitForHolderToSettle;
+    ready(): Promise<void>;
     /**
-     * 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
+     * Invalidates a single holder based on its current status.
      */
-    beginRequest(requestId: string, metadata?: Record<string, any>, priority?: number): RequestContextHolder;
+    private invalidateHolder;
     /**
-     * Ends a request context and cleans up all associated instances.
-     * @param requestId The request ID to end
+     * Invalidates a request-scoped holder based on its current status.
      */
-    endRequest(requestId: string): Promise<void>;
+    private invalidateRequestHolder;
     /**
-     * Gets the current request context.
-     * @returns The current request context holder or null
+     * Common invalidation logic for holders based on their status.
      */
-    getCurrentRequestContext(): RequestContextHolder | null;
+    private invalidateHolderByStatus;
     /**
-     * Sets the current request context.
-     * @param requestId The request ID to set as current
+     * Destroys a holder and cleans up its resources.
      */
-    setCurrentRequestContext(requestId: string): void;
+    private destroyHolder;
     /**
-     * Validates and resolves token arguments, handling factory token resolution and validation.
+     * Destroys a request-scoped holder and cleans up its resources.
      */
-    private validateAndResolveTokenArgs;
+    private destroyRequestHolder;
     /**
-     * Internal method to resolve token args and create instance name.
-     * Handles factory token resolution and validation.
+     * Common destroy logic for holders with customizable cleanup.
      */
-    private resolveTokenAndPrepareInstanceName;
+    private destroyHolderWithCleanup;
     /**
-     * Gets an instance by its instance name, handling all the logic after instance name creation.
+     * Waits for a holder to settle (either created, destroyed, or error state).
      */
-    private retrieveOrCreateInstanceByInstanceName;
+    private waitForHolderToSettle;
     /**
-     * Attempts to retrieve an existing instance, handling request-scoped and singleton instances.
-     * Returns null if no instance exists and a new one should be created.
+     * Clears services with dependency awareness, ensuring proper cleanup order.
+     * Services with no dependencies are cleared first, then services that depend on them.
      */
-    private tryGetExistingInstance;
+    private clearServicesWithDependencyAwareness;
     /**
-     * Attempts to get a request-scoped instance if applicable.
+     * Finds services that are ready to be cleared in the current round.
+     * A service is ready if all its dependencies have already been cleared.
      */
-    private tryGetRequestScopedInstance;
+    private findServicesReadyForClearing;
     /**
-     * Attempts to get a singleton instance from the manager.
+     * Force clears services that couldn't be cleared through normal dependency resolution.
+     * This handles edge cases like circular dependencies.
      */
-    private tryGetSingletonInstance;
+    private forceClearServices;
     /**
-     * Waits for an instance holder to be ready and returns the appropriate result.
+     * Gets all service names currently managed by the ServiceLocator.
      */
-    private waitForInstanceReady;
+    private getAllServiceNames;
     /**
      * Emits events to listeners for instance lifecycle events.
      */
     private emitInstanceEvent;
+}
+
+declare class ServiceLocator {
+    private readonly registry;
+    private readonly logger;
+    private readonly injectors;
+    private readonly eventBus;
+    private readonly manager;
+    private readonly serviceInstantiator;
+    private readonly tokenProcessor;
+    private readonly requestContextManager;
+    private readonly serviceInvalidator;
+    private readonly instanceResolver;
+    constructor(registry?: Registry, logger?: Console | null, injectors?: Injectors);
+    getEventBus(): ServiceLocatorEventBus;
+    getManager(): ServiceLocatorManager;
+    getRequestContexts(): Map<string, RequestContextHolder>;
+    getRequestContextManager(): RequestContextManager;
+    getServiceInvalidator(): ServiceInvalidator;
+    getInstanceIdentifier(token: AnyInjectableType, args?: any): string;
+    getInstance(token: AnyInjectableType, args?: any, onPrepare?: (data: {
+        instanceName: string;
+        actualToken: any;
+        validatedArgs?: any;
+    }) => void): Promise<any[]>;
+    getOrThrowInstance<Instance>(token: AnyInjectableType, args: any): Promise<Instance>;
+    getSyncInstance<Instance, Schema extends InjectionTokenSchemaType | undefined>(token: AnyInjectableType, args: Schema extends ZodObject ? z.input<Schema> : Schema extends ZodOptional<ZodObject> ? z.input<Schema> | undefined : undefined): Instance | null;
+    invalidate(service: string, round?: number): Promise<any>;
     /**
-     * Creates a new instance for the given token and arguments.
-     */
-    private createNewInstance;
-    /**
-     * Instantiates a service from the registry using the service instantiator.
-     */
-    private instantiateServiceFromRegistry;
-    /**
-     * Handles the result of service instantiation.
+     * Gracefully clears all services in the ServiceLocator using invalidation logic.
+     * This method respects service dependencies and ensures proper cleanup order.
+     * Services that depend on others will be invalidated first, then their dependencies.
+     *
+     * @param options Optional configuration for the clearing process
+     * @returns Promise that resolves when all services have been cleared
      */
-    private handleInstantiationResult;
+    clearAll(options?: ClearAllOptions): Promise<void>;
     /**
-     * Handles successful service instantiation.
+     * 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
      */
-    private handleInstantiationSuccess;
+    beginRequest(requestId: string, metadata?: Record<string, any>, priority?: number): RequestContextHolder;
     /**
-     * Handles service instantiation errors.
+     * Ends a request context and cleans up all associated instances.
+     * @param requestId The request ID to end
      */
-    private handleInstantiationError;
+    endRequest(requestId: string): Promise<void>;
     /**
-     * Stores an instance holder based on its scope.
+     * Gets the current request context.
+     * @returns The current request context holder or null
      */
-    private storeInstanceByScope;
+    getCurrentRequestContext(): RequestContextHolder | null;
     /**
-     * Tries to get a pre-prepared instance from request contexts.
+     * Sets the current request context.
+     * @param requestId The request ID to set as current
      */
-    private tryGetPrePreparedInstance;
+    setCurrentRequestContext(requestId: string): void;
     /**
-     * Creates a factory context for dependency injection during service instantiation.
-     * @param contextHolder Optional request context holder for priority-based resolution
+     * Waits for all services to settle (either created, destroyed, or error state).
      */
-    private createFactoryContext;
+    ready(): Promise<void>;
     /**
-     * Generates a unique instance name based on token and arguments.
+     * Helper method for TokenProcessor to access pre-prepared instances.
+     * This is needed for the factory context creation.
      */
-    private generateInstanceName;
+    tryGetPrePreparedInstance(instanceName: string, contextHolder: RequestContextHolder | undefined, deps: Set<string>): any;
     /**
-     * Formats a single argument value for instance name generation.
+     * Helper method for InstanceResolver to generate instance names.
+     * This is needed for the factory context creation.
      */
-    private formatArgValue;
+    generateInstanceName(token: any, args: any): string;
 }
 export { ServiceLocator }
 export { ServiceLocator as ServiceLocator_alias_1 }
@@ -922,7 +1068,6 @@ declare interface ServiceLocatorInstanceHolderCreated<Instance> {
     deps: Set<string>;
     destroyListeners: ServiceLocatorInstanceDestroyListener[];
     createdAt: number;
-    ttl: number;
 }
 export { ServiceLocatorInstanceHolderCreated }
 export { ServiceLocatorInstanceHolderCreated as ServiceLocatorInstanceHolderCreated_alias_1 }
@@ -938,7 +1083,6 @@ declare interface ServiceLocatorInstanceHolderCreating<Instance> {
     deps: Set<string>;
     destroyListeners: ServiceLocatorInstanceDestroyListener[];
     createdAt: number;
-    ttl: number;
 }
 export { ServiceLocatorInstanceHolderCreating }
 export { ServiceLocatorInstanceHolderCreating as ServiceLocatorInstanceHolderCreating_alias_1 }
@@ -954,7 +1098,6 @@ declare interface ServiceLocatorInstanceHolderDestroying<Instance> {
     deps: Set<string>;
     destroyListeners: ServiceLocatorInstanceDestroyListener[];
     createdAt: number;
-    ttl: number;
 }
 export { ServiceLocatorInstanceHolderDestroying }
 export { ServiceLocatorInstanceHolderDestroying as ServiceLocatorInstanceHolderDestroying_alias_1 }
@@ -970,7 +1113,6 @@ declare interface ServiceLocatorInstanceHolderError {
     deps: Set<string>;
     destroyListeners: ServiceLocatorInstanceDestroyListener[];
     createdAt: number;
-    ttl: number;
 }
 export { ServiceLocatorInstanceHolderError }
 export { ServiceLocatorInstanceHolderError as ServiceLocatorInstanceHolderError_alias_1 }
@@ -986,9 +1128,9 @@ export { ServiceLocatorInstanceHolderStatus as ServiceLocatorInstanceHolderStatu
 
 declare class ServiceLocatorManager extends BaseInstanceHolderManager {
     constructor(logger?: Console | null);
-    get(name: string): [InstanceExpired | InstanceDestroying, ServiceLocatorInstanceHolder] | [InstanceNotFound] | [undefined, ServiceLocatorInstanceHolder];
+    get(name: string): [DIError, ServiceLocatorInstanceHolder] | [DIError] | [undefined, ServiceLocatorInstanceHolder];
     set(name: string, holder: ServiceLocatorInstanceHolder): void;
-    has(name: string): [InstanceExpired | InstanceDestroying] | [undefined, boolean];
+    has(name: string): [DIError] | [undefined, boolean];
     /**
      * Creates a new holder with Created status and an actual instance.
      * This is useful for creating holders that already have their instance ready.
@@ -997,10 +1139,9 @@ declare class ServiceLocatorManager extends BaseInstanceHolderManager {
      * @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
      */
-    storeCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): ServiceLocatorInstanceHolder<Instance>;
+    storeCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>): ServiceLocatorInstanceHolder<Instance>;
 }
 export { ServiceLocatorManager }
 export { ServiceLocatorManager as ServiceLocatorManager_alias_1 }
@@ -1017,6 +1158,109 @@ export declare const test4: {
 
 export declare const test5: object;
 
+/**
+ * A binding builder for the TestContainer that allows chaining binding operations.
+ */
+declare class TestBindingBuilder<T> {
+    private readonly container;
+    private readonly token;
+    constructor(container: TestContainer, token: InjectionToken<T, any>);
+    /**
+     * Binds the token to a specific value.
+     * This is useful for testing with mock values or constants.
+     * @param value The value to bind to the token
+     */
+    toValue(value: T): TestContainer;
+    /**
+     * Binds the token to a class constructor.
+     * @param target The class constructor to bind to
+     */
+    toClass(target: ClassType): TestContainer;
+}
+export { TestBindingBuilder }
+export { TestBindingBuilder as TestBindingBuilder_alias_1 }
+
+/**
+ * TestContainer extends the base Container with additional methods useful for testing.
+ * It provides a simplified API for binding values and classes during test setup.
+ */
+declare class TestContainer extends Container {
+    constructor(registry?: Registry, logger?: Console | null, injectors?: Injectors);
+    /**
+     * Creates a binding builder for the given token.
+     * This allows chaining binding operations like bind(Token).toValue(value).
+     * @param token The injection token to bind
+     * @returns A TestBindingBuilder for chaining binding operations
+     */
+    bind<T>(token: ClassType): TestBindingBuilder<T>;
+    bind<T>(token: InjectionToken<T, any>): TestBindingBuilder<T>;
+    /**
+     * Binds a value directly to a token.
+     * This is a convenience method equivalent to bind(token).toValue(value).
+     * @param token The injection token to bind
+     * @param value The value to bind to the token
+     * @returns The TestContainer instance for chaining
+     */
+    bindValue<T>(token: ClassType, value: T): TestContainer;
+    bindValue<T>(token: InjectionToken<T, any>, value: T): TestContainer;
+    /**
+     * Binds a class to a token.
+     * This is a convenience method equivalent to bind(token).toClass(target).
+     * @param token The injection token to bind
+     * @param target The class constructor to bind to
+     * @returns The TestContainer instance for chaining
+     */
+    bindClass(token: ClassType, target: ClassType): TestContainer;
+    bindClass<T>(token: InjectionToken<T, any>, target: ClassType): TestContainer;
+    /**
+     * Creates a new TestContainer instance with the same configuration.
+     * This is useful for creating isolated test containers.
+     * @returns A new TestContainer instance
+     */
+    createChild(): TestContainer;
+}
+export { TestContainer }
+export { TestContainer as TestContainer_alias_1 }
+
+/**
+ * TokenProcessor handles token validation, resolution, and instance name generation.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export declare class TokenProcessor {
+    private readonly logger;
+    constructor(logger?: Console | null);
+    /**
+     * Validates and resolves token arguments, handling factory token resolution and validation.
+     */
+    validateAndResolveTokenArgs(token: AnyInjectableType, args?: any): [
+    DIError | undefined,
+        {
+        actualToken: InjectionTokenType;
+        validatedArgs?: any;
+    }
+    ];
+    /**
+     * Generates a unique instance name based on token and arguments.
+     */
+    generateInstanceName(token: InjectionTokenType, args: any): string;
+    /**
+     * Formats a single argument value for instance name generation.
+     */
+    formatArgValue(value: any): string;
+    /**
+     * Creates a factory context for dependency injection during service instantiation.
+     * @param serviceLocator Reference to the service locator for dependency resolution
+     */
+    createFactoryContext(serviceLocator: ServiceLocator): FactoryContext & {
+        getDestroyListeners: () => (() => void)[];
+        deps: Set<string>;
+    };
+    /**
+     * Tries to get a pre-prepared instance from request contexts.
+     */
+    tryGetPrePreparedInstance(instanceName: string, contextHolder: RequestContextHolder | undefined, deps: Set<string>, currentRequestContext: RequestContextHolder | null): any;
+}
+
 declare type UnionToArray<T, A extends unknown[] = []> = IsUnion<T> extends true ? UnionToArray<Exclude<T, PopUnion<T>>, [PopUnion<T>, ...A]> : [T, ...A];
 export { UnionToArray }
 export { UnionToArray as UnionToArray_alias_1 }
@@ -1032,15 +1276,6 @@ export { UnionToOvlds }
 export { UnionToOvlds as UnionToOvlds_alias_1 }
 export { UnionToOvlds as UnionToOvlds_alias_2 }
 
-declare class UnknownError extends Error {
-    code: ErrorsEnum;
-    parent?: Error;
-    constructor(message: string | Error);
-}
-export { UnknownError }
-export { UnknownError as UnknownError_alias_1 }
-export { UnknownError as UnknownError_alias_2 }
-
 declare const wrapSyncInit: Injectors['wrapSyncInit'];
 export { wrapSyncInit }
 export { wrapSyncInit as wrapSyncInit_alias_1 }