nanoeffects 0.28.0 → 0.30.1

package/docs/effects.md

@@ -1,109 +1,155 @@
 # Effects and cancellation
 
-Use this page for retry, timeouts, waiting, or parallel work — not as the first page for a small bus. Pick **one** helper for your job; the rest is reference.
+> **Level C.** Read first: [Policies](policies.md).
+
+Use this page for retry, timeouts, waiting, or parallel work — not as the first page for a small bus. Pick **one** effect for your job; the rest is reference.
 
 An abort only raises a flag. Your code decides to stop. Start with `retry` / `timeout` on a handler (see [Guide §5](guide.md#5-add-retry-and-timeout)).
 
-## Wrap a handler with retry and timeout
+## Effects
+
+Every effect below has its own section with its forms, options and an example. `ctx` is the context of the task.
+
+- [`retry`](#retry) — repeat a call after an error.
+- [`timeout`](#timeout) — stop a call that takes too long.
+- [`poll`](#poll) — call a function at an interval.
+- [`backoff`](#backoff) — make the pause between retries grow.
+- [`delay`](#delay) — wait for a time; an abort ends the wait.
+- [`cancellable`](#cancellable) — a Promise tied to the task signal, for callbacks and timers.
+- [`onAbort`](#onabort) — run code when the task is aborted.
+- [`ctx.on` and `ctx.off`](#ctxon-and-ctxoff) — subscribe to the bus inside a task.
+- [`take`](#take) — wait for the next event inside a handler.
+- [`all`](#all) — run several calls together; one failure cancels the rest.
+- [`allSettled`](#allsettled) — wait for all of them, whatever the outcome.
+- [`race`](#race) — take the first result and cancel the rest.
+- [`effectsPlugin`](#effectsplugin) — short forms of effects: call them without `ctx`.
+- [Effects outside a task](#effects-outside-a-task) — call effects where there is no handler.
+
+## `retry`
+
+Runs a function again after an error. Use it when a call fails now and then, for example because of the network.
 
-`retry`, `timeout`, and `poll` have two forms:
+Forms:
 
-- **Task wrapper** — take a function `(payload, ctx) => result` and return one. Pass them into `on` next to policies (no `ctx` in their arguments).
-- **Call inside a body** — take `ctx` first.
+- `retry(fn, options?)` — a wrapper of a handler: takes a function `(payload, ctx) => result` and returns one. Pass it to `on` next to policies.
+- `retry(ctx, fn, options?)` — a call inside the body of a handler.
 
-The first argument tells them apart: a function (`retry`), a number (`timeout`), or a number/function (`poll`) is a wrapper; an object is `ctx`.
+Options:
+
+- `times` — total attempts. It is `3` by default.
+- `delay` — a number or a function `(attempt, error) => ms`. For a growing pause see [`backoff`](#backoff).
+- `shouldRetry(error, attempt)` — return `false` to stop early.
+- `fn` gets the attempt number, starting at `1`.
+- On abort, `retry` rejects with the abort reason.
 
 ```js
 import { createBus } from "nanoeffects";
-import { poll, retry, timeout } from "nanoeffects/effects";
+import { retry } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
 const bus = createBus();
 const loadUser = (id, { signal }) => fetchUser(id, { signal });
 
-// timeout — one try must finish within 5 s
-const loadOnce = timeout(5000, loadUser);
-// retry — up to 4 attempts with backoff
-const loadWithRetry = retry(loadOnce, {
+// retry — a wrapper of the handler: up to 4 attempts, but not after a fatal error
+const loadWithRetry = retry(loadUser, {
   times: 4,
-  delay: (attempt) => 2 ** attempt * 100,
   shouldRetry: (error) => !isFatal(error),
 });
-// latest — a newer load aborts the older retry chain
-bus.on("load", latest(loadWithRetry));
 
-// poll — call refresh every 10 s until the task aborts
-bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+// latest — a newer load aborts the older chain of attempts
+bus.on("load", latest(loadWithRetry));
 
-// ctx.run — run a wrapped Task as a child (aborted with the handler)
+// ctx.run — run the wrapped function as a child task (aborted with the handler)
 bus.on("open", async (id, ctx) => {
-  const load = retry(timeout(5000, loadUser));
-  const user = await ctx.run(load, id);
+  const user = await ctx.run(loadWithRetry, id);
   ctx.emit("opened", user);
 });
+```
+
+Use the wrapper for a whole handler or a whole `ctx.run`. Each attempt gets its own child context: an abort of the caller reaches it, and an abort of one attempt does not reach the caller. For one call in the middle of a body use the form with `ctx`:
+
+```js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+
+const bus = createBus();
 
-// ctx-first form — one call inside a body
 bus.on("load", async (id, ctx) => {
+  // retry with ctx — one call inside the body
   const user = await retry(
     ctx,
     () => fetchUser(id, { signal: ctx.signal }),
     { times: 4 },
   );
-  const data = await timeout(ctx, 5000, ({ signal }) => {
-    return fetchData(id, { signal });
-  });
-  await poll(ctx, () => refresh(), 10_000);
-  ctx.emit("ready", { user, data });
+
+  ctx.emit("loaded", user);
 });
 ```
 
-Use the wrapper for a whole handler or a whole `ctx.run`. Use the `ctx` form for one call in the middle of a body.
+## `timeout`
 
-Each attempt or call of a wrapper gets its own child context. Abort of the caller reaches it. Abort of one attempt (a timeout) does not reach the caller. The attempt number is passed only in the `ctx` form.
+Rejects when the work takes longer than the time you set, and aborts it. Use it when a request can hang.
 
-### Options for retry, timeout, and poll
+Forms:
 
-**`retry`**
+- `timeout(ms, handler)` — a wrapper of a handler.
+- `timeout(ctx, ms, fn)` — a call inside a body; `fn` gets the context of its own child task.
 
-- `times` — total attempts (default `3`).
-- `delay` — number or `(attempt, error) => ms`.
-- `shouldRetry(error, attempt)` — stop early.
-- `fn` gets the attempt number starting at `1`.
-- On abort, rejects with the abort reason.
+The error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`). `timeout` rejects even if the function ignores its signal.
 
-**`timeout`**
+```js
+import { createBus } from "nanoeffects";
+import { timeout } from "nanoeffects/effects";
 
-- Error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`).
-- Rejects even if the starter ignores its signal.
+const bus = createBus();
+const loadUser = (id, { signal }) => fetchUser(id, { signal });
 
-**`poll`** (like patronum `interval`)
+// timeout — a wrapper of the handler: it must finish within 5 s
+bus.on("load", timeout(5000, loadUser));
 
-- First call after `ms`. `leading: true` also calls at once.
-- Next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap the next call.
-- `waitForFn: true` starts each pause when the call ends — calls never overlap.
-- `fn` gets the call number from `0`.
-- An error from `fn` stops polling and rejects. An abort ends it normally and clears the timer.
+bus.on("open", async (id, ctx) => {
+  // timeout with ctx — one call inside the body; child carries the signal of the request
+  const data = await timeout(ctx, 5000, (child) => fetchData(id, child));
+  ctx.emit("opened", data);
+});
+```
+
+## `poll`
+
+Calls a function again and again at an interval, until the task is aborted. Use it to refresh data every N seconds. It is like `interval` in patronum.
+
+Forms:
+
+- `poll(ms, fn, options?)` — a wrapper of a handler.
+- `poll(ctx, fn, ms)` — a call inside a body.
 
-A pause can be a function wherever a time is given. For retries with a cap and jitter, see [Back off between retries](#back-off-between-retries):
+Options:
+
+- The first call happens after `ms`. `leading: true` also calls at once.
+- The next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap the next call. `waitForFn: true` starts each pause when the call ends, so calls never overlap.
+- `fn` gets the call number, starting at `0`.
+- An error from `fn` stops polling and rejects. An abort ends it normally and clears the timer.
 
 ```js
 import { createBus } from "nanoeffects";
-import { delay, poll, retry } from "nanoeffects/effects";
+import { poll } from "nanoeffects/effects";
 
 const bus = createBus();
 
+// poll — a wrapper of the handler: call refresh every 10 s until the task aborts
+bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+
 bus.on("sync", async (_, ctx) => {
-  retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
-  poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
-  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+  // poll with ctx — the same inside a body
+  await poll(ctx, () => refresh(), 10_000);
 });
 ```
 
-All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
+`retry`, `timeout` and `poll` are traced: the effect is a group, and each attempt or call is a `run` child.
 
-## Back off between retries
+## `backoff`
 
-Use this when a server or network fails under load. Retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. Make the pause grow with each attempt, and add jitter so clients spread out.
+Makes the pause between retries grow, with a cap and jitter. Use it when a server or network fails under load: retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. `backoff(options)` returns a function `(attempt) => ms`.
 
 The shortest form is a `delay` function. It needs no import:
 
@@ -143,48 +189,41 @@ const loadWithRetry = retry(loadUser, {
 - `retry` counts attempts from 1. `poll` counts calls from 0, so with `poll` the first pause is `base / factor`.
 - The result is a plain function `(attempt) => ms`, so it also fits `delay(ctx, …)`.
 
-## Put selected effects on `ctx`
-
-If handlers call the same helpers often, put them on the task once. A handler then destructures them like `signal`, with no `ctx` argument. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
+A pause can be a function wherever a time is given:
 
 ```js
 import { createBus } from "nanoeffects";
-import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
-
-// effectsPlugin — add race, all and delay to the context of every task
-const effects = effectsPlugin({ race, all, delay });
-
-// use returns the same bus, typed with the new fields
-const bus = createBus().use(effects);
+import { delay, poll, retry } from "nanoeffects/effects";
 
-bus.on("load", async (id, { race, all, delay }) => {
-  // race — same as race(ctx, …)
-  const result = await race({
-    data: ({ signal }) => fetchData(id, { signal }),
-    // a starter gets its own child with the same bound effects, so delay(5000) stops with the race
-    timeout: ({ delay }) => delay(5000),
-  });
-  if ("timeout" in result) throw new Error("timed out");
+const bus = createBus();
 
-  // all — same as all(ctx, …)
-  const { user, posts } = await all({
-    user: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
-  });
+bus.on("sync", async (_, ctx) => {
+  retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
+  poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
+  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
 });
 ```
 
-- The key is the name the effect gets on `ctx`. `race`, `all`, `allSettled`, `take` and `delay` are typed by hand.
-- Your own function works too if its first parameter is `{ signal }` (an *effect*): `effectsPlugin({ fetchJson })` gives `ctx.fetchJson(url)`. TypeScript removes the first parameter from its type; for a generic function see [keep a generic effect generic](scope.md#keep-a-generic-effect-generic).
-- Leave `retry`, `timeout` and `poll` out: bound to the task they would look like their handler wrappers.
-- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
-- Free forms keep working: `race(ctx, …)`.
+## `delay`
+
+Waits for the given time and rejects on abort. A plain `setTimeout` would go on after the task is aborted; `delay` ends the wait at once and clears the timer. `delay(ctx, ms)`, where `ms` can be a function.
+
+```js
+import { createBus } from "nanoeffects";
+import { delay } from "nanoeffects/effects";
+
+const bus = createBus();
 
-## Tie a promise to the task signal
+bus.on("saved", async (_, ctx) => {
+  // delay — wait 3 s; an abort ends the wait at once and clears the timer
+  await delay(ctx, 3000);
+  ctx.emit("toast/hidden");
+});
+```
 
-`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
+## `cancellable`
 
-`cancellable(ctx, executor)` is a promise tied to the task signal. It works like `new Promise`, but the executor gets `{ resolve, reject, onCancel }`.
+A Promise tied to the task signal. Use it for APIs that work with callbacks, timers or listeners: the signal cannot stop them by itself, so `cancellable` rejects the Promise on abort and runs your cleanup. `cancellable(ctx, executor)` works like `new Promise`, but the executor gets `{ resolve, reject, onCancel }`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -193,7 +232,7 @@ import { latest } from "nanoeffects/policies";
 
 const bus = createBus();
 
-// cancellable — promise tied to the task signal; onCancel for cleanups
+// cancellable — a Promise tied to the task signal; onCancel registers a cleanup
 // latest — a newer wait aborts the older timer
 bus.on(
   "wait",
@@ -206,13 +245,13 @@ bus.on(
 );
 ```
 
-- If the task aborts before the promise settles, cleanups run (last registered first) and the promise rejects with the abort reason.
+- If the task aborts before the Promise settles, cleanups run (last registered first) and the Promise rejects with the abort reason.
 - If the task is already aborted, the executor does not run.
-- After the promise settles, the abort listener is removed and cleanups are dropped.
+- After the Promise settles, the abort listener is removed and cleanups are dropped.
 
-## Run cleanup on abort
+## `onAbort`
 
-`onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if already aborted) and returns a function that unsubscribes.
+Runs code when the task is aborted: a hook of the life of the task. A task may be aborted because the user left or a newer call replaced it, and whatever it opened (a socket, a timer, a listener) must be closed then. `onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if the task is already aborted) and returns a function that unsubscribes.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -222,14 +261,14 @@ const bus = createBus();
 
 bus.on("connect", (url, ctx) => {
   const socket = new WebSocket(url);
-  // onAbort — run cleanup when this task aborts
+  // onAbort — close the socket when this task aborts
   onAbort(ctx, () => socket.close());
 });
 ```
 
-## Wait for the next event with `take`
+## `ctx.on` and `ctx.off`
 
-A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts:
+Subscribes to the bus inside a task. A task context has `on` and `off`, like the bus, and a subscription made with `ctx.on` ends when the task aborts.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -237,15 +276,29 @@ import { createBus } from "nanoeffects";
 const bus = createBus();
 
 bus.on("watch", (_, ctx) => {
-  ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
+  // gone when this task aborts
+  const stop = ctx.on("tick", (n) => console.log(n));
+
+  // or end it sooner yourself: stop() unsubscribes
+  ctx.on("watch/closed", stop);
 });
 ```
 
-- The returned function unsubscribes sooner. After abort, `ctx.on` does nothing.
-- Under `latest`, subscriptions of a superseded run end with that run.
-- `ctx.off(event)` clears every handler of the event on the bus, not only the task’s.
+Be careful with it:
+
+- **A task that finishes by itself is not aborted**, so its `ctx.on` subscription stays. When the work is done, unsubscribe with the function that `ctx.on` returns, or call `ctx.abort()`.
+- To wait for **one** event, use [`take`](#take): it unsubscribes by itself.
+- For listeners that live as long as a feature, use a [module](actions.md#modules): `unmount` removes all of them.
+
+Also:
 
-`take(ctx, event, options?)` waits for the next `event` and resolves with its payload. `event` is the name of an event or an action creator, as for `bus.on`:
+- After an abort, `ctx.on` does nothing.
+- Under `latest`, the subscriptions of a superseded run end with that run.
+- `ctx.off(event)` clears every handler of the event on the bus, not only the ones of this task.
+
+## `take`
+
+Waits for the next event of the bus inside a handler and resolves with its payload. `take(ctx, event, options?)`. The `event` is the name of an event or an action creator, as for `bus.on`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -267,22 +320,65 @@ bus.on("login", async (user, ctx) => {
   const id = await timeout(
     ctx,
     5000,
-    take("saved", { predicate: (savedId) => savedId === draft.id }), // take without ctx: a starter
+    take("saved", { predicate: (savedId) => savedId === draft.id }), // take without ctx — a ready-made function for the group
   );
 });
 ```
 
-- Sees only events emitted after the call, takes one, and unsubscribes.
+- It sees only events emitted after the call, takes one, and unsubscribes.
 - With an action creator the result has the payload type of the creator. A creator made without a payload type (`createAction("saved")`) takes it from the event map of the bus.
 - `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
-- `options.signal` stops the wait. Inside `race`, `all` or `timeout` you do not need it: the group already stops the starter, so write `take("saved")` without options.
-- On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
+- `options.signal` stops the wait. Inside `race`, `all` or `timeout` you do not need it: the group already stops the wait, so write `take("saved")` without options.
+- On abort of the task or of `options.signal`, it unsubscribes and rejects with the abort reason.
+
+## `all`
 
-## Run several starters together
+Runs several calls together; one failure cancels the rest. Use it to load several things at once. `all(ctx, effects)` takes an object or an array of functions, and the result keeps that shape.
+
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("open", async (id, ctx) => {
+  // all — run both requests together; one failure cancels the other. child is the context of its own request
+  const { user, posts } = await all(ctx, {
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
+  });
+
+  ctx.emit("opened", { user, posts });
+});
+```
 
-`all(ctx, effects)` runs starters together. One failure cancels the rest. Shape of the input (object or array) is preserved in the result.
+Every function of the group gets `child`, the context of its own child task. Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the group ends or fails, `child` is aborted and stops exactly this effect. If your API takes the signal in its options, `child` has a `signal`, so pass it as the options: `(child) => fetchUser(id, child)` (`fetch` reads only `signal` from it). The same holds for `allSettled`, `race` and `timeout`.
 
-`allSettled(ctx, effects)` waits for every starter and never fails because of one. Each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`. Nothing is cancelled when a starter fails. Only an abort of `ctx` rejects it.
+**Limit how many run at once.** `all` and `allSettled` start everything together. Over a long list that is a burst of requests. Pass `{ concurrency }` as the third argument and at most that many run at a time; the next one starts when a running one settles:
+
+```js
+import { createBus } from "nanoeffects";
+import { all, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("sync", async (ids, ctx) => {
+  // all with concurrency — 5 loads at a time, results in the order of ids
+  const users = await all(
+    ctx,
+    ids.map((id) => retry(() => loadUser(id), { times: 2 })),
+    { concurrency: 5 },
+  );
+
+  render(users);
+});
+```
+
+The result has the same order and shape as without the option. If one call of `all` fails, the running ones are cancelled and the waiting ones are never started. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a call that waited for a free slot would never run.
+
+## `allSettled`
+
+Waits for every call and never fails because of one. Use it when a partial answer is better than none. `allSettled(ctx, effects)`. Each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`. Nothing is cancelled when a call fails; only an abort of `ctx` rejects it.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -291,9 +387,10 @@ import { allSettled } from "nanoeffects/effects";
 const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
+  // allSettled — wait for both, whatever the outcome
   const { user, posts } = await allSettled(ctx, {
-    user: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
   });
 
   if (user.status === "fulfilled") {
@@ -302,7 +399,9 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-`race(ctx, effects)` settles with the first starter that finishes and cancels the others.
+## `race`
+
+Settles with the first call that finishes and cancels the others. Use it to take the fastest answer or to cut a wait short. `race(ctx, effects)`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -311,9 +410,9 @@ import { delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 bus.on("save", async (draft, ctx) => {
-  // race — the first starter to finish wins, the other is cancelled
+  // race — the first to finish wins, the other is cancelled
   const result = await race(ctx, {
-    waited: delay(1000), // delay without ctx — a starter: race gives it its own child
+    waited: delay(1000), // delay without ctx — a ready-made function for the group: race gives it its own child
     cancelled: take("cancel"), // take without ctx — the same, waits for the next "cancel"
   });
 
@@ -323,9 +422,9 @@ bus.on("save", async (draft, ctx) => {
 });
 ```
 
-**`delay` and `take` without `ctx` are ready-made starters.** In a group, `delay(1000)` and `take("cancel")` do what `(child) => delay(child, 1000)` and `(child) => take(child, "cancel")` do. The group calls them with the child, so the wait stops with the group. Use this form inside `race`, `all`, `allSettled` and `timeout`; use `delay(ctx, 1000)` in plain handler code. A starter waits only when a group calls it: do not `await delay(1000)` on its own, it is a function, not a promise. Write `take("cancel")` in the group, as above; a starter stored in a variable outside it does not know the events of your bus, and you name them yourself in TypeScript (`const cancelled: StarterOf<Events> = take("cancel")`; `StarterOf` is exported by `nanoeffects/effects`).
+**`delay` and `take` without `ctx` are ready-made functions for a group.** In a group, `delay(1000)` and `take("cancel")` do what `(child) => delay(child, 1000)` and `(child) => take(child, "cancel")` do: the group calls them with the child, so the wait stops with the group. Use this form inside `race`, `all`, `allSettled` and `timeout`; use `delay(ctx, 1000)` in plain handler code. They wait only when a group calls them: `await delay(1000)` on its own does not wait, because it is a function, not a Promise. In TypeScript, one kept in a variable outside a group does not know the events of your bus; name them yourself: `const cancelled: StarterOf<Events> = take("cancel")` (`StarterOf` is exported by `nanoeffects/effects`).
 
-The wrapper form of `retry`, `timeout` and `poll` is a starter too: a group calls it with the child, and the function you wrap gets `undefined` as its payload and the child as its context. Write the data it needs into a closure:
+The wrapper form of `retry`, `timeout` and `poll` works in a group too: the group calls it with the child, and the function you wrap gets `undefined` as its payload and the child as its context. Write the data it needs into a closure:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -335,7 +434,7 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   const result = await race(ctx, {
-    // retry without ctx — a starter: up to 3 attempts, each with the signal of the child
+    // retry without ctx — up to 3 attempts, each with the signal of the child
     user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
     // delay without ctx — the loser is cancelled when the other one finishes
     waited: delay(5000),
@@ -347,9 +446,9 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-The same call with a payload and a context, `(payload, ctx)`, is the Task that `bus.on` and `ctx.run` use, and it does not change. `retry`, `timeout` and `poll` therefore have three call forms: with `ctx`, as a Task, and as a starter. All three stay; [Stability](stability.md#rely-on-these-call-forms) says how they are told apart.
+So `retry`, `timeout` and `poll` have three call forms: with `ctx`, as a Task for `bus.on` and `ctx.run`, and inside a group. The arguments tell them apart: a context first is the `ctx` form; a function called with a payload and a context is a Task; the same function called by a group with one argument, its child, is the group form. This does not depend on how many parameters your function declares.
 
-**`all`, `allSettled` and `race` without `ctx` are starters too**, so a group nests in another group with no wrapper. Load two things, but give up after five seconds:
+**`all`, `allSettled` and `race` without `ctx` also work in a group**, so a group nests in another group with no wrapper. Load two things, but give up after five seconds:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -359,7 +458,7 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   const result = await race(ctx, {
-    // all without ctx — a starter: loads both, each with up to 3 attempts
+    // all without ctx — loads both, each with up to 3 attempts
     loaded: all({
       user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
       posts: retry((_, { signal }) => fetchPosts(id, { signal }), { times: 3 }),
@@ -374,37 +473,66 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-One argument is the short form and two arguments are the form with `ctx`: `all(effects)` returns a starter, `all(ctx, effects)` runs the group. The inner group stops with the outer one and cancels its own starters. Passing only a context, `all(ctx)`, is a mistake and throws a `TypeError` at once. A group starter written in a group needs no type. One kept in a variable outside a group does not know its bus: in TypeScript, annotate it with `StarterOf<Events>`, or `StarterOf<Events, Result>` when you need its value.
+One argument is the short form and two arguments are the form with `ctx`: `all(effects)` returns a function for a group, `all(ctx, effects)` runs the group. The inner group stops with the outer one and cancels its own calls. Passing only a context, `all(ctx)`, is a mistake and throws a `TypeError` at once. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`; write `(child) => all(child, effects, { concurrency: 5 })` there. In TypeScript, a group kept in a variable outside a group needs a type: `StarterOf<Events>`, or `StarterOf<Events, Result>` when you need its value.
 
-**Limit how many run at once.** `all` and `allSettled` start every starter together. Over a long list that is a burst of requests. Pass `{ concurrency }` as the third argument and at most that many run at a time; the next one starts when a running one settles:
+## `effectsPlugin`
+
+Short forms of effects: `effectsPlugin(effects)` puts chosen effects on `ctx`, so a handler calls them without passing `ctx` around. Use it when many handlers call the same helpers, to cut the boilerplate. A handler destructures them like `signal`. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
 
 ```js
 import { createBus } from "nanoeffects";
-import { all, retry } from "nanoeffects/effects";
+import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
 
-const bus = createBus();
+// effectsPlugin — add race, all and delay to the context of every task
+const effects = effectsPlugin({ race, all, delay });
 
-bus.on("sync", async (ids, ctx) => {
-  // all with concurrency — 5 loads at a time, results in the order of ids
-  const users = await all(
-    ctx,
-    ids.map((id) => retry(() => loadUser(id), { times: 2 })),
-    { concurrency: 5 },
-  );
+// use returns the same bus, typed with the new fields
+const bus = createBus().use(effects);
 
-  render(users);
+bus.on("load", async (id, { race, all, delay }) => {
+  // race — same as race(ctx, …)
+  const result = await race({
+    data: (child) => fetchData(id, child),
+    // a group function gets its own child with the same bound effects, so delay(5000) stops with the race
+    timeout: ({ delay }) => delay(5000),
+  });
+  if ("timeout" in result) throw new Error("timed out");
+
+  // all — same as all(ctx, …)
+  const { user, posts } = await all({
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
+  });
 });
 ```
 
-The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`, so a group starter inside another group takes none; write `(child) => all(child, effects, { concurrency: 5 })` there.
+- The key is the name the effect gets on `ctx`. `race`, `all`, `allSettled`, `take` and `delay` are typed by hand.
+- Your own function works too if its first parameter is `{ signal }` (an *effect*): `effectsPlugin({ fetchJson })` gives `ctx.fetchJson(url)`. TypeScript removes the first parameter from its type; for a generic function see [keep a generic effect generic](context.md#keep-a-generic-effect-generic).
+- Leave `retry`, `timeout` and `poll` out: bound to the task they would look like their handler wrappers.
+- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
+- The free forms keep working: `race(ctx, …)`.
 
+## Effects outside a task
 
-**A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options: `({ signal }) => fetchUser(id, { signal })`. The same holds for `all`, `allSettled` and `timeout`.
+Effects take `ctx` first. Inside a handler it is the `ctx` you already have. Outside a task (in a plain function, a script or a test) there is no `ctx`: pass an object with a `signal`, or `{}` if you never abort.
 
-If `ctx` is `{}` or a bare `{ signal }` (outside a task), `child` has only `signal` and `abort`, so it fits `delay` and `poll` but not `take`, which needs a bus.
+```js
+import { delay, retry } from "nanoeffects/effects";
 
-## Pass `ctx` outside a task
+const controller = new AbortController();
 
-Effects that wait inside a body take `ctx` first: `delay`, `all`, `allSettled`, `race`, `cancellable`, `onAbort`, `take`, and the `ctx` forms of `retry` / `timeout` / `poll`. Outside a task, pass `{}` or any object with a `signal`. The one exception is `delay(ms)` and `take(event)` as starters of a group, which take no `ctx` (see above).
+// outside a task there is no ctx: an object with a signal is enough
+const context = { signal: controller.signal };
 
-For `fetch` and other APIs that take a signal, pass `ctx.signal`. A timeout without `race`: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])`.
+// the effects take it as ctx; fetchUser gets the same signal, so the request itself stops too
+const user = await retry(
+  context,
+  () => fetchUser("1", { signal: controller.signal }),
+  { times: 3 },
+);
+
+await delay(context, 500);
+
+// stops the pending retries and waits
+controller.abort();
+```

package/docs/errors.md

@@ -1,5 +1,7 @@
 # Handle errors and unheard events
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 and 2.
+
 Defaults match a small bus. Set these when you want isolation or typo warnings.
 
 ## Isolate failing handlers
@@ -21,9 +23,9 @@ const bus = createBus({
 
 ## Warn when nobody listens
 
-A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for actions, which always have a handler to run.
+A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for an action that has a handler to run. An action without a handler is only an event, so it is called for it.
 
-Use it as a warning in development:
+Use it as a warning in development (`import.meta.env.DEV` is the Vite flag; use your own check in another bundler):
 
 ```js
 import { createBus } from "nanoeffects";