@wirestate/react 0.6.3 → 0.7.0-experimental.1

package/index.d.ts

@@ -1,254 +1,671 @@
-import { CommandType, CommandDescriptor, CommandHandler, QueryType, QueryHandler, ServiceIdentifier, Container, Newable, InjectableDescriptor, SeedEntries, EventType, EventHandler } from '@wirestate/core';
+import { CommandType, CommandDescriptor, CommandHandler, Container, WireScope, EventType, EventHandler, ServiceIdentifier, SeedEntries, CreateContainerOptions, QueryType, QueryHandler } from '@wirestate/core';
 import * as react from 'react';
-import { ReactNode, ReactElement, Dispatch, SetStateAction, PropsWithChildren } from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { InjectableEntries } from '@wirestate/core/types/privision';
 
 /**
- * Returns a function to dispatch commands on the active container.
+ * Represents a value that can be of type `T` or `null`.
  *
- * @returns command dispatcher
+ * @group general-types
+ *
+ * @template T - The base type.
  */
-declare function useCommandCaller(): <R = unknown, D = unknown, T extends CommandType = CommandType>(type: T, data?: D) => CommandDescriptor<R>;
-
+type Optional<T> = T | null;
 /**
- * Returns a function to dispatch optional commands on the active container.
- * Returns null instead of throwing when no handler is registered.
+ * Represents a value that can be of type `T` or a `Promise` resolving to `T`.
+ *
+ * @group general-types
  *
- * @returns optional command dispatcher
+ * @template T - The base type.
  */
-declare function useOptionalCommandCaller(): <R = unknown, D = unknown, T extends CommandType = CommandType>(type: T, data?: D) => CommandDescriptor<R> | null;
+type MaybePromise<T> = T | Promise<T>;
 
 /**
- * Registers a command handler for the component's lifetime.
- * The handler is stored in a ref to avoid manual memoization.
- * Only one handler is active per type; newer registrations shadow older ones.
+ * Represents signature for a function that dispatches commands.
  *
- * @param type - command type
- * @param handler - command handler function
+ * @remarks
+ * Typically returned by {@link useCommandCaller}. Dispatched commands are
+ * automatically wrapped in a {@link CommandDescriptor}.
+ *
+ * @group Commands
+ *
+ * @template R - The expected result type of the command task.
+ * @template D - The type of the data payload.
+ * @template T - The command identifier type.
+ *
+ * @param type - The command identifier.
+ * @param data - Optional payload for the command.
+ *
+ * @returns A descriptor containing the execution task and status.
  */
-declare function useCommandHandler<R = unknown, D = unknown>(type: CommandType, handler: CommandHandler<D, R>): void;
+type CommandCaller = <R = unknown, D = unknown, T extends CommandType = CommandType>(type: T, data?: D) => CommandDescriptor<R>;
+/**
+ * Represents signature for a function that dispatches optional commands.
+ *
+ * @remarks
+ * Typically returned by {@link useOptionalCommandCaller}. Returns `null` if no
+ * handler is registered for the command type, instead of throwing.
+ *
+ * @group Commands
+ *
+ * @template R - The expected result type of the command task.
+ * @template D - The type of the data payload.
+ * @template T - The command identifier type.
+ *
+ * @param type - The command identifier.
+ * @param data - Optional payload for the command.
+ *
+ * @returns A descriptor if a handler was found, or `null` otherwise.
+ */
+type OptionalCommandCaller = <R = unknown, D = unknown, T extends CommandType = CommandType>(type: T, data?: D) => Optional<CommandDescriptor<R>>;
 
