nanoeffects 0.28.0 → 0.30.1

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,8 +1,23 @@
-# 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) 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.
+> **Level E.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
 
-You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
+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.
+
+## On this page
+
+- [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
 
@@ -63,7 +78,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 }),
   });
 
@@ -113,11 +128,266 @@ 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
+
+<!-- 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.

package/docs/react.md

@@ -1,20 +1,34 @@
 # Build a sign-up form in React
 
-Use this page when a React screen starts requests on user input and you need them not to race: a username check while typing, a submit button, a flaky network. It builds one registration form. The bus lives outside React; the component only subscribes to it.
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
+The task is a registration form. While the user types a name, the form asks the backend whether it is free, and the "Sign up" button submits the form. That makes the requests race: the answer to an old input can arrive after the answer to a new one and show a wrong result. This page shows how to solve it with nanoeffects. The bus lives outside React; the component only subscribes to it.
+
+Steps 1 and 2 are required, step 3 is not. The last two sections are extra.
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
-## See what goes wrong without a bus
+## On this page
+
+- [Problems of the form without a bus](#problems-of-the-form-without-a-bus)
+- [1. The bus and the handlers](#1-the-bus-and-the-handlers)
+- [2. The form component](#2-the-form-component)
+- [3. Stop requests when the form closes](#3-stop-requests-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)
+
+## Problems of the form without a bus
 
 A registration form has three problems that `useEffect` and `fetch` leave to you:
 
-- **A stale answer.** The user types `ann`, then `anna`. The answer for `ann` arrives last and says the name is free, although `anna` is taken.
+- **A race in the name check.** The user types `ann`, then `anna`, and every input sends a "is the name free" request. The answer for `ann` arrives last and says the name is free, although `anna` is taken.
 - **A double submit.** A second click on "Sign up" sends a second request while the first one is running.
 - **A flaky network.** One failed request should be retried, but a "name is taken" answer should not.
 
 Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one place, outside the component.
 
-## Wire the bus once
+## 1. The bus and the handlers
 
 Keep the bus in a file of its own, and the handlers of the form in another. Create the bus once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
 
@@ -71,11 +85,11 @@ bus.on(
 
 The handlers know nothing about React. A test can emit `username/typed` and read `username/checked` without rendering anything: the same wiring is tested in [`examples/registration-form.ts`](../examples/registration-form.ts) and `src/tests/registration-form.test.ts`.
 
-## Connect the form
+## 2. The form component
 
 <!-- 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
@@ -142,11 +156,11 @@ The `disabled` button is only for the look. The form stays correct without it: `
 
 In development, React StrictMode runs the effect twice (subscribe, unsubscribe, subscribe). That is safe here, because the cleanup removes exactly what the effect added.
 
-## Stop running work when the form closes
+## 3. Stop requests when the form closes
 
 <!-- docs-check: continue -->
 
-Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
+This step is optional. Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
 
 ```js
 import { latest } from "nanoeffects/policies";
@@ -268,12 +282,37 @@ export const Search = ({ wait }) => {
 - Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
 - To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
 - `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
-- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+- Without a React component, use [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus).
+
+### Write a policy without its function
+
+**Problem.** `usePolicy` puts the callback of the latest render into the policy itself, so it needs a policy that has no function yet. If you passed your own function there, it would be easy to pass the wrong one.
+
+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:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- 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: `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.
 
 ## Where to go next
 
 - The policies behind this form: [Policies](policies.md).
-- A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
+- A policy as a plain function without a bus: [`withPolicy`: call a policy outside a bus](policies.md#withpolicy-call-a-policy-outside-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).