@wirestate/core 0.6.1 → 0.7.0-experimental.1

package/index.d.ts

@@ -1,129 +1,414 @@
-import { ServiceIdentifier, LazyServiceIdentifier, Container, Newable } from 'inversify';
-export { bindingTypeValues as BindingType, Container, ContainerModule, inject as Inject, injectable as Injectable, LazyServiceIdentifier, multiInject as MultiInject, named as Named, Newable, optional as Optional, postConstruct as PostConstruct, preDestroy as PreDestroy, bindingScopeValues as ScopeBindingType, ServiceIdentifier, tagged as Tagged } from 'inversify';
-import { I as InjectableDescriptor } from './lib.js';
+import { ServiceIdentifier, LazyServiceIdentifier, Container, BindWhenOnFluentSyntax, Newable } from 'inversify';
+export { AbstractNewable, Bind, BindInFluentSyntax, BindInWhenOnFluentSyntax, BindOnFluentSyntax, BindToFluentSyntax, BindWhenFluentSyntax, BindWhenOnFluentSyntax, BindingActivation, BindingConstraints, BindingDeactivation, BindingIdentifier, BindingScope, bindingTypeValues as BindingType, BoundServiceSyntax, Container, ContainerModule, ContainerModuleLoadOptions, ContainerOptions, DynamicValueBuilder, Factory, GetAllOptions, GetOptions, GetOptionsTagConstraint, inject as Inject, injectFromBase as InjectFromBase, InjectFromBaseOptions, InjectFromBaseOptionsLifecycle, injectFromHierarchy as InjectFromHierarchy, InjectFromHierarchyOptions, InjectFromHierarchyOptionsLifecycle, injectable as Injectable, IsBound, IsBoundOptions, LazyServiceIdentifier, MapToResolvedValueInjectOptions, MetadataName, MetadataTag, multiInject as MultiInject, MultiInjectOptions, named as Named, Newable, optional as Optional, OptionalGetOptions, postConstruct as PostConstruct, preDestroy as PreDestroy, Rebind, RebindSync, ResolutionContext, ResolvedValueInjectOptions, ResolvedValueMetadataInjectOptions, ResolvedValueMetadataInjectTagOptions, bindingScopeValues as ScopeBindingType, ServiceIdentifier, tagged as Tagged, Unbind, UnbindSync, unmanaged as Unmanaged, bindingScopeValues, bindingTypeValues } from 'inversify';
+import { I as InjectableDescriptor, M as MaybePromise, O as Optional, A as AnyObject, S as SeedEntries, a as SeedKey } from './lib.js';
+export { b as SeedEntry, c as SeedsMap } from './lib.js';
 
+/**
+ * Util to resolve circular dependencies by wrapping the service identifier in a lazy identifier.
+ *
+ * @group External-inversify
+ * @see {@link https://inversify.io/}
+ *
+ * @param forward - A function that returns the service identifier.
+ * @returns A lazy service identifier.
+ */
 declare function forwardRef<TInstance = unknown>(forward: () => ServiceIdentifier<TInstance>): LazyServiceIdentifier<TInstance>;
 
+/**
+ * Binds a constant value to a service identifier in the container.
+ *
+ * @remarks
+ * Use this to register configuration values, primitive constants, or pre-instantiated objects.
+ * Constant values are bound with a singleton scope by default.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the service being bound.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Descriptor containing `id` (token) and `value` (constant).
+ * @returns Inversify fluent syntax for additional constraints.
+ *
+ * @throws {@link WirestateError} If `entry.scopeBindingType` is not `Singleton`.
+ *
+ * @example
+ * ```typescript
+ * const API_URL: unique symbol = Symbol("API_URL");
+ *
+ * bindConstant(container, {
+ *   id: API_URL,
+ *   value: "https://api.example.com"
+ * });
+ * ```
+ */
+declare function bindConstant<T>(container: Container, entry: InjectableDescriptor): BindWhenOnFluentSyntax<T>;
+
+/**
+ * Binds a dynamic value (factory-based) to an identifier in the container.
+ *
+ * @remarks
+ * Use this when the value depends on runtime state or requires logic during resolution.
+ * The binding uses `entry.factory` if provided; otherwise, it falls back to `entry.value`.
+ * Supports custom scoping via `entry.scopeBindingType`.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the value being bound.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Descriptor containing `id`, `factory` or `value`, and optional `scopeBindingType`.
+ * @returns Inversify fluent syntax for additional constraints.
+ *
+ * @example
+ * ```typescript
+ * const DATE_NOW: unique symbol = Symbol("DATE_NOW");
+ *
+ * bindDynamicValue(container, {
+ *   id: DATE_NOW,
+ *   factory: () => new Date()
+ * });
+ * ```
+ */
+declare function bindDynamicValue<T>(container: Container, entry: InjectableDescriptor): BindWhenOnFluentSyntax<T>;
+
+/**
+ * Represents options for {@link bindService}.
+ *
+ * @group Bind
+ */
 interface BindServiceOptions {
-    isWithIgnoreLifecycle?: boolean;
+    /**
+     * If true, suppresses execution of `@OnActivated` and `@OnDeactivation` methods.
+     * Messaging registrations (commands, queries, events) are still processed.
+     *
+     * @default false
+     */
+    readonly isWithIgnoreLifecycle?: boolean;
 }
 /**
- * Registers a service class in the container with activation/deactivation logic.
- * Ensures container references, event subscriptions, command and query handlers are managed correctly.
+ * Binds a service class in the {@link Container} with full lifecycle and messaging integration.
+ *
+ * @remarks
+ * Binds the class in singleton scope and configures Inversify activation/deactivation hooks to:
+ * - Manage the `IS_DISPOSED` lifecycle state flag.
+ * - Trigger `@OnActivated` and `@OnDeactivation` decorated methods.
+ * - Register/unregister `@OnCommand`, `@OnEvent` and `@OnQuery` handlers.
+ * - Set up event dispatching and bus subscriptions.
+ * - Track and dispose injected {@link WireScope} instances.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the service instance.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Service class constructor.
+ * @param options - Configuration options for the binding.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   @OnActivated()
+ *   public onActivated(): void {
+ *     console.log("UserService activated");
+ *   }
+ *
+ *   @OnDeactivation()
+ *   public onDeactivation(): void {
+ *     console.log("UserService deactivating");
+ *   }
+ *
+ *   @OnEvent("USER_LOGGED_IN")
+ *   private onUserLoggedIn(event: UserLoggedInEvent) {
+ *     console.log('User logged in:', event.payload);
+ *   }
+ *
+ *   @OnCommand("LOG_DATE_NOW")
+ *   private onLogDateNow(): void {
+ *     console.log("Date now:", new Date());
+ *   }
+ *
+ *   @OnQuery("DATE_NOW")
+ *   private onQueryDateNow(): void {
+ *     return new Date();
+ *   }
+ * }
  *
- * @param container - target Inversify container
- * @param entry - service constructor
- * @param options - options object to control binding flow
+ * bindService(container, UserService);
+ * ```
  */
 declare function bindService<T extends object>(container: Container, entry: Newable<T>, options?: BindServiceOptions): void;
 
 /**
- * Options for {@link bindEntry}.
+ * Represents options for {@link bindEntry}.
+ *
+ * @group Bind
  */
 interface BindEntryOptions extends BindServiceOptions {
-    isWithIgnoreLifecycle?: boolean;
+    /**
+     * If true, the service's lifecycle methods (like `@OnActivated`) will be ignored
+     * during the binding process.
+     *
+     * @default `false`
+     */
+    readonly isWithIgnoreLifecycle?: boolean;
 }
 /**
- * Binds a single service entry to the container, dispatching to the
- * correct binding strategy based on the descriptor's `type` field.
+ * Binds an entry to the Inversify {@link Container} using the appropriate strategy.
+ *
+ * @remarks
+ * This is a high-level dispatching function that selects the binding method based on the `entry` type:
+ * - **Class Constructor**: Binds as a singleton service via {@link bindService}.
+ * - **ConstantValue**: Binds a fixed value via {@link bindConstant}.
+ * - **DynamicValue**: Binds a factory-generated value via {@link bindDynamicValue}.
+ * - **Instance**: Binds a value as a class instance via {@link bindService}.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the object being bound.
+ *
+ * @param container - Target Inversify {@link Container}.
+ * @param entry - Class constructor or {@link InjectableDescriptor} describing the service.
+ * @param options - Optional binding configuration (primarily used for class-based services).
+ *
+ * @throws {@link WirestateError} If `entry.scopeBindingType` is not `Singleton` for constant values.
+ *
+ * @example
+ * ```typescript
+ * // Binding a class constructor (defaults to singleton)
+ * class MyService {}
  *
- * Supports:
- * - Service classes (function entries) - bound as singleton
- * - Constant values - bound via `bindConstant`
- * - Dynamic values - bound via `toDynamicValue` with optional scope
- * - Instance bindings - bound as generic singleton service
+ * bindEntry(container, MyService);
  *
- * @param container - target IOC container to bind into
- * @param entry - entry descriptor to bind
- * @param options - optional binding configuration
- * @returns void
+ * // Binding a constant value
+ * const API_URL: unique symbol = Symbol("API_URL");
+ *
+ * bindEntry(container, {
+ *   id: API_URL,
+ *   value: "https://api.example.com"
+ * });
+ *
+ * // Binding a dynamic value (factory)
+ * const CURRENT_TIME: unique symbol = Symbol("CURRENT_TIME");
+ *
+ * bindEntry(container, {
+ *   id: CURRENT_TIME,
+ *   bindingType: "DynamicValue",
+ *   factory: () => new Date()
+ * });
+ * ```
  */
 declare function bindEntry<T extends object = object>(container: Container, entry: Newable<T> | InjectableDescriptor, options?: BindEntryOptions): void;
 
 /**
- * Binds a constant value to a token in the container.
+ * Resolves the identifier for a given entry.
  *
- * @param container - target Inversify container
- * @param entry - entry descriptor to bind
- */
-declare function bindConstant<T>(container: Container, entry: InjectableDescriptor): void;
-
-/**
- * Returns the container token for a service entry.
- * For plain service classes the class itself is the token;
- * for descriptors the `id` field is used.
+ * @remarks
+ * Handles both plain service classes and injectable descriptors:
+ * - If `entry` is a class constructor, it is returned as the identifier.
+ * - If `entry` is an {@link InjectableDescriptor}, its `id` field is returned.
+ *
+ * @group Bind
+ *
+ * @template T - Type of the injectable object.
+ *
+ * @param entry - Class constructor or descriptor to get the identifier for.
+ * @returns Identifier token for Inversify.
  *
- * @param entry - entry descriptor to get service identifier for
- * @returns injectable identifier token
+ * @example
+ * ```typescript
+ * class MyService {}
+ *
+ * getEntryToken(MyService); // returns MyService
+ *
+ * getEntryToken({ id: "my-service" }); // returns "my-service"
+ * ```
  */
 declare function getEntryToken<T extends object = object>(entry: Newable<T> | InjectableDescriptor): ServiceIdentifier;
 
