nanoeffects 0.28.0 → 0.29.0

package/docs/actions.md

@@ -10,6 +10,32 @@ 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)).
 
+## Pick the word: event, action, job, module
+
+Four names, one idea each. Take the first row that fits.
+
+| Word | What it is | Use it when |
+| ---- | ---------- | ----------- |
+| Event | A name and a payload; `createAction("x")` with no handler. | The UI or a handler tells that something happened. |
+| Action with a handler | The same, plus work: `createAction("x", handler)`. `emit` returns the result. | The caller needs a value back. |
+| Job | An action with a handler that also emits `pending`, `success`, `fail` and `cancel`. | The UI shows a loading state. |
+| Module | A group of listeners, handlers and tasks, mounted and unmounted with one call. | One domain must start and stop as a unit. |
+
+Start with events. 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
+
+- [Pick the word: event, action, job, module](#pick-the-word-event-action-job-module)
+- [Return a value from `emit` with a handler](#return-a-value-from-emit-with-a-handler)
+- [Describe events, handlers and jobs](#describe-events-handlers-and-jobs)
+  - [Actions](#actions)
+  - [Bind a handler later](#bind-a-handler-later)
+  - [Say what a bound handler returns](#say-what-a-bound-handler-returns)
+  - [Jobs](#jobs)
+- [Show a loading state with a job](#show-a-loading-state-with-a-job)
+- [Mount domains with modules](#mount-domains-with-modules)
+- [Give an action or a module its own fields](#give-an-action-or-a-module-its-own-fields)
+
 ## Return a value from `emit` with a handler
 
 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.
@@ -164,7 +190,7 @@ 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.
 

package/docs/chat-example.md

@@ -14,6 +14,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:

package/docs/chat-widget.md

@@ -30,7 +30,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 +80,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 +96,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 +113,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

@@ -21,7 +21,7 @@ Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may
 
 To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
 
-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](scope.md).
 
 ## Type the fields (optional)
 
@@ -45,6 +45,38 @@ 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 }))`.
 
+## Build a field from the signal of each task
+
+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.

package/docs/effects.md

@@ -4,6 +4,18 @@ Use this page for retry, timeouts, waiting, or parallel work — not as the firs
 
 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)).
 
+## On this page
+
+- [Wrap a handler with retry and timeout](#wrap-a-handler-with-retry-and-timeout)
+  - [Options for retry, timeout, and poll](#options-for-retry-timeout-and-poll)
+- [Back off between retries](#back-off-between-retries)
+- [Put selected effects on `ctx`](#put-selected-effects-on-ctx)
+- [Tie a promise to the task signal](#tie-a-promise-to-the-task-signal)
+- [Run cleanup on abort](#run-cleanup-on-abort)
+- [Wait for the next event with `take`](#wait-for-the-next-event-with-take)
+- [Run several starters together](#run-several-starters-together)
+- [Pass `ctx` outside a task](#pass-ctx-outside-a-task)
+
 ## Wrap a handler with retry and timeout
 
 `retry`, `timeout`, and `poll` have two forms:
@@ -49,9 +61,7 @@ bus.on("load", async (id, ctx) => {
     () => fetchUser(id, { signal: ctx.signal }),
     { times: 4 },
   );
-  const data = await timeout(ctx, 5000, ({ signal }) => {
-    return fetchData(id, { signal });
-  });
+  const data = await timeout(ctx, 5000, (child) => fetchData(id, child));
   await poll(ctx, () => refresh(), 10_000);
   ctx.emit("ready", { user, data });
 });
@@ -160,7 +170,8 @@ const bus = createBus().use(effects);
 bus.on("load", async (id, { race, all, delay }) => {
   // race — same as race(ctx, …)
   const result = await race({
-    data: ({ signal }) => fetchData(id, { signal }),
+    // child — the context of this starter; it has the `signal`, so the request stops with the race
+    data: (child) => fetchData(id, child),
     // a starter gets its own child with the same bound effects, so delay(5000) stops with the race
     timeout: ({ delay }) => delay(5000),
   });
@@ -168,8 +179,8 @@ bus.on("load", async (id, { race, all, delay }) => {
 
   // all — same as all(ctx, …)
   const { user, posts } = await all({
-    user: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
   });
 });
 ```
@@ -292,8 +303,8 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   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") {
@@ -399,7 +410,7 @@ bus.on("sync", async (ids, ctx) => {
 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.
 
 
-**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`.
+**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, and `child` has a `signal`, so pass it as the options: `(child) => fetchUser(id, child)` (`fetch` reads only `signal` from it). The same holds for `all`, `allSettled` and `timeout`.
 
 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.
 

package/docs/guide.md

@@ -11,6 +11,23 @@ Climb one step at a time: small bus → policies → effects → handlers and mo
 
 Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 
+## On this page
+
+- [1. Create a bus](#1-create-a-bus)
+  - [Listen to every event](#listen-to-every-event)
+  - [Pick events with a function](#pick-events-with-a-function)
+- [2. Use the handler context](#2-use-the-handler-context)
+- [3. Abort the previous run with `latest`](#3-abort-the-previous-run-with-latest)
+- [4. Pick another policy when overlap differs](#4-pick-another-policy-when-overlap-differs)
+- [5. Add retry and timeout](#5-add-retry-and-timeout)
+- [6. Run work in parallel or wait for an event](#6-run-work-in-parallel-or-wait-for-an-event)
+- [7. Name events three ways](#7-name-events-three-ways)
+- [8. Bind a handler to an action later](#8-bind-a-handler-to-an-action-later)
+- [9. Mount a domain as a module](#9-mount-a-domain-as-a-module)
+- [10. Add types when you want checking (optional)](#10-add-types-when-you-want-checking-optional)
+- [11. Isolate errors and warn on typos](#11-isolate-errors-and-warn-on-typos)
+- [Where next](#where-next)
+
 ## 1. Create a bus
 
 `on` subscribes. `emit` calls the subscribers. `on` returns the unsubscribe function.
@@ -272,10 +289,11 @@ import { all, delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 // all — run together; one failure cancels the rest
+// child — the context of that starter: it has the `signal`, so the request stops with the group
 bus.on("search", async (id, ctx) => {
   const { user, posts } = await all(ctx, {
-    user: ({ signal }) => api.user(id, { signal }),
-    posts: ({ signal }) => api.posts(id, { signal }),
+    user: (child) => api.user(id, child),
+    posts: (child) => api.posts(id, child),
   });
   ctx.emit("loaded", { user, posts });
 });

package/docs/migrating-from-effector.md

@@ -2,6 +2,17 @@
 
 Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
 
+## On this page
+
+- [Split the work](#split-the-work)
+- [Find the equivalent](#find-the-equivalent)
+- [Rewrite an effect](#rewrite-an-effect)
+  - [Keep the state in Zustand](#keep-the-state-in-zustand)
+- [Rewrite a form](#rewrite-a-form)
+  - [Replace the log with a request](#replace-the-log-with-a-request)
+- [Use both in one app](#use-both-in-one-app)
+- [What is different](#what-is-different)
+
 ## Split the work
 
 | Job | Use |

package/docs/observable.md

@@ -2,6 +2,8 @@
 
 Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
+The same entry has `events`, which needs no stream library: it gives an event to a `for await` loop. See [Read an event with a `for await` loop](#read-an-event-with-a-for-await-loop).
+
 `createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
 
 ## Turn an event into a stream
@@ -145,6 +147,47 @@ bus.on(
 
 `switchMap` drops the old inner stream. `latest` aborts the old task through `signal`, so a `fetch` that got the signal really stops.
 
+## Read an event with a `for await` loop
+
+Problem: a task wants to handle the payloads of one event one after another, in order, and stop when the screen closes. `take` waits for one payload, and a listener has no place for a loop.
+
+`events(source, event, options)` from `nanoeffects/observable` returns an async iterator of the payloads. It listens from the call, so a payload that comes before the first read is kept. `source` is a bus or a task context; with a context the loop also ends when the task aborts.
+
+```js
+import { createBus } from "nanoeffects";
+import { events } from "nanoeffects/observable";
+
+const bus = createBus();
+const controller = new AbortController();
+
+// events — the "query/changed" payloads one by one; keeps the last 3 while the loop is busy
+const queries = events(bus, "query/changed", {
+  signal: controller.signal,
+  buffer: 3,
+});
+
+async function watchQueries() {
+  for await (const query of queries) {
+    console.log("search for", query); // runs once per payload, in order
+  }
+}
+
+watchQueries().catch((reason) => console.log("stopped:", reason)); // the abort rejects the loop
+bus.emit("query/changed", "cat");
+controller.abort("screen closed"); // the loop ends with this reason
+```
+
+| Option | What it does | Default |
+| ------ | ------------ | ------- |
+| `signal` | Ends the loop. The waiting read rejects with the abort reason. | none |
+| `buffer` | The most payloads kept while the loop is busy. | `Infinity` |
+| `overflow` | Which payload goes when the buffer is full: `"drop-oldest"` or `"drop-newest"`. | `"drop-oldest"` |
+
+- `break`, `return` and a throw inside the loop remove the listener.
+- With no `buffer`, a loop that never reads keeps every payload. Set `buffer` for a slow loop.
+- An event of a bus does not end, so the loop ends only by `break`, the `signal` or the task.
+- Inside a task, `events(ctx, "query/changed")` needs no `signal`: the task ending is the end.
+
 ## Convert back to a stream or a promise
 
 | You need | Write |

package/docs/oop.md

@@ -9,6 +9,23 @@ Use this page when **your domain logic lives in classes**: a service, a store or
 
 If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
 
+## On this page
+
+- [The problem without it](#the-problem-without-it)
+- [Make an independent emitter with `Emitter`](#make-an-independent-emitter-with-emitter)
+  - [Type the events (optional)](#type-the-events-optional)
+- [Give a class the methods of a shared bus](#give-a-class-the-methods-of-a-shared-bus)
+  - [Extend the result with no class of your own](#extend-the-result-with-no-class-of-your-own)
+- [Let the class make its bus](#let-the-class-make-its-bus)
+- [End the subscriptions with `dispose`](#end-the-subscriptions-with-dispose)
+- [Stream an event with a `Subject`](#stream-an-event-with-a-subject)
+- [Keep a method of your own](#keep-a-method-of-your-own)
+- [Subscribe a method with `@On` and `@Once`](#subscribe-a-method-with-on-and-once)
+- [Decorate the class with `@WithBus`](#decorate-the-class-with-withbus)
+- [Pass a method by hand](#pass-a-method-by-hand)
+- [Type the instances (optional)](#type-the-instances-optional)
+- [What is not done](#what-is-not-done)
+
 ## The problem without it
 
 A class that listens to the bus keeps a reference to it, and keeps every unsubscribe function in a list to call when the object goes away. Forget one and the old object keeps handling events. `extendBus` does both for you.

package/docs/package.md

@@ -2,24 +2,33 @@
 
 Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
 
+## Start with these three
+
 | Import | What is in it |
 | ------ | ------------- |
 | `nanoeffects` | `createBus`, the types |
 | `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
-| `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` |
-| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
-| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value |
-| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` |
-| `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` |
-| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) |
-| `nanoeffects/redux` | `createEffectsMiddleware` |
-| `nanoeffects/observable` | `createObserve`, `Subject` |
-| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
-| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) |
-| `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) |
-| `nanoeffects/dev` | `devPlugin` (no-op in production) |
-| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |
+
+## Add the rest when you need it
+
+Each row is optional. The "when" column says what need brings you to it.
+
+| Import | What is in it | When |
+| ------ | ------------- | ---- |
+| `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` | `emit` must return a result, or domain logic leaves the UI |
+| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events | `on` must take a function that picks events |
+| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value | a store or client must be on every task |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` | an outside `AbortSignal` (request, React Query) must stop tasks |
+| `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` | you write classes, not functions |
+| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) | one action or module needs its own fields |
+| `nanoeffects/redux` | `createEffectsMiddleware` | you already use Redux |
+| `nanoeffects/observable` | `createObserve`, `Subject` | you need an Observable (RxJS) |
+| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) | React components |
+| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) | Svelte components |
+| `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) | Vue components |
+| `nanoeffects/dev` | `devPlugin` (no-op in production) | you look for leaks in development |
+| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) | you want to see what ran and why |
 
 The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists all of them, what each returns, and the order to use them in.
 

package/docs/plugins.md

@@ -2,12 +2,52 @@
 
 Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registry of handlers, diagnostics. Read this page when you want to know which plugins exist, what each one gives you, and in what order to use them. Skip it for a small bus: `createBus()` alone is enough.
 
+## On this page
+
+- [Use a plugin](#use-a-plugin)
+- [Pick a plugin by task](#pick-a-plugin-by-task)
+- [Main plugins](#main-plugins)
+  - [Put a store or a client on every handler: `contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin)
+  - [Use `race` and `delay` without `ctx`: `effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin)
+  - [Bind or replace a handler: `actionsPlugin`](#bind-or-replace-a-handler-actionsplugin)
+  - [Mount a domain as one unit: `modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin)
+- [Extra plugins](#extra-plugins)
+  - [Give one action its own fields: `scopePlugin`](#give-one-action-its-own-fields-scopeplugin)
+  - [Tie an emit or a listener to an outside signal: `signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin)
+  - [Name the origin and the flow of a trace: `tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin)
+  - [Listen to a group of events: `matchPlugin`](#listen-to-a-group-of-events-matchplugin)
+  - [Hand the bus to a state manager: `emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin)
+  - [Tell the bus when a React value changes: `reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin)
+  - [Find leaks while you develop: `devPlugin`](#find-leaks-while-you-develop-devplugin)
+- [Put them together](#put-them-together)
+- [Use them in any order](#use-them-in-any-order)
+- [See what is not a plugin](#see-what-is-not-a-plugin)
+- [Write your own plugin](#write-your-own-plugin)
+
 ## Use a plugin
 
 A plugin is a function of the bus. `bus.use(plugin)` calls it with the bus and returns whatever the plugin returns. Most plugins return the same bus, so you can chain them: `createBus().use(a).use(b)`. A few return something of their own (a registry, an app, a `disconnect` function): keep it.
 
 In TypeScript keep the result of `contextPlugin` and `effectsPlugin`: the type of the bus with its new fields is the type they return (`const bus = createBus().use(contextPlugin({ store }))`).
 
+## Pick a plugin by task
+
+Find your need in the left column. No row fits: you need no plugin.
+
+| I need | Use |
+| ------ | --- |
+| A store, client or logger on every handler | [`contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin) |
+| `race`, `all` or `delay` without passing `ctx` | [`effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin) |
+| A test that replaces a handler | [`actionsPlugin`](#bind-or-replace-a-handler-actionsplugin) |
+| One domain mounted and unmounted as a unit | [`modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin) |
+| Fields for one action or module only | [`scopePlugin`](#give-one-action-its-own-fields-scopeplugin) |
+| Tasks that stop when a request, socket or query is cancelled | [`signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin) |
+| One listener for a group of events | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) |
+| A callback for a state manager that emits | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) |
+| A React component that sends its value to the bus | [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) |
+| Names in the trace | [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) |
+| Warnings about leaks while you develop | [`devPlugin`](#find-leaks-while-you-develop-devplugin) |
+
 ## Main plugins
 
 These four cover what most apps need: shared dependencies, effects, handlers and modules. Start here.
@@ -33,6 +73,8 @@ const bus = createBus().use(contextPlugin({ store }));
 bus.on("save", (draft, { store }) => store.put(draft));
 ```
 
+A client that must stop with the task, such as an `axios` instance, goes in as `fromSignal((signal) => axios.create({ signal }))` from `nanoeffects/signal`: it is built from the signal of each task, when the task reads it. More in [Build a field from the signal of each task](context.md#build-a-field-from-the-signal-of-each-task).
+
 ### Use `race` and `delay` without `ctx`: `effectsPlugin`
 
 Effects such as `race`, `all`, `take` and `delay` are bound to the task, so a handler calls `race({ … })` and not `race(ctx, { … })`. Your own functions that take `{ signal }` first work too. More in [Effects](effects.md#put-selected-effects-on-ctx).
@@ -48,7 +90,7 @@ const bus = createBus().use(effects);
 
 bus.on("load", async (id, { race, delay }) => {
   const result = await race({
-    data: ({ signal }) => api.get(id, { signal }),
+    data: (child) => api.get(id, child),
     timeout: () => delay(5000),
   });
 });
@@ -85,7 +127,7 @@ const bus = createBus();
 // modulePlugin — mounts userModule at the end of this block, or at the first use if that is earlier, and returns the app
 const app = bus.use(modulePlugin([userModule]));
 
-app.unmount(userModule); // its listeners, bound commands and tasks are gone
+app.unmount(userModule); // its listeners, bound actions and tasks are gone
 ```
 
 ## Extra plugins
@@ -95,7 +137,7 @@ Add one of these when you meet its need. None of them is required.
 | Plugin | What it gives you | Import | `bus.use` returns |
 | ------ | ----------------- | ------ | ----------------- |
 | [`scopePlugin`](#give-one-action-its-own-fields-scopeplugin) | Its own fields for one action, job or module, and a way to replace them in one `emit`. | `nanoeffects/scope` | The same bus |
-| [`signalPlugin`](#tie-an-emit-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
+| [`signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks, and `on(event, handler, { signal })` that removes the listener, when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
 | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) | `on` that listens to a group of events which a function picks. | `nanoeffects/match` | The same bus, typed with the new overloads |
 | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) | A callback that emits an action, to give to a state manager. | `nanoeffects/actions` | The same bus, with `emitter` |
 | [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) | `traceId` and `traceGroupId` for a trace: the root of an emitter, a flow, a named listener. | `nanoeffects/trace` | The same bus |
@@ -111,10 +153,10 @@ import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
-// scopePlugin — makes the scope of a command work on this bus
+// scopePlugin — makes the scope of an action work on this bus
 const bus = createBus().use(scopePlugin());
 
-// the last argument: fields of this command only
+// the last argument: fields of this action only
 const getUser = createAction("user/get", (id, { api }) => api.getUser(id), {
   api,
 });
@@ -123,25 +165,41 @@ const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
 bus.emit(getUser("1"), { api: fakeApi }); // a fake api for this call only
 ```
 
-### Tie an emit to an outside signal: `signalPlugin`
+### Tie an emit or a listener to an outside signal: `signalPlugin`
 
-A library such as React Query owns the request and gives you an `AbortSignal`. `emit` takes it as `{ signal }` and aborts the tasks it starts when the signal aborts, so `timeout`, `retry` and the request stop too. More in [Use nanoeffects with React Query and SWR](query-libraries.md).
+A library such as React Query owns the request and gives you an `AbortSignal`. `emit` takes it as `{ signal }` and aborts the tasks it starts when the signal aborts, so `timeout`, `retry` and the request stop too. More in [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).
 
 ```js
 import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { signalPlugin } from "nanoeffects/signal";
 
-// signalPlugin — emit takes { signal } for a command, a job or an action
+// signalPlugin — emit takes { signal } for an action, a job or an action
 const bus = createBus().use(signalPlugin());
 
 const getUser = createAction("user/get", (id, { signal }) => api.getUser(id, { signal }));
 
 const controller = new AbortController();
-bus.emit(getUser("1"), { signal: controller.signal }); // runs the command
+bus.emit(getUser("1"), { signal: controller.signal }); // runs the action
 controller.abort(); // ctx.signal of the handler aborts with it
 ```
 
+The same signal can end a listener. `on` and `once` take `{ signal }` as their options, as `addEventListener` does, so code that has a signal keeps no `unbind` function. The listener is removed when the signal aborts; a handler that already runs is not aborted. A signal that is aborted already adds no listener.
+
+```js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — on and once take { signal } in their options
+const bus = createBus().use(signalPlugin());
+
+const controller = new AbortController();
+bus.on("saved", (draft) => console.log(draft), { signal: controller.signal }); // listens until the abort
+controller.abort(); // the listener is gone: bus.get("saved") is empty
+```
+
+Without the plugin the `signal` option is ignored and the listener stays. `off(event, handler)` removes a listener but does not end its link to the signal; call the function that `on` returned for that.
+
 ### Name the origin and the flow of a trace: `tracePlugin`
 
 With a tracer on the bus, the plugin lets a trace say which subscription began a chain (`traceId` of `useEmitter` and `bus.emitter`), follow one flow by a `traceGroupId`, and show which listener ran (`bus.on(event, handler, { traceId })`). Without the plugin the options are ignored. More in [Tracing](tracing.md#show-which-subscription-began-a-chain).
@@ -254,7 +312,7 @@ import { scopePlugin } from "nanoeffects/scope";
 export const bus = createBus()
   .use(contextPlugin({ store })) // ctx.store on every task
   .use(effectsPlugin({ race, all })) // ctx.race and ctx.all, bound to the task
-  .use(scopePlugin()) // scopes for commands, actions, jobs, modules and emit
+  .use(scopePlugin()) // scopes for actions, jobs, modules and emit
   .use(matchPlugin()) // bus.on takes a function that picks the events
   .use(emitterPlugin()); // bus.emitter(creator)
 
@@ -295,7 +353,7 @@ These connect the bus to something, but are not used with `bus.use`:
 - `createEffectsMiddleware(bus, { filter })` from `nanoeffects/redux` is a Redux middleware for a bus that exists. See [Stores](stores.md#wire-redux-toolkit-to-a-bus).
 - `createBus({ trace })` takes a tracer from `nanoeffects/trace`. See [Tracing](tracing.md).
 - `extendBus(bus, Base)` from `nanoeffects/oop` gives a class the methods of a bus, with the subscriptions of each instance ended by `dispose()`. It reads the bus as it is, so use the plugins first. See [Use the bus from a class](oop.md).
-- `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable. See [Observable](observable.md).
+- `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable, and `events(bus, event)` into a `for await` loop. See [Observable](observable.md).
 
 ## Write your own plugin