use-typed-event 0.1.0

package/dist/index.cjs

@@ -0,0 +1,159 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createEmitter: () => createEmitter,
+  createSelectors: () => createSelectors
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/emitter.ts
+var matchesHandler = (registered, target) => registered === target || typeof registered !== "function" && registered.handler === target;
+var keyOf = (name) => typeof name === "string" ? name : String(name);
+var copyWithout = (list, index) => {
+  const length = list.length;
+  const next = new Array(length - 1);
+  for (let i = 0; i < index; i++) next[i] = list[i];
+  for (let i = index + 1; i < length; i++) next[i - 1] = list[i];
+  return next;
+};
+var createEmitter = () => {
+  const handlers = /* @__PURE__ */ new Map();
+  let anyHandlers = [];
+  const removeFromList = (name, slot, target) => {
+    const length = slot.length;
+    let index = 0;
+    while (index < length && !matchesHandler(slot[index], target)) index++;
+    if (index === length) return;
+    if (length === 2) handlers.set(name, slot[1 - index]);
+    else handlers.set(name, copyWithout(slot, index));
+  };
+  const removeNamed = (name, target) => {
+    const slot = handlers.get(name);
+    if (slot === void 0) return;
+    if (Array.isArray(slot)) removeFromList(name, slot, target);
+    else if (matchesHandler(slot, target)) handlers.set(name, void 0);
+  };
+  const subscribe = (name, entry) => {
+    const key = keyOf(name);
+    const slot = handlers.get(key);
+    if (slot === void 0) handlers.set(key, entry);
+    else if (Array.isArray(slot)) slot.push(entry);
+    else handlers.set(key, [slot, entry]);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const current = handlers.get(key);
+      if (current === entry) handlers.set(key, void 0);
+      else if (Array.isArray(current)) removeFromList(key, current, entry);
+    };
+  };
+  const once = (name, handler) => subscribe(keyOf(name), { handler });
+  const off = (name, handler) => {
+    const key = keyOf(name);
+    if (!handler) {
+      handlers.delete(key);
+      return;
+    }
+    removeNamed(key, handler);
+  };
+  const emit = (name, payload) => {
+    const key = keyOf(name);
+    const slot = handlers.get(key);
+    if (slot !== void 0) {
+      if (typeof slot === "function") slot(payload);
+      else if (Array.isArray(slot)) {
+        const length = slot.length;
+        for (let i = 0; i < length; i++) {
+          const entry = slot[i];
+          if (typeof entry === "function") entry(payload);
+          else {
+            removeNamed(key, entry);
+            entry.handler(payload);
+          }
+        }
+      } else {
+        handlers.set(key, void 0);
+        slot.handler(payload);
+      }
+    }
+    const anyList = anyHandlers;
+    const anyLength = anyList.length;
+    for (let i = 0; i < anyLength; i++) anyList[i](key, payload);
+  };
+  const onAny = (handler) => {
+    anyHandlers.push(handler);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const index = anyHandlers.indexOf(handler);
+      if (index !== -1) anyHandlers = copyWithout(anyHandlers, index);
+    };
+  };
+  const waitFor = (name, options) => {
+    const key = keyOf(name);
+    const signal = options?.signal;
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        unsubscribe();
+        reject(signal?.reason);
+      };
+      const unsubscribe = once(key, (payload) => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve(payload);
+      });
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  };
+  const clear = () => {
+    handlers.clear();
+    anyHandlers = [];
+  };
+  return {
+    on: subscribe,
+    once,
+    off,
+    emit,
+    onAny,
+    waitFor,
+    clear
+  };
+};
+
+// src/selectors.ts
+var build = (path) => new Proxy({}, {
+  get(_t, prop) {
+    if (prop === Symbol.toPrimitive || prop === "toString" || prop === "valueOf")
+      return () => path.join(".");
+    if (prop === "$") return path.join(".");
+    if (typeof prop === "symbol") return void 0;
+    return build([...path, prop]);
+  }
+});
+var createSelectors = () => build([]);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createEmitter,
+  createSelectors
+});

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+/** Maps event names to their payload types. Use `void` for payload-less events. */
+type EventMap = Record<string, unknown>;
+/**
+ * Argument tuple for a payload of type `P`: no argument for `void` events,
+ * an optional argument when `undefined` is part of the payload type, and a
+ * required argument otherwise.
+ */
+type PayloadArgs<P> = [P] extends [void] ? [] : undefined extends P ? [payload?: P] : [payload: P];
+/** Handler invoked with the payload of a single event. */
+type EventHandler<P> = (payload: P) => void;
+/** Union of `[name, payload]` tuples across every event in the map. */
+type EventTuple<E extends EventMap> = {
+    [K in keyof E & string]: [name: K, payload: E[K]];
+}[keyof E & string];
+/**
+ * Wildcard handler receiving `(name, payload)` for every emit. Narrowing on
+ * `name` narrows `payload` to the mapped type.
+ */
+type AnyHandler<E extends EventMap> = (...event: EventTuple<E>) => void;
+/** Detaches a previously registered handler. Safe to call more than once. */
+type Unsubscribe = () => void;
+/** Options for {@link Emitter.waitFor}. */
+type WaitForOptions = {
+    /** Rejects the pending promise with `signal.reason` when aborted. */
+    signal?: AbortSignal;
+};
+/** A typed event emitter over the event map `E`. */
+type Emitter<E extends EventMap> = {
+    /** Registers `handler` for `name`. Returns an idempotent unsubscribe. */
+    on: <K extends keyof E & string>(name: K, handler: EventHandler<E[K]>) => Unsubscribe;
+    /** Registers `handler` for `name`, invoked at most once. Returns an idempotent unsubscribe. */
+    once: <K extends keyof E & string>(name: K, handler: EventHandler<E[K]>) => Unsubscribe;
+    /**
+     * Removes the first registration of `handler` for `name` — including
+     * `once` registrations, matched by their original handler reference — or
+     * every handler for `name` when omitted.
+     */
+    off: <K extends keyof E & string>(name: K, handler?: EventHandler<E[K]>) => void;
+    /** Emits `name`, delivering the payload to named handlers first, then wildcard handlers. */
+    emit: <K extends keyof E & string>(name: K, ...args: PayloadArgs<E[K]>) => void;
+    /** Registers a wildcard handler for every event. Returns an idempotent unsubscribe. */
+    onAny: (handler: AnyHandler<E>) => Unsubscribe;
+    /** Resolves with the next payload of `name`; rejects with `signal.reason` on abort. */
+    waitFor: <K extends keyof E & string>(name: K, options?: WaitForOptions) => Promise<E[K]>;
+    /** Removes every named and wildcard handler. */
+    clear: () => void;
+};
+
+/**
+ * Creates a typed event emitter for the event map `E`.
+ */
+declare const createEmitter: <E extends EventMap>() => Emitter<E>;
+
+type After<K extends string, Prefix extends string> = K extends `${Prefix}${infer R}` ? R : never;
+type HeadSeg<R extends string> = R extends `${infer H}.${string}` ? H : R;
+/** The exact event key at `Prefix + Head`, or `never` if no such event exists. */
+type Leaf<E extends EventMap, Prefix extends string, Head extends string> = `${Prefix}${Head}` & (keyof E & string);
+/** The nested selector under `Prefix + Head + "."`, or `never` if nothing nests there. */
+type Deeper<E extends EventMap, Prefix extends string, Head extends string> = After<keyof E & string, `${Prefix}${Head}.`> extends never ? never : EventSelectors<E, `${Prefix}${Head}.`>;
+/**
+ * Nested selector object mirroring the dotted event keys of `E`. Each leaf is
+ * typed as its exact event key literal — `events.cart.add` has type `"cart.add"`
+ * — driving the same payload inference as the raw string. A key that is both a
+ * leaf and a prefix exposes its own key via the reserved `$` accessor:
+ * `events.cart.$` has type `"cart"`.
+ */
+type EventSelectors<E extends EventMap, Prefix extends string = ""> = {
+    [Head in HeadSeg<After<keyof E & string, Prefix>>]: [Leaf<E, Prefix, Head>] extends [never] ? Deeper<E, Prefix, Head> : [Deeper<E, Prefix, Head>] extends [never] ? Leaf<E, Prefix, Head> : Deeper<E, Prefix, Head> & {
+        readonly $: Leaf<E, Prefix, Head>;
+    };
+};
+/**
+ * Builds a typed selector proxy for the event map `E`. Property access
+ * accumulates a path that coerces to the dotted event key —
+ * `String(createSelectors<E>().cart.add) === "cart.add"`. The reserved `$`
+ * accessor returns the current path as a plain string.
+ */
+declare const createSelectors: <E extends EventMap>() => EventSelectors<E>;
+
+export { type AnyHandler, type Emitter, type EventHandler, type EventMap, type EventSelectors, type EventTuple, type PayloadArgs, type Unsubscribe, type WaitForOptions, createEmitter, createSelectors };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/** Maps event names to their payload types. Use `void` for payload-less events. */
+type EventMap = Record<string, unknown>;
+/**
+ * Argument tuple for a payload of type `P`: no argument for `void` events,
+ * an optional argument when `undefined` is part of the payload type, and a
+ * required argument otherwise.
+ */
+type PayloadArgs<P> = [P] extends [void] ? [] : undefined extends P ? [payload?: P] : [payload: P];
+/** Handler invoked with the payload of a single event. */
+type EventHandler<P> = (payload: P) => void;
+/** Union of `[name, payload]` tuples across every event in the map. */
+type EventTuple<E extends EventMap> = {
+    [K in keyof E & string]: [name: K, payload: E[K]];
+}[keyof E & string];
+/**
+ * Wildcard handler receiving `(name, payload)` for every emit. Narrowing on
+ * `name` narrows `payload` to the mapped type.
+ */
+type AnyHandler<E extends EventMap> = (...event: EventTuple<E>) => void;
+/** Detaches a previously registered handler. Safe to call more than once. */
+type Unsubscribe = () => void;
+/** Options for {@link Emitter.waitFor}. */
+type WaitForOptions = {
+    /** Rejects the pending promise with `signal.reason` when aborted. */
+    signal?: AbortSignal;
+};
+/** A typed event emitter over the event map `E`. */
+type Emitter<E extends EventMap> = {
+    /** Registers `handler` for `name`. Returns an idempotent unsubscribe. */
+    on: <K extends keyof E & string>(name: K, handler: EventHandler<E[K]>) => Unsubscribe;
+    /** Registers `handler` for `name`, invoked at most once. Returns an idempotent unsubscribe. */
+    once: <K extends keyof E & string>(name: K, handler: EventHandler<E[K]>) => Unsubscribe;
+    /**
+     * Removes the first registration of `handler` for `name` — including
+     * `once` registrations, matched by their original handler reference — or
+     * every handler for `name` when omitted.
+     */
+    off: <K extends keyof E & string>(name: K, handler?: EventHandler<E[K]>) => void;
+    /** Emits `name`, delivering the payload to named handlers first, then wildcard handlers. */
+    emit: <K extends keyof E & string>(name: K, ...args: PayloadArgs<E[K]>) => void;
+    /** Registers a wildcard handler for every event. Returns an idempotent unsubscribe. */
+    onAny: (handler: AnyHandler<E>) => Unsubscribe;
+    /** Resolves with the next payload of `name`; rejects with `signal.reason` on abort. */
+    waitFor: <K extends keyof E & string>(name: K, options?: WaitForOptions) => Promise<E[K]>;
+    /** Removes every named and wildcard handler. */
+    clear: () => void;
+};
+
+/**
+ * Creates a typed event emitter for the event map `E`.
+ */
+declare const createEmitter: <E extends EventMap>() => Emitter<E>;
+
+type After<K extends string, Prefix extends string> = K extends `${Prefix}${infer R}` ? R : never;
+type HeadSeg<R extends string> = R extends `${infer H}.${string}` ? H : R;
+/** The exact event key at `Prefix + Head`, or `never` if no such event exists. */
+type Leaf<E extends EventMap, Prefix extends string, Head extends string> = `${Prefix}${Head}` & (keyof E & string);
+/** The nested selector under `Prefix + Head + "."`, or `never` if nothing nests there. */
+type Deeper<E extends EventMap, Prefix extends string, Head extends string> = After<keyof E & string, `${Prefix}${Head}.`> extends never ? never : EventSelectors<E, `${Prefix}${Head}.`>;
+/**
+ * Nested selector object mirroring the dotted event keys of `E`. Each leaf is
+ * typed as its exact event key literal — `events.cart.add` has type `"cart.add"`
+ * — driving the same payload inference as the raw string. A key that is both a
+ * leaf and a prefix exposes its own key via the reserved `$` accessor:
+ * `events.cart.$` has type `"cart"`.
+ */
+type EventSelectors<E extends EventMap, Prefix extends string = ""> = {
+    [Head in HeadSeg<After<keyof E & string, Prefix>>]: [Leaf<E, Prefix, Head>] extends [never] ? Deeper<E, Prefix, Head> : [Deeper<E, Prefix, Head>] extends [never] ? Leaf<E, Prefix, Head> : Deeper<E, Prefix, Head> & {
+        readonly $: Leaf<E, Prefix, Head>;
+    };
+};
+/**
+ * Builds a typed selector proxy for the event map `E`. Property access
+ * accumulates a path that coerces to the dotted event key —
+ * `String(createSelectors<E>().cart.add) === "cart.add"`. The reserved `$`
+ * accessor returns the current path as a plain string.
+ */
+declare const createSelectors: <E extends EventMap>() => EventSelectors<E>;
+
+export { type AnyHandler, type Emitter, type EventHandler, type EventMap, type EventSelectors, type EventTuple, type PayloadArgs, type Unsubscribe, type WaitForOptions, createEmitter, createSelectors };

