nanoeffects 0.8.0 → 0.10.0

package/docs/observable.md

@@ -1,24 +1,138 @@
 # Turn events into Observables
 
-Use this page only when you already work in Observables / RxJS. Prefer `bus.on` with policies for cancellation and tracing.
+Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
 `createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
 
+## Turn an event into a stream
+
+Problem: a search box emits `typed` on every key. You want to wait for a pause and skip repeats with operators you already know.
+
 <!-- docs-check: skip - needs rxjs, which the project does not depend on -->
 ```js
-import { from } from "rxjs";
-import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";
+import { createBus } from "nanoeffects";
 import { createObserve } from "nanoeffects/observable";
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged } from "rxjs/operators";
 
-const observe = createObserve(bus); // Observable per event name
+const bus = createBus(); // the bus: events and handlers
+const observe = createObserve(bus); // observe(event) gives an Observable per event name
 
-from(observe("typed"))
-  .pipe(debounceTime(300), distinctUntilChanged(), switchMap(searchRequest))
-  .subscribe((items) => bus.emit("results", items));
+const typed$ = from(observe("typed")); // RxJS wraps it with from()
+
+const subscription = typed$
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query)); // back into the bus
 ```
 
 - `observe(event)` returns an Observable of the payloads of that event. Each `subscribe` is a `bus.on` of its own; `unsubscribe()` removes it.
 - `subscribe` takes a function or an object with `next`.
-- The stream never completes and never fails: events are the only thing that arrives. Errors of the subscriber’s handler belong to the subscriber.
-- A subscription made this way is not tied to a task. End it yourself: `onAbort(ctx, subscription.unsubscribe)` inside a task, or with the signal of a module.
-- For cancellation, policies, and tracing, keep to `bus.on` with `latest`, `debounce`, `queue` — they know about tasks. The Observable is for places where a stream is already how you work.
+- Types follow the event map: `observe("typed")` is an `Observable<string>` when `typed` carries a string.
+
+## Send a stream into the bus
+
+Problem: `.subscribe((value) => bus.emit(action(value)))` repeats the bus and the action in every subscription. `bus.emitter(action)` from `emitterPlugin` returns that callback, so it is the argument of `subscribe`. It works with any source that takes a `next` function: an RxJS stream, a store callback, a DOM listener.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("search/queryChanged"); // a plain action creator
+```
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map } from "rxjs/operators";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+const input = document.querySelector("#search"); // the search box
+
+const subscription = fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+  )
+  .subscribe(bus.emitter(queryChanged)); // calls bus.emit(queryChanged(value))
+
+bus.on(queryChanged, (query) => console.log("search for", query));
+```
+
+The Observable can come from anywhere, not only from `createObserve`. `subscription.unsubscribe()` stops it; the bus does not know about it. Pass the callback to `subscribe` as it is, and do not call `bus.emitter(...)` inside the operators on every value.
+
+## Do the work in a handler, not in `switchMap`
+
+An Observable is good for shaping values. A request is better in a handler with a policy, because the handler has a `signal` and the trace shows it. Split it: RxJS ends at the value, the bus starts the work.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { latest } from "nanoeffects/policies";
+
+// RxJS: shape the values (debounce, skip repeats), then hand them to the bus
+from(observe("typed"))
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query));
+
+// nanoeffects: one cancellable request; a newer "search" aborts the old one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+`switchMap` drops the old inner stream. `latest` aborts the old task through `signal`, so a `fetch` that got the signal really stops.
+
+## Convert back to a stream or a promise
+
+| You need | Write |
+| -------- | ----- |
+| A stream of events, with operators | `from(observe("event"))` |
+| The next event as a promise | `firstValueFrom(from(observe("event")))`; inside a task `take(ctx, "event")` does the same and respects abort |
+| The events of a bus as an RxJS `Observable` class (for `instanceof` or `pipe` as a method) | `new Observable((subscriber) => observe("event").subscribe(subscriber))` |
+| A task's abort as a stream | `fromEvent(ctx.signal, "abort")`, for `takeUntil` |
+| The latest value to new subscribers | `from(observe("event")).pipe(shareReplay(1))`; the Observable replays nothing by itself |
+
+Events that fired before `subscribe` are lost: the Observable is hot, like `bus.on`. Add `startWith(initial)` or `shareReplay` when a late subscriber needs a value.
+
+## End the subscription
+
+A subscription from `observe` is not tied to a task. Nothing ends it for you. Pick one:
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { fromEvent, from } from "rxjs";
+import { takeUntil } from "rxjs/operators";
+import { onAbort } from "nanoeffects/effects";
+
+bus.on("screen-opened", (_, ctx) => {
+  // takeUntil: stop the stream when the task aborts
+  from(observe("typed"))
+    .pipe(takeUntil(fromEvent(ctx.signal, "abort")))
+    .subscribe((query) => bus.emit("search", query));
+
+  // or: onAbort calls unsubscribe for you
+  const subscription = observe("scrolled").subscribe(updatePosition);
+  onAbort(ctx, subscription.unsubscribe);
+});
+```
+
+Outside a task, call `subscription.unsubscribe()` yourself when the screen goes away, or use the signal of a module.
+
+## Know the limits
+
+- The stream never completes and never fails: events are the only thing that arrives. An error thrown by your subscriber is yours; the bus handles it only if `onError` is set ([Errors](errors.md)).
+- `observe` reads the bus when you call `subscribe`, not when you create it. Create it once, call it as often as needed.
+- Operators that keep state (`scan`, `buffer`, `window`) live in RxJS. The bus keeps no values. For the full split of work see [Use nanoeffects next to RxJS](migrating-from-rxjs.md).

