nanoeffects 0.3.0 → 0.4.0

package/docs/actions.md

@@ -1,68 +1,141 @@
 # Actions, commands, jobs and modules
 
-## Actions, commands and jobs
+Use this page when **domain logic lives on the bus**, off the UI: the UI emits and listens; handlers and modules own the work.
 
-`nanoeffects/actions` has the pieces to describe what a bus does, apart from the code that does it.
+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.
 
-```ts
+Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
+
+## Return a value from `emit` with a command
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// createCommand — emit runs the handler and returns its result
+const double = createCommand("math/double", (value) => value * 2);
+bus.emit(double(21)); // 42
+```
+
+## Describe events, commands, and jobs
+
+`nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
+
+```js
 import { createAction, createCommand, createJob } from "nanoeffects/actions";
 
-// an event with a payload, as in Redux Toolkit
-// the payload types come from the event map of the bus: type Events = { "user/loaded": User; "user/failed": Error }
+// createAction — event with a payload (like RTK createAction)
 const userLoaded = createAction("user/loaded");
 const loadFailed = createAction("user/failed");
 
-// a request for a result: emit it and get what its handler returns
-const getUser = createCommand("user/get", (id: string, { signal }) => fetchUser(id, { signal }));
+// createCommand with a handler — emit returns what the handler returns
+const getUser = createCommand("user/get", (id, { signal }) => {
+  return fetchUser(id, { signal });
+});
 
-// a contract without a handler: the code that sends mail is elsewhere
-const sendMail = createCommand<Mail, void>("mail/send");
+// createCommand without a handler — a contract; register the work elsewhere
+const sendMail = createCommand("mail/send");
 
-// a command whose outcome is sent on as actions: they are its properties, loadUser.success and loadUser.fail
+// createJob — command that also emits success / fail actions
 const loadUser = createJob("user/load", fetchUser, {
-  success: userLoaded, // an action creator that exists: used and returned as it is
-  fail: "user/failed", // a string: the job makes the action creator
+  success: userLoaded,
+  fail: "user/failed",
 });
 ```
 
-**Actions.** `createAction(type)` returns a creator, with no generics: it keeps the literal type, and the bus checks the payload against its event map (`bus.emit(userLoaded(5))` is an error when `"user/loaded"` is a `User`). Without an event map give the payload type, `createAction<User>("user/loaded")`. The creator: `userLoaded(user)` is `{ type, payload }`, `userLoaded.type` is the type, `userLoaded.match(action)` narrows an action. `createAction(type, prepare)` builds the payload from several arguments. A creator works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`.
+### Actions
+
+`createAction(type)` returns a creator. Without generics it keeps the literal type; the bus checks the payload against its event map. Without an event map, give the payload type: `createAction<User>("user/loaded")`.
+
+- `userLoaded(user)` → `{ type, payload }`
+- `userLoaded.type` — the type string
+- `userLoaded.match(action)` — narrows an action
+- `createAction(type, prepare)` — build the payload from several arguments
+- Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
 
-**Commands.** `bus.emit(command, payload)` tells the listeners of the command's type, then runs its handler as a task, with a context, and returns the result. The handler can be wrapped in a policy, `createCommand("search", latest(fn))`. Calling `command(payload)` runs its own handler without a bus. `command.match(action)` tells whether an action has the command's type and narrows it, as `match` of an action creator does.
+### Commands
 
-**Where handlers are registered.** The command may carry a handler. The bus gets the handlers bound to commands from a registry, `commandsPlugin`, and a handler bound there wins over the command's own. The registry belongs to one bus, as an effector scope does with `fork({ handlers })`, so each bus (each test) can have its own.
+Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or `bus.emit(command, payload)`) tells the listeners of the command’s type, then runs its handler as a task and returns the result.
 
