nanoeffects 0.28.0 → 0.30.1

package/docs/actions.md

@@ -1,6 +1,23 @@
 # Actions, jobs and modules
 
-Use this page when **domain logic lives on the bus**, off the UI: the UI emits and listens; handlers and modules own the work.
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 6.
+
+When a project has a lot of business logic, you need to split it. One way is to split it by domains, or entities. In a shop, the domains could be products and product categories. Then the code that belongs to the actions of one domain goes into one file (`product.js`), its handlers into another, and the module that mounts them into a third. A domain can then be mounted, replaced or unmounted without touching the others. For the shop the files could look like this:
+
+```text
+src/
+  bus.js
+  product/
+    product.js
+    product-handlers.js
+    product-module.js
+  category/
+    category.js
+    category-handlers.js
+    category-module.js
+```
+
+The examples below show the content of such files.
 
 If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until you need a result from `emit` or a mountable domain.
 
@@ -10,11 +27,37 @@ A chat with two entities and three features, jobs under policies and effects, an
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
-## Return a value from `emit` with a handler
+## Action, job and module
+
+Four forms, one idea each. Take the first row that fits.
+
+| Form | What it is | Use it when |
+| ---- | ---------- | ----------- |
+| `createAction(type)` | An action with no handler: a name and a payload. | The UI or a handler tells that something happened. |
+| `createAction(type, handler)` | An action with a handler: `emit` runs the handler and returns its result. | You want the result of the handler from `emit`. |
+| `createJob(type, handler)` | An action with a handler that returns its result as the actions `success` and `fail`, and also sends `pending` and `cancel`. | You want the result of the work of a handler and, if you need it, to subscribe to the state of that work. |
+| `createModule(name, setup)` | A group of actions and jobs with their handlers, mounted and unmounted with one call. | One domain must start and stop as a unit. |
+
+Start with actions. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
+
+## On this page
+
+- [Action, job and module](#action-job-and-module)
+- [Get the result of `emit`](#get-the-result-of-emit)
+- [Actions, handlers and jobs](#actions-handlers-and-jobs)
+  - [Actions](#actions)
+  - [Bind a handler later](#bind-a-handler-later)
+  - [The result type of a bound handler](#the-result-type-of-a-bound-handler)
+  - [Jobs](#jobs)
+- [The state of a job](#the-state-of-a-job)
+- [Modules](#modules)
+- [Extend the context of actions and modules](#extend-the-context-of-actions-and-modules)
+
+## Get the result of `emit`
 
-Give `createAction` a handler, and `emit` runs it and returns its result. There is one creator for an event and for an action with work behind it; the handler is the only difference.
+When you want an answer from a handler at the `emit` call, give `createAction` the handler. A handler is a function `(payload, ctx) => result` that runs when the action is emitted. `emit` runs it and returns its result. There is one creator for an action with and without a handler; the handler is the only difference.
 
-The bus lives in one file and its events in another, so any module can import both without a cycle.
+The bus lives in one file and its actions in another, so any module can import both without a cycle.
 
 ```js
 // bus.js
@@ -39,7 +82,7 @@ import { double } from "./math";
 bus.emit(double(21)); // 42
 ```
 
-## Describe events, handlers and jobs
+## Actions, handlers and jobs
 
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
@@ -74,7 +117,7 @@ These are the events of the user domain, in a file of their own (`user.js`). The
 - `userLoaded.match(action)` — narrows an action
 - `createAction(type, handler)` — a function as the second argument is the handler; `bus.emit(action(payload))` tells the listeners, runs the handler as a task and returns its result
 - `createAction(type, { prepare })` — build the payload from several arguments
-- `createAction(type, { handle, prepare, ...scope })` — everything in one object: `handle` and `prepare` are taken out, and every other field is the [scope](scope.md)
+- `createAction(type, { handle, prepare, ...scope })` — everything in one object: `handle` and `prepare` are taken out, and every other field is the [scope](context.md#scope-fields-for-an-action-a-module-and-a-call)
 - Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
 
 A scope goes after a handler as the last argument, `createAction(type, handler, scope)`; `prepare` with a handler goes in that last object: `createAction(type, handler, { prepare, ...scope })`.
@@ -124,7 +167,7 @@ A handler bound in the registry makes `bus.emit(sendMail(mail))` run it and retu
 
 The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the handler that the action carries. `bus.use(actionsPlugin())` sets `bus.actions`. A second `actionsPlugin` binds its list in that registry and returns it. There is no `actions` option in `createBus`; assign a custom runner with `bus.actions = { run }`, and add `bound(type)` to it to answer for actions that have no handler of their own.
 
-### Say what a bound handler returns
+### The result type of a bound handler
 
 TypeScript cannot see which handler the registry has, so the type of `emit` for an action without a handler is `void`. Tell it what the bound handler returns with `Call<Payload, Result>`. This is a promise of yours: nothing checks it against the handler.
 
@@ -164,11 +207,11 @@ On a bus without an event map you can say it where you call: `const id = bus.emi
 - `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
 - `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, give `createAction` the handler.
 - Outcome actions are emitted as the task that ran the job (also for a handler bound with `actions.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
-- A job without a handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent. An action without a handler is an event and does not throw.
+- A job without a handler is not an outcome: `emit` throws `No handler for action "..."` and nothing is sent. An action without a handler is an event and does not throw.
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
 - The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
 
-## Show a loading state with a job
+## The state of 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`.
 
@@ -241,7 +284,7 @@ bus.emit(loadUser("1"));
 
 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
+## Modules
 
 **Problem.** A domain needs several subscriptions and handler bindings. With plain `bus.on` / `actions.handle` you must remember every unsubscribe.
 
@@ -334,9 +377,9 @@ If the `setup` of one module throws, the modules of that call that were already
   - `spawn` — background task, aborted on unmount.
 - An action that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.
 
-## Give an action or a module its own fields
+## Extend the context of actions and modules
 
-An action with a handler can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createAction`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
+An action with a handler can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
 // bus.js
@@ -368,4 +411,4 @@ const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
 bus.emit(getUser("1"), { api: fakeApi });
 ```
 
-The handler gets the fields typed. Without `scopePlugin` the scope is ignored. The full picture, with jobs, actions, modules and which value wins, is in [scopes](scope.md).
+The handler gets the fields typed. Without `scopePlugin` the scope is ignored. The full picture, with jobs, actions, modules and which value wins, is in [scopes](context.md#scope-fields-for-an-action-a-module-and-a-call).

package/docs/cancel-stale-requests.md

@@ -1,5 +1,7 @@
 # Cancel stale requests and fix race conditions
 
+> **Level B.** Read first: the bus from the [README](../README.md).
+
 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

package/docs/chat-example.md

@@ -1,5 +1,7 @@
 # Build a chat with entities, features, modules and a small server
 
+> **Level D.** Read first: [Actions, jobs and modules](actions.md).
+
 Use this page when your app has several features that react to each other and you want to see where each piece of logic goes. The example is a chat with rooms, a history that loads, messages that can fail to send, a search across all rooms, and new messages that arrive on their own. A small Fastify server in the example answers every request, and it misbehaves on a known schedule, so each problem on this page really happens.
 
 It is a level D example. Start with [Actions, jobs and modules](actions.md) for the API, or with the `domains-ts` template in [Start a project from a template](starter.md#start-with-domains) for a smaller project.
@@ -14,6 +16,18 @@ npm run dev
 
 `npm run dev` starts the server and Vite together. Start it with `CHAOS=off npm run dev` to turn the failures off.
 
+## On this page
+
+- [Read how the server fails](#read-how-the-server-fails)
+- [See how the files are split](#see-how-the-files-are-split)
+- [Load a history that must not race](#load-a-history-that-must-not-race)
+- [Send a message that can fail](#send-a-message-that-can-fail)
+- [Search where one room is slow](#search-where-one-room-is-slow)
+- [Wait for a room before marking a result](#wait-for-a-room-before-marking-a-result)
+- [Poll for new messages](#poll-for-new-messages)
+- [Know where each value lives](#know-where-each-value-lives)
+- [Where to go next](#where-to-go-next)
+
 ## Read how the server fails
 
 The server keeps its data in memory. These rules are on purpose, and they are the same every run, so you can follow each section below by doing what the table says:
@@ -76,7 +90,7 @@ import { latest } from "nanoeffects/policies";
 export const fetchHistory = latest((roomId, { signal }) => api.loadHistory(roomId, { signal }));
 ```
 
-The module gives the job its work and keeps the state from the outcomes, so an aborted load clears the flag too (see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job)):
+The module gives the job its work and keeps the state from the outcomes, so an aborted load clears the flag too (see [Show a loading state with a job](actions.md#the-state-of-a-job)):
 
 ```js
 // message-module.js

package/docs/chat-widget.md

@@ -1,5 +1,7 @@
 # Build a chat widget that listens only while it is open
 
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when a site has a chat with a bot behind a launcher button, and the chat must cost nothing while it is closed. Closed means no subscriptions on the bus, no polling, no keyboard listener, and no request still running. Opening turns all of it on, and closing turns all of it off in one call.
 
 The code is in [`examples/chat-widget`](../examples/chat-widget): plain DOM and TypeScript, a fake bot in the browser, no server. Run it on [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat-widget), or on your machine:
@@ -30,7 +32,7 @@ It is a level D example: the logic lives in one module, and the page only mounts
 | `src/chat-handlers.ts` | `askBot` (`timeout` and `retry` inside) and `watchOperator` (`poll`): plain `async` functions that know nothing about the page. |
 | `src/chat-module.ts` | The list of what is alive while the chat is open. |
 | `src/panel.ts` | The view: shows the lines, sends the texts, returns one function that removes it. |
-| `src/main.ts` | The launcher: the only file that knows both the module and the panel. |
+| `src/main.ts` | The launcher: the only file that knows both the module and the panel; it listens for `closeRequested` only while the chat is open. |
 
 ## Bind everything in one module
 
@@ -80,7 +82,7 @@ Three details that make the cleanup complete:
 
 ## Open and close from the launcher
 
-`app.mount` returns the function that unmounts the module. The launcher puts it together with the one that removes the panel.
+`app.mount` returns the function that unmounts the module. `bus.on` returns the one that unsubscribes. The launcher puts them together with the one that removes the panel into a single `close`.
 
 <!-- docs-check: skip - the other files of the example are in examples/chat-widget -->
 ```js
@@ -96,7 +98,10 @@ let close = null; // set while the chat is open
 const open = () => {
   const stopModule = app.mount(chatModule); // subscriptions, polling and Escape start
   const stopPanel = renderPanel(document.body);
+  // the module emits closeRequested on Escape; nothing does while the chat is closed
+  const stopEscape = bus.on(closeRequested, () => close?.());
   close = () => {
+    stopEscape();
     stopPanel();
     stopModule(); // everything the module started ends, a running request included
     close = null;
@@ -110,18 +115,15 @@ button.addEventListener("click", () => {
     open();
   }
 });
-
-// the launcher stays subscribed: it must hear Escape to close the chat
-bus.on(closeRequested, () => close?.());
 ```
 
-The launcher's own `bus.on` is the only subscription that lives while the chat is closed, and it does nothing then: `close` is `null`.
+While the chat is closed the launcher holds no subscription at all: it only has the click listener of the button, which is a DOM listener, not a listener of the bus.
 
 ## Check that closing cleans up
 
 1. Open the chat and send a text. The bot answers after about a second. Every third question fails, and the retry asks again.
 2. Send a text and close the chat before the answer arrives. No line appears, also when you open the chat again.
-3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: only `chat/closeRequested` has a listener (the launcher). Open: `chat/sent`, `chat/messageAdded` and `chat/typing` have one each as well. That is the proof that nothing is left subscribed.
+3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: every event shows `0`, and so does "all events". Open: each of the four has one listener, and "all events" is `4`. That is the proof that nothing is left subscribed.
 4. Wait 10 s with the chat closed. The operator is not polled: no line from the operator appears.
 5. Press `Escape` with the chat closed. Nothing happens. Open the chat and press it again: it closes.
 6. Open the chat again. The old lines are back, and the polling runs.

package/docs/context.md

@@ -1,8 +1,31 @@
-# Put your own fields on every task
+# Working with context
 
-Optional: put a store, client, or logger on every task. Skip until many handlers need the same dependency.
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus).
 
-## Pass values at runtime
+Optional: put a store, client or logger on every task, or give fields to one action, module or call. Skip until many handlers need the same dependency.
+
+## On this page
+
+- [Context fields](#context-fields)
+  - [Pass values at runtime](#pass-values-at-runtime)
+  - [Type the fields (optional)](#type-the-fields-optional)
+  - [Build a field from the signal of each task](#build-a-field-from-the-signal-of-each-task)
+- [Scope: fields for an action, a module and a call](#scope-fields-for-an-action-a-module-and-a-call)
+  - [Turn scopes on](#turn-scopes-on)
+  - [Give an action its own fields](#give-an-action-its-own-fields)
+  - [Bind an effect to the task](#bind-an-effect-to-the-task)
+  - [Replace a field for one call](#replace-a-field-for-one-call)
+  - [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
+  - [Which value wins](#which-value-wins)
+  - [Keep a generic effect generic](#keep-a-generic-effect-generic)
+  - [Type the fields of a scope](#type-the-fields-of-a-scope)
+  - [Limits](#limits)
+
+## Context fields
+
+### Pass values at runtime
+
+<!-- docs-check: new -->
 
 ```js
 import { createBus } from "nanoeffects";
@@ -15,15 +38,17 @@ bus.on("save", (draft, { store }) => {
 });
 ```
 
-That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
+Here `store` is your own object: a store, an API client, a logger, anything. That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
 
 Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may be a function `(task) => fields` when the value depends on the task.
 
-To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
+To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#effectsplugin).
 
-To give fields to **one** command, action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](context.md#scope-fields-for-an-action-a-module-and-a-call).
 
-## Type the fields (optional)
+### Type the fields (optional)
+
+<!-- docs-check: new -->
 
 In TypeScript, `contextPlugin` (from `nanoeffects/context`) puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
 
@@ -45,7 +70,41 @@ bus.on("save", (draft, { store }) => store.put(draft));
 - A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
 - The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
 
-### Name the fields in the event map instead
+### Build a field from the signal of each task
+
+<!-- docs-check: new -->
+
+Problem: an HTTP client or a database handle should stop when the task is aborted. Without help, every handler passes `ctx.signal` to it by hand, and one forgotten call leaves a request running.
+
+`fromSignal(make)` from `nanoeffects/signal` marks a field of `contextPlugin` as a value that is built from the signal of the task. It does not run `make` for the bus: it runs it for each task that reads the field, once, with the `ctx.signal` of that task.
+
+```js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal } from "nanoeffects/signal";
+import axios from "axios";
+
+// contextPlugin — every task gets these fields
+// fromSignal — http is made from the signal of the task that reads ctx.http
+const bus = createBus().use(
+  contextPlugin({
+    logger: console, // a plain field: the same object for every task
+    http: fromSignal((signal) => axios.create({ signal })),
+  }),
+);
+
+bus.on("user/open", async (id, ctx) => {
+  const response = await ctx.http.get(`/users/${id}`); // aborts with the task
+  ctx.logger.log(response.data);
+});
+```
+
+- `make` runs at the first read, so a handler that never uses `ctx.http` pays nothing for it.
+- A task that `ctx.run` starts builds its own value from its own signal, so aborting the child stops only the child's requests.
+- The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.
+- Without `contextPlugin` a `fromSignal` marker is only an object.
+
+#### Name the fields in the event map instead
 
 `createBus<Events>({ context: { store } })` also types the fields, but through the event map: `WithContext` is checker-only and says which fields the handlers of this bus have. Use it when you cannot call `use`, for example for the bus that `createEffectsMiddleware` makes.
 
@@ -57,3 +116,288 @@ type Events = { save: Draft } & WithContext<{ store: Store }>;
 
 const bus = createBus<Events>({ context: { store } });
 ```
+
+## Scope: fields for an action, a module and a call
+
+Optional, for domain logic. Use it when one action needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
+
+A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `$effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
+
+You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
+
+### Turn scopes on
+
+<!-- docs-check: new -->
+
+Scopes are a plugin, so a bus that does not use them pays nothing.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scopes below work on this bus; returns the same bus
+export const bus = createBus().use(scopePlugin());
+```
+
+The bus is in one file and the actions in files named after their domain, so the next example imports `bus` from here. Each section after it keeps its own `bus.js` and domain file, as if it were an app of its own.
+
+- Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
+- Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
+
+### Give an action its own fields
+
+<!-- docs-check: new -->
+
+<!-- docs-check: continue -->
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — third argument is the scope of this action
+export const getUser = createAction(
+  "user/get",
+  (id, { api, cache }) => {
+    // api and cache are on ctx for this action only
+    return cache.get(id) ?? api.getUser(id);
+  },
+  { api, cache: new Map() },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+const user = await bus.emit(getUser("1")); // the handler has api and cache
+```
+
+The listeners of `"user/get"` get the same fields when the action is emitted, because the fields belong to the call.
+
+### Bind an effect to the task
+
+<!-- docs-check: new -->
+
+An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
+
+```js
+// feed.js
+import { createAction } from "nanoeffects/actions";
+import { delay, race } from "nanoeffects/effects";
+
+// your own effect: first parameter is the task (only its signal is used)
+const fetchJson = (ctx, url) =>
+  fetch(url, { signal: ctx.signal }).then((response) => response.json());
+
+export const loadFeed = createAction(
+  "feed/load",
+  (url, { fetchJson, race, delay }) =>
+    // race, delay, fetchJson — bound to this task: no ctx argument
+    race({
+      feed: () => fetchJson(url),
+      timeout: () => delay(5000),
+    }),
+  // $effects — built-in and your own functions share one object
+  { $effects: { fetchJson, race, delay } },
+);
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+import { bus } from "./bus";
+import { loadFeed } from "./feed";
+
+const result = await bus.emit(loadFeed("/feed"));
+```
+
+- Put in `$effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
+- A function under any other key is copied as it is; a function in `$effects` is bound.
+- `$effects` is the one name with a meaning. A field called `effects` is an ordinary field: `{ effects: { retries: 3 } }` puts that object on `ctx`, and nothing in it is bound.
+
+### Replace a field for one call
+
+<!-- docs-check: new -->
+
+The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+export const getUser = createAction(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+// the real api for this call
+await bus.emit(getUser("1"));
+
+// the second argument — a fake api, for this call only
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+await bus.emit(getUser("1"), { api: fakeApi });
+```
+
+Rules for the second argument:
+
+- It works with the call of an action (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
+- It does not work with the string form: in `emit("user/get", payload)` the second argument is the payload.
+- It can replace `$effects` too: `{ $effects: { delay: instantDelay } }`.
+- Fields of the library (`signal`, `emit`, …) in it are ignored.
+
+### Give an action, a job or a module its own fields
+
+<!-- docs-check: new -->
+
+```js
+// user.js
+import { createAction, createJob } from "nanoeffects/actions";
+
+// createAction — the listeners of this action's calls get the fields
+export const userLoaded = createAction("user/loaded", { store });
+
+// createJob — the scope is the fourth argument, after the outcomes;
+// the handler and the listeners of the outcome get its fields
+export const loadUser = createJob(
+  "user/load",
+  fetchUser,
+  { success: userLoaded, fail: "user/failed" },
+  { logger },
+);
+```
+
+```js
+// audit-module.js
+import { createModule } from "nanoeffects/actions";
+import { userLoaded } from "./user";
+
+// createModule — third argument; everything the module owns gets the fields:
+// m.on listeners, m.handle handlers, m.spawn tasks
+export const auditModule = createModule(
+  "audit",
+  (m) => {
+    m.on(userLoaded, (user, { logger }) => logger.info(user.id));
+  },
+  { logger },
+);
+```
+
+If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
+
+A module scope does not leak: a listener registered outside the module does not see it.
+
+### Which value wins
+
+<!-- docs-check: new -->
+
+When several places set the same field, the strongest one wins:
+
+| Strength | Where it is set |
+| -------- | --------------- |
+| 1 (strongest) | the second argument of `emit` |
+| 2 | the scope of the action or job |
+| 3 | the scope of the module that owns the handler |
+| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
+
+The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. The name `traceGroupId` is reserved: the tracer reads it, and it is not put on `ctx` ([Follow one flow](tracing.md#follow-one-flow-with-a-tracegroupid)). A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+
+### Keep a generic effect generic
+
+<!-- docs-check: new -->
+
+In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+
+`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
+
+```js
+// pick.js
+import { createAction } from "nanoeffects/actions";
+import { effect } from "nanoeffects/scope";
+
+// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
+const first = effect((ctx, items) => items[0]);
+
+export const pick = createAction("pick", (items, { first }) => first(items), {
+  first, // a plain key of the scope, not an entry of `$effects`
+});
+```
+
+Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
+
+`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
+
+```ts
+import { createAction } from "nanoeffects/actions";
+import type { Effect } from "nanoeffects/effects";
+
+// First — checker-only: how a handler calls the effect (no ctx)
+type First = <T>(items: T[]) => T;
+
+// Effect<First> — the function takes the task first and is typed as First once bound
+const first: Effect<First> = (ctx, items) => items[0];
+
+const pick = createAction(
+  "pick",
+  (id: string, { first }) => first([id]), // string
+  { $effects: { first } },
+);
+```
+
+`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
+
+### Type the fields of a scope
+
+<!-- docs-check: new -->
+
+A handler of an action, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+
+```ts
+import { createAction } from "nanoeffects/actions";
+
+type User = { id: string; name: string };
+
+const getUser = createAction(
+  "user/get",
+  async (id: string, ctx) => {
+    ctx.cache; // Map<string, User>, from the scope below
+    return ctx.cache.get(id);
+  },
+  { cache: new Map<string, User>() },
+);
+```
+
+- A field of a scope replaces a field of the same name from the bus in the type too.
+- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
+- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
+- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
+
+### Limits
+
+<!-- docs-check: new -->
+
+- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
+- The fields of the bus are not in the handler of an action made with `createAction(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
+- The string form of `emit` takes no scope.
+- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
+- A scope on an action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.

package/docs/debounce-and-abort.md

@@ -1,4 +1,6 @@
-# Debounce a request and abort the previous one
+# Pause between requests
+
+> **Level B.** Read first: [Policies](policies.md).
 
 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.