nanoeffects 0.3.0 → 0.5.0

package/llms-full.txt

@@ -0,0 +1,2645 @@
+# nanoeffects
+
+> A small typed event bus for JavaScript and TypeScript apps. Each handler runs as a task with an `AbortSignal`, so in-flight work can be cancelled. Policies (`latest`, `debounce`, ...) and effects (`retry`, `timeout`, ...) are plain functions.
+
+Rules that generated code often gets wrong:
+
+- The package is ESM only. There is no default export and no `require`.
+- `const unbind = bus.on("event", handler)` subscribes and returns the unsubscribe function. There is no `subscribe` or `addListener`.
+- A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
+- Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
+- Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; needs React), `nanoeffects/trace`, `nanoeffects/dev`.
+- `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
+
+---
+Source: docs/guide.md
+
+# Guide
+
+Climb one step at a time: small bus → policies → effects → commands and modules. Stop when your project has what it needs.
+
+| Your project | Stop after |
+| ------------ | ---------- |
+| Widget / prototype | §1–2 |
+| SPA with async UI | §3–4 |
+| Unreliable network / long flows | §5–6 |
+| Domain logic off the UI | §7–9 |
+
+Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
+
+## 1. Create a bus
+
+`on` subscribes. `emit` calls the subscribers. `on` returns the unsubscribe function.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+const unbind = bus.on("greet", (name) => {
+  console.log(`hello ${name}`);
+});
+
+bus.emit("greet", "Ada"); // hello Ada
+unbind();
+bus.emit("greet", "Bob"); // nobody listens
+```
+
+Handlers run at once, in subscription order.
+
+`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
+
+// once — runs at most once, then unsubscribes
+bus.once("ready", () => console.log("ready"));
+bus.emit("ready"); // ready
+bus.emit("ready"); // nobody listens
+
+bus.on("tick", () => {});
+bus.off(); // clear every subscription
+```
+
+## 2. Use the handler context
+
+The second argument is the **task** context for this call. Emit further events through it. Pass `ctx.signal` to `fetch` when you cancel work.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
+
+bus.on("moved", ({ x, y }, ctx) => {
+  if (x < 0) {
+    ctx.emit("outOfBounds", { x, y });
+  }
+});
+```
+
+`ctx` has `signal`, `abort`, `emit`, `on`, and `run`. An aborted task stops emitting and delivers no result.
+
+## 3. Abort the previous run with `latest`
+
+A handler is often called again before the last call finished (typing, double-clicks). A **policy** wraps the handler and decides what happens then. Start with `latest`: a newer call aborts the older one through `signal`.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// latest — a newer run aborts the older one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    await api.search(query, { signal });
+  }),
+);
+```
+
+Same `on`, same handler shape. More in [Policies](policies.md).
+
+## 4. Pick another policy when overlap differs
+
+| Policy | When calls overlap |
+| ------ | ------------------ |
+| `latest` | previous call is aborted |
+| `leading` | new calls drop while one runs |
+| `debounce` | runs after a pause |
+| `throttle` | at most once per window |
+| `queue` | one after another |
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest, queue, throttle } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// throttle — at most once per 100 ms
+bus.on("scroll", throttle(100, (position) => {
+  updateScrollbar(position);
+}));
+
+// debounce — run after 300 ms of quiet
+bus.on("typed", debounce(300, (text) => {
+  validate(text);
+}));
+
+// queue — one save after another, in order
+bus.on(
+  "save",
+  queue(async (draft, { signal }) => {
+    await api.save(draft, { signal });
+  }),
+);
+
+// nest: wait for quiet, then keep only the latest search
+const searchLatest = latest(async (query, { signal }) => {
+  await api.search(query, { signal });
+});
+bus.on("search", debounce(300, searchLatest));
+```
+
+Full options: [Policies](policies.md).
+
+## 5. Add retry and timeout
+
+An **effect** adds what an async handler usually needs. `retry` and `timeout` wrap a handler like a policy, so they go into `on` with no `ctx` in their arguments.
+
+```js
+import { createBus } from "nanoeffects";
+import { retry, timeout } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+const search = (query, { signal }) => api.search(query, { signal });
+
+// timeout — fail one try after 5 s
+const searchOnce = timeout(5000, search);
+// retry — up to 3 tries
+const searchWithRetry = retry(searchOnce, { times: 3 });
+
+// latest — a newer typed query aborts the whole retry chain
+bus.on("typed", latest(searchWithRetry));
+```
+
+When the handler itself needs the result, `ctx.run` runs the wrapped function as a child task (aborted with the parent):
+
+```js
+import { createBus } from "nanoeffects";
+import { retry, timeout } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+const search = (query, { signal }) => api.search(query, { signal });
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const load = retry(timeout(5000, search), { times: 3 });
+    const items = await ctx.run(load, query); // child task; aborted with this one
+    ctx.emit("results", items);
+  }),
+);
+```
+
+For one call in the middle of a body: `await retry(ctx, () => api.search(q, { signal: ctx.signal }))`. More in [Effects](effects.md).
+
+## 6. Run work in parallel or wait for an event
+
+```js
+import { createBus } from "nanoeffects";
+import { all, take } from "nanoeffects/effects";
+
+const bus = createBus();
+
+// all — run together; one failure cancels the rest
+bus.on("search", async (id, ctx) => {
+  const { user, posts } = await all(ctx, {
+    user: ({ signal }) => api.user(id, { signal }),
+    posts: ({ signal }) => api.posts(id, { signal }),
+  });
+  ctx.emit("loaded", { user, posts });
+});
+
+// take — wait for the next event of that name
+bus.on("typed", async (query, ctx) => {
+  const position = await take(ctx, "scroll");
+  ctx.emit("scrolled", { query, position });
+});
+```
+
+More in [Effects](effects.md).
+
+## 7. Name events three ways
+
+`emit` and `on` take a string, an object `{ type, payload }` (a Redux action fits), or a function with a `type` property (action creators and commands).
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction, createCommand } from "nanoeffects/actions";
+
+const bus = createBus();
+
+bus.emit("moved", { x: 1, y: 2 });
+bus.emit({ type: "moved", payload: { x: 2, y: 2 } });
+
+// createAction — names an event; calling it builds { type, payload }
+const moved = createAction("moved");
+bus.emit(moved({ x: 3, y: 2 }));
+bus.on(moved, ({ x }) => console.log(x));
+
+// createCommand — like an action, but emit runs a handler and returns its result
+const double = createCommand("math/double", (value) => value * 2);
+bus.emit(double(21)); // 42
+```
+
+Use strings for the plain case. Use objects when other code already builds actions. Use commands when you need a result from `emit`.
+
+## 8. Register a command handler
+
+A command may carry its handler, or only be a **contract** (name + types) with the work registered elsewhere — another file, or a fake in a test.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand, commandsPlugin } from "nanoeffects/actions";
+
+const getUser = createCommand("user/get"); // contract — no handler yet
+
+const bus = createBus();
+// commandsPlugin — registry of handlers for this bus
+const commands = bus.use(commandsPlugin());
+
+bus.emit(getUser("1")); // throws: No handler for command "user/get"
+
+const unregister = commands.handle(getUser, (id) => api.user(id));
+const user = await bus.emit(getUser("1"));
+
+unregister();
+```
+
+Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can register handlers and remove them on unmount. More in [Actions](actions.md).
+
+## 9. Mount a domain as a module
+
+**Problem.** A feature owns several things on the bus: who answers `getUser`, who listens to `greet`, maybe a command that already carries its handler. With plain `bus.on` / `commands.handle` you must remember every unsubscribe when the feature goes away. Miss one and listeners pile up.
+
+**When.** Domain logic lives on the bus, off the UI, and you need one mount / one unmount for that feature. Skip modules while a few top-level `bus.on` calls are enough.
+
+**What you do.** `createModule(name, setup)` describes the feature. `bus.use(modulePlugin([…]))` mounts it. `app.unmount(module)` undoes everything the setup registered.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand, createModule, modulePlugin } from "nanoeffects/actions";
+
+const getUser = createCommand("user/get"); // contract — no handler yet
+const double = createCommand("math/double", (value) => value * 2); // carries its handler
+
+const bus = createBus();
+
+// createModule — one feature; name is stable for hot reload replace
+const greeting = createModule("greeting", (m) => {
+  // m.on — like bus.on, removed automatically on unmount
+  m.on("greet", (name) => console.log(`hello ${name}`));
+
+  // m.handle — this module answers getUser while mounted
+  m.handle(getUser, (id) => api.user(id));
+
+  // m.use — register a command that already has a handler, for this module’s life
+  m.use(double);
+});
+
+// modulePlugin — mount modules on the bus
+const app = bus.use(modulePlugin([greeting]));
+bus.emit("greet", "Ada"); // hello Ada
+app.unmount(greeting); // greet listener and getUser binding are gone
+```
+
+- **`m.on`** — same job as `bus.on`, scoped to the module’s lifetime.
+- **`m.handle`** — bind a handler to a contract command; gone on unmount.
+- **`m.use`** — bring a command that already carries a handler (or a sub-module). Prefer `handle` when the handler must die with the feature.
+
+Modules also make [hot reload](hmr.md) work. Full API in [Actions](actions.md); a longer recipe in [`examples/modules.ts`](../examples/modules.ts).
+
+## 10. Add types when you want checking (optional)
+
+Describe events once when you want `on` / `emit` checked. An event without data is `void`. Skip this while you are learning the bus.
+
+```ts
+import { createBus } from "nanoeffects";
+
+// Events — event name → payload for this bus (checker only)
+type Events = {
+  greet: string;
+  moved: { x: number; y: number };
+  reset: void;
+};
+
+const bus = createBus<Events>();
+
+bus.on("moved", ({ x, y }) => console.log(x + y));
+bus.emit("moved", { x: 1, y: 2 });
+bus.emit("reset");
+// bus.emit("moved", { x: "1" }); // error
+// bus.emit("jumped", 1); // error
+```
+
+Without a map, any string event is allowed and the payload is `unknown`.
+
+## 11. Isolate errors and warn on typos
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  onError: (error) => report(error), // isolate failing handlers
+  onUnhandled: ({ type }) => console.warn(`nobody listens to ${type}`),
+});
+```
+
+More in [Errors](errors.md).
+
+## Where next
+
+| Need | Page |
+| ---- | ---- |
+| Store or client on every task | [Context fields](context.md) |
+| Redux / Zustand / MobX | [Stores](stores.md) |
+| Observe tasks | [Tracing](tracing.md) |
+| Guarantees | [Semantics](semantics.md) |
+| Which import | [Package entries](package.md) |
+
+---
+Source: docs/package.md
+
+# Choose a package entry
+
+Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
+
+| Import | What is in it |
+| ------ | ------------- |
+| `nanoeffects` | `createBus`, the types |
+| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
+| `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
+| `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
+| `nanoeffects/redux` | `createEffectsMiddleware` |
+| `nanoeffects/observable` | `createObserve` |
+| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
+| `nanoeffects/dev` | `devPlugin` (no-op in production) |
+| `nanoeffects/trace` | `createTracer` and the loggers |
+
+## Give the docs to an AI assistant
+
+The package ships two plain-text files for assistants that write code with it:
+
+- `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
+- `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.
+
+---
+Source: docs/policies.md
+
+# Policies
+
+Use this page when handlers overlap in a SPA (search-as-you-type, double submit, leave page). A **policy** wraps a handler and decides what happens then.
+
+Start with `latest`. The table and sections below are the rest of the reference.
+
+## Abort the previous run
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// latest — a newer run aborts the older one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal — lets latest cancel this request, not only drop its result
+    await api.search(query, { signal });
+  }),
+);
+```
+
+Pass `signal` to `fetch` (and the like) so the request cancels.
+
+## Choose a policy
+
+Every policy accepts `key` in its options (see [Isolate state by key](#isolate-state-by-key)).
+
+| Policy | Overlapping calls |
+| ------ | ----------------- |
+| `latest(fn)` | previous run aborted, result dropped |
+| `leading(fn)` | new calls dropped while a run is going |
+| `debounce(ms, fn, options?)` | run after `ms` of quiet |
+| `throttle(ms, fn, options?)` | at most one run per `ms` |
+| `queue(fn, options?)` | one after another, in order |
+
+## Configure debounce and throttle
+
+`debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.
+
+**Throttle** (`throttle(ms, fn)`):
+
+- Default `leading: true`, `trailing: true`.
+- A call when the throttle is idle (at least `ms` after the previous call and run) runs at once.
+- Calls made while it waits are held; the latest runs when the window closes.
+- Under a steady stream it runs every `ms`.
+- `leading: false` — even the first call waits for the end of its window.
+- `trailing: false` — drop calls made during a window.
+
+**Debounce** (`debounce(ms, fn)`):
+
+- Default `trailing: true` — run the last call after `ms` of quiet.
+- `leading: true` — also run the first call of a burst at once; the trailing run happens only if more calls follow.
+- `leading: true, trailing: false` — only the first call of a burst.
+- Both `false` — nothing runs.
+
+## Isolate state by key
+
+`key` gives each key its own state. Calls with different keys do not affect each other. Idle keys are dropped, so keys can be unbounded (ids, urls).
+
+```js
+import { createBus } from "nanoeffects";
+import { latest, queue } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// one latest run per user id
+bus.on(
+  "load",
+  latest(loadUser, { key: (user) => user.id }),
+);
+
+// uploads of the same file go one after another
+bus.on(
+  "upload",
+  queue(upload, { key: (file) => file.name }),
+);
+```
+
+## Run calls one after another with `queue`
+
+```js
+import { createBus } from "nanoeffects";
+import { queue } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// queue — one after another, in order
+bus.on(
+  "save",
+  queue(async (draft, { signal }) => {
+    await api.save(draft, { signal });
+  }),
+);
+
+bus.emit("save", draftA); // runs now
+bus.emit("save", draftB); // waits for draftA, then runs
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `concurrency` | how many calls may run at once (default `1`) |
+| `limit` | how many calls may wait |
+| `overflow` | when the line is full: `"drop-new"` (default) or `"drop-old"` |
+
+A dropped call resolves with `undefined`. `queue(fn, { limit: 1, overflow: "drop-old" })` keeps only the latest waiting call. `limit: 0` lets nothing wait.
+
+Every call returns a promise with the result of its own run. An error rejects only that call; the queue continues.
+
+**Abort:**
+
+- A waiting call whose task aborts is skipped and resolves with `undefined`.
+- When a running call aborts, its slot is freed at once and its result is dropped.
+- Pass `signal` into what `fn` does. A `fn` that ignores it can overlap with the next run.
+
+---
+Source: docs/effects.md
+
+# Effects and cancellation
+
+Use this page for retry, timeouts, waiting, or parallel work — not as the first page for a small bus. Pick **one** helper for your job; the rest is reference.
+
+An abort only raises a flag. Your code decides to stop. Start with `retry` / `timeout` on a handler (see [Guide §5](guide.md#5-add-retry-and-timeout)).
+
+## Wrap a handler with retry and timeout
+
+`retry`, `timeout`, and `poll` have two forms:
+
+- **Task wrapper** — take a function `(payload, ctx) => result` and return one. Pass them into `on` next to policies (no `ctx` in their arguments).
+- **Call inside a body** — take `ctx` first.
+
+The first argument tells them apart: a function (`retry`), a number (`timeout`), or a number/function (`poll`) is a wrapper; an object is `ctx`.
+
+```js
+import { createBus } from "nanoeffects";
+import { poll, retry, timeout } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+const loadUser = (id, { signal }) => fetchUser(id, { signal });
+
+// timeout — one try must finish within 5 s
+const loadOnce = timeout(5000, loadUser);
+// retry — up to 4 attempts with backoff
+const loadWithRetry = retry(loadOnce, {
+  times: 4,
+  delay: (attempt) => 2 ** attempt * 100,
+  shouldRetry: (error) => !isFatal(error),
+});
+// latest — a newer load aborts the older retry chain
+bus.on("load", latest(loadWithRetry));
+
+// poll — call refresh every 10 s until the task aborts
+bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+
+// ctx.run — run a wrapped Task as a child (aborted with the handler)
+bus.on("open", async (id, ctx) => {
+  const load = retry(timeout(5000, loadUser));
+  const user = await ctx.run(load, id);
+  ctx.emit("opened", user);
+});
+
+// ctx-first form — one call inside a body
+bus.on("load", async (id, ctx) => {
+  const user = await retry(
+    ctx,
+    () => fetchUser(id, { signal: ctx.signal }),
+    { times: 4 },
+  );
+  const data = await timeout(ctx, 5000, ({ signal }) => {
+    return fetchData(id, { signal });
+  });
+  await poll(ctx, () => refresh(), 10_000);
+  ctx.emit("ready", { user, data });
+});
+```
+
+Use the wrapper for a whole handler or a whole `ctx.run`. Use the `ctx` form for one call in the middle of a body.
+
+Each attempt or call of a wrapper gets its own child context. Abort of the caller reaches it. Abort of one attempt (a timeout) does not reach the caller. The attempt number is passed only in the `ctx` form.
+
+### Options for retry, timeout, and poll
+
+**`retry`**
+
+- `times` — total attempts (default `3`).
+- `delay` — number or `(attempt, error) => ms`.
+- `shouldRetry(error, attempt)` — stop early.
+- `fn` gets the attempt number starting at `1`.
+- On abort, rejects with the abort reason.
+
+**`timeout`**
+
+- Error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`).
+- Rejects even if the starter ignores its signal.
+
+**`poll`** (like patronum `interval`)
+
+- First call after `ms`. `leading: true` also calls at once.
+- Next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap the next call.
+- `waitForFn: true` starts each pause when the call ends — calls never overlap.
+- `fn` gets the call number from `0`.
+- An error from `fn` stops polling and rejects. An abort ends it normally and clears the timer.
+
+A pause can be a function wherever a time is given. For retries with a cap and jitter, see [Back off between retries](#back-off-between-retries):
+
+```js
+import { createBus } from "nanoeffects";
+import { delay, poll, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("sync", async (_, ctx) => {
+  retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
+  poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
+  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+});
+```
+
+All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
+
+## Back off between retries
+
+Use this when a server or network fails under load. Retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. Make the pause grow with each attempt, and add jitter so clients spread out.
+
+The shortest form is a `delay` function. It needs no import:
+
+```js
+import { retry } from "nanoeffects/effects";
+
+const loadWithRetry = retry(loadUser, {
+  times: 5,
+  delay: (attempt) => 2 ** attempt * 100, // 200, 400, 800, 1600 ms
+});
+```
+
+When you also want a cap and jitter, build the function with `backoff`:
+
+```js
+import { backoff, retry } from "nanoeffects/effects";
+
+const loadWithRetry = retry(loadUser, {
+  times: 5,
+  // backoff — pause 200, 400, 800, … ms, never over 5 s, a random part of it
+  delay: backoff({ base: 200, max: 5000, jitter: true }),
+});
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `base` | pause before the second attempt, in ms (default `100`) |
+| `factor` | each pause is this many times longer (default `2`) |
+| `max` | longest pause, in ms (default none) |
+| `jitter` | `true` picks a random pause from 0 up to the computed one (default `false`) |
+
+- With `jitter: true` a pause can be close to 0, so treat `base` as a scale, not a minimum.
+- `retry` counts attempts from 1. `poll` counts calls from 0, so with `poll` the first pause is `base / factor`.
+- The result is a plain function `(attempt) => ms`, so it also fits `delay(ctx, …)`.
+
+## Put selected effects on `ctx`
+
+If handlers call the same helpers often, put them on the task once. A handler then destructures them like `signal`, with no `ctx` argument. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
+
+```js
+import { createBus } from "nanoeffects";
+import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
+
+// effectsPlugin — add race, all and delay to the context of every task; returns the same bus
+const bus = createBus().use(effectsPlugin({ race, all, delay }));
+
+bus.on("load", async (id, { race, all, delay }) => {
+  // race — same as race(ctx, …)
+  const result = await race({
+    data: ({ signal }) => fetchData(id, { signal }),
+    timeout: () => delay(5000), // delay — same as delay(ctx, 5000)
+  });
+  if ("timeout" in result) throw new Error("timed out");
+
+  // all — same as all(ctx, …)
+  const { user, posts } = await all({
+    user: ({ signal }) => fetchUser(id, { signal }),
+    posts: ({ signal }) => fetchPosts(id, { signal }),
+  });
+});
+```
+
+- Supported: `race`, `all`, `allSettled`, `take`, `delay`. The key is the effect name.
+- `retry`, `timeout` and `poll` are not supported: bound to the task they would look like their handler wrappers.
+- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
+- Free forms keep working: `race(ctx, …)`.
+
+## Tie a promise to the task signal
+
+`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
+
+`cancellable(ctx, executor)` is a promise tied to the task signal. It works like `new Promise`, but the executor gets `{ resolve, reject, onCancel }`.
+
+```js
+import { createBus } from "nanoeffects";
+import { cancellable } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// cancellable — promise tied to the task signal; onCancel for cleanups
+// latest — a newer wait aborts the older timer
+bus.on(
+  "wait",
+  latest((_, ctx) => {
+    return cancellable(ctx, ({ resolve, onCancel }) => {
+      const timer = setTimeout(resolve, 5000);
+      onCancel(() => clearTimeout(timer));
+    });
+  }),
+);
+```
+
+- If the task aborts before the promise settles, cleanups run (last registered first) and the promise rejects with the abort reason.
+- If the task is already aborted, the executor does not run.
+- After the promise settles, the abort listener is removed and cleanups are dropped.
+
+## Run cleanup on abort
+
+`onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if already aborted) and returns a function that unsubscribes.
+
+```js
+import { createBus } from "nanoeffects";
+import { onAbort } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("connect", (url, ctx) => {
+  const socket = new WebSocket(url);
+  // onAbort — run cleanup when this task aborts
+  onAbort(ctx, () => socket.close());
+});
+```
+
+## Wait for the next event with `take`
+
+A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts:
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
+
+bus.on("watch", (_, ctx) => {
+  ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
+});
+```
+
+- The returned function unsubscribes sooner. After abort, `ctx.on` does nothing.
+- Under `latest`, subscriptions of a superseded run end with that run.
+- `ctx.off(event)` clears every handler of the event on the bus, not only the task’s.
+
+`take(ctx, event, options?)` waits for the next `event` and resolves with its payload:
+
+```js
+import { createBus } from "nanoeffects";
+import { take, timeout } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("login", async (user, ctx) => {
+  const reason = await take(ctx, "logout"); // resolves on the next logout
+  cleanup(user, reason);
+
+  // wait for a matching event, but not longer than 5 s
+  const id = await timeout(ctx, 5000, ({ signal }) =>
+    take(ctx, "saved", { signal, predicate: (savedId) => savedId === draft.id }),
+  );
+});
+```
+
+- Sees only events emitted after the call, takes one, and unsubscribes.
+- `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
+- `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
+- On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
+
+## Run several starters together
+
+`all(ctx, effects)` runs starters together. One failure cancels the rest. Shape of the input (object or array) is preserved in the result.
+
+`allSettled(ctx, effects)` waits for every starter and never fails because of one. Each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`. Nothing is cancelled when a starter fails. Only an abort of `ctx` rejects it.
+
+```js
+import { createBus } from "nanoeffects";
+import { allSettled } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("open", async (id, ctx) => {
+  const { user, posts } = await allSettled(ctx, {
+    user: ({ signal }) => fetchUser(id, { signal }),
+    posts: ({ signal }) => fetchPosts(id, { signal }),
+  });
+
+  if (user.status === "fulfilled") {
+    render(user.value);
+  }
+});
+```
+
+`race(ctx, effects)` settles with the first starter that finishes and cancels the others.
+
+## Pass `ctx` outside a task
+
+Effects that wait inside a body take `ctx` first: `delay`, `all`, `allSettled`, `race`, `cancellable`, `onAbort`, `take`, and the `ctx` forms of `retry` / `timeout` / `poll`. Outside a task, pass `{}` or any object with a `signal`.
+
+For `fetch` and other APIs that take a signal, pass `ctx.signal`. A timeout without `race`: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])`.
+
+---
+Source: docs/errors.md
+
+# Handle errors and unheard events
+
+Defaults match a small bus. Set these when you want isolation or typo warnings.
+
+## Isolate failing handlers
+
+`emit` is a plain loop over the handlers (like nanoevents). If a handler throws, the remaining handlers are skipped and the error reaches the caller of `emit`. A rejected promise of an async handler is left unhandled.
+
+Pass `onError` to isolate handlers instead. Then every handler runs. Thrown errors and rejections of async handlers (including those wrapped in `latest`, `debounce`, and the like) go to `onError`. An `onError` that throws is logged to `console.error`.
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus — onError isolates failing handlers so others still run
+const bus = createBus({
+  onError: (error, { type, payload }) => {
+    report(error, type, payload);
+  },
+});
+```
+
+## Warn when nobody listens
+
+A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for commands, which always have a handler to run.
+
+Use it as a warning in development:
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  onUnhandled: import.meta.env.DEV
+    ? ({ type }) => console.warn(`Nobody listens to "${type}"`)
+    : void 0,
+});
+```
+
+---
+Source: docs/actions.md
+
+# Actions, commands, jobs and modules
+
+Use this page when **domain logic lives on the bus**, off the UI: the UI emits and listens; handlers and modules own the work.
+
+If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until you need a result from `emit` or a mountable domain.
+
+Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
+
+## Return a value from `emit` with a command
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// createCommand — emit runs the handler and returns its result
+const double = createCommand("math/double", (value) => value * 2);
+bus.emit(double(21)); // 42
+```
+
+## Describe events, commands, and jobs
+
+`nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
+
+```js
+import { createAction, createCommand, createJob } from "nanoeffects/actions";
+
+// createAction — event with a payload (like RTK createAction)
+const userLoaded = createAction("user/loaded");
+const loadFailed = createAction("user/failed");
+
+// createCommand with a handler — emit returns what the handler returns
+const getUser = createCommand("user/get", (id, { signal }) => {
+  return fetchUser(id, { signal });
+});
+
+// createCommand without a handler — a contract; register the work elsewhere
+const sendMail = createCommand("mail/send");
+
+// createJob — command that also emits success / fail actions
+const loadUser = createJob("user/load", fetchUser, {
+  success: userLoaded,
+  fail: "user/failed",
+});
+```
+
+### Actions
+
+`createAction(type)` returns a creator. Without generics it keeps the literal type; the bus checks the payload against its event map. Without an event map, give the payload type: `createAction<User>("user/loaded")`.
+
+- `userLoaded(user)` → `{ type, payload }`
+- `userLoaded.type` — the type string
+- `userLoaded.match(action)` — narrows an action
+- `createAction(type, prepare)` — build the payload from several arguments
+- Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
+
+### Commands
+
+Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or `bus.emit(command, payload)`) tells the listeners of the command’s type, then runs its handler as a task and returns the result.
+
+- Wrap the handler in a policy: `createCommand("search", latest(fn))`.
+- `command.match(action)` narrows like an action creator’s `match`.
+
+**Where handlers are registered.** The command may carry a handler. The bus can also take handlers from a registry (`commandsPlugin`). A handler bound there wins over the command’s own. Each bus (each test) has its own registry.
+
+```js
+import { createBus } from "nanoeffects";
+import {
+  bindHandler,
+  commandsPlugin,
+  createCommand,
+} from "nanoeffects/actions";
+
+const sendMail = createCommand("mail/send");
+const getUser = createCommand("user/get");
+
+const bus = createBus();
+
+// commandsPlugin — registry of handlers for this bus
+const commands = bus.use(
+  commandsPlugin([bindHandler(sendMail, smtpSend)]),
+);
+
+// later, e.g. in a test — latest binding wins
+const unbind = commands.handle(getUser, async () => fakeUser);
+unbind();
+```
+
+A command with no handler anywhere throws `No handler for command "..."` from `emit` (the call itself only builds the action).
+
+The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second plugin on the same bus replaces it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
+
+### Jobs
+
+`createJob(type, handler, { success, fail })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.success` and `loadUser.fail` on it.
+
+- On success, emits `loadUser.success(result)`.
+- On failure, emits `loadUser.fail(error)`.
+- `success` / `fail` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/success` or `<type>/fail`.
+- `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
+- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). Nothing is sent after abort.
+- A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
+- Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+
+## Mount domains with modules
+
+**Problem.** A domain needs several subscriptions and command bindings. With plain `bus.on` / `commands.handle` you must remember every unsubscribe.
+
+**When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
+
+`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `commands`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
+
+```js
+import { createBus } from "nanoeffects";
+import {
+  createCommand,
+  createModule,
+  modulePlugin,
+} from "nanoeffects/actions";
+
+const getUser = createCommand("user/get");
+const saveUser = createCommand("user/save", persistUser);
+
+// createModule — one domain; unmount undoes everything below
+const userModule = createModule("user", (m) => {
+  m.handle(getUser, fetchUser);
+  m.use(saveUser, authModule);
+  m.on("login", (user, ctx) => {
+    ctx.emit("loaded", user);
+  });
+  m.spawn(async (_, ctx) => {
+    /* background work; ends when the module unmounts */
+  });
+});
+
+const bus = createBus();
+// modulePlugin — mount modules on the bus
+const app = bus.use(modulePlugin([userModule]));
+
+const unmount = app.mount(orderModule); // later, e.g. after a lazy import
+app.commands.handle(getUser, fakeUser); // in a test
+app.dispose(); // unmounts every module
+```
+
+- **Unmounting undoes everything** the module did: subscriptions, bound commands, sub-modules, and background tasks (aborted).
+- **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
+- **Registry.** If `bus.use(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
+- A disposed app cannot mount modules.
+- Module context = task context plus `handle`, `use`, and `spawn`:
+  - `handle` — give a command a handler (contract, or override).
+  - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
+  - `spawn` — background task, aborted on unmount.
+- A command that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.
+
+---
+Source: docs/stores.md
+
+# Connect Redux, Zustand, MobX, or Pinia
+
+Use this page when you **already have a store** and want async work with cancellation and policies next to it. It is not a reason to pick Redux (or any store).
+
+If you do not have a store yet, use `createBus` from the [Guide](guide.md).
+
+## On this page
+
+- [Wire Redux Toolkit to a bus](#wire-redux-toolkit-to-a-bus)
+- [Emit from a state manager](#emit-from-a-state-manager)
+  - [Nanostores](#nanostores)
+  - [MobX](#mobx)
+  - [Valtio](#valtio)
+  - [Jotai](#jotai)
+  - [Zustand](#zustand)
+  - [Pinia](#pinia)
+  - [React: sharing a value across components](#react-sharing-a-value-across-components)
+  - [Callbacks on every change](#callbacks-on-every-change)
+  - [Stop watching a store](#stop-watching-a-store)
+  - [Give the store to every handler](#give-the-store-to-every-handler)
+
+## Wire Redux Toolkit to a bus
+
+Redux’s `dispatch` → reducers updates **state**. It does not give you first-class **tasks** (abort in-flight work, `latest` / `debounce` / `queue`, `retry` / `timeout`). People usually reach for thunks, RTK listener middleware, or sagas for that.
+
+`createEffectsMiddleware(bus)` does the same job: after the reducer runs, the action also hits the nanoeffects bus you pass to it. Keep RTK for state; use policies and effects for async.
+
+Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts).
+
+```js
+import { configureStore, createAction } from "@reduxjs/toolkit";
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { createEffectsMiddleware } from "nanoeffects/redux";
+
+const userRequested = createAction("user/requested"); // RTK
+const userLoaded = createAction("user/loaded");
+
+const bus = createBus(); // the bus of your app; it can exist before the store
+
+// createEffectsMiddleware — actions reach the bus after reducers; tasks get ctx.store
+const effects = createEffectsMiddleware(bus);
+
+const store = configureStore({
+  reducer,
+  middleware: (getDefault) => getDefault().concat(effects),
+});
+
+// latest — a newer run aborts the older one
+bus.on(
+  userRequested,
+  latest(async (id, { store, signal }) => {
+    const user = await fetchUser(id, { signal });
+    store.dispatch(userLoaded(user));
+  }),
+);
+```
+
+String event names (`"user/requested"`) work the same. Use your usual RTK actions (`createSlice` / `createAction`). nanoeffects adds the middleware and policies; it does not replace RTK actions.
+
+### What the middleware guarantees
+
+- **No self-loop.** An action that a handler dispatches through `ctx.store` and that has the type the handler works on does not go back to the bus. Other handlers of that type do not get it either. Longer cycles (`a` → `b` → `a`) are yours to avoid.
+- **A failing handler does not break `dispatch`.** With `onError` on the bus, the bus isolates the handlers. Without it the error goes to `console.error`, as in RTK listeners. Reducers still throw to the caller.
+- **`store` reaches tasks when the middleware is installed**, even though the bus is created before `configureStore`.
+
+The only option is `filter`, which keeps rejected actions away from the bus. Options of the bus (`onError`, `context`, `trace`) go to `createBus`. Use one bus for one store. Values that are not plain actions (thunks) go through untouched. Nothing here depends on the `redux` package at runtime.
+
+### Type `ctx.store` (optional)
+
+Only if you want TypeScript to know `store` on handlers. **Skip this in JavaScript** — the middleware already puts `store` on the task at runtime. These lines do not connect the store across the app.
+
+```ts
+import { createBus, type WithContext } from "nanoeffects";
+import {
+  createEffectsMiddleware,
+  type ReduxStoreApi,
+} from "nanoeffects/redux";
+
+// RootState — your Redux state shape (for getState)
+type RootState = { user: string | null };
+
+// Events — event name → payload for this bus
+// WithContext — checker-only: handlers also have ctx.store
+type Events = {
+  "user/requested": string;
+} & WithContext<{ store: ReduxStoreApi<RootState> }>;
+
+const bus = createBus<Events>(); // the event map types ctx.store
+const effects = createEffectsMiddleware(bus);
+```
+
+## Emit from a state manager
+
+Zustand, MobX, Jotai, Valtio, Nanostores and Pinia have no adapter. Redux is different: use the middleware from the first section, it sends actions to the bus. A plain store works with the bus in two directions, and both are shown for each store below:
+
+- **The store triggers an event.** The store tells you about a change with a callback. You pass that callback `bus.emitter(action)`, and the change becomes an event that starts a handler.
+- **The event changes the store.** The handler reports its result as an event. A listener of the bus writes it into the store.
+
+The example is a search box. The store holds two fields: `query`, which the user types, and `results`, which a request fills. A change of `query` starts a debounced search; the search ends with an event that writes `results`.
+
+Writing `(query) => bus.emit(queryChanged(query))` for every subscription repeats the bus and the action. `emitterPlugin` adds `bus.emitter(action)`: it returns that callback for you. The action stays a plain `createAction`, so `bus.emit(queryChanged("nano"))` and `bus.on(queryChanged, …)` work as before.
+
+The bus is the same for every store below. Create it once; each subsection imports it.
+
+```js
+// search-bus.js
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { debounce, latest } from "nanoeffects/policies";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter; returns the same bus
+
+// createAction — plain action creators; calling one only builds { type, payload }
+export const queryChanged = createAction("search/queryChanged");
+export const searchLoaded = createAction("search/loaded");
+
+// bus.emitter: a callback (query) => bus.emit(queryChanged(query))
+export const emitQueryChanged = bus.emitter(queryChanged);
+
+// debounce — wait 300 ms of quiet; latest — abort the search of the previous query
+bus.on(
+  queryChanged,
+  debounce(
+    300,
+    latest(async (query, ctx) => {
+      // api — your client; ctx.signal lets latest cancel the request itself
+      const items = await api.search(query, { signal: ctx.signal });
+      ctx.emit(searchLoaded(items)); // report the result as an event
+    }),
+  ),
+);
+```
+
+Write `results` and never the field you watch: a handler that changed `query` would start itself again. Find your store below.
+
+### Nanostores
+
+`listen` calls back with the new value. `subscribe` would also call at once, with the current value, so use `listen`.
+
+```js
+import { atom } from "nanostores";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const $query = atom("");
+const $results = atom([]);
+
+// store → bus: listen calls back with the new query on every change
+const stopQuery = $query.listen(emitQueryChanged);
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  $results.set(items);
+});
+```
+
+### MobX
+
+`reaction` watches an expression and calls back with its value. Change observables inside `runInAction`.
+
+```js
+import { observable, reaction, runInAction } from "mobx";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const search = observable({ query: "", results: [] });
+
+// store → bus: reaction watches the expression and calls back with its value
+const stopQuery = reaction(() => search.query, emitQueryChanged);
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  runInAction(() => {
+    search.results = items;
+  });
+});
+```
+
+### Valtio
+
+`subscribeKey` watches one field of a proxy state. Assign to the proxy to change it.
+
+```js
+import { proxy } from "valtio";
+import { subscribeKey } from "valtio/utils";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const state = proxy({ query: "", results: [] });
+
+// store → bus: subscribeKey watches one field
+const stopQuery = subscribeKey(state, "query", emitQueryChanged);
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  state.results = items;
+});
+```
+
+### Jotai
+
+`sub` gives no value, so read it yourself. Write with `store.set`.
+
+```js
+import { atom, createStore } from "jotai";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const queryAtom = atom("");
+const resultsAtom = atom([]);
+const store = createStore();
+
+// store → bus: sub calls back without a value; store.get reads it
+const stopQuery = store.sub(queryAtom, () => emitQueryChanged(store.get(queryAtom)));
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  store.set(resultsAtom, items);
+});
+```
+
+### Zustand
+
+With `subscribeWithSelector` the selector picks the field, and the callback is called only when it changes. Without a selector Zustand calls back on every `setState`, with the whole state.
+
+```js
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+const useSearchStore = create(
+  subscribeWithSelector(() => ({ query: "", results: [] })),
+);
+
+// store → bus: subscribe with a selector calls back with state.query only when it changes
+const stopQuery = useSearchStore.subscribe((state) => state.query, emitQueryChanged);
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  useSearchStore.setState({ results: items });
+});
+```
+
+### Pinia
+
+Pinia (the store of Vue) keeps reactive objects, and its `$subscribe` reports every mutation of the store, not one field. Watch one getter with Vue's `watch` instead: it calls back with the new value. Assign to the store to change it.
+
+```js
+import { watch } from "vue";
+import { defineStore } from "pinia";
+import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+
+// defineStore — Pinia: the state of one store
+const useSearch = defineStore("search", {
+  state: () => ({ query: "", results: [] }),
+});
+
+const search = useSearch(); // call it after the app has installed Pinia
+
+// store → bus: watch calls back with the new query when search.query changes
+const stopQuery = watch(() => search.query, emitQueryChanged);
+
+// bus → store: bus.on returns the function that removes this listener
+const stopResults = bus.on(searchLoaded, (items) => {
+  search.results = items;
+});
+```
+
+### React: sharing a value across components
+
+A value of your UI (a query, a filter, a name) often has two jobs. Several components read it and re-render when it changes, and the bus must hear about each change to start a handler. The recipes below differ in where the value lives. Pick the first one unless a handler must read the value.
+
+| The value lives in | Use when |
+| --- | --- |
+| A Context provider with `useState` | Only components read it. Plain React, one `useEmitter` call. |
+| A small store on `useSyncExternalStore` | A bus handler, a test or a timer must read it too. |
+| An atom of a store library | You already use Nanostores, Jotai and the like. |
+
+#### Plain React: Context and `useEmitter`
+
+Writing `useEffect(() => bus.emit(...), [value])` looks enough, but it emits on mount, emits twice on mount under StrictMode, and re-runs when the emit function is new on every render. `useEmitter` from `nanoeffects/react` avoids all three. It emits after a render commits with a changed value, never on mount, and compares with `Object.is`. You need React 18 or newer; no other entry of the package uses React.
+
+First the bus. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export:
+
+```js
+// react-search-bus.js
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+import { debounce, latest } from "nanoeffects/policies";
+import { reactPlugin } from "nanoeffects/react";
+
+export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds bus.useEmitter
+export const { useEmitter } = bus; // a free hook: it does not read `this`
+
+export const queryChanged = createAction("query/changed");
+export const searchLoaded = createAction("search/loaded");
+
+// debounce — wait 300 ms of quiet; latest — a newer query aborts the older request
+bus.on(
+  queryChanged,
+  debounce(
+    300,
+    latest(async (query, ctx) => {
+      const items = await api.search(query, { signal: ctx.signal });
+      ctx.emit(searchLoaded(items)); // the result goes back to the bus as an event
+    }),
+  ),
+);
+```
+
+Then the provider. It holds the state, calls `useEmitter` once, and listens for the result. Every component below it only reads the context:
+
+```jsx
+// SearchProvider.jsx
+import { createContext, useContext, useEffect, useState } from "react";
+import { bus, queryChanged, searchLoaded, useEmitter } from "./react-search-bus";
+
+const SearchContext = createContext(null);
+
+export function SearchProvider({ children }) {
+  const [query, setQuery] = useState("");
+  const [items, setItems] = useState([]);
+
+  // React → bus: emits queryChanged(query) after every change of query, not on mount
+  useEmitter(queryChanged, query);
+
+  // bus → React: bus.on returns the unsubscribe function, which the effect returns
+  useEffect(() => bus.on(searchLoaded, setItems), []);
+
+  return (
+    <SearchContext.Provider value={{ query, setQuery, items }}>
+      {children}
+    </SearchContext.Provider>
+  );
+}
+
+export const useSearch = () => useContext(SearchContext);
+```
+
+```jsx
+// Search.jsx
+import { useSearch } from "./SearchProvider";
+
+// any number of components can read the same value
+export function SearchBox() {
+  const { query, setQuery } = useSearch();
+  return <input value={query} onChange={(event) => setQuery(event.target.value)} />;
+}
+
+export function Results() {
+  const { items } = useSearch();
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Two limits to know:
+
+- **All consumers re-render** on any change of the context value. Split it into two contexts (`query` and `items`) if that is slow.
+- **A new object counts as a change.** For a value that is rebuilt with the same content, pass a third argument that says when two values are the same: `useEmitter(profileChanged, profile, (previous, next) => previous.id === next.id)`.
+
+`useEmitter` emits after the render, not at the moment of `setQuery`. To emit on every call, even with the same value, call an emitter from the event handler (`bus.emitter(action)`, see [Zustand](#zustand)) instead.
+
+#### A value that a handler must read
+
+A context is not visible to a bus handler. When a handler needs the current value, keep the value outside React. About twelve lines of `useSyncExternalStore` do it, and `contextPlugin` hands it to every handler as `ctx.query`:
+
+```jsx
+// value-store.js
+import { useSyncExternalStore } from "react";
+
+export function createValue(initial) {
+  let value = initial;
+  const listeners = new Set();
+
+  return {
+    get: () => value,
+    set(next) {
+      if (Object.is(next, value)) {
+        return; // no change, no notification: this also stops loops
+      }
+      value = next;
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+export const useValue = (store) => useSyncExternalStore(store.subscribe, store.get);
+```
+
+```jsx
+// search-value.jsx
+import { createBus, contextPlugin } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { createValue, useValue } from "./value-store";
+
+const query = createValue("");
+
+// emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query
+const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+
+const queryChanged = createAction("query/changed");
+const refreshed = createAction("search/refreshed");
+
+// store → bus: bus.emitter turns the action into a callback; one place, any number of setters
+const emitQueryChanged = bus.emitter(queryChanged);
+query.subscribe(() => emitQueryChanged(query.get()));
+
+// the handler reads the current value from ctx, whoever changed it
+bus.on(refreshed, async (_payload, ctx) => {
+  const items = await api.search(ctx.query.get(), { signal: ctx.signal });
+  console.log(items.length);
+});
+
+// any number of components read and write the same value
+export function SearchBox() {
+  const text = useValue(query);
+  return <input value={text} onChange={(event) => query.set(event.target.value)} />;
+}
+```
+
+#### A store library
+
+With Nanostores, Jotai or Zustand the value already lives outside React and has a subscription. Connect it to the bus once, as in [Nanostores](#nanostores), and read it in components with the library's own hook:
+
+```jsx
+// search-atom.jsx
+import { atom } from "nanostores";
+import { useStore } from "@nanostores/react";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+const $query = atom("");
+const queryChanged = createAction("query/changed");
+
+// listen, not subscribe: listen skips the call with the current value at start
+$query.listen(bus.emitter(queryChanged));
+
+export function SearchBox() {
+  const query = useStore($query); // the hook of Nanostores; it re-renders on every change
+  return <input value={query} onChange={(event) => $query.set(event.target.value)} />;
+}
+```
+
+#### Do not emit inside a `useReducer` reducer
+
+React may run a reducer more than once for one dispatch (twice in StrictMode), so a `bus.emit` inside it fires twice. Dispatch to the reducer first, then emit, from one helper. Or keep the state in a reducer and pass it to `useEmitter` like any other value.
+
+```jsx
+// search-reducer.jsx
+import { useReducer } from "react";
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+
+const bus = createBus(); // the bus: created once
+
+const queryChanged = createAction("query/changed");
+const queryCleared = createAction("query/cleared");
+
+function reducer(state, action) {
+  if (queryChanged.match(action)) {
+    return action.payload;
+  }
+  if (queryCleared.match(action)) {
+    return "";
+  }
+  return state;
+}
+
+export function Search() {
+  const [query, dispatch] = useReducer(reducer, "");
+
+  // send: the reducer first, then the bus (bus.emit accepts an action)
+  function send(action) {
+    dispatch(action);
+    bus.emit(action);
+  }
+
+  return (
+    <div>
+      <input value={query} onChange={(event) => send(queryChanged(event.target.value))} />
+      <button type="button" onClick={() => send(queryCleared())}>
+        Clear
+      </button>
+    </div>
+  );
+}
+```
+
+A plain `dispatch` skips the bus, so call `send` everywhere.
+
+### Callbacks on every change
+
+The stores above call back only when the value changed, so the emitter does not compare values. For a store that calls back on every change, select a smaller value first, as Zustand does above.
+
+### Stop watching a store
+
+Stop both directions with what the calls returned: `stopQuery` from the store and `stopResults` from `bus.on`. Call them yourself, or hand them over: `onAbort(ctx, stopQuery)` inside a task, or `m.signal.addEventListener("abort", stopQuery)` in a module.
+
+### Give the store to every handler
+
+Instead of a listener per store, give the store to all tasks with `createBus({ context: { store } })` ([Context fields](context.md)) and change it from any handler (`setState`, a MobX action, a Pinia store). The same rule holds: write the field you do not watch. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.
+
+---
+Source: docs/react.md
+
+# Build a sign-up form in React
+
+Use this page when a React screen starts requests on user input and you need them not to race: a username check while typing, a submit button, a flaky network. It builds one registration form. The bus lives outside React; the component only subscribes to it.
+
+You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
+
+## See what goes wrong without a bus
+
+A registration form has three problems that `useEffect` and `fetch` leave to you:
+
+- **A stale answer.** The user types `ann`, then `anna`. The answer for `ann` arrives last and says the name is free, although `anna` is taken.
+- **A double submit.** A second click on "Sign up" sends a second request while the first one is running.
+- **A flaky network.** One failed request should be retried, but a "name is taken" answer should not.
+
+Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one place, outside the component.
+
+## Wire the bus once
+
+Put the bus and its handlers in their own file. Create it once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
+
+```js
+// registration.js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+import { debounce, latest, leading } from "nanoeffects/policies";
+
+// fetch rejects with a TypeError when the network fails; an HTTP error is a plain Error
+const isNetworkError = (error) => error instanceof TypeError;
+
+export const bus = createBus(); // the bus: created once, at the top of the module
+
+// debounce — wait 300 ms of quiet; latest — abort the check of the previous name
+bus.on(
+  "username/typed",
+  debounce(
+    300,
+    latest(async (name, ctx) => {
+      // api — your client; pass ctx.signal so latest can cancel the request itself
+      const available = await api.usernameAvailable(name, { signal: ctx.signal });
+      ctx.emit("username/checked", { name, available });
+    }),
+  ),
+);
+
+// leading — a second click is ignored while the first sign up is running
+bus.on(
+  "form/submitted",
+  leading(async (form, ctx) => {
+    const signUp = () => api.signUp(form, { signal: ctx.signal });
+    try {
+      // retry — up to 3 tries, 500 ms apart, and only when the network failed
+      const user = await retry(ctx, signUp, {
+        times: 3,
+        delay: 500,
+        shouldRetry: isNetworkError,
+      });
+      ctx.emit("form/succeeded", user);
+    } catch (error) {
+      ctx.emit("form/failed", error.message);
+    }
+  }),
+);
+```
+
+The handlers know nothing about React. A test can emit `username/typed` and read `username/checked` without rendering anything: the same wiring is tested in [`examples/registration-form.ts`](../examples/registration-form.ts) and `src/tests/registration-form.test.ts`.
+
+## Connect the form
+
+The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount.
+
+```jsx
+// SignUpForm.jsx
+import { useEffect, useState } from "react";
+import { bus } from "./registration"; // the bus of the previous snippet
+
+export function SignUpForm() {
+  const [name, setName] = useState("");
+  const [password, setPassword] = useState("");
+  const [available, setAvailable] = useState(null); // null: not checked yet
+  const [status, setStatus] = useState("idle"); // idle, sending, done or failed
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    // bus.on — listen for what the handlers report; each call returns an unsubscribe function
+    const unbindChecked = bus.on("username/checked", (result) => {
+      setAvailable(result.available);
+    });
+    const unbindSucceeded = bus.on("form/succeeded", () => setStatus("done"));
+    const unbindFailed = bus.on("form/failed", (message) => {
+      setStatus("failed");
+      setError(message);
+    });
+
+    return () => {
+      unbindChecked();
+      unbindSucceeded();
+      unbindFailed();
+    };
+  }, []);
+
+  function handleName(event) {
+    const value = event.target.value;
+    setName(value);
+    setAvailable(null);
+    bus.emit("username/typed", value); // bus.emit — the handler debounces and checks the name
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    setStatus("sending");
+    bus.emit("form/submitted", { name, password }); // a second click is dropped by leading
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={name} onChange={handleName} placeholder="Username" />
+      {available === false && <p>This name is taken</p>}
+      <input
+        type="password"
+        value={password}
+        onChange={(event) => setPassword(event.target.value)}
+      />
+      <button type="submit" disabled={status === "sending"}>Sign up</button>
+      {status === "failed" && <p>{error}</p>}
+      {status === "done" && <p>Welcome!</p>}
+    </form>
+  );
+}
+```
+
+The `disabled` button is only for the look. The form stays correct without it: `leading` drops a second submit while the first one runs.
+
+In development, React StrictMode runs the effect twice (subscribe, unsubscribe, subscribe). That is safe here, because the cleanup removes exactly what the effect added.
+
+## Stop running work when the form closes
+
+Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
+
+```js
+import { latest } from "nanoeffects/policies";
+
+// the username check of registration.js, with one new line
+const checkName = latest(async (name, ctx) => {
+  // ctx.on — a subscription of this task; aborting the task also drops the result
+  ctx.on("form/closed", () => ctx.abort());
+  const available = await api.usernameAvailable(name, { signal: ctx.signal });
+  ctx.emit("username/checked", { name, available });
+});
+```
+
+In the component, add `bus.emit("form/closed")` to the cleanup function of the effect. This is optional: skip it when finishing a request after unmount does no harm, as for a cheap check.
+
+## Where to go next
+
+- The policies behind this form: [Policies](policies.md).
+- `retry`, `timeout` and the other effects: [Effects](effects.md).
+- A state library instead of `useState`: [Stores](stores.md).
+
+---
+Source: docs/context.md
+
+# Put your own fields on every task
+
+Optional: put a store, client, or logger on every task. Skip until many handlers need the same dependency.
+
+## Pass values at runtime
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus({ context }) — every task gets these fields
+const bus = createBus({ context: { store } });
+
+bus.on("save", (draft, { store }) => {
+  store.put(draft);
+});
+```
+
+That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, commands, modules, and child tasks of effects and policies.
+
+Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may be a function `(task) => fields` when the value depends on the task.
+
+To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
+
+## Type the fields (optional)
+
+In TypeScript, `contextPlugin` puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
+
+```ts
+import { contextPlugin, createBus } from "nanoeffects";
+
+// Events — event name → payload
+type Events = { save: Draft };
+
+// contextPlugin — every task gets ctx.store; the type is the type of `store`
+const bus = createBus<Events>().use(contextPlugin({ store }));
+
+bus.on("save", (draft, { store }) => store.put(draft));
+```
+
+- A function `(task) => fields` makes the fields per task. It gets `{ type, payload }`.
+- Several `contextPlugin` calls, `effectsPlugin` and the `context` option of `createBus` all add their fields to the same context.
+- A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
+- The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
+
+### Name the fields in the event map instead
+
+`createBus<Events>({ context: { store } })` also types the fields, but through the event map: `WithContext` is checker-only and says which fields the handlers of this bus have. Use it when you cannot call `use`, for example for the bus that `createEffectsMiddleware` makes.
+
+```ts
+import { createBus, type WithContext } from "nanoeffects";
+
+// WithContext — checker-only: handlers also have ctx.store
+type Events = { save: Draft } & WithContext<{ store: Store }>;
+
+const bus = createBus<Events>({ context: { store } });
+```
+
+---
+Source: docs/typescript.md
+
+# Use nanoeffects in a TypeScript app with many files
+
+Read this page if your app is in TypeScript and the commands and modules live in different files. It shows how to write a command so that TypeScript infers its payload and result, and what to add when the handlers need the fields of your bus (`ctx.store`, the effects of `effectsPlugin`). For one file or for JavaScript you do not need it.
+
+## Write a command with its handler
+
+Give `createCommand` the handler and write nothing else. The payload comes from the annotated parameter, the result from the body. You do not write a generic.
+
+<!-- docs-check: skip - a file of examples/typescript, type-checked there -->
+```ts
+// user.ts
+import { createCommand, createModule } from "nanoeffects/actions";
+
+export type User = { id: string; name: string };
+
+// payload: string, from `id: string`; result: Promise<User>, from the body
+export const getUser = createCommand(
+  "user/get",
+  async (id: string, { signal }) => {
+    const response = await fetch(`/api/users/${id}`, { signal });
+    const user: User = await response.json();
+    return user;
+  },
+);
+
+// createModule: m.use binds the handler the command carries, while the module is mounted
+export const userModule = createModule("user", (m) => {
+  m.use(getUser);
+});
+```
+
+Mount the module where you create the bus. The result is typed from the handler:
+
+<!-- docs-check: skip - a file of examples/typescript, type-checked there -->
+```ts
+// main.ts
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { getUser, userModule } from "./user";
+
+const bus = createBus();
+const app = bus.use(modulePlugin([userModule])); // mounts the modules
+
+const user = bus.emit(getUser("1")); // Promise<User>
+```
+
+What you annotate, and why:
+
+| Part | Annotated? | Why |
+| ---- | ---------- | --- |
+| payload (`id: string`) | yes | a function parameter has no type to infer from |
+| `ctx` | no, for `signal` and the fields every task has | `signal`, `emit`, `on` and `run` are on every `ctx` |
+| result | no | inferred from the body |
+
+A wrong payload at the call (`getUser(1)`) is an error. Annotate the parameters, not the variable: a type on the whole variable, such as `const handler: Task<string, Events> = …`, fixes the type of the function, and the result becomes `unknown`.
+
+## Give `ctx` the fields of your bus
+
+Types of a bus live on the bus. `contextPlugin({ store })` and `effectsPlugin({ race })` make `ctx.store` and `ctx.race` known to the handlers of **that bus**. A command made in another file does not see the bus, so its `ctx` has no `store`:
+
+<!-- docs-check: skip - shows the error on purpose -->
+```ts
+export const getUser = createCommand("user/get", (id: string, ctx) => {
+  ctx.store; // error: Property 'store' does not exist
+});
+```
+
+At runtime the bus still gives the task its fields. Only the checker does not know it. Name the types of the bus once, in the file that creates it. `contextPlugin` takes the type of each field from the value you pass, so the event map holds only events. `EventsOf` reads the event map from the bus, with the fields that the plugins added. The code of this section is in [`examples/typescript-context`](../examples/typescript-context).
+
+<!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
+```ts
+// bus.ts
+import { type Context, contextPlugin, createBus, type EventsOf } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { effectsPlugin, race } from "nanoeffects/effects";
+
+// Events: event name → payload; nothing about ctx is written here
+type Events = { "user/loaded": User };
+
+export const bus = createBus<Events>()
+  .use(contextPlugin({ store })) // ctx.store, typed from the value `store`
+  .use(effectsPlugin({ race })); // ctx.race; each plugin returns the same bus, typed with its fields
+
+// the app of the bus: mounts modules and creates them with the types of the bus
+export const app = bus.use(modulePlugin()); // no modules yet: main.ts mounts them
+export const { createModule } = app; // createModule with the types of the bus
+
+export type AppEvents = EventsOf<typeof bus>; // the event map and all fields of ctx
+export type AppContext = Context<AppEvents>; // ctx of a handler of this bus: has store and race
+```
+
+| Type | What it is | Why you name it |
+| ---- | ---------- | --------------- |
+| `EventsOf<typeof bus>` | the event map of the bus, with the context fields of the plugins (and of `WithContext`, if you use it) | the source of `AppContext` |
+| `Context<AppEvents>` | the `ctx` that a handler of the bus gets | annotate the `ctx` of a handler given to `createCommand` |
+
+These types change nothing at runtime. They only tell the checker what the bus already does.
+
+Annotate `ctx` with `AppContext` where the handler reads a field of the bus, and create the module with the `createModule` that `bus.ts` exports, so its `m.on` handlers see the fields too:
+
+<!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
+```ts
+// user.ts
+import { createCommand } from "nanoeffects/actions";
+import { type AppContext, createModule } from "./bus";
+
+export const getUser = createCommand(
+  "user/get",
+  (id: string, { store, signal }: AppContext) => store.fetchUser(id, { signal }),
+);
+
+// createModule from bus.ts: handlers of the module see the context fields of the bus
+export const userModule = createModule("user", (m) => {
+  m.use(getUser);
+  m.on("user/loaded", (user, { store }) => store.remember(user));
+});
+```
+
+<!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
+```ts
+// main.ts: the modules are mounted here, because the module files need `app`
+import { app, bus } from "./bus";
+import { getUser, userModule } from "./user";
+
+const unmount = app.mount(userModule); // starts the module; unmount() undoes it
+const user = bus.emit(getUser("1")); // Promise<User>
+```
+
+`createModule` of the app only creates the module: it does not mount it, and it keeps no link to the bus. That is why the app in `bus.ts` starts without modules. `createModule` from `nanoeffects/actions` stays for a module made without a bus: there you write the event map yourself, `createModule<AppEvents>("user", …)`.
+
+## Keep the contract apart from the code
+
+When the file with the command must not import the code that implements it, make the command without a handler. Here you write the payload and the result once, as generics, and the handler goes to a module, where it needs no annotation:
+
+<!-- docs-check: skip - fragment of the file above -->
+```ts
+export const getUser = createCommand<string, Promise<User>>("user/get"); // the contract
+
+createModule("user", (m) => {
+  // payload and result come from the command, ctx from the app: no annotation
+  m.handle(getUser, (id, { store, signal }) => store.fetchUser(id, { signal }));
+});
+```
+
+A wrong payload, a wrong field of `ctx` and a wrong result are errors.
+
+## Check your setup
+
+- **A field is missing on `ctx`.** The `ctx` of a handler given to `createCommand` is not annotated: add `: AppContext`. A handler written inline in `m.handle` or `m.on` of a module made with the `createModule` of `bus.ts` does not need it. The default `ctx` has no fields of your bus.
+- **`EventsOf<typeof bus>` is `never`.** `bus` is not a bus. `bus.use(commandsPlugin())` and `bus.use(modulePlugin(...))` return the registry or the app, not the bus: keep the bus in its own constant (`bus`, then `app = bus.use(modulePlugin())`).
+- **`effectsPlugin` is not in the type.** `use` must come before you read `typeof bus`. Chain `createBus(...).use(effectsPlugin(...))` in one binding.
+- **A policy loses the types.** It does not: `latest(handler)` keeps the payload, the result and the context of `handler`.
+- **Do not pass the context as a generic of `createCommand`.** It is the fourth generic, after the payload, the result and the type string, so you would have to write all four. Annotate `ctx` with `AppContext`, or put the handler in a module made with the `createModule` of `bus.ts`.
+
+---
+Source: docs/migrating-from-saga.md
+
+# Coming from redux-saga
+
+Read this page if you know redux-saga and want to find the same job in nanoeffects. It maps the names, shows one saga rewritten, and lists what has no equivalent. It does not teach the library: start with the [Guide](guide.md).
+
+## Find the equivalent
+
+| redux-saga | nanoeffects |
+| ---------- | ----------- |
+| `takeEvery` | `bus.on(event, handler)` |
+| `takeLatest` | [`latest`](policies.md) |
+| `takeLeading` | [`leading`](policies.md) |
+| `debounce`, `throttle` | [`debounce`, `throttle`](policies.md) (same rules as lodash) |
+| `call(fn, x)` | `await ctx.run(task, x)` |
+| `fork(fn, x)` | `ctx.run(task, x)` without `await` |
+| `spawn(fn, x)` | `ctx.emit(event, x)` or `bus.emit(event, x)` |
+| `put(action)` | `ctx.emit(action)` |
+| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md) |
+| `select` | a [context field](context.md), such as `store` |
+| `all`, `race` | [`all`, `race`](effects.md) |
+| `retry`, `delay` | [`retry`, `delay`](effects.md) |
+| `cancel(task)` | `ctx.abort()` on the context, or a newer call under `latest` |
+| `eventChannel` | `bus.emitter(action)` as the callback of the subscription |
+| `actionChannel` | [`queue`](policies.md) and the other policies |
+
+## Rewrite a saga
+
+A saga that searches on every new query, cancels the older request, and retries a failed one:
+
+<!-- docs-check: skip - redux-saga code, not nanoeffects -->
+```js
+// redux-saga
+function* search({ payload }) {
+  const items = yield retry(3, 1000, api.search, payload);
+  yield put(found(items));
+}
+function* watchSearch() {
+  yield takeLatest("search", search);
+}
+```
+
+The same job in nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const search = (query, { signal }) => api.search(query, { signal });
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // latest: a newer "search" aborts this run; ctx.signal is aborted
+    const load = retry(search, { times: 3, delay: 1000 }); // retry: up to 3 attempts, 1 s apart
+    const items = await ctx.run(load, query); // child task, aborted with this handler
+    ctx.emit("found", items); // like put
+  }),
+);
+```
+
+Tasks are plain `async` functions. `ctx.signal` replaces `cancel`: pass it to `fetch` or to your client, and the request stops.
+
+## Start a task without waiting
+
+`fork` and `spawn` differ in what happens when the caller is aborted. Pick by that.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+const loadSidebar = (_, { signal }) => api.sidebar({ signal });
+
+bus.on("page-opened", async (_, ctx) => {
+  // like fork: a child of this task, aborted with it
+  const warmUp = ctx.run(loadSidebar);
+  warmUp.catch(console.error); // nobody awaits it, so handle the error here
+
+  // like spawn: a new task, not stopped when this one is aborted
+  ctx.emit("analytics", { page: "home" });
+});
+```
+
+## What is different
+
+- **Errors go up only through `await`.** `await ctx.run(task)` and `all(ctx, …)` throw the error of a child to the caller. A child that nobody awaits does not abort its parent, as a forked child does in redux-saga: handle it yourself, as above. See [Errors](errors.md).
+- **Abort goes down.** Aborting a task aborts its children. A child does not abort its siblings.
+- **Effects are not data.** `yield call(fn)` returns a description that a test can compare. Here `await` calls the function. Test with the real handler and fake timers, as the tests of this library do.
+- **No generators.** Sequential flows are `async` functions with `await take(ctx, event)`.
+- **No `END` of a channel.** A task stops when its signal aborts.
+- **One payload.** A task has one argument, so pass an object where a saga passes several.
+
+---
+Source: docs/migrating-from-effector.md
+
+# Coming from Effector
+
+Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Hold state (`createStore`, `combine`, `restore`) | Effector, or any store: [Stores](stores.md) |
+| Derive state from events (`.on`, `sample` into a store) | Effector, or any store |
+| Run a request when an event happens, cancel, retry, time out, trace | nanoeffects |
+
+nanoeffects has no store. `createStore` can be replaced by any store you like, for example Zustand: a store and its `set` do the job of `createStore` and `.on`. [Stores](stores.md) shows how each of Zustand, Redux, MobX, Jotai and others calls the bus. If you keep Effector, use nanoeffects only for the effects that `createEffect` runs with little control over overlapping calls.
+
+## Find the equivalent
+
+| Effector | nanoeffects |
+| -------- | ----------- |
+| `createEvent()` | an event name on the bus, or [`createAction`](actions.md) |
+| event call `loaded(user)` | `bus.emit("loaded", user)` |
+| `createEffect(handler)` | a handler: `bus.on(event, handler)` |
+| effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
+| `effect.pending` | not provided: keep a flag in your store, or read it from [Tracing](tracing.md) |
+| `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
+| `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
+| `sample({ filter })` | an `if` in the handler |
+| `debounce`, `throttle` from patronum | [`debounce`, `throttle`](policies.md) (same rules as lodash, checked in tests) |
+| take only the last effect call | [`latest`](policies.md) |
+| `attach` | a [context field](context.md): the handler reads it from `ctx` |
+| `fork()` and scope | one `createBus()` per scope |
+| `createStore`, `combine`, `restore` | any store, such as Zustand, Redux, MobX or Jotai: see [Stores](stores.md) |
+| `watch`, `createWatch` | `bus.on(event, handler)` |
+| `event.prepend(fn)` | a function that you write, `(event) => ({ key, value })`; the bus needs nothing |
+| `useStoreMap({ store, keys, fn })` | a selector of your store; with `useState` the component keeps the value |
+| `event.watch((e) => e.preventDefault())` | call `event.preventDefault()` in the `onSubmit` handler |
+
+## Rewrite an effect
+
+A search that runs on every query, and reacts to the result:
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+// Effector
+import { createEffect, createEvent, createStore, sample } from "effector";
+
+const queryChanged = createEvent();
+const searchFx = createEffect((query) => api.search(query));
+const $items = createStore([]).on(searchFx.doneData, (_, items) => items);
+
+sample({ clock: queryChanged, target: searchFx });
+```
+
+If the user types fast, several `searchFx` calls overlap, and the old ones are not cancelled. The same job in nanoeffects, with the old request cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer query aborts the request in flight
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("found", items);
+});
+
+bus.on("query-changed", debounce(300, search)); // debounce: run after 300 ms of quiet
+```
+
+The store (`$items`) is not here. Keep it in Effector and update it from the `found` event, or replace it with a store of your choice. The next example does that with Zustand.
+
+### Keep the state in Zustand
+
+Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
+
+```jsx
+// search-zustand.jsx
+import { create } from "zustand";
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+// create — Zustand: the store replaces $items
+const useSearchStore = create(() => ({ items: [] }));
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  useSearchStore.setState({ items }); // Zustand: replaces .on(searchFx.doneData, …)
+});
+
+bus.on("query-changed", debounce(300, search));
+
+export function Search() {
+  const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
+
+  return (
+    <div>
+      <input onChange={(event) => bus.emit("query-changed", event.target.value)} />
+      <ul>
+        {items.map((item) => (
+          <li key={item.id}>{item.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+`bus.emit("query-changed", …)` in `onChange` does the work of calling the `queryChanged` event. To also start a task when the store changes, see [Zustand in Stores](stores.md#zustand).
+
+## Rewrite a form
+
+The form from the [Forms recipe of the Effector docs](https://effector.dev/en/recipes/react/forms/) has five parts: an event for a change of a field (`fieldUpdate`), a store for the values (`$form`), an event for the submit (`formSubmitted`), an effect that sends them (`sendFormFx`), and a `sample` that reads the store when the form is submitted. Four of them keep state or wire units together. Only the effect has a counterpart in nanoeffects.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```jsx
+// Effector (adapted from the Effector docs)
+import { createEffect, createEvent, createStore, sample } from "effector";
+import { useStoreMap } from "effector-react";
+
+const formSubmitted = createEvent();
+const fieldUpdate = createEvent();
+
+const sendFormFx = createEffect((params) => {
+  console.log(params);
+});
+
+const $form = createStore({});
+$form.on(fieldUpdate, (form, { key, value }) => ({ ...form, [key]: value }));
+
+// sample: when the form is submitted, read $form and run the effect with it
+sample({ clock: formSubmitted, source: $form, target: sendFormFx });
+
+// prepend: turn a DOM event into the { key, value } that fieldUpdate takes
+const handleChange = fieldUpdate.prepend((event) => ({
+  key: event.target.name,
+  value: event.target.value,
+}));
+
+const Field = ({ name, type, label }) => {
+  const value = useStoreMap({
+    store: $form,
+    keys: [name],
+    fn: (values) => values[name] ?? "",
+  });
+
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={handleChange} />
+    </div>
+  );
+};
+
+const App = () => (
+  <form onSubmit={formSubmitted}>
+    <Field name="login" label="Login" />
+    <Field name="password" type="password" label="Password" />
+    <button type="submit">Submit!</button>
+  </form>
+);
+
+formSubmitted.watch((event) => {
+  event.preventDefault();
+});
+```
+
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+
+```js
+// form-bus.js
+import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: events and their handlers
+
+// bus.on — the job of sendFormFx: runs when the form is submitted
+bus.on("form/submitted", (values) => {
+  console.log(values);
+});
+```
+
+Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`; the event handler does the work of the `watch` that called `preventDefault`:
+
+```jsx
+// App.jsx
+import { useState } from "react";
+import { bus } from "./form-bus"; // the bus of the previous snippet
+
+function Field({ name, type, label, value, onChange }) {
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={onChange} />
+    </div>
+  );
+}
+
+export function App() {
+  const [form, setForm] = useState({}); // the values of the form, as $form held them
+
+  // one handler for every field, as handleChange was
+  function handleChange(event) {
+    const { name, value } = event.target;
+    setForm((current) => ({ ...current, [name]: value }));
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault(); // the page must not reload; no separate watcher is needed
+    bus.emit("form/submitted", form); // bus.emit — the values go in the event
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Field name="login" label="Login" value={form.login ?? ""} onChange={handleChange} />
+      <Field
+        name="password"
+        type="password"
+        label="Password"
+        value={form.password ?? ""}
+        onChange={handleChange}
+      />
+      <button type="submit">Submit!</button>
+    </form>
+  );
+}
+```
+
+`useStoreMap` re-renders only the field whose value changed. Here every field re-renders with the form, which is fine for a small form. If it matters, use the selector of your store (Zustand and Jotai have one).
+
+If the values live in a store outside React, give the store to the handlers with `createBus({ context: { store } })` ([Context fields](context.md)) and read it in the handler, as `sample` read `$form`.
+
+### Replace the log with a request
+
+`sendFormFx` only logs. A real sign-up sends a request, and then the double click and the network matter. `leading` drops a second submit while the first one runs, and `ctx.signal` lets the request be cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and their handlers
+
+// leading — a second submit is ignored while the request is running
+bus.on(
+  "form/submitted",
+  leading(async (values, ctx) => {
+    // api — your client; ctx.signal lets the request be cancelled
+    await api.signUp(values, { signal: ctx.signal });
+  }),
+);
+```
+
+Retrying a failed network request, and cancelling when the form closes, are in [Build a sign-up form in React](react.md).
+
+## Use both in one app
+
+Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const queryChanged = createAction("query/changed"); // a plain action creator
+
+const found = createEvent(); // Effector: the result comes back as an event
+const $items = createStore([]).on(found, (_, items) => items);
+const $query = createStore("");
+
+// watch calls back on every change of the store; bus.emitter turns it into an emit
+$query.watch(bus.emitter(queryChanged));
+
+bus.on(
+  queryChanged,
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    found(items); // back to Effector
+  }),
+);
+```
+
+## What is different
+
+- **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
+- **No `pending`.** A running task is visible through [Tracing](tracing.md), not through a store. A flag in your store set at the start and the end of the handler does the job.
+- **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
+- **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
+- **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.
+- **The event carries the data.** `sample({ source })` reads a store at the moment of the clock. Here the sender puts the values in the event (`bus.emit("form/submitted", form)`), or the handler reads a store from a [context field](context.md).
+- **Scopes are buses.** `fork()` becomes a `createBus()` per scope (a test, a request on the server).
+
+---
+Source: docs/migrating-from-rxjs.md
+
+# Use nanoeffects next to RxJS
+
+Read this page if your project uses RxJS and you wonder what nanoeffects takes over. It does not replace RxJS. The two split the work: RxJS shapes streams of values, nanoeffects runs the side effects that events start. It maps the operators, shows one search box both ways, and lists what stays in RxJS.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Start a request when something happens, cancel it when a newer one arrives, retry it, time it out | nanoeffects |
+| Know which task started which, log and trace it | nanoeffects ([Tracing](tracing.md)) |
+| Combine several streams, keep a running value, buffer, window, merge over time | RxJS |
+| Work with a stream as a value (`map`, `scan`, `combineLatest`) | RxJS |
+
+A handler in nanoeffects is one function per event. A pipeline in RxJS is a chain of operators over a stream. If your pipeline is a few operators that end in `switchMap` and a request, it fits a handler with a policy and is shorter. If it combines streams, it stays.
+
+## Find the equivalent
+
+| RxJS | nanoeffects |
+| ---- | ----------- |
+| `mergeMap` | `bus.on(event, handler)`: every event starts a task |
+| `switchMap` | [`latest`](policies.md) |
+| `exhaustMap` | [`leading`](policies.md) |
+| `concatMap` | [`queue`](policies.md) |
+| `debounceTime` | [`debounce`](policies.md) |
+| `throttleTime` | [`throttle`](policies.md) |
+| `groupBy` + `switchMap` | `latest(handler, { key })` |
+| `retry`, `retryWhen` | [`retry`, `backoff`](effects.md) |
+| `timeout` | [`timeout`](effects.md) |
+| `interval` + `switchMap` | [`poll`](effects.md) |
+| `takeUntil(stop$)` | `ctx.signal`, and [`take`](effects.md) to wait for the stop event |
+| `forkJoin` | [`all`](effects.md) |
+| `race` | [`race`](effects.md) |
+| `firstValueFrom(fromEvent(…))` | [`take(ctx, event)`](effects.md) |
+| `Subject` | `bus.emit` and `bus.on` |
+| `map`, `filter`, `scan`, `combineLatest`, `buffer`, `window`, `share` | stay in RxJS |
+| `distinctUntilChanged` | a check in the handler, or in the store subscription (see [Stores](stores.md)) |
+
+A policy and an operator differ in one thing. `switchMap` drops the old inner stream. `latest` aborts the old task through its `signal`, so a `fetch` that got the signal stops. Pass the signal on, or the work goes on in the background.
+
+## Rewrite a search box
+
+The same job in RxJS: wait for a pause, skip repeats, cancel the old request.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+// RxJS
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map, switchMap } from "rxjs/operators";
+
+fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+    switchMap((query) => api.searchStream(query)),
+  )
+  .subscribe((items) => render(items));
+```
+
+The same job in nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+
+bus.on("results", (items) => render(items));
+
+const input = document.querySelector("#search"); // the search box
+input.addEventListener("input", (event) => bus.emit("typed", event.target.value));
+```
+
+The skip of repeated values is not here. Add `if (query === lastQuery) return;` to the handler, or keep that one step in RxJS (next section).
+
+## Use both in one app
+
+Keep RxJS where a stream is how you think, and let events cross to the bus in either direction.
+
+**Bus to RxJS.** `createObserve(bus)` gives an Observable of an event ([Observables](observable.md)).
+
+**RxJS to bus.** `bus.emitter(action)` returns a callback that emits the action, so it is the argument of `subscribe` ([Stores](stores.md) has the plugin).
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { combineLatest } from "rxjs";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const filtersChanged = createAction("filters/changed"); // a plain action creator
+
+// RxJS: combine two streams into one value; nanoeffects does not do that
+const subscription = combineLatest([query$, category$]).subscribe(
+  bus.emitter(filtersChanged), // calls bus.emit(filtersChanged(value))
+);
+
+// nanoeffects: one cancellable request per change of the filters
+bus.on(
+  filtersChanged,
+  latest(async ([query, category], { signal }) => {
+    const items = await api.search(query, category, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+The subscription is not tied to a task. Call `subscription.unsubscribe()` when the screen goes away.
+
+## What is different
+
+- **No streams of values.** A handler gets one payload and runs a task. There is no `pipe`, no operator for the values that follow.
+- **Abort replaces unsubscribe for work in flight.** A stopped task is stopped through its `signal`. Pass it to `fetch` or to the client.
+- **Errors are not part of the stream.** A failed task rejects its own promise. Without `onError` on the bus nobody else hears it ([Errors](errors.md)).
+- **No completion.** An event bus does not end. A task ends when its work ends or its signal aborts.
+- **No marble tests.** Test with the real handler and fake timers.
+
+---
+Source: docs/semantics.md
+
+# Semantics
+
+Guarantees and sharp edges. Read when something surprises you; not required to start.
+
+- **An aborted task delivers no result.** If the task aborts before a promise settles, the promise rejects with the abort reason, even if the value was just produced in the same tick. `latest`, `debounce`, `all`, `race`, `take`, and the rest follow this rule.
+- **`emit` is a plain, synchronous loop** (see [Errors](errors.md)). A `ctx.emit` inside a handler is the same call: without `onError`, an error of a nested handler is thrown into the handler that emitted; with `onError` it goes there and `ctx.emit` does not throw.
+- **Rejections of async handlers** are not handled for you. Without `onError` they are unhandled rejections, which end a Node process by default. Use `onError` for async handlers.
+- **`leading` releases its lock when the task aborts**, not only when `fn` settles. A `fn` that ignores the abort signal can then overlap with the next run — pass `ctx.signal` to what `fn` does.
+- **Effects start their function synchronously**, so an event emitted right after the call reaches a `take` inside it.
+
+---
+Source: docs/tracing.md
+
+# Trace tasks
+
+Reference for long-lived apps that need to observe task phases, Redux DevTools, or a build without tracing. Not part of onboarding.
+
+## Attach a tracer
+
+Pass `trace` to `createBus`. Make it with `createTracer` from `nanoeffects/trace`, which takes a logger (a function) or an array of them. The tracing code lives in that entry, so a bus without `trace` does not carry it.
+
+```js
+import { createBus } from "nanoeffects";
+import { createTracer } from "nanoeffects/trace";
+
+const bus = createBus({
+  // createTracer — observe every task phase
+  trace: createTracer((event) => console.log(event)),
+});
+```
+
+Each `TraceEvent` has:
+
+| Field | Meaning |
+| ----- | ------- |
+| `id` | Unique task id within the bus |
+| `parent` | Id of the task that started this one (absent for handler tasks) |
+| `type` | Event type the task works on |
+| `effect` | `latest`, `debounce`, `throttle`, `leading`, `run`, `all`, `race`, … |
+| `phase` | `start`, `done`, `error`, `cancel`, or `drop` |
+| `payload` | Event payload |
+| `error` | Thrown value, only for `error` |
+
+Phases:
+
+- `start` — the work began.
+- `done` / `error` — it finished or threw.
+- `cancel` — aborted after it started (superseded by `latest`, parent aborted, lost a `race`).
+- `drop` — never started (`leading` while busy, a `throttle` call replaced by a newer one, a `debounce` call replaced before its delay ended).
+
+`all` and `race` are traced when you pass them the handler `ctx`: the group is one task; every starter is a child `run` task.
+
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("load", async (id, ctx) => {
+  await all(ctx, {
+    user: () => fetchUser(id),
+    posts: () => fetchPosts(id),
+  });
+});
+```
+
+## Use built-in loggers
+
+A logger is `(event) => void`. `createTracer` takes one logger or an array. A logger that throws is reported to `console.error` and never breaks the task or the other loggers.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, reduxDevtools } from "nanoeffects/trace";
+
+const bus = createBus({
+  trace: createTracer([reduxDevtools({ name: "app" }), consoleLogger()]),
+});
+```
+
+| Logger | What it does |
+| ------ | ------------ |
+| `reduxDevtools()` | Sends tasks to Redux DevTools as `type/effect/phase`; state is `{ running }` |
+| `consoleLogger()` | Prints one line per phase, indented by task depth |
+| `performanceLogger()` | User Timing measures for the browser Performance panel |
+| `createTraceRecorder()` | Keeps events in `recorder.events`, for tests |
+
+### Cut volume in production
+
+```js
+import { createTracer } from "nanoeffects/trace";
+
+createTracer(logger, {
+  sample: 0.05, // trace 5% of handler calls (share, or function of { type, payload })
+  filter: (event) => event.phase === "error", // keep only failures
+});
+```
+
+- `sample` is decided once per root task; every task below it follows, so a trace is never cut in the middle. Unsampled tasks cost almost nothing.
+- `filter` runs on each event before any logger sees it.
+
+### Configure Redux DevTools
+
+Read-only (the bus owns no state, so there is no time travel). Does nothing when the extension is not installed. Has its own instance in the DevTools picker, apart from your store.
+
+Quiet by default:
+
+- **A task is one action**, sent when it ends (`done`, `error`, `cancel`, `drop`). Running tasks are in `{ running }`. `starts: true` also sends every start.
+- **Only the top is shown**: handler tasks and the effects they start. Attempts and starters under them are hidden. `depth: 0` — handlers only; `depth: 3` — more; `Infinity` — everything.
+- `maxAge: 200` — how many actions DevTools keeps (its default is 50).
+
+```js
+import { reduxDevtools } from "nanoeffects/trace";
+
+reduxDevtools({ name: "app", depth: 0 }); // one line per handler call
+reduxDevtools({ name: "app", starts: true, depth: Infinity }); // everything
+```
+
+### Write your own logger
+
+```ts
+import type { TraceLogger } from "nanoeffects";
+
+const errorsOnly = (): TraceLogger => (event) => {
+  if (event.phase === "error") {
+    report(event.error);
+  }
+};
+```
+
+## Drop tracing from a build
+
+Without a tracer the hooks cost almost nothing. `nanoeffects/trace` is only bundled when imported.
+
+To also drop tracing code from the core, use the `notrace` export condition. The package ships a second build of `index`, `effects`, `policies`, and `actions` with `__NANOEFFECTS_TRACE__` set to `false`.
+
+```js
+// vite / rolldown
+resolve: { conditions: ["notrace"] }
+// webpack
+resolve: { conditionNames: ["notrace", "import", "..."] }
+// esbuild
+conditions: ["notrace"]
+```
+
+In a build from the sources, `define: { __NANOEFFECTS_TRACE__: "false" }` does the same. With the condition set, that build’s types have no `trace` option: `createBus({ trace })` is a type error. `nanoeffects/trace` has no `notrace` build. The saving is about 0.4 kB gzip of the whole library.
+
+---
+Source: docs/observable.md
+
+# Turn events into Observables
+
+Use this page only when you already work in Observables / RxJS. Prefer `bus.on` with policies for cancellation and tracing.
+
+`createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";
+import { createObserve } from "nanoeffects/observable";
+
+const observe = createObserve(bus); // Observable per event name
+
+from(observe("typed"))
+  .pipe(debounceTime(300), distinctUntilChanged(), switchMap(searchRequest))
+  .subscribe((items) => bus.emit("results", items));
+```
+
+- `observe(event)` returns an Observable of the payloads of that event. Each `subscribe` is a `bus.on` of its own; `unsubscribe()` removes it.
+- `subscribe` takes a function or an object with `next`.
+- The stream never completes and never fails: events are the only thing that arrives. Errors of the subscriber’s handler belong to the subscriber.
+- A subscription made this way is not tied to a task. End it yourself: `onAbort(ctx, subscription.unsubscribe)` inside a task, or with the signal of a module.
+- For cancellation, policies, and tracing, keep to `bus.on` with `latest`, `debounce`, `queue` — they know about tasks. The Observable is for places where a stream is already how you work.
+
+---
+Source: docs/hmr.md
+
+# Hot reload and development diagnostics
+
+Use this page in development with modules and hot reload. Skip until you mount domains with `modulePlugin`.
+
+When a file is edited, the bundler loads its new version and runs it again, while the page and the rest of the code stay alive. For a bus that can go wrong in three ways:
+
+1. A file that calls `bus.on(...)` subscribes a second time.
+2. A file that makes the bus makes a new one.
+3. Tasks of the old code keep running.
+
+## Replace modules by name
+
+Mounting a module whose name is taken replaces the mounted one. The old module is unmounted first — and with it its subscriptions, bound commands, sub-modules, and background tasks (their signals abort). The new version of a module file only has to mount again; nothing piles up.
+
+- **Names must be unique.** The name means “this is the new version of that module”, so two different modules with one name replace each other. The name is also the type of the module’s tasks in the trace.
+- **Pass `signal` to what the module does.** An unmount aborts the tasks, but a `fetch` or a loop that ignores `ctx.signal` runs on with the old code.
+- **Sub-modules** (`m.use(...)`) are replaced by name inside their parent. A reload of the parent replaces it with all its children.
+- Keep the bus and the app in a file that is not reloaded (or in what your bundler keeps across reloads), so a reload does not make a new bus that other files do not talk to.
+
+A `bus.on` outside a module returns the function that unsubscribes: hand it to the dispose hook of your bundler, or put the subscription in a module.
+
+## Report leaks with `devPlugin`
+
+`bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
+
+```js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { devPlugin } from "nanoeffects/dev";
+
+const bus = createBus();
+const app = bus.use(modulePlugin([userModule]));
+// devPlugin — warn on piled-up listeners; log module mount/replace/unmount
+bus.use(devPlugin({ app }));
+```
+
+- **Listeners that pile up.** When more than `maxListeners` (default `10`) listeners of one event were added and not unsubscribed, one warning names the event and the count. The count follows the function that `on` returns; `bus.off(event, fn)` is not seen.
+- **Modules.** With `app` it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
+- **Options.** `leaks: false` and `modules: false` switch a diagnostic off; `maxListeners` sets the limit; `log` receives the messages instead of the console.
+- **Disconnect.** `bus.use(devPlugin(...))` returns the function that stops the diagnostics and puts `bus.on` and `app.mount` back.
+
+It changes no behavior: it wraps `bus.on`, `app.mount`, and `app.unmount` and adds messages.
+
+### Keep the import in production
+
+`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin({ app }))` can stay without a guard: it touches nothing and costs a few bytes.
+
+If you want even the call gone, guard it (`if (import.meta.env.DEV)` in Vite). An app that does not import the entry does not carry it.