-```ts
-import { commandsPlugin, bindHandler } from "nanoeffects/actions";
+- Wrap the handler in a policy: `createCommand("search", latest(fn))`.
+- `command.match(action)` narrows like an action creator’s `match`.
 
-const bus = createBus<Events>();
-const commands = bus.use(commandsPlugin([bindHandler(sendMail, smtpSend)])); // attached to the bus
+**Where handlers are registered.** The command may carry a handler. The bus can also take handlers from a registry (`commandsPlugin`). A handler bound there wins over the command’s own. Each bus (each test) has its own registry.
 
-const unbind = commands.handle(getUser, async () => fakeUser); // later, e.g. in a test
-unbind(); // the command's own handler is back; the latest binding wins
+```js
+import { createBus } from "nanoeffects";
+import {
+  bindHandler,
+  commandsPlugin,
+  createCommand,
+} from "nanoeffects/actions";
+
+const sendMail = createCommand("mail/send");
+const getUser = createCommand("user/get");
+
+const bus = createBus();
+
+// commandsPlugin — registry of handlers for this bus
+const commands = bus.use(
+  commandsPlugin([bindHandler(sendMail, smtpSend)]),
+);
+
+// later, e.g. in a test — latest binding wins
+const unbind = commands.handle(getUser, async () => fakeUser);
+unbind();
 ```
 
-A command with no handler anywhere throws `No handler for command "..."` from `emit`. The registry lives in `nanoeffects/actions`, so a bus without one carries none of this code; without it `emit(command, payload)` simply runs the command's own handler. `bus.use(commandsPlugin())` sets the registry as `bus.commands`, and a second one on the same bus replaces it. There is no `commands` option in `createBus`; a custom runner is assigned, `bus.commands = { run }`.
+A command with no handler anywhere throws `No handler for command "..."` from `emit` (the call itself only builds the action).
+
+The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second plugin on the same bus replaces it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
+
+### 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.
+
+- 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`.
+- `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 "..."`.
+- Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
+
+## Mount domains with modules
+
+**Problem.** A domain needs several subscriptions and command bindings. With plain `bus.on` / `commands.handle` you must remember every unsubscribe.
 
-**Jobs.** `createJob(type, handler, { success, fail })` makes a command that sends its outcome on as actions, for when nobody waits for the result, and returns the command itself, with the two actions on it: `loadUser.success` and `loadUser.fail`. When the handler succeeds, `loadUser.success(result)` is emitted on the bus, and when it fails, `loadUser.fail(error)`.
+**When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
 
-- `success` and `fail` are a string, from which the job makes an action creator with `createAction` (the payload is the result, or the error), or an action creator that exists already, which is used and returned as it is. A missing one is made with the type `<type>/success` or `<type>/fail`.
-- `bus.emit(command, payload)` returns a promise of the result. An error of the handler always counts as handled: it goes to `loadUser.fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
-- The actions are emitted as the task that ran the job, also for a handler bound with `commands.handle`, and are not sent once the task is aborted. A missing handler is not an outcome: `emit` throws `No handler for command "..."`.
-- Calling `command(payload)` directly runs only the handler.
+`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, and `commands`.
 
-## Modules
+```js
+import { createBus } from "nanoeffects";
+import {
+  createCommand,
+  createModule,
+  modulePlugin,
+} from "nanoeffects/actions";
 
-`bus.use(modulePlugin(modules))`, with `modulePlugin` from `nanoeffects/actions`, assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose` and `commands`, the registry of command handlers. A module is what a domain of the app needs: the commands it handles, the events it listens to, its sub-modules and its background tasks.
+const getUser = createCommand("user/get");
+const saveUser = createCommand("user/save", persistUser);
 
-```ts
-const userModule = createModule<Events>("user", (m) => {
-  m.handle(getUser, fetchUser); // a contract gets its handler here
-  m.use(saveUser, authModule); // a command that carries a handler, and a sub-module
-  m.on("login", (user, ctx) => ctx.emit("loaded", user));
-  m.spawn(async (_, ctx) => { /* background work, ends with the module */ });
+// createModule — one domain; unmount undoes everything below
+const userModule = createModule("user", (m) => {
+  m.handle(getUser, fetchUser);
+  m.use(saveUser, authModule);
+  m.on("login", (user, ctx) => {
+    ctx.emit("loaded", user);
+  });
+  m.spawn(async (_, ctx) => {
+    /* background work; ends when the module unmounts */
+  });
 });
 
-const bus = createBus<Events>();
+const bus = createBus();
+// modulePlugin — mount modules on the bus
 const app = bus.use(modulePlugin([userModule]));
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
@@ -70,9 +143,12 @@ app.commands.handle(getUser, fakeUser); // in a test
 app.dispose(); // unmounts every module
 ```
 