package/docs/package.md

@@ -9,6 +9,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
 | `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
 | `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` |
 | `nanoeffects/oop` | `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` |
 | `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one command, action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
@@ -21,9 +22,10 @@ The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists
 
 ## Give the docs to an AI assistant
 
-The package ships two plain-text files for assistants that write code with it:
+The package ships plain-text files for assistants that write code with it:
 
 - `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
 - `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+- `skills/nanoeffects/SKILL.md`: a skill for assistants that support skills (for example Claude Code). It says when to suggest nanoeffects, when not to, and the same rules. Copy the folder to `.claude/skills/` in your project or to `~/.claude/skills/`.
 
-Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. All match the installed version.

package/docs/plugins.md

@@ -92,6 +92,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-command-its-own-fields-scopeplugin) | Its own fields for one command, action, job or module, and a way to replace them in one `emit`. | `nanoeffects/scope` | The same bus |
+| [`signalPlugin`](#tie-an-emit-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
 | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) | `on` that listens to a group of events which a function picks. | `nanoeffects/match` | The same bus, typed with the new overloads |
 | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) | A callback that emits an action, to give to a state manager. | `nanoeffects/actions` | The same bus, with `emitter` |
 | [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) | A React hook that emits when a value of a component changes. | `nanoeffects/react` | The same bus, with `useEmitter` |