package/dist/index.js

@@ -0,0 +1,8 @@
+import {
+  createEmitter,
+  createSelectors
+} from "./chunk-ZRE57KHP.js";
+export {
+  createEmitter,
+  createSelectors
+};

package/dist/react.cjs

@@ -0,0 +1,234 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  createEmitter: () => createEmitter,
+  createEventBus: () => createEventBus,
+  createEventHooks: () => createEventHooks,
+  createSelectors: () => createSelectors
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/emitter.ts
+var matchesHandler = (registered, target) => registered === target || typeof registered !== "function" && registered.handler === target;
+var keyOf = (name) => typeof name === "string" ? name : String(name);
+var copyWithout = (list, index) => {
+  const length = list.length;
+  const next = new Array(length - 1);
+  for (let i = 0; i < index; i++) next[i] = list[i];
+  for (let i = index + 1; i < length; i++) next[i - 1] = list[i];
+  return next;
+};
+var createEmitter = () => {
+  const handlers = /* @__PURE__ */ new Map();
+  let anyHandlers = [];
+  const removeFromList = (name, slot, target) => {
+    const length = slot.length;
+    let index = 0;
+    while (index < length && !matchesHandler(slot[index], target)) index++;
+    if (index === length) return;
+    if (length === 2) handlers.set(name, slot[1 - index]);
+    else handlers.set(name, copyWithout(slot, index));
+  };
+  const removeNamed = (name, target) => {
+    const slot = handlers.get(name);
+    if (slot === void 0) return;
+    if (Array.isArray(slot)) removeFromList(name, slot, target);
+    else if (matchesHandler(slot, target)) handlers.set(name, void 0);
+  };
+  const subscribe = (name, entry) => {
+    const key = keyOf(name);
+    const slot = handlers.get(key);
+    if (slot === void 0) handlers.set(key, entry);
+    else if (Array.isArray(slot)) slot.push(entry);
+    else handlers.set(key, [slot, entry]);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const current = handlers.get(key);
+      if (current === entry) handlers.set(key, void 0);
+      else if (Array.isArray(current)) removeFromList(key, current, entry);
+    };
+  };
+  const once = (name, handler) => subscribe(keyOf(name), { handler });
+  const off = (name, handler) => {
+    const key = keyOf(name);
+    if (!handler) {
+      handlers.delete(key);
+      return;
+    }
+    removeNamed(key, handler);
+  };
+  const emit = (name, payload) => {
+    const key = keyOf(name);
+    const slot = handlers.get(key);
+    if (slot !== void 0) {
+      if (typeof slot === "function") slot(payload);
+      else if (Array.isArray(slot)) {
+        const length = slot.length;
+        for (let i = 0; i < length; i++) {
+          const entry = slot[i];
+          if (typeof entry === "function") entry(payload);
+          else {
+            removeNamed(key, entry);
+            entry.handler(payload);
+          }
+        }
+      } else {
+        handlers.set(key, void 0);
+        slot.handler(payload);
+      }
+    }
+    const anyList = anyHandlers;
+    const anyLength = anyList.length;
+    for (let i = 0; i < anyLength; i++) anyList[i](key, payload);
+  };
+  const onAny = (handler) => {
+    anyHandlers.push(handler);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const index = anyHandlers.indexOf(handler);
+      if (index !== -1) anyHandlers = copyWithout(anyHandlers, index);
+    };
+  };
+  const waitFor = (name, options) => {
+    const key = keyOf(name);
+    const signal = options?.signal;
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        unsubscribe();
+        reject(signal?.reason);
+      };
+      const unsubscribe = once(key, (payload) => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve(payload);
+      });
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  };
+  const clear = () => {
+    handlers.clear();
+    anyHandlers = [];
+  };
+  return {
+    on: subscribe,
+    once,
+    off,
+    emit,
+    onAny,
+    waitFor,
+    clear
+  };
+};
+
+// src/react/use-event.ts
+var import_react = require("react");
+var makeUseEvent = (emitter) => {
+  const useEvent = (name, handler) => {
+    const key = keyOf(name);
+    const handlerRef = (0, import_react.useRef)(handler);
+    (0, import_react.useEffect)(() => {
+      handlerRef.current = handler;
+    });
+    (0, import_react.useEffect)(() => emitter.on(key, (payload) => handlerRef.current(payload)), [key]);
+  };
+  return useEvent;
+};
+
+// src/react/use-event-state.ts
+var import_react2 = require("react");
+var makeUseEventState = (emitter, last) => {
+  function useEventState(name, initialValue) {
+    const initialRef = (0, import_react2.useRef)(initialValue);
+    const key = keyOf(name);
+    const subscribe = (0, import_react2.useCallback)(
+      (onStoreChange) => emitter.on(key, (payload) => {
+        last.set(key, payload);
+        onStoreChange();
+      }),
+      [key]
+    );
+    const getSnapshot = () => last.has(key) ? last.get(key) : initialRef.current;
+    const getServerSnapshot = () => initialRef.current;
+    const value = (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot);
+    const setValue = (0, import_react2.useCallback)(
+      (...args) => {
+        emitter.emit(key, ...args);
+      },
+      [key]
+    );
+    return [value, setValue];
+  }
+  return useEventState;
+};
+
+// src/selectors.ts
+var build = (path) => new Proxy({}, {
+  get(_t, prop) {
+    if (prop === Symbol.toPrimitive || prop === "toString" || prop === "valueOf")
+      return () => path.join(".");
+    if (prop === "$") return path.join(".");
+    if (typeof prop === "symbol") return void 0;
+    return build([...path, prop]);
+  }
+});
+var createSelectors = () => build([]);
+
+// src/react.ts
+var setUpHooks = (emitter) => {
+  const last = /* @__PURE__ */ new Map();
+  const record = (name, payload) => {
+    last.set(name, payload);
+  };
+  const installRecorder = () => {
+    emitter.onAny(record);
+  };
+  installRecorder();
+  const hooks = {
+    useEvent: makeUseEvent(emitter),
+    useEventState: makeUseEventState(emitter, last)
+  };
+  return { hooks, last, installRecorder };
+};
+var createEventHooks = (emitter) => setUpHooks(emitter).hooks;
+var createEventBus = () => {
+  const emitter = createEmitter();
+  const bus = { ...emitter };
+  const { hooks, last, installRecorder } = setUpHooks(bus);
+  const clear = () => {
+    emitter.clear();
+    last.clear();
+    installRecorder();
+  };
+  const events = createSelectors();
+  return Object.assign(bus, hooks, { clear, events });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createEmitter,
+  createEventBus,
+  createEventHooks,
+  createSelectors
+});

