nanoeffects 0.27.0 → 0.29.0

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.
@@ -31,7 +48,7 @@ bus.emit("greet", "Bob"); // nobody listens
 
 Handlers run at once, in subscription order.
 
-`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus.
+`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus. `bus.get("greet")` gives the listeners that event has right now; `bus.get("greet").length === 0` tells that nobody listens any more (`"*"` gives the any-event listeners, which a named event does not include; `bus.get()` with no name gives every listener of every event). It takes the event name as a string: for an action creator use `creator.type`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -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.
@@ -310,7 +327,7 @@ export const SearchService = extendBus(bus, SearchServiceBase);
 
 Things to know:
 
-- The event is a name, an action creator or a command, as for `bus.on`. For a creator or a command the payload of the method is checked against it.
+- The event is a name or an action creator, as for `bus.on`. For a creator the payload of the method is checked against it.
 - The second argument, `wrap`, takes the bound handler and returns the one to subscribe: `latest`, or `(handler) => debounce(300, handler)`. A policy needs it: `latest(this.search)` wraps the function without `this`, and the bound handler is what `wrap` gets.
 - The subscriptions are made right after the constructor of `Base`. An event that is emitted inside that constructor does not reach them.
 - A subclass inherits them. A method that a subclass overrides is subscribed only if the override is decorated.

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 command, 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