nanoeffects 0.6.0 → 0.8.0

package/llms-full.txt

@@ -86,6 +86,74 @@ unbind();
 - An event that only `"*"` listens to counts as heard, so `onUnhandled` does not fire for it.
 - `bus.off("*")` removes every `"*"` listener; `bus.off()` clears the whole bus, `"*"` included.
 
+### Pick events with a function
+
+To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { matchPlugin } from "nanoeffects/match";
+
+// matchPlugin — lets on, once and off take a function that picks the events
+export const bus = createBus().use(matchPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+export const userLoaded = createAction("user/loaded");
+export const userFailed = createAction("user/failed");
+```
+
+```js
+// user-handlers.js
+import { bus } from "./bus";
+
+// the function picks the events; the handler gets the payload and the context of each
+bus.on(
+  (action) => action.type.startsWith("user/"),
+  (payload, ctx) => {
+    console.log(ctx.type, payload);
+  },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { userFailed, userLoaded } from "./user";
+
+bus.emit(userLoaded({ id: "1" })); // user/loaded { id: "1" }
+bus.emit("order/placed", 5); // not picked
+bus.emit(userFailed("boom")); // user/failed boom
+```
+
+- `once(fn, handler)` waits for the first event that `fn` accepts. `off(fn)` removes every handler of `fn`, and `off(fn, handler)` removes one.
+- An action creator or a command still means that one event: only a function with no `type` is a function that picks events.
+- The cost: the handler listens to `"*"`, so each event makes one task for each such subscription, also when the function says no, and an event that only such a subscription listens to counts as heard for `onUnhandled`. For a few known events, `on(creator, handler)` is cheaper.
+- It works in any order with the other plugins, `devPlugin` included.
+
+In TypeScript a function that is a type guard narrows the payload of the handler:
+
+```ts
+import { bus } from "./bus";
+
+type User = { id: string };
+
+// the guard says which event this is, and the handler gets its payload typed
+const isLoaded = (action: {
+  type: string;
+  payload: unknown;
+}): action is { type: "user/loaded"; payload: User } => action.type === "user/loaded";
+
+bus.on(isLoaded, (user) => console.log(user.id)); // user: User
+```
+
+`ctx.on` takes such a function at run time too, but its type does not know it yet.
+
 ## 2. Use the handler context
 
 The second argument is the **task** context for this call. Emit further events through it. Pass `ctx.signal` to `fetch` when you cancel work.
@@ -242,22 +310,42 @@ More in [Effects](effects.md).
 
 `emit` and `on` take a string, an object `{ type, payload }` (a Redux action fits), or a function with a `type` property (action creators and commands).
 
+From here on the bus is kept in one file and the events in files named after their domain (`move.js`, `math.js`), as in a real app: the events can then be imported anywhere without importing the bus.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+export const bus = createBus();
+```
+
+```js
+// move.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — names an event; calling it builds { type, payload }
+export const moved = createAction("moved");
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+// createCommand — like an action, but emit runs a handler and returns its result
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { moved } from "./move";
+import { double } from "./math";
 
 bus.emit("moved", { x: 1, y: 2 });
 bus.emit({ type: "moved", payload: { x: 2, y: 2 } });
 
-// createAction — names an event; calling it builds { type, payload }
-const moved = createAction("moved");
 bus.emit(moved({ x: 3, y: 2 }));
 bus.on(moved, ({ x }) => console.log(x));
 
-// createCommand — like an action, but emit runs a handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
 bus.emit(double(21)); // 42
 ```
 
@@ -268,14 +356,25 @@ Use strings for the plain case. Use objects when other code already builds actio
 A command may carry its handler, or only be a **contract** (name + types) with the work registered elsewhere — another file, or a fake in a test.
 
 ```js
-import { createBus } from "nanoeffects";
-import { createCommand, commandsPlugin } from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { commandsPlugin } from "nanoeffects/actions";
+
+export const bus = createBus();
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(commandsPlugin());
+export const commands = bus.use(commandsPlugin());
+```
+
+```js
+import { bus, commands } from "./bus";
+import { getUser } from "./user";
 
 bus.emit(getUser("1")); // throws: No handler for command "user/get"
 
@@ -296,16 +395,27 @@ Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can reg
 **What you do.** `createModule(name, setup)` describes the feature. `bus.use(modulePlugin([…]))` mounts it. `app.unmount(module)` undoes everything the setup registered.
 
 ```js
-import { createBus } from "nanoeffects";
-import { createCommand, createModule, modulePlugin } from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // contract — no handler yet
-const double = createCommand("math/double", (value) => value * 2); // carries its handler
+export const getUser = createCommand("user/get"); // contract — no handler yet
+```
 
-const bus = createBus();
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
+
+export const double = createCommand("math/double", (value) => value * 2); // carries its handler
+```
+
+```js
+// greeting-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser } from "./user";
+import { double } from "./math";
 
 // createModule — one feature; name is stable for hot reload replace
-const greeting = createModule("greeting", (m) => {
+export const greeting = createModule("greeting", (m) => {
   // m.on — like bus.on, removed automatically on unmount
   m.on("greet", (name) => console.log(`hello ${name}`));
 
@@ -315,9 +425,23 @@ const greeting = createModule("greeting", (m) => {
   // m.use — register a command that already has a handler, for this module’s life
   m.use(double);
 });
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { greeting } from "./greeting-module";
 
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([greeting]));
+export const app = bus.use(modulePlugin([greeting]));
+```
+
+```js
+import { app, bus } from "./bus";
+import { greeting } from "./greeting-module";
+
 bus.emit("greet", "Ada"); // hello Ada
 app.unmount(greeting); // greet listener and getUser binding are gone
 ```
@@ -389,6 +513,8 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
 | `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
+| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
+| `nanoeffects/oop` | `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` |
@@ -396,6 +522,8 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/dev` | `devPlugin` (no-op in production) |
 | `nanoeffects/trace` | `createTracer` and the loggers |
 
+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.
+
 ## Give the docs to an AI assistant
 
 The package ships two plain-text files for assistants that write code with it:
@@ -405,6 +533,294 @@ The package ships two plain-text files for assistants that write code with it:
 
 Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.
 
+---
+Source: docs/plugins.md
+
+# Choose the plugins of a bus
+
+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.
+
+## 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 }))`).
+
+## Main plugins
+
+These four cover what most apps need: shared dependencies, effects, commands and modules. Start here.
+
+| Plugin | What it gives you | Import | `bus.use` returns |
+| ------ | ----------------- | ------ | ----------------- |
+| [`contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin) | Your own fields (a store, a client, a logger) on `ctx` of every handler. | `nanoeffects` | The same bus, typed with the fields |
+| [`effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin) | `race`, `all`, `delay` and your own effects on `ctx`, called without passing `ctx`. | `nanoeffects/effects` | The same bus, typed with the effects |
+| [`commandsPlugin`](#let-a-test-replace-a-handler-commandsplugin) | The handlers of commands in a registry, so a test can replace one. | `nanoeffects/actions` | The registry `{ run, handle }` |
+| [`modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin) | A module: the listeners, handlers and tasks of one domain, mounted and unmounted with one call. | `nanoeffects/actions` | The app `{ mount, unmount, isMounted, dispose, commands, createModule }` |
+
+### Put a store or a client on every handler: `contextPlugin`
+
+Every task gets the same fields on `ctx`: a store, an API client, a logger. The types come from the values. More in [Context fields](context.md).
+
+```js
+import { contextPlugin, createBus } from "nanoeffects";
+
+// contextPlugin — every handler gets ctx.store
+const bus = createBus().use(contextPlugin({ store }));
+
+bus.on("save", (draft, { store }) => store.put(draft));
+```
+
+### 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).
+
+```js
+import { createBus } from "nanoeffects";
+import { delay, effectsPlugin, race } from "nanoeffects/effects";
+
+// effectsPlugin — race and delay are bound to the task of each handler
+const bus = createBus().use(effectsPlugin({ race, delay }));
+
+bus.on("load", async (id, { race, delay }) => {
+  const result = await race({
+    data: ({ signal }) => api.get(id, { signal }),
+    timeout: () => delay(5000),
+  });
+});
+```
+
+### Let a test replace a handler: `commandsPlugin`
+
+Commands get their handlers from a registry that belongs to the bus. A command can be only a contract, and a test binds a fake. More in [Actions](actions.md#describe-events-commands-and-jobs).
+
+```js
+import { createBus } from "nanoeffects";
+import { commandsPlugin, createCommand } from "nanoeffects/actions";
+
+const getUser = createCommand("user/get"); // a contract: no handler yet
+const bus = createBus();
+
+// commandsPlugin — the registry of handlers of this bus
+const commands = bus.use(commandsPlugin());
+
+commands.handle(getUser, async (id) => ({ id })); // the latest binding wins
+const user = await bus.emit(getUser("1")); // { id: "1" }
+```
+
+### Mount a domain as one unit: `modulePlugin`
+
+A module groups the listeners, the bound commands and the background tasks of one domain, and ends all of them when it is unmounted. It also makes [hot reload](hmr.md) work. More in [Modules](actions.md#mount-domains-with-modules).
+
+```js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// modulePlugin — mounts userModule on the first use of the app or the bus, and returns the app
+const app = bus.use(modulePlugin([userModule]));
+
+app.unmount(userModule); // its listeners, bound commands and tasks are gone
+```
+
+## Extra plugins
+
+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-command-its-own-fields-scopeplugin) | Its own fields for one command, action, job or module, and a way to replace them in one `emit`. | `nanoeffects/scope` | The same bus |
+| [`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` |
+| [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) | A React hook that emits when a value of a component changes. | `nanoeffects/react` | The same bus, with `useEmitter` |
+| [`devPlugin`](#find-leaks-while-you-develop-devplugin) | Warnings about listeners that pile up, and messages about modules, while you develop. | `nanoeffects/dev` | A function that disconnects it |
+
+### Give one command its own fields: `scopePlugin`
+
+A command, an action, a job or a module can carry its own fields and effects, and one `emit` can replace them. A test gives a fake to one call. More in [Scopes](scope.md).
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scope of a command work on this bus
+const bus = createBus().use(scopePlugin());
+
+// the last argument: fields of this command only
+const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
+  api,
+});
+
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+bus.emit(getUser("1"), { api: fakeApi }); // a fake api for this call only
+```
+
+### Listen to a group of events: `matchPlugin`
+
+`on`, `once` and `off` take a function that picks the events, such as every `user/*` event. A type guard narrows the payload. The subscription listens to every event, so for a few known events `on(creator, handler)` is cheaper. More in the [Guide](guide.md#pick-events-with-a-function).
+
+```js
+import { createBus } from "nanoeffects";
+import { matchPlugin } from "nanoeffects/match";
+
+// matchPlugin — on takes a function that picks the events
+const bus = createBus().use(matchPlugin());
+
+bus.on(
+  (action) => action.type.startsWith("user/"),
+  (payload, ctx) => console.log(ctx.type, payload),
+);
+```
+
+### Hand the bus to a state manager: `emitterPlugin`
+
+`bus.emitter(creator)` is a callback that emits an action. A state manager takes it as its subscription callback, so a change of the store becomes an event. More in [Stores](stores.md#emit-from-a-state-manager).
+
+```js
+import { atom } from "nanostores";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+
+// emitterPlugin — adds bus.emitter
+const bus = createBus().use(emitterPlugin());
+const nameChanged = createAction("name/changed");
+const $name = atom("");
+
+$name.listen(bus.emitter(nameChanged)); // every change of $name emits nameChanged
+```
+
+### Tell the bus when a React value changes: `reactPlugin`
+
+`useEmitter(event, value)` emits after a render commits with a new value. It does not emit on mount, and not twice under StrictMode. It needs React 18 or newer. More in [Stores](stores.md#react-sharing-a-value-across-components).
+
+```jsx
+import { useState } from "react";
+import { createBus } from "nanoeffects";
+import { reactPlugin } from "nanoeffects/react";
+
+// reactPlugin — adds bus.useEmitter; destructuring gives a free hook
+const bus = createBus().use(reactPlugin());
+const { useEmitter } = bus;
+
+function Profile() {
+  const [name, setName] = useState("");
+  useEmitter("name/changed", name); // emits after a render with a new name
+  return <input value={name} onChange={(event) => setName(event.target.value)} />;
+}
+```
+
+### Find leaks while you develop: `devPlugin`
+
+It warns about listeners that were added and never unbound, and reports the modules that are mounted, replaced and unmounted. In a production build `nanoeffects/dev` is empty, so the call can stay. More in [Hot reload](hmr.md#report-leaks-with-devplugin).
+
+```js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { devPlugin } from "nanoeffects/dev";
+
+const bus = createBus();
+bus.use(modulePlugin([userModule]));
+
+// devPlugin — warnings and messages in the console while you develop;
+// it finds the app of modulePlugin on the bus, whichever you use first
+const disconnect = bus.use(devPlugin());
+
+disconnect(); // stops the diagnostics
+```
+
+## Put them together
+
+One bus with every plugin that does not need React, in a file of its own. The events of the app stay in other files. The plugins work in any order; the next section says what that means for modules.
+
+```js
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import {
+  commandsPlugin,
+  emitterPlugin,
+  modulePlugin,
+} from "nanoeffects/actions";
+import { devPlugin } from "nanoeffects/dev";
+import { all, effectsPlugin, race } from "nanoeffects/effects";
+import { matchPlugin } from "nanoeffects/match";
+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(matchPlugin()) // bus.on takes a function that picks the events
+  .use(emitterPlugin()); // bus.emitter(creator)
+
+// commandsPlugin — the registry of command handlers; keep it to bind handlers later
+export const commands = bus.use(commandsPlugin());
+
+// modulePlugin — mounts userModule on the first use; keep app to mount and unmount later
+export const app = bus.use(modulePlugin([userModule]));
+
+// devPlugin — reports leaks and modules while you develop; keep disconnect to remove it
+export const disconnect = bus.use(devPlugin());
+```
+
+## Use them in any order
+
+The plugins give the same result in any order. Use them as they read best, and put the app of `modulePlugin` where you keep it.
+
+Two things happen because modules are mounted late:
+
+- **Modules start on the first use.** `modulePlugin([userModule])` mounts `userModule` when the app or the bus is first used: the first `bus.emit`, or the first call of `app.mount`, `app.unmount`, `app.isMounted`, `app.dispose` or the read of `app.commands`. By then every plugin is on the bus, so a module and the tasks it spawns have the fields, effects and scopes of the plugins you used after `modulePlugin`, and `m.on(fn, handler)` works with `matchPlugin`.
+- **Listeners keep their place.** A `bus.on` after `bus.use(modulePlugin(...))` is held until the modules are mounted, then made, in the order you wrote them. The listeners of a module therefore stay ahead of the ones registered after the plugin, and behind the ones registered before it. The function `bus.on` returns works before and after.
+
+Other plugins do not need an order for another reason:
+
+- `commandsPlugin` binds its list in the registry that the bus has, so it can come before or after `modulePlugin`. A custom `bus.commands = { run }` is replaced.
+- `effectsPlugin` and `contextPlugin` do not replace a field that is on `ctx` already, so a scope wins in any order.
+- `devPlugin()` finds the app that `modulePlugin` put on the bus (`bus.app`). `devPlugin({ app })` still works.
+- `matchPlugin` and `devPlugin` both wrap `bus.on`; `devPlugin` counts a function that picks events under `"*"`, and its `disconnect` leaves a wrapper that was put on top of it.
+
+A name that is already a context field of the bus is a type error when `contextPlugin` or `effectsPlugin` adds it again.
+
+A test puts every plugin on a bus in many orders and checks what each one does (`src/tests/plugin-matrix.test.ts`). An order that breaks something is a bug.
+
+## See what is not a plugin
+
+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).
+
+## Write your own plugin
+
+A plugin is a function of the bus that returns what you want back. The bus keeps no list of plugins, so a plugin that was used cannot be taken out by the bus; it returns its own `stop` or `disconnect` when it needs one.
+
+```js
+// count-plugin.js
+// your own plugin: a function of the bus that returns what you want back
+export const countPlugin = (bus) => {
+  let count = 0;
+  const unbind = bus.on("*", () => {
+    count += 1;
+  });
+  return { count: () => count, stop: unbind };
+};
+```
+
+```js
+import { createBus } from "nanoeffects";
+import { countPlugin } from "./count-plugin";
+
+const bus = createBus();
+// use — calls countPlugin(bus) and returns its result
+const counter = bus.use(countPlugin);
+
+bus.emit("greet", "Ada");
+console.log(counter.count()); // 1
+counter.stop();
+```
+
 ---
 Source: docs/policies.md
 
@@ -876,14 +1292,28 @@ Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
 ## Return a value from `emit` with a command
 
+The bus lives in one file and its events in another, so any module can import both without a cycle.
+
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 
-const bus = createBus();
+// createBus — one bus for the app
+export const bus = createBus();
+```
+
+```js
+// math.js
+import { createCommand } from "nanoeffects/actions";
 
 // createCommand — emit runs the handler and returns its result
-const double = createCommand("math/double", (value) => value * 2);
+export const double = createCommand("math/double", (value) => value * 2);
+```
+
+```js
+import { bus } from "./bus";
+import { double } from "./math";
+
 bus.emit(double(21)); // 42
 ```
 
@@ -892,27 +1322,30 @@ bus.emit(double(21)); // 42
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
 ```js
+// user.js
 import { createAction, createCommand, createJob } from "nanoeffects/actions";
 
 // createAction — event with a payload (like RTK createAction)
-const userLoaded = createAction("user/loaded");
-const loadFailed = createAction("user/failed");
+export const userLoaded = createAction("user/loaded");
+export const loadFailed = createAction("user/failed");
 
 // createCommand with a handler — emit returns what the handler returns
-const getUser = createCommand("user/get", (id, { signal }) => {
+export const getUser = createCommand("user/get", (id, { signal }) => {
   return fetchUser(id, { signal });
 });
 
 // createCommand without a handler — a contract; register the work elsewhere
-const sendMail = createCommand("mail/send");
+export const sendMail = createCommand("mail/send");
 
 // createJob — command that also emits success / fail actions
-const loadUser = createJob("user/load", fetchUser, {
+export const loadUser = createJob("user/load", fetchUser, {
   success: userLoaded,
   fail: "user/failed",
 });
 ```
 
+These are the events of the user domain, in a file of their own (`user.js`). The bus is made in another file (`bus.js` below), and neither imports the other.
+
 ### 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")`.
@@ -933,22 +1366,22 @@ Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(comm
 **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.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import {
-  bindHandler,
-  commandsPlugin,
-  createCommand,
-} from "nanoeffects/actions";
-
-const sendMail = createCommand("mail/send");
-const getUser = createCommand("user/get");
+import { bindHandler, commandsPlugin } from "nanoeffects/actions";
+import { sendMail } from "./user";
 
-const bus = createBus();
+export const bus = createBus();
 
 // commandsPlugin — registry of handlers for this bus
-const commands = bus.use(
+export const commands = bus.use(
   commandsPlugin([bindHandler(sendMail, smtpSend)]),
 );
+```
+
+```js
+import { commands } from "./bus";
+import { getUser } from "./user";
 
 // later, e.g. in a test — latest binding wins
 const unbind = commands.handle(getUser, async () => fakeUser);
@@ -957,7 +1390,7 @@ unbind();
 
 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 }`.
+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 `commandsPlugin` binds its list in that registry and returns it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
 
 ### Jobs
 
@@ -980,18 +1413,20 @@ The registry lives in `nanoeffects/actions`, so a bus without one carries none o
 `bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `commands`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
 
 ```js
-import { createBus } from "nanoeffects";
-import {
-  createCommand,
-  createModule,
-  modulePlugin,
-} from "nanoeffects/actions";
+// user.js
+import { createCommand } from "nanoeffects/actions";
+
+export const getUser = createCommand("user/get");
+export const saveUser = createCommand("user/save", persistUser);
+```
 
-const getUser = createCommand("user/get");
-const saveUser = createCommand("user/save", persistUser);
+```js
+// user-module.js
+import { createModule } from "nanoeffects/actions";
+import { getUser, saveUser } from "./user";
 
 // createModule — one domain; unmount undoes everything below
-const userModule = createModule("user", (m) => {
+export const userModule = createModule("user", (m) => {
   m.handle(getUser, fetchUser);
   m.use(saveUser, authModule);
   m.on("login", (user, ctx) => {
@@ -1001,10 +1436,22 @@ const userModule = createModule("user", (m) => {
     /* background work; ends when the module unmounts */
   });
 });
+```
 
-const bus = createBus();
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { userModule } from "./user-module";
+
+export const bus = createBus();
 // modulePlugin — mount modules on the bus
-const app = bus.use(modulePlugin([userModule]));
+export const app = bus.use(modulePlugin([userModule]));
+```
+
+```js
+import { app } from "./bus";
+import { getUser } from "./user";
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
 app.commands.handle(getUser, fakeUser); // in a test
@@ -1015,6 +1462,7 @@ app.dispose(); // unmounts every module
 - **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.
+- **The given modules are mounted on the first use** of the app or the bus (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`), so the plugins you use after `modulePlugin` still reach them. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
 - 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.
@@ -1023,20 +1471,32 @@ app.dispose(); // unmounts every module
 
 ## Give a command, an action or a module its own fields
 
-A command can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`effects` binds functions to the task), as the last argument of `createCommand`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
+A command can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createCommand`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
 // scopePlugin — makes the scope of a command work on this bus
-const bus = createBus().use(scopePlugin());
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
 
 // the third argument — fields of this command only
-const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
-  api,
-});
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // a test replaces them for one call
 const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
@@ -1067,7 +1527,7 @@ If you do not have a store yet, use `createBus` from the [Guide](guide.md).
   - [React: sharing a value across components](#react-sharing-a-value-across-components)
   - [Callbacks on every change](#callbacks-on-every-change)
   - [Stop watching a store](#stop-watching-a-store)
-  - [Give the store to every handler](#give-the-store-to-every-handler)
+  - [Change the store from any handler](#change-the-store-from-any-handler)
 
 ## Wire Redux Toolkit to a bus
 
@@ -1078,23 +1538,40 @@ Redux’s `dispatch` → reducers updates **state**. It does not give you first-
 Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts).
 
 ```js
-import { configureStore, createAction } from "@reduxjs/toolkit";
+// bus.js
 import { createBus } from "nanoeffects";
-import { latest } from "nanoeffects/policies";
-import { createEffectsMiddleware } from "nanoeffects/redux";
 
-const userRequested = createAction("user/requested"); // RTK
-const userLoaded = createAction("user/loaded");
+export const bus = createBus(); // the bus of your app; it can exist before the store
+```
+
+```js
+// user.js
+import { createAction } from "@reduxjs/toolkit";
+
+export const userRequested = createAction("user/requested"); // RTK
+export const userLoaded = createAction("user/loaded");
+```
 
-const bus = createBus(); // the bus of your app; it can exist before the store
+```js
+// store.js
+import { configureStore } from "@reduxjs/toolkit";
+import { createEffectsMiddleware } from "nanoeffects/redux";
+import { bus } from "./bus";
 
 // createEffectsMiddleware — actions reach the bus after reducers; tasks get ctx.store
 const effects = createEffectsMiddleware(bus);
 
-const store = configureStore({
+export const store = configureStore({
   reducer,
   middleware: (getDefault) => getDefault().concat(effects),
 });
+```
+
+```js
+// user-handlers.js
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { userLoaded, userRequested } from "./user";
 
 // latest — a newer run aborts the older one
 bus.on(
@@ -1145,28 +1622,44 @@ const effects = createEffectsMiddleware(bus);
 Zustand, MobX, Jotai, Valtio, Nanostores and Pinia have no adapter. Redux is different: use the middleware from the first section, it sends actions to the bus. A plain store works with the bus in two directions, and both are shown for each store below:
 
 - **The store triggers an event.** The store tells you about a change with a callback. You pass that callback `bus.emitter(action)`, and the change becomes an event that starts a handler.
-- **The event changes the store.** The handler reports its result as an event. A listener of the bus writes it into the store.
+- **The event changes the store.** The handler reports its result as an event. A listener of the bus gets the store from `ctx` and changes it with a mutation.
 
 The example is a search box. The store holds two fields: `query`, which the user types, and `results`, which a request fills. A change of `query` starts a debounced search; the search ends with an event that writes `results`.
 
 Writing `(query) => bus.emit(queryChanged(query))` for every subscription repeats the bus and the action. `emitterPlugin` adds `bus.emitter(action)`: it returns that callback for you. The action stays a plain `createAction`, so `bus.emit(queryChanged("nano"))` and `bus.on(queryChanged, …)` work as before.
 
-The bus is the same for every store below. Create it once; each subsection imports it.
+The bus gets the store as context: `contextPlugin({ store })` puts it on every task as `ctx.store` ([Context fields](context.md)). A handler then changes the store with its mutations and never reaches for the store by name. Only `store.js` is different for each store below. It exports a `store` with the same three members:
+
+- `setQuery(query)` and `setResults(items)` are the mutations. The user's input calls the first, the handler calls the second.
+- `onQueryChanged(callback)` tells you about a change of `query`, and returns the function that stops it.
+
+The bus, the events, the handlers and the link from the store to the bus are the same for every store, each in a file of its own: the bus knows no events, and the events know no bus.
 
 ```js
-// search-bus.js
-import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { debounce, latest } from "nanoeffects/policies";
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+import { store } from "./store";
+
+export const bus = createBus()
+  .use(emitterPlugin()) // adds bus.emitter
+  .use(contextPlugin({ store })); // ctx.store on every task
+```
 
-export const bus = createBus().use(emitterPlugin()); // adds bus.emitter; returns the same bus
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
 // createAction — plain action creators; calling one only builds { type, payload }
 export const queryChanged = createAction("search/queryChanged");
 export const searchLoaded = createAction("search/loaded");
+```
 
-// bus.emitter: a callback (query) => bus.emit(queryChanged(query))
-export const emitQueryChanged = bus.emitter(queryChanged);
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 // debounce — wait 300 ms of quiet; latest — abort the search of the previous query
 bus.on(
@@ -1180,141 +1673,199 @@ bus.on(
     }),
   ),
 );
+
+// event → store: the store comes from ctx, and a mutation changes it
+bus.on(searchLoaded, (items, { store }) => {
+  store.setResults(items);
+});
+```
+
+```js
+// connect.js
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+import { store } from "./store";
+
+// store → event: bus.emitter turns the callback into an emit of queryChanged
+export const stopQuery = store.onQueryChanged(bus.emitter(queryChanged));
 ```
 
 Write `results` and never the field you watch: a handler that changed `query` would start itself again. Find your store below.
 
 ### Nanostores
 
-`listen` calls back with the new value. `subscribe` would also call at once, with the current value, so use `listen`.
+`action` makes a named mutation of an atom. `listen` calls back with the new value; `subscribe` would also call at once, with the current value, so use `listen`.
 
 ```js
-import { atom } from "nanostores";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+// store.js
+import { action, atom } from "nanostores";
 
 const $query = atom("");
 const $results = atom([]);
 
-// store → bus: listen calls back with the new query on every change
-const stopQuery = $query.listen(emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  $results.set(items);
-});
+export const store = {
+  // action — a named mutation of an atom
+  setQuery: action($query, "setQuery", (target, query) => target.set(query)),
+  setResults: action($results, "setResults", (target, items) => target.set(items)),
+  // listen — calls back with the new query on every change
+  onQueryChanged: (callback) => $query.listen(callback),
+};
 ```
 
 ### MobX
 
-`reaction` watches an expression and calls back with its value. Change observables inside `runInAction`.
+`makeAutoObservable` turns the methods of a class into actions, which is where MobX wants changes to happen. `reaction` watches an expression and calls back with its value.
+
+<!-- docs-check: fork -->
 
 ```js
-import { observable, reaction, runInAction } from "mobx";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+// store.js
+import { makeAutoObservable, reaction } from "mobx";
 
-const search = observable({ query: "", results: [] });
+class SearchStore {
+  query = "";
+  results = [];
 
-// store → bus: reaction watches the expression and calls back with its value
-const stopQuery = reaction(() => search.query, emitQueryChanged);
+  constructor() {
+    makeAutoObservable(this); // the methods below become actions
+  }
 
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  runInAction(() => {
-    search.results = items;
-  });
-});
+  setQuery(query) {
+    this.query = query;
+  }
+
+  setResults(items) {
+    this.results = items;
+  }
+
+  // reaction — watches the expression and calls back with its value
+  onQueryChanged(callback) {
+    return reaction(() => this.query, callback);
+  }
+}
+
+export const store = new SearchStore();
 ```
 
 ### Valtio
 
-`subscribeKey` watches one field of a proxy state. Assign to the proxy to change it.
+`subscribeKey` watches one field of a proxy state. A mutation assigns to the proxy.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { proxy } from "valtio";
 import { subscribeKey } from "valtio/utils";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
 const state = proxy({ query: "", results: [] });
 
-// store → bus: subscribeKey watches one field
-const stopQuery = subscribeKey(state, "query", emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  state.results = items;
-});
+export const store = {
+  setQuery(query) {
+    state.query = query;
+  },
+  setResults(items) {
+    state.results = items;
+  },
+  // subscribeKey — watches one field
+  onQueryChanged: (callback) => subscribeKey(state, "query", callback),
+};
 ```
 
 ### Jotai
 
-`sub` gives no value, so read it yourself. Write with `store.set`.
+`sub` gives no value, so read it yourself. A write-only atom is the mutation, and `set` runs it.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { atom, createStore } from "jotai";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
 const queryAtom = atom("");
 const resultsAtom = atom([]);
-const store = createStore();
-
-// store → bus: sub calls back without a value; store.get reads it
-const stopQuery = store.sub(queryAtom, () => emitQueryChanged(store.get(queryAtom)));
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  store.set(resultsAtom, items);
-});
+const jotai = createStore();
+
+// write-only atoms: the mutations
+const setQueryAtom = atom(null, (_get, set, query) => set(queryAtom, query));
+const setResultsAtom = atom(null, (_get, set, items) => set(resultsAtom, items));
+
+export const store = {
+  setQuery: (query) => jotai.set(setQueryAtom, query),
+  setResults: (items) => jotai.set(setResultsAtom, items),
+  // sub calls back without a value; get reads it
+  onQueryChanged: (callback) =>
+    jotai.sub(queryAtom, () => callback(jotai.get(queryAtom))),
+};
 ```
 
 ### Zustand
 
-With `subscribeWithSelector` the selector picks the field, and the callback is called only when it changes. Without a selector Zustand calls back on every `setState`, with the whole state.
+With `subscribeWithSelector` the selector picks the field, and the callback is called only when it changes. Without a selector Zustand calls back on every `setState`, with the whole state. The mutations are functions in the state.
+
+<!-- docs-check: fork -->
 
 ```js
+// store.js
 import { create } from "zustand";
 import { subscribeWithSelector } from "zustand/middleware";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
 
-const useSearchStore = create(
-  subscribeWithSelector(() => ({ query: "", results: [] })),
+const useSearch = create(
+  subscribeWithSelector((set) => ({
+    query: "",
+    results: [],
+    // the mutations are part of the state
+    setQuery: (query) => set({ query }),
+    setResults: (items) => set({ results: items }),
+  })),
 );
 
-// store → bus: subscribe with a selector calls back with state.query only when it changes
-const stopQuery = useSearchStore.subscribe((state) => state.query, emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  useSearchStore.setState({ results: items });
-});
+export const store = {
+  setQuery: (query) => useSearch.getState().setQuery(query),
+  setResults: (items) => useSearch.getState().setResults(items),
+  // a selector: called back with state.query only when it changes
+  onQueryChanged: (callback) => useSearch.subscribe((state) => state.query, callback),
+};
 ```
 
 ### Pinia
 
-Pinia (the store of Vue) keeps reactive objects, and its `$subscribe` reports every mutation of the store, not one field. Watch one getter with Vue's `watch` instead: it calls back with the new value. Assign to the store to change it.
+Pinia (the store of Vue) keeps reactive objects, and its `$subscribe` reports every mutation of the store, not one field. Watch one getter with Vue's `watch` instead: it calls back with the new value. The mutations are the actions of the store.
+
+<!-- docs-check: fork -->
 
 ```js
-import { watch } from "vue";
+// store.js
 import { defineStore } from "pinia";
-import { bus, emitQueryChanged, searchLoaded } from "./search-bus";
+import { watch } from "vue";
 
-// defineStore — Pinia: the state of one store
+// defineStore — Pinia: the state and the actions of one store
 const useSearch = defineStore("search", {
   state: () => ({ query: "", results: [] }),
+  actions: {
+    setQuery(query) {
+      this.query = query;
+    },
+    setResults(items) {
+      this.results = items;
+    },
+  },
 });
 
 const search = useSearch(); // call it after the app has installed Pinia
 
-// store → bus: watch calls back with the new query when search.query changes
-const stopQuery = watch(() => search.query, emitQueryChanged);
-
-// bus → store: bus.on returns the function that removes this listener
-const stopResults = bus.on(searchLoaded, (items) => {
-  search.results = items;
-});
+export const store = {
+  setQuery: (query) => search.setQuery(query),
+  setResults: (items) => search.setResults(items),
+  // watch — calls back with the new query when search.query changes
+  onQueryChanged: (callback) => watch(() => search.query, callback),
+};
 ```
 
 ### React: sharing a value across components
 
+<!-- docs-check: new -->
+
 A value of your UI (a query, a filter, a name) often has two jobs. Several components read it and re-render when it changes, and the bus must hear about each change to start a handler. The recipes below differ in where the value lives. Pick the first one unless a handler must read the value.
 
 | The value lives in | Use when |
@@ -1327,20 +1878,30 @@ A value of your UI (a query, a filter, a name) often has two jobs. Several compo
 
 Writing `useEffect(() => bus.emit(...), [value])` looks enough, but it emits on mount, emits twice on mount under StrictMode, and re-runs when the emit function is new on every render. `useEmitter` from `nanoeffects/react` avoids all three. It emits after a render commits with a changed value, never on mount, and compares with `Object.is`. You need React 18 or newer; no other entry of the package uses React.
 
-First the bus. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export:
+First the bus, the events and the handlers, each in its own file. `reactPlugin()` adds `bus.useEmitter`, and destructuring it gives a plain hook that you export from the bus file:
 
 ```js
-// react-search-bus.js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction } from "nanoeffects/actions";
-import { debounce, latest } from "nanoeffects/policies";
 import { reactPlugin } from "nanoeffects/react";
 
 export const bus = createBus().use(reactPlugin()); // the bus; reactPlugin adds bus.useEmitter
 export const { useEmitter } = bus; // a free hook: it does not read `this`
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
 export const queryChanged = createAction("query/changed");
 export const searchLoaded = createAction("search/loaded");
+```
+
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 // debounce — wait 300 ms of quiet; latest — a newer query aborts the older request
 bus.on(
@@ -1360,7 +1921,8 @@ Then the provider. It holds the state, calls `useEmitter` once, and listens for
 ```jsx
 // SearchProvider.jsx
 import { createContext, useContext, useEffect, useState } from "react";
-import { bus, queryChanged, searchLoaded, useEmitter } from "./react-search-bus";
+import { bus, useEmitter } from "./bus";
+import { queryChanged, searchLoaded } from "./search";
 
 const SearchContext = createContext(null);
 
@@ -1417,6 +1979,8 @@ Two limits to know:
 
 A context is not visible to a bus handler. When a handler needs the current value, keep the value outside React. About twelve lines of `useSyncExternalStore` do it, and `contextPlugin` hands it to every handler as `ctx.query`:
 
+<!-- docs-check: new -->
+
 ```jsx
 // value-store.js
 import { useSyncExternalStore } from "react";
@@ -1446,19 +2010,36 @@ export function createValue(initial) {
 export const useValue = (store) => useSyncExternalStore(store.subscribe, store.get);
 ```
 
-```jsx
-// search-value.jsx
-import { createBus, contextPlugin } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { createValue, useValue } from "./value-store";
+```js
+// query.js
+import { createValue } from "./value-store";
 
-const query = createValue("");
+export const query = createValue("");
+```
+
+```js
+// bus.js
+import { contextPlugin, createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+import { query } from "./query";
 
 // emitterPlugin adds bus.emitter; contextPlugin puts `query` on every task as ctx.query
-const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+export const bus = createBus().use(emitterPlugin()).use(contextPlugin({ query }));
+```
 
-const queryChanged = createAction("query/changed");
-const refreshed = createAction("search/refreshed");
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed");
+export const refreshed = createAction("search/refreshed");
+```
+
+```js
+// search-handlers.js
+import { bus } from "./bus";
+import { query } from "./query";
+import { queryChanged, refreshed } from "./search";
 
 // store → bus: bus.emitter turns the action into a callback; one place, any number of setters
 const emitQueryChanged = bus.emitter(queryChanged);
@@ -1469,6 +2050,12 @@ bus.on(refreshed, async (_payload, ctx) => {
   const items = await api.search(ctx.query.get(), { signal: ctx.signal });
   console.log(items.length);
 });
+```
+
+```jsx
+// SearchBox.jsx
+import { query } from "./query";
+import { useValue } from "./value-store";
 
 // any number of components read and write the same value
 export function SearchBox() {
@@ -1481,16 +2068,31 @@ export function SearchBox() {
 
 With Nanostores, Jotai or Zustand the value already lives outside React and has a subscription. Connect it to the bus once, as in [Nanostores](#nanostores), and read it in components with the library's own hook:
 
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("query/changed");
+```
+
 ```jsx
-// search-atom.jsx
+// SearchBox.jsx
 import { atom } from "nanostores";
 import { useStore } from "@nanostores/react";
-import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
 const $query = atom("");
-const queryChanged = createAction("query/changed");
 
 // listen, not subscribe: listen skips the call with the current value at start
 $query.listen(bus.emitter(queryChanged));
@@ -1505,16 +2107,28 @@ export function SearchBox() {
 
 React may run a reducer more than once for one dispatch (twice in StrictMode), so a `bus.emit` inside it fires twice. Dispatch to the reducer first, then emit, from one helper. Or keep the state in a reducer and pass it to `useEmitter` like any other value.
 
-```jsx
-// search-reducer.jsx
-import { useReducer } from "react";
+<!-- docs-check: new -->
+
+```js
+// bus.js
 import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: created once
+```
+
+```js
+// search.js
 import { createAction } from "nanoeffects/actions";
 
-const bus = createBus(); // the bus: created once
+export const queryChanged = createAction("query/changed");
+export const queryCleared = createAction("query/cleared");
+```
 
-const queryChanged = createAction("query/changed");
-const queryCleared = createAction("query/cleared");
+```jsx
+// Search.jsx
+import { useReducer } from "react";
+import { bus } from "./bus";
+import { queryChanged, queryCleared } from "./search";
 
 function reducer(state, action) {
   if (queryChanged.match(action)) {
@@ -1554,11 +2168,11 @@ The stores above call back only when the value changed, so the emitter does not
 
 ### Stop watching a store
 
-Stop both directions with what the calls returned: `stopQuery` from the store and `stopResults` from `bus.on`. Call them yourself, or hand them over: `onAbort(ctx, stopQuery)` inside a task, or `m.signal.addEventListener("abort", stopQuery)` in a module.
+`connect.js` keeps the function that `onQueryChanged` returned (`stopQuery`). Call it yourself, or hand it over: `onAbort(ctx, stopQuery)` inside a task, or `m.signal.addEventListener("abort", stopQuery)` in a module. To stop the other direction, remove the listener of `searchLoaded` with `bus.off(searchLoaded, handler)`, or register it in a module, which removes it on unmount.
 
-### Give the store to every handler
+### Change the store from any handler
 
-Instead of a listener per store, give the store to all tasks with `createBus({ context: { store } })` ([Context fields](context.md)) and change it from any handler (`setState`, a MobX action, a Pinia store). The same rule holds: write the field you do not watch. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.
+A handler gets the store from `ctx.store` and calls a mutation, whatever it handles: not only the result of a search. The same rule holds: write the field you do not watch. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.
 
 ---
 Source: docs/react.md
@@ -1581,19 +2195,26 @@ Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one p
 
 ## Wire the bus once
 
-Put the bus and its handlers in their own file. Create it once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
+Keep the bus in a file of its own, and the handlers of the form in another. Create the bus once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
 
 ```js
-// registration.js
+// bus.js
 import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: created once, at the top of the module
+```
+
+The handlers know the bus and the bus knows nothing of them. They register when `registration.js` is imported, once, when the app starts:
+
+```js
+// registration.js
 import { retry } from "nanoeffects/effects";
 import { debounce, latest, leading } from "nanoeffects/policies";
+import { bus } from "./bus";
 
 // fetch rejects with a TypeError when the network fails; an HTTP error is a plain Error
 const isNetworkError = (error) => error instanceof TypeError;
 
-export const bus = createBus(); // the bus: created once, at the top of the module
-
 // debounce — wait 300 ms of quiet; latest — abort the check of the previous name
 bus.on(
   "username/typed",
@@ -1631,12 +2252,15 @@ The handlers know nothing about React. A test can emit `username/typed` and read
 
 ## Connect the form
 
+<!-- docs-check: continue -->
+
 The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount.
 
 ```jsx
 // SignUpForm.jsx
 import { useEffect, useState } from "react";
-import { bus } from "./registration"; // the bus of the previous snippet
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./registration"; // registers the handlers; the app does this once, when it starts
 
 export function SignUpForm() {
   const [name, setName] = useState("");
@@ -1699,6 +2323,8 @@ In development, React StrictMode runs the effect twice (subscribe, unsubscribe,
 
 ## Stop running work when the form closes
 
+<!-- docs-check: continue -->
+
 Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
 
 ```js
@@ -1790,7 +2416,7 @@ Source: docs/scope.md
 
 Optional, for domain logic. Use it when one command needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
 
-A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
+A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `$effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
 
 You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
 
@@ -1799,27 +2425,29 @@ You give a scope to the thing that uses it. A call can replace it. Nothing else
 Scopes are a plugin, so a bus that does not use them pays nothing.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
 import { scopePlugin } from "nanoeffects/scope";
 
 // scopePlugin — makes the scopes below work on this bus; returns the same bus
-const bus = createBus().use(scopePlugin());
+export const bus = createBus().use(scopePlugin());
 ```
 
+The bus is in one file and the commands and actions in files named after their domain, so the next example imports `bus` from here. Each section after it keeps its own `bus.js` and domain file, as if it were an app of its own.
+
 - Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
-- Use it **after** `effectsPlugin` (an effect it adds later would be assigned over an effect of a scope with the same name) and **before** `modulePlugin` (it mounts the modules when it is used). `contextPlugin` and `createBus({ context })` can come in any order: a scope wins over them.
+- Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
 
 ## Give a command its own fields
 
+<!-- docs-check: continue -->
+
 ```js
-import { createBus } from "nanoeffects";
+// user.js
 import { createCommand } from "nanoeffects/actions";
-import { scopePlugin } from "nanoeffects/scope";
-
-const bus = createBus().use(scopePlugin());
 
 // createCommand — third argument is the scope of this command
-const getUser = createCommand(
+export const getUser = createCommand(
   "user/get",
   (id, { api, cache }) => {
     // api and cache are on ctx for this command only
@@ -1827,6 +2455,11 @@ const getUser = createCommand(
   },
   { api, cache: new Map() },
 );
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 const user = await bus.emit(getUser("1")); // the handler has api and cache
 ```
@@ -1835,21 +2468,18 @@ The listeners of `"user/get"` get the same fields when the command is emitted, b
 
 ## Bind an effect to the task
 
-An effect is a function with `{ signal }` as its first parameter. In `effects` it is bound to the task, so it stops with the task.
+An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
 
 ```js
-import { createBus } from "nanoeffects";
+// feed.js
 import { createCommand } from "nanoeffects/actions";
 import { delay, race } from "nanoeffects/effects";
-import { scopePlugin } from "nanoeffects/scope";
-
-const bus = createBus().use(scopePlugin());
 
 // your own effect: first parameter is the task (only its signal is used)
 const fetchJson = (ctx, url) =>
   fetch(url, { signal: ctx.signal }).then((response) => response.json());
 
-const loadFeed = createCommand(
+export const loadFeed = createCommand(
   "feed/load",
   (url, { fetchJson, race, delay }) =>
     // race, delay, fetchJson — bound to this task: no ctx argument
@@ -1857,30 +2487,56 @@ const loadFeed = createCommand(
       feed: () => fetchJson(url),
       timeout: () => delay(5000),
     }),
-  // effects — built-in and your own functions share one object
-  { effects: { fetchJson, race, delay } },
+  // $effects — built-in and your own functions share one object
+  { $effects: { fetchJson, race, delay } },
 );
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+import { bus } from "./bus";
+import { loadFeed } from "./feed";
 
 const result = await bus.emit(loadFeed("/feed"));
 ```
 
-- Put in `effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
-- A function under any other key is copied as it is; a function in `effects` is bound.
-- `effects` is the one name a field of the scope cannot have.
+- Put in `$effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
+- A function under any other key is copied as it is; a function in `$effects` is bound.
+- `$effects` is the one name with a meaning. A field called `effects` is an ordinary field: `{ effects: { retries: 3 } }` puts that object on `ctx`, and nothing in it is bound.
 
 ## Replace a field for one call
 
 The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
 
 ```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
-const bus = createBus().use(scopePlugin());
-const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
-  api,
-});
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // the real api for this call
 await bus.emit(getUser("1"));
@@ -1894,29 +2550,36 @@ Rules for the second argument:
 
 - It works with an action or a command call (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
 - It does not work with the string form: in `emit("user/get", payload)` the second argument is the payload.
-- It can replace `effects` too: `{ effects: { delay: instantDelay } }`.
+- It can replace `$effects` too: `{ $effects: { delay: instantDelay } }`.
 - Fields of the library (`signal`, `emit`, …) in it are ignored.
 
 ## Give an action, a job or a module its own fields
 
 ```js
-import { createAction, createJob, createModule } from "nanoeffects/actions";
+// user.js
+import { createAction, createJob } from "nanoeffects/actions";
 
 // createAction — the listeners of this action's calls get the fields
-const userLoaded = createAction("user/loaded", { store });
+export const userLoaded = createAction("user/loaded", { store });
 
 // createJob — the scope is the fourth argument, after the outcomes;
 // the handler and the listeners of the outcome get its fields
-const loadUser = createJob(
+export const loadUser = createJob(
   "user/load",
   fetchUser,
   { success: userLoaded, fail: "user/failed" },
   { logger },
 );
+```
+
+```js
+// audit-module.js
+import { createModule } from "nanoeffects/actions";
+import { userLoaded } from "./user";
 
 // createModule — third argument; everything the module owns gets the fields:
 // m.on listeners, m.handle handlers, m.spawn tasks
-const auditModule = createModule(
+export const auditModule = createModule(
   "audit",
   (m) => {
     m.on(userLoaded, (user, { logger }) => logger.info(user.id));
@@ -1925,6 +2588,8 @@ const auditModule = createModule(
 );
 ```
 
+If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
+
 A module scope does not leak: a listener registered outside the module does not see it.
 
 ## Which value wins
@@ -1942,25 +2607,26 @@ The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`
 
 ## Keep a generic effect generic
 
-In `effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
 
 `effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
 
 ```js
+// pick.js
 import { createCommand } from "nanoeffects/actions";
 import { effect } from "nanoeffects/scope";
 
 // effect — marks the function, so a scope binds it to the task; the editor keeps its generic
 const first = effect((ctx, items) => items[0]);
 
-const pick = createCommand("pick", (items, { first }) => first(items), {
-  first, // a plain key of the scope, not an entry of effects
+export const pick = createCommand("pick", (items, { first }) => first(items), {
+  first, // a plain key of the scope, not an entry of `$effects`
 });
 ```
 
 Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
 
-`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `effects`.
+`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
 
 ```ts
 import { createCommand } from "nanoeffects/actions";
@@ -1975,7 +2641,7 @@ const first: Effect<First> = (ctx, items) => items[0];
 const pick = createCommand(
   "pick",
   (id: string, { first }) => first([id]), // string
-  { effects: { first } },
+  { $effects: { first } },
 );
 ```
 
@@ -2010,8 +2676,298 @@ const getUser = createCommand(
 - No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
 - The fields of the bus are not in the handler of a command made with `createCommand(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
 - The string form of `emit` takes no scope.
-- `effect(fn)` works only as a value of a scope, not as an entry of `effects`.
-- A scope on a command, action, job or module is typed without the events of a bus, so `take` in its `effects` takes any event name.
+- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
+- A scope on a command, action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.
+
+---
+Source: docs/oop.md
+
+# Use the bus from a class
+
+Use this page when **your domain logic lives in classes**: a service, a store or a controller that needs the bus inside its methods. A class made with `extendBus` has `on`, `emit` and the other methods of the bus, and remembers what each instance subscribed to, so `dispose()` ends it all.
+
+If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
+
+## 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.
+
+## Give a class the methods of a bus
+
+`extendBus(bus, Base)` returns a subclass of `Base`. Its instances have the methods of the bus, and the arguments of `new` go to the constructor of `Base`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus that the services of the app share
+export const bus = createBus();
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the events of the search domain
+export const queryChanged = createAction("search/query-changed");
+export const resultsLoaded = createAction("search/results-loaded");
+```
+
+```js
+// search-service.js
+import { extendBus } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged, resultsLoaded } from "./search";
+
+class SearchServiceBase {
+  constructor(api) {
+    this.api = api;
+    // this.on — a subscription of this instance; dispose() removes it
+    this.on(queryChanged, (query, ctx) => this.search(query, ctx)); // an arrow keeps this
+  }
+
+  async search(query, { signal, emit }) {
+    const items = await this.api.search(query, { signal });
+    emit(resultsLoaded(items));
+  }
+}
+
+// extendBus — a subclass whose instances have on, once, off, emit and dispose
+export const SearchService = extendBus(bus, SearchServiceBase);
+```
+
+```js
+import { queryChanged } from "./search";
+import { SearchService } from "./search-service";
+
+const service = new SearchService(api); // the arguments go to SearchServiceBase
+service.emit(queryChanged("nano")); // the same bus as bus.emit
+service.dispose(); // its subscriptions are gone
+```
+
+What you get:
+
+- The class keeps the name of `Base`, and its instances are instances of `Base`.
+- `on`, `once`, `off` and `emit` act on the bus. They can be destructured: `const { emit } = service`.
+- The other methods of the bus, such as `emitter` from [`emitterPlugin`](plugins.md), are there too. Only the plugins used **before** `extendBus` count: the names are taken when it runs.
+- `bus` is the bus, and `Class.bus` is the same one.
+- `this.on` works in the constructor of `Base`. The methods exist on the prototype of the subclass, which is the prototype of the instance already.
+
+## Let the class make its bus
+
+Leave the bus out and the class gets its own, shared by all of its instances.
+
+```js
+// notifier.js
+import { extendBus } from "nanoeffects/oop";
+
+class NotifierBase {}
+
+// extendBus without a bus — a new bus for this class; two classes have two buses
+export const Notifier = extendBus(NotifierBase);
+
+const first = new Notifier();
+const second = new Notifier();
+second.on("notified", (message) => console.log(message));
+first.emit("notified", "hello"); // the instances share Notifier.bus
+```
+
+Pass a bus when you need plugins (`contextPlugin`, `scopePlugin`) or when several classes talk to each other.
+
+## End the subscriptions with `dispose`
+
+`dispose()` removes every subscription made through `this.on` and `this.once` of that instance, and nothing else. It is safe to call twice. `instance[Symbol.dispose]()` does the same, so `using service = new SearchService(api)` works where the runtime supports it.
+
+```js
+// dispose.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+const bus = createBus();
+const Service = extendBus(bus, class {});
+
+const service = new Service();
+const stop = service.on("ping", () => console.log("service heard it"));
+bus.on("ping", () => console.log("the bus heard it")); // not a subscription of the service
+
+service.dispose();
+bus.emit("ping"); // only "the bus heard it"
+stop(); // the function on returned still works, and does nothing now
+```
+
+A subscription that you removed yourself (the function `on` returned, `this.off`, or a `once` that fired) is forgotten, so the instance holds nothing for it.
+
+## Keep a method of your own
+
+The class wins any clash of names. If `Base` has `emit`, `dispose`, `on` or `bus`, yours stays and the bus method is not added. A `Base` with its own `dispose` would never end the subscriptions, so call `disposeBus(this)` from there.
+
+```js
+// cache.js
+import { createBus } from "nanoeffects";
+import { disposeBus, extendBus } from "nanoeffects/oop";
+
+const bus = createBus();
+
+class CacheBase {
+  dispose() {
+    this.items.clear(); // your own cleanup
+    disposeBus(this); // disposeBus — ends the subscriptions of this instance
+  }
+
+  items = new Map();
+}
+
+export const Cache = extendBus(bus, CacheBase);
+```
+
+`disposeBus` does nothing for a value that is not an instance of such a class.
+
+## Subscribe a method with `@On` and `@Once`
+
+A decorator turns a method into a handler of an event for each instance, with `this` bound. You write no `this.on` in the constructor, and `dispose()` ends the subscription too.
+
+The bus and the events are the same as above, in TypeScript:
+
+```ts
+// bus.ts
+import { createBus } from "nanoeffects";
+
+export const bus = createBus();
+```
+
+```ts
+// search.ts
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction<string>("search/query-changed");
+export const resultsLoaded = createAction<string[]>("search/results-loaded");
+```
+
+```ts
+// search-service.ts
+import { latest } from "nanoeffects/policies";
+import { extendBus, On, Once } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged, resultsLoaded } from "./search";
+
+class SearchServiceBase {
+  // On — this method handles queryChanged for each instance, this is the instance;
+  // latest — each new query aborts the one before it
+  @On(queryChanged, latest)
+  async search(query: string, { signal, emit }: { signal: AbortSignal; emit: (event: unknown) => void }) {
+    const items = await api.search(query, { signal });
+    emit(resultsLoaded(items));
+  }
+
+  // Once — runs for the first event only
+  @Once("search/ready")
+  ready() {
+    console.log("first ready");
+  }
+}
+
+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 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.
+- On a class that `extendBus` did not make, a decorator does nothing.
+- Both the decorators of the language and `experimentalDecorators` work. Your compiler has to support the one you use: TypeScript 5 or newer for the first, and the `experimentalDecorators` option for the second.
+
+## Decorate the class with `@WithBus`
+
+`@WithBus(bus)` does what `extendBus(bus, Base)` does, as a class decorator. `@WithBus()` makes a bus for the class.
+
+<!-- docs-check: continue -->
+
+```ts
+// search-service.ts
+import { type BusMethods, On, WithBus } from "nanoeffects/oop";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+// TypeScript does not change the type of a decorated class, so say what it gets;
+// checker only: at run time WithBus already adds the methods
+interface SearchService extends BusMethods<typeof bus> {}
+
+// WithBus — replaces the class by extendBus(bus, SearchService)
+@WithBus(bus)
+class SearchService {
+  @On(queryChanged)
+  search(query: string) {
+    console.log(query);
+  }
+}
+
+export { SearchService };
+```
+
+Prefer `extendBus(bus, Base)` when you can: its types come from the call and need no `interface`.
+
+## Pass a method by hand
+
+A handler given to `this.on` is called as the bus calls it, with no `this`. A method passed bare loses `this`, as in plain JavaScript:
+
+```js
+// handlers.js
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+class BaseWithHandler {
+  name = "handler";
+
+  handle() {
+    console.log(this?.name);
+  }
+
+  listen() {
+    this.on("ping", this.handle); // this is lost: prints undefined
+    this.on("ping", () => this.handle()); // an arrow keeps it
+  }
+}
+
+export const Listener = extendBus(createBus(), BaseWithHandler);
+```
+
+Use an arrow or a decorated method. The library does not bind `this` for you: a policy such as `latest(this.handle)` wraps the function, so binding would work in half of the cases.
+
+## Type the instances (optional)
+
+`extendBus` returns a class that takes the arguments of `Base`, and its instances are `Base` plus `BusMethods<typeof bus>`: the function members of the bus (`on`, `emit`, and those of plugins used before) with `dispose` and `bus`. A member of `Base` with the same name keeps its own type.
+
+```ts
+// service.ts
+import { createBus } from "nanoeffects";
+import { extendBus } from "nanoeffects/oop";
+
+type Events = { "order/placed": { id: string } };
+
+// Events — checker only: the payloads of the bus
+const bus = createBus<Events>();
+
+class OrderServiceBase {
+  name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+export const OrderService = extendBus(bus, OrderServiceBase);
+
+const service = new OrderService("main"); // the constructor of OrderServiceBase
+service.emit("order/placed", { id: "o1" }); // checked against Events
+```
+
+## What is not done
+
+- `this` is not bound in a handler that you pass by hand (see above).
+- The methods of a plugin used after `extendBus` are not on the class. Use the plugins first, then `extendBus`.
+- One bus for each instance, mixing the methods into an object that exists, and decorators for fields or parameters are not part of this entry.
 
 ---
 Source: docs/typescript.md
@@ -2345,16 +3301,26 @@ The store (`$items`) is not here. Keep it in Effector and update it from the `fo
 
 Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
 
-```jsx
-// search-zustand.jsx
-import { create } from "zustand";
+```js
+// bus.js
 import { createBus } from "nanoeffects";
-import { debounce, latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// search-store.js
+import { create } from "zustand";
 
 // create — Zustand: the store replaces $items
-const useSearchStore = create(() => ({ items: [] }));
+export const useSearchStore = create(() => ({ items: [] }));
+```
 
-const bus = createBus(); // the bus: events and handlers
+```js
+// search-handlers.js
+import { debounce, latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 // latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
 const search = latest(async (query, { signal }) => {
@@ -2363,6 +3329,12 @@ const search = latest(async (query, { signal }) => {
 });
 
 bus.on("query-changed", debounce(300, search));
+```
+
+```jsx
+// Search.jsx
+import { bus } from "./bus";
+import { useSearchStore } from "./search-store";
 
 export function Search() {
   const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
@@ -2438,13 +3410,18 @@ formSubmitted.watch((event) => {
 });
 ```
 
-The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus and the handler, each in its own file:
 
 ```js
-// form-bus.js
+// bus.js
 import { createBus } from "nanoeffects";
 
-export const bus = createBus(); // the bus: events and their handlers
+export const bus = createBus(); // the bus: only the bus
+```
+
+```js
+// form-handlers.js
+import { bus } from "./bus";
 
 // bus.on — the job of sendFormFx: runs when the form is submitted
 bus.on("form/submitted", (values) => {
@@ -2457,7 +3434,8 @@ Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`;
 ```jsx
 // App.jsx
 import { useState } from "react";
-import { bus } from "./form-bus"; // the bus of the previous snippet
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./form-handlers"; // registers the handler; the app does this once, when it starts
 
 function Field({ name, type, label, value, onChange }) {
   return (
@@ -2527,16 +3505,27 @@ Retrying a failed network request, and cancelling when the form closes, are in [
 
 Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
 
-<!-- docs-check: skip - needs effector, which the project does not depend on -->
 ```js
-import { createEvent, createStore } from "effector";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const queryChanged = createAction("query/changed"); // a plain action creator
+```
 
-const queryChanged = createAction("query/changed"); // a plain action creator
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
 
 const found = createEvent(); // Effector: the result comes back as an event
 const $items = createStore([]).on(found, (_, items) => items);
@@ -2659,16 +3648,27 @@ Keep RxJS where a stream is how you think, and let events cross to the bus in ei
 
 **RxJS to bus.** `bus.emitter(action)` returns a callback that emits the action, so it is the argument of `subscribe` ([Stores](stores.md) has the plugin).
 
-<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
 ```js
-import { combineLatest } from "rxjs";
+// bus.js
 import { createBus } from "nanoeffects";
-import { createAction, emitterPlugin } from "nanoeffects/actions";
-import { latest } from "nanoeffects/policies";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+```
+
+```js
+// filters.js
+import { createAction } from "nanoeffects/actions";
 
-const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+export const filtersChanged = createAction("filters/changed"); // a plain action creator
+```
 
-const filtersChanged = createAction("filters/changed"); // a plain action creator
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { combineLatest } from "rxjs";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { filtersChanged } from "./filters";
 
 // RxJS: combine two streams into one value; nanoeffects does not do that
 const subscription = combineLatest([query$, category$]).subscribe(
@@ -2898,7 +3898,7 @@ A `bus.on` outside a module returns the function that unsubscribes: hand it to t
 
 ## Report leaks with `devPlugin`
 
-`bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
+`bus.use(devPlugin())` reports what is easy to miss while developing:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2906,13 +3906,14 @@ import { modulePlugin } from "nanoeffects/actions";
 import { devPlugin } from "nanoeffects/dev";
 
 const bus = createBus();
-const app = bus.use(modulePlugin([userModule]));
+bus.use(modulePlugin([userModule]));
 // devPlugin — warn on piled-up listeners; log module mount/replace/unmount
-bus.use(devPlugin({ app }));
+// (it finds the app of modulePlugin on the bus, in either order of the two)
+bus.use(devPlugin());
 ```
 
 - **Listeners that pile up.** When more than `maxListeners` (default `10`) listeners of one event were added and not unsubscribed, one warning names the event and the count. The count follows the function that `on` returns; `bus.off(event, fn)` is not seen.
-- **Modules.** With `app` it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
+- **Modules.** For the app of `modulePlugin` (or the `app` option) it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
 - **Options.** `leaks: false` and `modules: false` switch a diagnostic off; `maxListeners` sets the limit; `log` receives the messages instead of the console.
 - **Disconnect.** `bus.use(devPlugin(...))` returns the function that stops the diagnostics and puts `bus.on` and `app.mount` back.
 
@@ -2920,6 +3921,6 @@ It changes no behavior: it wraps `bus.on`, `app.mount`, and `app.unmount` and ad
 
 ### Keep the import in production
 
-`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin({ app }))` can stay without a guard: it touches nothing and costs a few bytes.
+`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin())` can stay without a guard: it touches nothing and costs a few bytes.
 
 If you want even the call gone, guard it (`if (import.meta.env.DEV)` in Vite). An app that does not import the entry does not carry it.