nanoeffects 0.28.0 → 0.29.0

package/llms-full.txt

@@ -10,7 +10,7 @@ Rules that generated code often gets wrong:
 - 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` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
-- `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
+- `bus.emit(action(payload))` runs the action's handler and returns its result. Plain events return nothing.
 
 ---
 Source: docs/guide.md
@@ -28,6 +28,23 @@ Climb one step at a time: small bus → policies → effects → handlers and mo
 
 Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 
+## On this page
+
+- [1. Create a bus](#1-create-a-bus)
+  - [Listen to every event](#listen-to-every-event)
+  - [Pick events with a function](#pick-events-with-a-function)
+- [2. Use the handler context](#2-use-the-handler-context)
+- [3. Abort the previous run with `latest`](#3-abort-the-previous-run-with-latest)
+- [4. Pick another policy when overlap differs](#4-pick-another-policy-when-overlap-differs)
+- [5. Add retry and timeout](#5-add-retry-and-timeout)
+- [6. Run work in parallel or wait for an event](#6-run-work-in-parallel-or-wait-for-an-event)
+- [7. Name events three ways](#7-name-events-three-ways)
+- [8. Bind a handler to an action later](#8-bind-a-handler-to-an-action-later)
+- [9. Mount a domain as a module](#9-mount-a-domain-as-a-module)
+- [10. Add types when you want checking (optional)](#10-add-types-when-you-want-checking-optional)
+- [11. Isolate errors and warn on typos](#11-isolate-errors-and-warn-on-typos)
+- [Where next](#where-next)
+
 ## 1. Create a bus
 
 `on` subscribes. `emit` calls the subscribers. `on` returns the unsubscribe function.
@@ -289,10 +306,11 @@ import { all, delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 // all — run together; one failure cancels the rest
+// child — the context of that starter: it has the `signal`, so the request stops with the group
 bus.on("search", async (id, ctx) => {
   const { user, posts } = await all(ctx, {
-    user: ({ signal }) => api.user(id, { signal }),
-    posts: ({ signal }) => api.posts(id, { signal }),
+    user: (child) => api.user(id, child),
+    posts: (child) => api.posts(id, child),
   });
   ctx.emit("loaded", { user, posts });
 });
@@ -696,24 +714,33 @@ Source: docs/package.md
 
 Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
 
+## Start with these three
+
 | Import | What is in it |
 | ------ | ------------- |
 | `nanoeffects` | `createBus`, the types |
 | `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
-| `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` |
-| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
-| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value |
-| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` |
-| `nanoeffects/oop` | `Emitter`, `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 action, job, module or `emit` (the types `Scope`, `Effect`) |
-| `nanoeffects/redux` | `createEffectsMiddleware` |
-| `nanoeffects/observable` | `createObserve`, `Subject` |
-| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
-| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) |
-| `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) |
-| `nanoeffects/dev` | `devPlugin` (no-op in production) |
-| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |
+
+## Add the rest when you need it
+
+Each row is optional. The "when" column says what need brings you to it.
+
+| Import | What is in it | When |
+| ------ | ------------- | ---- |
+| `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` | `emit` must return a result, or domain logic leaves the UI |
+| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events | `on` must take a function that picks events |
+| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value | a store or client must be on every task |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` | an outside `AbortSignal` (request, React Query) must stop tasks |
+| `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` | you write classes, not functions |
+| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) | one action or module needs its own fields |
+| `nanoeffects/redux` | `createEffectsMiddleware` | you already use Redux |
+| `nanoeffects/observable` | `createObserve`, `Subject` | you need an Observable (RxJS) |
+| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) | React components |
+| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) | Svelte components |
+| `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) | Vue components |
+| `nanoeffects/dev` | `devPlugin` (no-op in production) | you look for leaks in development |
+| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) | you want to see what ran and why |
 
 The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists all of them, what each returns, and the order to use them in.
 
@@ -804,8 +831,8 @@ import { race, retry } from "nanoeffects/effects";
 const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
-  // with ctx: you pass the context, the function gets the signal
-  const user = await retry(ctx, ({ signal }) => fetchUser(id, { signal }), { times: 3 });
+  // with ctx: you pass the context, and the function takes the signal from it
+  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 3 });
 
   // as a starter: a group (race, all, allSettled, timeout) calls it with its child
   const result = await race(ctx, {
@@ -828,12 +855,52 @@ Source: docs/plugins.md
 
 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.
 
+## On this page
+
+- [Use a plugin](#use-a-plugin)
+- [Pick a plugin by task](#pick-a-plugin-by-task)
+- [Main plugins](#main-plugins)
+  - [Put a store or a client on every handler: `contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin)
+  - [Use `race` and `delay` without `ctx`: `effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin)
+  - [Bind or replace a handler: `actionsPlugin`](#bind-or-replace-a-handler-actionsplugin)
+  - [Mount a domain as one unit: `modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin)
+- [Extra plugins](#extra-plugins)
+  - [Give one action its own fields: `scopePlugin`](#give-one-action-its-own-fields-scopeplugin)
+  - [Tie an emit or a listener to an outside signal: `signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin)
+  - [Name the origin and the flow of a trace: `tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin)
+  - [Listen to a group of events: `matchPlugin`](#listen-to-a-group-of-events-matchplugin)
+  - [Hand the bus to a state manager: `emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin)
+  - [Tell the bus when a React value changes: `reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin)
+  - [Find leaks while you develop: `devPlugin`](#find-leaks-while-you-develop-devplugin)
+- [Put them together](#put-them-together)
+- [Use them in any order](#use-them-in-any-order)
+- [See what is not a plugin](#see-what-is-not-a-plugin)
+- [Write your own plugin](#write-your-own-plugin)
+
 ## 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. 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 }))`).
 
+## Pick a plugin by task
+
+Find your need in the left column. No row fits: you need no plugin.
+
+| I need | Use |
+| ------ | --- |
+| A store, client or logger on every handler | [`contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin) |
+| `race`, `all` or `delay` without passing `ctx` | [`effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin) |
+| A test that replaces a handler | [`actionsPlugin`](#bind-or-replace-a-handler-actionsplugin) |
+| One domain mounted and unmounted as a unit | [`modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin) |
+| Fields for one action or module only | [`scopePlugin`](#give-one-action-its-own-fields-scopeplugin) |
+| Tasks that stop when a request, socket or query is cancelled | [`signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin) |
+| One listener for a group of events | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) |
+| A callback for a state manager that emits | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) |
+| A React component that sends its value to the bus | [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) |
+| Names in the trace | [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) |
+| Warnings about leaks while you develop | [`devPlugin`](#find-leaks-while-you-develop-devplugin) |
+
 ## Main plugins
 
 These four cover what most apps need: shared dependencies, effects, handlers and modules. Start here.
@@ -859,6 +926,8 @@ const bus = createBus().use(contextPlugin({ store }));
 bus.on("save", (draft, { store }) => store.put(draft));
 ```
 
+A client that must stop with the task, such as an `axios` instance, goes in as `fromSignal((signal) => axios.create({ signal }))` from `nanoeffects/signal`: it is built from the signal of each task, when the task reads it. More in [Build a field from the signal of each task](context.md#build-a-field-from-the-signal-of-each-task).
+
 ### 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).
@@ -874,7 +943,7 @@ const bus = createBus().use(effects);
 
 bus.on("load", async (id, { race, delay }) => {
   const result = await race({
-    data: ({ signal }) => api.get(id, { signal }),
+    data: (child) => api.get(id, child),
     timeout: () => delay(5000),
   });
 });
@@ -911,7 +980,7 @@ const bus = createBus();
 // modulePlugin — mounts userModule at the end of this block, or at the first use if that is earlier, and returns the app
 const app = bus.use(modulePlugin([userModule]));
 
-app.unmount(userModule); // its listeners, bound commands and tasks are gone
+app.unmount(userModule); // its listeners, bound actions and tasks are gone
 ```
 
 ## Extra plugins
@@ -921,7 +990,7 @@ 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-action-its-own-fields-scopeplugin) | Its own fields for one 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` |
+| [`signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks, and `on(event, handler, { signal })` that removes the listener, 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` |
 | [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) | `traceId` and `traceGroupId` for a trace: the root of an emitter, a flow, a named listener. | `nanoeffects/trace` | The same bus |
@@ -937,10 +1006,10 @@ import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
-// scopePlugin — makes the scope of a command work on this bus
+// scopePlugin — makes the scope of an action work on this bus
 const bus = createBus().use(scopePlugin());
 
-// the last argument: fields of this command only
+// the last argument: fields of this action only
 const getUser = createAction("user/get", (id, { api }) => api.getUser(id), {
   api,
 });
@@ -949,25 +1018,41 @@ 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`
+### Tie an emit or a listener 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).
+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, SWR and RTK Query](query-libraries.md).
 
 ```js
 import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { signalPlugin } from "nanoeffects/signal";
 
-// signalPlugin — emit takes { signal } for a command, a job or an action
+// signalPlugin — emit takes { signal } for an action, a job or an action
 const bus = createBus().use(signalPlugin());
 
 const getUser = createAction("user/get", (id, { signal }) => api.getUser(id, { signal }));
 
 const controller = new AbortController();
-bus.emit(getUser("1"), { signal: controller.signal }); // runs the command
+bus.emit(getUser("1"), { signal: controller.signal }); // runs the action
 controller.abort(); // ctx.signal of the handler aborts with it
 ```
 
+The same signal can end a listener. `on` and `once` take `{ signal }` as their options, as `addEventListener` does, so code that has a signal keeps no `unbind` function. The listener is removed when the signal aborts; a handler that already runs is not aborted. A signal that is aborted already adds no listener.
+
+```js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — on and once take { signal } in their options
+const bus = createBus().use(signalPlugin());
+
+const controller = new AbortController();
+bus.on("saved", (draft) => console.log(draft), { signal: controller.signal }); // listens until the abort
+controller.abort(); // the listener is gone: bus.get("saved") is empty
+```
+
+Without the plugin the `signal` option is ignored and the listener stays. `off(event, handler)` removes a listener but does not end its link to the signal; call the function that `on` returned for that.
+
 ### Name the origin and the flow of a trace: `tracePlugin`
 
 With a tracer on the bus, the plugin lets a trace say which subscription began a chain (`traceId` of `useEmitter` and `bus.emitter`), follow one flow by a `traceGroupId`, and show which listener ran (`bus.on(event, handler, { traceId })`). Without the plugin the options are ignored. More in [Tracing](tracing.md#show-which-subscription-began-a-chain).
@@ -1080,7 +1165,7 @@ import { scopePlugin } from "nanoeffects/scope";
 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(scopePlugin()) // scopes for actions, jobs, modules and emit
   .use(matchPlugin()) // bus.on takes a function that picks the events
   .use(emitterPlugin()); // bus.emitter(creator)
 
@@ -1121,7 +1206,7 @@ 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).
+- `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable, and `events(bus, event)` into a `for await` loop. See [Observable](observable.md).
 
 ## Write your own plugin
 
@@ -1700,6 +1785,18 @@ Use this page for retry, timeouts, waiting, or parallel work — not as the firs
 
 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)).
 
+## On this page
+
+- [Wrap a handler with retry and timeout](#wrap-a-handler-with-retry-and-timeout)
+  - [Options for retry, timeout, and poll](#options-for-retry-timeout-and-poll)
+- [Back off between retries](#back-off-between-retries)
+- [Put selected effects on `ctx`](#put-selected-effects-on-ctx)
+- [Tie a promise to the task signal](#tie-a-promise-to-the-task-signal)
+- [Run cleanup on abort](#run-cleanup-on-abort)
+- [Wait for the next event with `take`](#wait-for-the-next-event-with-take)
+- [Run several starters together](#run-several-starters-together)
+- [Pass `ctx` outside a task](#pass-ctx-outside-a-task)
+
 ## Wrap a handler with retry and timeout
 
 `retry`, `timeout`, and `poll` have two forms:
@@ -1745,9 +1842,7 @@ bus.on("load", async (id, ctx) => {
     () => fetchUser(id, { signal: ctx.signal }),
     { times: 4 },
   );
-  const data = await timeout(ctx, 5000, ({ signal }) => {
-    return fetchData(id, { signal });
-  });
+  const data = await timeout(ctx, 5000, (child) => fetchData(id, child));
   await poll(ctx, () => refresh(), 10_000);
   ctx.emit("ready", { user, data });
 });
@@ -1856,7 +1951,8 @@ const bus = createBus().use(effects);
 bus.on("load", async (id, { race, all, delay }) => {
   // race — same as race(ctx, …)
   const result = await race({
-    data: ({ signal }) => fetchData(id, { signal }),
+    // child — the context of this starter; it has the `signal`, so the request stops with the race
+    data: (child) => fetchData(id, child),
     // a starter gets its own child with the same bound effects, so delay(5000) stops with the race
     timeout: ({ delay }) => delay(5000),
   });
@@ -1864,8 +1960,8 @@ bus.on("load", async (id, { race, all, delay }) => {
 
   // all — same as all(ctx, …)
   const { user, posts } = await all({
-    user: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
   });
 });
 ```
@@ -1988,8 +2084,8 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   const { user, posts } = await allSettled(ctx, {
-    user: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
   });
 
   if (user.status === "fulfilled") {
@@ -2095,7 +2191,7 @@ bus.on("sync", async (ids, ctx) => {
 The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`, so a group starter inside another group takes none; write `(child) => all(child, effects, { concurrency: 5 })` there.
 
 
-**A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options: `({ signal }) => fetchUser(id, { signal })`. The same holds for `all`, `allSettled` and `timeout`.
+**A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options, and `child` has a `signal`, so pass it as the options: `(child) => fetchUser(id, child)` (`fetch` reads only `signal` from it). The same holds for `all`, `allSettled` and `timeout`.
 
 If `ctx` is `{}` or a bare `{ signal }` (outside a task), `child` has only `signal` and `abort`, so it fits `delay` and `poll` but not `take`, which needs a bus.
 
@@ -2160,6 +2256,32 @@ A chat with two entities and three features, jobs under policies and effects, an
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
+## Pick the word: event, action, job, module
+
+Four names, one idea each. Take the first row that fits.
+
+| Word | What it is | Use it when |
+| ---- | ---------- | ----------- |
+| Event | A name and a payload; `createAction("x")` with no handler. | The UI or a handler tells that something happened. |
+| Action with a handler | The same, plus work: `createAction("x", handler)`. `emit` returns the result. | The caller needs a value back. |
+| Job | An action with a handler that also emits `pending`, `success`, `fail` and `cancel`. | The UI shows a loading state. |
+| Module | A group of listeners, handlers and tasks, mounted and unmounted with one call. | One domain must start and stop as a unit. |
+
+Start with events. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
+
+## On this page
+
+- [Pick the word: event, action, job, module](#pick-the-word-event-action-job-module)
+- [Return a value from `emit` with a handler](#return-a-value-from-emit-with-a-handler)
+- [Describe events, handlers and jobs](#describe-events-handlers-and-jobs)
+  - [Actions](#actions)
+  - [Bind a handler later](#bind-a-handler-later)
+  - [Say what a bound handler returns](#say-what-a-bound-handler-returns)
+  - [Jobs](#jobs)
+- [Show a loading state with a job](#show-a-loading-state-with-a-job)
+- [Mount domains with modules](#mount-domains-with-modules)
+- [Give an action or a module its own fields](#give-an-action-or-a-module-its-own-fields)
+
 ## Return a value from `emit` with a handler
 
 Give `createAction` a handler, and `emit` runs it and returns its result. There is one creator for an event and for an action with work behind it; the handler is the only difference.
@@ -2314,7 +2436,7 @@ On a bus without an event map you can say it where you call: `const id = bus.emi
 - `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, give `createAction` the handler.
 - Outcome actions are emitted as the task that ran the job (also for a handler bound with `actions.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
-- A job without a handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent. An action without a handler is an event and does not throw.
+- A job without a handler is not an outcome: `emit` throws `No handler for action "..."` and nothing is sent. An action without a handler is an event and does not throw.
 - 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.
 
@@ -3198,11 +3320,24 @@ A handler gets the store from `ctx.store` and calls a mutation, whatever it hand
 ---
 Source: docs/query-libraries.md
 
-# Use nanoeffects with React Query and SWR
+# Use nanoeffects with React Query, SWR and RTK Query
+
+Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query), [SWR](https://swr.vercel.app) or [RTK Query](https://redux-toolkit.js.org/rtk-query/overview) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one action that the libraries call, then three recipes for the parts around it: a client that stops with the request, a live stream into the cache, and a refetch on a bus event.
 
-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 action that both libraries call.
+You need a React project, `nanoeffects`, and one of the libraries. `api` below is your own client: replace it with your requests.
+
+## On this page
 
-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](#decide-who-owns-what)
+- [Make the action](#make-the-action)
+- [Call it from React Query](#call-it-from-react-query)
+- [Call it from SWR](#call-it-from-swr)
+- [Let the bus know the result](#let-the-bus-know-the-result)
+- [Call it from RTK Query](#call-it-from-rtk-query)
+- [Give the client its signal once](#give-the-client-its-signal-once)
+- [Push a live stream into the cache](#push-a-live-stream-into-the-cache)
+- [Refetch queries when the bus says so](#refetch-queries-when-the-bus-says-so)
+- [Know the limits](#know-the-limits)
 
 ## Decide who owns what
 
@@ -3263,7 +3398,7 @@ 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
+    // emit — runs the action; { signal } ties its task to the signal of React Query
     queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
   });
 
@@ -3315,9 +3450,264 @@ export const userLoaded = createAction("user/loaded");
 
 Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the action 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).
 
+## Call it from RTK Query
+
+<!-- docs-check: new -->
+
+RTK Query gives the `queryFn` of an endpoint a `signal` in its second argument, so the call is the same as with React Query: pass it to `emit`. This page does not set up the store; see [Stores](stores.md) for that.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — lets emit take { signal }
+export const bus = createBus().use(signalPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction with a handler — emit returns what the handler returns
+export const getUser = createAction("user/get", (id, { signal }) =>
+  api.getUser(id, { signal }),
+);
+```
+
+```js
+// api-slice.js
+import { createApi, fakeBaseQuery } from "@reduxjs/toolkit/query/react";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export const userApi = createApi({
+  reducerPath: "userApi",
+  baseQuery: fakeBaseQuery(), // RTK Query — every endpoint brings its own queryFn
+  endpoints: (build) => ({
+    getUser: build.query({
+      // emit — runs the action; { signal } ties its task to the request of RTK Query
+      queryFn: async (id, { signal }) => {
+        const user = await bus.emit(getUser(id), { signal });
+        return { data: user };
+      },
+    }),
+  }),
+});
+```
+
+## Give the client its signal once
+
+<!-- docs-check: new -->
+
+Problem: the action passes `signal` to every call of `api`, and one forgotten `{ signal }` leaves a request running after the query is gone. `fromSignal` builds the client from the signal of each task, so the handler cannot forget it. Use it when many actions share one client. A single action is simpler as it is in [Make the action](#make-the-action).
+
+`fromSignal` marks a field of `contextPlugin`. The client is made when a handler first reads `ctx.http`, from the `ctx.signal` of that task. More in [Context fields](context.md#build-a-field-from-the-signal-of-each-task).
+
+```js
+// bus.js
+import axios from "axios";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal, signalPlugin } from "nanoeffects/signal";
+
+// fromSignal — http is a new axios client for each task, bound to the signal of that task
+const http = fromSignal((signal) => axios.create({ baseURL: "/api", signal }));
+
+// contextPlugin — every handler gets ctx.http
+const context = contextPlugin({ http });
+
+// signalPlugin — emit takes { signal }, so the signal of the query reaches the task
+export const bus = createBus().use(signalPlugin()).use(context);
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// the handler never sees a signal: ctx.http stops when the task aborts
+export const getUser = createAction("user/get", async (id, { http }) => {
+  const response = await http.get(`/users/${id}`);
+  return response.data;
+});
+```
+
+```jsx
+// Profile.jsx
+import { useQuery } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export function Profile({ id }) {
+  const { data } = useQuery({
+    queryKey: ["user", id],
+    // emit — the signal of React Query aborts the task, and with it the request of ctx.http
+    queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
+  });
+
+  return <p>{data?.name}</p>;
+}
+```
+
+## Push a live stream into the cache
+
+<!-- docs-check: new -->
+
+Problem: prices arrive from a socket, and the component should show the newest one without a refetch. The socket code emits an event on the bus; the component reads those events with `events` and writes each into the cache. Both libraries have an entry point for pushed data: `setQueryData` in React Query and `useSWRSubscription` in SWR.
+
+`events` gives the payloads to a `for await` loop. `buffer: 1` keeps only the newest price while a write is running. The abort in the cleanup ends the loop and removes the listener. More in [Read an event with a `for await` loop](observable.md#read-an-event-with-a-for-await-loop).
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the socket code and the components share
+export const bus = createBus();
+```
+
+```js
+// prices.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the event the socket code emits for every new price
+export const priceChanged = createAction("price/changed");
+```
+
+```jsx
+// Price.jsx
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { events } from "nanoeffects/observable";
+import { bus } from "./bus";
+import { priceChanged } from "./prices";
+
+export function Price({ symbol }) {
+  const queryClient = useQueryClient();
+  const { data } = useQuery({
+    queryKey: ["price", symbol],
+    queryFn: () => api.getPrice(symbol), // the first value; the stream keeps it fresh
+  });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    // events — the newest price event, one at a time
+    const prices = events(bus, priceChanged, {
+      signal: controller.signal,
+      buffer: 1,
+    });
+
+    async function follow() {
+      for await (const price of prices) {
+        if (price.symbol === symbol) {
+          queryClient.setQueryData(["price", symbol], price.value); // write into the cache
+        }
+      }
+    }
+
+    follow().catch((error) => {
+      if (!controller.signal.aborted) throw error; // the abort ends the loop; anything else is a bug
+    });
+
+    return () => controller.abort(); // the component left: the loop ends, the listener goes
+  }, [queryClient, symbol]);
+
+  return <p>{data}</p>;
+}
+```
+
+SWR does the same with `useSWRSubscription` from `swr/subscription`. Its subscribe function gets `next` to push a value and returns the cleanup:
+
+```jsx
+// Price.jsx
+import useSWRSubscription from "swr/subscription";
+import { events } from "nanoeffects/observable";
+import { bus } from "./bus";
+import { priceChanged } from "./prices";
+
+export function Price({ symbol }) {
+  const { data } = useSWRSubscription(["price", symbol], (_key, { next }) => {
+    const controller = new AbortController();
+    // events — the newest price event, one at a time
+    const prices = events(bus, priceChanged, {
+      signal: controller.signal,
+      buffer: 1,
+    });
+
+    async function follow() {
+      for await (const price of prices) {
+        if (price.symbol === symbol) {
+          next(null, price.value); // SWR — push the value to the hook
+        }
+      }
+    }
+
+    follow().catch((error) => {
+      if (!controller.signal.aborted) next(error);
+    });
+
+    return () => controller.abort(); // SWR calls this when the last component of the key leaves
+  });
+
+  return <p>{data}</p>;
+}
+```
+
+## Refetch queries when the bus says so
+
+<!-- docs-check: new -->
+
+Problem: a save in one part of the app should refresh the lists in another. The save emits an event, and the component that owns the queries listens for it. One `AbortController` ends every listener of the component, instead of one `unbind` for each. For a single listener, `return bus.on(…)` from the effect is shorter.
+
+This needs `signalPlugin`, because `{ signal }` in the options of `on` is read by the plugin. Without it the listeners stay after the component leaves.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — on takes { signal } and removes the listener when it aborts
+export const bus = createBus().use(signalPlugin());
+```
+
+```js
+// user-events.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — events the save code emits
+export const userSaved = createAction("user/saved");
+export const userDeleted = createAction("user/deleted");
+```
+
+```jsx
+// UserList.jsx
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { userDeleted, userSaved } from "./user-events";
+
+export function UserList() {
+  const queryClient = useQueryClient();
+  const { data } = useQuery({ queryKey: ["users"], queryFn: () => api.listUsers() });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const { signal } = controller;
+    const refresh = () => queryClient.invalidateQueries({ queryKey: ["users"] });
+
+    // on with { signal } — both listeners go when the component leaves
+    bus.on(userSaved, refresh, { signal });
+    bus.on(userDeleted, refresh, { signal });
+
+    return () => controller.abort();
+  }, [queryClient]);
+
+  return <ul>{data?.map((user) => <li key={user.id}>{user.name}</li>)}</ul>;
+}
+```
+
 ## Know the limits
 
-- **Without the plugin, `{ signal }` is ignored.** The action runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
+- **Without the plugin, `{ signal }` is ignored,** in `emit` and in the options of `on`. The action 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. Actions 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 an action with a handler or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
@@ -3367,7 +3757,7 @@ The action loads a user. It tries the request up to three times, and gives up on
 import { createAction } from "nanoeffects/actions";
 import { retry, timeout } from "nanoeffects/effects";
 
-// createAction — a command with a handler: emit returns what the handler returns
+// createAction — an action with a handler: emit returns what the handler returns
 export const getUser = createAction("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 });
@@ -3408,7 +3798,7 @@ app.get("/users/:id", async (request, reply) => {
   });
 
   try {
-    // emit with { signal } — aborting the controller aborts the command: timeout, retry and the request
+    // emit with { signal } — aborting the controller aborts the action: timeout, retry and the request
     const call = getUser(request.params.id);
     return await bus.emit(call, { signal: controller.signal });
   } catch (error) {
@@ -3461,7 +3851,7 @@ import { createAction } from "nanoeffects/actions";
 import { poll } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
-// createAction — a command with a handler
+// createAction — an action with a handler
 // latest — a new subscription stops the old one; key — but only the old one of the same socket
 export const watchPrices = createAction(
   "prices/watch",
@@ -3540,6 +3930,16 @@ Use this page when a React screen starts requests on user input and you need the
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
+## On this page
+
+- [See what goes wrong without a bus](#see-what-goes-wrong-without-a-bus)
+- [Wire the bus once](#wire-the-bus-once)
+- [Connect the form](#connect-the-form)
+- [Stop running work when the form closes](#stop-running-work-when-the-form-closes)
+- [Show the last value of an event as state](#show-the-last-value-of-an-event-as-state)
+- [Keep a debounced handler between renders](#keep-a-debounced-handler-between-renders)
+- [Where to go next](#where-to-go-next)
+
 ## See what goes wrong without a bus
 
 A registration form has three problems that `useEffect` and `fetch` leave to you:
@@ -3611,7 +4011,7 @@ The handlers know nothing about React. A test can emit `username/typed` and read
 
 <!-- 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.
+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. If the component already holds an `AbortSignal`, `bus.on(event, handler, { signal })` ends the listener with it; see [`signalPlugin`](plugins.md#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin).
 
 ```jsx
 // SignUpForm.jsx
@@ -3812,7 +4212,7 @@ export const Search = ({ wait }) => {
 - 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).
+- React Query or SWR instead of your own state: [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).
 
 ---
 Source: docs/chat-example.md
@@ -3833,6 +4233,18 @@ npm run dev
 
 `npm run dev` starts the server and Vite together. Start it with `CHAOS=off npm run dev` to turn the failures off.
 
+## On this page
+
+- [Read how the server fails](#read-how-the-server-fails)
+- [See how the files are split](#see-how-the-files-are-split)
+- [Load a history that must not race](#load-a-history-that-must-not-race)
+- [Send a message that can fail](#send-a-message-that-can-fail)
+- [Search where one room is slow](#search-where-one-room-is-slow)
+- [Wait for a room before marking a result](#wait-for-a-room-before-marking-a-result)
+- [Poll for new messages](#poll-for-new-messages)
+- [Know where each value lives](#know-where-each-value-lives)
+- [Where to go next](#where-to-go-next)
+
 ## Read how the server fails
 
 The server keeps its data in memory. These rules are on purpose, and they are the same every run, so you can follow each section below by doing what the table says:
@@ -4105,7 +4517,7 @@ It is a level D example: the logic lives in one module, and the page only mounts
 | `src/chat-handlers.ts` | `askBot` (`timeout` and `retry` inside) and `watchOperator` (`poll`): plain `async` functions that know nothing about the page. |
 | `src/chat-module.ts` | The list of what is alive while the chat is open. |
 | `src/panel.ts` | The view: shows the lines, sends the texts, returns one function that removes it. |
-| `src/main.ts` | The launcher: the only file that knows both the module and the panel. |
+| `src/main.ts` | The launcher: the only file that knows both the module and the panel; it listens for `closeRequested` only while the chat is open. |
 
 ## Bind everything in one module
 
@@ -4155,7 +4567,7 @@ Three details that make the cleanup complete:
 
 ## Open and close from the launcher
 
-`app.mount` returns the function that unmounts the module. The launcher puts it together with the one that removes the panel.
+`app.mount` returns the function that unmounts the module. `bus.on` returns the one that unsubscribes. The launcher puts them together with the one that removes the panel into a single `close`.
 
 <!-- docs-check: skip - the other files of the example are in examples/chat-widget -->
 ```js
@@ -4171,7 +4583,10 @@ let close = null; // set while the chat is open
 const open = () => {
   const stopModule = app.mount(chatModule); // subscriptions, polling and Escape start
   const stopPanel = renderPanel(document.body);
+  // the module emits closeRequested on Escape; nothing does while the chat is closed
+  const stopEscape = bus.on(closeRequested, () => close?.());
   close = () => {
+    stopEscape();
     stopPanel();
     stopModule(); // everything the module started ends, a running request included
     close = null;
@@ -4185,18 +4600,15 @@ button.addEventListener("click", () => {
     open();
   }
 });
-
-// the launcher stays subscribed: it must hear Escape to close the chat
-bus.on(closeRequested, () => close?.());
 ```
 
-The launcher's own `bus.on` is the only subscription that lives while the chat is closed, and it does nothing then: `close` is `null`.
+While the chat is closed the launcher holds no subscription at all: it only has the click listener of the button, which is a DOM listener, not a listener of the bus.
 
 ## Check that closing cleans up
 
 1. Open the chat and send a text. The bot answers after about a second. Every third question fails, and the retry asks again.
 2. Send a text and close the chat before the answer arrives. No line appears, also when you open the chat again.
-3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: only `chat/closeRequested` has a listener (the launcher). Open: `chat/sent`, `chat/messageAdded` and `chat/typing` have one each as well. That is the proof that nothing is left subscribed.
+3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: every event shows `0`, and so does "all events". Open: each of the four has one listener, and "all events" is `4`. That is the proof that nothing is left subscribed.
 4. Wait 10 s with the chat closed. The operator is not polled: no line from the operator appears.
 5. Press `Escape` with the chat closed. Nothing happens. Open the chat and press it again: it closes.
 6. Open the chat again. The old lines are back, and the polling runs.
@@ -4420,7 +4832,7 @@ Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may
 
 To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
 
-To give fields to **one** command, action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
 
 ## Type the fields (optional)
 
@@ -4444,6 +4856,38 @@ bus.on("save", (draft, { store }) => store.put(draft));
 - A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
 - The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
 
+## Build a field from the signal of each task
+
+Problem: an HTTP client or a database handle should stop when the task is aborted. Without help, every handler passes `ctx.signal` to it by hand, and one forgotten call leaves a request running.
+
+`fromSignal(make)` from `nanoeffects/signal` marks a field of `contextPlugin` as a value that is built from the signal of the task. It does not run `make` for the bus: it runs it for each task that reads the field, once, with the `ctx.signal` of that task.
+
+```js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal } from "nanoeffects/signal";
+import axios from "axios";
+
+// contextPlugin — every task gets these fields
+// fromSignal — http is made from the signal of the task that reads ctx.http
+const bus = createBus().use(
+  contextPlugin({
+    logger: console, // a plain field: the same object for every task
+    http: fromSignal((signal) => axios.create({ signal })),
+  }),
+);
+
+bus.on("user/open", async (id, ctx) => {
+  const response = await ctx.http.get(`/users/${id}`); // aborts with the task
+  ctx.logger.log(response.data);
+});
+```
+
+- `make` runs at the first read, so a handler that never uses `ctx.http` pays nothing for it.
+- A task that `ctx.run` starts builds its own value from its own signal, so aborting the child stops only the child's requests.
+- The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.
+- Without `contextPlugin` a `fromSignal` marker is only an object.
+
 ### Name the fields in the event map instead
 
 `createBus<Events>({ context: { store } })` also types the fields, but through the event map: `WithContext` is checker-only and says which fields the handlers of this bus have. Use it when you cannot call `use`, for example for the bus that `createEffectsMiddleware` makes.
@@ -4468,6 +4912,18 @@ A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`,
 
 You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
 
+## On this page
+
+- [Turn scopes on](#turn-scopes-on)
+- [Give an action its own fields](#give-an-action-its-own-fields)
+- [Bind an effect to the task](#bind-an-effect-to-the-task)
+- [Replace a field for one call](#replace-a-field-for-one-call)
+- [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
+- [Which value wins](#which-value-wins)
+- [Keep a generic effect generic](#keep-a-generic-effect-generic)
+- [Type the fields (optional)](#type-the-fields-optional)
+- [Limits](#limits)
+
 ## Turn scopes on
 
 Scopes are a plugin, so a bus that does not use them pays nothing.
@@ -4498,7 +4954,7 @@ import { createAction } from "nanoeffects/actions";
 export const getUser = createAction(
   "user/get",
   (id, { api, cache }) => {
-    // api and cache are on ctx for this command only
+    // api and cache are on ctx for this action only
     return cache.get(id) ?? api.getUser(id);
   },
   { api, cache: new Map() },
@@ -4647,7 +5103,7 @@ 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 |
+| 2 | the scope of the action or job |
 | 3 | the scope of the module that owns the handler |
 | 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
 
@@ -4741,6 +5197,23 @@ Use this page when **your domain logic lives in classes**: a service, a store or
 
 If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
 
+## On this page
+
+- [The problem without it](#the-problem-without-it)
+- [Make an independent emitter with `Emitter`](#make-an-independent-emitter-with-emitter)
+  - [Type the events (optional)](#type-the-events-optional)
+- [Give a class the methods of a shared bus](#give-a-class-the-methods-of-a-shared-bus)
+  - [Extend the result with no class of your own](#extend-the-result-with-no-class-of-your-own)
+- [Let the class make its bus](#let-the-class-make-its-bus)
+- [End the subscriptions with `dispose`](#end-the-subscriptions-with-dispose)
+- [Stream an event with a `Subject`](#stream-an-event-with-a-subject)
+- [Keep a method of your own](#keep-a-method-of-your-own)
+- [Subscribe a method with `@On` and `@Once`](#subscribe-a-method-with-on-and-once)
+- [Decorate the class with `@WithBus`](#decorate-the-class-with-withbus)
+- [Pass a method by hand](#pass-a-method-by-hand)
+- [Type the instances (optional)](#type-the-instances-optional)
+- [What is not done](#what-is-not-done)
+
 ## 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.
@@ -5171,7 +5644,7 @@ export const getUser = createAction(
   },
 );
 
-// createModule: m.use binds the handler the command carries, while the module is mounted
+// createModule: m.use binds the handler the action carries, while the module is mounted
 export const userModule = createModule("user", (m) => {
   m.use(getUser);
 });
@@ -5421,6 +5894,17 @@ Source: docs/migrating-from-effector.md
 
 Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
 
+## On this page
+
+- [Split the work](#split-the-work)
+- [Find the equivalent](#find-the-equivalent)
+- [Rewrite an effect](#rewrite-an-effect)
+  - [Keep the state in Zustand](#keep-the-state-in-zustand)
+- [Rewrite a form](#rewrite-a-form)
+  - [Replace the log with a request](#replace-the-log-with-a-request)
+- [Use both in one app](#use-both-in-one-app)
+- [What is different](#what-is-different)
+
 ## Split the work
 
 | Job | Use |
@@ -6051,6 +6535,16 @@ Source: docs/semantics.md
 
 Guarantees and sharp edges. Read when something surprises you; not required to start.
 
+## Five rules to know first
+
+1. A handler is `(payload, ctx)`. Use `ctx.signal`, `ctx.emit` and `ctx.on`; the rest of `ctx` is optional.
+2. Pass `ctx.signal` to what the handler calls (`fetch`, a client), so an abort stops the work.
+3. An aborted task delivers no result and emits nothing.
+4. `emit` is synchronous: the first handler error is thrown, unless `onError` is set.
+5. Rejections of async handlers are not handled without `onError`.
+
+Details of each rule and the rest:
+
 - **An aborted task delivers no result.** If the task aborts before a promise settles, the promise rejects with the abort reason, even if the value was just produced in the same tick. `latest`, `debounce`, `all`, `race`, `take`, and the rest follow this rule.
 - **`emit` is a plain, synchronous loop** (see [Errors](errors.md)). A `ctx.emit` inside a handler is the same call: without `onError`, an error of a nested handler is thrown into the handler that emitted; with `onError` it goes there and `ctx.emit` does not throw.
 - **Rejections of async handlers** are not handled for you. Without `onError` they are unhandled rejections, which end a Node process by default. Use `onError` for async handlers.
@@ -6066,6 +6560,22 @@ Find out what your app did and why: which events were emitted, which calls a pol
 
 Tracing is optional. A bus works the same without it, and it costs almost nothing until you turn it on. If you only want to see what happens while you develop, jump to [Show every emit](#show-every-emit) and [Configure Redux DevTools](#configure-redux-devtools); the rest of the page is for apps that need to follow a flow or turn tracing off in a build.
 
+## On this page
+
+- [Attach a tracer](#attach-a-tracer)
+- [Show every emit](#show-every-emit)
+- [Show which subscription began a chain](#show-which-subscription-began-a-chain)
+- [Follow one flow with a traceGroupId](#follow-one-flow-with-a-tracegroupid)
+- [Name a listener](#name-a-listener)
+- [Keep the chain: `ctx.emit`, not `bus.emit`](#keep-the-chain-ctxemit-not-busemit)
+- [Turn the names off](#turn-the-names-off)
+- [Use built-in loggers](#use-built-in-loggers)
+  - [Cut volume in production](#cut-volume-in-production)
+  - [Keep the last events for an incident](#keep-the-last-events-for-an-incident)
+  - [Configure Redux DevTools](#configure-redux-devtools)
+  - [Write your own logger](#write-your-own-logger)
+- [Drop tracing from a build](#drop-tracing-from-a-build)
+
 ## Attach a tracer
 
 Pass `trace` to `createBus`. Make it with `createTracer` from `nanoeffects/trace`, which takes a logger (a function) or an array of them. The tracing code lives in that entry, so a bus without `trace` does not carry it.
@@ -6148,7 +6658,7 @@ The event changes nothing else: the other tasks keep their `parentId`, `rootId`
 
 ## Show which subscription began a chain
 
-**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of commands and retries.
+**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of actions and retries.
 
 **When.** The bus has a tracer and the project has several `useEmitter` or `bus.emitter` calls. The names come from `tracePlugin`: use it on the bus, or the `traceId` is ignored.
 
@@ -6176,8 +6686,8 @@ In a component, the same option goes in the options of the hook: `useEmitter(nam
 
 ```
 [nanoeffects] Profile · run start
-[nanoeffects]   user/save · command start
-[nanoeffects]   user/save · command done
+[nanoeffects]   user/save · action start
+[nanoeffects]   user/save · action done
 [nanoeffects] Profile · run done
 ```
 
@@ -6217,7 +6727,7 @@ const pay = createAction("checkout/pay", async () => {}, {
 ```
 
 ```
-[nanoeffects] [checkout] checkout/pay · command start
+[nanoeffects] [checkout] checkout/pay · action start
 ```
 
 The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", traceGroupId: "checkout" })`. `traceGroupId` works without `scopePlugin`, and needs `tracePlugin`.
@@ -6247,7 +6757,7 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 
 ```
 [nanoeffects] saveNotifier · run start
-[nanoeffects]   user/save · command start
+[nanoeffects]   user/save · action start
 [nanoeffects] saveNotifier · run done
 ```
 
@@ -6292,7 +6802,7 @@ const bus = createBus({
 | `reduxDevtools()` | Sends the emits to Redux DevTools, and with `policies` the stages of the handlers as `type/effect/phase`; state is `{ running }` |
 | `consoleLogger()` | Prints one line per phase, indented by task depth |
 | `performanceLogger()` | User Timing measures for the browser Performance panel |
-| `createTraceRecorder()` | Keeps events in `recorder.events`, for tests |
+| `createTraceRecorder()` | Keeps events in `recorder.events`: all of them for tests, or with `{ capacity }` the last N ([see below](#keep-the-last-events-for-an-incident)) |
 
 ### Cut volume in production
 
@@ -6308,8 +6818,60 @@ createTracer(logger, {
 - `sample` is decided once per root task; every task below it follows, so a trace is never cut in the middle. Unsampled tasks cost almost nothing.
 - `filter` runs on each event before any logger sees it.
 
+### Keep the last events for an incident
+
+`createTraceRecorder()` with no option keeps every event, so a long session fills memory. That is fine in a test and wrong in a running app. Give it a `capacity` and it keeps only the last N events (a ring buffer): when something goes wrong, you still have what led up to it.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer } from "nanoeffects/trace";
+
+// A logger that keeps the last 500 events and drops the older ones.
+export const recorder = createTraceRecorder({ capacity: 500 });
+
+// Feed the recorder from the tracer.
+const trace = createTracer(recorder);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// incident.js
+import { recorder } from "./bus";
+
+// Keep what is safe to send. An event also has `payload` and `error`.
+const withoutPayload = ({ id, parentId, type, effect, phase }) => ({
+  id,
+  parentId,
+  type,
+  effect,
+  phase,
+});
+
+window.addEventListener("error", () => {
+  const events = recorder.events; // a snapshot, oldest event first
+  const safe = events.map(withoutPayload);
+  const body = JSON.stringify(safe);
+  navigator.sendBeacon("/api/incident", body);
+});
+```
+
+What to know before you send the events:
+
+- **`payload` and `error` can hold private data**: what a user typed, tokens, personal text. The recorder keeps them as they are and does not redact. Choose what to send, as `withoutPayload` does.
+- **There is no time on an event.** You get the order, not the duration. To add a time, wrap the recorder in a logger that stamps `performance.now()` on a copy of the event.
+- **An old `parentId` can point at an event that was pushed out.** When you build a tree from the events, treat an unknown `parentId` as a root.
+- **`recorder.events` is a snapshot with a `capacity`.** Each read builds a new array, so read it once at the moment you need it. Without a `capacity` it is one live array.
+- **A low `sample` thins the buffer.** `createTracer(recorder, { sample: 0.05 })` records 5% of root tasks, so the buffer may hold little when the incident comes. See [Cut volume in production](#cut-volume-in-production).
+- **A `capacity` that is not a positive integer** (`0`, a negative number, `NaN`) means no limit.
+
 ### Configure Redux DevTools
 
+<!-- docs-check: new -->
+
 Read-only (the bus owns no state, so there is no time travel). Does nothing when the extension is not installed. Has its own instance in the DevTools picker, apart from your store.
 
 Quiet by default, so you see what happened before you see how:
@@ -6409,6 +6971,8 @@ Source: docs/observable.md
 
 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.
 
+The same entry has `events`, which needs no stream library: it gives an event to a `for await` loop. See [Read an event with a `for await` loop](#read-an-event-with-a-for-await-loop).
+
 `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
@@ -6552,6 +7116,47 @@ bus.on(
 
 `switchMap` drops the old inner stream. `latest` aborts the old task through `signal`, so a `fetch` that got the signal really stops.
 
+## Read an event with a `for await` loop
+
+Problem: a task wants to handle the payloads of one event one after another, in order, and stop when the screen closes. `take` waits for one payload, and a listener has no place for a loop.
+
+`events(source, event, options)` from `nanoeffects/observable` returns an async iterator of the payloads. It listens from the call, so a payload that comes before the first read is kept. `source` is a bus or a task context; with a context the loop also ends when the task aborts.
+
+```js
+import { createBus } from "nanoeffects";
+import { events } from "nanoeffects/observable";
+
+const bus = createBus();
+const controller = new AbortController();
+
+// events — the "query/changed" payloads one by one; keeps the last 3 while the loop is busy
+const queries = events(bus, "query/changed", {
+  signal: controller.signal,
+  buffer: 3,
+});
+
+async function watchQueries() {
+  for await (const query of queries) {
+    console.log("search for", query); // runs once per payload, in order
+  }
+}
+
+watchQueries().catch((reason) => console.log("stopped:", reason)); // the abort rejects the loop
+bus.emit("query/changed", "cat");
+controller.abort("screen closed"); // the loop ends with this reason
+```
+
+| Option | What it does | Default |
+| ------ | ------------ | ------- |
+| `signal` | Ends the loop. The waiting read rejects with the abort reason. | none |
+| `buffer` | The most payloads kept while the loop is busy. | `Infinity` |
+| `overflow` | Which payload goes when the buffer is full: `"drop-oldest"` or `"drop-newest"`. | `"drop-oldest"` |
+
+- `break`, `return` and a throw inside the loop remove the listener.
+- With no `buffer`, a loop that never reads keeps every payload. Set `buffer` for a slow loop.
+- An event of a bus does not end, so the loop ends only by `break`, the `signal` or the task.
+- Inside a task, `events(ctx, "query/changed")` needs no `signal`: the task ending is the end.
+
 ## Convert back to a stream or a promise
 
 | You need | Write |