-- **Unmounting undoes everything** the module did: its subscriptions, its bound commands, its sub-modules and its background tasks, which are aborted.
-- **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one. That is what hot reload needs: see [hmr.md](hmr.md).
-- **The registry.** If `bus.use(commandsPlugin())` was called, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`, so the commands that modules bind are the ones the bus runs.
+- **Unmounting undoes everything** the module did: subscriptions, bound commands, sub-modules, and background tasks (aborted).
+- **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
+- **Registry.** If `bus.use(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
 - A disposed app cannot mount modules.
-- A module context is a task context plus `handle` (give a command a handler: for a contract, or to override), `use` (bring sub-modules and commands that carry a handler: `m.use(getUser, saveUser, subModule)`, in any order; the returned function undoes just that call) and `spawn` (a background task, aborted on unmount).
-- A command that carries a handler keeps answering after its module is unmounted: the handler is its own, and `use` only brings the command and tracks it in the registry. Use `handle` for a handler that should live only as long as the module.
+- Module context = task context plus `handle`, `use`, and `spawn`:
+  - `handle` — give a command a handler (contract, or override).
+  - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
+  - `spawn` — background task, aborted on unmount.
+- A command 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.

package/docs/context.md

@@ -1,15 +1,34 @@
-# Your own fields in the context
+# Put your own fields on every task
 
-Add fields to the context of every task of a bus: a store, a client, a logger. Describe them in the event map with `WithContext`, and give the values in `createBus({ context })`:
+Optional: put a store, client, or logger on every task. Skip until many handlers need the same dependency.
+
+## Pass values at runtime
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus({ context }) — every task gets these fields
+const bus = createBus({ context: { store } });
+
+bus.on("save", (draft, { store }) => {
+  store.put(draft);
+});
+```
+
+That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, commands, 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.
+
+## Type the fields (optional)
+
+`WithContext` on the event map only tells TypeScript that handlers of **this** bus have those fields. It does not wire anything at runtime and is not app-wide — another bus can have different fields or none.
 
 ```ts
+import { createBus, type WithContext } from "nanoeffects";
+
+// Events — event name → payload
+// WithContext — checker-only: handlers also have ctx.store
 type Events = { save: Draft } & WithContext<{ store: Store }>;
 
 const bus = createBus<Events>({ context: { store } });
-bus.on("save", (draft, { store }) => store.put(draft));
 ```
-
-The fields are in the context of handlers, `ctx.run`, listeners added with `ctx.on`, commands, modules and the child tasks of effects and policies, and the compiler checks them: a handler of a bus without `WithContext` has no `store`, and `context` must have the fields that the map names. Two buses can have different fields.
-
-- The fields of the library (`signal`, `emit`, `run`, ...) win when the names are the same.
-- `context` can also be a function, `(task) => fields`, called with `{ type, payload }` of each task, for fields that depend on the task.

package/docs/effects.md

@@ -1,20 +1,122 @@
 # Effects and cancellation
 
-An abort only raises a flag: your code decides to stop. `nanoeffects/effects` has helpers for the usual cases.
+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.
 
-`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function). `cancellable(ctx, executor)` is a promise tied to the task signal; it works like `new Promise`, but the executor gets one object, `{ resolve, reject, onCancel }`, with `onCancel` for cleanups:
+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)).
 
-```ts
+## Wrap a handler with retry and timeout
+
+`retry`, `timeout`, and `poll` have two 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.
+
+The first argument tells them apart: a function (`retry`), a number (`timeout`), or a number/function (`poll`) is a wrapper; an object is `ctx`.
+
+```js
+import { createBus } from "nanoeffects";
+import { poll, retry, timeout } 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, {
+  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 })));
+
+// ctx.run — run a wrapped Task as a child (aborted with the handler)
+bus.on("open", async (id, ctx) => {
+  const load = retry(timeout(5000, loadUser));
+  const user = await ctx.run(load, id);
+  ctx.emit("opened", user);
+});
+
+// ctx-first form — one call inside a body
+bus.on("load", async (id, ctx) => {
+  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 });
+});
+```
+
+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.
+
+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.
+
+### Options for retry, timeout, and poll
+
+**`retry`**
+
+- `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.
+
+**`timeout`**
+
+- Error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`).
+- Rejects even if the starter ignores its signal.
+
+**`poll`** (like patronum `interval`)
+
+- 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.
+
+A pause can be a function wherever a time is given (backoff or jitter):
+
+```js
+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
+```
+
+All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
+
+## Tie a promise to the task signal
+
+`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
+
+`cancellable(ctx, executor)` is a promise tied to the task signal. It works like `new Promise`, but the executor gets `{ resolve, reject, onCancel }`.
+
+```js
+import { createBus } from "nanoeffects";
 import { cancellable } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
 
+const bus = createBus();
+
+// cancellable — promise tied to the task signal; onCancel for cleanups
+// latest — a newer wait aborts the older timer
 bus.on(
   "wait",
-  latest((_, ctx) =>
-    cancellable(ctx, ({ resolve, onCancel }) => {
+  latest((_, ctx) => {
+    return cancellable(ctx, ({ resolve, onCancel }) => {
       const timer = setTimeout(resolve, 5000);
       onCancel(() => clearTimeout(timer));
-    }),
-  ),
+    });
+  }),
 );
 ```
 