package/dist/react.d.cts

@@ -0,0 +1,50 @@
+import { EventMap, EventHandler, PayloadArgs, Emitter, EventSelectors } from './index.cjs';
+export { AnyHandler, EventTuple, Unsubscribe, WaitForOptions, createEmitter, createSelectors } from './index.cjs';
+
+/**
+ * Subscribes to an event for the lifetime of the component. The latest
+ * `handler` is always invoked.
+ */
+type UseEvent<E extends EventMap> = <K extends keyof E & string>(name: K, handler: EventHandler<E[K]>) => void;
+
+/**
+ * Returns a `[value, setValue]` tuple. `value` is the last emitted payload of
+ * the event as React state: without an `initialValue` it is `undefined` until
+ * the first emit. The `initialValue` is pinned on the first render; later
+ * changes to it are ignored. Emits carrying a value equal (`Object.is`) to the
+ * current one do not re-render.
+ *
+ * `setValue` is not local state — it emits the event on the bus
+ * (`emit(name, ...)`), so **every** subscriber of `name` updates, not just the
+ * calling component. Its argument follows `PayloadArgs`. It is referentially
+ * stable across renders for a given `name`.
+ */
+type UseEventState<E extends EventMap> = {
+    <K extends keyof E & string>(name: K): [value: E[K] | undefined, setValue: (...args: PayloadArgs<E[K]>) => void];
+    <K extends keyof E & string>(name: K, initialValue: E[K]): [value: E[K], setValue: (...args: PayloadArgs<E[K]>) => void];
+};
+
+/** React hooks bound to a single emitter. */
+type EventHooks<E extends EventMap> = {
+    /** Subscribes `handler` to `name` for the component's lifetime. */
+    useEvent: UseEvent<E>;
+    /**
+     * Returns a `[value, setValue]` tuple: the last emitted payload of `name`
+     * as React state, and a stable setter that emits `name` on the bus so
+     * every subscriber updates.
+     */
+    useEventState: UseEventState<E>;
+};
+/** A typed emitter with bound React hooks. */
+type EventBus<E extends EventMap> = Omit<Emitter<E>, "clear"> & EventHooks<E> & {
+    /** Removes every handler and forgets all recorded payloads. */
+    clear: () => void;
+    /** typed selector object; `bus.events.cart.add` === the event name `"cart.add"`. */
+    events: EventSelectors<E>;
+};
+/** Binds React hooks to an existing emitter. */
+declare const createEventHooks: <E extends EventMap>(emitter: Emitter<E>) => EventHooks<E>;
+/** Creates a fresh emitter with bound React hooks, spread into one bus object. */
+declare const createEventBus: <E extends EventMap>() => EventBus<E>;
+
+export { Emitter, type EventBus, EventHandler, type EventHooks, EventMap, EventSelectors, PayloadArgs, type UseEvent, type UseEventState, createEventBus, createEventHooks };

