nanoeffects 0.8.0 → 0.10.0

package/llms-full.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; needs React), `nanoeffects/trace`, `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; `usePolicy`; needs React), `nanoeffects/trace`, `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ---
@@ -234,7 +234,7 @@ const searchLatest = latest(async (query, { signal }) => {
 bus.on("search", debounce(300, searchLatest));
 ```
 
-Full options: [Policies](policies.md).
+Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 
 ## 5. Add retry and timeout
 
@@ -500,6 +500,51 @@ More in [Errors](errors.md).
 | Guarantees | [Semantics](semantics.md) |
 | Which import | [Package entries](package.md) |
 
+---
+Source: docs/motivation.md
+
+# Why nanoeffects exists
+
+Read this page if you build an SDK, a core library or a micro-frontend shell and wonder why you would pick a new event bus. It explains the constraints the library was made for. It does not teach the API: start with the [Guide](guide.md).
+
+## The problem: a shared dependency is a shared risk
+
+A shared library (an SDK, a core package, a platform shell) is loaded by many apps. Whatever it depends on, the apps depend on too. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other.
+
+Module Federation makes this visible. Each remote can bring its own copy unless every team agrees on a `singleton` and a version range. The [Nx guide on library versions](https://nx.dev/docs/kb/manage-library-versions-with-module-federation) lists the result: libraries with internal state conflict, and a missing method in one version breaks callers written for another.
+
+Real cases from the libraries nanoeffects was compared with:
+
+| Library | What goes wrong | Source |
+| ------- | --------------- | ------ |
+| Redux, React Redux | A shared component library uses `react-redux`. Every micro-frontend must use the same version of that library, or `react-redux` "breaks weirdly". | [react-redux#1949](https://github.com/reduxjs/react-redux/issues/1949) |
+| Redux | A store is reachable only under a `Provider`. Each sub-app needs its own provider, and a second one must not be created when a module is injected. Reducers duplicated between the host and a module add to it. | [Redux on Module Federation](https://dev.to/manomano-tech-team/how-to-work-with-redux-on-module-federation-13gm) |
+| Effector | A library that uses `effector-react/scope` and is bundled into another project gets two instances. Its `Provider` is not seen by `useStore` of the app: "no scope found". | [effector#727](https://github.com/effector/effector/issues/727) |
+| RxJS | Two copies give two `Observable` classes. Types of one version do not fit the other, and operators added to one copy are missing on the other. The advice is "one version in `node_modules`". | [RxJS#2984](https://github.com/ReactiveX/rxjs/issues/2984), [neo4j-javascript-driver#978](https://github.com/neo4j/neo4j-javascript-driver/issues/978) |
+
+A library that is **not** a shared singleton cannot break this way. nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
+
+## Why not the alternatives
+
+| Option | Why it did not fit |
+| ------ | ------------------ |
+| Redux (with sagas) | A store and a provider shared by every consumer, which is the risk above. `redux-saga` also has no cheap way to get an answer back from an event: effects talk through the store. |
+| Effector | A graph with global identity. A version or scope mismatch between the SDK and the app reaches the whole infrastructure. |
+| Zustand | Good state, but it is a store, not a way to run and cancel work. It is the natural place to hold state next to nanoeffects: see [Stores](stores.md). |
+| RxJS | Flexible, but learning its ecosystem (operators, subjects, schedulers) is a high entry cost for every developer who touches the SDK. The package is also not small: [Bundlephobia](https://bundlephobia.com/package/rxjs) reports 17.3 kB minified and gzipped for 7.8.2. |
+
+## What the library does instead
+
+- **No dependencies, no global state.** It is safe to ship inside an SDK next to whatever the host app runs. It does not need a `singleton` entry in the Module Federation config.
+- **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and commands are separate entries you import only when you need them. See [Package entries](package.md).
+- **Simple first.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
+- **`emit` can return an answer.** A [command](actions.md) is an event whose handler returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
+- **Easy to debug.** Event-driven code is hard to follow: you see an effect and not the event that caused it. Every task knows its parent, so [tracing](tracing.md) shows the chain of events, with loggers for the console, the Performance panel and Redux DevTools.
+
+## When this is not the right tool
+
+nanoeffects holds no state. If you need a store, keep Redux, Zustand or Effector and let the bus run the async work: [Stores](stores.md). If you already have streams everywhere, keep RxJS: [Use nanoeffects next to RxJS](migrating-from-rxjs.md).
+
 ---
 Source: docs/package.md
 
@@ -514,6 +559,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` |
@@ -526,12 +572,13 @@ The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists
 
 ## Give the docs to an AI assistant
 
-The package ships two plain-text files for assistants that write code with it:
+The package ships plain-text files for assistants that write code with it:
 
 - `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
 - `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+- `skills/nanoeffects/SKILL.md`: a skill for assistants that support skills (for example Claude Code). It says when to suggest nanoeffects, when not to, and the same rules. Copy the folder to `.claude/skills/` in your project or to `~/.claude/skills/`.
 
-Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. All match the installed version.
 
 ---
 Source: docs/plugins.md
@@ -630,6 +677,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` |
@@ -656,6 +704,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).
@@ -935,11 +1002,401 @@ A dropped call resolves with `undefined`. `queue(fn, { limit: 1, overflow: "drop
 
 Every call returns a promise with the result of its own run. An error rejects only that call; the queue continues.
 
-**Abort:**
+**Abort:**
+
+- 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.
+
+---
+Source: docs/cancel-stale-requests.md
+
+# Cancel stale requests and fix race conditions
+
+Read this page if an older response can overwrite a newer one: a search box that shows the results of the previous query, a filter that flickers, a form that submits twice. It shows the cause, the fix with `latest`, and how to add a pause, a retry and a timeout. It needs only the bus from the [README](../README.md).
+
+## See the problem
+
+A user types `ab`, then `abc`. Two requests start. If the one for `ab` is slower, it finishes last and its results replace the right ones.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "search" starts its own request, and the slowest one wins.
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+```
+
+Checking a counter by hand (`if (id !== lastId) return`) hides the old result, but the old request still runs. Calling `controller.abort()` by hand works, but you must keep the controller somewhere and abort it before each new call.
+
+## Keep only the latest request
+
+Wrap the handler in `latest`. A new `"search"` aborts the task of the previous one, and an aborted task delivers no result.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal: pass it on so the browser cancels the request, not only drops the result
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+
+bus.on("results", (items) => render(items));
+```
+
+What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. Without it, `latest` still ignores the old result, but the request keeps running.
+
+Result: `emit("search", "ab")` followed by `emit("search", "abc")` shows only the results for `abc`, and the request for `ab` is cancelled.
+
+## Wait for a pause in typing
+
+Add `debounce` outside `latest`. The search starts after 300 ms without a new keystroke.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+```
+
+## Retry a failed request and limit its time
+
+Use `retry` and `timeout` around the request. The pause grows with each attempt.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { backoff, retry, timeout } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// timeout: abort one attempt after 5 s
+const searchOnce = timeout(5000, (query, { signal }) => api.search(query, { signal }));
+
+// retry: up to 4 attempts, backoff makes the pause longer each time
+const searchWithRetry = retry(searchOnce, {
+  times: 4,
+  delay: backoff({ base: 200, max: 5000, jitter: true }),
+});
+
+// latest: a newer search aborts the whole retry chain
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await ctx.run(searchWithRetry, query); // ctx.run: a child task, aborted with this one
+    ctx.emit("results", items);
+  }),
+);
+```
+
+## Pick another policy for another race
+
+| Situation | Policy |
+| --------- | ------ |
+| Only the newest result matters (search, filter, tab switch) | `latest` |
+| A second click while the first call runs must be ignored (submit, pay) | `leading` |
+| Every call must run, one after another (save, upload) | `queue` |
+| Calls come in bursts and you want one at the end | `debounce` |
+| Calls come in bursts and you want one per period | `throttle` |
+| Each user or item has its own race | add `{ key }`, for example `latest(handler, { key })` |
+
+All policies and their options: [Policies](policies.md). The same step by step in a form: [Build a sign-up form in React](react.md).
+
+---
+Source: docs/debounce-and-abort.md
+
+# Debounce a request and abort the previous one
+
+Read this page if you debounce user input (a search box, an autosave, a resize handler) and you also want the request in flight to stop when a new one starts. `debounce` alone waits for a pause. It does not cancel a request that already started. This page shows the two policies together, the order to put them in, and when to use `throttle` instead.
+
+## Know what each policy does
+
+| Policy | What it does | What it does not do |
+| ------ | ------------ | ------------------- |
+| `debounce(ms, fn)` | runs `fn` after `ms` without a new call | does not cancel a run that already started |
+| `latest(fn)` | aborts the previous run when a new one starts | does not wait for a pause |
+
+Use both for a search box. `debounce` sends fewer requests. `latest` cancels the slow one when the user types again after the pause.
+
+## Combine them
+
+Put `debounce` outside and `latest` inside. The event waits for a pause first. When the run starts, it aborts the previous run.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer run aborts the older request
+const searchLatest = latest(async (query, { signal }) => {
+  // signal: pass it on so the browser cancels the request itself
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run searchLatest after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+
+bus.on("results", (items) => render(items));
+```
+
+What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. `render` shows the items.
+
+Result: typing `a`, `ab`, `abc` within 300 ms sends one request for `abc`. If the user types `abcd` while that request runs, the request for `abc` is aborted and one for `abcd` starts after the pause.
+
+## Run the first call at once
+
+By default `debounce` waits even before the first call. For an input where the first key press should react at once, add `leading: true`. The first call of a burst runs immediately, and the last one runs after the pause.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const showSuggestions = (query) => console.log("suggest", query);
+
+// debounce with leading: the first call runs at once, the last one after 300 ms of quiet
+bus.on("typed", debounce(300, showSuggestions, { leading: true }));
+```
+
+`leading` and `trailing` follow lodash. All combinations: [Policies](policies.md#configure-debounce-and-throttle).
+
+## Use throttle for continuous input
+
+`debounce` never runs while calls keep coming. For a scroll or a drag you want updates during the movement. Use `throttle`: at most one run per period.
+
+```js
+import { createBus } from "nanoeffects";
+import { throttle } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const saveScroll = (position) => localStorage.setItem("scroll", String(position));
+
+// throttle: at most one run per 100 ms while "scrolled" keeps coming
+bus.on("scrolled", throttle(100, saveScroll));
+```
+
+## Debounce without a bus
+
+If the page has no bus, wrap the same pair with `withPolicy`. The result is a plain function that you call from an input handler.
+
+```js
+import { debounce, latest, withPolicy } from "nanoeffects/policies";
+
+// latest: a newer run aborts the older request
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  console.log(items);
+});
+
+// withPolicy: debounce by 300 ms, called as a plain function
+const onTyped = withPolicy(debounce(300, searchLatest));
+
+onTyped("a");
+onTyped("ab"); // only "ab" runs, 300 ms later
+
+// cancel: drop a pending call and abort a running request, for example on page leave
+onTyped.cancel();
+```
+
+In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders), which also cancels on unmount.
+
+## Check these when it does not cancel
+
+- The request did not get `signal`. `latest` then drops the old result but the request goes on.
+- The order is reversed. Write `debounce(300, latest(handler))`, as above, so `debounce` receives the events and `latest` guards the request.
+- Several inputs share one event. Give each its own event name, or use `{ key }`, for example `latest(handler, { key: (input) => input.id })`.
+
+Related: [Cancel stale requests](cancel-stale-requests.md), [Policies](policies.md).
+
+---
+Source: docs/prevent-double-submit.md
+
+# Prevent a double submit
+
+Read this page if a second click on "Pay", "Sign up" or "Save" sends the request twice. It shows how to ignore the second click while the first request runs, how to do it per item, and when to queue the calls instead.
+
+## See the problem
+
+A user clicks twice. Both clicks run the handler, and the server gets two requests.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// Without a policy every "submitted" starts its own request.
+bus.on("submitted", async (form) => {
+  const order = await api.pay(form);
+  bus.emit("paid", order);
+});
+```
+
+A `disabled` button helps only until the next render. A flag in a variable (`if (busy) return`) must be reset on every error path and after an abort.
+
+## Ignore clicks while a request runs
+
+Wrap the handler in `leading`. While one run is going, new calls are dropped. When the run ends, the next click works.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// leading: a call is dropped while a previous run is still going
+bus.on(
+  "submitted",
+  leading(async (form, ctx) => {
+    const order = await api.pay(form, { signal: ctx.signal });
+    ctx.emit("paid", order);
+  }),
+);
+```
+
+What to replace: `api.pay` is your own request function.
+
+Result: `emit("submitted", form)` twice in a row sends one request. The second call returns at once and does nothing.
+
+`leading` frees its lock when the task ends or aborts. If the handler throws, the next click works again, with no flag to reset.
+
+## Allow one run per item
+
+A list of rows, each with its own "Delete" button, should not block the whole list. Give each item its own state with `key`.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// leading with key: one running call per row id, other rows are not blocked
+bus.on(
+  "row/deleted",
+  leading(
+    async (row, ctx) => {
+      await api.deleteRow(row.id, { signal: ctx.signal });
+      ctx.emit("row/removed", row.id);
+    },
+    { key: (row) => row.id },
+  ),
+);
+```
+
+## Retry only when the network failed
+
+A retry after a failed payment can charge twice if the server did run the first request. Retry only on errors where the request did not reach the server, and make the server accept an idempotency key.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+import { retry } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+// fetch rejects with a TypeError when the network fails; an HTTP error is a plain Error
+const isNetworkError = (error) => error instanceof TypeError;
+
+bus.on(
+  "submitted",
+  leading(async (form, ctx) => {
+    const pay = () => api.pay(form, { signal: ctx.signal });
+    // retry: up to 3 tries, 500 ms apart, only when the network failed
+    const order = await retry(ctx, pay, { times: 3, delay: 500, shouldRetry: isNetworkError });
+    ctx.emit("paid", order);
+  }),
+);
+```
+
+Backoff between tries: [Back off between retries](effects.md#back-off-between-retries).
+
+## Guard a handler when you have no bus
+
+`withPolicy` turns a policy into a plain function, so a click handler needs no bus.
+
+```js
+import { leading, withPolicy } from "nanoeffects/policies";
+
+// leading: ignore new calls while a run is going
+const policy = leading(async (form, { signal }) => {
+  await api.save(form, { signal });
+});
+
+// withPolicy: a plain function to call from onSubmit
+const submit = withPolicy(policy);
+
+submit({ name: "Ada" }); // runs
+submit({ name: "Ada" }); // ignored while the first runs; resolves with undefined
+```
+
+In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders).
+
+## Pick another policy when clicks must not be lost
+
+| You want | Policy |
+| -------- | ------ |
+| Ignore a second click while the first runs (pay, sign up) | `leading` |
+| Run every click, one after another (save a draft, upload files) | `queue` |
+| Keep only the newest click and cancel the older (filters, tabs) | `latest` |
 
-- 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.
+Related: [Policies](policies.md), [Build a sign-up form in React](react.md).
 
 ---
 Source: docs/effects.md
@@ -1394,15 +1851,91 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 
 ### Jobs
 
-`createJob(type, handler, { success, fail })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.success` and `loadUser.fail` on it.
+`createJob(type, handler, { pending, success, fail, cancel })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
 
+- When the handler starts, emits `loadUser.pending(payload)`.
 - On success, emits `loadUser.success(result)`.
 - On failure, emits `loadUser.fail(error)`.
-- `success` / `fail` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/success` or `<type>/fail`.
+- When the task is aborted before the handler settles, emits `loadUser.cancel(reason)` instead of `success` or `fail`. After `pending`, exactly one of the three follows.
+- `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
 - `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
-- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). Nothing is sent after abort.
-- A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
+- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
+- A missing handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent.
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+- The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
+
+## Show a loading state with a job
+
+**Problem.** A spinner needs a flag that is `true` while a request runs. Setting it by hand in the handler (`loading = true`, then `try` / `finally`) breaks when the task is aborted: `ctx.emit` does nothing after an abort, so a flag that is cleared through the bus stays `true`.
+
+**When.** The UI shows a loading state for a request, and the request can be aborted (a page is left, `ctx.abort()` is called). Skip it when nothing shows the state.
+
+A job sends one action when the handler starts and one when it ends, whatever way it ends. A store sets the flag on `pending` and clears it on `success`, `fail` and `cancel`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the app shares
+export const bus = createBus();
+```
+
+```js
+// user.js
+import { createJob } from "nanoeffects/actions";
+
+// createJob — a command that also sends pending, success, fail and cancel
+export const loadUser = createJob("user/load", fetchUser);
+```
+
+```js
+// user-store.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+export const state = { loading: false, user: null };
+
+// pending — the handler starts: show the spinner
+bus.on(loadUser.pending, () => {
+  state.loading = true;
+});
+
+// success — the handler returned a user
+bus.on(loadUser.success, (user) => {
+  state.loading = false;
+  state.user = user;
+});
+
+// fail — the handler threw
+bus.on(loadUser.fail, () => {
+  state.loading = false;
+});
+
+// cancel — the task was aborted: the only way to clear the flag then
+bus.on(loadUser.cancel, () => {
+  state.loading = false;
+});
+```
+
+```js
+// page.js
+import { bus } from "./bus";
+import { loadUser } from "./user";
+
+// emit — runs the job; state.loading is true as soon as it returns
+bus.emit(loadUser("1"));
+```
+
+`cancel` is sent at the moment of the abort, with the abort reason. A handler that ignores the signal and finishes later sends nothing more, so the flag is already `false`.
+
+**With a policy.** A policy such as `latest`, `leading`, `debounce`, `throttle` or `queue` around the handler tells the job what it does with each call:
+
+- `pending` is sent when the handler really starts: at once for `leading`, after the wait for `debounce`, when its turn comes for `queue`.
+- A call that the policy drops before it starts sends nothing, not even `pending`. A second click that `leading` ignores does not clear the flag of the first.
+- A run that `latest` replaces sends `cancel` before the next call sends `pending`.
+- Every `pending` is followed by exactly one of `success`, `fail` and `cancel`, and nothing is sent without `pending`.
+
+A flag is exact when calls do not overlap, or when `latest` replaces them. If several runs can go at once (`queue` with `concurrency` above 1, or a job without a policy called many times), keep a counter: add one on `pending` and take one off on `success`, `fail` and `cancel`. A policy that you write yourself, or that you hide in your own function, does not report to the job; `pending` is then sent at the call, as for a job with no policy.
 
 ## Mount domains with modules
 
@@ -2174,6 +2707,134 @@ The stores above call back only when the value changed, so the emitter does not
 
 A handler gets the store from `ctx.store` and calls a mutation, whatever it handles: not only the result of a search. The same rule holds: write the field you do not watch. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.
 
+---
+Source: docs/query-libraries.md
+
+# Use nanoeffects with React Query and SWR
+
+Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one command that both libraries call.
+
+You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
+
+## Decide who owns what
+
+The libraries and nanoeffects do different jobs, so each keeps its own.
+
+| React Query or SWR | nanoeffects |
+| ------------------ | ----------- |
+| `isLoading`, `data`, `error` | `retry`, `timeout`, `latest` and other policies |
+| the cache, one request for the same key | the abort that reaches the request |
+| refetch on focus, on reconnect, on interval | the handler: the same code for a test, a worker and the UI |
+
+`isLoading` and `data` come from the library, not from `emit`. `await bus.emit(...)` resolves once, with the result, so it cannot report that the request is still running.
+
+## Make the command
+
+A command is the request itself. It lives in files that know nothing about React: the bus, the command with its handler, and the component.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// createBus — the bus the app shares
+// signalPlugin — lets emit take { signal }, the signal of the library
+export const bus = createBus().use(signalPlugin());
+```
+
+The handler tries the request up to three times and gives up after five seconds for each try. `ctx.signal` is the signal of the task: it aborts when the library aborts the request.
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+import { retry, timeout } from "nanoeffects/effects";
+
+// createCommand — a command with a handler: emit returns what the handler returns
+export const getUser = createCommand("user/get", async (id, ctx) => {
+  // one try: the request, with the signal of timeout so it can stop it
+  const load = ({ signal }) => api.getUser(id, { signal });
+  // timeout — fail the try after 5 s
+  const attempt = () => timeout(ctx, 5000, load);
+  // retry — up to 3 tries, 500 ms apart
+  return retry(ctx, attempt, { times: 3, delay: 500 });
+});
+```
+
+## Call it from React Query
+
+<!-- docs-check: continue -->
+
+React Query gives `queryFn` a `signal` and aborts it when the query becomes inactive or out of date. Pass it to `emit`. The task is aborted with it, so `timeout` and `retry` stop, and so does the request.
+
+```jsx
+// Profile.jsx
+import { useQuery } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export function Profile({ id }) {
+  const { isLoading, data, error } = useQuery({
+    queryKey: ["user", id],
+    // emit — runs the command; { signal } ties its task to the signal of React Query
+    queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
+  });
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>{data.name}</p>;
+}
+```
+
+The command rejects when all tries fail, so React Query shows the `error`. React Query counts its own `retry` too: set `retry: false` in `useQuery` when the handler already retries, or the tries multiply.
+
+## Call it from SWR
+
+<!-- docs-check: continue -->
+
+SWR does not pass a signal to the fetcher, so there is nothing to give to `emit`. The command still brings `retry` and `timeout`.
+
+```jsx
+// Profile.jsx
+import useSWR from "swr";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+// the fetcher gets the key (here the id) and returns a promise
+const fetcher = (id) => bus.emit(getUser(id));
+
+export function Profile({ id }) {
+  const { isLoading, data, error } = useSWR(id, fetcher);
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>{data.name}</p>;
+}
+```
+
+## Let the bus know the result
+
+<!-- docs-check: continue -->
+
+A command gives its result only to the caller. If a store or another module must react to a loaded user, the handler can say so:
+
+```js
+// user-events.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — an event with a payload
+export const userLoaded = createAction("user/loaded");
+```
+
+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.
+
 ---
 Source: docs/react.md
 
@@ -2341,11 +3002,55 @@ const checkName = latest(async (name, ctx) => {
 
 In the component, add `bus.emit("form/closed")` to the cleanup function of the effect. This is optional: skip it when finishing a request after unmount does no harm, as for a cheap check.
 
+## Keep a debounced handler between renders
+
+**Problem.** A component runs again on every render. A policy made in its body, such as `debounce(300, search)`, is made again each time and loses its timer. A policy made once keeps the callback of the first render, which reads old props and state.
+
+**When.** A handler in a component needs a policy, and you do not need a bus: a search box, an autosave, a submit that must not fire twice.
+
+`usePolicy(callback, make, deps)` keeps one function between renders. It calls the `callback` of the latest render, so an inline callback sees fresh state. It cancels pending calls when the component unmounts.
+
+```jsx
+import { useState } from "react";
+import { debounce } from "nanoeffects/policies";
+import { usePolicy } from "nanoeffects/react";
+
+export const Search = ({ wait }) => {
+  const [items, setItems] = useState([]);
+
+  // usePolicy — a stable function; the first argument is the latest render's callback
+  const onChange = usePolicy(
+    async (query, { signal }) => {
+      const found = await api.search(query, { signal });
+      setItems(found);
+    },
+    // the second argument builds the policy once; task runs the callback above
+    (task) => debounce(wait, task),
+    // deps — list what the second argument reads; a new wait makes a new policy
+    [wait],
+  );
+
+  return (
+    <div>
+      <input onChange={(event) => onChange(event.target.value)} />
+      <p>{items.length} found</p>
+    </div>
+  );
+};
+```
+
+- `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
+- A pending call is cancelled on unmount and when `deps` change.
+- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+
 ## Where to go next
 
 - The policies behind this form: [Policies](policies.md).
+- A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 - `retry`, `timeout` and the other effects: [Effects](effects.md).
 - A state library instead of `useState`: [Stores](stores.md).
+- React Query or SWR instead of your own state: [Use nanoeffects with React Query and SWR](query-libraries.md).
 
 ---
 Source: docs/context.md
@@ -3248,7 +3953,7 @@ nanoeffects has no store. `createStore` can be replaced by any store you like, f
 | event call `loaded(user)` | `bus.emit("loaded", user)` |
 | `createEffect(handler)` | a handler: `bus.on(event, handler)` |
 | effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
-| `effect.pending` | not provided: keep a flag in your store, or read it from [Tracing](tracing.md) |
+| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)) |
 | `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
 | `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
 | `sample({ filter })` | an `if` in the handler |
@@ -3546,13 +4251,114 @@ bus.on(
 ## What is different
 
 - **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
-- **No `pending`.** A running task is visible through [Tracing](tracing.md), not through a store. A flag in your store set at the start and the end of the handler does the job.
+- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)). Policies report to the job, so the flag also follows `latest`, `leading`, `debounce`, `throttle` and `queue`; that section says when to count instead. A running task is also visible through [Tracing](tracing.md).
 - **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
 - **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
 - **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.
 - **The event carries the data.** `sample({ source })` reads a store at the moment of the clock. Here the sender puts the values in the event (`bus.emit("form/submitted", form)`), or the handler reads a store from a [context field](context.md).
 - **Scopes are buses.** `fork()` becomes a `createBus()` per scope (a test, a request on the server).
 
+---
+Source: docs/migrating-from-mitt.md
+
+# Coming from mitt, nanoevents or EventEmitter
+
+Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, Node's `EventEmitter`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
+
+## When to switch
+
+An emitter calls a function and forgets it. That is enough while handlers are synchronous. Switch when handlers start async work and you hit one of these:
+
+- an older request finishes after a newer one and overwrites its result;
+- you keep `AbortController` objects by hand;
+- you write debounce, throttle or retry around handlers yourself;
+- you cannot tell which event started which request.
+
+If handlers stay synchronous, keep your emitter. nanoeffects costs about 1.4 kB gzip (1.3 kB brotli), close to the small emitters.
+
+## Find the equivalent
+
+| mitt / EventEmitter | nanoeffects |
+| ------------------- | ----------- |
+| `emitter.on("a", handler)` | `bus.on("a", handler)` |
+| `emitter.off("a", handler)` | call the function that `bus.on` returned, or `bus.off("a")` for all handlers of `a` |
+| `emitter.emit("a", payload)` | `bus.emit("a", payload)` |
+| `emitter.once("a", handler)` | `bus.once("a", handler)` |
+| `on("*", (type, payload) => …)` | `bus.on("*", (payload, ctx) => …)`: the event name is `ctx.type` (see the [Guide](guide.md)) |
+| `emitter.all.clear()` | `bus.off()` |
+
+Two differences to know:
+
+- `bus.on` returns the unsubscribe function. You do not need to keep the handler to remove it.
+- The handler gets a second argument, the task context: `(payload, ctx)`. You can ignore it until you need `ctx.signal` or `ctx.emit`.
+
+## Move a handler
+
+Before, with `mitt`:
+
+<!-- docs-check: skip - needs mitt, which the project does not depend on -->
+```js
+import mitt from "mitt";
+
+const emitter = mitt();
+
+emitter.on("search", async (query) => {
+  const items = await api.search(query);
+  emitter.emit("results", items);
+});
+
+emitter.emit("search", "abc");
+```
+
+After, with nanoeffects. The first step changes only the import and the constructor:
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+bus.on("search", async (query) => {
+  const items = await api.search(query);
+  bus.emit("results", items);
+});
+
+bus.emit("search", "abc");
+```
+
+The second step fixes the race. Wrap the handler in `latest` and pass the signal to the request:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // event bus; each handler call is a task
+
+// latest: a newer "search" aborts the older run
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal }); // signal cancels the request
+    bus.emit("results", items);
+  }),
+);
+
+bus.emit("search", "abc");
+```
+
+More cases (pause, retry, timeout): [Cancel stale requests](cancel-stale-requests.md).
+
+## Check the differences
+
+| Topic | Emitter | nanoeffects |
+| ----- | ------- | ----------- |
+| Handler order | order of subscription | order of subscription |
+| Error in a handler | depends on the library | the first error stops the rest and is thrown from `emit`; set `onError` to isolate handlers ([Errors](errors.md)) |
+| Async handler rejects | usually an unhandled rejection | not handled without `onError`; set `onError` to catch it |
+| Event without a listener | ignored | ignored; set `onUnhandled` to be told |
+| Types | event map in a type parameter | event map in a type parameter ([TypeScript](typescript.md)) |
+
+The exact rules of `emit`, abort and ordering: [Semantics](semantics.md).
+
 ---
 Source: docs/migrating-from-rxjs.md
 
@@ -3849,28 +4655,142 @@ Source: docs/observable.md
 
 # Turn events into Observables
 
-Use this page only when you already work in Observables / RxJS. Prefer `bus.on` with policies for cancellation and tracing.
+Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
 `createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
 
+## Turn an event into a stream
+
+Problem: a search box emits `typed` on every key. You want to wait for a pause and skip repeats with operators you already know.
+
 <!-- docs-check: skip - needs rxjs, which the project does not depend on -->
 ```js
-import { from } from "rxjs";
-import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";
+import { createBus } from "nanoeffects";
 import { createObserve } from "nanoeffects/observable";
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged } from "rxjs/operators";
 
-const 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).
 
 ---
 Source: docs/hmr.md