-type AnyObject = Record<string, any>;
-type Optional<T> = T | null;
-type MaybePromise<T> = T | Promise<T>;
-
 /**
- * Command identifier. Use symbols for private commands.
+ * Represents identifier used to dispatch and handle commands.
+ *
+ * @remarks
+ * Use strings for public commands and symbols for private/scoped commands to avoid name collisions.
+ *
+ * @group Commands
+ *
+ * @example
+ * ```typescript
+ * const PUBLIC_COMMAND: CommandType = "USER/LOGIN";
+ *
+ * const PRIVATE_COMMAND: CommandType = Symbol("INTERNAL/SYNC");
+ *
+ * enum CounterCommand {
+ *   INCREMENT = "COUNTER/INCREMENT",
+ *   DECREMENT = "COUNTER/DECREMENT",
+ * }
+ * ```
  */
 type CommandType = string | symbol;
 /**
- * Command handler signature.
+ * Represents function signature for handling command execution.
+ *
+ * @group Commands
+ *
+ * @template D - Type of the input payload (data) for the command.
+ * @template R - Type of the result returned by the handler (can be wrapped in a Promise).
+ *
+ * @example
+ * ```typescript
+ * const loginHandler: CommandHandler<Credentials, Session> = (payload) => {
+ *   return auth.login(payload);
+ * };
+ * ```
  */
