@wirestate/react 0.6.2 → 0.7.0-experimental.1

package/cjs/development/index.js

@@ -2,35 +2,53 @@
 
 var core = require('@wirestate/core');
 var react = require('react');
-var iocProvider = require('./lib.js');
+var containerProvider = require('./lib.js');
+
+var ERROR_CODE_INVALID_CONTEXT = 1052;
 
 /**
- * Returns the full IoC context.
+ * 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.
  *
- * @returns active IoC context
- * @internal
+ * @example
+ * ```tsx
+ * const container: Container = useContainer();
+ * const isBound: boolean = container.isBound(MyToken);
+ * ```
  */
-function useIocContext() {
-  var value = react.useContext(iocProvider.IocReactContext);
+function useContainer() {
+  var value = react.useContext(containerProvider.ContainerReactContext);
   if (!value) {
-    throw new core.WirestateError(iocProvider.ERROR_CODE_INVALID_CONTEXT, "Trying to access IOC context from React subtree not wrapped in <IocProvider>.");
+    throw new core.WirestateError(ERROR_CODE_INVALID_CONTEXT, "Trying to access container context from React subtree not wrapped in <ContainerProvider>.");
   }
   return value;
 }
 
 /**
- * Returns the active IoC container.
+ * Returns a stable function to dispatch commands on the active container.
  *
- * @returns active Inversify container
- */
-function useContainer() {
-  return useIocContext().container;
-}
-
-/**
- * Returns a 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.
  *
- * @returns command dispatcher
+ * @example
+ * ```tsx
+ * const call: CommandCaller = useCommandCaller();
+ *
+ * const onClick = () => call("SAVE_USER_COMMAND", { id: 1 });
+ * ```
  */
 function useCommandCaller() {
   var container = useContainer();
@@ -40,10 +58,26 @@ function useCommandCaller() {
 }
 
 /**
- * Returns a function to dispatch optional commands on the active container.
- * Returns null instead of throwing when no handler is registered.
+ * 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.
  *
- * @returns optional command dispatcher
+ * @example
+ * ```tsx
+ * const callOptional: OptionalCommandCaller = useOptionalCommandCaller();
+ * const descriptor: CommandDescriptor<string> | null = callOptional("OPTIONAL_COMMAND", data);
+ *
+ * if (descriptor) {
+ *   const result: string = await descriptor.task;
+ * }
+ * ```
  */
 function useOptionalCommandCaller() {
   var container = useContainer();
@@ -54,11 +88,27 @@ function useOptionalCommandCaller() {
 
 /**
  * Registers a command handler for the component's lifetime.
- * The handler is stored in a ref to avoid manual memoization.
+ *
+ * @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
- * @param handler - command handler function
+ * @param type - Command type (string or symbol).
+ * @param handler - Command handler function.
+ *
+ * @example
+ * ```tsx
+ * useCommandHandler("SAVE_COMMAND", (data) => {
+ *   return api.save(data);
+ * });
+ * ```
  */
 function useCommandHandler(type, handler) {
   var container = useContainer();
@@ -75,107 +125,257 @@ function useCommandHandler(type, handler) {
 }
 
 /**
- * Returns a function to dispatch queries on the active container.
+ * 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.
  *
- * @returns query dispatcher
+ * @example
+ * ```tsx
+ * const container: Container = useRootContainer(
+ *   () =>
+ *     createIocContainer({
+ *       entries: [CounterService, LoggerService],
+ *     }),
+ *   []
+ * );
+ * ```
  */
-function useQueryCaller() {
-  var container = useContainer();
-  return react.useCallback(function (type, data) {
-    return container.get(core.QueryBus).query(type, data);
-  }, [container]);
+function useRootContainer(factory, deps) {
+  return react.useMemo(function () {
+    var container = factory();
+    return container;
+  }, deps);
 }
 
 /**
- * Returns a function to dispatch optional queries on the active container.
- * Returns null instead of throwing 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.
  *
- * @returns optional query dispatcher
+ * @group Context
+ *
+ * @returns A {@link WireScope} instance.
+ *
+ * @example
+ * ```tsx
+ * const scope: WireScope = useScope();
+ *
+ * scope.emitEvent("UI_READY");
+ * ```
  */
-function useOptionalQueryCaller() {
+function useScope() {
   var container = useContainer();
-  return react.useCallback(function (type, data) {
-    return container.get(core.QueryBus).queryOptional(type, data);
+  return react.useMemo(function () {
+    return container.get(core.WireScope);
   }, [container]);
 }
 
 /**
- * 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 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
+ *
+ * @param type - Event type to listen for.
+ * @param handler - Function invoked when the specified event is emitted.
  *
- * @param type - query type
- * @param handler - query handler function
+ * @example
+ * ```tsx
+ * useEvent("USER_LOGGED_IN", (event) => {
+ *   console.log("User logged in:,", event);
+ * });
+ * ```
  */
-function useQueryHandler(type, handler) {
-  var container = useContainer();
+function useEvent(type, handler) {
+  var typeRef = react.useRef(type);
   var handlerRef = react.useRef(handler);
+  var container = useContainer();
   react.useEffect(function () {
+    typeRef.current = type;
     handlerRef.current = handler;
   });
   react.useEffect(function () {
-    return container.get(core.QueryBus).register(type, function (data) {
-      return handlerRef.current(data);
+    return container.get(core.EventBus).subscribe(function (event) {
+      var _a;
+      if (event.type === typeRef.current) {
+        (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, event);
+      }
     });
   }, [container, type]);
 }
 
 /**
- * Returns a stable function to dispatch synchronous queries.
- * Returns the value directly from the handler.
+ * Subscribes a component to multiple event types on the {@link EventBus}.
+ *
+ * @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.
  *
- * @returns sync query dispatcher
+ * @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();
+ * });
+ * ```
  */
-function useSyncQueryCaller() {
+function useEvents(types, handler) {
+  var typesRef = react.useRef(types);
+  var handlerRef = react.useRef(handler);
   var container = useContainer();
-  return react.useCallback(function (type, data) {
-    // Access the container-scoped QueryBus and execute the query.
-    return container.get(core.QueryBus).query(type, data);
+  react.useEffect(function () {
+    typesRef.current = types;
+    handlerRef.current = handler;
+  });
+  react.useEffect(function () {
+    return container.get(core.EventBus).subscribe(function (event) {
+      var _a;
+      if (typesRef.current.includes(event.type)) {
+        (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, event);
+      }
+    });
   }, [container]);
 }
 
 /**
- * Returns a stable function to dispatch synchronous optional queries.
- * Returns null instead of throwing when no handler is registered.
+ * 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.
  *
- * @returns optional sync query dispatcher
+ * @group Events
+ *
+ * @param handler - Event handler invoked for every emitted event.
+ *
+ * @example
+ * ```tsx
+ * useEventsHandler((event) => {
+ *   console.log('Event receieved:', event.type, event.payload);
+ * });
+ * ```
  */
-function useOptionalSyncQueryCaller() {
+function useEventsHandler(handler) {
+  var handlerRef = react.useRef(handler);
   var container = useContainer();
-  return react.useCallback(function (type, data) {
-    return container.get(core.QueryBus).queryOptional(type, data);
+  react.useEffect(function () {
+    handlerRef.current = handler;
+  });
+  react.useEffect(function () {
+    return container.get(core.EventBus).subscribe(function (event) {
+      var _a;
+      (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, event);
+    });
+  }, [container]);
+}
+
+/**
+ * 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();
+ *
+ * const onClick = () => emit("BUTTON_CLICKED", { id: "submit" });
+ * ```
+ */
+function useEventEmitter() {
+  var container = useContainer();
+  return react.useCallback(function (type, payload, from) {
+    container.get(core.EventBus).emit({
+      type: type,
+      payload: payload,
+      from: from
+    });
   }, [container]);
 }
 
 /**
- * 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.
  *
- * @param injectionId - injection identifier
- * @returns resolved value
+ * @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).
+ *
+ * @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);
+ * ```
  */
 function useInjection(injectionId) {
-  var _a = useIocContext(),
-    container = _a.container,
-    revision = _a.revision;
+  var container = useContainer();
   // Revision bump causes a container reset; force re-resolution to drop stale instances.
   return react.useMemo(function () {
     return container.get(injectionId);
-  }, [container, revision, injectionId]);
+  }, [container, injectionId]);
 }
 
 /**
- * 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.
  *
- * @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
+ * @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`.
+ *
+ * @example
+ * ```tsx
+ * const logger = useOptionalInjection(FileLogger, (container) => container.get(ConsoleLoggerService);
+ * ```
  */
 function useOptionalInjection(injectionId, onFallback) {
-  var _a = useIocContext(),
-    container = _a.container,
-    revision = _a.revision;
+  var container = useContainer();
   // Revision bump forces a container reset; force re-resolution to drop stale instances.
   return react.useMemo(function () {
     if (container.isBound(injectionId)) {
@@ -185,201 +385,239 @@ function useOptionalInjection(injectionId, onFallback) {
     } else {
       return null;
     }
-  }, [container, revision, injectionId]);
+  }, [container, injectionId]);
 }
 
 /**
- * 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.
+ *
+ * @group Provision
  *
- * @param entries - service classes or injectable descriptors to bind
- * @param options - provider configuration
- * @returns injectables provider component
+ * @param props - Provider props.
+ * @returns A React context provider for the child container.
  */
-function createInjectablesProvider(entries, options) {
-  if (options === void 0) {
-    options = {};
-  }
-  var activate = options.activate;
-  if (activate && activate.length > 0) {
-    var entryTokens = entries.map(core.getEntryToken);
-    for (var _i = 0, activate_1 = activate; _i < activate_1.length; _i++) {
-      var eager = activate_1[_i];
-      if (!entryTokens.includes(eager)) {
-        throw new core.WirestateError(iocProvider.ERROR_CODE_VALIDATION_ERROR, "createInjectablesProvider: '".concat(String(eager), "' is listed in 'activate' but was not provided in 'entries'."));
-      }
-    }
-  }
-  function InjectablesProviderComponent(props) {
-    var iocContext = react.useContext(iocProvider.IocReactContext);
-    if (!iocContext) {
-      throw new core.WirestateError(iocProvider.ERROR_CODE_INVALID_CONTEXT, "<InjectablesProvider> must be rendered inside an <IocProvider> React subtree.");
+function SubContainerProvider(props) {
+  var _a;
+  var parent = useContainer();
+  var source = {
+    entries: props.entries,
+    parent: parent,
+    seeds: props.seeds
+  };
+  var state = containerProvider.useContainerProvisionState(source, {
+    create: createSubContainerState,
+    label: "SubContainerProvider",
+    reuse: canReuseSubContainerState
+  });
+  return react.createElement(containerProvider.ContainerReactContext.Provider, {
+    value: state.container
+  }, (_a = props.children) !== null && _a !== void 0 ? _a : null);
+}
+/**
+ * Selects the child-container state that should be exposed for this render.
+ *
+ * @param current - Previously exposed state, if any.
+ * @param source - Current provider source.
+ * @param disposed - Child containers already disposed by this provider.
+ * @returns Existing or replacement child-container state.
+ */
+function canReuseSubContainerState(current, source, disposed) {
+  return !disposed.has(current.container) && current.source.parent === source.parent && containerProvider.shallowEqualArrays(source.entries, current.source.entries);
+}
+/**
+ * Creates a child container, applies seeds, and binds entries.
+ *
+ * @param source - Parent container plus child bindings.
+ * @returns Child-container state ready for context.
+ */
+function createSubContainerState(source) {
+  var container = core.createContainer({
+    entries: source.entries,
+    parent: source.parent,
+    seeds: source.seeds
+  });
+  return {
+    source: source,
+    container: container,
+    owned: true
+  };
+}
+
+/**
+ * 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.
+ */
+function ContainerActivator(props) {
+  var _a;
+  var container = useContainer();
+  var activatedContainerRef = react.useRef(null);
+  if (activatedContainerRef.current !== container) {
+    activatedContainerRef.current = container;
+    for (var _i = 0, _b = props.activate; _i < _b.length; _i++) {
+      var entry = _b[_i];
+      container.get(entry);
     }
-    // Snapshot props on mount to ensure binding stability.
-    // useState lazy initializer ensures it only runs once.
-    var initialPropsSnapshot = react.useState(function () {
-      return props;
-    })[0];
-    react.useMemo(function () {
-      // Seed must be applied BEFORE binding so @Inject(INITIAL_STATE_TOKEN) works during activation.
-      if (initialPropsSnapshot.seeds) {
-        core.applySeeds(iocContext.container, initialPropsSnapshot.seeds);
-      }
-      for (var _i = 0, entries_1 = entries; _i < entries_1.length; _i++) {
-        var entry = entries_1[_i];
-        if (!iocContext.container.isBound(core.getEntryToken(entry))) {
-          core.bindEntry(iocContext.container, entry);
-        }
-      }
-      if (activate) {
-        for (var _a = 0, activate_2 = activate; _a < activate_2.length; _a++) {
-          var eager = activate_2[_a];
-          iocContext.container.get(eager);
-        }
-      }
-    }, entries);
-    react.useEffect(function () {
-      // Re-apply state and re-bind if container was reset (e.g. StrictMode remount or HMR).
-      var didRebind = false;
-      if (initialPropsSnapshot.seeds) {
-        core.applySeeds(iocContext.container, initialPropsSnapshot.seeds);
-      }
-      for (var _i = 0, entries_2 = entries; _i < entries_2.length; _i++) {
-        var entry = entries_2[_i];
-        if (!iocContext.container.isBound(core.getEntryToken(entry))) {
-          didRebind = true;
-          core.bindEntry(iocContext.container, entry);
-        }
-      }
-      if (activate) {
-        for (var _a = 0, activate_3 = activate; _a < activate_3.length; _a++) {
-          var eager = activate_3[_a];
-          iocContext.container.get(eager);
-        }
-      }
-      // Increment revision to invalidate stale injection caches.
-      if (didRebind) {
-        iocContext.setRevision(function (r) {
-          return r + 1;
-        });
-      }
-      return function () {
-        for (var _i = 0, entries_3 = entries; _i < entries_3.length; _i++) {
-          var entry = entries_3[_i];
-          var token = core.getEntryToken(entry);
-          if (iocContext.container.isBound(token)) {
-            iocContext.container.unbind(token);
-          }
-        }
-        // Remove only this provider's targeted initial state entries.
-        if (initialPropsSnapshot.seeds) {
-          core.unapplySeeds(iocContext.container, initialPropsSnapshot.seeds);
-        }
-      };
-    }, entries);
-    return props.children;
   }
-  InjectablesProviderComponent.displayName = "InjectablesProvider";
-  return InjectablesProviderComponent;
+  return (_a = props.children) !== null && _a !== void 0 ? _a : null;
 }
 
 /**
- * Returns the current container revision.
+ * 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.
  *
- * @returns revision number
+ * @group Queries
+ *
+ * @returns A query dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const query: QueryCaller = useQueryCaller();
+ * const result: UserProfile = await query(GET_USER_PROFILE, { id: 123 });
+ * ```
  */
-function useContainerRevision() {
-  return useIocContext().revision;
+function useQueryCaller() {
+  var container = useContainer();
+  return react.useCallback(function (type, data) {
+    return container.get(core.QueryBus).query(type, data);
+  }, [container]);
 }
 
 /**
- * Subscribes a component to events.
+ * Returns a stable function to dispatch optional queries on the active container.
  *
- * @param type - event type to listen to
- * @param handler - event handler to invoke when event is emitted
+ * @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 });
+ * ```
  */
-function useEvent(type, handler) {
-  var typeRef = react.useRef(type);
-  var handlerRef = react.useRef(handler);
+function useOptionalQueryCaller() {
   var container = useContainer();
-  react.useEffect(function () {
-    typeRef.current = type;
-    handlerRef.current = handler;
-  });
-  react.useEffect(function () {
-    return container.get(core.EventBus).subscribe(function (event) {
-      var _a;
-      if (event.type === typeRef.current) {
-        (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, event);
-      }
-    });
-  }, [container, type]);
+  return react.useCallback(function (type, data) {
+    return container.get(core.QueryBus).queryOptional(type, data);
+  }, [container]);
 }
 
 /**
- * Subscribes a component to multiple event types.
+ * Registers a query handler for the component's lifetime.
  *
- * @param types - event types to filter by
- * @param handler - events handler
+ * @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.
+ *
+ * @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" };
+ * });
+ * ```
  */
-function useEvents(types, handler) {
-  var typesRef = react.useRef(types);
-  var handlerRef = react.useRef(handler);
+function useQueryHandler(type, handler) {
   var container = useContainer();
+  var handlerRef = react.useRef(handler);
   react.useEffect(function () {
-    typesRef.current = types;
     handlerRef.current = handler;
   });
   react.useEffect(function () {
-    return container.get(core.EventBus).subscribe(function (event) {
-      var _a;
-      if (typesRef.current.includes(event.type)) {
-        (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, event);
-      }
+    return container.get(core.QueryBus).register(type, function (data) {
+      return handlerRef.current(data);
     });
-  }, [container]);
+  }, [container, type]);
 }
 
 /**
- * Subscribes a component to all events without type filtering.
+ * 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
  *
- * @param handler - event handler invoked for every emitted event
+ * @returns A synchronous query dispatcher function.
+ *
+ * @example
+ * ```tsx
+ * const querySync: SyncQueryCaller = useSyncQueryCaller();
+ * const config: ApplicationConfig = querySync("GET_APP_CONFIG");
+ * ```
  */
-function useEventsHandler(handler) {
-  var handlerRef = react.useRef(handler);
+function useSyncQueryCaller() {
   var container = useContainer();
-  react.useEffect(function () {
-    handlerRef.current = handler;
-  });
-  react.useEffect(function () {
-    return container.get(core.EventBus).subscribe(function (event) {
-      var _a;
-      (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, event);
-    });
+  return react.useCallback(function (type, data) {
+    // Access the container-scoped QueryBus and execute the query.
+    return container.get(core.QueryBus).query(type, data);
   }, [container]);
 }
 
 /**
- * Returns a stable function to emit events.
+ * 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.
  *
- * @returns event emitter
+ * @example
+ * ```tsx
+ * const querySyncOptional: OptionalSyncQueryCaller = useOptionalSyncQueryCaller();
+ * const value: ThemePreference | null = querySyncOptional(GET_THEME_PREFERENCE);
+ * ```
  */
-function useEventEmitter() {
-  var container = useIocContext().container;
-  return react.useCallback(function (type, payload, from) {
-    container.get(core.EventBus).emit({
-      type: type,
-      payload: payload,
-      from: from
-    });
+function useOptionalSyncQueryCaller() {
+  var container = useContainer();
+  return react.useCallback(function (type, data) {
+    return container.get(core.QueryBus).queryOptional(type, data);
   }, [container]);
 }
 
-exports.IocProvider = iocProvider.IocProvider;
-exports.createInjectablesProvider = createInjectablesProvider;
+exports.ContainerProvider = containerProvider.ContainerProvider;
+exports.ContainerActivator = ContainerActivator;
+exports.SubContainerProvider = SubContainerProvider;
 exports.useCommandCaller = useCommandCaller;
 exports.useCommandHandler = useCommandHandler;
 exports.useContainer = useContainer;
-exports.useContainerRevision = useContainerRevision;
 exports.useEvent = useEvent;
 exports.useEventEmitter = useEventEmitter;
 exports.useEvents = useEvents;
@@ -391,5 +629,7 @@ exports.useOptionalQueryCaller = useOptionalQueryCaller;
 exports.useOptionalSyncQueryCaller = useOptionalSyncQueryCaller;
 exports.useQueryCaller = useQueryCaller;
 exports.useQueryHandler = useQueryHandler;
+exports.useRootContainer = useRootContainer;
+exports.useScope = useScope;
 exports.useSyncQueryCaller = useSyncQueryCaller;
 //# sourceMappingURL=index.js.map