-type Optional<T> = T | null;
-type MaybePromise<T> = T | Promise<T>;
+/**
+ * Returns a stable function to dispatch commands on the active container.
+ *
+ * @remarks
+ * The returned dispatcher is memoized using `useCallback` and stays stable
+ * for the lifetime of the container. It uses {@link CommandBus.command} internally.
+ *
+ * @group Commands
+ *
+ * @returns A command dispatcher function that takes a type and optional data.
+ *
+ * @example
+ * ```tsx
+ * const call: CommandCaller = useCommandCaller();
+ *
+ * const onClick = () => call("SAVE_USER_COMMAND", { id: 1 });
+ * ```
+ */
+declare function useCommandCaller(): CommandCaller;
 
 /**
- * Public query responder signature.
+ * Returns a stable function to dispatch optional commands on the active container.
+ *
+ * @remarks
+ * Similar to {@link useCommandCaller}, but returns `null` instead of throwing
+ * {WirestateError} if no handler is registered for the command type.
+ * Uses {@link CommandBus.commandOptional} internally.
+ *
+ * @group Commands
+ *
+ * @returns An optional command dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const callOptional: OptionalCommandCaller = useOptionalCommandCaller();
+ * const descriptor: CommandDescriptor<string> | null = callOptional("OPTIONAL_COMMAND", data);
+ *
+ * if (descriptor) {
+ *   const result: string = await descriptor.task;
+ * }
+ * ```
  */
-type QueryResponder<R = unknown, D = unknown> = (data?: D) => MaybePromise<R>;
+declare function useOptionalCommandCaller(): OptionalCommandCaller;
+
 /**
- * Dispatches queries and returns their result as a value or promise.
+ * Registers a command handler for the component's lifetime.
+ *
+ * @remarks
+ * The handler is stored in a `useRef` and synced on every render to avoid stale
+ * closures without requiring manual memoization of the handler function.
+ * Only one handler is active per type; newer registrations shadow older ones.
+ * The handler is automatically unregistered when the component unmounts.
+ *
+ * @group Commands
+ *
+ * @template R - Result type of the command.
+ * @template D - Data/payload type of the command.
+ *
+ * @param type - Command type (string or symbol).
+ * @param handler - Command handler function.
+ *
+ * @example
+ * ```tsx
+ * useCommandHandler("SAVE_COMMAND", (data) => {
+ *   return api.save(data);
+ * });
+ * ```
  */
-type QueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => MaybePromise<R>;
+declare function useCommandHandler<R = unknown, D = unknown>(type: CommandType, handler: CommandHandler<D, R>): void;
+
 /**
- * Dispatches synchronous queries and returns their result directly.
+ * Returns the active container from the context.
+ *
+ * @remarks
+ * Use this hook when you need direct access to the {@link Container} for manual
+ * resolution or checking bindings. For typical service usage, prefer
+ * {@link useInjection}.
+ *
+ * @group Context
+ *
+ * @returns The active container.
+ *
+ * @example
+ * ```tsx
+ * const container: Container = useContainer();
+ * const isBound: boolean = container.isBound(MyToken);
+ * ```
  */
-type SyncQueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => R;
+declare function useContainer(): Container;
+
 /**
- * Dispatches optional queries. Returns null when no handler is registered.
+ * Creates and memoizes a root container for a component.
+ *
+ * @remarks
+ * The `factory` function re-runs only when one of `deps` changes.
+ * Between such changes, the same container instance is returned.
+ *
+ * @group Context
+ *
+ * @param factory - Lazily creates the root container.
+ * @param deps - Dependency list controlling when container is recreated.
+ * @returns The memoized root container instance.
+ *
+ * @example
+ * ```tsx
+ * const container: Container = useRootContainer(
+ *   () =>
+ *     createIocContainer({
+ *       entries: [CounterService, LoggerService],
+ *     }),
+ *   []
+ * );
+ * ```
  */
-type OptionalQueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => Optional<MaybePromise<R>>;
+declare function useRootContainer(factory: () => Container, deps: Array<unknown>): Container;
+
 /**
- * Dispatches optional synchronous queries. Returns null when no handler is registered.
+ * Returns a {@link WireScope} instance bound to the active container.
+ *
+ * @remarks
+ * The scope is recreated if the container changes. It provides a convenient
+ * way to access container features like events, commands, and queries.
+ *
+ * @group Context
+ *
+ * @returns A {@link WireScope} instance.
+ *
+ * @example
+ * ```tsx
+ * const scope: WireScope = useScope();
+ *
+ * scope.emitEvent("UI_READY");
+ * ```
  */