package/dist/react.d.ts

@@ -0,0 +1,50 @@
+import { EventMap, EventHandler, PayloadArgs, Emitter, EventSelectors } from './index.js';
+export { AnyHandler, EventTuple, Unsubscribe, WaitForOptions, createEmitter, createSelectors } from './index.js';
+
+/**
+ * Subscribes to an event for the lifetime of the component. The latest
+ * `handler` is always invoked.
+ */
+type UseEvent<E extends EventMap> = <K extends keyof E & string>(name: K, handler: EventHandler<E[K]>) => void;
+
+/**
+ * Returns a `[value, setValue]` tuple. `value` is the last emitted payload of
+ * the event as React state: without an `initialValue` it is `undefined` until
+ * the first emit. The `initialValue` is pinned on the first render; later
+ * changes to it are ignored. Emits carrying a value equal (`Object.is`) to the
+ * current one do not re-render.
+ *
+ * `setValue` is not local state — it emits the event on the bus
+ * (`emit(name, ...)`), so **every** subscriber of `name` updates, not just the
+ * calling component. Its argument follows `PayloadArgs`. It is referentially
+ * stable across renders for a given `name`.
+ */
+type UseEventState<E extends EventMap> = {
+    <K extends keyof E & string>(name: K): [value: E[K] | undefined, setValue: (...args: PayloadArgs<E[K]>) => void];
+    <K extends keyof E & string>(name: K, initialValue: E[K]): [value: E[K], setValue: (...args: PayloadArgs<E[K]>) => void];
+};
+
+/** React hooks bound to a single emitter. */
+type EventHooks<E extends EventMap> = {
+    /** Subscribes `handler` to `name` for the component's lifetime. */
+    useEvent: UseEvent<E>;
+    /**
+     * Returns a `[value, setValue]` tuple: the last emitted payload of `name`
+     * as React state, and a stable setter that emits `name` on the bus so
+     * every subscriber updates.
+     */
+    useEventState: UseEventState<E>;
+};
+/** A typed emitter with bound React hooks. */
+type EventBus<E extends EventMap> = Omit<Emitter<E>, "clear"> & EventHooks<E> & {
+    /** Removes every handler and forgets all recorded payloads. */
+    clear: () => void;
+    /** typed selector object; `bus.events.cart.add` === the event name `"cart.add"`. */
+    events: EventSelectors<E>;
+};
+/** Binds React hooks to an existing emitter. */
+declare const createEventHooks: <E extends EventMap>(emitter: Emitter<E>) => EventHooks<E>;
+/** Creates a fresh emitter with bound React hooks, spread into one bus object. */
+declare const createEventBus: <E extends EventMap>() => EventBus<E>;
+
+export { Emitter, type EventBus, EventHandler, type EventHooks, EventMap, EventSelectors, PayloadArgs, type UseEvent, type UseEventState, createEventBus, createEventHooks };