-type CommandHandler<D = unknown, R = unknown> = (data: D) => MaybePromise<R>;
+type CommandHandler<D = unknown, R = unknown> = (payload: D) => MaybePromise<R>;
 /**
- * Removes a command handler.
+ * Represents function returned when a command handler is registered.
+ * Calling this function removes the handler from the command bus.
+ *
+ * @group Commands
+ *
+ * @example
+ * ```typescript
+ * const unregister: CommandUnregister = commandBus.register("MY_COMMAND", handler);
+ *
+ * unregister();
+ * ```
  */
 type CommandUnregister = () => void;
 /**
- * Command execution status.
+ * Represents the current state of a command execution.
+ *
+ * @group Commands
  */
 declare enum CommandStatus {
+    /** The command task has started but not yet completed. */
     PENDING = "pending",
+    /** The command task has successfully completed. */
     SETTLED = "settled",
+    /** The command task failed with an error. */
     ERROR = "error"
 }
 /**
- * Descriptor returned by command execution.
- * Contains the task promise, current status, and responder with result/error.
+ * Represents a handle to an executing command.
+ *
+ * @remarks
+ * Returned by the command bus when a command is dispatched. It allows tracking
+ * the progress and outcome of the command execution.
+ *
+ * @group Commands
+ *
+ * @template R - Type of the result produced by the command.
  */
 interface CommandDescriptor<R = unknown> {
+    /**
+     * A promise that resolves with the command result or rejects with an error.
+     */
     readonly task: Promise<R>;
+    /**
+     * The current execution status of the command.
+     */
     readonly status: CommandStatus;
 }
 
 /**
- * Dispatches a command on the provided container.
+ * Dispatches a command through the {@link CommandBus} resolved from the container.
+ *
+ * @remarks
+ * This is a convenience wrapper around the `CommandBus.command` method.
+ * Commands allow for decoupled communication between services.
  *
- * @param container - inversify container
- * @param type - command type
- * @param data - command data
- * @returns command descriptor
+ * @group Commands
+ *
+ * @template R - Type of the expected result from the command execution.
+ * @template D - Type of the data (payload) passed to the command.
+ * @template T - Type of the command identifier.
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link CommandBus} from.
+ * @param type - Unique identifier of the command to dispatch.
+ * @param data - Optional payload for the command handler.
+ * @returns A descriptor to track the command execution and result.
+ *
+ * @example
+ * ```typescript
+ * const descriptor = command<User, UserFindParameters>(
+ *   container,
+ *   "FIND_USER",
+ *   { id: "123" }
+ * );
+ *
+ * const user: User = await descriptor.task;
+ * ```
  */
 declare function command<R = unknown, D = unknown, T extends CommandType = CommandType>(container: Container, type: T, data?: D): CommandDescriptor<R>;
 
 /**
- * Dispatches a command on the provided container, returning null if no handler is registered.
+ * Dispatches a command through the {@link CommandBus} resolved from the container, returning null if no handler exists.
+ *
+ * @remarks
+ * This is a convenience wrapper around the `CommandBus.commandOptional` method.
+ * Unlike {@link command}, it does not throw if no handler is registered.
  *
- * @param container - inversify container
- * @param type - command type
- * @param data - command data
- * @returns command descriptor or null
+ * @group Commands
+ *
+ * @template R - Type of the expected result from the command execution.
+ * @template D - Type of the data (payload) passed to the command.
+ * @template T - Type of the command identifier.
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link CommandBus} from.
+ * @param type - Unique identifier of the command to dispatch.
+ * @param data - Optional payload for the command handler.
+ * @returns A {@link CommandDescriptor} if a handler was found, or `null` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const descriptor = commandOptional<User, FindUserOptions>(
+ *   container,
+ *   "FIND_USER",
+ *   { id: "123" }
+ * );
+ *
+ * if (descriptor) {
+ *   const user: User = await descriptor.task;
+ * }
+ * ```
  */
 declare function commandOptional<R = unknown, D = unknown, T extends CommandType = CommandType>(container: Container, type: T, data?: D): Optional<CommandDescriptor<R>>;
 
 /**
- * Decorator for service methods that handle a command.
+ * Decorator for service methods that handle a specific command.
+ *
+ * @remarks
+ * Methods decorated with `@OnCommand` are automatically registered as command handlers
+ * when the service is bound via {@link bindService}.
  *
- * @param type - command type identifier
- * @returns decorator function
+ * @group Commands
+ *
+ * @param type - Unique identifier of the command to handle.
+ * @returns A method decorator function.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @OnCommand("USER_LOGIN")
+ *   private onUserLogin(credentials: Credentials): Promise<Session> {
+ *     return auth.login(credentials);
+ *   }
+ * }
+ * ```
  */
 declare function OnCommand(type: CommandType): MethodDecorator;
 
 /**
- * Dispatches commands to handlers.
+ * Orchestrates command dispatching and handler registration.
  *
- * Unlike queries, command execution always wraps the handler in a promise
- * and returns a descriptor with task, status, and responder.
+ * @remarks
+ * The `CommandBus` provides a way to decouple command dispatchers from their handlers.
+ * It supports handler shadowing: when multiple handlers are registered for the same type,
+ * the last registered one takes priority.
+ *
+ * @group Commands
  */
 declare class CommandBus {
     /**
@@ -132,70 +417,163 @@ declare class CommandBus {
      */
     private readonly handlers;
     /**
-     * Registers a command handler.
-     * Returns an unregister function.
-     *
-     * @param type - command type
-     * @param handler - handler function
-     * @returns unregister function
+     * Removes all registered command handlers from the bus.
      */
-    register<D = unknown, R = unknown>(type: CommandType, handler: CommandHandler<D, R>): CommandUnregister;
+    clear(): void;
     /**
      * Dispatches a command to the last registered handler.
-     * Wraps the handler execution in a promise and returns a descriptor.
      *
-     * @param type - command type
-     * @param data - command payload
-     * @returns command descriptor with task, status, and responder
+     * @remarks
+     * Execution is always asynchronous. The handler's return value is wrapped in a Promise.
+     * Returns a {@link CommandDescriptor} that tracks the execution status and task.
+     *
+     * @template R - Type of the command result.
+     * @template D - Type of the command payload data.
+     *
+     * @param type - Command identifier.
+     * @param data - Optional payload for the handler.
+     * @returns A descriptor for the executing command.
+     *
+     * @throws {@link WirestateError} If no handler is registered.
      *
-     * @throws if no handler is registered
+     * @example
+     * ```typescript
+     * const descriptor: CommandDescriptor<User> = commandBus.command<User, string>("GET_USER", "id-123");
+     * const user: User = await descriptor.task;
+     * ```
      */
     command<R = unknown, D = unknown>(type: CommandType, data?: D): CommandDescriptor<R>;
     /**
-     * Dispatches a command to the last registered handler, returning null if no handler exists.
+     * Dispatches a command if a handler exists, otherwise returns null.
      *
-     * @param type - command type
-     * @param data - command payload
-     * @returns command descriptor or null if no handler is registered
+     * @template R - Type of the command result.
+     * @template D - Type of the command payload data.
+     *
+     * @param type - Command identifier.
+     * @param data - Optional payload for the handler.
+     * @returns A command descriptor, or `null` if no handler is found.
      */
     commandOptional<R = unknown, D = unknown>(type: CommandType, data?: D): Optional<CommandDescriptor<R>>;
     /**
-     * Checks if a handler is registered for the given type.
+     * Checks if at least one handler is registered for the given command type.
      *
-     * @param type - command type
-     * @returns true if handler exists
+     * @param type - Command identifier.
+     * @returns `true` if a handler is available, `false` otherwise.
      */
     has(type: CommandType): boolean;
     /**
-     * Removes all registered handlers.
+     * Registers a handler for a specific command type.
+     *
+     * @remarks
+     * If multiple handlers are registered for the same type, they are stored in a stack.
+     * The most recently registered handler will be used for dispatching.
+     *
+     * @template D - Type of the command payload data.
+     * @template R - Type of the command execution result.
+     *
+     * @param type - Command identifier.
+     * @param handler - Function to execute when the command is dispatched.
+     * @returns A function to unregister the handler.
+     *
+     * @example
+     * ```typescript
+     * const unregister: CommandUnregister = commandBus.register("LOG_MESSAGE", (message: string) => {
+     *   console.log(message);
+     * });
+     * ```
+     */
+    register<D = unknown, R = unknown>(type: CommandType, handler: CommandHandler<D, R>): CommandUnregister;
+    /**
+     * Removes a previously registered command handler.
+     *
+     * @remarks
+     * If the handler was not registered for the given type, this operation does nothing.
+     *
+     * @template D - Type of the command payload data.
+     * @template R - Type of the command execution result.
+     *
+     * @param type - Command identifier.
+     * @param handler - The handler function instance to remove.
      */
-    clear(): void;
+    unregister<D = unknown, R = unknown>(type: CommandType, handler: CommandHandler<D, R>): void;
 }
 