-type OptionalSyncQueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => Optional<R>;
+declare function useScope(): WireScope;
 
 /**
- * Returns a function to dispatch queries on the active container.
+ * Subscribes a component to a specific event type on the {@link EventBus}.
+ *
+ * @remarks
+ * The subscription is active for the component's lifetime and is automatically
+ * cleaned up on unmount. The handler is synced via `useRef` to avoid stale
+ * closures without requiring manual memoization of the handler function.
+ *
+ * @group Events
  *
- * @returns query dispatcher
+ * @param type - Event type to listen for.
+ * @param handler - Function invoked when the specified event is emitted.
+ *
+ * @example
+ * ```tsx
+ * useEvent("USER_LOGGED_IN", (event) => {
+ *   console.log("User logged in:,", event);
+ * });
+ * ```
  */
-declare function useQueryCaller(): QueryCaller;
+declare function useEvent(type: EventType, handler: EventHandler): void;
 
 /**
- * Returns a function to dispatch optional queries on the active container.
- * Returns null instead of throwing when no handler is registered.
+ * Subscribes a component to multiple event types on the {@link EventBus}.
  *
- * @returns optional query dispatcher
+ * @remarks
+ * Similar to {@link useEvent}, but allows listening for a collection of event
+ * types using a single handler.
+ * The handler and type list are synced via `useRef` to avoid stale closures.
+ *
+ * @group Events
+ *
+ * @param types - Array of event types (strings or symbols) to filter by.
+ * @param handler - Function invoked when any of the specified events are emitted.
+ *
+ * @example
+ * ```tsx
+ * useEvents(["USER_UPDATED", "USER_DELETED"], (event) => {
+ *   refreshList();
+ * });
+ * ```
  */
-declare function useOptionalQueryCaller(): OptionalQueryCaller;
+declare function useEvents(types: ReadonlyArray<EventType>, handler: EventHandler): void;
 
 /**
- * Registers a query handler for the component's lifetime.
- * The handler is stored in a ref to avoid manual memoization.
- * Only one handler is active per type; newer registrations shadow older ones.
+ * Subscribes a component to all events on the {@link EventBus} without type filtering.
+ *
+ * @remarks
+ * Useful for logging, debugging, or cross-cutting concerns that need to see
+ * every event passing through the bus.
+ * The handler is synced via `useRef` to avoid stale closures.
+ * The subscription is automatically cleaned up on unmount.
+ *
+ * @group Events
  *
- * @param type - query type
- * @param handler - query handler function
+ * @param handler - Event handler invoked for every emitted event.
+ *
+ * @example
+ * ```tsx
+ * useEventsHandler((event) => {
+ *   console.log('Event receieved:', event.type, event.payload);
+ * });
+ * ```
  */
-declare function useQueryHandler<R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, handler: QueryHandler<D, R>): void;
+declare function useEventsHandler(handler: EventHandler): void;
 
 /**
- * Returns a stable function to dispatch synchronous queries.
- * Returns the value directly from the handler.
+ * Represents signature for a function that emits events via the EventBus.
+ *
+ * @remarks
+ * Typically returned by {@link useEventEmitter}. Supports optional payload
+ * and source identifier.
+ *
+ * @group Events
  *
- * @returns sync query dispatcher
+ * @template P - The type of the event payload.
+ * @template T - The event identifier type.
+ * @template F - The type of the event source identifier.
+ *
+ * @param type - The event identifier.
+ * @param payload - Optional data associated with the event.
+ * @param from - Optional identifier of the event source.
  */
-declare function useSyncQueryCaller(): SyncQueryCaller;
+type EventEmitter<P = unknown, T extends EventType = EventType, F = unknown> = (type: T, payload?: P, from?: F) => void;
 
 /**
- * Returns a stable function to dispatch synchronous optional queries.
- * Returns null instead of throwing when no handler is registered.
+ * Returns a stable function to emit events via the {@link EventBus}.
+ *
+ * @remarks
+ * The returned emitter is memoized using `useCallback` and stays stable
+ * for the lifetime of the container.
+ *
+ * @group Events
+ *
+ * @template P - Default payload type for emitted events.
+ * @template T - Default event identifier type.
+ *
+ * @returns An event emitter function.
+ *
+ * @example
+ * ```tsx
+ * const emit: EventEmitter = useEventEmitter();
  *
- * @returns optional sync query dispatcher
+ * const onClick = () => emit("BUTTON_CLICKED", { id: "submit" });
+ * ```
  */
