nanoeffects 0.29.0 → 0.31.0

package/docs/pass-the-signal.md

@@ -0,0 +1,346 @@
+# Keep the signal through a handler
+
+> **Level B.** Read first: [Policies](policies.md#latest).
+
+A policy such as `latest` cancels an older call by aborting its `ctx.signal`. The handler stops only if every step that waits gets that signal. One request without it keeps running, and its result arrives after the newer one. This page lists the ways the signal gets lost, what catches each one before the code runs (a linter) and while it runs (`devPlugin`), and how to fix it.
+
+## On this page
+
+- [Know what the signal does](#know-what-the-signal-does)
+- [Bind the signal once](#bind-the-signal-once)
+- [Fix a handler that loses the signal](#fix-a-handler-that-loses-the-signal)
+- [Pass the signal when it is hard](#pass-the-signal-when-it-is-hard)
+- [Turn on the checks](#turn-on-the-checks)
+- [Choose which calls are checked](#choose-which-calls-are-checked)
+- [Count lost signals in a test](#count-lost-signals-in-a-test)
+- [Prove it with a test](#prove-it-with-a-test)
+- [Know what the checks cannot see](#know-what-the-checks-cannot-see)
+
+## Know what the signal does
+
+`ctx.signal` is an `AbortSignal`. The policy aborts it when the call is cancelled (a newer call of `latest`, a `debounce` that was replaced, an unmounted module). A step stops when you give it the signal: `fetch(url, { signal: ctx.signal })`, `api.search(query, { signal: ctx.signal })`, or the whole `ctx` for an effect, `retry(ctx, ...)`. Everything else keeps running. The bus drops what a cancelled handler emits with `ctx.emit`, so the loss shows up late and quietly.
+
+## Bind the signal once
+
+The surest fix is a handler with no signal in it. Make the client from the signal of the task, once, and the handler calls `ctx.fetch` and cannot forget anything. `signalFetch` is a `fetch` bound to a signal; `fromSignal` builds it for each task.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal, signalFetch } from "nanoeffects/signal";
+import axios from "axios";
+
+// fromSignal — ctx.fetch is made from the signal of the task that reads it
+export const bus = createBus().use(
+  contextPlugin({
+    fetch: fromSignal(signalFetch),
+    // your own client too: it is made from the signal of each task
+    http: fromSignal((signal) => axios.create({ signal })),
+  }),
+);
+```
+
+```js
+// search-handlers.js
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // no signal here: ctx.fetch stops when the policy cancels the handler
+    const response = await ctx.fetch(`/api?q=${query}`);
+    ctx.emit("results", await response.json());
+  }),
+);
+```
+
+A call with a `signal` of its own stops with whichever aborts first. Then make the linter hold the line: with `requireContext: true`, every call that a handler waits for must go through `ctx` or be given `ctx`, so a global `fetch` or `api.search(...)` is an error even when the signal is passed by hand ([turn on the checks](#turn-on-the-checks)).
+
+## Fix a handler that loses the signal
+
+The two shapes you meet first, and the fix:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// 1. ctx is taken and the signal is lost: the request cannot stop
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query);
+    ctx.emit("results", items);
+  }),
+);
+
+// 2. one step passes it and another does not: the first one cannot stop
+bus.on(
+  "feed",
+  latest(async (query, ctx) => {
+    const news = await api.news(query);
+    const posts = await api.posts(query, { signal: ctx.signal });
+    ctx.emit("results", { news, posts });
+  }),
+);
+
+// the fix: every step that waits gets the signal
+bus.on(
+  "feed/fixed",
+  latest(async (query, ctx) => {
+    const news = await api.news(query, { signal: ctx.signal });
+    const posts = await api.posts(query, { signal: ctx.signal });
+    ctx.emit("results", { news, posts });
+  }),
+);
+```
+
+## Pass the signal when it is hard
+
+Each row is a situation where the signal is easy to lose. The right column says how to keep it. "Lint" is the rule from [`examples/lint`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/lint) that flags it, and "devPlugin" is the warning at run time ([details](hmr.md#find-a-handler-that-ignores-the-signal)).
+
+| Situation | What to do | Lint | devPlugin |
+| --------- | ---------- | :--: | :-------: |
+| The handler has no `ctx`: `latest(async (query) => ...)` | Take `(query, ctx)` and pass `ctx.signal` | yes | |
+| `ctx` is taken and never used for the request | Pass `{ signal: ctx.signal }` to each request, or bind it once: `ctx.fetch` ([above](#bind-the-signal-once)) | yes | yes |
+| One step passes the signal, another does not | Pass it to every step | yes | yes |
+| The signal is in a variable: `const options = { signal: ctx.signal }` | Nothing, a variable that holds it counts | accepted | |
+| Calls run together: `Promise.all([a(), b()])` | Pass it to each call, not only one | yes | |
+| `Promise.all(ids.map((id) => load(id)))` | Pass it inside the callback | yes | |
+| The step is inside an effect: `retry(ctx, () => api.search(q))` | The callback is not given the signal. Pass `{ signal: ctx.signal }` in it, or use the child context it gets | yes | |
+| `timeout(ctx, 1000, (child) => api.search(q))` | Pass `child`, or `child.signal`, to the request | yes | |
+| `ctx.run((child) => api.search(q))` | Pass `child` | yes | |
+| A pause: `await new Promise((r) => setTimeout(r, 1000))` | Use `delay(ctx, 1000)` | yes | |
+| A stream: `for await (const x of api.stream(q))` | Pass the signal to `api.stream` | yes | |
+| A chain: `api.news(q).then(...)` | Pass the signal to the first call | yes | |
+| Another signal: `AbortSignal.timeout(5000)`, or the signal of your own `AbortController` | Join it with the handler's: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])` | yes | |
+| Reading a response body: `await response.json()` | Nothing, the signal of the request stops it | accepted | |
+| A library that takes no signal (a cache, a local database) | List it in `ignore`, or check only the calls on your list with `only`. With type information the rule skips a function that takes no signal on its own | `ignore`, `only`, types | |
+| A function takes the signal and never uses it: `search(query, options) { return fetch(url); }` | Pass the signal on inside it. Only type information finds this in the linter; a test finds it for sure | types | |
+| The signal is wired by hand: `signal.addEventListener("abort", ...)` | Nothing, the handler is not checked step by step | accepted | |
+| `bus.emit` in a handler | Use `ctx.emit`: only it is dropped after the handler was cancelled | yes | |
+| A request that keeps running after the cancel, on Node | Pass the signal, or use `ctx.fetch` | | yes |
+| Results emitted after the cancel | The handler ignored the signal. Pass it, or check `ctx.signal.aborted` | | yes |
+| `ctx.on` after the cancel | The same | | yes |
+
+The pause and the effect rows in code:
+
+```js
+import { createBus } from "nanoeffects";
+import { delay, retry, timeout } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // delay — a pause that stops with ctx, not new Promise(setTimeout)
+    await delay(ctx, 300);
+
+    // retry — the attempts stop with ctx, but the request needs the signal too
+    const items = await retry(ctx, () => api.search(query, { signal: ctx.signal }));
+
+    // timeout — the callback gets a child context: give it to the request
+    const details = await timeout(ctx, 5000, (child) => api.details(query, child));
+
+    ctx.emit("results", { items, details });
+  }),
+);
+```
+
+Calls that run together, and a signal that joins another:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+bus.on(
+  "feed",
+  latest(async (query, ctx) => {
+    // each call of the group gets the signal, not only the first
+    const [news, posts] = await Promise.all([
+      api.news(query, { signal: ctx.signal }),
+      api.posts(query, { signal: ctx.signal }),
+    ]);
+
+    // AbortSignal.any — stops with the handler or after 5 seconds, whichever comes first
+    const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)]);
+    const details = await api.details(query, { signal });
+
+    ctx.emit("results", { news, posts, details });
+  }),
+);
+```
+
+## Turn on the checks
+
+**While you write.** [`examples/lint`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/lint) has a rule for ESLint and oxlint (one file, no dependency) and two GritQL plugins for Biome. Copy the file, turn the rule on, and give it the names of calls that cannot be cancelled:
+
+<!-- docs-check: skip - a config file of the reader's project -->
+```js
+// eslint.config.mjs
+import nanoeffects from "./nanoeffects-lint.mjs";
+
+export default [
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx}"],
+    plugins: { nanoeffects },
+    rules: {
+      "nanoeffects/policy-handler-uses-signal": [
+        "warn",
+        // calls that take no signal and are fine to wait for
+        { ignore: ["cache.get", "storage.*"], requireContext: false },
+      ],
+    },
+  },
+];
+```
+
+For oxlint list the file in `jsPlugins` of `.oxlintrc.json` and use the same rule name. For Biome list the two `.grit` files in `plugins`. The Biome plugins read text, so they flag the direct steps (the first rows above) and miss the deeper ones: the calls of `Promise.all`, the callbacks of effects, `for await`, a pause, and the key of an options object.
+
+**While you run.** `devPlugin` warns once when a handler emits, or subscribes with `ctx.on`, after its task was cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { devPlugin } from "nanoeffects/dev";
+
+const bus = createBus();
+
+// devPlugin — warns about a handler that kept running after it was cancelled; nothing in production
+bus.use(devPlugin());
+```
+
+## Choose which calls are checked
+
+The rule cannot tell, from the call alone, whether the function takes a signal. Ways to tell it:
+
+- **`requireContext`** needs no list: set it to `true` when handlers make requests through `ctx` (see [Bind the signal once](#bind-the-signal-once)), and any call that does not go through `ctx` is reported. `ignore` still skips a call.
+- **`ignore`** lists the calls to skip, by name: `ignore: ["cache.get", "storage.*"]`. Use it when most calls take a signal and a few cannot.
+- **`only`** lists the calls to check, by name: `only: ["api.*", "fetch"]`. Anything else is left alone, so a call that is not on the list is never reported. Use it when you know which clients take a signal. A call on both lists is skipped, and a pause that nothing can cancel (`await new Promise(...)`) is reported whatever `only` says.
+- **Type information** needs no list. With `@typescript-eslint/parser` and a `project`, the rule reads the function it calls. A call that does not get the signal is reported only when the function takes one (a parameter typed `AbortSignal`, or an options object with `signal`), so `cache.get(key)` is left alone. A call that passes the signal is reported when the function is in your sources and never uses it: the parameter is unused, or only other options are read from it. A signal forwarded to another function of yours is followed up to three calls deep, and a function from a library is trusted. A callee typed `any` is reported as before.
+
+<!-- docs-check: skip - a config file of the reader's project -->
+```js
+// eslint.config.mjs
+import parser from "@typescript-eslint/parser";
+import nanoeffects from "./nanoeffects-lint.mjs";
+
+export default [
+  {
+    files: ["**/*.{ts,tsx}"],
+    // the parser gives the rule the type checker of your project
+    languageOptions: { parser, parserOptions: { project: "./tsconfig.json" } },
+    plugins: { nanoeffects },
+    rules: { "nanoeffects/policy-handler-uses-signal": "warn" },
+  },
+];
+```
+
+oxlint and Biome do not give a rule type information, so they use the syntax and the lists. The type-aware mode needs the `typescript` package with the compiler API (version 5 today; the native version 7 has none), as `@typescript-eslint/parser` does.
+
+## Count lost signals in a test
+
+`getLostSignalsCount(bus)` from `nanoeffects/dev` returns how many signals the handlers of a bus lost: each emit or `ctx.on` that a handler made after its task was cancelled. The bus needs `devPlugin`. Run the flow the way a user would, cancel it, and check that the count is 0:
+
+```js
+import { createBus } from "nanoeffects";
+import { devPlugin, getLostSignalsCount, getLostSignals } from "nanoeffects/dev";
+import { latest } from "nanoeffects/policies";
+import { expect, test } from "vitest";
+
+test("a newer search leaves no lost signals", async () => {
+  const bus = createBus();
+  // devPlugin — records every emit that a cancelled handler made; log hides its warnings in the test
+  bus.use(devPlugin({ log: () => {} }));
+  bus.on(
+    "search",
+    latest(async (query, ctx) => {
+      const items = await api.search(query, { signal: ctx.signal });
+      ctx.emit("results", items);
+    }),
+  );
+
+  bus.emit("search", "a");
+  bus.emit("search", "ab"); // cancels the first call
+
+  // wait — how long to let the handlers finish before counting, in ms
+  const count = await getLostSignalsCount(bus, { wait: 50 });
+
+  expect(count).toBe(0);
+});
+```
+
+`getLostSignals(bus)` gives the list instead of the count: `{ kind: "emit" | "on", handler, event }` for each, so a failing test says which handler and which event. Without `devPlugin` (or with `abandoned: false`) it throws and says so. In a production build both functions are empty: the count is 0.
+
+On Node (tests, servers) it counts requests too. `devPlugin` follows the `fetch` calls that a handler makes, also after `await`, and counts one with `kind: "request"` when its task was cancelled while the request was still running and the request did not stop: it got no signal, or a signal that is not the task's. You add nothing to the test. In a browser there is no way to tell which task made a request, so only the emits and subscriptions are counted. `requests: false` turns the tracking off.
+
+```js
+import { createBus } from "nanoeffects";
+import { devPlugin, getLostSignals } from "nanoeffects/dev";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+bus.use(devPlugin({ log: () => {} }));
+
+bus.on(
+  "search",
+  latest(async (query) => {
+    await fetch(`/api?q=${query}`); // no signal
+  }),
+);
+
+bus.emit("search", "a");
+bus.emit("search", "ab");
+
+// [{ kind: "request", handler: "search", event: "/api?q=a" }]
+console.log(await getLostSignals(bus, { wait: 50 }));
+```
+
+A request that finished before the cancel is not counted. For another client (axios, a driver) bind it with `fromSignal`, or stub it in a test as the next section does for `fetch`.
+
+## Prove it with a test
+
+A linter reads code; it cannot know what a function does with the signal. A test can. The idea: replace `fetch` with a server that answers when the test lets it and stops when the request's signal aborts, run the handler, cancel it in the middle of each step, and list the requests that did not stop. No timers are involved, so the result does not depend on how fast the machine is.
+
+<!-- docs-check: skip - a test file of the reader's project -->
+```js
+// search.cancel.test.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { expect, test } from "vitest";
+// copy prove-cancel.js from examples/lint; it needs no package
+import { requestsThatKeptRunning } from "./prove-cancel.js";
+
+test("a newer search stops the older one at every step", async () => {
+  const bus = createBus();
+  bus.on(
+    "search",
+    latest(async (query, ctx) => {
+      const news = await api.news(query, { signal: ctx.signal });
+      const posts = await api.posts(query, { signal: ctx.signal });
+      ctx.emit("results", { news, posts });
+    }),
+  );
+
+  // for each step: start a call, cancel it with a newer one, and collect the requests that did not stop
+  const kept = await requestsThatKeptRunning((value) => bus.emit("search", value));
+
+  // empty when every request got a signal that aborted with the handler
+  expect(kept).toEqual([]);
+});
+```
+
+`kept` has the url of each request that went on, the step where the handler was cancelled, and whether the request got a signal at all (`hadSignal: false`) or one that is not the handler's (`hadSignal: true`). This finds what the linter cannot: `api.posts` that takes `{ signal }` and ignores it, an `AbortSignal.timeout` in place of the handler's signal, a request in a branch you did not think of. It checks the boundary, `fetch`; for another client (axios, a database driver) stub that client in the same way. The repository tests the helper on handlers that forward the signal, ignore it, drop it at the third step, and use a signal of their own.
+
+## Know what the checks cannot see
+
+- **A handler that is not written in place.** `latest(searchHandler)` and `latest(withLogging(async (query, ctx) => ...))` are not read by the linter.
+- **A callee that ignores the signal you pass.** Without type information the rule sees that you passed it, not what the callee does with it. With it, the rule reads callees in your sources; a library is trusted. The test above checks the real requests.
+- **A handler that never emits.** `devPlugin` sees a lost signal by an emit after the cancel; a handler that only writes elsewhere is seen by the linter alone.
+- **Shadowed names.** The rule uses no scope analysis, so an inner variable named `signal` can hide a lost signal.

package/docs/plugins.md

@@ -1,5 +1,7 @@
 # Choose the plugins of a bus
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 and 2.
+
 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
@@ -19,6 +21,7 @@ Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registr
   - [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)
+  - [Cut a loop that runs away: `loopGuardPlugin`](#cut-a-loop-that-runs-away-loopguardplugin)
 - [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)
@@ -47,6 +50,7 @@ Find your need in the left column. No row fits: you need no plugin.
 | 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) |
+| A loop that must not take the app down | [`loopGuardPlugin`](#cut-a-loop-that-runs-away-loopguardplugin) |
 
 ## Main plugins
 
@@ -56,7 +60,7 @@ These four cover what most apps need: shared dependencies, effects, handlers and
 | ------ | ----------------- | ------ | ----------------- |
 | [`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 |
-| [`actionsPlugin`](#let-a-test-replace-a-handler-commandsplugin) | The handlers of actions in a registry, so a test can bind or replace one. | `nanoeffects/actions` | The registry `{ run, handle }` |
+| [`actionsPlugin`](#bind-or-replace-a-handler-actionsplugin) | The handlers of actions in a registry, so a test can bind or 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, actions, createModule }` |
 
 ### Put a store or a client on every handler: `contextPlugin`
@@ -77,7 +81,7 @@ A client that must stop with the task, such as an `axios` instance, goes in as `
 
 ### 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).
+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#effectsplugin).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -116,7 +120,7 @@ const user = await bus.emit(getUser("1")); // { id: "1" }
 
 ### Mount a domain as one unit: `modulePlugin`
 
-A module groups the listeners, the bound handlers 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).
+A module groups the listeners, the bound handlers 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#modules).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -143,10 +147,11 @@ Add one of these when you meet its need. None of them is required.
 | [`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 |
 | [`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 |
+| [`loopGuardPlugin`](#cut-a-loop-that-runs-away-loopguardplugin) | Refuses the emit that would pass a limit of a chain, so a loop ends. | `nanoeffects/guard` | The same bus |
 
 ### Give one action its own fields: `scopePlugin`
 
-An action with a handler, 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).
+An action with a handler, 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](context.md#scope-fields-for-an-action-a-module-and-a-call).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -174,7 +179,7 @@ import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { signalPlugin } from "nanoeffects/signal";
 
-// signalPlugin — emit takes { signal } for an action, a job or an action
+// signalPlugin — emit takes { signal } for an action or a job
 const bus = createBus().use(signalPlugin());
 
 const getUser = createAction("user/get", (id, { signal }) => api.getUser(id, { signal }));
@@ -291,6 +296,18 @@ const disconnect = bus.use(devPlugin());
 disconnect(); // stops the diagnostics
 ```
 
+### Cut a loop that runs away: `loopGuardPlugin`
+
+Two handlers that emit each other's events never stop, and a loop of microtasks freezes the page. The plugin follows the chain of emits and refuses the emit that would repeat one event too often or make the chain too long. It needs no tracer, so it can stay on in production. More in [Cut a loop](loop-guard.md).
+
+```js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+// loopGuardPlugin — refuses the emit that would put one event in a chain 50 times
+const bus = createBus().use(loopGuardPlugin({ maxRepeats: 50 }));
+```
+
 ## Put them together
 
 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.

package/docs/policies.md

@@ -1,10 +1,12 @@
 # Policies
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when handlers overlap in a SPA (search-as-you-type, double submit, leave page). A **policy** wraps a handler and decides what happens then.
 
 Start with `latest`. The table and sections below are the rest of the reference.
 
-## Abort the previous run
+## `latest`: abort the previous run
 
 ```js
 import { createBus } from "nanoeffects";
@@ -26,7 +28,7 @@ Pass `signal` to `fetch` (and the like) so the request cancels.
 
 ## Choose a policy
 
-Every policy accepts `key` in its options (see [Isolate state by key](#isolate-state-by-key)).
+Every policy accepts `key` in its options (see [`key`: isolate state by key](#key-isolate-state-by-key)).
 
 | Policy | Overlapping calls |
 | ------ | ----------------- |
@@ -36,54 +38,79 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
-## Call a policy without its function
+Each policy has a short entry in [Look up a policy](#look-up-a-policy).
 
-**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+## Look up a policy
 
-**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+One entry per policy: what it does, and a link to the full recipe.
 
-Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+### `latest`
 
-```js
-import { debounce } from "nanoeffects/policies";
+A newer call aborts the older one and drops its result.
 
-const runSearch = async (query) => {
-  await api.search(query);
-};
+Signature: `latest(fn, options?)`.
 
-// debounce(300) — no function yet: returns a wrapper
-const wrap = debounce(300);
+More: [`latest`: abort the previous run](#latest-abort-the-previous-run).
 
-// the wrapper takes the function; same as debounce(300, runSearch)
-const search = wrap(runSearch);
-```
+### `leading`
+
+New calls are dropped while a run is going.
+
+Signature: `leading(fn, options?)`.
+
+More: [Prevent a double submit](prevent-double-submit.md).
+
+### `debounce`
+
+Runs after a period of quiet.
+
+Signature: `debounce(ms, fn, options?)`.
+
+More: [Configure debounce and throttle](#configure-debounce-and-throttle).
+
+### `throttle`
+
+At most one run within `ms`.
 
-- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
-- Each time you apply a wrapper to a function, you get a new policy with its own state.
-- To combine policies, nest them as before: `throttle(100, latest(fn))`.
-- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+Signature: `throttle(ms, fn, options?)`.
+
+More: [Configure debounce and throttle](#configure-debounce-and-throttle).
+
+### `queue`
+
+Builds a queue of calls: they run one after another, in order.
+
+Signature: `queue(fn, options?)`.
+
+More: [Run calls one after another with `queue`](#run-calls-one-after-another-with-queue).
+
+### `key`
+
+An option of every policy. It splits the state of the policy by a property, for example by id: calls with different keys do not affect each other.
+
+Signature: `latest(fn, { key: (payload) => payload.id })`.
+
+More: [`key`: isolate state by key](#key-isolate-state-by-key).
+
+To use a policy for your own function with no bus, see [`withPolicy`: call a policy outside a bus](#withpolicy-call-a-policy-outside-a-bus).
 
 ## Configure debounce and throttle
 
-`debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.
+`debounce` and `throttle` take two options, `leading` and `trailing`. They decide which call of a series runs. `leading` runs the first call of the series at once. `trailing` runs the last call at the end of the series. Both functions are built on the same algorithm as in lodash (and patronum) and behave exactly like them.
 
-**Throttle** (`throttle(ms, fn)`):
+**Throttle** (`throttle(ms, fn)`) runs a call at once if it has been idle for at least `ms`, holds the calls that come within `ms`, and runs the last of them when the window closes. Under a steady stream it runs every `ms`.
 
-- Default `leading: true`, `trailing: true`.
-- A call when the throttle is idle (at least `ms` after the previous call and run) runs at once.
-- Calls made while it waits are held; the latest runs when the window closes.
-- Under a steady stream it runs every `ms`.
-- `leading: false` — even the first call waits for the end of its window.
-- `trailing: false` — drop calls made during a window.
+- `leading` — run the first call of a series at once. It is `true` by default. With `false`, even the first call waits for the end of its window.
+- `trailing` — run the last held call when the window closes. It is `true` by default. With `false`, calls made during a window are dropped.
 
-**Debounce** (`debounce(ms, fn)`):
+**Debounce** (`debounce(ms, fn)`) runs the last call of a series after `ms` of quiet.
 
-- Default `trailing: true` — run the last call after `ms` of quiet.
-- `leading: true` — also run the first call of a burst at once; the trailing run happens only if more calls follow.
-- `leading: true, trailing: false` — only the first call of a burst.
+- `trailing` — run the last call after `ms` of quiet. It is `true` by default.
+- `leading` — also run the first call of a series at once. It is `false` by default. The closing run then happens only if more calls follow.
+- `leading: true, trailing: false` — only the first call of a series.
 - Both `false` — nothing runs.
 
-## Isolate state by key
+## `key`: isolate state by key
 
 `key` gives each key its own state. Calls with different keys do not affect each other. Idle keys are dropped, so keys can be unbounded (ids, urls).
 
@@ -142,35 +169,35 @@ 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.
 
-## Use a policy without a bus
+## `withPolicy`: call a policy outside a bus
 
-**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.
+**Problem.** You want a debounced input handler or a "latest request wins" fetch for your own function, but the code has no bus: a DOM handler, a click callback, a function in a service. A policy needs a context on every call, so `debounce(300, search)("re")` does not work on its own.
 
-**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.
+**When.** One input, button or function needs a policy and nothing else from the library. If you already have a bus, `bus.on(event, policy)` is simpler. In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders), which also keeps the function between renders.
 
-`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.
+`withPolicy` takes a policy and returns a plain function. The function needs no bus and no context argument, and it keeps the state of the policy between calls.
 
 ```js
 import { debounce, withPolicy } from "nanoeffects/policies";
 
+const input = document.querySelector("#search");
+
 // debounce — waits for 300 ms of quiet, then runs the callback
 const policy = debounce(300, async (query, { signal }) => {
-  await api.search(query, { signal });
+  const items = await api.search(query, { signal });
+  render(items);
 });
 
 // withPolicy — a plain function: no bus, no context argument
-const onChange = withPolicy(policy);
+const onInput = withPolicy(policy);
 
-onChange("re");
-onChange("redux"); // only this call runs, 300 ms after it
+input.addEventListener("input", (event) => onInput(event.target.value));
 
-// cancel — drops a pending call and aborts a running one
-onChange.cancel();
+// cancel — drops a pending call and aborts a running request, for example when the page closes
+window.addEventListener("pagehide", () => onInput.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.
+- Where `Symbol.dispose` exists, `using onInput = withPolicy(policy)` calls `cancel()` at the end of the scope.

package/docs/prevent-double-submit.md

@@ -1,5 +1,7 @@
 # Prevent a double submit
 
+> **Level B.** Read first: [Policies](policies.md).
+
 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
@@ -94,7 +96,7 @@ bus.on(
 );
 ```
 
-Backoff between tries: [Back off between retries](effects.md#back-off-between-retries).
+Backoff between tries: [`backoff`](effects.md#backoff).
 
 ## Guard a handler when you have no bus
 

package/docs/query-libraries.md

@@ -1,5 +1,7 @@
 # Use nanoeffects with React Query, SWR and RTK Query
 
+> **Level E.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 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.
 
 You need a React project, `nanoeffects`, and one of the libraries. `api` below is your own client: replace it with your requests.
@@ -126,7 +128,7 @@ import { createAction } from "nanoeffects/actions";
 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).
+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#the-state-of-a-job).
 
 ## Call it from RTK Query