@@ -118,6 +119,25 @@ const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
 bus.emit(getUser("1"), { api: fakeApi }); // a fake api for this call only
 ```
 
+### Tie an emit to an outside signal: `signalPlugin`
+
+A library such as React Query owns the request and gives you an `AbortSignal`. `emit` takes it as `{ signal }` and aborts the tasks it starts when the signal aborts, so `timeout`, `retry` and the request stop too. More in [Use nanoeffects with React Query and SWR](query-libraries.md).
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — emit takes { signal } for a command, a job or an action
+const bus = createBus().use(signalPlugin());
+
+const getUser = createCommand("user/get", (id, { signal }) => api.getUser(id, { signal }));
+
+const controller = new AbortController();
+bus.emit(getUser("1"), { signal: controller.signal }); // runs the command
+controller.abort(); // ctx.signal of the handler aborts with it
+```
+
 ### Listen to a group of events: `matchPlugin`
 
 `on`, `once` and `off` take a function that picks the events, such as every `user/*` event. A type guard narrows the payload. The subscription listens to every event, so for a few known events `on(creator, handler)` is cheaper. More in the [Guide](guide.md#pick-events-with-a-function).

package/docs/policies.md

@@ -114,3 +114,36 @@ Every call returns a promise with the result of its own run. An error rejects on
 - A waiting call whose task aborts is skipped and resolves with `undefined`.
 - When a running call aborts, its slot is freed at once and its result is dropped.
 - Pass `signal` into what `fn` does. A `fn` that ignores it can overlap with the next run.
+
+## Use a policy without 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.
+
+**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.
+
+`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.
+
+```js
+import { debounce, withPolicy } from "nanoeffects/policies";
+
+// debounce — waits for 300 ms of quiet, then runs the callback
+const policy = debounce(300, async (query, { signal }) => {
+  await api.search(query, { signal });
+});
+
+// withPolicy — a plain function: no bus, no context argument
+const onChange = withPolicy(policy);
+
+onChange("re");
+onChange("redux"); // only this call runs, 300 ms after it
+
+// cancel — drops a pending call and aborts a running one
+onChange.cancel();
+```
+
+- The callback has the same `(payload, ctx)` shape as for a bus. `ctx.signal`, `ctx.abort` and `ctx.run` work. `ctx.emit` and `ctx.on` do nothing, because there is no bus.
+- Every call returns a promise with the result. A call the policy drops resolves with `undefined`.
+- `cancel()` aborts every call that has not finished. Calls made after it work again.
+- Where `Symbol.dispose` exists, `using onChange = withPolicy(policy)` calls `cancel()` at the end of the scope.
+
+In a React component, use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) instead: it keeps the function between renders.

package/docs/prevent-double-submit.md

@@ -0,0 +1,128 @@
+# Prevent a double submit
+
+Read this page if a second click on "Pay", "Sign up" or "Save" sends the request twice. It shows how to ignore the second click while the first request runs, how to do it per item, and when to queue the calls instead.
+
+## See the problem
+
+A user clicks twice. Both clicks run the handler, and the server gets two requests.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "submitted" starts its own request.
+bus.on("submitted", async (form) => {
+  const order = await api.pay(form);
+  bus.emit("paid", order);
+});
+```
+
+A `disabled` button helps only until the next render. A flag in a variable (`if (busy) return`) must be reset on every error path and after an abort.
+
+## Ignore clicks while a request runs
+
+Wrap the handler in `leading`. While one run is going, new calls are dropped. When the run ends, the next click works.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// leading: a call is dropped while a previous run is still going
+bus.on(
+  "submitted",
+  leading(async (form, ctx) => {
+    const order = await api.pay(form, { signal: ctx.signal });
+    ctx.emit("paid", order);
+  }),
+);
+```
+
+What to replace: `api.pay` is your own request function.
+
+Result: `emit("submitted", form)` twice in a row sends one request. The second call returns at once and does nothing.
+
+`leading` frees its lock when the task ends or aborts. If the handler throws, the next click works again, with no flag to reset.
+
+## Allow one run per item
+
+A list of rows, each with its own "Delete" button, should not block the whole list. Give each item its own state with `key`.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// leading with key: one running call per row id, other rows are not blocked
+bus.on(
+  "row/deleted",
+  leading(
+    async (row, ctx) => {
+      await api.deleteRow(row.id, { signal: ctx.signal });
+      ctx.emit("row/removed", row.id);
+    },
+    { key: (row) => row.id },
+  ),
+);
+```
+
+## Retry only when the network failed
+
+A retry after a failed payment can charge twice if the server did run the first request. Retry only on errors where the request did not reach the server, and make the server accept an idempotency key.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+import { retry } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// fetch rejects with a TypeError when the network fails; an HTTP error is a plain Error
+const isNetworkError = (error) => error instanceof TypeError;
+
+bus.on(
+  "submitted",
+  leading(async (form, ctx) => {
+    const pay = () => api.pay(form, { signal: ctx.signal });
+    // retry: up to 3 tries, 500 ms apart, only when the network failed
+    const order = await retry(ctx, pay, { times: 3, delay: 500, shouldRetry: isNetworkError });
+    ctx.emit("paid", order);
+  }),
+);
+```
+
+Backoff between tries: [Back off between retries](effects.md#back-off-between-retries).
+
+## Guard a handler when you have no bus
+
+`withPolicy` turns a policy into a plain function, so a click handler needs no bus.
+
+```js
+import { leading, withPolicy } from "nanoeffects/policies";
+
+// leading: ignore new calls while a run is going
+const policy = leading(async (form, { signal }) => {
+  await api.save(form, { signal });
+});
+
+// withPolicy: a plain function to call from onSubmit
+const submit = withPolicy(policy);
+
+submit({ name: "Ada" }); // runs
+submit({ name: "Ada" }); // ignored while the first runs; resolves with undefined
+```
+
+In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders).
+
+## Pick another policy when clicks must not be lost
+
+| You want | Policy |
+| -------- | ------ |
+| Ignore a second click while the first runs (pay, sign up) | `leading` |
+| Run every click, one after another (save a draft, upload files) | `queue` |
+| Keep only the newest click and cancel the older (filters, tabs) | `latest` |
+
+Related: [Policies](policies.md), [Build a sign-up form in React](react.md).

package/docs/query-libraries.md

@@ -0,0 +1,124 @@
+# Use nanoeffects with React Query and SWR
+
+Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one command that both libraries call.
+
+You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
+
+## Decide who owns what
+
+The libraries and nanoeffects do different jobs, so each keeps its own.
+
+| React Query or SWR | nanoeffects |
+| ------------------ | ----------- |
+| `isLoading`, `data`, `error` | `retry`, `timeout`, `latest` and other policies |
+| the cache, one request for the same key | the abort that reaches the request |
+| refetch on focus, on reconnect, on interval | the handler: the same code for a test, a worker and the UI |
+
+`isLoading` and `data` come from the library, not from `emit`. `await bus.emit(...)` resolves once, with the result, so it cannot report that the request is still running.
+
+## Make the command
+
+A command is the request itself. It lives in files that know nothing about React: the bus, the command with its handler, and the component.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// createBus — the bus the app shares
+// signalPlugin — lets emit take { signal }, the signal of the library
+export const bus = createBus().use(signalPlugin());
+```
+
+The handler tries the request up to three times and gives up after five seconds for each try. `ctx.signal` is the signal of the task: it aborts when the library aborts the request.
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+import { retry, timeout } from "nanoeffects/effects";
+
+// createCommand — a command with a handler: emit returns what the handler returns
+export const getUser = createCommand("user/get", async (id, ctx) => {
+  // one try: the request, with the signal of timeout so it can stop it
+  const load = ({ signal }) => api.getUser(id, { signal });
+  // timeout — fail the try after 5 s
+  const attempt = () => timeout(ctx, 5000, load);
+  // retry — up to 3 tries, 500 ms apart
+  return retry(ctx, attempt, { times: 3, delay: 500 });
+});
+```
+
+## Call it from React Query
+
+<!-- docs-check: continue -->
+
+React Query gives `queryFn` a `signal` and aborts it when the query becomes inactive or out of date. Pass it to `emit`. The task is aborted with it, so `timeout` and `retry` stop, and so does the request.
+
+```jsx
+// Profile.jsx
+import { useQuery } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export function Profile({ id }) {
+  const { isLoading, data, error } = useQuery({
+    queryKey: ["user", id],
+    // emit — runs the command; { signal } ties its task to the signal of React Query
+    queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
+  });
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>{data.name}</p>;
+}
+```
+
+The command rejects when all tries fail, so React Query shows the `error`. React Query counts its own `retry` too: set `retry: false` in `useQuery` when the handler already retries, or the tries multiply.
+
+## Call it from SWR
+
+<!-- docs-check: continue -->
+
+SWR does not pass a signal to the fetcher, so there is nothing to give to `emit`. The command still brings `retry` and `timeout`.
+
+```jsx
+// Profile.jsx
+import useSWR from "swr";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+// the fetcher gets the key (here the id) and returns a promise
+const fetcher = (id) => bus.emit(getUser(id));
+
+export function Profile({ id }) {
+  const { isLoading, data, error } = useSWR(id, fetcher);
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>{data.name}</p>;
+}
+```
+
+## Let the bus know the result
+
+<!-- docs-check: continue -->
+
+A command gives its result only to the caller. If a store or another module must react to a loaded user, the handler can say so:
+
+```js
+// user-events.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — an event with a payload
+export const userLoaded = createAction("user/loaded");
+```
+
+Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the command with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job).
+
+## Know the limits
+
+- **Without the plugin, `{ signal }` is ignored.** The command runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
+- **Only the call forms take it.** `bus.emit(getUser(id), { signal })` works; `bus.emit("user/get", id, { signal })` does not.
+- **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Commands that fetch are async, so this only matters for a sync handler that sets up a callback.
+- **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
+- **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.

package/docs/react.md

@@ -162,8 +162,52 @@ const checkName = latest(async (name, ctx) => {
 
 In the component, add `bus.emit("form/closed")` to the cleanup function of the effect. This is optional: skip it when finishing a request after unmount does no harm, as for a cheap check.
 
+## Keep a debounced handler between renders
+
+**Problem.** A component runs again on every render. A policy made in its body, such as `debounce(300, search)`, is made again each time and loses its timer. A policy made once keeps the callback of the first render, which reads old props and state.
+
+**When.** A handler in a component needs a policy, and you do not need a bus: a search box, an autosave, a submit that must not fire twice.
+
+`usePolicy(callback, make, deps)` keeps one function between renders. It calls the `callback` of the latest render, so an inline callback sees fresh state. It cancels pending calls when the component unmounts.
+
+```jsx
+import { useState } from "react";
+import { debounce } from "nanoeffects/policies";
+import { usePolicy } from "nanoeffects/react";
+
+export const Search = ({ wait }) => {
+  const [items, setItems] = useState([]);
+
+  // usePolicy — a stable function; the first argument is the latest render's callback
+  const onChange = usePolicy(
+    async (query, { signal }) => {
+      const found = await api.search(query, { signal });
+      setItems(found);
+    },
+    // the second argument builds the policy once; task runs the callback above
+    (task) => debounce(wait, task),
+    // deps — list what the second argument reads; a new wait makes a new policy
+    [wait],
+  );
+
+  return (
+    <div>
+      <input onChange={(event) => onChange(event.target.value)} />
+      <p>{items.length} found</p>
+    </div>
+  );
+};
+```
+
+- `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
+- A pending call is cancelled on unmount and when `deps` change.
+- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+
 ## Where to go next
 
 - The policies behind this form: [Policies](policies.md).
+- A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 - `retry`, `timeout` and the other effects: [Effects](effects.md).
 - A state library instead of `useState`: [Stores](stores.md).
+- React Query or SWR instead of your own state: [Use nanoeffects with React Query and SWR](query-libraries.md).