-interface CreateIocContainerOptions {
+/**
+ * Represents configuration options for {@link createContainer}.
+ *
+ * @group Container
+ */
+interface CreateContainerOptions {
     /**
-     * Parent container for inheritance.
+     * Optional parent container.
+     * Enables hierarchical resolution and sharing of bindings.
      */
     readonly parent?: Container;
     /**
-     * Optional default seed value.
+     * Initial data for the root seed.
+     * Accessible via {@link WireScope.getSeed}() in services.
      */
     readonly seed?: AnyObject;
+    /**
+     * Targeted seeds bound to specific injectables or tokens.
+     */
+    readonly seeds?: SeedEntries;
+    /**
+     * Injectables to be bound to the container.
+     *
+     * @remarks
+     * Supports class constructors and {@link InjectableDescriptor} configurations.
+     */
+    readonly entries?: ReadonlyArray<Newable<object> | InjectableDescriptor>;
+    /**
+     * Services to resolve immediately.
+     *
+     * @remarks
+     * Listed services must also be present in the `entries` array.
+     */
+    readonly activate?: ReadonlyArray<ServiceIdentifier>;
 }
 /**
- * Creates an IoC container with framework essentials.
+ * Creates an Inversify IoC container pre-configured with Wirestate essentials.
  *
- * @param options - container configuration
- * @returns new IoC container
+ * @remarks
+ * The container is initialized with:
+ * - State management tokens: `SEEDS_TOKEN` and `SEED_TOKEN`.
+ * - Messaging buses: {@link EventBus}, {@link QueryBus}, {@link CommandBus}.
+ * - Service bridge: {@link WireScope} (bound in transient scope).
+ * - Default scope set to `Singleton`.
+ *
+ * @group Container
+ *
+ * @param options - {@link CreateContainerOptions} configuration.
+ * @returns A new Inversify {@link Container} instance.
+ *
+ * @example
+ * ```typescript
+ * const container: Container = createIocContainer({
+ *   seeds: [
+ *     [CounterService, { count: 1000 }],
+ *     ["SOME_KEY", "VALUE"],
+ *   ],
+ *   entries: [CounterService, LoggerService],
+ *   activate: [LoggerService]
+ * });
+ *
+ * bindService(container, MyService);
+ * ```
  */
-declare function createIocContainer(options?: CreateIocContainerOptions): Container;
+declare function createContainer(options?: CreateContainerOptions): Container;
 
 /**
- * Event identifier.
+ * Represents an Event identifier.
+ *
+ * @group Events
  */
 type EventType = string | symbol;
 /**
- * Event object.
+ * Represents an event object.
+ *
+ * @group Events
  */
 interface Event<P = unknown, T extends EventType = EventType, F = unknown> {
     readonly type: T;
@@ -203,44 +581,75 @@ interface Event<P = unknown, T extends EventType = EventType, F = unknown> {
     readonly from?: F;
 }
 /**
- * Event handler signature.
+ * Represents event handler signature.
+ *
+ * @group Events
  */
 type EventHandler<E extends Event = Event> = (event: E) => void;
 /**
- * Unsubscribes from events, part of events subscription lifecycle.
+ * Represents event bus unsubscribing function, part of events subscription lifecycle.
+ *
+ * @group Events
  */
 type EventUnsubscriber = () => void;
 
 /**
- * Lookup key for service seeds.
- */
-type SeedKey = Newable | string | symbol;
-/**
- * Service-to-seed mapping entry.
- */
-type SeedEntry<T = unknown> = readonly [SeedKey, T];
-/**
- * Collection of seed entries.
- */
-type SeedEntries = ReadonlyArray<SeedEntry>;
-
-/**
- * Query identifier. Use symbols for private queries.
+ * Represents unique identifier for a query.
+ *
+ * @remarks
+ * Queries use a request-response pattern. Using symbols is recommended for
+ * private or internal queries to avoid naming collisions.
+ *
+ * @group Queries
+ *
+ * @example
+ * ```typescript
+ * const GET_USER_QUERY: QueryType = Symbol("GET_USER");
+ * ```
  */
 type QueryType = string | symbol;
 /**
- * Query handler signature.
+ * Represents signature for a function that handles queries of a specific type.
+ *
+ * @remarks
+ * Query handlers can be synchronous or asynchronous. They receive a payload
+ * and must return a result (or a Promise resolving to it).
+ *
+ * @group Queries
+ *
+ * @template D - Type of the input data (payload).
+ * @template R - Type of the returned result.
+ *
+ * @example
+ * ```typescript
+ * const handler: QueryHandler<string, User> = (userId) => userRepository.find(userId);
+ * ```
  */
 type QueryHandler<D = unknown, R = unknown> = (data: D) => MaybePromise<R>;
 /**
- * Removes a query handler.
+ * Represents function returned by registration methods to remove a query handler.
+ *
+ * @group Queries
+ *
+ * @example
+ * ```typescript
+ * const unregister: QueryUnregister = queryBus.register("QUERY_TYPE", handler);
+ *
+ * unregister(); // Handler is no longer active
+ * ```
  */
 type QueryUnregister = () => void;
 
 /**
- * Injectable scope providing access to wirestate buses and seeds.
- * Each injecting service receives its own instance (transient scope).
- * The scope is activated and deactivated automatically alongside its owner service.
+ * A transient bridge providing services with access to Wirestate buses, lazy resolution, and seeds.
+ *
+ * @remarks
+ * Every service bound via {@link bindService} receives its own unique `WireScope` instance.
+ * It acts as a facade to the IoC container while enforcing lifecycle safety.
+ *
+ * Methods are available only while the scope is "active" (after service activation and before deactivation).
+ *
+ * @group Container
  */
 declare class WireScope {
     private readonly container;
@@ -250,152 +659,471 @@ declare class WireScope {
     readonly isDisposed: boolean;
     constructor(container: Optional<Container>);
     /**
-     * Access the IoC container.
-     * Available only for activated instances of scope.
+     * Provides direct access to the underlying Inversify {@link Container}.
+     *
+     * @returns The active {@link Container}.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
      *
-     * @returns active container
+     * @example
+     * ```typescript
+     * const container: Container = scope.getContainer();
      *
-     * @throws WirestateError if scope is not activated or already disposed
+     * container.bind("TOKEN").toConstantValue(42);
+     * ```
      */
     getContainer(): Container;
     /**
-     * Resolves a sibling service or injected value.
-     * Use for lazy resolution or circular dependency breaking.
-     * Available only for activated containers.
+     * Lazily resolves a service or value from the container.
+     *
+     * @remarks
+     * Use this to break circular dependencies or for services that are not needed immediately.
+     *
+     * @template T - Type of the service or value to resolve.
      *
-     * @param injectionId - injection identifier
-     * @returns resolved injection, service instance, or generic value
+     * @param injectionId - Service token (class constructor, symbol, or string).
+     * @returns The resolved instance or value.
      *
-     * @throws WirestateError if scope is not activated
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     * @throws {Error} If the service cannot be resolved from the container.
+     *
+     * @example
+     * ```typescript
+     * const service: MyService = scope.resolve(MyService);
+     * ```
      */
     resolve<T>(injectionId: ServiceIdentifier<T>): T;
     /**
-     * Resolves a sibling service or injected value.
-     * Use for lazy resolution or circular dependency breaking.
-     * Available only for activated containers.
+     * Lazily resolves a service if it is bound, otherwise returns null.
+     *
+     * @template T - Type of the service or value to resolve.
+     *
+     * @param injectionId - Service token (class constructor, symbol, or string).
+     * @returns The resolved instance, value, or `null` if not bound.
      *
-     * @param injectionId - injection identifier
-     * @returns resolved injection, service instance, generic value, or null if it is not bound
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
      *
-     * @throws WirestateError if scope is not activated
+     * @example
+     * ```typescript
+     * const logger: Logger | null = scope.resolveOptional(Logger);
+     *
+     * logger?.info("Resolved optionally");
+     * ```
      */
     resolveOptional<T>(injectionId: ServiceIdentifier<T>): Optional<T>;
     /**
-     * Broadcasts an event.
-     * Available only for activated containers.
+     * Dispatches an event to the {@link EventBus}.
+     *
+     * @template P - Type of the event payload.
+     * @template T - Type of the event identifier.
      *
-     * @param type - type of event to emit
-     * @param payload - optional payload to send with the event
-     * @param from - optional sender of the event
+     * @param type - Event identifier.
+     * @param payload - Optional data associated with the event.
+     * @param from - Optional source identifier (defaults to current scope).
      *
-     * @throws WirestateError if scope is not activated
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * scope.emitEvent("VALUE_CHANGED", { value: "abcd" });
+     * ```
      */
     emitEvent<P, T extends EventType = EventType>(type: T, payload?: P, from?: unknown): void;
     /**
-     * Dispatches a query and returns the result.
-     * Available only for activated containers.
+     * Subscribes to all events on the {@link EventBus}.
+     *
+     * @param handler - Function called for every emitted event.
+     * @returns A function to unsubscribe.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe: EventUnsubscriber = scope.subscribeToEvent((event) => {
+     *   console.log("Event received:", event);
+     * });
+     * ```
+     */
+    subscribeToEvent(handler: EventHandler): EventUnsubscriber;
+    /**
+     * Unsubscribes a specific handler from the {@link EventBus}.
+     *
+     * @param handler - The handler instance to remove.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * scope.unsubscribeFromEvent(this.onEvent);
+     * ```
+     */
+    unsubscribeFromEvent(handler: EventHandler): void;
+    /**
+     * Dispatches a query and waits for the result.
+     *
+     * @template R - Type of the query result.
+     * @template D - Type of the query data (payload).
+     * @template T - Type of the query identifier.
      *
-     * @param type - query type
-     * @param data - query data
-     * @returns query result
+     * @param type - Query identifier.
+     * @param data - Input data for the query handler.
+     * @returns The query result (can be a Promise).
      *
-     * @throws WirestateError if scope is not activated
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     * @throws {@link WirestateError} If no query handler is registered.
+     *
+     * @example
+     * ```typescript
+     * const user: User = await scope.queryData("GET_USER", { id: 1 });
+     * ```
      */
     queryData<R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D): MaybePromise<R>;
     /**
-     * Dispatches a query and returns the result.
-     * Available only for activated containers.
+     * Dispatches a query and returns the result, or null if no handler is registered.
+     *
+     * @template R - Type of the query result.
+     * @template D - Type of the query data (payload).
+     * @template T - Type of the query identifier.
      *
-     * @param type - query type
-     * @param data - query data
-     * @returns query result or null if handler is not registered
+     * @param type - Query identifier.
+     * @param data - Input data for the query handler.
+     * @returns The query result or `null`.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * const config: Config | null = await scope.queryOptionalData("GET_CONFIG");
+     * ```
      */
     queryOptionalData<R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D): Optional<MaybePromise<R>>;
     /**
-     * Dispatches a command and returns the descriptor.
-     * Available only for activated containers.
+     * Registers a handler for a specific query type.
+     *
+     * @template D - Type of the query data (payload).
+     * @template R - Type of the query result.
      *
-     * @param type - command type
-     * @param data - command data
-     * @returns command descriptor
+     * @param type - Query identifier.
+     * @param handler - The handler function.
+     * @returns A function to unregister the handler.
      *
-     * @throws WirestateError if scope is not activated
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * scope.registerQueryHandler("GET_DATE_NOW", () => new Date());
+     * ```
+     */
+    registerQueryHandler<D = unknown, R = unknown>(type: QueryType, handler: QueryHandler<D, R>): QueryUnregister;
+    /**
+     * Removes a specific query handler registration.
+     *
+     * @template D - Type of the query data (payload).
+     * @template R - Type of the query result.
+     *
+     * @param type - Query identifier.
+     * @param handler - The handler instance to remove.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * scope.unregisterQueryHandler("GET_DATE_NOW", this.onGetDateNow);
+     * ```
+     */
+    unregisterQueryHandler<D = unknown, R = unknown>(type: QueryType, handler: QueryHandler<D, R>): void;
+    /**
+     * Dispatches a command and returns a descriptor to track its progress.
+     *
+     * @template R - Type of the command result.
+     * @template D - Type of the command payload.
+     * @template T - Type of the command identifier.
+     *
+     * @param type - Command identifier.
+     * @param data - Payload for the command.
+     * @returns A {@link CommandDescriptor}.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     * @throws {@link WirestateError} If no command handler is registered.
+     *
+     * @example
+     * ```typescript
+     * const descriptor: CommandDescriptor = scope.executeCommand("LOGOUT");
+     *
+     * await descriptor.task;
+     * ```
      */
     executeCommand<R = unknown, D = unknown, T extends CommandType = CommandType>(type: T, data?: D): CommandDescriptor<R>;
     /**
-     * Dispatches a command and returns the descriptor.
-     * Available only for activated containers.
+     * Dispatches a command if a handler is registered, otherwise returns null.
+     *
+     * @template R - Type of the command result.
+     * @template D - Type of the command payload.
+     * @template T - Type of the command identifier.
+     *
+     * @param type - Command identifier.
+     * @param data - Payload for the command.
+     * @returns A {@link CommandDescriptor} or `null`.
      *
-     * @param type - command type
-     * @param data - command data
-     * @returns command descriptor or null if handler is not registered
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * const descriptor: CommandDescriptor | null = scope.executeOptionalCommand("CLEANUP_CACHE");
+     *
+     * if (descriptor) {
+     *   await descriptor.task;
+     * }
+     * ```
      */
     executeOptionalCommand<R = unknown, D = unknown, T extends CommandType = CommandType>(type: T, data?: D): Optional<CommandDescriptor<R>>;
-    getSeed<T>(): T;
-    getSeed<T>(seed?: SeedKey): Optional<T>;
+    /**
+     * Registers a handler for a specific command type.
+     *
+     * @template D - Type of the command payload.
+     * @template R - Type of the command result.
+     *
+     * @param type - Command identifier.
+     * @param handler - The handler function.
+     * @returns A function to unregister the handler.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * scope.registerCommandHandler("LOG_ERROR", (error) => {
+     *   console.error(error);
+     * });
+     * ```
+     */
+    registerCommandHandler<D = unknown, R = unknown>(type: CommandType, handler: CommandHandler<D, R>): CommandUnregister;
+    /**
+     * Removes a specific command handler registration.
+     *
+     * @template D - Type of the command payload.
+     * @template R - Type of the command result.
+     *
+     * @param type - Command identifier.
+     * @param handler - The handler instance to remove.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * scope.unregisterCommandHandler("LOG_ERROR", this.handleLogError);
+     * ```
+     */
+    unregisterCommandHandler<D = unknown, R = unknown>(type: CommandType, handler: CommandHandler<D, R>): void;
+    /**
+     * Retrieves the global seed object (initial state) from the container.
+     *
+     * @remarks
+     * Use this to access the entire seed object when no specific key is provided.
+     *
+     * @template T - Expected type of the global seed object.
+     * @returns The global seed object.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * interface GlobalSeed {
+     *   apiUrl: string;
+     * }
+     *
+     * const seeds: GlobalSeed = scope.getSeed();
+     * ```
+     */
+    getSeed<T extends AnyObject>(): T;
+    /**
+     * Retrieves a specific seed value by key from the container's seed map.
+     *
+     * @remarks
+     * Use this to retrieve individual values registered in the seed map.
+     *
+     * @template T - Expected type of the seed value.
+     * @param seed - Lookup key (identifier or token) for the seed.
+     * @returns The seed value or `null` if not found.
+     *
+     * @throws {@link WirestateError} If accessed before activation or after disposal.
+     *
+     * @example
+     * ```typescript
+     * const apiUrl: string = scope.getSeed("API_URL");
+     * ```
+     */
+    getSeed<T>(seed: SeedKey): Optional<T>;
 }
 
 /**
- * A custom error class that contains generic error information for Wirestate-related issues.
+ * Base error class for all Wirestate-related exceptions.
+ *
+ * @remarks
+ * `WirestateError` provides structured error information, including a numeric error code
+ * and a descriptive message. It is used throughout the library to signal lifecycle
+ * violations, messaging failures, and configuration issues.
  *
- * This class extends the native `Error` class and is used to represent errors specific
- * to the Wirestate library, providing more structured error handling.
+ * @group Error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   scope.getContainer();
+ * } catch (error) {
+ *   if (error instanceof WirestateError) {
+ *     console.error(`Error code: ${error.code}`);
+ *   }
+ * }
+ * ```
  */
 declare class WirestateError extends Error {
     /**
-     * Name or error class to help differentiate error class in minified environments.
+     * The name of the error class, useful for identification in minified environments.
      */
     readonly name: string;
     /**
-     * Error code describing the issue.
+     * Numeric error code identifying the specific failure type.
      */
     readonly code: number;
     /**
-     * Error message describing the issue.
+     * Human-readable description of the error.
      */
     readonly message: string;
+    /**
+     * Creates a new instance of WirestateError.
+     *
+     * @param code - Numeric identifier for the error (defaults to ERROR_CODE_GENERIC).
+     * @param detail - Optional descriptive message.
+     */
     constructor(code?: number, detail?: string);
 }
 
 /**
- * Emits events for container from outside scope.
+ * Broadcasts an event to all subscribers via the {@link EventBus} resolved from the container.
  *
- * @param container - inversify container
- * @param type - event type ot emit
- * @param payload - event payload
- * @param from - optional indicator of the event source
+ * @remarks
+ * Use this utility to emit events from outside a service's {@link WireScope} (e.g., from a bootstrap script or external controller).
+ *
+ * @group Events
+ *
+ * @template P - Type of the event payload.
+ * @template T - Type of the event identifier.
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link EventBus} from.
+ * @param type - Unique event identifier.
+ * @param payload - Optional data associated with the event.
+ * @param from - Optional source identifier.
+ *
+ * @example
+ * ```typescript
+ * emitEvent(container, "SYSTEM_READY", { version: "1.0.0" });
+ * ```
  */
 declare function emitEvent<P, T extends EventType>(container: Container, type: T, payload?: P, from?: unknown): void;
 
 /**
  * Decorator for service methods that respond to events.
  *
- * @param types - event type(s) to handle. If omitted, handles all events
- * @returns decorator function
+ * @remarks
+ * Methods decorated with `@OnEvent` are automatically registered as subscribers
+ * when the service is bound via {@link bindService}.
+ *
+ * You can specify one or more event types to handle. If `types` is omitted,
+ * the method acts as a catch-all handler for all events broadcasted to the {@link EventBus}.
+ *
+ * @group Events
+ *
+ * @param types - Event identifier(s) to handle. If omitted, handles all events.
+ * @returns Method decorator.
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @OnEvent("USER_LOGGED_IN")
+ *   private onLogin(event: Event<User>): void {
+ *     console.log("User logged in:", event);
+ *   }
+ *
+ *   @OnEvent(["LOGOUT", "SESSION_EXPIRED"])
+ *   private onSessionEnd(event: Event): void {
+ *     console.log("Specific event received:", event);
+ *   }
+ *
+ *   @OnEvent()
+ *   private onAnyEvent(event: Event): void {
+ *     // Catch-all handler
+ *   }
+ * }
+ * ```
  */
 declare function OnEvent(types?: EventType | ReadonlyArray<EventType>): MethodDecorator;
 
 /**
- * Dispatches events to subscribers.
+ * Orchestrates event broadcasting to multiple subscribers.
+ *
+ * @remarks
+ * The `EventBus` facilitates decoupled, many-to-many communication.
+ * Unlike commands or queries, which are dispatched to a single handler,
+ * events are broadcast to all registered subscribers.
+ *
+ * @group Events
  */
 declare class EventBus {
     private readonly handlers;
     /**
-     * Broadcasts an event to all subscribers.
+     * Broadcasts an event to all registered subscribers.
+     *
+     * @remarks
+     * Handlers are executed in a try-catch block to ensure that a single
+     * failing subscriber does not prevent others from receiving the event.
+     *
+     * @template P - Type of the event payload.
+     * @template T - Type of the event identifier.
+     * @template F - Type of the event source.
+     *
+     * @param event - The event object to broadcast.
      *
-     * @param event - event to emit
+     * @example
+     * ```typescript
+     * eventBus.emit({
+     *   type: "USER_LOGGED_IN",
+     *   payload: { userId: "123" },
+     *   from: AuthService
+     * });
+     * ```
      */
     emit<P = unknown, T extends EventType = EventType, F = unknown>(event: Event<P, T, F>): void;
     /**
-     * Subscribes a handler to all events.
-     * Returns an unsubscribe function.
+     * Registers a handler to receive all broadcasted events.
      *
-     * @param handler - event handler function
-     * @returns unsubscribe function
+     * @param handler - Function invoked for every emitted event.
+     * @returns An {@link EventUnsubscriber} function to remove the subscription.
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe: EventUnsubscriber = eventBus.subscribe((event) => {
+     *   console.log('Received event:', event);
+     * });
+     * ```
      */
     subscribe(handler: EventHandler): EventUnsubscriber;
     /**
-     * Removes all registered handlers.
+     * Removes a previously registered event handler.
+     *
+     * @remarks
+     * If the handler was not subscribed, this operation does nothing.
+     *
+     * @param handler - The handler function instance to remove.
+     */
+    unsubscribe(handler: EventHandler): void;
+    /**
+     * Checks if the bus has any active subscribers.
+     *
+     * @returns `true` if at least one handler is registered, `false` otherwise.
+     */
+    has(): boolean;
+    /**
+     * Removes all registered handlers from the bus.
      *
      * @internal
      */
@@ -403,27 +1131,69 @@ declare class EventBus {
 }
 
 /**
- * Dispatches a query on the provided container.
+ * Dispatches a query through the {@link QueryBus} resolved from the container.
+ *
+ * @remarks
+ * This is a convenience wrapper around the `QueryBus.query` method.
+ * Queries allow for decoupled request-response communication between services.
+ *
+ * @group Queries
+ *
+ * @template R - Type of the expected query result.
+ * @template D - Type of the input data (payload).
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link QueryBus} from.
+ * @param type - Unique query identifier.
+ * @param data - Optional input data for the query handler.
+ * @returns The query result (can be a Promise).
+ *
+ * @throws {@link WirestateError} If no query handler is registered.
  *
- * @param container - inversify container
- * @param type - query type
- * @param data - query data
- * @returns query result
+ * @example
+ * ```typescript
+ * const result: string = await query<string, FindUserParameters>(
+ *   container,
+ *   "GET_USER_NAME",
+ *   { id: 123 }
+ * );
+ * ```
  */
 declare function query<R = unknown, D = unknown>(container: Container, type: QueryType, data?: D): MaybePromise<R>;
 
 /**
- * Dispatches a query on the provided container, returning null if no handler is registered.
+ * Dispatches a query through the {@link QueryBus}, returning null if no handler is registered.
  *
- * @param container - inversify container
- * @param type - query type
- * @param data - query data
- * @returns query result or null
+ * @remarks
+ * This is a convenience wrapper around the `QueryBus.queryOptional` method.
+ * Use this when the query resolution is optional and you want to avoid catching errors.
+ *
+ * @group Queries
+ *
+ * @template R - Type of the expected query result.
+ * @template D - Type of the input data (payload).
+ *
+ * @param container - Inversify {@link Container} to resolve the {@link QueryBus} from.
+ * @param type - Unique query identifier.
+ * @param data - Optional input data for the query handler.
+ * @returns The query result or `null` if no handler exists.
+ *
+ * @example
+ * ```typescript
+ * const config: Config | null = await queryOptional<Config>(container, "GET_OPTIONAL_CONFIG");
+ * ```
  */
 declare function queryOptional<R = unknown, D = unknown>(container: Container, type: QueryType, data?: D): Optional<MaybePromise<R>>;
 
 /**
- * Dispatches queries to handlers.
+ * Orchestrates query dispatching and handler registration.
+ *
+ * @remarks
+ * The `QueryBus` provides a request-response mechanism for decoupled communication.
+ * It supports handler shadowing: when multiple handlers are registered for the same type,
+ * the last registered one (e.g., at the component level) takes priority over earlier ones
+ * (e.g., at the global service level).
+ *
+ * @group Queries
  */
 declare class QueryBus {
     /**
@@ -432,41 +1202,82 @@ declare class QueryBus {
      */
     private readonly handlers;
     /**
-     * Registers a query handler.
-     * Returns an unregister function.
+     * Registers a handler for a specific query type.
+     *
+     * @remarks
+     * If multiple handlers are registered for the same type, they are stored in a stack.
+     * The most recently registered handler will be used for resolution.
+     *
+     * @template D - Type of the query input data.
+     * @template R - Type of the query result.
+     *
+     * @param type - Unique query identifier.
+     * @param handler - Function to execute when the query is dispatched.
+     * @returns A function to unregister the handler.
      *
-     * @param type - query type
-     * @param handler - handler function
-     * @returns unregister function
+     * @example
+     * ```typescript
+     * const unregister: QueryUnregister = queryBus.register("GET_NOW", () => Date.now());
+     * ```
      */
     register<D = unknown, R = unknown>(type: QueryType, handler: QueryHandler<D, R>): QueryUnregister;
     /**
-     * Dispatches a query to the last registered handler.
+     * Removes a previously registered query handler.
      *
-     * @param type - query type
-     * @param data - query payload
-     * @returns query result
+     * @remarks
+     * If the handler was not registered for the given type, this operation does nothing.
      *
-     * @throws if no handler is registered
+     * @template D - Type of the query input data.
+     * @template R - Type of the query result.
+     *
+     * @param type - Unique query identifier.
+     * @param handler - The handler function instance to remove.
+     */
+    unregister<D = unknown, R = unknown>(type: QueryType, handler: QueryHandler<D, R>): void;
+    /**
+     * Dispatches a query to the last registered handler and returns the result.
+     *
+     * @remarks
+     * Query handlers can be synchronous or asynchronous. The result is returned as-is
+     * (or as a Promise if the handler is async).
+     *
+     * @template R - Type of the expected query result.
+     * @template D - Type of the data (payload) passed to the query.
+     * @template T - Type of the query identifier.
+     *
+     * @param type - Unique query identifier.
+     * @param data - Optional input data for the handler.
+     * @returns The result of the query execution.
+     *
+     * @throws {@link WirestateError} If no handler is registered for the given type.
+     *
+     * @example
+     * ```typescript
+     * const user: User = await queryBus.query<User, string>("FIND_USER", "user-id-123");
+     * ```
      */
     query<R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D): MaybePromise<R>;
     /**
-     * Dispatches a query to the last registered handler, returning null if no handler exists.
+     * Dispatches a query if a handler exists, otherwise returns null.
      *
-     * @param type - query type
-     * @param data - query payload
-     * @returns query result or null if no handler is registered
+     * @template R - Type of the expected query result.
+     * @template D - Type of the data (payload) passed to the query.
+     * @template T - Type of the query identifier.
+     *
+     * @param type - Unique query identifier.
+     * @param data - Optional input data for the handler.
+     * @returns The query result, or `null` if no handler is found.
      */
     queryOptional<R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D): Optional<MaybePromise<R>>;
     /**
-     * Checks if a handler is registered for the given type.
+     * Checks if at least one handler is registered for the given query type.
      *
-     * @param type - query type
-     * @returns true if handler exists
+     * @param type - Unique query identifier.
+     * @returns `true` if a handler is available, `false` otherwise.
      */
     has(type: QueryType): boolean;
     /**
-     * Removes all registered handlers.
+     * Removes all registered query handlers from the bus.
      *
      * @internal
      */
@@ -476,59 +1287,178 @@ declare class QueryBus {
 /**
  * Decorator for service methods that respond to a query.
  *
- * @param type - query type identifier
- * @returns decorator function
+ * @remarks
+ * Methods decorated with `@OnQuery` are automatically registered as query handlers
+ * when the service is bound via {@link bindService}.
+ *
+ * Unlike events, queries MUST be handled by exactly one handler. If multiple handlers
+ * are registered for the same query type, the most recent one (usually the most
+ * specific in terms of class hierarchy or registration order) will shadow the others.
+ *
+ * @group Queries
+ *
+ * @param type - Unique query identifier to handle.
+ * @returns Method decorator.
+ *
+ * @example
+ * ```typescript
+ * class UserProfileService {
+ *   @OnQuery("GET_USER_AVATAR")
+ *   private async onGetUserAvatar(userId: string): Promise<string> {
+ *     const user: User = await this.userRepository.findById(userId);
+ *
+ *     return user.avatarUrl;
+ *   }
+ * }
+ * ```
  */
 declare function OnQuery(type: QueryType): MethodDecorator;
 
 /**
- * Token for the container-scoped seeds map.
+ * Unique symbol used as a token for the container-scoped seeds map.
+ *
+ * @remarks
+ * This token is used to bind and resolve the {@link SeedsMap} in the Inversify {@link Container}.
+ *
+ * @group Seeds
+ *
+ * @example
+ * ```typescript
+ * const seedsMap: SeedsMap = container.get(SEEDS_TOKEN);
+ * ```
  */
 declare const SEEDS_TOKEN: unique symbol;
 /**
- * Token for the container-scoped shared seed object.
+ * Unique symbol used as a token for the container-scoped shared seed object.
+ *
+ * @remarks
+ * This token is used to bind and resolve the global shared seed object in the Inversify {@link Container}.
+ *
+ * @group Seeds
+ *
+ * @example
+ * ```typescript
+ * const sharedSeed: AnyObject = container.get(SEED_TOKEN);
+ * ```
  */
 declare const SEED_TOKEN: unique symbol;
 
 /**
- * Applies seeds to the container into the existing instance instead of replacing it.
- * This allows multiple providers to co-exist without wiping each other's seeds.
+ * Applies targeted seeds to the container's internal seed map.
+ *
+ * @remarks
+ * This function updates the existing {@link SeedsMap} instance instead of replacing it.
+ * This ensures that multiple providers can co-exist and contribute their own seeds
+ * without overwriting each other's data.
+ *
+ * @group Seeds
  *
- * @param container - target container
- * @param seeds - targeted seed entries apply
+ * @param container - The Inversify {@link Container} where seeds should be applied.
+ * @param seeds - An array of {@link SeedEntries} to add to the container.
+ *
+ * @example
+ * ```typescript
+ * applySeeds(container, [
+ *   [UserService, { initialUser: "admin" }],
+ *   ["API_KEY", "12345"]
+ * ]);
+ * ```
  */
 declare function applySeeds(container: Container, seeds: SeedEntries): void;
 
 /**
- * Applies shared seed to the container.
+ * Rebinds the global shared seed object in the container.
+ *
+ * @remarks
+ * Unlike targeted seeds, there is only one shared seed object per container.
+ * This function uses `rebind` to ensure the new shared seed replaces the previous one.
+ * The shared seed is typically used for global configuration or common state.
  *
- * @param container - target container
- * @param seed - shared seed object
+ * @group Seeds
+ *
+ * @param container - The Inversify {@link Container} to update.
+ * @param seed - The new shared seed object.
+ *
+ * @example
+ * ```typescript
+ * applySharedSeed(container, { theme: "dark", lang: "en" });
+ * ```
  */
 declare function applySharedSeed(container: Container, seed: AnyObject): void;
 
 /**
- * Removes specific seeds from the container.
- * Used during provider unmounting to clean up only the entries owned by that provider.
+ * Removes specific targeted seeds from the container's internal seed map.
+ *
+ * @remarks
+ * This is typically called during provider unmounting to ensure that only
+ * the seeds owned by that specific provider are removed, leaving other
+ * providers' seeds intact.
+ *
+ * @group Seeds
  *
- * @param container - target container
- * @param seeds - targeted seeds to remove
+ * @param container - The Inversify {@link Container} to clean up.
+ * @param seeds - The targeted {@link SeedEntries} to remove.
+ *
+ * @example
+ * ```typescript
+ * unapplySeeds(container, [[UserService, { initialUser: "admin" }]]);
+ * ```
  */
 declare function unapplySeeds(container: Container, seeds: SeedEntries): void;
 
 /**
- * Decorator for service methods that run after activation.
+ * Decorator for service methods that should be executed after the service instance is activated.
+ *
+ * @remarks
+ * Methods decorated with `@OnActivated` are automatically invoked when the service
+ * is resolved from the container and its activation lifecycle hook is triggered.
+ *
+ * It is commonly used for initial setup, subscribing to events, or starting background tasks.
+ * Multiple `@OnActivated` methods can exist in the same class hierarchy; they are executed
+ * in parent-to-child order.
+ *
+ * @group Service
+ *
+ * @returns A method decorator function.
  *
- * @returns decorator function
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @OnActivated()
+ *   public onActivated(): void {
+ *     console.log("Service activated!");
+ *   }
+ * }
+ * ```
  */
 declare function OnActivated(): MethodDecorator;
 
 /**
- * Decorator for service methods that run before deactivation.
+ * Decorator for service methods that should be executed before the service instance is deactivated.
+ *
+ * @remarks
+ * Methods decorated with `@OnDeactivation` are automatically invoked when the service
+ * is being removed from the container or when the container itself is being disposed.
+ *
+ * It is commonly used for cleanup, unsubscribing from events, or stopping background tasks.
+ * Multiple `@OnDeactivation` methods can exist in the same class hierarchy; they are executed
+ * in parent-to-child order.
+ *
+ * @group Service
+ *
+ * @returns A method decorator function.
  *
- * @returns decorator function
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @OnDeactivation()
+ *   public onDeactivation(): void {
+ *     console.log("Service deactivating!");
+ *   }
+ * }
+ * ```
  */
 declare function OnDeactivation(): MethodDecorator;
 
-export { CommandBus, CommandStatus, EventBus, InjectableDescriptor, OnActivated, OnCommand, OnDeactivation, OnEvent, OnQuery, QueryBus, SEED_TOKEN as SEED, SEEDS_TOKEN as SEEDS, WireScope, WirestateError, applySeeds, applySharedSeed, bindConstant, bindEntry, bindService, command, commandOptional, createIocContainer, emitEvent, forwardRef, getEntryToken, query, queryOptional, unapplySeeds };
-export type { CommandDescriptor, CommandHandler, CommandType, CommandUnregister, Event, EventHandler, EventType, EventUnsubscriber, QueryHandler, QueryType, QueryUnregister, SeedEntries, SeedEntry, SeedKey };
+export { CommandBus, CommandStatus, EventBus, InjectableDescriptor, OnActivated, OnCommand, OnDeactivation, OnEvent, OnQuery, QueryBus, SEED_TOKEN as SEED, SEEDS_TOKEN as SEEDS, SeedEntries, SeedKey, WireScope, WirestateError, applySeeds, applySharedSeed, bindConstant, bindDynamicValue, bindEntry, bindService, command, commandOptional, createContainer, emitEvent, forwardRef, getEntryToken, query, queryOptional, unapplySeeds };
+export type { BindEntryOptions, BindServiceOptions, CommandDescriptor, CommandHandler, CommandType, CommandUnregister, CreateContainerOptions, Event, EventHandler, EventType, EventUnsubscriber, QueryHandler, QueryType, QueryUnregister };