nanoeffects 0.7.0 → 0.9.0

package/llms-full.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - 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`.
+- 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`; `usePolicy`; needs React), `nanoeffects/trace`, `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ---
@@ -86,6 +86,74 @@ unbind();
 - An event that only `"*"` listens to counts as heard, so `onUnhandled` does not fire for it.
 - `bus.off("*")` removes every `"*"` listener; `bus.off()` clears the whole bus, `"*"` included.
 
+### Pick events with a function
+
+To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { matchPlugin } from "nanoeffects/match";
+
+// matchPlugin — lets on, once and off take a function that picks the events
+export const bus = createBus().use(matchPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+export const userLoaded = createAction("user/loaded");
+export const userFailed = createAction("user/failed");
+```
+
+```js
+// user-handlers.js
+import { bus } from "./bus";
+
+// the function picks the events; the handler gets the payload and the context of each
+bus.on(
+  (action) => action.type.startsWith("user/"),
+  (payload, ctx) => {
+    console.log(ctx.type, payload);
+  },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { userFailed, userLoaded } from "./user";
+
+bus.emit(userLoaded({ id: "1" })); // user/loaded { id: "1" }
+bus.emit("order/placed", 5); // not picked
+bus.emit(userFailed("boom")); // user/failed boom
+```
+
+- `once(fn, handler)` waits for the first event that `fn` accepts. `off(fn)` removes every handler of `fn`, and `off(fn, handler)` removes one.
+- An action creator or a command still means that one event: only a function with no `type` is a function that picks events.
+- The cost: the handler listens to `"*"`, so each event makes one task for each such subscription, also when the function says no, and an event that only such a subscription listens to counts as heard for `onUnhandled`. For a few known events, `on(creator, handler)` is cheaper.
+- It works in any order with the other plugins, `devPlugin` included.
+
+In TypeScript a function that is a type guard narrows the payload of the handler:
+
+```ts
+import { bus } from "./bus";
+
+type User = { id: string };
+
+// the guard says which event this is, and the handler gets its payload typed
+const isLoaded = (action: {
+  type: string;
+  payload: unknown;
+}): action is { type: "user/loaded"; payload: User } => action.type === "user/loaded";
+
+bus.on(isLoaded, (user) => console.log(user.id)); // user: User
+```
+
+`ctx.on` takes such a function at run time too, but its type does not know it yet.
+
 ## 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.