@@ -22,116 +124,93 @@ bus.on(
 - If the task is already aborted, the executor does not run.
 - After the promise settles, the abort listener is removed and cleanups are dropped.
 
-`onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if already aborted) and returns a function that unsubscribes:
+## Run cleanup on abort
+
+`onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if already aborted) and returns a function that unsubscribes.
 
-```ts
+```js
+import { createBus } from "nanoeffects";
 import { onAbort } from "nanoeffects/effects";
 
+const bus = createBus();
+
 bus.on("connect", (url, ctx) => {
   const socket = new WebSocket(url);
+  // onAbort — run cleanup when this task aborts
   onAbort(ctx, () => socket.close());
 });
 ```
 
-## allSettled
-
-`allSettled(ctx, effects)` is `all` that waits for every starter and never fails because of one: each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`, in the shape of the input (object or array). Nothing is cancelled when a starter fails. Only an abort of `ctx` rejects it.
+## Wait for the next event with `take`
 
-```ts
-const { user, posts } = await allSettled(ctx, {
-  user: ({ signal }) => fetchUser(id, { signal }),
-  posts: ({ signal }) => fetchPosts(id, { signal }),
-});
-
-if (user.status === "fulfilled") render(user.value);
-```
+A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts:
 
-## Subscribing from a task: ctx.on, ctx.off, take
+```js
+import { createBus } from "nanoeffects";
 
-A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts, so it cannot outlive the work that needed it:
+const bus = createBus();
 
-```ts
 bus.on("watch", (_, ctx) => {
   ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
 });
 ```
 
-- The returned function unsubscribes sooner. After the task is aborted, `ctx.on` does nothing.
-- A policy passes its handler a child context, so under `latest` the subscriptions of a superseded run end with it.
-- `ctx.off` is the bus `off`: `ctx.off(event)` clears every handler of the event, not only the task's.
+- 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.
 
 `take(ctx, event, options?)` waits for the next `event` and resolves with its payload:
 
-```ts
+```js
+import { createBus } from "nanoeffects";
 import { take, timeout } from "nanoeffects/effects";
 
+const bus = createBus();
+
 bus.on("login", async (user, ctx) => {
   const reason = await take(ctx, "logout"); // resolves on the next logout
   cleanup(user, reason);
 
   // wait for a matching event, but not longer than 5 s
   const id = await timeout(ctx, 5000, ({ signal }) =>
-    take(ctx, "saved", { signal, predicate: (id) => id === draft.id }),
+    take(ctx, "saved", { signal, predicate: (savedId) => savedId === draft.id }),
   );
 });
 ```
 
-- It sees only events emitted after the call, takes one, and unsubscribes.
-- `options.predicate` skips payloads it rejects; `options.signal` stops the wait, which is how a `race` or `timeout` starter cancels it.
-- On abort of the task or of `options.signal` it unsubscribes and rejects with the abort reason. It is traced as a `take` group.
+- Sees only events emitted after the call, takes one, and unsubscribes.
+- `options.predicate` skips payloads it rejects.
+- `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
+- On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
 
-## retry, timeout, poll
+## Run several starters together
 
-These three have two forms. As a **Task wrapper** they take a function `(payload, ctx) => result` and return one, so they go straight into `on`, next to the policies, with no `ctx` in their arguments. As a **call inside a body** they take `ctx` first.
+`all(ctx, effects)` runs starters together. One failure cancels the rest. Shape of the input (object or array) is preserved in the result.
 
-```ts
-import { poll, retry, timeout } from "nanoeffects/effects";
+`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.
 
-const loadUser = (id: string, { signal }) => fetchUser(id, { signal });
+```js
+import { createBus } from "nanoeffects";
+import { allSettled } from "nanoeffects/effects";
 
-// wrappers: up to 4 attempts with a backoff, each within 5 s; a newer call supersedes the older
-bus.on(
-  "load",
-  latest(
-    retry(timeout(5000, loadUser), {
-      times: 4,
-      delay: (attempt) => 2 ** attempt * 100,
-      shouldRetry: (error) => !isFatal(error),
-    }),
-  ),
-);
+const bus = createBus();
 