-declare function useOptionalSyncQueryCaller(): OptionalSyncQueryCaller;
+declare function useEventEmitter<P = unknown, T extends EventType = EventType>(): EventEmitter<P, T>;
 
 /**
- * Resolves a value from the container - constant or service.
- * Automatically re-resolves if the container is reset or services are rebound.
+ * Resolves a service or constant from the active container.
+ *
+ * @remarks
+ * This hook automatically re-resolves the dependency if the container's
+ * revision changes (e.g., due to re-binding in a provider).
+ *
+ * @group Injection
+ *
+ * @template T - The type of the value being resolved.
+ *
+ * @param injectionId - The service identifier (string, symbol, or constructor).
  *
- * @param injectionId - injection identifier
- * @returns resolved value
+ * @returns The resolved instance or value.
+ *
+ * @throws {WirestateError} If the container is not found in context.
+ * @throws {Error} If Inversify fails to resolve the identifier.
+ *
+ * @example
+ * ```tsx
+ * const api: ApiService = useInjection(ApiService);
+ * ```
  */
 declare function useInjection<T>(injectionId: ServiceIdentifier<T>): T;
 
 /**
- * Resolves a value from the container if bound, returning null otherwise.
- * Unlike {@link useInjection}, this hook does not throw when the token is not bound.
+ * Safely resolves a value from the container, returning a fallback or null if not bound.
+ *
+ * @remarks
+ * Unlike {@link useInjection}, this hook does not throw if the dependency
+ * is missing from the container.
+ *
+ * @group Injection
+ *
+ * @template T - The type of the value being resolved.
+ *
+ * @param injectionId - The service identifier (string, symbol, or constructor).
+ * @param onFallback - Optional function called to provide a value if the token is not bound.
+ *
+ * @returns The resolved value, the result of the fallback function, or `null`.
  *
- * @param injectionId - injection identifier
- * @param onFallback - optional callback to handle cases when dependency was not resolved
- * @returns resolved value, result of optional fallback handler or null
+ * @example
+ * ```tsx
+ * const logger = useOptionalInjection(FileLogger, (container) => container.get(ConsoleLoggerService);
+ * ```
  */
 declare function useOptionalInjection<T>(injectionId: ServiceIdentifier<T>, onFallback?: (container: Container) => T): Optional<T>;
 
 /**
- * Props for the component returned by {@link createInjectablesProvider}.
+ * Props accepted by {@link SubContainerProvider}.
+ *
+ * @group Provision
  */