@@ -166,7 +234,7 @@ const searchLatest = latest(async (query, { signal }) => {
 bus.on("search", debounce(300, searchLatest));
 ```
 
-Full options: [Policies](policies.md).
+Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 
 ## 5. Add retry and timeout
 
@@ -242,22 +310,42 @@ More in [Effects](effects.md).
 
 `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).
 
+From here on the bus is kept in one file and the events in files named after their domain (`move.js`, `math.js`), as in a real app: the events can then be imported anywhere without importing the bus.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+export const bus = createBus();
+```
+
+```js
+// move.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — names an event; calling it builds { type, payload }
+export const moved = createAction("moved");
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+// createCommand — like an action, but emit runs a handler and returns its result
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { moved } from "./move";
+import { double } from "./math";
 
 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
 ```
 
@@ -268,14 +356,25 @@ Use strings for the plain case. Use objects when other code already builds actio
 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";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { commandsPlugin } from "nanoeffects/actions";
+
+export const bus = createBus();
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(commandsPlugin());
+export const commands = bus.use(commandsPlugin());
+```
+
+```js
+import { bus, commands } from "./bus";
+import { getUser } from "./user";
 
 bus.emit(getUser("1")); // throws: No handler for command "user/get"
 
@@ -296,16 +395,27 @@ Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can reg
 **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";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
-const double = createCommand("math/double", (value) => value * 2); // carries its handler
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+export const double = createCommand("math/double", (value) => value * 2); // carries its handler
+```
+
+```js
+// greeting-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser } from "./user";
+import { double } from "./math";
 
 // createModule — one feature; name is stable for hot reload replace
-const greeting = createModule("greeting", (m) => {
+export const greeting = createModule("greeting", (m) => {
   // m.on — like bus.on, removed automatically on unmount
   m.on("greet", (name) => console.log(`hello ${name}`));
 
@@ -315,9 +425,23 @@ const greeting = createModule("greeting", (m) => {
   // m.use — register a command that already has a handler, for this module’s life
   m.use(double);
 });
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { greeting } from "./greeting-module";
 
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([greeting]));
+export const app = bus.use(modulePlugin([greeting]));
+```
+
+```js
+import { app, bus } from "./bus";
+import { greeting } from "./greeting-module";
+
 bus.emit("greet", "Ada"); // hello Ada
 app.unmount(greeting); // greet listener and getUser binding are gone
 ```
@@ -376,6 +500,51 @@ More in [Errors](errors.md).
 | Guarantees | [Semantics](semantics.md) |
 | Which import | [Package entries](package.md) |
 
+---
+Source: docs/motivation.md
+
+# Why nanoeffects exists
+
+Read this page if you build an SDK, a core library or a micro-frontend shell and wonder why you would pick a new event bus. It explains the constraints the library was made for. It does not teach the API: start with the [Guide](guide.md).
+
+## The problem: a shared dependency is a shared risk
+
+A shared library (an SDK, a core package, a platform shell) is loaded by many apps. Whatever it depends on, the apps depend on too. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other.
+
+Module Federation makes this visible. Each remote can bring its own copy unless every team agrees on a `singleton` and a version range. The [Nx guide on library versions](https://nx.dev/docs/kb/manage-library-versions-with-module-federation) lists the result: libraries with internal state conflict, and a missing method in one version breaks callers written for another.
+
+Real cases from the libraries nanoeffects was compared with:
+
+| Library | What goes wrong | Source |
+| ------- | --------------- | ------ |
+| Redux, React Redux | A shared component library uses `react-redux`. Every micro-frontend must use the same version of that library, or `react-redux` "breaks weirdly". | [react-redux#1949](https://github.com/reduxjs/react-redux/issues/1949) |
+| Redux | A store is reachable only under a `Provider`. Each sub-app needs its own provider, and a second one must not be created when a module is injected. Reducers duplicated between the host and a module add to it. | [Redux on Module Federation](https://dev.to/manomano-tech-team/how-to-work-with-redux-on-module-federation-13gm) |
+| Effector | A library that uses `effector-react/scope` and is bundled into another project gets two instances. Its `Provider` is not seen by `useStore` of the app: "no scope found". | [effector#727](https://github.com/effector/effector/issues/727) |
+| RxJS | Two copies give two `Observable` classes. Types of one version do not fit the other, and operators added to one copy are missing on the other. The advice is "one version in `node_modules`". | [RxJS#2984](https://github.com/ReactiveX/rxjs/issues/2984), [neo4j-javascript-driver#978](https://github.com/neo4j/neo4j-javascript-driver/issues/978) |
+
+A library that is **not** a shared singleton cannot break this way. nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
+
+## Why not the alternatives
+
+| Option | Why it did not fit |
+| ------ | ------------------ |
+| Redux (with sagas) | A store and a provider shared by every consumer, which is the risk above. `redux-saga` also has no cheap way to get an answer back from an event: effects talk through the store. |
+| Effector | A graph with global identity. A version or scope mismatch between the SDK and the app reaches the whole infrastructure. |
+| Zustand | Good state, but it is a store, not a way to run and cancel work. It is the natural place to hold state next to nanoeffects: see [Stores](stores.md). |
+| RxJS | Flexible, but learning its ecosystem (operators, subjects, schedulers) is a high entry cost for every developer who touches the SDK. The package is also not small: [Bundlephobia](https://bundlephobia.com/package/rxjs) reports 17.3 kB minified and gzipped for 7.8.2. |
+
+## What the library does instead
+
+- **No dependencies, no global state.** It is safe to ship inside an SDK next to whatever the host app runs. It does not need a `singleton` entry in the Module Federation config.
+- **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and commands are separate entries you import only when you need them. See [Package entries](package.md).
+- **Simple first.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
+- **`emit` can return an answer.** A [command](actions.md) is an event whose handler returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
+- **Easy to debug.** Event-driven code is hard to follow: you see an effect and not the event that caused it. Every task knows its parent, so [tracing](tracing.md) shows the chain of events, with loggers for the console, the Performance panel and Redux DevTools.
+
+## When this is not the right tool
+
+nanoeffects holds no state. If you need a store, keep Redux, Zustand or Effector and let the bus run the async work: [Stores](stores.md). If you already have streams everywhere, keep RxJS: [Use nanoeffects next to RxJS](migrating-from-rxjs.md).
+
 ---
 Source: docs/package.md
 
@@ -389,6 +558,9 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `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/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` |
+| `nanoeffects/oop` | `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` |
 | `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one command, action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve` |
@@ -400,67 +572,236 @@ The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists
 
 ## Give the docs to an AI assistant
 
-The package ships two plain-text files for assistants that write code with it:
+The package ships 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.
+- `skills/nanoeffects/SKILL.md`: a skill for assistants that support skills (for example Claude Code). It says when to suggest nanoeffects, when not to, and the same rules. Copy the folder to `.claude/skills/` in your project or to `~/.claude/skills/`.
 
-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.
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. All match the installed version.
 
 ---
 Source: docs/plugins.md
 
 # Choose the plugins of a bus
 
-Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registry of handlers, diagnostics. Read this page when you want to know which plugins exist, what each one returns, and in what order to use them. Skip it for a small bus: `createBus()` alone is enough.
+Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registry of handlers, diagnostics. Read this page when you want to know which plugins exist, what each one gives you, and in what order to use them. Skip it for a small bus: `createBus()` alone is enough.
 
 ## Use a plugin
 
-A plugin is a function of the bus. `bus.use(plugin)` calls it with the bus and returns whatever the plugin returns.
+A plugin is a function of the bus. `bus.use(plugin)` calls it with the bus and returns whatever the plugin returns. Most plugins return the same bus, so you can chain them: `createBus().use(a).use(b)`. A few return something of their own (a registry, an app, a `disconnect` function): keep it.
+
+In TypeScript keep the result of `contextPlugin` and `effectsPlugin`: the type of the bus with its new fields is the type they return (`const bus = createBus().use(contextPlugin({ store }))`).
+
+## Main plugins
+
+These four cover what most apps need: shared dependencies, effects, commands and modules. Start here.
+
+| Plugin | What it gives you | Import | `bus.use` returns |
+| ------ | ----------------- | ------ | ----------------- |
+| [`contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin) | Your own fields (a store, a client, a logger) on `ctx` of every handler. | `nanoeffects` | The same bus, typed with the fields |
+| [`effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin) | `race`, `all`, `delay` and your own effects on `ctx`, called without passing `ctx`. | `nanoeffects/effects` | The same bus, typed with the effects |
+| [`commandsPlugin`](#let-a-test-replace-a-handler-commandsplugin) | The handlers of commands in a registry, so a test can replace one. | `nanoeffects/actions` | The registry `{ run, handle }` |
+| [`modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin) | A module: the listeners, handlers and tasks of one domain, mounted and unmounted with one call. | `nanoeffects/actions` | The app `{ mount, unmount, isMounted, dispose, commands, createModule }` |
+
+### Put a store or a client on every handler: `contextPlugin`
+
+Every task gets the same fields on `ctx`: a store, an API client, a logger. The types come from the values. More in [Context fields](context.md).
+
+```js
+import { contextPlugin, createBus } from "nanoeffects";
+
+// contextPlugin — every handler gets ctx.store
+const bus = createBus().use(contextPlugin({ store }));
+
+bus.on("save", (draft, { store }) => store.put(draft));
+```
+
+### Use `race` and `delay` without `ctx`: `effectsPlugin`
+
+Effects such as `race`, `all`, `take` and `delay` are bound to the task, so a handler calls `race({ … })` and not `race(ctx, { … })`. Your own functions that take `{ signal }` first work too. More in [Effects](effects.md#put-selected-effects-on-ctx).
 
 ```js
 import { createBus } from "nanoeffects";
+import { delay, effectsPlugin, race } from "nanoeffects/effects";
 
-// your own plugin: a function of the bus that returns what you want back
-const countPlugin = (bus) => {
-  let count = 0;
-  const unbind = bus.on("*", () => {
-    count += 1;
+// effectsPlugin — race and delay are bound to the task of each handler
+const bus = createBus().use(effectsPlugin({ race, delay }));
+
+bus.on("load", async (id, { race, delay }) => {
+  const result = await race({
+    data: ({ signal }) => api.get(id, { signal }),
+    timeout: () => delay(5000),
   });
-  return { count: () => count, stop: unbind };
-};
+});
+```
+
+### Let a test replace a handler: `commandsPlugin`
+
+Commands get their handlers from a registry that belongs to the bus. A command can be only a contract, and a test binds a fake. More in [Actions](actions.md#describe-events-commands-and-jobs).
+
+```js
+import { createBus } from "nanoeffects";
+import { commandsPlugin, createCommand } from "nanoeffects/actions";
 
+const getUser = createCommand("user/get"); // a contract: no handler yet
 const bus = createBus();
-// use — calls countPlugin(bus) and returns its result
-const counter = bus.use(countPlugin);
 
-bus.emit("greet", "Ada");
-console.log(counter.count()); // 1
-counter.stop();
+// commandsPlugin — the registry of handlers of this bus
+const commands = bus.use(commandsPlugin());
+
+commands.handle(getUser, async (id) => ({ id })); // the latest binding wins
+const user = await bus.emit(getUser("1")); // { id: "1" }
+```
+
+### Mount a domain as one unit: `modulePlugin`
+
+A module groups the listeners, the bound commands and the background tasks of one domain, and ends all of them when it is unmounted. It also makes [hot reload](hmr.md) work. More in [Modules](actions.md#mount-domains-with-modules).
+
+```js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// modulePlugin — mounts userModule on the first use of the app or the bus, and returns the app
+const app = bus.use(modulePlugin([userModule]));
+
+app.unmount(userModule); // its listeners, bound commands and tasks are gone
+```
+
+## Extra plugins
+
+Add one of these when you meet its need. None of them is required.
+
+| Plugin | What it gives you | Import | `bus.use` returns |
+| ------ | ----------------- | ------ | ----------------- |
+| [`scopePlugin`](#give-one-command-its-own-fields-scopeplugin) | Its own fields for one command, action, job or module, and a way to replace them in one `emit`. | `nanoeffects/scope` | The same bus |
+| [`signalPlugin`](#tie-an-emit-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
+| [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) | `on` that listens to a group of events which a function picks. | `nanoeffects/match` | The same bus, typed with the new overloads |
+| [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) | A callback that emits an action, to give to a state manager. | `nanoeffects/actions` | The same bus, with `emitter` |
+| [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) | A React hook that emits when a value of a component changes. | `nanoeffects/react` | The same bus, with `useEmitter` |
+| [`devPlugin`](#find-leaks-while-you-develop-devplugin) | Warnings about listeners that pile up, and messages about modules, while you develop. | `nanoeffects/dev` | A function that disconnects it |
+
+### Give one command its own fields: `scopePlugin`
+
+A command, an action, a job or a module can carry its own fields and effects, and one `emit` can replace them. A test gives a fake to one call. More in [Scopes](scope.md).
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scope of a command work on this bus
+const bus = createBus().use(scopePlugin());
+
+// the last argument: fields of this command only
+const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
+  api,
+});
+
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+bus.emit(getUser("1"), { api: fakeApi }); // a fake api for this call only
+```
+
+### Tie an emit to an outside signal: `signalPlugin`
+
+A library such as React Query owns the request and gives you an `AbortSignal`. `emit` takes it as `{ signal }` and aborts the tasks it starts when the signal aborts, so `timeout`, `retry` and the request stop too. More in [Use nanoeffects with React Query and SWR](query-libraries.md).
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — emit takes { signal } for a command, a job or an action
+const bus = createBus().use(signalPlugin());
+
+const getUser = createCommand("user/get", (id, { signal }) => api.getUser(id, { signal }));
+
+const controller = new AbortController();
+bus.emit(getUser("1"), { signal: controller.signal }); // runs the command
+controller.abort(); // ctx.signal of the handler aborts with it
+```
+
+### Listen to a group of events: `matchPlugin`
+
+`on`, `once` and `off` take a function that picks the events, such as every `user/*` event. A type guard narrows the payload. The subscription listens to every event, so for a few known events `on(creator, handler)` is cheaper. More in the [Guide](guide.md#pick-events-with-a-function).
+
+```js
+import { createBus } from "nanoeffects";
+import { matchPlugin } from "nanoeffects/match";
+
+// matchPlugin — on takes a function that picks the events
+const bus = createBus().use(matchPlugin());
+
+bus.on(
+  (action) => action.type.startsWith("user/"),
+  (payload, ctx) => console.log(ctx.type, payload),
+);
+```
+
+### Hand the bus to a state manager: `emitterPlugin`
+
+`bus.emitter(creator)` is a callback that emits an action. A state manager takes it as its subscription callback, so a change of the store becomes an event. More in [Stores](stores.md#emit-from-a-state-manager).
+
+```js
+import { atom } from "nanostores";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+
+// emitterPlugin — adds bus.emitter
+const bus = createBus().use(emitterPlugin());
+const nameChanged = createAction("name/changed");
+const $name = atom("");
+
+$name.listen(bus.emitter(nameChanged)); // every change of $name emits nameChanged
+```
+
+### Tell the bus when a React value changes: `reactPlugin`
+
+`useEmitter(event, value)` emits after a render commits with a new value. It does not emit on mount, and not twice under StrictMode. It needs React 18 or newer. More in [Stores](stores.md#react-sharing-a-value-across-components).
+
+```jsx
+import { useState } from "react";
+import { createBus } from "nanoeffects";
+import { reactPlugin } from "nanoeffects/react";
+
+// reactPlugin — adds bus.useEmitter; destructuring gives a free hook
+const bus = createBus().use(reactPlugin());
+const { useEmitter } = bus;
+
+function Profile() {
+  const [name, setName] = useState("");
+  useEmitter("name/changed", name); // emits after a render with a new name
+  return <input value={name} onChange={(event) => setName(event.target.value)} />;
+}
 ```
 
-The bus keeps no list of plugins. A plugin that was used cannot be taken out by the bus; it returns its own `stop` or `disconnect` when it needs one.
+### Find leaks while you develop: `devPlugin`
+
+It warns about listeners that were added and never unbound, and reports the modules that are mounted, replaced and unmounted. In a production build `nanoeffects/dev` is empty, so the call can stay. More in [Hot reload](hmr.md#report-leaks-with-devplugin).
+
+```js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { devPlugin } from "nanoeffects/dev";
 
-## See every plugin
+const bus = createBus();
+bus.use(modulePlugin([userModule]));
 
-| Plugin | Import | It adds | `bus.use` returns | Page |
-| ------ | ------ | ------- | ----------------- | ---- |
-| `contextPlugin` | `nanoeffects` | Fields on `ctx` of every task | The same bus, typed with the fields | [Context fields](context.md) |
-| `effectsPlugin` | `nanoeffects/effects` | `race`, `all`, `take`, `delay` and your own effects on `ctx`, bound to the task | The same bus, typed with the effects | [Effects](effects.md#put-selected-effects-on-ctx) |
-| `scopePlugin` | `nanoeffects/scope` | Fields and effects for one command, action, job, module or `emit` | The same bus | [Scopes](scope.md) |
-| `commandsPlugin` | `nanoeffects/actions` | The registry of command handlers, `bus.commands` | The registry `{ run, handle }` | [Actions](actions.md#describe-events-commands-and-jobs) |
-| `modulePlugin` | `nanoeffects/actions` | Modules that mount and unmount as one unit | The app `{ mount, unmount, isMounted, dispose, commands, createModule }` | [Modules](actions.md#mount-domains-with-modules) |
-| `emitterPlugin` | `nanoeffects/actions` | `bus.emitter(creator)`, a callback that emits an action | The same bus, with `emitter` | [Stores](stores.md#emit-from-a-state-manager) |
-| `reactPlugin` | `nanoeffects/react` | `bus.useEmitter(event, value)`, a React hook | The same bus, with `useEmitter` | [React and stores](stores.md#react-sharing-a-value-across-components) |
-| `devPlugin` | `nanoeffects/dev` | Warnings about listeners that pile up, and messages about modules | A function that disconnects it | [Hot reload](hmr.md#report-leaks-with-devplugin) |
+// devPlugin — warnings and messages in the console while you develop;
+// it finds the app of modulePlugin on the bus, whichever you use first
+const disconnect = bus.use(devPlugin());
 
-"The same bus" means you can keep writing `bus` and ignore the result. Keep the result of `contextPlugin` and `effectsPlugin` in TypeScript, though: the type of the bus with its new fields is the type they return (`const bus = createBus().use(contextPlugin({ store }))`).
+disconnect(); // stops the diagnostics
+```
 
 ## Put them together
 
-One bus with every plugin that does not need React. The order is explained in the next section.
+One bus with every plugin that does not need React, in a file of its own. The events of the app stay in other files. The plugins work in any order; the next section says what that means for modules.
 
 ```js
+// bus.js
 import { contextPlugin, createBus } from "nanoeffects";
 import {
   commandsPlugin,
@@ -469,47 +810,45 @@ import {
 } from "nanoeffects/actions";
 import { devPlugin } from "nanoeffects/dev";
 import { all, effectsPlugin, race } from "nanoeffects/effects";
+import { matchPlugin } from "nanoeffects/match";
 import { scopePlugin } from "nanoeffects/scope";
 
-const bus = createBus()
+export const bus = createBus()
   .use(contextPlugin({ store })) // ctx.store on every task
   .use(effectsPlugin({ race, all })) // ctx.race and ctx.all, bound to the task
   .use(scopePlugin()) // scopes for commands, actions, jobs, modules and emit
+  .use(matchPlugin()) // bus.on takes a function that picks the events
   .use(emitterPlugin()); // bus.emitter(creator)
 
 // commandsPlugin — the registry of command handlers; keep it to bind handlers later
-const commands = bus.use(commandsPlugin());
+export const commands = bus.use(commandsPlugin());
 
-// modulePlugin — mounts userModule now; keep app to mount and unmount later
-const app = bus.use(modulePlugin([userModule]));
+// modulePlugin — mounts userModule on the first use; keep app to mount and unmount later
+export const app = bus.use(modulePlugin([userModule]));
 
 // devPlugin — reports leaks and modules while you develop; keep disconnect to remove it
-const disconnect = bus.use(devPlugin({ app }));
+export const disconnect = bus.use(devPlugin());
 ```
 
-## Follow the order
+## Use them in any order
+
+The plugins give the same result in any order. Use them as they read best, and put the app of `modulePlugin` where you keep it.
 
-Most plugins do not care about each other. These pairs do:
+Two things happen because modules are mounted late:
 
-| Rule | Why |
-| ---- | --- |
-| `scopePlugin` after `effectsPlugin` | `effectsPlugin` assigns its effects on `ctx`, so one used later would replace an effect with the same name that a scope put there. |
-| `scopePlugin` before `modulePlugin` | `modulePlugin` mounts the modules when it is used, and a module with a scope needs the plugin by then. |
-| `commandsPlugin` before `modulePlugin`, if you bind handlers yourself | `modulePlugin` uses the registry that exists. Without one it makes its own, which is `app.commands`. |
-| `modulePlugin` before `devPlugin({ app })` | `devPlugin` reports the modules of the `app` that `modulePlugin` returned. |
-| `emitterPlugin` and `reactPlugin` anywhere | They only call `bus.emit`, which is read when you call them. |
+- **Modules start on the first use.** `modulePlugin([userModule])` mounts `userModule` when the app or the bus is first used: the first `bus.emit`, or the first call of `app.mount`, `app.unmount`, `app.isMounted`, `app.dispose` or the read of `app.commands`. By then every plugin is on the bus, so a module and the tasks it spawns have the fields, effects and scopes of the plugins you used after `modulePlugin`, and `m.on(fn, handler)` works with `matchPlugin`.
+- **Listeners keep their place.** A `bus.on` after `bus.use(modulePlugin(...))` is held until the modules are mounted, then made, in the order you wrote them. The listeners of a module therefore stay ahead of the ones registered after the plugin, and behind the ones registered before it. The function `bus.on` returns works before and after.
 
-Two more things the checker enforces. A name that is already a context field of the bus is a type error when `contextPlugin` or `effectsPlugin` adds it again. `contextPlugin` does not replace a field that is on `ctx` already, so a scope wins over it in any order.
+Other plugins do not need an order for another reason:
 
-## Choose by need
+- `commandsPlugin` binds its list in the registry that the bus has, so it can come before or after `modulePlugin`. A custom `bus.commands = { run }` is replaced.
+- `effectsPlugin` and `contextPlugin` do not replace a field that is on `ctx` already, so a scope wins in any order.
+- `devPlugin()` finds the app that `modulePlugin` put on the bus (`bus.app`). `devPlugin({ app })` still works.
+- `matchPlugin` and `devPlugin` both wrap `bus.on`; `devPlugin` counts a function that picks events under `"*"`, and its `disconnect` leaves a wrapper that was put on top of it.
 
-- **A store, a client or a logger on every handler.** `contextPlugin`. Or `createBus({ context })` when you do not need the types from the value.
-- **`race`, `all` or your own effect without passing `ctx`.** `effectsPlugin`.
-- **Fields for one command, or a fake for one test call.** `scopePlugin`.
-- **A request with a result, or handlers that a test can replace.** `commandsPlugin`. Add `modulePlugin` when the domain needs a mount and an unmount.
-- **A callback for a state manager, such as `$name.listen(...)`.** `emitterPlugin`.
-- **Tell the bus when a value of a React component changes.** `reactPlugin`.
-- **Find listeners that were never unbound, or see modules reload.** `devPlugin`. In a production build `nanoeffects/dev` is empty, so the call can stay.
+A name that is already a context field of the bus is a type error when `contextPlugin` or `effectsPlugin` adds it again.
+
+A test puts every plugin on a bus in many orders and checks what each one does (`src/tests/plugin-matrix.test.ts`). An order that breaks something is a bug.
 
 ## See what is not a plugin
 
@@ -517,8 +856,38 @@ These connect the bus to something, but are not used with `bus.use`:
 
 - `createEffectsMiddleware(bus, { filter })` from `nanoeffects/redux` is a Redux middleware for a bus that exists. See [Stores](stores.md#wire-redux-toolkit-to-a-bus).
 - `createBus({ trace })` takes a tracer from `nanoeffects/trace`. See [Tracing](tracing.md).
+- `extendBus(bus, Base)` from `nanoeffects/oop` gives a class the methods of a bus, with the subscriptions of each instance ended by `dispose()`. It reads the bus as it is, so use the plugins first. See [Use the bus from a class](oop.md).
 - `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable. See [Observable](observable.md).
 
+## Write your own plugin
+
+A plugin is a function of the bus that returns what you want back. The bus keeps no list of plugins, so a plugin that was used cannot be taken out by the bus; it returns its own `stop` or `disconnect` when it needs one.
+
+```js
+// count-plugin.js
+// your own plugin: a function of the bus that returns what you want back
+export const countPlugin = (bus) => {
+  let count = 0;
+  const unbind = bus.on("*", () => {
+    count += 1;
+  });
+  return { count: () => count, stop: unbind };
+};
+```
+
+```js
+import { createBus } from "nanoeffects";
+import { countPlugin } from "./count-plugin";
+
+const bus = createBus();
+// use — calls countPlugin(bus) and returns its result
+const counter = bus.use(countPlugin);
+
+bus.emit("greet", "Ada");
+console.log(counter.count()); // 1
+counter.stop();
+```
+
 ---
 Source: docs/policies.md
 
@@ -639,18 +1008,408 @@ Every call returns a promise with the result of its own run. An error rejects on
 - 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 a policy without a bus
 
-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.
+**Problem.** You want a debounced input handler or a "latest request wins" fetch, but your code has no bus. A policy needs a context on every call, so `debounce(300, search)("re")` does not work on its own.
 
-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)).
+**When.** One component or module needs a policy and nothing else from the library. If you already have a bus, `bus.on(event, policy)` is simpler.
 
-## Wrap a handler with retry and timeout
+`withPolicy` takes the result of any policy and returns a plain function. It needs no bus and no context argument, and it keeps the state of the policy between calls.
 
-`retry`, `timeout`, and `poll` have two forms:
+```js
+import { debounce, withPolicy } from "nanoeffects/policies";
+
+// debounce — waits for 300 ms of quiet, then runs the callback
+const policy = debounce(300, async (query, { signal }) => {
+  await api.search(query, { signal });
+});
+
+// withPolicy — a plain function: no bus, no context argument
+const onChange = withPolicy(policy);
+
+onChange("re");
+onChange("redux"); // only this call runs, 300 ms after it
+
+// cancel — drops a pending call and aborts a running one
+onChange.cancel();
+```
+
+- The callback has the same `(payload, ctx)` shape as for a bus. `ctx.signal`, `ctx.abort` and `ctx.run` work. `ctx.emit` and `ctx.on` do nothing, because there is no bus.
+- Every call returns a promise with the result. A call the policy drops resolves with `undefined`.
+- `cancel()` aborts every call that has not finished. Calls made after it work again.
+- Where `Symbol.dispose` exists, `using onChange = withPolicy(policy)` calls `cancel()` at the end of the scope.
+
+In a React component, use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) instead: it keeps the function between renders.
+
+---
+Source: docs/cancel-stale-requests.md
+
+# Cancel stale requests and fix race conditions
+
+Read this page if an older response can overwrite a newer one: a search box that shows the results of the previous query, a filter that flickers, a form that submits twice. It shows the cause, the fix with `latest`, and how to add a pause, a retry and a timeout. It needs only the bus from the [README](../README.md).
+
+## See the problem
+
+A user types `ab`, then `abc`. Two requests start. If the one for `ab` is slower, it finishes last and its results replace the right ones.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "search" starts its own request, and the slowest one wins.
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+```
+
+Checking a counter by hand (`if (id !== lastId) return`) hides the old result, but the old request still runs. Calling `controller.abort()` by hand works, but you must keep the controller somewhere and abort it before each new call.
+
+## Keep only the latest request
+
+Wrap the handler in `latest`. A new `"search"` aborts the task of the previous one, and an aborted task delivers no result.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal: pass it on so the browser cancels the request, not only drops the result
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+
+bus.on("results", (items) => render(items));
+```
+
+What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. Without it, `latest` still ignores the old result, but the request keeps running.
+
+Result: `emit("search", "ab")` followed by `emit("search", "abc")` shows only the results for `abc`, and the request for `ab` is cancelled.
+
+## Wait for a pause in typing
+
+Add `debounce` outside `latest`. The search starts after 300 ms without a new keystroke.
+
+```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));
+```
+
+## Retry a failed request and limit its time
+
+Use `retry` and `timeout` around the request. The pause grows with each attempt.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { backoff, retry, timeout } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// timeout: abort one attempt after 5 s
+const searchOnce = timeout(5000, (query, { signal }) => api.search(query, { signal }));
+
+// retry: up to 4 attempts, backoff makes the pause longer each time
+const searchWithRetry = retry(searchOnce, {
+  times: 4,
+  delay: backoff({ base: 200, max: 5000, jitter: true }),
+});
+
+// latest: a newer search aborts the whole retry chain
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await ctx.run(searchWithRetry, query); // ctx.run: a child task, aborted with this one
+    ctx.emit("results", items);
+  }),
+);
+```
+
+## Pick another policy for another race
+
+| Situation | Policy |
+| --------- | ------ |
+| Only the newest result matters (search, filter, tab switch) | `latest` |
+| A second click while the first call runs must be ignored (submit, pay) | `leading` |
+| Every call must run, one after another (save, upload) | `queue` |
+| Calls come in bursts and you want one at the end | `debounce` |
+| Calls come in bursts and you want one per period | `throttle` |
+| Each user or item has its own race | add `{ key }`, for example `latest(handler, { key })` |
+
+All policies and their options: [Policies](policies.md). The same step by step in a form: [Build a sign-up form in React](react.md).
+
+---
+Source: docs/debounce-and-abort.md
+
+# Debounce a request and abort the previous one
+
+Read this page if you debounce user input (a search box, an autosave, a resize handler) and you also want the request in flight to stop when a new one starts. `debounce` alone waits for a pause. It does not cancel a request that already started. This page shows the two policies together, the order to put them in, and when to use `throttle` instead.
+
+## Know what each policy does
+
+| Policy | What it does | What it does not do |
+| ------ | ------------ | ------------------- |
+| `debounce(ms, fn)` | runs `fn` after `ms` without a new call | does not cancel a run that already started |
+| `latest(fn)` | aborts the previous run when a new one starts | does not wait for a pause |
+
+Use both for a search box. `debounce` sends fewer requests. `latest` cancels the slow one when the user types again after the pause.
+
+## Combine them
+
+Put `debounce` outside and `latest` inside. The event waits for a pause first. When the run starts, it aborts the previous run.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer run aborts the older request
+const searchLatest = latest(async (query, { signal }) => {
+  // signal: pass it on so the browser cancels the request itself
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run searchLatest after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+
+bus.on("results", (items) => render(items));
+```
+
+What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. `render` shows the items.
+
+Result: typing `a`, `ab`, `abc` within 300 ms sends one request for `abc`. If the user types `abcd` while that request runs, the request for `abc` is aborted and one for `abcd` starts after the pause.
+
+## Run the first call at once
+
+By default `debounce` waits even before the first call. For an input where the first key press should react at once, add `leading: true`. The first call of a burst runs immediately, and the last one runs after the pause.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const showSuggestions = (query) => console.log("suggest", query);
+
+// debounce with leading: the first call runs at once, the last one after 300 ms of quiet
+bus.on("typed", debounce(300, showSuggestions, { leading: true }));
+```
+
+`leading` and `trailing` follow lodash. All combinations: [Policies](policies.md#configure-debounce-and-throttle).
+
+## Use throttle for continuous input
+
+`debounce` never runs while calls keep coming. For a scroll or a drag you want updates during the movement. Use `throttle`: at most one run per period.
+
+```js
+import { createBus } from "nanoeffects";
+import { throttle } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const saveScroll = (position) => localStorage.setItem("scroll", String(position));
+
+// throttle: at most one run per 100 ms while "scrolled" keeps coming
+bus.on("scrolled", throttle(100, saveScroll));
+```
+
+## Debounce without a bus
+
+If the page has no bus, wrap the same pair with `withPolicy`. The result is a plain function that you call from an input handler.
+
+```js
+import { debounce, latest, withPolicy } from "nanoeffects/policies";
+
+// latest: a newer run aborts the older request
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  console.log(items);
+});
+
+// withPolicy: debounce by 300 ms, called as a plain function
+const onTyped = withPolicy(debounce(300, searchLatest));
+
+onTyped("a");
+onTyped("ab"); // only "ab" runs, 300 ms later
+
+// cancel: drop a pending call and abort a running request, for example on page leave
+onTyped.cancel();
+```
+
+In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders), which also cancels on unmount.
+
+## Check these when it does not cancel
+
+- The request did not get `signal`. `latest` then drops the old result but the request goes on.
+- The order is reversed. Write `debounce(300, latest(handler))`, as above, so `debounce` receives the events and `latest` guards the request.
+- Several inputs share one event. Give each its own event name, or use `{ key }`, for example `latest(handler, { key: (input) => input.id })`.
+
+Related: [Cancel stale requests](cancel-stale-requests.md), [Policies](policies.md).
+
+---
+Source: docs/prevent-double-submit.md
+
+# Prevent a double submit
+
+Read this page if a second click on "Pay", "Sign up" or "Save" sends the request twice. It shows how to ignore the second click while the first request runs, how to do it per item, and when to queue the calls instead.
+
+## See the problem
+
+A user clicks twice. Both clicks run the handler, and the server gets two requests.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "submitted" starts its own request.
+bus.on("submitted", async (form) => {
+  const order = await api.pay(form);
+  bus.emit("paid", order);
+});
+```
+
+A `disabled` button helps only until the next render. A flag in a variable (`if (busy) return`) must be reset on every error path and after an abort.
+
+## Ignore clicks while a request runs
+
+Wrap the handler in `leading`. While one run is going, new calls are dropped. When the run ends, the next click works.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// leading: a call is dropped while a previous run is still going
+bus.on(
+  "submitted",
+  leading(async (form, ctx) => {
+    const order = await api.pay(form, { signal: ctx.signal });
+    ctx.emit("paid", order);
+  }),
+);
+```
+
+What to replace: `api.pay` is your own request function.
+
+Result: `emit("submitted", form)` twice in a row sends one request. The second call returns at once and does nothing.
+
+`leading` frees its lock when the task ends or aborts. If the handler throws, the next click works again, with no flag to reset.
+
+## Allow one run per item
+
+A list of rows, each with its own "Delete" button, should not block the whole list. Give each item its own state with `key`.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// leading with key: one running call per row id, other rows are not blocked
+bus.on(
+  "row/deleted",
+  leading(
+    async (row, ctx) => {
+      await api.deleteRow(row.id, { signal: ctx.signal });
+      ctx.emit("row/removed", row.id);
+    },
+    { key: (row) => row.id },
+  ),
+);
+```
+
+## Retry only when the network failed
+
+A retry after a failed payment can charge twice if the server did run the first request. Retry only on errors where the request did not reach the server, and make the server accept an idempotency key.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+import { retry } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// fetch rejects with a TypeError when the network fails; an HTTP error is a plain Error
+const isNetworkError = (error) => error instanceof TypeError;
+
+bus.on(
+  "submitted",
+  leading(async (form, ctx) => {
+    const pay = () => api.pay(form, { signal: ctx.signal });
+    // retry: up to 3 tries, 500 ms apart, only when the network failed
+    const order = await retry(ctx, pay, { times: 3, delay: 500, shouldRetry: isNetworkError });
+    ctx.emit("paid", order);
+  }),
+);
+```
+
+Backoff between tries: [Back off between retries](effects.md#back-off-between-retries).
+
+## Guard a handler when you have no bus
+
+`withPolicy` turns a policy into a plain function, so a click handler needs no bus.
+
+```js
+import { leading, withPolicy } from "nanoeffects/policies";
+
+// leading: ignore new calls while a run is going
+const policy = leading(async (form, { signal }) => {
+  await api.save(form, { signal });
+});
+
+// withPolicy: a plain function to call from onSubmit
+const submit = withPolicy(policy);
+
+submit({ name: "Ada" }); // runs
+submit({ name: "Ada" }); // ignored while the first runs; resolves with undefined
+```
+
+In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders).
+
+## Pick another policy when clicks must not be lost
+
+| You want | Policy |
+| -------- | ------ |
+| Ignore a second click while the first runs (pay, sign up) | `leading` |
+| Run every click, one after another (save a draft, upload files) | `queue` |
+| Keep only the newest click and cancel the older (filters, tabs) | `latest` |
+
+Related: [Policies](policies.md), [Build a sign-up form in React](react.md).
+
+---
+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.
@@ -990,14 +1749,28 @@ Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
 ## Return a value from `emit` with a command
 
+The bus lives in one file and its events in another, so any module can import both without a cycle.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+// createBus — one bus for the app
+export const bus = createBus();
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
 
 // createCommand — emit runs the handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { double } from "./math";
+
 bus.emit(double(21)); // 42
 ```
 
@@ -1006,27 +1779,30 @@ bus.emit(double(21)); // 42
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
 ```js
+// user.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");
+export const userLoaded = createAction("user/loaded");
+export const loadFailed = createAction("user/failed");
 
 // createCommand with a handler — emit returns what the handler returns
-const getUser = createCommand("user/get", (id, { signal }) => {
+export 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");
+export const sendMail = createCommand("mail/send");
 
 // createJob — command that also emits success / fail actions
-const loadUser = createJob("user/load", fetchUser, {
+export const loadUser = createJob("user/load", fetchUser, {
   success: userLoaded,
   fail: "user/failed",
 });
 ```
 
+These are the events of the user domain, in a file of their own (`user.js`). The bus is made in another file (`bus.js` below), and neither imports the other.
+
 ### 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")`.
@@ -1047,22 +1823,22 @@ Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(comm
 **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
+// bus.js
 import { createBus } from "nanoeffects";
-import {
-  bindHandler,
-  commandsPlugin,
-  createCommand,
-} from "nanoeffects/actions";
+import { bindHandler, commandsPlugin } from "nanoeffects/actions";
+import { sendMail } from "./user";
 
-const sendMail = createCommand("mail/send");
-const getUser = createCommand("user/get");
-
-const bus = createBus();
+export const bus = createBus();
 
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(
+export const commands = bus.use(
   commandsPlugin([bindHandler(sendMail, smtpSend)]),
 );
+```
+
+```js
+import { commands } from "./bus";
+import { getUser } from "./user";
 
 // later, e.g. in a test — latest binding wins
 const unbind = commands.handle(getUser, async () => fakeUser);
@@ -1071,19 +1847,88 @@ 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 }`.
+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 `commandsPlugin` binds its list in that registry and returns 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.
+`createJob(type, handler, { pending, success, fail, cancel })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
 
+- When the handler starts, emits `loadUser.pending(payload)`.
 - 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`.
+- When the task is aborted before the handler settles, emits `loadUser.cancel(reason)` instead of `success` or `fail`. After `pending`, exactly one of the three follows.
+- `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
 - `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 "..."`.
+- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). `success` and `fail` are not sent after abort; `cancel` is, once the handler settles.
+- A missing handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent.
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+- The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
+
+## Show a loading state with a job
+
+**Problem.** A spinner needs a flag that is `true` while a request runs. Setting it by hand in the handler (`loading = true`, then `try` / `finally`) breaks when the task is aborted: `ctx.emit` does nothing after an abort, so a flag that is cleared through the bus stays `true`.
+
+**When.** The UI shows a loading state for a request, and the request can be aborted (a page is left, `ctx.abort()` is called). Skip it when nothing shows the state.
+
+A job sends one action when the handler starts and one when it ends, whatever way it ends. A store sets the flag on `pending` and clears it on `success`, `fail` and `cancel`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the app shares
+export const bus = createBus();
+```
+
+```js
+// user.js
+import { createJob } from "nanoeffects/actions";
+
+// createJob — a command that also sends pending, success, fail and cancel
+export const loadUser = createJob("user/load", fetchUser);
+```
+
+```js
+// user-store.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+export const state = { loading: false, user: null };
+
+// pending — the handler starts: show the spinner
+bus.on(loadUser.pending, () => {
+  state.loading = true;
+});
+
+// success — the handler returned a user
+bus.on(loadUser.success, (user) => {
+  state.loading = false;
+  state.user = user;
+});
+
+// fail — the handler threw
+bus.on(loadUser.fail, () => {
+  state.loading = false;
+});
+
+// cancel — the task was aborted: the only way to clear the flag then
+bus.on(loadUser.cancel, () => {
+  state.loading = false;
+});
+```
+
+```js
+// page.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+// emit — runs the job; state.loading is true as soon as it returns
+bus.emit(loadUser("1"));
+```
+
+`cancel` is sent when the handler settles, not at the moment of the abort. A handler that stops on `ctx.signal` (as `fetch` does) settles at once. A handler that ignores the signal sends `cancel` when it finishes, and one that never finishes sends nothing.
+
+**Limit: policies.** A policy such as `latest`, `leading`, `throttle` or `queue` wraps the handler, inside the job. The job does not know what the policy decides, so `pending` is sent for every call. A call that the policy drops, and a run that `latest` replaces, then close with `success(undefined)`, not with `cancel`. A flag set by `pending` is exact for a job without a policy, and for an abort of the task or of its parent. With a policy, count the calls or use the result of `emit`.
 
 ## Mount domains with modules
 
@@ -1094,18 +1939,20 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 `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";
+// user.js
+import { createCommand } from "nanoeffects/actions";
+
+export const getUser = createCommand("user/get");
+export const saveUser = createCommand("user/save", persistUser);
+```
 
-const getUser = createCommand("user/get");
-const saveUser = createCommand("user/save", persistUser);
+```js
+// user-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser, saveUser } from "./user";
 
 // createModule — one domain; unmount undoes everything below
-const userModule = createModule("user", (m) => {
+export const userModule = createModule("user", (m) => {
   m.handle(getUser, fetchUser);
   m.use(saveUser, authModule);
   m.on("login", (user, ctx) => {
@@ -1115,10 +1962,22 @@ const userModule = createModule("user", (m) => {
     /* background work; ends when the module unmounts */
   });
 });
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { userModule } from "./user-module";
+
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([userModule]));
+export const app = bus.use(modulePlugin([userModule]));
+```
+
+```js
+import { app } from "./bus";
+import { getUser } from "./user";
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
 app.commands.handle(getUser, fakeUser); // in a test
@@ -1129,6 +1988,7 @@ app.dispose(); // unmounts every module
 - **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.
+- **The given modules are mounted on the first use** of the app or the bus (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`), so the plugins you use after `modulePlugin` still reach them. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
 - 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.
@@ -1140,17 +2000,29 @@ app.dispose(); // unmounts every module
 A command can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createCommand`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
 // scopePlugin — makes the scope of a command work on this bus
-const bus = createBus().use(scopePlugin());
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
 // the third argument — fields of this command only
-const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
-  api,
-});
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // a test replaces them for one call
 const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
@@ -1181,7 +2053,7 @@ If you do not have a store yet, use `createBus` from the [Guide](guide.md).
   - [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)
+  - [Change the store from any handler](#change-the-store-from-any-handler)
 
 ## Wire Redux Toolkit to a bus
 
@@ -1192,23 +2064,40 @@ Redux’s `dispatch` → reducers updates **state**. It does not give you first-
 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";
+// bus.js
 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");
+export const bus = createBus(); // the bus of your app; it can exist before the store
+```
+
+```js
+// user.js
+import { createAction } from "@reduxjs/toolkit";
 
-const bus = createBus(); // the bus of your app; it can exist before the store
+export const userRequested = createAction("user/requested"); // RTK
+export const userLoaded = createAction("user/loaded");
+```
+
+```js
+// store.js
+import { configureStore } from "@reduxjs/toolkit";
+import { createEffectsMiddleware } from "nanoeffects/redux";
+import { bus } from "./bus";
 
 // createEffectsMiddleware — actions reach the bus after reducers; tasks get ctx.store
 const effects = createEffectsMiddleware(bus);
 
-const store = configureStore({
+export const store = configureStore({
   reducer,
   middleware: (getDefault) => getDefault().concat(effects),
 });
+```
+
+```js
+// user-handlers.js
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { userLoaded, userRequested } from "./user";
 
 // latest — a newer run aborts the older one
 bus.on(
@@ -1259,28 +2148,44 @@ const effects = createEffectsMiddleware(bus);
 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 event changes the store.** The handler reports its result as an event. A listener of the bus gets the store from `ctx` and changes it with a mutation.
 
 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.
+The bus gets the store as context: `contextPlugin({ store })` puts it on every task as `ctx.store` ([Context fields](context.md)). A handler then changes the store with its mutations and never reaches for the store by name. Only `store.js` is different for each store below. It exports a `store` with the same three members:
+
+- `setQuery(query)` and `setResults(items)` are the mutations. The user's input calls the first, the handler calls the second.
+- `onQueryChanged(callback)` tells you about a change of `query`, and returns the function that stops it.
+
+The bus, the events, the handlers and the link from the store to the bus are the same for every store, each in a file of its own: the bus knows no events, and the events know no bus.
 
 ```js
-// search-bus.js
-import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { debounce, latest } from "nanoeffects/policies";
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+import { store } from "./store";
 
-export const bus = createBus().use(emitterPlugin()); // adds bus.emitter; returns the same bus
+export const bus = createBus()
+  .use(emitterPlugin()) // adds bus.emitter
+  .use(contextPlugin({ store })); // ctx.store on every task
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
 // 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);
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 // debounce — wait 300 ms of quiet; latest — abort the search of the previous query
 bus.on(
@@ -1294,141 +2199,199 @@ bus.on(
     }),
   ),
 );
+
+// event → store: the store comes from ctx, and a mutation changes it
+bus.on(searchLoaded, (items, { store }) => {
+  store.setResults(items);
+});
+```
+
+```js
+// connect.js
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+import { store } from "./store";
+
+// store → event: bus.emitter turns the callback into an emit of queryChanged
+export const stopQuery = store.onQueryChanged(bus.emitter(queryChanged));
 ```
 
 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`.
+`action` makes a named mutation of an atom. `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";
+// store.js
+import { action, atom } from "nanostores";
 
 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);
-});
+export const store = {
+  // action — a named mutation of an atom
+  setQuery: action($query, "setQuery", (target, query) => target.set(query)),
+  setResults: action($results, "setResults", (target, items) => target.set(items)),
+  // listen — calls back with the new query on every change
+  onQueryChanged: (callback) => $query.listen(callback),
+};
 ```
 
 ### MobX
 
-`reaction` watches an expression and calls back with its value. Change observables inside `runInAction`.
+`makeAutoObservable` turns the methods of a class into actions, which is where MobX wants changes to happen. `reaction` watches an expression and calls back with its value.
+
+<!-- docs-check: fork -->
 
 ```js
-import { observable, reaction, runInAction } from "mobx";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+// store.js
+import { makeAutoObservable, reaction } from "mobx";
 
-const search = observable({ query: "", results: [] });
+class SearchStore {
+  query = "";
+  results = [];
 
-// store → bus: reaction watches the expression and calls back with its value
-const stopQuery = reaction(() => search.query, emitQueryChanged);
+  constructor() {
+    makeAutoObservable(this); // the methods below become actions
+  }
 
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  runInAction(() => {
-    search.results = items;
-  });
-});
+  setQuery(query) {
+    this.query = query;
+  }
+
+  setResults(items) {
+    this.results = items;
+  }
+
+  // reaction — watches the expression and calls back with its value
+  onQueryChanged(callback) {
+    return reaction(() => this.query, callback);
+  }
+}
+
+export const store = new SearchStore();
 ```
 
 ### Valtio
 
-`subscribeKey` watches one field of a proxy state. Assign to the proxy to change it.
+`subscribeKey` watches one field of a proxy state. A mutation assigns to the proxy.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.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;
-});
+export const store = {
+  setQuery(query) {
+    state.query = query;
+  },
+  setResults(items) {
+    state.results = items;
+  },
+  // subscribeKey — watches one field
+  onQueryChanged: (callback) => subscribeKey(state, "query", callback),
+};
 ```
 
 ### Jotai
 
-`sub` gives no value, so read it yourself. Write with `store.set`.
+`sub` gives no value, so read it yourself. A write-only atom is the mutation, and `set` runs it.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.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);
-});
+const jotai = createStore();
+
+// write-only atoms: the mutations
+const setQueryAtom = atom(null, (_get, set, query) => set(queryAtom, query));
+const setResultsAtom = atom(null, (_get, set, items) => set(resultsAtom, items));
+
+export const store = {
+  setQuery: (query) => jotai.set(setQueryAtom, query),
+  setResults: (items) => jotai.set(setResultsAtom, items),
+  // sub calls back without a value; get reads it
+  onQueryChanged: (callback) =>
+    jotai.sub(queryAtom, () => callback(jotai.get(queryAtom))),
+};
 ```
 
 ### 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.
+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. The mutations are functions in the state.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { create } from "zustand";
 import { subscribeWithSelector } from "zustand/middleware";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
-const useSearchStore = create(
-  subscribeWithSelector(() => ({ query: "", results: [] })),
+const useSearch = create(
+  subscribeWithSelector((set) => ({
+    query: "",
+    results: [],
+    // the mutations are part of the state
+    setQuery: (query) => set({ query }),
+    setResults: (items) => set({ results: items }),
+  })),
 );
 
-// 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 });
-});
+export const store = {
+  setQuery: (query) => useSearch.getState().setQuery(query),
+  setResults: (items) => useSearch.getState().setResults(items),
+  // a selector: called back with state.query only when it changes
+  onQueryChanged: (callback) => useSearch.subscribe((state) => state.query, callback),
+};
 ```
 
 ### 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.
+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. The mutations are the actions of the store.
+
+<!-- docs-check: fork -->
 
 ```js
-import { watch } from "vue";
+// store.js
 import { defineStore } from "pinia";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+import { watch } from "vue";
 
-// defineStore — Pinia: the state of one store
+// defineStore — Pinia: the state and the actions of one store
 const useSearch = defineStore("search", {
   state: () => ({ query: "", results: [] }),
+  actions: {
+    setQuery(query) {
+      this.query = query;
+    },
+    setResults(items) {
+      this.results = items;
+    },
+  },
 });
 
 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;
-});
+export const store = {
+  setQuery: (query) => search.setQuery(query),
+  setResults: (items) => search.setResults(items),
+  // watch — calls back with the new query when search.query changes
+  onQueryChanged: (callback) => watch(() => search.query, callback),
+};
 ```
 
 ### React: sharing a value across components
 
+<!-- docs-check: new -->
+
 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 |
@@ -1441,20 +2404,30 @@ A value of your UI (a query, a filter, a name) often has two jobs. Several compo
 
 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:
+First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export from the bus file:
 
 ```js
-// react-search-bus.js
+// 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`
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
 export const queryChanged = createAction("query/changed");
 export const searchLoaded = createAction("search/loaded");
+```
+
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 // debounce — wait 300 ms of quiet; latest — a newer query aborts the older request
 bus.on(
@@ -1474,7 +2447,8 @@ Then the provider. It holds the state, calls `useEmitter` once, and listens for
 ```jsx
 // SearchProvider.jsx
 import { createContext, useContext, useEffect, useState } from "react";
-import { bus, queryChanged, searchLoaded, useEmitter } from "./react-search-bus";
+import { bus, useEmitter } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 const SearchContext = createContext(null);
 
@@ -1531,6 +2505,8 @@ Two limits to know:
 
 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`:
 
+<!-- docs-check: new -->
+
 ```jsx
 // value-store.js
 import { useSyncExternalStore } from "react";
@@ -1560,19 +2536,36 @@ export function createValue(initial) {
 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";
+```js
+// query.js
+import { createValue } from "./value-store";
+
+export const query = createValue("");
+```
 
-const query = createValue("");
+```js
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+import { query } from "./query";
 
 // emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query
-const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+export const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed");
+export const refreshed = createAction("search/refreshed");
+```
 
-const queryChanged = createAction("query/changed");
-const refreshed = createAction("search/refreshed");
+```js
+// search-handlers.js
+import { bus } from "./bus";
+import { query } from "./query";
+import { queryChanged, refreshed } from "./search";
 
 // store → bus: bus.emitter turns the action into a callback; one place, any number of setters
 const emitQueryChanged = bus.emitter(queryChanged);
@@ -1583,6 +2576,12 @@ bus.on(refreshed, async (_payload, ctx) => {
   const items = await api.search(ctx.query.get(), { signal: ctx.signal });
   console.log(items.length);
 });
+```
+
+```jsx
+// SearchBox.jsx
+import { query } from "./query";
+import { useValue } from "./value-store";
 
 // any number of components read and write the same value
 export function SearchBox() {
@@ -1595,16 +2594,31 @@ export function SearchBox() {
 
 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:
 
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed");
+```
+
 ```jsx
-// search-atom.jsx
+// SearchBox.jsx
 import { atom } from "nanostores";
 import { useStore } from "@nanostores/react";
-import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
-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));
@@ -1619,16 +2633,28 @@ export function SearchBox() {
 
 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";
+<!-- docs-check: new -->
+
+```js
+// bus.js
 import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: created once
+```
+
+```js
+// search.js
 import { createAction } from "nanoeffects/actions";
 
-const bus = createBus(); // the bus: created once
+export const queryChanged = createAction("query/changed");
+export const queryCleared = createAction("query/cleared");
+```
 
-const queryChanged = createAction("query/changed");
-const queryCleared = createAction("query/cleared");
+```jsx
+// Search.jsx
+import { useReducer } from "react";
+import { bus } from "./bus";
+import { queryChanged, queryCleared } from "./search";
 
 function reducer(state, action) {
   if (queryChanged.match(action)) {
@@ -1668,11 +2694,139 @@ The stores above call back only when the value changed, so the emitter does not
 
 ### 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.
+`connect.js` keeps the function that `onQueryChanged` returned (`stopQuery`). Call it yourself, or hand it over: `onAbort(ctx, stopQuery)` inside a task, or `m.signal.addEventListener("abort", stopQuery)` in a module. To stop the other direction, remove the listener of `searchLoaded` with `bus.off(searchLoaded, handler)`, or register it in a module, which removes it on unmount.
+
+### Change the store from any handler
+
+A handler gets the store from `ctx.store` and calls a mutation, whatever it handles: not only the result of a search. 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/query-libraries.md
+
+# Use nanoeffects with React Query and SWR
+
+Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one command that both libraries call.
+
+You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
+
+## Decide who owns what
+
+The libraries and nanoeffects do different jobs, so each keeps its own.
+
+| React Query or SWR | nanoeffects |
+| ------------------ | ----------- |
+| `isLoading`, `data`, `error` | `retry`, `timeout`, `latest` and other policies |
+| the cache, one request for the same key | the abort that reaches the request |
+| refetch on focus, on reconnect, on interval | the handler: the same code for a test, a worker and the UI |
+
+`isLoading` and `data` come from the library, not from `emit`. `await bus.emit(...)` resolves once, with the result, so it cannot report that the request is still running.
+
+## Make the command
+
+A command is the request itself. It lives in files that know nothing about React: the bus, the command with its handler, and the component.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// createBus — the bus the app shares
+// signalPlugin — lets emit take { signal }, the signal of the library
+export const bus = createBus().use(signalPlugin());
+```
+
+The handler tries the request up to three times and gives up after five seconds for each try. `ctx.signal` is the signal of the task: it aborts when the library aborts the request.
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+import { retry, timeout } from "nanoeffects/effects";
+
+// createCommand — a command with a handler: emit returns what the handler returns
+export const getUser = createCommand("user/get", async (id, ctx) => {
+  // one try: the request, with the signal of timeout so it can stop it
+  const load = ({ signal }) => api.getUser(id, { signal });
+  // timeout — fail the try after 5 s
+  const attempt = () => timeout(ctx, 5000, load);
+  // retry — up to 3 tries, 500 ms apart
+  return retry(ctx, attempt, { times: 3, delay: 500 });
+});
+```
+
+## Call it from React Query
+
+<!-- docs-check: continue -->
+
+React Query gives `queryFn` a `signal` and aborts it when the query becomes inactive or out of date. Pass it to `emit`. The task is aborted with it, so `timeout` and `retry` stop, and so does the request.
+
+```jsx
+// Profile.jsx
+import { useQuery } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export function Profile({ id }) {
+  const { isLoading, data, error } = useQuery({
+    queryKey: ["user", id],
+    // emit — runs the command; { signal } ties its task to the signal of React Query
+    queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
+  });
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>{data.name}</p>;
+}
+```
+
+The command rejects when all tries fail, so React Query shows the `error`. React Query counts its own `retry` too: set `retry: false` in `useQuery` when the handler already retries, or the tries multiply.
+
+## Call it from SWR
+
+<!-- docs-check: continue -->
+
+SWR does not pass a signal to the fetcher, so there is nothing to give to `emit`. The command still brings `retry` and `timeout`.
+
+```jsx
+// Profile.jsx
+import useSWR from "swr";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+// the fetcher gets the key (here the id) and returns a promise
+const fetcher = (id) => bus.emit(getUser(id));
+
+export function Profile({ id }) {
+  const { isLoading, data, error } = useSWR(id, fetcher);
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>{data.name}</p>;
+}
+```
+
+## Let the bus know the result
+
+<!-- docs-check: continue -->
+
+A command gives its result only to the caller. If a store or another module must react to a loaded user, the handler can say so:
+
+```js
+// user-events.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — an event with a payload
+export const userLoaded = createAction("user/loaded");
+```
 
-### Give the store to every handler
+Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the command with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job).
 
-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.
+## Know the limits
+
+- **Without the plugin, `{ signal }` is ignored.** The command runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
+- **Only the call forms take it.** `bus.emit(getUser(id), { signal })` works; `bus.emit("user/get", id, { signal })` does not.
+- **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Commands that fetch are async, so this only matters for a sync handler that sets up a callback.
+- **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
+- **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
 
 ---
 Source: docs/react.md
@@ -1695,19 +2849,26 @@ Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one p
 
 ## 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.
+Keep the bus in a file of its own, and the handlers of the form in another. Create the bus 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
+// bus.js
 import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: created once, at the top of the module
+```
+
+The handlers know the bus and the bus knows nothing of them. They register when `registration.js` is imported, once, when the app starts:
+
+```js
+// registration.js
 import { retry } from "nanoeffects/effects";
 import { debounce, latest, leading } from "nanoeffects/policies";
+import { bus } from "./bus";
 
 // 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",
@@ -1745,12 +2906,15 @@ The handlers know nothing about React. A test can emit `username/typed` and read
 
 ## Connect the form
 
+<!-- docs-check: continue -->
+
 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
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./registration"; // registers the handlers; the app does this once, when it starts
 
 export function SignUpForm() {
   const [name, setName] = useState("");
@@ -1813,6 +2977,8 @@ In development, React StrictMode runs the effect twice (subscribe, unsubscribe,
 
 ## Stop running work when the form closes
 
+<!-- docs-check: continue -->
+
 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
@@ -1829,11 +2995,55 @@ const checkName = latest(async (name, ctx) => {
 
 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.
 
+## Keep a debounced handler between renders
+
+**Problem.** A component runs again on every render. A policy made in its body, such as `debounce(300, search)`, is made again each time and loses its timer. A policy made once keeps the callback of the first render, which reads old props and state.
+
+**When.** A handler in a component needs a policy, and you do not need a bus: a search box, an autosave, a submit that must not fire twice.
+
+`usePolicy(callback, make, deps)` keeps one function between renders. It calls the `callback` of the latest render, so an inline callback sees fresh state. It cancels pending calls when the component unmounts.
+
+```jsx
+import { useState } from "react";
+import { debounce } from "nanoeffects/policies";
+import { usePolicy } from "nanoeffects/react";
+
+export const Search = ({ wait }) => {
+  const [items, setItems] = useState([]);
+
+  // usePolicy — a stable function; the first argument is the latest render's callback
+  const onChange = usePolicy(
+    async (query, { signal }) => {
+      const found = await api.search(query, { signal });
+      setItems(found);
+    },
+    // the second argument builds the policy once; task runs the callback above
+    (task) => debounce(wait, task),
+    // deps — list what the second argument reads; a new wait makes a new policy
+    [wait],
+  );
+
+  return (
+    <div>
+      <input onChange={(event) => onChange(event.target.value)} />
+      <p>{items.length} found</p>
+    </div>
+  );
+};
+```
+
+- `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
+- A pending call is cancelled on unmount and when `deps` change.
+- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+
 ## Where to go next
 
 - The policies behind this form: [Policies](policies.md).
+- A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 - `retry`, `timeout` and the other effects: [Effects](effects.md).
 - A state library instead of `useState`: [Stores](stores.md).
+- React Query or SWR instead of your own state: [Use nanoeffects with React Query and SWR](query-libraries.md).
 
 ---
 Source: docs/context.md
@@ -1913,27 +3123,29 @@ You give a scope to the thing that uses it. A call can replace it. Nothing else
 Scopes are a plugin, so a bus that does not use them pays nothing.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
 import { scopePlugin } from "nanoeffects/scope";
 
 // scopePlugin — makes the scopes below work on this bus; returns the same bus
-const bus = createBus().use(scopePlugin());
+export const bus = createBus().use(scopePlugin());
 ```
 
+The bus is in one file and the commands and actions in files named after their domain, so the next example imports `bus` from here. Each section after it keeps its own `bus.js` and domain file, as if it were an app of its own.
+
 - Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
-- Use it **after** `effectsPlugin` (an effect it adds later would be assigned over an effect of a scope with the same name) and **before** `modulePlugin` (it mounts the modules when it is used). `contextPlugin` and `createBus({ context })` can come in any order: a scope wins over them.
+- Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
 
 ## Give a command its own fields
 
+<!-- docs-check: continue -->
+
 ```js
-import { createBus } from "nanoeffects";
+// user.js
 import { createCommand } from "nanoeffects/actions";
-import { scopePlugin } from "nanoeffects/scope";
-
-const bus = createBus().use(scopePlugin());
 
 // createCommand — third argument is the scope of this command
-const getUser = createCommand(
+export const getUser = createCommand(
   "user/get",
   (id, { api, cache }) => {
     // api and cache are on ctx for this command only
@@ -1941,6 +3153,11 @@ const getUser = createCommand(
   },
   { api, cache: new Map() },
 );
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 const user = await bus.emit(getUser("1")); // the handler has api and cache
 ```
@@ -1952,18 +3169,15 @@ The listeners of `"user/get"` get the same fields when the command is emitted, b
 An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
 
 ```js
-import { createBus } from "nanoeffects";
+// feed.js
 import { createCommand } from "nanoeffects/actions";
 import { delay, race } from "nanoeffects/effects";
-import { scopePlugin } from "nanoeffects/scope";
-
-const bus = createBus().use(scopePlugin());
 
 // your own effect: first parameter is the task (only its signal is used)
 const fetchJson = (ctx, url) =>
   fetch(url, { signal: ctx.signal }).then((response) => response.json());
 
-const loadFeed = createCommand(
+export const loadFeed = createCommand(
   "feed/load",
   (url, { fetchJson, race, delay }) =>
     // race, delay, fetchJson — bound to this task: no ctx argument
@@ -1974,6 +3188,19 @@ const loadFeed = createCommand(
   // $effects — built-in and your own functions share one object
   { $effects: { fetchJson, race, delay } },
 );
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+import { bus } from "./bus";
+import { loadFeed } from "./feed";
 
 const result = await bus.emit(loadFeed("/feed"));
 ```
@@ -1987,14 +3214,27 @@ const result = await bus.emit(loadFeed("/feed"));
 The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
-const bus = createBus().use(scopePlugin());
-const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
-  api,
-});
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // the real api for this call
 await bus.emit(getUser("1"));
@@ -2014,23 +3254,30 @@ Rules for the second argument:
 ## Give an action, a job or a module its own fields
 
 ```js
-import { createAction, createJob, createModule } from "nanoeffects/actions";
+// user.js
+import { createAction, createJob } from "nanoeffects/actions";
 
 // createAction — the listeners of this action's calls get the fields
-const userLoaded = createAction("user/loaded", { store });
+export const userLoaded = createAction("user/loaded", { store });
 
 // createJob — the scope is the fourth argument, after the outcomes;
 // the handler and the listeners of the outcome get its fields
-const loadUser = createJob(
+export const loadUser = createJob(
   "user/load",
   fetchUser,
   { success: userLoaded, fail: "user/failed" },
   { logger },
 );
+```
+
+```js
+// audit-module.js
+import { createModule } from "nanoeffects/actions";
+import { userLoaded } from "./user";
 
 // createModule — third argument; everything the module owns gets the fields:
 // m.on listeners, m.handle handlers, m.spawn tasks
-const auditModule = createModule(
+export const auditModule = createModule(
   "audit",
   (m) => {
     m.on(userLoaded, (user, { logger }) => logger.info(user.id));
@@ -2039,95 +3286,386 @@ const auditModule = createModule(
 );
 ```
 
-If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
+If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
+
+A module scope does not leak: a listener registered outside the module does not see it.
+
+## Which value wins
+
+When several places set the same field, the strongest one wins:
+
+| Strength | Where it is set |
+| -------- | --------------- |
+| 1 (strongest) | the second argument of `emit` |
+| 2 | the scope of the action, command or job |
+| 3 | the scope of the module that owns the handler |
+| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
+
+The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+
+## Keep a generic effect generic
+
+In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+
+`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
+
+```js
+// pick.js
+import { createCommand } from "nanoeffects/actions";
+import { effect } from "nanoeffects/scope";
+
+// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
+const first = effect((ctx, items) => items[0]);
+
+export const pick = createCommand("pick", (items, { first }) => first(items), {
+  first, // a plain key of the scope, not an entry of `$effects`
+});
+```
+
+Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
+
+`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
+
+```ts
+import { createCommand } from "nanoeffects/actions";
+import type { Effect } from "nanoeffects/effects";
+
+// First — checker-only: how a handler calls the effect (no ctx)
+type First = <T>(items: T[]) => T;
+
+// Effect<First> — the function takes the task first and is typed as First once bound
+const first: Effect<First> = (ctx, items) => items[0];
+
+const pick = createCommand(
+  "pick",
+  (id: string, { first }) => first([id]), // string
+  { $effects: { first } },
+);
+```
+
+`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
+
+## Type the fields (optional)
+
+A handler of a command, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+
+```ts
+import { createCommand } from "nanoeffects/actions";
+
+type User = { id: string; name: string };
+
+const getUser = createCommand(
+  "user/get",
+  async (id: string, ctx) => {
+    ctx.cache; // Map<string, User>, from the scope below
+    return ctx.cache.get(id);
+  },
+  { cache: new Map<string, User>() },
+);
+```
+
+- A field of a scope replaces a field of the same name from the bus in the type too.
+- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
+- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
+- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
+
+## Limits
+
+- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
+- The fields of the bus are not in the handler of a command made with `createCommand(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
+- The string form of `emit` takes no scope.
+- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
+- A scope on a command, action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.
+
+---
+Source: docs/oop.md
+
+# Use the bus from a class
+
+Use this page when **your domain logic lives in classes**: a service, a store or a controller that needs the bus inside its methods. A class made with `extendBus` has `on`, `emit` and the other methods of the bus, and remembers what each instance subscribed to, so `dispose()` ends it all.
+
+If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
+
+## The problem without it
+
+A class that listens to the bus keeps a reference to it, and keeps every unsubscribe function in a list to call when the object goes away. Forget one and the old object keeps handling events. `extendBus` does both for you.
+
+## Give a class the methods of a bus
+
+`extendBus(bus, Base)` returns a subclass of `Base`. Its instances have the methods of the bus, and the arguments of `new` go to the constructor of `Base`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus that the services of the app share
+export const bus = createBus();
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the events of the search domain
+export const queryChanged = createAction("search/query-changed");
+export const resultsLoaded = createAction("search/results-loaded");
+```
+
+```js
+// search-service.js
+import { extendBus } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged, resultsLoaded } from "./search";
+
+class SearchServiceBase {
+  constructor(api) {
+    this.api = api;
+    // this.on — a subscription of this instance; dispose() removes it
+    this.on(queryChanged, (query, ctx) => this.search(query, ctx)); // an arrow keeps this
+  }
+
+  async search(query, { signal, emit }) {
+    const items = await this.api.search(query, { signal });
+    emit(resultsLoaded(items));
+  }
+}
+
+// extendBus — a subclass whose instances have on, once, off, emit and dispose
+export const SearchService = extendBus(bus, SearchServiceBase);
+```
+
+```js
+import { queryChanged } from "./search";
+import { SearchService } from "./search-service";
+
+const service = new SearchService(api); // the arguments go to SearchServiceBase
+service.emit(queryChanged("nano")); // the same bus as bus.emit
+service.dispose(); // its subscriptions are gone
+```
+
+What you get:
+
+- The class keeps the name of `Base`, and its instances are instances of `Base`.
+- `on`, `once`, `off` and `emit` act on the bus. They can be destructured: `const { emit } = service`.
+- The other methods of the bus, such as `emitter` from [`emitterPlugin`](plugins.md), are there too. Only the plugins used **before** `extendBus` count: the names are taken when it runs.
+- `bus` is the bus, and `Class.bus` is the same one.
+- `this.on` works in the constructor of `Base`. The methods exist on the prototype of the subclass, which is the prototype of the instance already.
+
+## Let the class make its bus
+
+Leave the bus out and the class gets its own, shared by all of its instances.
+
+```js
+// notifier.js
+import { extendBus } from "nanoeffects/oop";
+
+class NotifierBase {}
+
+// extendBus without a bus — a new bus for this class; two classes have two buses
+export const Notifier = extendBus(NotifierBase);
+
+const first = new Notifier();
+const second = new Notifier();
+second.on("notified", (message) => console.log(message));
+first.emit("notified", "hello"); // the instances share Notifier.bus
+```
+
+Pass a bus when you need plugins (`contextPlugin`, `scopePlugin`) or when several classes talk to each other.
+
+## End the subscriptions with `dispose`
+
+`dispose()` removes every subscription made through `this.on` and `this.once` of that instance, and nothing else. It is safe to call twice. `instance[Symbol.dispose]()` does the same, so `using service = new SearchService(api)` works where the runtime supports it.
+
+```js
+// dispose.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+const bus = createBus();
+const Service = extendBus(bus, class {});
+
+const service = new Service();
+const stop = service.on("ping", () => console.log("service heard it"));
+bus.on("ping", () => console.log("the bus heard it")); // not a subscription of the service
+
+service.dispose();
+bus.emit("ping"); // only "the bus heard it"
+stop(); // the function on returned still works, and does nothing now
+```
+
+A subscription that you removed yourself (the function `on` returned, `this.off`, or a `once` that fired) is forgotten, so the instance holds nothing for it.
+
+## Keep a method of your own
+
+The class wins any clash of names. If `Base` has `emit`, `dispose`, `on` or `bus`, yours stays and the bus method is not added. A `Base` with its own `dispose` would never end the subscriptions, so call `disposeBus(this)` from there.
+
+```js
+// cache.js
+import { createBus } from "nanoeffects";
+import { disposeBus, extendBus } from "nanoeffects/oop";
+
+const bus = createBus();
+
+class CacheBase {
+  dispose() {
+    this.items.clear(); // your own cleanup
+    disposeBus(this); // disposeBus — ends the subscriptions of this instance
+  }
+
+  items = new Map();
+}
+
+export const Cache = extendBus(bus, CacheBase);
+```
+
+`disposeBus` does nothing for a value that is not an instance of such a class.
+
+## Subscribe a method with `@On` and `@Once`
+
+A decorator turns a method into a handler of an event for each instance, with `this` bound. You write no `this.on` in the constructor, and `dispose()` ends the subscription too.
+
+The bus and the events are the same as above, in TypeScript:
+
+```ts
+// bus.ts
+import { createBus } from "nanoeffects";
+
+export const bus = createBus();
+```
+
+```ts
+// search.ts
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction<string>("search/query-changed");
+export const resultsLoaded = createAction<string[]>("search/results-loaded");
+```
+
+```ts
+// search-service.ts
+import { latest } from "nanoeffects/policies";
+import { extendBus, On, Once } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged, resultsLoaded } from "./search";
+
+class SearchServiceBase {
+  // On — this method handles queryChanged for each instance, this is the instance;
+  // latest — each new query aborts the one before it
+  @On(queryChanged, latest)
+  async search(query: string, { signal, emit }: { signal: AbortSignal; emit: (event: unknown) => void }) {
+    const items = await api.search(query, { signal });
+    emit(resultsLoaded(items));
+  }
 
-A module scope does not leak: a listener registered outside the module does not see it.
+  // Once — runs for the first event only
+  @Once("search/ready")
+  ready() {
+    console.log("first ready");
+  }
+}
 
-## Which value wins
+export const SearchService = extendBus(bus, SearchServiceBase);
+```
 
-When several places set the same field, the strongest one wins:
+Things to know:
 
-| Strength | Where it is set |
-| -------- | --------------- |
-| 1 (strongest) | the second argument of `emit` |
-| 2 | the scope of the action, command or job |
-| 3 | the scope of the module that owns the handler |
-| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
+- The event is a name, an action creator or a command, as for `bus.on`. For a creator or a command the payload of the method is checked against it.
+- The second argument, `wrap`, takes the bound handler and returns the one to subscribe: `latest`, or `(handler) => debounce(300, handler)`. A policy needs it: `latest(this.search)` wraps the function without `this`, and the bound handler is what `wrap` gets.
+- The subscriptions are made right after the constructor of `Base`. An event that is emitted inside that constructor does not reach them.
+- A subclass inherits them. A method that a subclass overrides is subscribed only if the override is decorated.
+- On a class that `extendBus` did not make, a decorator does nothing.
+- Both the decorators of the language and `experimentalDecorators` work. Your compiler has to support the one you use: TypeScript 5 or newer for the first, and the `experimentalDecorators` option for the second.
 
-The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+## Decorate the class with `@WithBus`
 
-## Keep a generic effect generic
+`@WithBus(bus)` does what `extendBus(bus, Base)` does, as a class decorator. `@WithBus()` makes a bus for the class.
 
-In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+<!-- docs-check: continue -->
 
-`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
+```ts
+// search-service.ts
+import { type BusMethods, On, WithBus } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+// TypeScript does not change the type of a decorated class, so say what it gets;
+// checker only: at run time WithBus already adds the methods
+interface SearchService extends BusMethods<typeof bus> {}
+
+// WithBus — replaces the class by extendBus(bus, SearchService)
+@WithBus(bus)
+class SearchService {
+  @On(queryChanged)
+  search(query: string) {
+    console.log(query);
+  }
+}
 
-```js
-import { createCommand } from "nanoeffects/actions";
-import { effect } from "nanoeffects/scope";
+export { SearchService };
+```
 
-// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
-const first = effect((ctx, items) => items[0]);
+Prefer `extendBus(bus, Base)` when you can: its types come from the call and need no `interface`.
 
-const pick = createCommand("pick", (items, { first }) => first(items), {
-  first, // a plain key of the scope, not an entry of `$effects`
-});
-```
+## Pass a method by hand
 
-Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
+A handler given to `this.on` is called as the bus calls it, with no `this`. A method passed bare loses `this`, as in plain JavaScript:
 
-`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
+```js
+// handlers.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
 
-```ts
-import { createCommand } from "nanoeffects/actions";
-import type { Effect } from "nanoeffects/effects";
+class BaseWithHandler {
+  name = "handler";
 
-// First — checker-only: how a handler calls the effect (no ctx)
-type First = <T>(items: T[]) => T;
+  handle() {
+    console.log(this?.name);
+  }
 
-// Effect<First> — the function takes the task first and is typed as First once bound
-const first: Effect<First> = (ctx, items) => items[0];
+  listen() {
+    this.on("ping", this.handle); // this is lost: prints undefined
+    this.on("ping", () => this.handle()); // an arrow keeps it
+  }
+}
 
-const pick = createCommand(
-  "pick",
-  (id: string, { first }) => first([id]), // string
-  { $effects: { first } },
-);
+export const Listener = extendBus(createBus(), BaseWithHandler);
 ```
 
-`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
+Use an arrow or a decorated method. The library does not bind `this` for you: a policy such as `latest(this.handle)` wraps the function, so binding would work in half of the cases.
 
-## Type the fields (optional)
+## Type the instances (optional)
 
-A handler of a command, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+`extendBus` returns a class that takes the arguments of `Base`, and its instances are `Base` plus `BusMethods<typeof bus>`: the function members of the bus (`on`, `emit`, and those of plugins used before) with `dispose` and `bus`. A member of `Base` with the same name keeps its own type.
 
 ```ts
-import { createCommand } from "nanoeffects/actions";
+// service.ts
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
 
-type User = { id: string; name: string };
+type Events = { "order/placed": { id: string } };
 
-const getUser = createCommand(
-  "user/get",
-  async (id: string, ctx) => {
-    ctx.cache; // Map<string, User>, from the scope below
-    return ctx.cache.get(id);
-  },
-  { cache: new Map<string, User>() },
-);
-```
+// Events — checker only: the payloads of the bus
+const bus = createBus<Events>();
 
-- A field of a scope replaces a field of the same name from the bus in the type too.
-- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
-- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
-- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
+class OrderServiceBase {
+  name: string;
 
-## Limits
+  constructor(name: string) {
+    this.name = name;
+  }
+}
 
-- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
-- The fields of the bus are not in the handler of a command made with `createCommand(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
-- The string form of `emit` takes no scope.
-- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
-- A scope on a command, action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.
+export const OrderService = extendBus(bus, OrderServiceBase);
+
+const service = new OrderService("main"); // the constructor of OrderServiceBase
+service.emit("order/placed", { id: "o1" }); // checked against Events
+```
+
+## What is not done
+
+- `this` is not bound in a handler that you pass by hand (see above).
+- The methods of a plugin used after `extendBus` are not on the class. Use the plugins first, then `extendBus`.
+- One bus for each instance, mixing the methods into an object that exists, and decorators for fields or parameters are not part of this entry.
 
 ---
 Source: docs/typescript.md
@@ -2408,7 +3946,7 @@ nanoeffects has no store. `createStore` can be replaced by any store you like, f
 | 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) |
+| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)) |
 | `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 |
@@ -2461,16 +3999,26 @@ The store (`$items`) is not here. Keep it in Effector and update it from the `fo
 
 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";
+```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { debounce, latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// search-store.js
+import { create } from "zustand";
 
 // create — Zustand: the store replaces $items
-const useSearchStore = create(() => ({ items: [] }));
+export const useSearchStore = create(() => ({ items: [] }));
+```
 
-const bus = createBus(); // the bus: events and handlers
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 // latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
 const search = latest(async (query, { signal }) => {
@@ -2479,6 +4027,12 @@ const search = latest(async (query, { signal }) => {
 });
 
 bus.on("query-changed", debounce(300, search));
+```
+
+```jsx
+// Search.jsx
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 export function Search() {
   const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
@@ -2554,13 +4108,18 @@ formSubmitted.watch((event) => {
 });
 ```
 
-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:
+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 and the handler, each in its own file:
 
 ```js
-// form-bus.js
+// bus.js
 import { createBus } from "nanoeffects";
 
-export const bus = createBus(); // the bus: events and their handlers
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// form-handlers.js
+import { bus } from "./bus";
 
 // bus.on — the job of sendFormFx: runs when the form is submitted
 bus.on("form/submitted", (values) => {
@@ -2573,7 +4132,8 @@ Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`;
 ```jsx
 // App.jsx
 import { useState } from "react";
-import { bus } from "./form-bus"; // the bus of the previous snippet
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./form-handlers"; // registers the handler; the app does this once, when it starts
 
 function Field({ name, type, label, value, onChange }) {
   return (
@@ -2643,16 +4203,27 @@ Retrying a failed network request, and cancelling when the form closes, are in [
 
 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";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const queryChanged = createAction("query/changed"); // a plain action creator
+```
 
-const queryChanged = createAction("query/changed"); // a plain action creator
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
 const found = createEvent(); // Effector: the result comes back as an event
 const $items = createStore([]).on(found, (_, items) => items);
@@ -2673,13 +4244,114 @@ bus.on(
 ## 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.
+- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)). With a policy such as `latest` around the handler the flag is not exact yet, which that section explains. A running task is also visible through [Tracing](tracing.md).
 - **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-mitt.md
+
+# Coming from mitt, nanoevents or EventEmitter
+
+Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, Node's `EventEmitter`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
+
+## When to switch
+
+An emitter calls a function and forgets it. That is enough while handlers are synchronous. Switch when handlers start async work and you hit one of these:
+
+- an older request finishes after a newer one and overwrites its result;
+- you keep `AbortController` objects by hand;
+- you write debounce, throttle or retry around handlers yourself;
+- you cannot tell which event started which request.
+
+If handlers stay synchronous, keep your emitter. nanoeffects costs about 1.4 kB gzip (1.3 kB brotli), close to the small emitters.
+
+## Find the equivalent
+
+| mitt / EventEmitter | nanoeffects |
+| ------------------- | ----------- |
+| `emitter.on("a", handler)` | `bus.on("a", handler)` |
+| `emitter.off("a", handler)` | call the function that `bus.on` returned, or `bus.off("a")` for all handlers of `a` |
+| `emitter.emit("a", payload)` | `bus.emit("a", payload)` |
+| `emitter.once("a", handler)` | `bus.once("a", handler)` |
+| `on("*", (type, payload) => …)` | `bus.on("*", (payload, ctx) => …)`: the event name is `ctx.type` (see the [Guide](guide.md)) |
+| `emitter.all.clear()` | `bus.off()` |
+
+Two differences to know:
+
+- `bus.on` returns the unsubscribe function. You do not need to keep the handler to remove it.
+- The handler gets a second argument, the task context: `(payload, ctx)`. You can ignore it until you need `ctx.signal` or `ctx.emit`.
+
+## Move a handler
+
+Before, with `mitt`:
+
+<!-- docs-check: skip - needs mitt, which the project does not depend on -->
+```js
+import mitt from "mitt";
+
+const emitter = mitt();
+
+emitter.on("search", async (query) => {
+  const items = await api.search(query);
+  emitter.emit("results", items);
+});
+
+emitter.emit("search", "abc");
+```
+
+After, with nanoeffects. The first step changes only the import and the constructor:
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+
+bus.emit("search", "abc");
+```
+
+The second step fixes the race. Wrap the handler in `latest` and pass the signal to the request:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal }); // signal cancels the request
+    bus.emit("results", items);
+  }),
+);
+
+bus.emit("search", "abc");
+```
+
+More cases (pause, retry, timeout): [Cancel stale requests](cancel-stale-requests.md).
+
+## Check the differences
+
+| Topic | Emitter | nanoeffects |
+| ----- | ------- | ----------- |
+| Handler order | order of subscription | order of subscription |
+| Error in a handler | depends on the library | the first error stops the rest and is thrown from `emit`; set `onError` to isolate handlers ([Errors](errors.md)) |
+| Async handler rejects | usually an unhandled rejection | not handled without `onError`; set `onError` to catch it |
+| Event without a listener | ignored | ignored; set `onUnhandled` to be told |
+| Types | event map in a type parameter | event map in a type parameter ([TypeScript](typescript.md)) |
+
+The exact rules of `emit`, abort and ordering: [Semantics](semantics.md).
+
 ---
 Source: docs/migrating-from-rxjs.md
 
@@ -2775,16 +4447,27 @@ Keep RxJS where a stream is how you think, and let events cross to the bus in ei
 
 **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";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// filters.js
+import { createAction } from "nanoeffects/actions";
 
-const filtersChanged = createAction("filters/changed"); // a plain action creator
+export const filtersChanged = createAction("filters/changed"); // a plain action creator
+```
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { combineLatest } from "rxjs";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { filtersChanged } from "./filters";
 
 // RxJS: combine two streams into one value; nanoeffects does not do that
 const subscription = combineLatest([query$, category$]).subscribe(
@@ -2965,28 +4648,142 @@ 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.
+Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
 `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.
 
+## Turn an event into a stream
+
+Problem: a search box emits `typed` on every key. You want to wait for a pause and skip repeats with operators you already know.
+
 <!-- 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 { createBus } from "nanoeffects";
 import { createObserve } from "nanoeffects/observable";
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged } from "rxjs/operators";
+
+const bus = createBus(); // the bus: events and handlers
+const observe = createObserve(bus); // observe(event) gives an Observable per event name
 
-const observe = createObserve(bus); // Observable per event name
+const typed$ = from(observe("typed")); // RxJS wraps it with from()
 
-from(observe("typed"))
-  .pipe(debounceTime(300), distinctUntilChanged(), switchMap(searchRequest))
-  .subscribe((items) => bus.emit("results", items));
+const subscription = typed$
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query)); // back into the bus
 ```
 
 - `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.
+- Types follow the event map: `observe("typed")` is an `Observable<string>` when `typed` carries a string.
+
+## Send a stream into the bus
+
+Problem: `.subscribe((value) => bus.emit(action(value)))` repeats the bus and the action in every subscription. `bus.emitter(action)` from `emitterPlugin` returns that callback, so it is the argument of `subscribe`. It works with any source that takes a `next` function: an RxJS stream, a store callback, a DOM listener.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("search/queryChanged"); // a plain action creator
+```
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map } from "rxjs/operators";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+const input = document.querySelector("#search"); // the search box
+
+const subscription = fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+  )
+  .subscribe(bus.emitter(queryChanged)); // calls bus.emit(queryChanged(value))
+
+bus.on(queryChanged, (query) => console.log("search for", query));
+```
+
+The Observable can come from anywhere, not only from `createObserve`. `subscription.unsubscribe()` stops it; the bus does not know about it. Pass the callback to `subscribe` as it is, and do not call `bus.emitter(...)` inside the operators on every value.
+
+## Do the work in a handler, not in `switchMap`
+
+An Observable is good for shaping values. A request is better in a handler with a policy, because the handler has a `signal` and the trace shows it. Split it: RxJS ends at the value, the bus starts the work.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { latest } from "nanoeffects/policies";
+
+// RxJS: shape the values (debounce, skip repeats), then hand them to the bus
+from(observe("typed"))
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query));
+
+// nanoeffects: one cancellable request; a newer "search" aborts the old one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+`switchMap` drops the old inner stream. `latest` aborts the old task through `signal`, so a `fetch` that got the signal really stops.
+
+## Convert back to a stream or a promise
+
+| You need | Write |
+| -------- | ----- |
+| A stream of events, with operators | `from(observe("event"))` |
+| The next event as a promise | `firstValueFrom(from(observe("event")))`; inside a task `take(ctx, "event")` does the same and respects abort |
+| The events of a bus as an RxJS `Observable` class (for `instanceof` or `pipe` as a method) | `new Observable((subscriber) => observe("event").subscribe(subscriber))` |
+| A task's abort as a stream | `fromEvent(ctx.signal, "abort")`, for `takeUntil` |
+| The latest value to new subscribers | `from(observe("event")).pipe(shareReplay(1))`; the Observable replays nothing by itself |
+
+Events that fired before `subscribe` are lost: the Observable is hot, like `bus.on`. Add `startWith(initial)` or `shareReplay` when a late subscriber needs a value.
+
+## End the subscription
+
+A subscription from `observe` is not tied to a task. Nothing ends it for you. Pick one:
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { fromEvent, from } from "rxjs";
+import { takeUntil } from "rxjs/operators";
+import { onAbort } from "nanoeffects/effects";
+
+bus.on("screen-opened", (_, ctx) => {
+  // takeUntil: stop the stream when the task aborts
+  from(observe("typed"))
+    .pipe(takeUntil(fromEvent(ctx.signal, "abort")))
+    .subscribe((query) => bus.emit("search", query));
+
+  // or: onAbort calls unsubscribe for you
+  const subscription = observe("scrolled").subscribe(updatePosition);
+  onAbort(ctx, subscription.unsubscribe);
+});
+```
+
+Outside a task, call `subscription.unsubscribe()` yourself when the screen goes away, or use the signal of a module.
+
+## Know the limits
+
+- The stream never completes and never fails: events are the only thing that arrives. An error thrown by your subscriber is yours; the bus handles it only if `onError` is set ([Errors](errors.md)).
+- `observe` reads the bus when you call `subscribe`, not when you create it. Create it once, call it as often as needed.
+- Operators that keep state (`scan`, `buffer`, `window`) live in RxJS. The bus keeps no values. For the full split of work see [Use nanoeffects next to RxJS](migrating-from-rxjs.md).
 
 ---
 Source: docs/hmr.md
@@ -3014,7 +4811,7 @@ A `bus.on` outside a module returns the function that unsubscribes: hand it to t
 
 ## Report leaks with `devPlugin`
 
-`bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
+`bus.use(devPlugin())` reports what is easy to miss while developing:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -3022,13 +4819,14 @@ import { modulePlugin } from "nanoeffects/actions";
 import { devPlugin } from "nanoeffects/dev";
 
 const bus = createBus();
-const app = bus.use(modulePlugin([userModule]));
+bus.use(modulePlugin([userModule]));
 // devPlugin — warn on piled-up listeners; log module mount/replace/unmount
-bus.use(devPlugin({ app }));
+// (it finds the app of modulePlugin on the bus, in either order of the two)
+bus.use(devPlugin());
 ```
 
 - **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.
+- **Modules.** For the app of `modulePlugin` (or the `app` option) 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.
 
@@ -3036,6 +4834,6 @@ It changes no behavior: it wraps `bus.on`, `app.mount`, and `app.unmount` and ad
 
 ### 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.
+`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())` 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.