@djodjonx/wiredi 0.0.2

package/dist/index.d.mts

@@ -0,0 +1,1139 @@
+import * as awilix0 from "awilix";
+import { AwilixContainer } from "awilix";
+import * as inversify0 from "inversify";
+import { Container } from "inversify";
+
+//#region src/Provider/types.d.ts
+/**
+ * Generic constructor type
+ * @template T - The type of the class instance
+ */
+type Constructor$3<T = any> = new (...args: any[]) => T;
+/**
+ * Dependency lifecycle options
+ * Independent of the underlying container implementation
+ */
+declare enum ProviderLifecycle {
+  /** Single shared instance throughout the application (default) */
+  Singleton = "singleton",
+  /** New instance created on each resolution */
+  Transient = "transient",
+  /** One instance per scope/child container */
+  Scoped = "scoped",
+}
+/**
+ * Resolution token type (symbol or class constructor)
+ * @template T - The type of the resolved dependency
+ */
+type ProviderToken<T = any> = symbol | Constructor$3<T>;
+/**
+ * DI Container Provider Interface
+ *
+ * Contract that each adapter (tsyringe, awilix, inversify, etc.)
+ * must implement to be compatible with WireDI.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomProvider implements ContainerProvider {
+ *     readonly name = 'my-provider'
+ *     // ... implement all methods
+ * }
+ * ```
+ */
+interface ContainerProvider {
+  /**
+       * Provider name for debugging and logging purposes
+       */
+  readonly name: string;
+  /**
+       * Registers a static value in the container
+       *
+       * @template T - The type of the value
+       * @param token - Symbol token to register the value under
+       * @param value - The value to register
+       *
+       * @example
+       * ```typescript
+       * provider.registerValue(TOKENS.ApiUrl, 'https://api.example.com')
+       * ```
+       */
+  registerValue<T>(token: symbol, value: T): void;
+  /**
+       * Registers a factory function in the container
+       *
+       * @template T - The type of the value produced by the factory
+       * @param token - Symbol token to register the factory under
+       * @param factory - Function that creates the instance (receives the provider to resolve dependencies)
+       *
+       * @example
+       * ```typescript
+       * provider.registerFactory(TOKENS.HttpClient, (p) => {
+       *     return new HttpClient(p.resolve(TOKENS.ApiUrl))
+       * })
+       * ```
+       */
+  registerFactory<T>(token: symbol, factory: (provider: ContainerProvider) => T): void;
+  /**
+       * Registers a class in the container
+       *
+       * @template T - The type of the class instance
+       * @param token - Token (symbol or class) to register under
+       * @param implementation - Class to instantiate (optional if token is a class)
+       * @param lifecycle - Instance lifecycle (Singleton, Transient, or Scoped)
+       *
+       * @example
+       * ```typescript
+       * // Register class as its own token
+       * provider.registerClass(UserService)
+       *
+       * // Register implementation for a symbol token
+       * provider.registerClass(TOKENS.Logger, ConsoleLogger, ProviderLifecycle.Singleton)
+       * ```
+       */
+  registerClass<T>(token: ProviderToken<T>, implementation?: Constructor$3<T>, lifecycle?: ProviderLifecycle): void;
+  /**
+       * Checks if a token is already registered in the container
+       *
+       * @param token - Token to check
+       * @returns `true` if the token is registered, `false` otherwise
+       *
+       * @example
+       * ```typescript
+       * if (!provider.isRegistered(TOKENS.Logger)) {
+       *     provider.registerClass(TOKENS.Logger, ConsoleLogger)
+       * }
+       * ```
+       */
+  isRegistered(token: ProviderToken): boolean;
+  /**
+       * Resolves a dependency from the container
+       *
+       * @template T - The type of the resolved dependency
+       * @param token - Token of the dependency to resolve
+       * @returns Instance of the dependency
+       * @throws Error if the token is not registered
+       *
+       * @example
+       * ```typescript
+       * const logger = provider.resolve<LoggerInterface>(TOKENS.Logger)
+       * const userService = provider.resolve(UserService)
+       * ```
+       */
+  resolve<T>(token: ProviderToken<T>): T;
+  /**
+       * Creates a child scope (child container)
+       * Useful for HTTP requests, transactions, or isolated contexts
+       *
+       * @returns New scoped provider instance
+       *
+       * @example
+       * ```typescript
+       * const requestScope = provider.createScope()
+       * requestScope.registerValue(TOKENS.RequestId, generateRequestId())
+       * ```
+       */
+  createScope(): ContainerProvider;
+  /**
+       * Releases provider resources
+       * Called during application cleanup or shutdown
+       */
+  dispose(): void;
+  /**
+       * Access to the underlying container (for advanced use cases)
+       * Return type is generic as it depends on the implementation
+       *
+       * @returns The underlying DI container instance
+       *
+       * @example
+       * ```typescript
+       * const tsyringeContainer = provider.getUnderlyingContainer() as DependencyContainer
+       * ```
+       */
+  getUnderlyingContainer(): unknown;
+}
+/**
+ * Options for provider adapters
+ */
+interface ProviderAdapterOptions {
+  /**
+       * Existing container to use (optional)
+       * If not provided, a new container will be created
+       */
+  container?: unknown;
+}
+//#endregion
+//#region src/Provider/ProviderManager.d.ts
+/**
+ * Configures the DI container provider to use globally
+ *
+ * Must be called ONCE at the application entry point,
+ * before any calls to `useBuilder`.
+ *
+ * @param provider - The provider instance to use
+ * @throws Error if a provider is already configured
+ *
+ * @example
+ * ```typescript
+ * // main.ts - Application entry point
+ * import 'reflect-metadata'
+ * import { container, Lifecycle } from 'tsyringe'
+ * import { useContainerProvider, TsyringeProvider } from '@djodjonx/wiredi'
+ *
+ * useContainerProvider(new TsyringeProvider({ container, Lifecycle }))
+ *
+ * // Now useBuilder can be used anywhere
+ * ```
+ */
+declare function useContainerProvider(provider: ContainerProvider): void;
+/**
+ * Retrieves the configured container provider
+ *
+ * @returns The configured provider instance
+ * @throws Error if no provider is configured
+ *
+ * @example
+ * ```typescript
+ * const provider = getContainerProvider()
+ * const service = provider.resolve(MyService)
+ * ```
+ */
+declare function getContainerProvider(): ContainerProvider;
+/**
+ * Checks if a provider is currently configured
+ *
+ * @returns `true` if a provider is configured, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (!hasContainerProvider()) {
+ *     useContainerProvider(new TsyringeProvider({ container, Lifecycle }))
+ * }
+ * ```
+ */
+declare function hasContainerProvider(): boolean;
+/**
+ * Resets the global provider (primarily for testing)
+ *
+ * ⚠️ WARNING: Do not use in production, only for testing purposes
+ *
+ * @example
+ * ```typescript
+ * // In a test file
+ * beforeEach(() => {
+ *     resetContainerProvider()
+ *     useContainerProvider(new TsyringeProvider({ container, Lifecycle }))
+ * })
+ * ```
+ */
+declare function resetContainerProvider(): void;
+//#endregion
+//#region src/Provider/adapters/TsyringeProvider.d.ts
+/**
+ * Minimal interface for tsyringe's DependencyContainer
+ * Allows decoupling from the actual tsyringe package
+ */
+interface TsyringeDependencyContainer {
+  /**
+       * Registers a dependency in the container
+       */
+  register<T>(token: any, provider: {
+    useValue?: T;
+    useFactory?: () => T;
+    useClass?: Constructor$3<T>;
+  }, options?: {
+    lifecycle?: unknown;
+  }): void;
+  /**
+       * Checks if a token is registered
+       */
+  isRegistered(token: any): boolean;
+  /**
+       * Resolves a dependency from the container
+       */
+  resolve<T>(token: any): T;
+  /**
+       * Creates a child container for scoped registrations
+       */
+  createChildContainer(): TsyringeDependencyContainer;
+  /**
+       * Clears all singleton instances
+       */
+  clearInstances(): void;
+}
+/**
+ * Minimal interface for tsyringe's Lifecycle enum
+ */
+interface TsyringeLifecycle {
+  /** Single instance throughout the application */
+  Singleton: unknown;
+  /** New instance on each resolution */
+  Transient: unknown;
+  /** Single instance per child container */
+  ContainerScoped: unknown;
+  /** Single instance per resolution tree */
+  ResolutionScoped: unknown;
+}
+/**
+ * Dependencies required to create a TsyringeProvider
+ * The user must provide these from their tsyringe installation
+ */
+interface TsyringeDependencies {
+  /**
+       * The tsyringe container to use
+       * @example `import { container } from 'tsyringe'`
+       */
+  container: TsyringeDependencyContainer;
+  /**
+       * The tsyringe Lifecycle enum
+       * @example `import { Lifecycle } from 'tsyringe'`
+       */
+  Lifecycle: TsyringeLifecycle;
+}
+/**
+ * Configuration options for TsyringeProvider
+ */
+interface TsyringeProviderOptions {
+  /**
+       * Use a child container instead of the provided container
+       * Useful for isolating registrations in tests or modules
+       * @default false
+       */
+  useChildContainer?: boolean;
+}
+/**
+ * tsyringe adapter implementing the ContainerProvider interface
+ *
+ * Provides integration between WireDI and tsyringe,
+ * allowing you to use tsyringe as your DI container while benefiting
+ * from WireDI's configuration and validation features.
+ */
+declare class TsyringeProvider implements ContainerProvider {
+  /** @inheritdoc */
+  readonly name = "tsyringe";
+  /** The tsyringe container instance */
+  private readonly container;
+  /** The tsyringe Lifecycle enum reference */
+  private readonly Lifecycle;
+  /**
+       * Creates a new TsyringeProvider instance
+       *
+       * @param dependencies - tsyringe dependencies (container and Lifecycle)
+       * @param options - Configuration options
+       *
+       * @example
+       * ```typescript
+       * import { container, Lifecycle } from 'tsyringe'
+       *
+       * const provider = new TsyringeProvider(
+       *     { container, Lifecycle },
+       *     { useChildContainer: true }
+       * )
+       * ```
+       */
+  constructor(dependencies: TsyringeDependencies, options?: TsyringeProviderOptions);
+  /** @inheritdoc */
+  registerValue<T>(token: symbol, value: T): void;
+  /** @inheritdoc */
+  registerFactory<T>(token: symbol, factory: (provider: ContainerProvider) => T): void;
+  /** @inheritdoc */
+  registerClass<T>(token: ProviderToken<T>, implementation?: Constructor$3<T>, lifecycle?: ProviderLifecycle): void;
+  /** @inheritdoc */
+  isRegistered(token: ProviderToken): boolean;
+  /** @inheritdoc */
+  resolve<T>(token: ProviderToken<T>): T;
+  /** @inheritdoc */
+  createScope(): ContainerProvider;
+  /** @inheritdoc */
+  dispose(): void;
+  /**
+       * Returns the underlying tsyringe DependencyContainer
+       * @returns The tsyringe container instance
+       */
+  getUnderlyingContainer(): TsyringeDependencyContainer;
+  /**
+       * Maps WireDI lifecycle to tsyringe Lifecycle
+       * @internal
+       */
+  private mapLifecycle;
+  /**
+       * Type guard to check if a token is a class constructor
+       * @internal
+       */
+  private isConstructor;
+}
+//#endregion
+//#region src/Provider/adapters/AwilixProvider.d.ts
+/**
+ * Generic constructor type for class instantiation
+ * @template T - The type of the class instance
+ * @internal
+ */
+type Constructor$2<T = any> = new (...args: any[]) => T;
+/**
+ * Configuration options for AwilixProvider
+ */
+interface AwilixProviderOptions {
+  /**
+       * Existing Awilix container to use
+       * If not provided, a new container will be created
+       * @default undefined (creates new container)
+       */
+  container?: AwilixContainer;
+  /**
+       * Awilix injection mode
+       * - `'PROXY'`: Dependencies are injected via a proxy object (recommended)
+       * - `'CLASSIC'`: Dependencies are injected via constructor parameters by name
+       * @default 'PROXY'
+       */
+  injectionMode?: 'PROXY' | 'CLASSIC';
+}
+/**
+ * Awilix adapter implementing the ContainerProvider interface
+ *
+ * Provides integration between WireDI and Awilix,
+ * allowing you to use Awilix as your DI container while benefiting
+ * from WireDI's configuration and validation features.
+ */
+declare class AwilixProvider implements ContainerProvider {
+  private options;
+  /** @inheritdoc */
+  readonly name = "awilix";
+  /** The Awilix container instance */
+  private container;
+  /** Maps tokens to Awilix string-based registration names */
+  private tokenToName;
+  /** Counter for generating unique token names */
+  private nameCounter;
+  /** Lazily loaded awilix module */
+  private awilix;
+  /**
+       * Creates a new AwilixProvider instance
+       *
+       * @param options - Configuration options
+       *
+       * @remarks
+       * When using the constructor directly, you must call `init()` before use,
+       * or use `createSync()` for synchronous initialization.
+       */
+  constructor(options?: AwilixProviderOptions);
+  /**
+       * Lazily initializes the container (async)
+       * @internal
+       */
+  private ensureInitialized;
+  /**
+       * Throws if container is not initialized
+       * @internal
+       */
+  private ensureInitializedSync;
+  /**
+       * Initializes the provider asynchronously
+       *
+       * @remarks
+       * Required before using the provider if not using `createSync()`.
+       *
+       * @example
+       * ```typescript
+       * const provider = new AwilixProvider({ injectionMode: 'PROXY' })
+       * await provider.init()
+       * useContainerProvider(provider)
+       * ```
+       */
+  init(): Promise<void>;
+  /**
+       * Creates a pre-initialized provider synchronously
+       *
+       * @param awilix - The awilix module import
+       * @param options - Configuration options
+       * @returns Fully initialized AwilixProvider instance
+       *
+       * @remarks
+       * This is the recommended way to create an AwilixProvider as it
+       * avoids async initialization and ensures the provider is ready immediately.
+       *
+       * @example
+       * ```typescript
+       * import * as awilix from 'awilix'
+       *
+       * const provider = AwilixProvider.createSync(awilix, {
+       *     injectionMode: 'CLASSIC'
+       * })
+       * ```
+       */
+  static createSync(awilix: typeof awilix0, options?: AwilixProviderOptions): AwilixProvider;
+  /**
+       * Gets or creates a unique string name for a token
+       * Awilix uses string-based registration, so we map symbols/classes to strings
+       * @internal
+       */
+  private getTokenName;
+  /**
+       * Maps WireDI lifecycle to Awilix Lifetime
+       * @internal
+       */
+  private mapLifecycle;
+  /** @inheritdoc */
+  registerValue<T>(token: symbol, value: T): void;
+  /** @inheritdoc */
+  registerFactory<T>(token: symbol, factory: (provider: ContainerProvider) => T): void;
+  /** @inheritdoc */
+  registerClass<T>(token: symbol | Constructor$2<T>, impl?: Constructor$2<T>, lifecycle?: ProviderLifecycle): void;
+  /** @inheritdoc */
+  isRegistered(token: symbol | Constructor$2): boolean;
+  /** @inheritdoc */
+  resolve<T>(token: symbol | Constructor$2<T>): T;
+  /** @inheritdoc */
+  createScope(): ContainerProvider;
+  /** @inheritdoc */
+  dispose(): void;
+  /**
+       * Returns the underlying Awilix container instance
+       * @returns The AwilixContainer instance
+       */
+  getUnderlyingContainer(): AwilixContainer;
+}
+//#endregion
+//#region src/Provider/adapters/InversifyProvider.d.ts
+/**
+ * Generic constructor type for class instantiation
+ * @template T - The type of the class instance
+ * @internal
+ */
+type Constructor$1<T = any> = new (...args: any[]) => T;
+/**
+ * InversifyJS binding scope options
+ * @internal
+ */
+type BindingScope = 'Singleton' | 'Transient' | 'Request';
+/**
+ * Configuration options for InversifyProvider
+ */
+interface InversifyProviderOptions {
+  /**
+       * Existing Inversify container to use
+       * If not provided, a new container will be created
+       * @default undefined (creates new container)
+       */
+  container?: Container;
+  /**
+       * Default binding scope for registrations without explicit lifecycle
+       * @default 'Singleton'
+       */
+  defaultScope?: BindingScope;
+}
+/**
+ * InversifyJS adapter implementing the ContainerProvider interface
+ *
+ * Provides integration between WireDI and InversifyJS,
+ * allowing you to use InversifyJS as your DI container while benefiting
+ * from WireDI's configuration and validation features.
+ */
+declare class InversifyProvider implements ContainerProvider {
+  private options;
+  /** @inheritdoc */
+  readonly name = "inversify";
+  /** The InversifyJS container instance */
+  private container;
+  /** Default scope for bindings */
+  private defaultScope;
+  /** Lazily loaded inversify module */
+  private inversify;
+  /**
+       * Creates a new InversifyProvider instance
+       *
+       * @param options - Configuration options
+       *
+       * @remarks
+       * When using the constructor directly, you must call `init()` before use,
+       * or use `createSync()` for synchronous initialization.
+       */
+  constructor(options?: InversifyProviderOptions);
+  /**
+       * Lazily initializes the container (async)
+       * @internal
+       */
+  private ensureInitialized;
+  /**
+       * Throws if container is not initialized
+       * @internal
+       */
+  private ensureInitializedSync;
+  /**
+       * Initializes the provider asynchronously
+       *
+       * @remarks
+       * Required before using the provider if not using `createSync()`.
+       *
+       * @example
+       * ```typescript
+       * const provider = new InversifyProvider()
+       * await provider.init()
+       * useContainerProvider(provider)
+       * ```
+       */
+  init(): Promise<void>;
+  /**
+       * Creates a pre-initialized provider synchronously
+       *
+       * @param inversify - The inversify module import
+       * @param options - Configuration options
+       * @returns Fully initialized InversifyProvider instance
+       *
+       * @remarks
+       * This is the recommended way to create an InversifyProvider as it
+       * avoids async initialization and ensures the provider is ready immediately.
+       *
+       * @example
+       * ```typescript
+       * import * as inversify from 'inversify'
+       *
+       * const provider = InversifyProvider.createSync(inversify, {
+       *     defaultScope: 'Transient'
+       * })
+       * ```
+       */
+  static createSync(inversify: typeof inversify0, options?: InversifyProviderOptions): InversifyProvider;
+  /**
+       * Maps WireDI lifecycle to InversifyJS binding scope
+       * @internal
+       */
+  private mapLifecycle;
+  /**
+       * Applies the scope to an InversifyJS binding
+       * @internal
+       */
+  private applyScope;
+  /** @inheritdoc */
+  registerValue<T>(token: symbol, value: T): void;
+  /** @inheritdoc */
+  registerFactory<T>(token: symbol, factory: (provider: ContainerProvider) => T): void;
+  /** @inheritdoc */
+  registerClass<T>(token: symbol | Constructor$1<T>, impl?: Constructor$1<T>, lifecycle?: ProviderLifecycle): void;
+  /** @inheritdoc */
+  isRegistered(token: symbol | Constructor$1): boolean;
+  /** @inheritdoc */
+  resolve<T>(token: symbol | Constructor$1<T>): T;
+  /** @inheritdoc */
+  createScope(): ContainerProvider;
+  /** @inheritdoc */
+  dispose(): void;
+  /**
+       * Returns the underlying InversifyJS Container instance
+       * @returns The InversifyJS Container
+       */
+  getUnderlyingContainer(): Container;
+}
+//#endregion
+//#region src/EventDispatcher/Provider/types.d.ts
+/**
+ * Token representing an event type (class constructor)
+ * Events are identified by their class constructor
+ */
+type EventToken = new (...args: any[]) => any;
+/**
+ * Token representing a listener (class constructor or symbol)
+ * Listeners can be registered as classes or symbol tokens
+ */
+type ListenerToken = (new (...args: any[]) => any) | symbol;
+/**
+ * Configuration entry for registering a listener to an event
+ *
+ * @example
+ * ```typescript
+ * const entry: EventListenerEntry = {
+ *     event: UserCreatedEvent,
+ *     listener: SendWelcomeEmailListener
+ * }
+ * ```
+ */
+interface EventListenerEntry {
+  /** The event class to listen for */
+  event: EventToken;
+  /** The listener class or token to invoke */
+  listener: ListenerToken;
+}
+/**
+ * Interface for Event Dispatcher Provider
+ *
+ * This abstraction allows plugging different event dispatching systems
+ * (e.g., custom implementation, EventEmitter, RxJS, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Create and register provider at app startup
+ * const eventProvider = new MutableEventDispatcherProvider({
+ *     containerProvider: getContainerProvider()
+ * })
+ * useEventDispatcherProvider(eventProvider)
+ *
+ * // Later, dispatch events
+ * const dispatcher = getEventDispatcherProvider()
+ * dispatcher.dispatch(new UserCreatedEvent(user))
+ * ```
+ */
+interface EventDispatcherProvider {
+  /**
+       * Unique name identifying this provider implementation
+       * Used for debugging and logging purposes
+       */
+  readonly name: string;
+  /**
+       * Registers a listener for a specific event type
+       *
+       * @param eventToken - The event class/constructor to listen for
+       * @param listenerToken - The listener class/symbol to invoke when event is dispatched
+       *
+       * @example
+       * ```typescript
+       * provider.register(UserCreatedEvent, SendWelcomeEmailListener)
+       * ```
+       */
+  register(eventToken: EventToken, listenerToken: ListenerToken): void;
+  /**
+       * Dispatches an event to all registered listeners
+       * Listeners are resolved from the DI container and their `onEvent` method is called
+       *
+       * @param event - The event instance to dispatch
+       *
+       * @example
+       * ```typescript
+       * provider.dispatch(new UserCreatedEvent(user))
+       * ```
+       */
+  dispatch(event: object): void;
+  /**
+       * Checks if any listeners are registered for an event type
+       *
+       * @param eventToken - The event class/constructor to check
+       * @returns `true` if at least one listener is registered
+       */
+  hasListeners(eventToken: EventToken): boolean;
+  /**
+       * Removes all listeners for a specific event type
+       *
+       * @param eventToken - The event class/constructor to clear
+       */
+  clearListeners(eventToken: EventToken): void;
+  /**
+       * Removes all registered listeners from all events
+       */
+  clearAllListeners(): void;
+  /**
+       * Returns the underlying event dispatcher implementation
+       * Useful for advanced use cases or testing
+       *
+       * @returns The internal data structure (implementation-specific)
+       */
+  getUnderlyingDispatcher(): unknown;
+}
+/**
+ * Configuration options for creating an EventDispatcherProvider
+ */
+interface EventDispatcherProviderOptions {
+  /**
+       * The DI container provider used to resolve listener instances
+       * Listeners are resolved from this container when events are dispatched
+       */
+  containerProvider: ContainerProvider;
+}
+//#endregion
+//#region src/EventDispatcher/Provider/MutableEventDispatcherProvider.d.ts
+/**
+ * Default EventDispatcherProvider implementation
+ *
+ * This provider stores listeners in memory and resolves them through the DI container
+ * when dispatching events. Each listener must implement an `onEvent(event)` method.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import {
+ *     MutableEventDispatcherProvider,
+ *     useEventDispatcherProvider,
+ *     getContainerProvider
+ * } from '@djodjonx/wiredi'
+ *
+ * const eventProvider = new MutableEventDispatcherProvider({
+ *     containerProvider: getContainerProvider()
+ * })
+ * useEventDispatcherProvider(eventProvider)
+ * ```
+ *
+ * @example Dispatching events
+ * ```typescript
+ * const dispatcher = getEventDispatcherProvider()
+ * dispatcher.dispatch(new UserCreatedEvent(user))
+ * ```
+ */
+declare class MutableEventDispatcherProvider implements EventDispatcherProvider {
+  /** @inheritdoc */
+  readonly name = "mutable-event-dispatcher";
+  /** Map of event names to their registered listener tokens */
+  private listeners;
+  /** DI container provider for resolving listener instances */
+  private containerProvider;
+  /**
+       * Creates a new MutableEventDispatcherProvider instance
+       *
+       * @param options - Configuration options including the container provider
+       */
+  constructor(options: EventDispatcherProviderOptions);
+  /**
+       * Extracts the event name from an event token (class constructor)
+       * @internal
+       */
+  private getEventName;
+  /**
+       * Extracts the event name from an event instance
+       * @internal
+       */
+  private getEventNameFromInstance;
+  /** @inheritdoc */
+  register(eventToken: EventToken, listenerToken: ListenerToken): void;
+  /** @inheritdoc */
+  dispatch(event: object): void;
+  /** @inheritdoc */
+  hasListeners(eventToken: EventToken): boolean;
+  /** @inheritdoc */
+  clearListeners(eventToken: EventToken): void;
+  /** @inheritdoc */
+  clearAllListeners(): void;
+  /**
+       * Returns the internal listeners map
+       * @returns Map of event names to listener tokens
+       */
+  getUnderlyingDispatcher(): Map<string, ListenerToken[]>;
+}
+//#endregion
+//#region src/EventDispatcher/Provider/index.d.ts
+/**
+ * Sets the global EventDispatcherProvider instance
+ *
+ * Call this once at application startup after setting up the container provider.
+ * The event dispatcher uses the container provider to resolve listener instances.
+ *
+ * @param provider - The EventDispatcherProvider implementation to use
+ * @throws Error if a provider is already registered
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     useContainerProvider,
+ *     TsyringeProvider,
+ *     useEventDispatcherProvider,
+ *     MutableEventDispatcherProvider,
+ *     getContainerProvider
+ * } from '@djodjonx/wiredi'
+ *
+ * // 1. Setup DI container first
+ * useContainerProvider(new TsyringeProvider({ container, Lifecycle }))
+ *
+ * // 2. Setup event dispatcher (optional)
+ * useEventDispatcherProvider(new MutableEventDispatcherProvider({
+ *     containerProvider: getContainerProvider()
+ * }))
+ * ```
+ */
+declare function useEventDispatcherProvider(provider: EventDispatcherProvider): void;
+/**
+ * Retrieves the currently registered EventDispatcherProvider
+ *
+ * @returns The registered EventDispatcherProvider instance
+ * @throws Error if no provider has been registered
+ *
+ * @example
+ * ```typescript
+ * const eventDispatcher = getEventDispatcherProvider()
+ * eventDispatcher.dispatch(new UserCreatedEvent(user))
+ * ```
+ */
+declare function getEventDispatcherProvider(): EventDispatcherProvider;
+/**
+ * Checks if an EventDispatcherProvider has been registered
+ *
+ * @returns `true` if a provider is registered, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (hasEventDispatcherProvider()) {
+ *     getEventDispatcherProvider().dispatch(event)
+ * }
+ * ```
+ */
+declare function hasEventDispatcherProvider(): boolean;
+/**
+ * Resets the global EventDispatcherProvider
+ *
+ * Clears all registered listeners and removes the provider.
+ * Useful for testing or reconfiguration scenarios.
+ *
+ * ⚠️ WARNING: This should rarely be used in production code.
+ *
+ * @example
+ * ```typescript
+ * // In a test file
+ * afterEach(() => {
+ *     resetEventDispatcherProvider()
+ * })
+ * ```
+ */
+declare function resetEventDispatcherProvider(): void;
+//#endregion
+//#region src/index.d.ts
+type Constructor<T = any> = new (...args: any[]) => T;
+interface BuilderConfigEntryValue<C = null> {
+  token: symbol;
+  value: <R>(context?: C) => R;
+}
+interface BuilderConfigEntryInjectionWithToken {
+  token: symbol;
+  provider: Constructor;
+  lifecycle?: ProviderLifecycle;
+}
+interface BuilderConfigEntryInjectionWithClass {
+  token: Constructor;
+  lifecycle?: ProviderLifecycle;
+}
+interface BuilderConfigEntryFactory {
+  token: symbol;
+  factory: (provider: ContainerProvider) => any;
+}
+type BuilderConfigEntries<C> = BuilderConfigEntryValue<C> | BuilderConfigEntryInjectionWithToken | BuilderConfigEntryFactory | BuilderConfigEntryInjectionWithClass;
+type InjectionConfig<C> = readonly BuilderConfigEntries<C>[];
+interface EventEntry {
+  event: Constructor;
+  listener: Constructor;
+}
+type EventConfig = readonly EventEntry[];
+interface BuilderConfig<C = null> {
+  builderId: string;
+  injections: InjectionConfig<C>;
+  listeners: EventConfig;
+}
+/**
+ * A partial builder configuration that defines a set of injections and listeners.
+ * Partials are "traits" or "mixins" that can be composed into a main `BuilderConfig`.
+ *
+ * NOTE: Partials cannot extend other partials to prevent hidden dependency chains.
+ */
+interface PartialBuilderConfig<C = null> {
+  injections?: InjectionConfig<C>;
+  listeners?: EventConfig;
+}
+type ResolveToken<T> = symbol | Constructor<T>;
+/**
+ * Helper type to extract the tuple of tokens from the injections config.
+ */
+type ExtractTokens<T> = { [K in keyof T]: T[K] extends {
+  token: infer Token;
+} ? Token : never };
+/**
+ * A builder configuration with strictly inferred token types.
+ * @template C The context type.
+ * @template Tokens The tuple of allowed tokens.
+ */
+interface TypedBuilderConfig<C, Tokens> extends BuilderConfig<C> {
+  readonly __tokens?: Tokens;
+}
+/**
+ * A partial builder configuration with strictly inferred token types.
+ * @template C The context type.
+ * @template Tokens The tuple of allowed tokens.
+ */
+interface TypedPartialConfig<C, Tokens> extends PartialBuilderConfig<C> {
+  readonly __tokens?: Tokens;
+}
+/**
+ * Interface for the return object of `useBuilder`, providing a `resolve` method.
+ * The `AllowedTokens` generic parameter strictly types which tokens can be resolved.
+ */
+interface IUseBuilder<AllowedTokens = ResolveToken<any>> {
+  /**
+       * Resolves a class dependency.
+       * The return type is automatically inferred as the class instance.
+       *
+       * @template Token The class constructor type (inferred from argument).
+       * @param token The class constructor token.
+       * @returns The instance of the class.
+       */
+  resolve<Token extends Extract<AllowedTokens, Constructor<any>>>(token: Token): InstanceType<Token>;
+  /**
+       * Resolves a dependency from the container (for Symbols or explicit types).
+       *
+       * @template T The type of the dependency to resolve.
+       * @param token The token (symbol or constructor) of the dependency.
+       *              This is strictly type-checked against the `injections` defined in the builder config.
+       * @returns The resolved instance of the dependency.
+       */
+  resolve<T>(token: AllowedTokens & ResolveToken<T>): T;
+}
+/**
+ * Helper to define a partial configuration (injections/listeners).
+ *
+ * Partials are designed to be flat collections of dependencies. They do not support
+ * inheritance (`extends`) or overriding to prevent complex dependency graphs.
+ * All conflict resolution must happen in the main `defineBuilderConfig`.
+ *
+ * @template C The type of the context object (optional).
+ * @template I The specific type of the injections array (inferred).
+ * @param config The partial builder configuration object.
+ * @returns The configuration object typed as TypedPartialConfig.
+ */
+declare function definePartialConfig<C = null, const I extends InjectionConfig<C> = InjectionConfig<C>>(config: PartialBuilderConfig<C> & {
+  injections?: I;
+}): TypedPartialConfig<C, ExtractTokens<I>>;
+/**
+ * Recursively extracts tokens from a tuple of TypedPartialConfigs.
+ */
+type ExtractTokensFromTypedPartials<T extends readonly TypedPartialConfig<any, any>[]> = T extends readonly [infer Head, ...infer Tail] ? Tail extends readonly TypedPartialConfig<any, any>[] ? Head extends TypedPartialConfig<any, infer Tokens> ? Tokens extends readonly any[] ? [...Tokens, ...ExtractTokensFromTypedPartials<Tail>] : ExtractTokensFromTypedPartials<Tail> : ExtractTokensFromTypedPartials<Tail> : [] : [];
+/**
+ * Helper to extract (Event, Listener) pairs from partials for duplicate checking.
+ */
+type ExtractListenersFromPartials<T extends readonly TypedPartialConfig<any, any>[]> = T extends readonly [infer Head, ...infer Tail] ? Tail extends readonly TypedPartialConfig<any, any>[] ? Head extends {
+  listeners?: readonly (infer L)[];
+} ? L | ExtractListenersFromPartials<Tail> : ExtractListenersFromPartials<Tail> : never : never;
+/**
+ * Validates that injections do not collide with tokens from inherited partials.
+ *
+ * Rules:
+ * 1. Token exists in Partial -> ❌ Error: Token collision (duplicates not allowed)
+ * 2. Token NOT in Partial -> ✅ Valid New Entry
+ *
+ * Note: Token overrides are not allowed. Each token must be unique across all partials
+ * and the main configuration. This prevents accidental redefinition of dependencies.
+ */
+type ValidateInjections<LocalInjections, InheritedTokenUnion> = [InheritedTokenUnion] extends [never] ? LocalInjections : { [K in keyof LocalInjections]: LocalInjections[K] extends {
+  token: infer T;
+} ? T extends InheritedTokenUnion ? {
+  error: '[WireDI] This token is already registered in a partial. Remove it from here or from the partial to avoid conflicts.';
+  token: T;
+  hint: 'Each token can only be registered once across all partials and the main config.';
+} : LocalInjections[K] : LocalInjections[K] };
+/**
+ * Validates that local listeners do not duplicate listeners already defined in partials.
+ * Duplicate = Same Event class AND Same Listener class.
+ */
+type ValidateListeners<LocalListeners, InheritedListenerUnion> = [InheritedListenerUnion] extends [never] ? LocalListeners : { [K in keyof LocalListeners]: LocalListeners[K] extends {
+  event: infer E;
+  listener: infer L;
+} ? {
+  event: E;
+  listener: L;
+} extends InheritedListenerUnion ? {
+  error: '[WireDI] This event listener is already registered in a partial';
+  event: E;
+  listener: L;
+  hint: 'Each (event, listener) pair can only be registered once.';
+} : LocalListeners[K] : LocalListeners[K] };
+/**
+ * A helper function to define a builder configuration with strict type inference and inheritance.
+ * Use this instead of manually casting with `satisfies BuilderConfig` or `as const`
+ * to ensure that `useBuilder` can correctly infer the available tokens.
+ *
+ * This function now supports `extends` to inherit from `definePartialConfig` definitions.
+ * Token collisions are strictly forbidden - each token must be unique across all partials
+ * and the main configuration to prevent accidental redefinition.
+ *
+ * @template C The type of the context object (optional).
+ * @template Partials The tuple of partial configs to extend.
+ * @template LocalInjections The specific type of the local injections array (inferred).
+ * @param config The builder configuration object.
+ * @returns The configuration object typed as TypedBuilderConfig to simplify IDE display.
+ *
+ * @example
+ * ```typescript
+ * import { Lifecycle } from 'tsyringe';
+ *
+ * class MyService {}
+ * class MyProvider {}
+ * class MyEvent {}
+ * class MyEventListener {
+ *   onEvent(event: MyEvent) {
+ *     console.log('Event received:', event);
+ *   }
+ * }
+ *
+ * const MY_TOKEN = Symbol('MY_TOKEN');
+ * const MY_VALUE_TOKEN = Symbol('MY_VALUE_TOKEN');
+ * const MY_FACTORY_TOKEN = Symbol('MY_FACTORY_TOKEN');
+ *
+ * // --- Partial Configuration ---
+ * const myPartial = definePartialConfig({
+ *   injections: [
+ *     { token: MyService } // Provides MyService
+ *   ],
+ *   listeners: [
+ *     { event: MyEvent, listener: MyEventListener }
+ *   ]
+ * });
+ *
+ * // --- Main Builder Configuration ---
+ * const myBuilderConfig = defineBuilderConfig({
+ *   builderId: 'my.unique.builder',
+ *   extends: [myPartial],
+ *   injections: [
+ *     // ❌ ERROR: Token collision - MyService is already defined in myPartial
+ *     // { token: MyService },
+ *
+ *     // ✅ OK: New tokens not in partials
+ *     { token: MY_TOKEN, provider: MyProvider },
+ *     { token: MY_TOKEN, provider: MyProvider, lifecycle: Lifecycle.Transient },
+ *
+ *     // 3. Value Injection (can use optional context)
+ *     { token: MY_VALUE_TOKEN, value: (context) => context?.someConfig ?? 'defaultValue' },
+ *
+ *     // 4. Factory Injection
+ *     { token: MY_FACTORY_TOKEN, factory: (container) => new MyService() },
+ *   ],
+ *   listeners: [
+ *     // ❌ ERROR: Duplicate listener (Event + Listener pair already in myPartial)
+ *     // { event: MyEvent, listener: MyEventListener },
+ *
+ *     // ✅ OK: New listener not in partials
+ *     { event: OtherEvent, listener: OtherEventListener },
+ *   ],
+ * });
+ *
+ * // Usage:
+ * // const { resolve } = useBuilder(myBuilderConfig, { someConfig: 'custom' });
+ * // const service = resolve(MyService);
+ * // const value = resolve(MY_VALUE_TOKEN);
+ * ```
+ */
+declare function defineBuilderConfig<C = null, const Partials extends readonly TypedPartialConfig<C, any>[] = [], const LocalInjections extends InjectionConfig<C> = InjectionConfig<C>, const LocalListeners extends EventConfig = EventConfig>(config: {
+  builderId: string;
+  extends?: Partials;
+  injections: ValidateInjections<LocalInjections, ExtractTokensFromTypedPartials<Partials>[number]>;
+  listeners: ValidateListeners<LocalListeners, ExtractListenersFromPartials<Partials>>;
+}): TypedBuilderConfig<C, [...ExtractTokensFromTypedPartials<Partials>, ...ExtractTokens<LocalInjections>]>;
+/**
+ * A composable function for setting up and interacting with a dependency injection container
+ * based on a `BuilderConfig`. It ensures that dependencies are registered only once per builderId
+ * and provides a type-safe `resolve` method.
+ *
+ * The `resolve` method is strictly type-checked to only allow tokens defined within the `injections`
+ * array of the provided `config`.
+ *
+ * ⚠️ Requires `useContainerProvider()` to be called first at app entry point.
+ *
+ * @template C The type of the context object that might be passed to value providers.
+ * @template Tokens The inferred tuple of allowed tokens from the config.
+ * @param config The typed builder configuration object.
+ * @param context An optional context object that can be passed to value providers in the injections.
+ * @returns An `IUseBuilder` instance with a type-safe `resolve` method.
+ *
+ * @example
+ * ```typescript
+ * // main.ts - Entry point
+ * import { useContainerProvider, TsyringeProvider } from '@djodjonx/wiredi'
+ * useContainerProvider(new TsyringeProvider())
+ *
+ * // anywhere.ts
+ * import { useBuilder } from '@djodjonx/wiredi'
+ * const { resolve } = useBuilder(myConfig)
+ * const service = resolve(MyService)
+ * ```
+ */
+declare function useBuilder<C = null, Tokens extends readonly any[] = []>(config: TypedBuilderConfig<C, Tokens>, context?: C): IUseBuilder<Tokens[number]>;
+//#endregion
+export { AwilixProvider, type AwilixProviderOptions, BuilderConfig, type ContainerProvider, EventConfig, type EventDispatcherProvider, type EventDispatcherProviderOptions, type EventListenerEntry, type EventToken, InjectionConfig, InversifyProvider, type InversifyProviderOptions, type ListenerToken, MutableEventDispatcherProvider, PartialBuilderConfig, type ProviderAdapterOptions, ProviderLifecycle, type ProviderToken, type TsyringeDependencies, type TsyringeDependencyContainer, type TsyringeLifecycle, TsyringeProvider, type TsyringeProviderOptions, TypedBuilderConfig, TypedPartialConfig, useBuilder as default, defineBuilderConfig, definePartialConfig, getContainerProvider, getEventDispatcherProvider, hasContainerProvider, hasEventDispatcherProvider, resetContainerProvider, resetEventDispatcherProvider, useContainerProvider, useEventDispatcherProvider };
+//# sourceMappingURL=index.d.mts.map