-// calls refresh every 10 s until the task is aborted
-bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
-
-// a wrapped Task runs as a child of a handler with ctx.run: the only place where ctx is written
 bus.on("open", async (id, ctx) => {
-  const user = await ctx.run(retry(timeout(5000, loadUser)), id);
-});
-
-// one call inside a body: ctx first
-bus.on("load", async (id, ctx) => {
-  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 4 });
-  const data = await timeout(ctx, 5000, ({ signal }) => fetchData(id, { signal }));
-  await poll(ctx, () => refresh(), 10_000);
+  const { user, posts } = await allSettled(ctx, {
+    user: ({ signal }) => fetchUser(id, { signal }),
+    posts: ({ signal }) => fetchPosts(id, { signal }),
+  });
+
+  if (user.status === "fulfilled") {
+    render(user.value);
+  }
 });
 ```
 
-Use the wrapper form for a whole handler or a whole `ctx.run`, and the `ctx` form for one call in the middle of a body. The forms are told apart by the first argument: a function (`retry`), a number (`timeout`), a number or a function (`poll`) is a wrapper; an object is `ctx`. Each attempt or call of a wrapper gets a context of its own, a child of the caller's, so an abort of the caller reaches it and an abort of one attempt (a timeout) does not reach the caller. The attempt number is passed only in the `ctx` form.
-
-- `retry`: `times` is the total number of attempts (default 3), `delay` is a number or `(attempt, error) => ms`, `shouldRetry(error, attempt)` can stop early. `fn` gets the attempt number, starting at 1. On abort it rejects with the abort reason.
-- `timeout`: the error is a `DOMException` named `TimeoutError`, like `AbortSignal.timeout`. It rejects even if the starter ignores its signal.
-- `poll`: like patronum `interval`. The first call comes after `ms` (`leading: true` also calls at once), and the next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap with the next call; `waitForFn: true` starts each pause when the call ends instead, so 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.
-- A pause can be a function wherever a time is given, for backoff or jitter: `retry`'s `delay` gets `(attempt, error)`, `poll`'s `ms` gets the number of the call the pause leads to, and `delay` itself takes a function called once when it starts:
-
-```ts
-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 down to once a minute
-await delay(ctx, () => 200 + Math.random() * 200); // 200 to 400 ms
-```
+`race(ctx, effects)` settles with the first starter that finishes and cancels the others.
 
-- All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
+## Pass `ctx` outside a task
 
-The other effects wait inside a body, so `ctx` is their first argument: `delay(ctx, ms)`, `all(ctx, effects)`, `allSettled(ctx, effects)`, `race(ctx, effects)`, `cancellable(ctx, executor)`, `onAbort(ctx, fn)`, `take(ctx, event, options)`, and `retry`, `timeout` and `poll` in their `ctx` form. It is required; outside a task pass `{}` or any object with a `signal`.
+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`.
 
 For `fetch` and other APIs that take a signal, pass `ctx.signal`. A timeout without `race`: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])`.

package/docs/errors.md

@@ -1,21 +1,34 @@
-# Errors and unheard events
+# Handle errors and unheard events
 
-`emit` is a plain loop over the handlers, like in nanoevents: if a handler throws, the remaining handlers are skipped and the error reaches the caller of `emit`. A rejected promise of an async handler is left unhandled.
+Defaults match a small bus. Set these when you want isolation or typo warnings.
 
-Pass `onError` to isolate handlers instead. Then every handler runs, and thrown errors and rejections of async handlers (including ones wrapped in `latest`, `debounce` and the like) go to `onError`; an `onError` that throws is logged to `console.error`.
+## Isolate failing handlers
 
-```ts
-const bus = createBus<Events>({
-  onError: (error, { type, payload }) => report(error, type, payload),
+`emit` is a plain loop over the handlers (like nanoevents). If a handler throws, the remaining handlers are skipped and the error reaches the caller of `emit`. A rejected promise of an async handler is left unhandled.
+
+Pass `onError` to isolate handlers instead. Then every handler runs. Thrown errors and rejections of async handlers (including those wrapped in `latest`, `debounce`, and the like) go to `onError`. An `onError` that throws is logged to `console.error`.
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus — onError isolates failing handlers so others still run
+const bus = createBus({
+  onError: (error, { type, payload }) => {
+    report(error, type, payload);
+  },
 });
 ```
 
-## Events that nobody listens to
+## 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 commands, which always have a handler to run.
+
+Use it as a warning in development:
 
-A typo in an event name, `emit("serch")`, does nothing and says nothing. `onUnhandled` is called when an event is emitted and nobody listens to it (a listener of every event, `"*"`, counts). It is not called for commands, which always have a handler to run. Use it as a warning in development:
+```js
+import { createBus } from "nanoeffects";
 
-```ts
-const bus = createBus<Events>({
+const bus = createBus({
   onUnhandled: import.meta.env.DEV
     ? ({ type }) => console.warn(`Nobody listens to "${type}"`)
     : void 0,