use-typed-event 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominik Rycharski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,516 @@
+# use-typed-event
+
+[![CI](https://github.com/doryski/use-typed-event/actions/workflows/ci.yml/badge.svg)](https://github.com/doryski/use-typed-event/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/use-typed-event)](https://www.npmjs.com/package/use-typed-event)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Minimal TS-native typed event emitter with **first-class React hooks**.
+> End-to-end typed event map, correctly-typed wildcard, void events, `waitFor`,
+> zero dependencies: **750 B gzipped core, 1,072 B gzipped React entry**.
+
+## Why
+
+The existing options make you pick between typing, size, and React integration:
+
+- **mitt** and **nanoevents** are wonderfully tiny, but ship **no React glue**:
+  wiring a component to an event means a manual `useState` + `useEffect` in every
+  component. And mitt's wildcard handler types the payload as a union of all
+  payloads without narrowing by name.
+
+`use-typed-event` gives you all three: a single `EventMap` typed end-to-end
+(`emit`, `on`, `once`, `off`, `waitFor`, and the wildcard all check against the same
+map), a wildcard whose payload **narrows** when you narrow the name, `void` events
+that take no payload argument, promise-based `waitFor` with `AbortSignal` support,
+and two zero-wiring React hooks (`useEvent`, `useEventState`), all with zero runtime
+dependencies.
+
+## Installation
+
+```bash
+pnpm add use-typed-event
+# or
+npm install use-typed-event
+```
+
+Requires Node ≥ 20. Ships dual ESM + CJS builds with TypeScript types and has zero
+runtime dependencies. `react` (^18 or ^19) is an **optional peer dependency**:
+the core `use-typed-event` entry works without React; only the
+`use-typed-event/react` entry needs it.
+
+## Usage
+
+### Core emitter
+
+```ts
+import { createEmitter } from "use-typed-event"
+
+type Events = {
+  "cart.add": { sku: string; qty: number }
+  "user.login": { id: string }
+  "app.ready": void
+}
+
+const emitter = createEmitter<Events>()
+
+const unsubscribe = emitter.on("cart.add", ({ sku, qty }) => {
+  console.log(`added ${qty} × ${sku}`)
+})
+
+emitter.once("user.login", ({ id }) => console.log(`first login: ${id}`))
+
+emitter.emit("cart.add", { sku: "A-1", qty: 2 })
+emitter.emit("app.ready") // void event, no payload argument
+
+unsubscribe() // idempotent, safe to call more than once
+emitter.off("user.login") // omit the handler to remove every handler for a name
+```
+
+Every subscription (`on`, `once`, `onAny`) returns an idempotent unsubscribe
+function. `off(name, handler)` removes the first registration of that handler,
+including `once` registrations, which are matched by the original handler
+reference you passed in.
+
+#### Typed wildcard with narrowing
+
+`onAny` receives `(name, payload)` for every emit; narrowing on `name` narrows
+`payload` to the mapped type:
+
+```ts
+emitter.onAny((name, payload) => {
+  if (name === "cart.add") {
+    console.log(payload.qty) // payload is { sku: string; qty: number } here
+  }
+})
+```
+
+Named handlers are delivered first, then wildcard handlers.
+
+#### `waitFor` with `AbortSignal`
+
+`waitFor(name)` resolves with the next payload of `name`. Pass a `signal` to stop
+waiting; the promise rejects with `signal.reason`:
+
+```ts
+const { id } = await emitter.waitFor("user.login")
+
+// give up after 5 seconds
+await emitter.waitFor("app.ready", { signal: AbortSignal.timeout(5_000) })
+```
+
+An already-aborted signal rejects immediately without subscribing.
+
+### Typed selectors
+
+Event names are just strings, so every API above works with a plain string key.
+But magic strings give up autocomplete and break silently on rename. Pass
+`createSelectors<E>()` a typed accessor instead: each dot-access maps to the
+`"."` separator in the key, so `events.cart.add === "cart.add"`.
+
+```ts
+import { createEmitter, createSelectors } from "use-typed-event"
+
+type Events = {
+  "cart.add": { sku: string; qty: number }
+  "user.login": { id: string }
+  "app.ready": void
+}
+
+const emitter = createEmitter<Events>()
+const events = createSelectors<Events>()
+
+emitter.emit(events.cart.add, { sku: "A-1", qty: 2 }) // same as emit("cart.add", ...)
+emitter.on(events.user.login, ({ id }) => console.log(id))
+await emitter.waitFor(events.app.ready)
+```
+
+Selectors resolve to the exact string literal (`events.cart.add` has type
+`"cart.add"`), so payload inference is identical to the string form: you get
+autocomplete while typing the path and a compile error if a key is renamed or
+removed. Strings and selectors are **fully interchangeable and share state**:
+`emit(events.cart.add, p)` reaches `on("cart.add", …)` and vice-versa, because
+both normalize to the same key.
+
+#### Leaf-and-prefix collisions
+
+When a key is **both a leaf and a namespace prefix** (an event map containing
+both `"cart"` and `"cart.add"`), `events.cart` can't be both a string leaf and a
+navigable object. The selector keeps navigating deeper and exposes the leaf
+through the reserved **`$`** accessor:
+
+```ts
+type Events = {
+  cart: { total: number }
+  "cart.add": { sku: string }
+}
+
+const events = createSelectors<Events>()
+
+emitter.emit(events.cart.$, { total: 5 })    // the "cart" leaf; events.cart.$ is typed "cart"
+emitter.emit(events.cart.add, { sku: "A-1" }) // still navigates to "cart.add"
+```
+
+`$` is fully type-checked (`events.cart.$` has type `"cart"` with the right
+payload) and works at any depth (`events.cart.item.$`). It is a **reserved**
+segment, so avoid an event key with a literal `$` segment. If you'd rather not
+use it, the plain string form (`emit("cart", …)`) always works, or you can avoid
+the collision by namespacing the leaf (e.g. `"cart.total"` instead of `"cart"`).
+
+### React hooks
+
+The `use-typed-event/react` entry gives you a bus factory whose hooks are already
+bound to the emitter: no provider, no context, no wiring:
+
+```tsx
+import { createEventBus } from "use-typed-event/react"
+
+type Events = {
+  "cart.add": { sku: string; qty: number }
+  "counter.changed": number
+}
+
+const bus = createEventBus<Events>()
+
+const CartBadge = () => {
+  const [lastAdd, setLastAdd] = bus.useEventState("cart.add")
+  return (
+    <button onClick={() => setLastAdd({ sku: "A-1", qty: 1 })}>
+      {lastAdd ? lastAdd.sku : "empty"}
+    </button>
+  )
+}
+
+const LoginToast = () => {
+  bus.useEvent("cart.add", ({ sku }) => showToast(`added ${sku}`))
+  return null
+}
+
+// emit from anywhere: event handlers, effects, non-React code
+bus.emit("cart.add", { sku: "A-1", qty: 2 })
+```
+
+The bus also exposes [typed selectors](#typed-selectors) as `bus.events`, so you
+can drop magic strings on the React side too. Selector and string forms address
+the same event and share state:
+
+```tsx
+bus.emit(bus.events.cart.add, { sku: "A-1", qty: 2 })
+const [lastAdd] = bus.useEventState(bus.events.cart.add)
+bus.useEvent(bus.events.cart.add, ({ sku }) => showToast(`added ${sku}`))
+```
+
+- **`useEventState(name)`** returns a `[value, setValue]` tuple. `value` is the
+  last emitted payload as React state (`undefined` until the first emit).
+  Payloads emitted **before** the component mounts are still visible; the bus
+  records the last payload of every event.
+- **`useEventState(name, initialValue)`** types `value` as `E[K]` (no
+  `undefined`). The initial value is pinned on the first render; later changes
+  to it are ignored.
+- **`setValue` emits on the bus**: it is `emit(name, ...)` in disguise, not
+  local state, so **every** subscriber of the event updates, not just the
+  calling component. Its argument follows the same rules as `emit`: none for
+  `void` events, optional when `undefined` is allowed, required otherwise. It
+  is referentially stable across renders for a given `name`.
+
+```tsx
+const [count, setCount] = bus.useEventState("counter.changed", 0) // count: number, not number | undefined
+setCount(count + 1) // === bus.emit("counter.changed", count + 1)
+```
+
+- **`useEvent(name, handler)`** subscribes for the component's lifetime. The
+  latest `handler` is always invoked; changing its identity never resubscribes,
+  so you can pass inline closures freely. Changing `name` resubscribes.
+
+#### Binding hooks to a shared core emitter
+
+If an emitter already exists (e.g. shared with non-React code), bind hooks to it
+with `createEventHooks`:
+
+```ts
+import { createEmitter } from "use-typed-event"
+import { createEventHooks } from "use-typed-event/react"
+
+const emitter = createEmitter<Events>()
+const { useEvent, useEventState } = createEventHooks(emitter)
+```
+
+Note: `createEventHooks` installs a wildcard recorder on the emitter so
+`useEventState` can see payloads emitted before any hook mounts. Calling
+`emitter.clear()` directly also removes that recorder, so prefer `createEventBus`,
+whose `clear` keeps recording intact (see below).
+
+### Semantics you should know
+
+#### Mutation during emit
+
+Delivery for an in-flight emit is stable: handlers **added during an emit are not
+called** for that emit, and handlers **removed during an emit are still called**
+for it (removal is copy-on-write). Both take effect from the next emit. A `once`
+handler is unsubscribed before it runs, so it fires exactly once even if its own
+emit re-enters.
+
+#### Error propagation
+
+Handlers are not wrapped in `try`/`catch`: a throwing handler propagates the
+error to the `emit` caller and stops delivery to the remaining handlers for that
+emit. If you need isolation, catch inside the handler.
+
+#### `clear()` semantics
+
+`bus.clear()` removes every handler (**including subscriptions of currently
+mounted hooks**) and forgets all recorded payloads, then reinstalls the payload
+recorder so subsequent emits keep being recorded. Mounted `useEventState`
+components are **not notified**: they keep showing their current value and stop
+receiving emits until they resubscribe (a `name` change or a remount). Components
+mounted after `clear()` see the initial value again.
+
+#### Last-payload memory (dynamic event names)
+
+The bus records the last payload of **every emitted event name** for its
+lifetime. With a fixed, finite event map this is a few map entries; but if you
+emit under high-cardinality or dynamically generated names, the map grows without
+bound until `clear()` is called.
+
+#### Removed-handler tombstones (dynamic event names)
+
+The core emitter has a related property: removing a handler tombstones the
+event name's map slot instead of deleting the key; only `off(name)` and
+`clear()` truly delete. With a fixed event map this is negligible, but
+emitting or subscribing under unbounded unique names retains a map key per
+name for the emitter's lifetime.
+
+#### SSR
+
+`useEventState` is built on `useSyncExternalStore` and provides a
+`getServerSnapshot` that returns the initial value (or `undefined` without one),
+so server rendering works out of the box and hydrates consistently.
+
+#### Same-value emits don't re-render
+
+`useEventState` re-renders only when the payload changes by `Object.is`; emitting
+the same value twice does not re-render. If you need to react to **every
+occurrence** of an event (e.g. `emit("save")` twice in a row), use `useEvent`,
+which invokes the handler on every emit regardless of the payload.
+
+#### Known type limitation: unions mixing `void` and payload events
+
+When the event name is a union mixing a `void` event with payload-carrying ones
+(e.g. `emit(cond ? "app.ready" : "user.login")`), the payload type becomes a union
+containing `void`, which turns the payload argument optional: the call compiles
+with zero arguments even though `"user.login"` alone requires one. This
+non-distributive form of `PayloadArgs` is a deliberate ergonomics tradeoff;
+call `emit` with a literal name to keep full checking.
+
+## API reference
+
+### `use-typed-event` (core)
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `createEmitter` | `createEmitter<E extends EventMap>(): Emitter<E>` | Creates a typed emitter for the event map `E`. |
+| `createSelectors` | `createSelectors<E extends EventMap>(): EventSelectors<E>` | Typed accessor whose dot-path resolves to the event key (`events.cart.add === "cart.add"`); interchangeable with string keys. |
+| `Emitter.on` | `on(name, handler): Unsubscribe` | Registers a handler; returns an idempotent unsubscribe. |
+| `Emitter.once` | `once(name, handler): Unsubscribe` | Invoked at most once; unsubscribed before it runs. |
+| `Emitter.off` | `off(name, handler?): void` | Removes the first registration of `handler` (matches `once` by original reference), or every handler for `name` when omitted. |
+| `Emitter.emit` | `emit(name, ...payload): void` | Payload argument is omitted for `void` events, optional when `undefined` is allowed, required otherwise. Named handlers run before wildcard handlers. |
+| `Emitter.onAny` | `onAny(handler): Unsubscribe` | Wildcard handler `(name, payload)`; narrowing `name` narrows `payload`. |
+| `Emitter.waitFor` | `waitFor(name, options?): Promise<E[K]>` | Resolves with the next payload; `options.signal` rejects with `signal.reason` on abort. |
+| `Emitter.clear` | `clear(): void` | Removes every named and wildcard handler. |
+| Types | `EventMap`, `Emitter`, `EventHandler`, `AnyHandler`, `EventTuple`, `PayloadArgs`, `Unsubscribe`, `WaitForOptions`, `EventSelectors` | |
+
+### `use-typed-event/react`
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `createEventBus` | `createEventBus<E extends EventMap>(): EventBus<E>` | Fresh emitter + bound hooks in one object; its `clear()` also forgets recorded payloads and keeps recording working. |
+| `bus.events` | `EventSelectors<E>` | Typed selectors bound to the bus (`bus.events.cart.add === "cart.add"`); usable anywhere a string key is, including `useEvent` / `useEventState`. |
+| `createEventHooks` | `createEventHooks<E>(emitter: Emitter<E>): EventHooks<E>` | Binds `useEvent` / `useEventState` to an existing emitter (installs a payload recorder). |
+| `useEvent` | `useEvent(name, handler): void` | Subscribes for the component's lifetime; always calls the latest handler, never resubscribes on handler identity change. |
+| `useEventState` | `useEventState(name): [E[K] \| undefined, setter]`<br>`useEventState(name, initialValue): [E[K], setter]` | `[value, setValue]` tuple: last emitted payload as state (`Object.is`-deduplicated, SSR-safe) plus a stable setter that emits on the bus, typed `setter: (...args: PayloadArgs<E[K]>) => void`. |
+| Types | `EventBus`, `EventHooks`, `UseEvent`, `UseEventState`, `EventSelectors` (+ re-exports everything from the core entry) | |
+
+## Benchmark: emitter throughput
+
+All three comparison suites below can also be viewed as a single self-contained
+HTML dashboard: `cd benchmarks/compare && pnpm report` generates and opens
+`benchmarks/compare/report/report.html`.
+
+Self-benchmark (tinybench, warmup 100 ms, measure 500 ms per task, node v22.14.0):
+
+```
+Task               ops/sec     ±rme%  mean ns
+-----------------  ----------  -----  -------
+emit 1 handler     24,081,165  0.00   39.0
+emit 10 handlers   19,779,190  0.02   58.1
+emit 100 handlers  1,477,465   0.02   843.2
+emit with 1 onAny  23,676,997  0.01   46.2
+on+off churn       21,670,755  0.01   57.1
+once+emit          19,606,729  0.02   60.2
+```
+
+Reproduce with:
+
+```bash
+pnpm bench
+```
+
+## Benchmark: vs. the field
+
+Compared against mitt, nanoevents, eventemitter3, tseep, and emittery (tinybench,
+warmup 100 ms / measure 300 ms per task, node v22.14.0). Caveat: **emittery's
+`emit` returns a promise and each call is awaited**, structurally slower than
+sync dispatch; it trades raw speed for async listener support. `n/a` = library
+lacks the capability.
+
+### emit 1 listener
+
+```
+Library                          ops/sec    ±rme%     mean ns
+  nanoevents                  24,470,300     3.71        37.0
+* use-typed-event             23,995,107     0.54        39.8
+  tseep                       23,877,486     1.99        40.3
+  eventemitter3               21,846,900     0.21        50.4
+  mitt                        20,513,520     9.48        82.1
+  emittery [async]               911,036     4.52       1,315
+```
+
+### emit 10 listeners
+
+```
+  tseep                       23,855,446     0.72        41.8
+  nanoevents                  20,947,671     0.36        53.7
+* use-typed-event             20,768,976     0.38        55.2
+  mitt                        13,589,125     1.59        88.0
+  eventemitter3                6,350,488     0.38       164.4
+  emittery [async]               326,960    13.36       3,811
+```
+
+### emit 100 listeners
+
+```
+  tseep                       18,406,249     0.26        63.0
+* use-typed-event              5,531,539     0.24       187.4
+  nanoevents                   3,256,819     7.18       386.0
+  mitt                         2,460,712     4.17       515.9
+  eventemitter3                  865,394     0.24       1,182
+  emittery [async]                43,537    15.44      27,439
+```
+
+### on+off churn
+
+```
+  eventemitter3               19,605,334     7.38        71.7
+  nanoevents                  18,706,724     0.64        63.5
+* use-typed-event             17,746,065     0.87        67.6
+  mitt                        12,683,408     5.14        96.4
+  tseep                       10,793,682     1.96       110.4
+  emittery [async]               724,642     7.17       1,665
+```
+
+### once+emit
+
+```
+  tseep                       20,713,625    17.36        87.3
+  eventemitter3               17,059,185     2.04        74.5
+* use-typed-event             16,363,474     9.90        95.8
+  emittery [async]               340,328     6.85       3,329
+  mitt                               n/a  (no once)
+  nanoevents                         n/a  (no once)
+```
+
+### wildcard emit
+
+```
+* use-typed-event             23,900,276     0.43        41.7
+  mitt                        19,361,322     9.70        73.6
+  emittery [async]               884,338     2.85       1,269
+  nanoevents / eventemitter3 / tseep   n/a  (no wildcard)
+```
+
+Read honestly: use-typed-event has the **fastest wildcard emit** of the
+libraries that support one (23.9M vs mitt's 18.8–19.4M) and the **best
+non-codegen result on emit with 100 listeners** (~1.7× nanoevents). tseep
+leads emit-heavy scenarios only through runtime code generation
+(`new Function`); we deliberately avoid codegen for CSP compatibility and
+bundle size. **once+emit** is statistically tied with eventemitter3 (the best
+non-codegen result), ~1.25–1.3× behind codegen tseep. **on+off churn** is
+borderline-tied with eventemitter3 (within 1.08–1.12×). On plain emit with 1
+or 10 listeners, use-typed-event lands 2–4% behind nanoevents, the
+structural cost of supporting `once` and `onAny`, which nanoevents lacks.
+
+Reproduce with:
+
+```bash
+cd benchmarks/compare && pnpm install && pnpm bench
+```
+
+## Benchmark: React render behavior
+
+25 hot + 25 cold subscribers, 100 bursts × 10 fires per burst (one `act` per
+burst), 5 runs (5 discarded warmups) → median ± sd, mount excluded. Run on
+**react@19.2.7**.
+
+```
+Driver                     hot renders    cold renders         commits       profiler ms           wall ms
+* use-typed-event              2500 ±0            0 ±0          100 ±0        4.91 ±0.32       11.53 ±0.83
+  use-bus                      2500 ±0            0 ±0          100 ±0        4.69 ±0.34       11.23 ±0.61
+  zustand                      2500 ±0            0 ±0          100 ±0        5.52 ±0.40       12.42 ±1.05
+```
+
+The same run on react@18.3.1 gives statistically tied profiler times per driver
+(within overlapping ±sd) with wall times uniformly ~1–2 ms lower; React
+version does not change the ranking or the render/commit counts.
+
+Driver notes:
+
+- **use-typed-event**: `createEventBus` + `useEventState`, no provider, no extra wiring.
+- **use-bus**: `useBus` only invokes a callback, so rendering the payload needs a
+  manual `useState` per component (the wiring a real user writes).
+- **zustand**: **not an event bus**; included as a state-management baseline.
+
+Read honestly: all drivers are within ~1–3 ms wall time and render/commit counts
+are identical; every driver achieves perfect subscription isolation (cold
+subscribers never re-render). The claim is **"no render-count penalty vs the
+rivals, with zero wiring and full typing"**, not a speed win.
+
+Reproduce with:
+
+```bash
+cd benchmarks/compare && pnpm install && pnpm bench:react
+```
+
+## Benchmark: bundle size
+
+esbuild, minified ESM, `react`/`react-dom` externalized:
+
+```
+Library                          min B    min+gzip B
+  nanoevents                       359           255
+  mitt                             451           278
+  use-bus                          587           390
+  zustand                          785           474
+* use-typed-event                1,456           750
+* use-typed-event/react          2,140         1,072
+  eventemitter3                  3,503         1,362
+  tseep                         18,284         3,703
+  emittery                      10,659         3,756
+```
+
+nanoevents and mitt stay smaller, but they also ship fewer capabilities (no `once`
+for either, no React hooks, and mitt's wildcard is untyped by name). The React
+entry at 1,072 B gzipped is the only one in this table that ships built-in
+hooks.
+
+Reproduce with:
+
+```bash
+cd benchmarks/compare && pnpm install && pnpm bench:size
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for development
+setup, testing commands, and coding conventions.
+
+## License
+
+[MIT](./LICENSE) © Dominik Rycharski

package/dist/chunk-ZRE57KHP.js

@@ -0,0 +1,133 @@
+// 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([]);
+
+export {
+  keyOf,
+  createEmitter,
+  createSelectors
+};