-interface InjectablesProviderProps {
+interface SubContainerProviderProps {
     /**
-     * Targeted seeds bound to specific injectables or tokens.
-     * Subsequent prop changes are ignored. Use a React `key` to re-seed the tree.
+     * Targeted seeds applied before entries are bound.
+     *
+     * @remarks
+     * Seed changes do not recreate the child container. Pass a React `key` to
+     * force a remount when you need to re-seed the subtree.
      */
     readonly seeds?: SeedEntries;
     /**
-     * Subtree that consumes the bound services.
+     * Services or descriptors bound inside the child container.
+     *
+     * @remarks
+     * The child container is recreated when this array changes by shallow
+     * comparison or when the parent container changes.
      */
-    readonly children?: ReactNode;
-}
-/**
- * Component returned by {@link createInjectablesProvider}.
- */
-type InjectablesProvider = ReturnType<typeof createInjectablesProvider>;
-/**
- * Configuration for {@link createInjectablesProvider}.
- */
-interface CreateInjectablesProviderOptions {
+    readonly entries: InjectableEntries;
     /**
-     * Services to resolve immediately on mount.
+     * React subtree that receives the child container.
      */
-    readonly activate?: ReadonlyArray<ServiceIdentifier>;
+    readonly children?: ReactNode;
 }
 /**
- * Creates a component that manages injectable lifetimes for its subtree.
+ * Provides a child container derived from the nearest parent container.
+ *
+ * @remarks
+ * The provider owns the child container. It disposes the previous child before
+ * exposing a replacement, recreates on parent or `entries` changes, and revives
+ * a cleaned child after React development remount cleanup.
  *
- * @param entries - service classes or injectable descriptors to bind
- * @param options - provider configuration
- * @returns injectables provider component
+ * @group Provision
+ *
+ * @param props - Provider props.
+ * @returns A React context provider for the child container.
  */
-declare function createInjectablesProvider(entries: ReadonlyArray<Newable<object> | InjectableDescriptor>, options?: CreateInjectablesProviderOptions): {
-    (props: InjectablesProviderProps): ReactElement;
-    displayName: string;
-};
+declare function SubContainerProvider(props: SubContainerProviderProps): react.FunctionComponentElement<react.ProviderProps<any>>;
 
 /**
- * React context value.
+ * Represents props for {@link ContainerActivator}.
+ *
+ * @group Provision
  */
-interface IocContext {
-    /**
-     * Inversify container.
-     */
-    readonly container: Container;
+interface ContainerActivatorProps {
     /**
-     * Revision counter for cache invalidation.
+     * Services to resolve immediately on render.
+     *
+     * @remarks
+     * Listed services must be bound in current container.
      */
-    readonly revision: number;
+    readonly activate: ReadonlyArray<ServiceIdentifier>;
     /**
-     * Forces a revision update.
+     * Nested child node.
      */
-    readonly setRevision: Dispatch<SetStateAction<number>>;
+    readonly children?: ReactNode;
 }
+/**
+ * Resolves specified services from the current IoC container before rendering children.
+ *
+ * @remarks
+ * Activation runs once per container instance.
+ * On rerender with the same container, services are not resolved again.
+ *
+ * @group Provision
+ *
+ * @param props - Component properties.
+ * @param props.activate - Services to resolve eagerly from container.
+ * @param props.children - React children element.
+ * @returns React children after activation side effect is applied.
+ */
+declare function ContainerActivator(props: ContainerActivatorProps): ReactElement<any, string | react.JSXElementConstructor<any>>;
 
 /**
- * Props for {@link IocProvider}.
+ * Describes how {@link ContainerProvider} receives its root container.
+ *
+ * @remarks
+ * Pass an existing {@link Container} when ownership lives outside React. Pass
+ * {@link CreateContainerOptions} when the provider should create and dispose a
+ * managed container for the subtree.
+ */
+type ContainerProviderSource = Container | CreateContainerOptions;
+/**
+ * Represents props accepted by {@link ContainerProvider}.
+ *
+ * @group Provision
  */
-interface IocProviderProps extends PropsWithChildren<unknown> {
+interface ContainerProviderProps {
     /**
-     * External container instance. If omitted, a new container is created.
+     * Container instance or options used to create one.
+     *
+     * @remarks
+     * External container instances are never disposed by this provider. Managed
+     * containers created from options are disposed on unmount and recreated when
+     * the `entries` array changes by shallow comparison.
      */
-    readonly container?: Container;
+    readonly container: ContainerProviderSource;
     /**
-     * Shared seed for the container.
+     * React subtree that receives the active container.
      */
-    readonly seed?: Record<string, unknown>;
+    readonly children?: ReactNode;
 }
 /**
- * Provides an IoC container to the component tree.
+ * Provides a root Wirestate container to a React subtree.
  *
- * @param props - component props
- * @param props.container - external container instance
- * @param props.seed - shared seed across the container
- * @param props.children - components to wrap
- * @returns provider element
+ * @remarks
+ * The provider supports two modes:
+ *
+ * - External mode: `container` is a prebuilt {@link Container}. The provider
+ *   only passes it through context.
+ * - Managed mode: `container` is {@link CreateContainerOptions}. The provider
+ *   creates a container, owns its disposal, recreates it when `entries` change,
+ *   and revives it after React development remount cleanup.
+ *
+ * @group Provision
+ *
+ * @param props - Provider props.
+ * @returns A React context provider for the active container.
  */
-declare function IocProvider({ container: externalContainer, seed, children }: IocProviderProps): react.FunctionComponentElement<react.ProviderProps<Optional<IocContext>>>;
+declare function ContainerProvider(props: ContainerProviderProps): react.FunctionComponentElement<react.ProviderProps<any>>;
 
 /**
- * Returns the active IoC container.
+ * Represents signature for a function that responds to a query.
+ *
+ * @group Queries
+ *
+ * @template R - The result type of the query.
+ * @template D - The type of the data payload.
+ *
+ * @param data - Optional payload for the query.
  *
- * @returns active Inversify container
+ * @returns The query result, possibly as a promise.
  */
-declare function useContainer(): Container;
-
+type QueryResponder<R = unknown, D = unknown> = (data?: D) => MaybePromise<R>;
 /**
- * Returns the current container revision.
+ * Represents signature for a function that dispatches queries and returns their result.
+ *
+ * @remarks
+ * Typically returned by {@link useQueryCaller}.
+ *
+ * @group Queries
+ *
+ * @template R - The result type of the query.
+ * @template D - The type of the data payload.
+ * @template T - The query identifier type.
  *
- * @returns revision number
+ * @param type - The query identifier.
+ * @param data - Optional payload for the query.
+ *
+ * @returns The query result as a value or promise.
  */
-declare function useContainerRevision(): number;
-
+type QueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => MaybePromise<R>;
+/**
+ * Represents signature for a function that dispatches synchronous queries.
+ *
+ * @remarks
+ * Typically returned by {@link useSyncQueryCaller}.
+ *
+ * @group Queries
+ *
+ * @template R - The result type of the query.
+ * @template D - The type of the data payload.
+ * @template T - The query identifier type.
+ *
+ * @param type - The query identifier.
+ * @param data - Optional payload for the query.
+ *
+ * @returns The query result directly.
+ */
+type SyncQueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => R;
 /**
- * Subscribes a component to events.
+ * Represents signature for a function that dispatches optional queries.
+ *
+ * @remarks
+ * Typically returned by {@link useOptionalQueryCaller}. Returns `null` when
+ * no handler is registered.
+ *
+ * @group Queries
  *
- * @param type - event type to listen to
- * @param handler - event handler to invoke when event is emitted
+ * @template R - The result type of the query.
+ * @template D - The type of the data payload.
+ * @template T - The query identifier type.
+ *
+ * @param type - The query identifier.
+ * @param data - Optional payload for the query.
+ *
+ * @returns The query result, or `null` if no handler was found.
  */
-declare function useEvent(type: EventType, handler: EventHandler): void;
-
+type OptionalQueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => Optional<MaybePromise<R>>;
 /**
- * Subscribes a component to multiple event types.
+ * Represents signature for a function that dispatches optional synchronous queries.
+ *
+ * @remarks
+ * Typically returned by {@link useOptionalSyncQueryCaller}. Returns `null`
+ * when no handler is registered.
  *
- * @param types - event types to filter by
- * @param handler - events handler
+ * @group Queries
+ *
+ * @template R - The result type of the query.
+ * @template D - The type of the data payload.
+ * @template T - The query identifier type.
+ *
+ * @param type - The query identifier.
+ * @param data - Optional payload for the query.
+ *
+ * @returns The query result directly, or `null` if no handler was found.
  */
-declare function useEvents(types: ReadonlyArray<EventType>, handler: EventHandler): void;
+type OptionalSyncQueryCaller = <R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, data?: D) => Optional<R>;
 
 /**
- * Subscribes a component to all events without type filtering.
+ * Returns a stable function to dispatch queries on the active container.
+ *
+ * @remarks
+ * The returned dispatcher is memoized using `useCallback` and stays stable
+ * for the lifetime of the container. It uses {@link QueryBus.query} internally.
  *
- * @param handler - event handler invoked for every emitted event
+ * @group Queries
+ *
+ * @returns A query dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const query: QueryCaller = useQueryCaller();
+ * const result: UserProfile = await query(GET_USER_PROFILE, { id: 123 });
+ * ```
  */
-declare function useEventsHandler(handler: EventHandler): void;
+declare function useQueryCaller(): QueryCaller;
 
 /**
- * Event emitter signature.
+ * Returns a stable function to dispatch optional queries on the active container.
+ *
+ * @remarks
+ * The returned dispatcher is memoized using `useCallback` and stays stable
+ * for the lifetime of the container. It returns `null` instead of throwing
+ * if no handler is registered.
+ *
+ * @group Queries
+ *
+ * @returns An optional query dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const queryOptional: OptionalQueryCaller = useOptionalQueryCaller();
+ * const settings: UserSettings | null = await queryOptional(GET_USER_SETTINGS, { id: 1 });
+ * ```
  */
-type EventEmitter<P = unknown, T extends EventType = EventType, F = unknown> = (type: T, payload?: P, from?: F) => void;
+declare function useOptionalQueryCaller(): OptionalQueryCaller;
 
 /**
- * Returns a stable function to emit events.
+ * Registers a query handler for the component's lifetime.
+ *
+ * @remarks
+ * The handler is stored in a `useRef` and synced on every render to avoid stale
+ * closures. Only one handler is active per type; newer registrations shadow older ones.
+ * The handler is automatically unregistered when the component unmounts.
  *
- * @returns event emitter
+ * @group Queries
+ *
+ * @template R - Result type of the query.
+ * @template D - Data/payload type of the query.
+ * @template T - Query identifier type.
+ *
+ * @param type - Query identifier (string or symbol).
+ * @param handler - Function that responds to the query.
+ *
+ * @example
+ * ```tsx
+ * useQueryHandler("GET_DATA", (data) => {
+ *   return { id: data.id, value: "Resolved" };
+ * });
+ * ```
  */
-declare function useEventEmitter<P = unknown, T extends EventType = EventType>(): EventEmitter<P, T>;
+declare function useQueryHandler<R = unknown, D = unknown, T extends QueryType = QueryType>(type: T, handler: QueryHandler<D, R>): void;
 
 /**
- * Command calling function signature.
+ * Returns a stable function to dispatch synchronous queries.
+ *
+ * @remarks
+ * The returned dispatcher returns the value directly from the handler
+ * instead of a Promise (unless the handler itself returns a Promise).
+ * Memoized using `useCallback`.
+ *
+ * @group Queries
+ *
+ * @returns A synchronous query dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const querySync: SyncQueryCaller = useSyncQueryCaller();
+ * const config: ApplicationConfig = querySync("GET_APP_CONFIG");
+ * ```
  */
-type CommandCaller<R = unknown, D = unknown, T extends CommandType = CommandType> = (type: T, data?: D) => CommandDescriptor<R>;
+declare function useSyncQueryCaller(): SyncQueryCaller;
+
 /**
- * Command calling function signature.
+ * Returns a stable function to dispatch synchronous optional queries.
+ *
+ * @remarks
+ * Similar to {@link useOptionalQueryCaller}, but returns the value directly
+ * (synchronously) from the handler. Returns `null` if no handler is registered.
+ *
+ * @group Queries
+ *
+ * @returns An optional synchronous query dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const querySyncOptional: OptionalSyncQueryCaller = useOptionalSyncQueryCaller();
+ * const value: ThemePreference | null = querySyncOptional(GET_THEME_PREFERENCE);
+ * ```
  */
-type OptionalCommandCaller<R = unknown, D = unknown, T extends CommandType = CommandType> = (type: T, data?: D) => Optional<CommandDescriptor<R>>;
+declare function useOptionalSyncQueryCaller(): OptionalSyncQueryCaller;
 
-export { IocProvider, createInjectablesProvider, useCommandCaller, useCommandHandler, useContainer, useContainerRevision, useEvent, useEventEmitter, useEvents, useEventsHandler, useInjection, useOptionalCommandCaller, useOptionalInjection, useOptionalQueryCaller, useOptionalSyncQueryCaller, useQueryCaller, useQueryHandler, useSyncQueryCaller };
-export type { CommandCaller, EventEmitter, InjectablesProvider, InjectablesProviderProps, OptionalCommandCaller, OptionalQueryCaller, OptionalSyncQueryCaller, QueryCaller, QueryResponder, SyncQueryCaller };
+export { ContainerActivator, ContainerProvider, SubContainerProvider, useCommandCaller, useCommandHandler, useContainer, useEvent, useEventEmitter, useEvents, useEventsHandler, useInjection, useOptionalCommandCaller, useOptionalInjection, useOptionalQueryCaller, useOptionalSyncQueryCaller, useQueryCaller, useQueryHandler, useRootContainer, useScope, useSyncQueryCaller };
+export type { CommandCaller, ContainerActivatorProps, ContainerProviderProps, EventEmitter, OptionalCommandCaller, OptionalQueryCaller, OptionalSyncQueryCaller, QueryCaller, QueryResponder, SubContainerProviderProps, SyncQueryCaller };