nanoeffects 0.26.0 → 0.27.0

package/llms-full.txt

@@ -17,7 +17,7 @@ Source: docs/guide.md
 
 # Guide
 
-Climb one step at a time: small bus → policies → effects → commands and modules. Stop when your project has what it needs.
+Climb one step at a time: small bus → policies → effects → handlers and modules. Stop when your project has what it needs.
 
 | Your project | Stop after |
 | ------------ | ---------- |
@@ -132,7 +132,7 @@ 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.
+- An action creator 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.
 
@@ -320,7 +320,7 @@ More in [Effects](effects.md).
 
 ## 7. Name events three ways
 
-`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).
+`emit` and `on` take a string, an object `{ type, payload }` (a Redux action fits), or a function with a `type` property (action creators and actions).
 
 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.
 
@@ -341,10 +341,10 @@ export const moved = createAction("moved");
 
 ```js
 // math.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } 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);
+// createAction with a handler — emit runs the handler and returns its result
+export const double = createAction("math/double", (value) => value * 2);
 ```
 
 ```js
@@ -361,36 +361,36 @@ bus.on(moved, ({ x }) => console.log(x));
 bus.emit(double(21)); // 42
 ```
 
-Use strings for the plain case. Use objects when other code already builds actions. Use commands when you need a result from `emit`.
+Use strings for the plain case. Use objects when other code already builds actions. Give `createAction` a handler when you need a result from `emit`.
 
-## 8. Register a command handler
+## 8. Bind a handler to an action later
 
-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.
+An action may carry its handler, as `double` above, or get it later from a registry — another file, or a fake in a test. An action with no handler is an event until one is bound.
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-export const getUser = createCommand("user/get"); // contract — no handler yet
+export const getUser = createAction("user/get"); // no handler yet: an event
 ```
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { commandsPlugin } from "nanoeffects/actions";
+import { actionsPlugin } from "nanoeffects/actions";
 
 export const bus = createBus();
-// commandsPlugin — registry of handlers for this bus
-export const commands = bus.use(commandsPlugin());
+// actionsPlugin — registry of handlers for this bus
+export const actions = bus.use(actionsPlugin());
 ```
 
 ```js
-import { bus, commands } from "./bus";
+import { bus, actions } from "./bus";
 import { getUser } from "./user";
 
-bus.emit(getUser("1")); // throws: No handler for command "user/get"
+bus.emit(getUser("1")); // nothing is bound: only an event
 
-const unregister = commands.handle(getUser, (id) => api.user(id));
+const unregister = actions.handle(getUser, (id) => api.user(id));
 const user = await bus.emit(getUser("1"));
 
 unregister();
@@ -400,7 +400,7 @@ Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can reg
 
 ## 9. Mount a domain as a module
 
-**Problem.** A feature owns several things on the bus: who answers `getUser`, who listens to `greet`, maybe a command that already carries its handler. With plain `bus.on` / `commands.handle` you must remember every unsubscribe when the feature goes away. Miss one and listeners pile up.
+**Problem.** A feature owns several things on the bus: who answers `getUser`, who listens to `greet`, maybe an action that already carries its handler. With plain `bus.on` / `actions.handle` you must remember every unsubscribe when the feature goes away. Miss one and listeners pile up.
 
 **When.** Domain logic lives on the bus, off the UI, and you need one mount / one unmount for that feature. Skip modules while a few top-level `bus.on` calls are enough.
 
@@ -408,16 +408,16 @@ Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can reg
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-export const getUser = createCommand("user/get"); // contract — no handler yet
+export const getUser = createAction("user/get"); // no handler yet
 ```
 
 ```js
 // math.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-export const double = createCommand("math/double", (value) => value * 2); // carries its handler
+export const double = createAction("math/double", (value) => value * 2); // carries its handler
 ```
 
 ```js
@@ -434,7 +434,7 @@ export const greeting = createModule("greeting", (m) => {
   // m.handle — this module answers getUser while mounted
   m.handle(getUser, (id) => api.user(id));
 
-  // m.use — register a command that already has a handler, for this module’s life
+  // m.use — register an action that already has a handler, for this module’s life
   m.use(double);
 });
 ```
@@ -459,8 +459,8 @@ app.unmount(greeting); // greet listener and getUser binding are gone
 ```
 
 - **`m.on`** — same job as `bus.on`, scoped to the module’s lifetime.
-- **`m.handle`** — bind a handler to a contract command; gone on unmount.
-- **`m.use`** — bring a command that already carries a handler (or a sub-module). Prefer `handle` when the handler must die with the feature.
+- **`m.handle`** — bind a handler to an action that has none; gone on unmount.
+- **`m.use`** — bring an action that already carries a handler (or a sub-module). Prefer `handle` when the handler must die with the feature.
 
 Modules also make [hot reload](hmr.md) work. Full API in [Actions](actions.md); a longer recipe in [`examples/modules.ts`](../examples/modules.ts).
 
@@ -617,7 +617,7 @@ npm create nanoeffects@latest my-app -- --template domains-ts
 
 For a bigger example, a chat in which parts react to each other, see [Build a chat with entities, features, modules and a small server](chat-example.md). It has more layers than `domains-ts`: when domains must react to each other, it keeps them from importing each other by splitting them into entities and features.
 
-The commands, jobs and modules themselves are explained in [Actions, commands, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
+The commands, jobs and modules themselves are explained in [Actions, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
 
 ## Read the files
 
@@ -643,9 +643,15 @@ Source: docs/motivation.md
 
 # Why nanoeffects exists
 
-Read this page if you build an SDK, a core library or a micro-frontend shell and wonder why you would pick a new event bus. It explains the constraints the library was made for. It does not teach the API: start with the [Guide](guide.md).
+Read this page to see why the library exists and when to pick it. The main reason is to take business logic and side effects out of React, Vue or Svelte components and write them as plain `async` functions, with cancellation, retries and a context for dependencies. The second part of the page is for SDKs, core libraries and micro-frontend shells, where a shared dependency is a shared risk. It does not teach the API: start with the [Guide](guide.md).
+
+## The main reason: logic outside the UI
+
+Components that hold requests, timers and races are hard to test and easy to break. The usual cure is services and pure functions outside the UI, and then every service needs the same things: to cancel work that is no longer wanted, to retry, to share dependencies, and to show what ran and why.
+
+The common tools ask a lot: redux-saga writes this logic as generators, and RxJS as streams and operators. nanoeffects keeps ordinary `async` functions and adds one idea, the `AbortSignal`. The event bus is its heart but not its value: any emitter can send events (`nanoevents` is about 100 bytes, and there are [dozens more](https://github.com/gajus/sister#similar-libraries)). What nanoeffects adds is cancellable tasks, policies and effects, a context that works as a small container for dependencies, actions and modules to group a feature, and [tracing](tracing.md) with an adapter for Redux DevTools. It also fits what a project already has: recipes and small adapters for [stores](stores.md) (Redux Toolkit, Zustand, MobX, Pinia), an [RxJS](migrating-from-rxjs.md) bridge, and helpers for [React](react.md), [Vue](vue.md) and [Svelte](svelte.md), so nothing has to be rewritten to start.
 
-## The problem: a shared dependency is a shared risk
+## When the constraint is a shared library
 
 A shared library (an SDK, a core package, a platform shell) is loaded by many apps. Whatever it depends on, the apps depend on too. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other.
 
@@ -674,9 +680,9 @@ A library that is **not** a shared singleton cannot break this way. nanoeffects
 ## What the library does instead
 
 - **No dependencies, no global state.** It is safe to ship inside an SDK next to whatever the host app runs. It does not need a `singleton` entry in the Module Federation config.
-- **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and commands are separate entries you import only when you need them. See [Package entries](package.md).
+- **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and actions are separate entries you import only when you need them. See [Package entries](package.md).
 - **Simple first.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
-- **`emit` can return an answer.** A [command](actions.md) is an event whose handler returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
+- **`emit` can return an answer.** An [action with a handler](actions.md) returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
 - **Easy to debug.** Event-driven code is hard to follow: you see an effect and not the event that caused it. Every task knows its parent, so [tracing](tracing.md) shows the chain of events, with loggers for the console, the Performance panel and Redux DevTools.
 
 ## When this is not the right tool
@@ -695,7 +701,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `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`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
+| `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` |
@@ -737,7 +743,7 @@ A stable entry follows the rules below. An unstable entry can change in any mino
 | `nanoeffects` | Stable | `createBus` and the types of a bus |
 | `nanoeffects/effects` | Stable | `retry`, `timeout`, `poll`, `take`, `delay`, `all`, `allSettled`, `race`, `backoff`, `cancellable`, `effectsPlugin` |
 | `nanoeffects/policies` | Stable | `latest`, `leading`, `debounce`, `throttle`, `queue`, `withPolicy` |
-| `nanoeffects/actions` | Stable | `createAction`, `createCommand`, `createJob`, `createModule` and their plugins |
+| `nanoeffects/actions` | Stable | `createAction`, `createJob`, `createModule` and their plugins |
 | `nanoeffects/trace` | Stable: the contract | `Tracer`, `Trace`, `TraceEvent`, `TraceLogger`, `Phase`, `EffectName` and `tracePlugin` |
 | `nanoeffects/trace` | Unstable: the tools | `createTracer`, `consoleLogger`, `performanceLogger`, `createTraceRecorder`, `reduxDevtools` and their option types |
 | `nanoeffects/scope` | Unstable | `scopePlugin`, `effect` |
@@ -780,7 +786,7 @@ A deprecated export keeps working and is removed only in a major release. `RaceS
 | ---- | --------- |
 | Node.js, the library | 18, 20, 22 and 24 (a smoke test runs the built package on each) |
 | Node.js, the dev tools and the trace in a browser | 22 and newer |
-| TypeScript | The types are written and checked with TypeScript 7. TypeScript 5.9 is used for the Vue tools and for the test of the exports. Older versions are not tested. |
+| TypeScript | 5.9 and 7. The built declaration files are type-checked with TypeScript 5.9 in CI, and the source with TypeScript 7. Older versions are not tested. |
 | React | 18 or newer (`nanoeffects/react`) |
 | Vue | 3.3 or newer (`nanoeffects/vue`) |
 | Svelte | 5 or newer (`nanoeffects/svelte`) |
@@ -830,14 +836,14 @@ In TypeScript keep the result of `contextPlugin` and `effectsPlugin`: the type o
 
 ## Main plugins
 
-These four cover what most apps need: shared dependencies, effects, commands and modules. Start here.
+These four cover what most apps need: shared dependencies, effects, handlers 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 }` |
+| [`actionsPlugin`](#let-a-test-replace-a-handler-commandsplugin) | The handlers of actions in a registry, so a test can bind or 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, actions, createModule }` |
 
 ### Put a store or a client on every handler: `contextPlugin`
 
@@ -874,27 +880,27 @@ bus.on("load", async (id, { race, delay }) => {
 });
 ```
 
-### Let a test replace a handler: `commandsPlugin`
+### Bind or replace a handler: `actionsPlugin`
 
-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).
+Handlers of actions can live in a registry that belongs to the bus. An action can have no handler, and a test or another layer binds one. More in [Actions](actions.md#bind-a-handler-later).
 
 ```js
 import { createBus } from "nanoeffects";
-import { commandsPlugin, createCommand } from "nanoeffects/actions";
+import { actionsPlugin, createAction } from "nanoeffects/actions";
 
-const getUser = createCommand("user/get"); // a contract: no handler yet
+const getUser = createAction("user/get"); // no handler yet: an event
 const bus = createBus();
 
-// commandsPlugin — the registry of handlers of this bus
-const commands = bus.use(commandsPlugin());
+// actionsPlugin — the registry of handlers of this bus
+const actions = bus.use(actionsPlugin());
 
-commands.handle(getUser, async (id) => ({ id })); // the latest binding wins
+actions.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).
+A module groups the listeners, the bound handlers 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";
@@ -914,7 +920,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-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 |
+| [`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` |
 | [`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` |
@@ -922,20 +928,20 @@ Add one of these when you meet its need. None of them is required.
 | [`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`
+### Give one action 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).
+An action with a handler, 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 { createAction } 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), {
+const getUser = createAction("user/get", (id, { api }) => api.getUser(id), {
   api,
 });
 
@@ -949,13 +955,13 @@ A library such as React Query owns the request and gives you an `AbortSignal`. `
 
 ```js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { signalPlugin } from "nanoeffects/signal";
 
 // signalPlugin — emit takes { signal } for a command, a job or an action
 const bus = createBus().use(signalPlugin());
 
-const getUser = createCommand("user/get", (id, { signal }) => api.getUser(id, { signal }));
+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
@@ -1062,7 +1068,7 @@ One bus with every plugin that does not need React, in a file of its own. The ev
 import { createBus } from "nanoeffects";
 import { contextPlugin } from "nanoeffects/context";
 import {
-  commandsPlugin,
+  actionsPlugin,
   emitterPlugin,
   modulePlugin,
 } from "nanoeffects/actions";
@@ -1078,8 +1084,8 @@ export const bus = createBus()
   .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());
+// actionsPlugin — the registry of action handlers; keep it to bind handlers later
+export const actions = bus.use(actionsPlugin());
 
 // modulePlugin — mounts userModule at the end of this block; keep app to mount and unmount later
 export const app = bus.use(modulePlugin([userModule]));
@@ -1094,12 +1100,12 @@ The plugins give the same result in any order. Use them as they read best, and p
 
 Two things happen because modules are mounted late:
 
-- **Modules start at the end of the block.** `modulePlugin([userModule])` mounts `userModule` when the synchronous block that made it has finished, or earlier if the app or the bus is used first: 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 used in the same block 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`. A plugin used after an `await` can come too late: use every plugin before the first `await`. With no module, `modulePlugin()` starts nothing until the first use.
+- **Modules start at the end of the block.** `modulePlugin([userModule])` mounts `userModule` when the synchronous block that made it has finished, or earlier if the app or the bus is used first: the first `bus.emit`, or the first call of `app.mount`, `app.unmount`, `app.isMounted`, `app.dispose` or the read of `app.actions`. By then every plugin used in the same block 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`. A plugin used after an `await` can come too late: use every plugin before the first `await`. With no module, `modulePlugin()` starts nothing until the first use.
 - **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.
+- `actionsPlugin` binds its list in the registry that the bus has, so it can come before or after `modulePlugin`. A custom `bus.actions = { 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.
@@ -2125,7 +2131,7 @@ const bus = createBus({
 
 ## Warn when nobody listens
 
-A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for commands, which always have a handler to run.
+A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for actions, which always have a handler to run.
 
 Use it as a warning in development:
 
@@ -2142,7 +2148,7 @@ const bus = createBus({
 ---
 Source: docs/actions.md
 
-# Actions, commands, jobs and modules
+# Actions, jobs and modules
 
 Use this page when **domain logic lives on the bus**, off the UI: the UI emits and listens; handlers and modules own the work.
 
@@ -2154,7 +2160,9 @@ A chat with two entities and three features, jobs under policies and effects, an
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
-## Return a value from `emit` with a command
+## Return a value from `emit` with a handler
+
+Give `createAction` a handler, and `emit` runs it and returns its result. There is one creator for an event and for an action with work behind it; the handler is the only difference.
 
 The bus lives in one file and its events in another, so any module can import both without a cycle.
 
@@ -2168,10 +2176,10 @@ export const bus = createBus();
 
 ```js
 // math.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-// createCommand — emit runs the handler and returns its result
-export const double = createCommand("math/double", (value) => value * 2);
+// createAction with a handler — emit runs the handler and returns its result
+export const double = createAction("math/double", (value) => value * 2);
 ```
 
 ```js
@@ -2181,27 +2189,24 @@ import { double } from "./math";
 bus.emit(double(21)); // 42
 ```
 
-## Describe events, commands, and jobs
+## Describe events, handlers and jobs
 
 `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";
+import { createAction, createJob } from "nanoeffects/actions";
 
-// createAction — event with a payload (like RTK createAction)
+// createAction — an event with a payload (like RTK createAction)
 export const userLoaded = createAction("user/loaded");
 export const loadFailed = createAction("user/failed");
 
-// createCommand with a handler — emit returns what the handler returns
-export const getUser = createCommand("user/get", (id, { signal }) => {
+// createAction with a handler — emit returns what the handler returns
+export const getUser = createAction("user/get", (id, { signal }) => {
   return fetchUser(id, { signal });
 });
 
-// createCommand without a handler — a contract; register the work elsewhere
-export const sendMail = createCommand("mail/send");
-
-// createJob — command that also emits success / fail actions
+// createJob — an action with a handler that also emits success / fail actions
 export const loadUser = createJob("user/load", fetchUser, {
   success: userLoaded,
   fail: "user/failed",
@@ -2217,57 +2222,99 @@ These are the events of the user domain, in a file of their own (`user.js`). The
 - `userLoaded(user)` → `{ type, payload }`
 - `userLoaded.type` — the type string
 - `userLoaded.match(action)` — narrows an action
-- `createAction(type, prepare)` — build the payload from several arguments
+- `createAction(type, handler)` — a function as the second argument is the handler; `bus.emit(action(payload))` tells the listeners, runs the handler as a task and returns its result
+- `createAction(type, { prepare })` — build the payload from several arguments
+- `createAction(type, { handle, prepare, ...scope })` — everything in one object: `handle` and `prepare` are taken out, and every other field is the [scope](scope.md)
 - Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
 
-### Commands
+A scope goes after a handler as the last argument, `createAction(type, handler, scope)`; `prepare` with a handler goes in that last object: `createAction(type, handler, { prepare, ...scope })`.
 
-Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or `bus.emit(command, payload)`) tells the listeners of the command’s type, then runs its handler as a task and returns the result.
+- Wrap the handler in a policy: `createAction("search", latest(fn))`.
 
-- Wrap the handler in a policy: `createCommand("search", latest(fn))`.
-- `command.match(action)` narrows like an action creator’s `match`.
+An action with no handler is an event. Emitting it does not throw, and `onUnhandled` hears about it when nobody listens.
 
-**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.
+### Bind a handler later
+
+**Problem.** The work belongs to another layer, or a test must replace it. Putting the handler in `createAction` then ties the event file to the work.
+
+**When.** Use the registry when the handler is not known where the action is made. The action can have no handler at all; a handler bound to its type answers it. Each bus (each test) has its own registry.
+
+```js
+// mail.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction without a handler — an event; the work is bound elsewhere
+export const sendMail = createAction("mail/send");
+```
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { bindHandler, commandsPlugin } from "nanoeffects/actions";
-import { sendMail } from "./user";
+import { actionsPlugin, setHandler } from "nanoeffects/actions";
+import { sendMail } from "./mail";
 
 export const bus = createBus();
 
-// commandsPlugin — registry of handlers for this bus
-export const commands = bus.use(
-  commandsPlugin([bindHandler(sendMail, smtpSend)]),
+// actionsPlugin — the registry of handlers of this bus; setHandler pairs an action with its work
+export const actions = bus.use(
+  actionsPlugin([setHandler(sendMail, smtpSend)]),
 );
 ```
 
 ```js
-import { commands } from "./bus";
+import { actions } from "./bus";
 import { getUser } from "./user";
 
-// later, e.g. in a test — latest binding wins
-const unbind = commands.handle(getUser, async () => fakeUser);
+// later, e.g. in a test — the latest binding wins, a handler bound here wins over the one in createAction
+const unbind = actions.handle(getUser, async () => fakeUser);
 unbind();
 ```
 
-A command with no handler anywhere throws `No handler for command "..."` from `emit` (the call itself only builds the action).
+A handler bound in the registry makes `bus.emit(sendMail(mail))` run it and return its result, the same as for an action that carries its handler. The listeners of the type are told first. With no handler bound, `sendMail` is an event again.
+
+The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the handler that the action carries. `bus.use(actionsPlugin())` sets `bus.actions`. A second `actionsPlugin` binds its list in that registry and returns it. There is no `actions` option in `createBus`; assign a custom runner with `bus.actions = { run }`, and add `bound(type)` to it to answer for actions that have no handler of their own.
+
+### Say what a bound handler returns
+
+TypeScript cannot see which handler the registry has, so the type of `emit` for an action without a handler is `void`. Tell it what the bound handler returns with `Call<Payload, Result>`. This is a promise of yours: nothing checks it against the handler.
+
+```ts
+// mail.ts
+import type { Call } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+
+// Call — payload Mail, a bound handler answers with a boolean (checker only; nothing runs differently)
+type Mail = { to: string };
+export const sendMail = createAction<Call<Mail, boolean>>("mail/send");
+```
+
+In an event map the same type does the job for string events, and `emit` returns `boolean`:
 
-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 }`.
+```ts
+// events.ts
+import type { Call } from "nanoeffects";
+
+// Call in the map — the payload is checked, emit returns the result (checker only)
+export type Events = {
+  "user/getId": Call<void, string>;
+  "user/loaded": { id: string };
+};
+```
+
+On a bus without an event map you can say it where you call: `const id = bus.emit<string>("user/getId")`. A bus with a map takes no such hint, so its names and payloads stay checked.
 
 ### Jobs
 
-`createJob(type, handler, { pending, success, fail, cancel })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
+`createJob(type, handler, { pending, success, fail, cancel })` makes an action with a handler that also sends its outcome as actions, when nobody waits for the result. It returns the action with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
 
 - When the handler starts, emits `loadUser.pending(payload)`.
 - On success, emits `loadUser.success(result)`.
 - On failure, emits `loadUser.fail(error)`.
 - When the task is aborted before the handler settles, emits `loadUser.cancel(reason)` instead of `success` or `fail`. After `pending`, exactly one of the three follows.
 - `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
-- `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, use a command.
-- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
-- A missing handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent.
+- `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, give `createAction` the handler.
+- Outcome actions are emitted as the task that ran the job (also for a handler bound with `actions.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
+- A job without a handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent. An action without a handler is an event and does not throw.
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
 - The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
 
@@ -2291,7 +2338,7 @@ export const bus = createBus();
 // user.js
 import { createJob } from "nanoeffects/actions";
 
-// createJob — a command that also sends pending, success, fail and cancel
+// createJob — an action with a handler that also sends pending, success, fail and cancel
 export const loadUser = createJob("user/load", fetchUser);
 ```
 
@@ -2346,18 +2393,18 @@ A flag is exact when calls do not overlap, or when `latest` replaces them. If se
 
 ## Mount domains with modules
 
-**Problem.** A domain needs several subscriptions and command bindings. With plain `bus.on` / `commands.handle` you must remember every unsubscribe.
+**Problem.** A domain needs several subscriptions and handler bindings. With plain `bus.on` / `actions.handle` you must remember every unsubscribe.
 
 **When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
 
-`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)).
+`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `actions`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-export const getUser = createCommand("user/get");
-export const saveUser = createCommand("user/save", persistUser);
+export const getUser = createAction("user/get");
+export const saveUser = createAction("user/save", persistUser);
 ```
 
 ```js
@@ -2394,7 +2441,7 @@ 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
+app.actions.handle(getUser, fakeUser); // in a test
 app.dispose(); // unmounts every module
 ```
 
@@ -2425,37 +2472,37 @@ app.unmount(...modules); // also in reverse order
 
 If the `setup` of one module throws, the modules of that call that were already mounted are unmounted again and the error is thrown, so a call mounts all of its modules or none. A module that is mounted already is skipped.
 
-- **Unmounting undoes everything** the module did: subscriptions, bound commands, sub-modules, and background tasks (aborted).
+- **Unmounting undoes everything** the module did: subscriptions, bound handlers, sub-modules, and background tasks (aborted).
 - **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
-- **Registry.** If `bus.use(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
+- **Registry.** If `bus.use(actionsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.actions` and `app.actions`.
 - A disposed app cannot mount modules.
 - **The given modules are mounted at the end of the block that made the app**, or at the first use of the app or the bus if that comes first (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`). Nothing needs to use the app: `bus.use(modulePlugin([a, b]))` is enough to start them. The plugins that you use after `modulePlugin` in the same block still reach them, because the modules wait until that block has finished. A plugin used after an `await` can come too late: use every plugin before the first `await`. 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).
 - **To mount by hand instead**, pass no modules: `modulePlugin()` starts nothing, and `app.mount(...)` starts the modules when you want.
 - 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.
+  - `handle` — give an action a handler (one that has none, or an override).
+  - `use` — bring sub-modules and actions that carry a handler; the returned function undoes that call.
   - `spawn` — background task, aborted on unmount.
-- A command that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.
+- An action that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.
 
-## Give a command, an action or a module its own fields
+## Give 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`:
+An action with a handler 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 `createAction`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
 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
 export const bus = createBus().use(scopePlugin());
 ```
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-// the third argument — fields of this command only
-export const getUser = createCommand(
+// the third argument — fields of this action only
+export const getUser = createAction(
   "user/get",
   (id, { api }) => api.getUser(id),
   { api },
@@ -3153,7 +3200,7 @@ Source: docs/query-libraries.md
 
 # Use nanoeffects with React Query and SWR
 
-Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one command that both libraries call.
+Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one action that both libraries call.
 
 You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
 
@@ -3169,9 +3216,9 @@ The libraries and nanoeffects do different jobs, so each keeps its own.
 
 `isLoading` and `data` come from the library, not from `emit`. `await bus.emit(...)` resolves once, with the result, so it cannot report that the request is still running.
 
-## Make the command
+## Make the action
 
-A command is the request itself. It lives in files that know nothing about React: the bus, the command with its handler, and the component.
+An action with a handler is the request itself. It lives in files that know nothing about React: the bus, the action with its handler, and the component.
 
 ```js
 // bus.js
@@ -3187,11 +3234,11 @@ The handler tries the request up to three times and gives up after five seconds
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { retry, timeout } from "nanoeffects/effects";
 
-// createCommand — a command with a handler: emit returns what the handler returns
-export const getUser = createCommand("user/get", async (id, ctx) => {
+// createAction with a handler — emit returns what the handler returns
+export const getUser = createAction("user/get", async (id, ctx) => {
   // one try: the request, with the signal of timeout so it can stop it
   const load = ({ signal }) => api.getUser(id, { signal });
   // timeout — fail the try after 5 s
@@ -3226,13 +3273,13 @@ export function Profile({ id }) {
 }
 ```
 
-The command rejects when all tries fail, so React Query shows the `error`. React Query counts its own `retry` too: set `retry: false` in `useQuery` when the handler already retries, or the tries multiply.
+The action rejects when all tries fail, so React Query shows the `error`. React Query counts its own `retry` too: set `retry: false` in `useQuery` when the handler already retries, or the tries multiply.
 
 ## Call it from SWR
 
 <!-- docs-check: continue -->
 
-SWR does not pass a signal to the fetcher, so there is nothing to give to `emit`. The command still brings `retry` and `timeout`.
+SWR does not pass a signal to the fetcher, so there is nothing to give to `emit`. The action still brings `retry` and `timeout`.
 
 ```jsx
 // Profile.jsx
@@ -3256,7 +3303,7 @@ export function Profile({ id }) {
 
 <!-- docs-check: continue -->
 
-A command gives its result only to the caller. If a store or another module must react to a loaded user, the handler can say so:
+An action with a handler gives its result only to the caller. If a store or another module must react to a loaded user, the handler can say so:
 
 ```js
 // user-events.js
@@ -3266,15 +3313,15 @@ import { createAction } from "nanoeffects/actions";
 export const userLoaded = createAction("user/loaded");
 ```
 
-Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the command with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job).
+Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the action with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job).
 
 ## Know the limits
 
-- **Without the plugin, `{ signal }` is ignored.** The command runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
+- **Without the plugin, `{ signal }` is ignored.** The action runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
 - **Only the call forms take it.** `bus.emit(getUser(id), { signal })` works; `bus.emit("user/get", id, { signal })` does not.
-- **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Commands that fetch are async, so this only matters for a sync handler that sets up a callback.
-- **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
-- **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
+- **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Actions that fetch are async, so this only matters for a sync handler that sets up a callback.
+- **Give each request its own signal for an event.** For an action with a handler or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
+- **The signal reaches the tasks that this `emit` starts**, with the listeners of the action's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
 
 A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).
 
@@ -3299,9 +3346,9 @@ The fix is one `AbortController` for each unit of work that the client owns, and
 | A WebSocket | the socket connects | the socket closes |
 | A queued job | the job is accepted | the server shuts down |
 
-## Make the bus and the command
+## Make the bus and the action
 
-The bus and the command live in files that know nothing about HTTP, so the same command can run in a route, a test or a worker.
+The bus and the action live in files that know nothing about HTTP, so the same action can run in a route, a test or a worker.
 
 ```js
 // bus.js
@@ -3313,15 +3360,15 @@ import { signalPlugin } from "nanoeffects/signal";
 export const bus = createBus().use(signalPlugin());
 ```
 
-The command loads a user. It tries the request up to three times, and gives up on each try after five seconds. `ctx.signal` is the signal of the task: it aborts when the controller of the request aborts.
+The action loads a user. It tries the request up to three times, and gives up on each try after five seconds. `ctx.signal` is the signal of the task: it aborts when the controller of the request aborts.
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { retry, timeout } from "nanoeffects/effects";
 
-// createCommand — a command with a handler: emit returns what the handler returns
-export const getUser = createCommand("user/get", async (id, ctx) => {
+// createAction — a command with a handler: emit returns what the handler returns
+export const getUser = createAction("user/get", async (id, ctx) => {
   // one try: the request, with the signal of timeout so it can stop it
   const load = ({ signal }) => api.getUser(id, { signal });
   // timeout — fail the try after 5 s
@@ -3374,7 +3421,7 @@ app.get("/users/:id", async (request, reply) => {
 });
 ```
 
-After an abort the command rejects with the abort reason. The `catch` above ignores it when the connection is gone, because there is nobody to answer.
+After an abort the action rejects with the abort reason. The `catch` above ignores it when the connection is gone, because there is nobody to answer.
 
 ## Stop the server
 
@@ -3406,17 +3453,17 @@ The route above fills `inFlight` and empties it in the `close` listener. The [ap
 
 A socket lasts minutes and carries several tasks (a subscription, a heartbeat), so the controller belongs to the socket and every `emit` for it gets the same signal. Closing the socket stops all of them.
 
-First the command. It sends a price now and then every second, until its task is aborted.
+First the action. It sends a price now and then every second, until its task is aborted.
 
 ```js
 // prices.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { poll } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
-// createCommand — a command with a handler
+// createAction — a command with a handler
 // latest — a new subscription stops the old one; key — but only the old one of the same socket
-export const watchPrices = createCommand(
+export const watchPrices = createAction(
   "prices/watch",
   latest(
     async (call, ctx) => {
@@ -3430,7 +3477,7 @@ export const watchPrices = createCommand(
 );
 ```
 
-Without the `key`, one policy serves the whole command, and a new subscription on one socket would stop the subscription on another.
+Without the `key`, one policy serves the whole action, and a new subscription on one socket would stop the subscription on another.
 
 Then the route. Each socket gets an id and a controller.
 
@@ -3774,7 +3821,7 @@ Source: docs/chat-example.md
 
 Use this page when your app has several features that react to each other and you want to see where each piece of logic goes. The example is a chat with rooms, a history that loads, messages that can fail to send, a search across all rooms, and new messages that arrive on their own. A small Fastify server in the example answers every request, and it misbehaves on a known schedule, so each problem on this page really happens.
 
-It is a level D example. Start with [Actions, commands, jobs and modules](actions.md) for the API, or with the `domains-ts` template in [Start a project from a template](starter.md#start-with-domains) for a smaller project.
+It is a level D example. Start with [Actions, jobs and modules](actions.md) for the API, or with the `domains-ts` template in [Start a project from a template](starter.md#start-with-domains) for a smaller project.
 
 The code is in [`examples/chat`](../examples/chat). Run it on [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat), or on your machine:
 
@@ -3820,7 +3867,7 @@ The code is in layers, and a file imports only from the layers below it. The com
 
 That rule is why `show-history` exists. Selecting a room must load its history, but `room` does not know `message` and `message` does not know `room`. The feature `show-history` is the one place that knows both: it listens to `rooms/selected` and starts the job `messages/loadHistory`. The same goes for a message that arrives: `receive-messages` emits `incoming/received`, an event that the `message` entity owns and listens to.
 
-A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its events and commands, never through its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any feature may listen: `rooms/selected` is heard by two. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
+A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its events and commands, never through its handlers or its store. Events and commands both live in the events file. An event (`createAction` with no handler) says that something happened, and any feature may listen: `rooms/selected` is heard by two. A command (`createAction` with a handler) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createAction`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 The layers come from [Feature-Sliced Design](https://feature-sliced.design/), reduced to the three that an app of this size needs.
 
@@ -3951,11 +3998,11 @@ export const runSearch = debounce(
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
 ```js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
-// createCommand — an order for the message entity, with the handler that does it
-const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
+// createAction with a handler — an order for the message entity, with the handler that does it
+const markMessage = createAction("messages/mark", (messageId) => console.log("mark", messageId));
 
 // the room that is open, kept from the rooms/selected event
 let selectedRoom = "general";
@@ -4019,7 +4066,7 @@ Each entity and each feature that has state keeps it in a [Zustand](https://zust
 
 ## Where to go next
 
-- The API of commands, jobs and modules: [Actions, commands, jobs and modules](actions.md).
+- The API of commands, jobs and modules: [Actions, jobs and modules](actions.md).
 - Policies such as `latest` and `queue`: [Policies](policies.md). Effects such as `allSettled`, `take` and `poll`: [Effects](effects.md).
 - A smaller project with two domains: [Start with domains](starter.md#start-with-domains). Its two domains do not talk to each other, so it needs no layers.
 
@@ -4228,7 +4275,7 @@ bus.on("save", (draft, { store }) => {
 });
 ```
 
-That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, commands, modules, and child tasks of effects and policies.
+That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
 
 Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may be a function `(task) => fields` when the value depends on the task.
 
@@ -4274,9 +4321,9 @@ const bus = createBus<Events>({ context: { store } });
 ---
 Source: docs/scope.md
 
-# Pin context fields to a command, an action, a module or a call
+# Pin context fields to an action, a module or a call
 
-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.
+Optional, for domain logic. Use it when one action 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)`.
 
@@ -4295,21 +4342,21 @@ import { scopePlugin } from "nanoeffects/scope";
 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.
+The bus is in one file and the 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 in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
 
-## Give a command its own fields
+## Give an action its own fields
 
 <!-- docs-check: continue -->
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-// createCommand — third argument is the scope of this command
-export const getUser = createCommand(
+// createAction — third argument is the scope of this action
+export const getUser = createAction(
   "user/get",
   (id, { api, cache }) => {
     // api and cache are on ctx for this command only
@@ -4326,7 +4373,7 @@ import { getUser } from "./user";
 const user = await bus.emit(getUser("1")); // the handler has api and cache
 ```
 
-The listeners of `"user/get"` get the same fields when the command is emitted, because the fields belong to the call.
+The listeners of `"user/get"` get the same fields when the action is emitted, because the fields belong to the call.
 
 ## Bind an effect to the task
 
@@ -4334,14 +4381,14 @@ An effect is a function with `{ signal }` as its first parameter. In `$effects`
 
 ```js
 // feed.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { delay, race } from "nanoeffects/effects";
 
 // 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());
 
-export const loadFeed = createCommand(
+export const loadFeed = createAction(
   "feed/load",
   (url, { fetchJson, race, delay }) =>
     // race, delay, fetchJson — bound to this task: no ctx argument
@@ -4387,9 +4434,9 @@ export const bus = createBus().use(scopePlugin());
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-export const getUser = createCommand(
+export const getUser = createAction(
   "user/get",
   (id, { api }) => api.getUser(id),
   { api },
@@ -4410,7 +4457,7 @@ await bus.emit(getUser("1"), { api: fakeApi });
 
 Rules for the second argument:
 
-- It works with an action or a command call (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
+- It works with the call of an action (`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 } }`.
 - Fields of the library (`signal`, `emit`, …) in it are ignored.
@@ -4475,13 +4522,13 @@ In `$effects` a function loses its first parameter, and TypeScript cannot keep a
 
 ```js
 // pick.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } 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]);
 
-export const pick = createCommand("pick", (items, { first }) => first(items), {
+export const pick = createAction("pick", (items, { first }) => first(items), {
   first, // a plain key of the scope, not an entry of `$effects`
 });
 ```
@@ -4491,7 +4538,7 @@ Call `effect` where you declare the function, as above, and not inline in the sc
 `Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
 
 ```ts
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import type { Effect } from "nanoeffects/effects";
 
 // First — checker-only: how a handler calls the effect (no ctx)
@@ -4500,7 +4547,7 @@ type First = <T>(items: T[]) => T;
 // Effect<First> — the function takes the task first and is typed as First once bound
 const first: Effect<First> = (ctx, items) => items[0];
 
-const pick = createCommand(
+const pick = createAction(
   "pick",
   (id: string, { first }) => first([id]), // string
   { $effects: { first } },
@@ -4511,14 +4558,14 @@ const pick = createCommand(
 
 ## Type the fields (optional)
 
-A handler of a command, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+A handler of an action, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
 
 ```ts
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
 type User = { id: string; name: string };
 
-const getUser = createCommand(
+const getUser = createAction(
   "user/get",
   async (id: string, ctx) => {
     ctx.cache; // Map<string, User>, from the scope below
@@ -4536,10 +4583,10 @@ const getUser = createCommand(
 ## Limits
 
 - 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 fields of the bus are not in the handler of an action made with `createAction(…, 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.
+- A scope on an 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
@@ -4962,21 +5009,21 @@ Source: docs/typescript.md
 
 # Use nanoeffects in a TypeScript app with many files
 
-Read this page if your app is in TypeScript and the commands and modules live in different files. It shows how to write a command so that TypeScript infers its payload and result, and what to add when the handlers need the fields of your bus (`ctx.store`, the effects of `effectsPlugin`). For one file or for JavaScript you do not need it.
+Read this page if your app is in TypeScript and the handlers and modules live in different files. It shows how to write an action with a handler so that TypeScript infers its payload and result, and what to add when the handlers need the fields of your bus (`ctx.store`, the effects of `effectsPlugin`). For one file or for JavaScript you do not need it.
 
-## Write a command with its handler
+## Write an action with its handler
 
-Give `createCommand` the handler and write nothing else. The payload comes from the annotated parameter, the result from the body. You do not write a generic.
+Give `createAction` the handler and write nothing else. The payload comes from the annotated parameter, the result from the body. You do not write a generic.
 
 <!-- docs-check: skip - a file of examples/typescript, type-checked there -->
 ```ts
 // user.ts
-import { createCommand, createModule } from "nanoeffects/actions";
+import { createAction, createModule } from "nanoeffects/actions";
 
 export type User = { id: string; name: string };
 
 // payload: string, from `id: string`; result: Promise<User>, from the body
-export const getUser = createCommand(
+export const getUser = createAction(
   "user/get",
   async (id: string, { signal }) => {
     const response = await fetch(`/api/users/${id}`, { signal });
@@ -5018,11 +5065,11 @@ A wrong payload at the call (`getUser(1)`) is an error. Annotate the parameters,
 
 ## Give `ctx` the fields of your bus
 
-Types of a bus live on the bus. `contextPlugin({ store })` and `effectsPlugin({ race })` make `ctx.store` and `ctx.race` known to the handlers of **that bus**. A command made in another file does not see the bus, so its `ctx` has no `store`:
+Types of a bus live on the bus. `contextPlugin({ store })` and `effectsPlugin({ race })` make `ctx.store` and `ctx.race` known to the handlers of **that bus**. An action with a handler made in another file does not see the bus, so its `ctx` has no `store`:
 
 <!-- docs-check: skip - shows the error on purpose -->
 ```ts
-export const getUser = createCommand("user/get", (id: string, ctx) => {
+export const getUser = createAction("user/get", (id: string, ctx) => {
   ctx.store; // error: Property 'store' does not exist
 });
 ```
@@ -5055,7 +5102,7 @@ export type AppContext = Context<AppEvents>; // ctx of a handler of this bus: ha
 | Type | What it is | Why you name it |
 | ---- | ---------- | --------------- |
 | `EventsOf<typeof bus>` | the event map of the bus, with the context fields of the plugins (and of `WithContext`, if you use it) | the source of `AppContext` |
-| `Context<AppEvents>` | the `ctx` that a handler of the bus gets | annotate the `ctx` of a handler given to `createCommand` |
+| `Context<AppEvents>` | the `ctx` that a handler of the bus gets | annotate the `ctx` of a handler given to `createAction` |
 
 These types change nothing at runtime. They only tell the checker what the bus already does.
 
@@ -5064,10 +5111,10 @@ Annotate `ctx` with `AppContext` where the handler reads a field of the bus, and
 <!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
 ```ts
 // user.ts
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { type AppContext, createModule } from "./bus";
 
-export const getUser = createCommand(
+export const getUser = createAction(
   "user/get",
   (id: string, { store, signal }: AppContext) => store.fetchUser(id, { signal }),
 );
@@ -5107,14 +5154,14 @@ Pass `ctx` (or `{ signal }`) when you call it. The effects of `nanoeffects/effec
 
 ## Keep the contract apart from the code
 
-When the file with the command must not import the code that implements it, make the command without a handler. Here you write the payload and the result once, as generics, and the handler goes to a module, where it needs no annotation:
+When the file with the action must not import the code that implements it, make the action without a handler. Here you write the payload and the result once, as a `Call`, and the handler goes to a module, where it needs no annotation. `Call` is a promise of yours: nothing checks it against the handler, so keep the handler typed from it in the module:
 
 <!-- docs-check: skip - fragment of the file above -->
 ```ts
-export const getUser = createCommand<string, Promise<User>>("user/get"); // the contract
+export const getUser = createAction<Call<string, Promise<User>>>("user/get"); // the contract
 
 createModule("user", (m) => {
-  // payload and result come from the command, ctx from the app: no annotation
+  // payload and result come from the Call, ctx from the app: no annotation
   m.handle(getUser, (id, { store, signal }) => store.fetchUser(id, { signal }));
 });
 ```
@@ -5123,11 +5170,11 @@ A wrong payload, a wrong field of `ctx` and a wrong result are errors.
 
 ## Check your setup
 
-- **A field is missing on `ctx`.** The `ctx` of a handler given to `createCommand` is not annotated: add `: AppContext`. A handler written inline in `m.handle` or `m.on` of a module made with the `createModule` of `bus.ts` does not need it. The default `ctx` has no fields of your bus.
-- **`EventsOf<typeof bus>` is `never`.** `bus` is not a bus. `bus.use(commandsPlugin())` and `bus.use(modulePlugin(...))` return the registry or the app, not the bus: keep the bus in its own constant (`bus`, then `app = bus.use(modulePlugin())`).
+- **A field is missing on `ctx`.** The `ctx` of a handler given to `createAction` is not annotated: add `: AppContext`. A handler written inline in `m.handle` or `m.on` of a module made with the `createModule` of `bus.ts` does not need it. The default `ctx` has no fields of your bus.
+- **`EventsOf<typeof bus>` is `never`.** `bus` is not a bus. `bus.use(actionsPlugin())` and `bus.use(modulePlugin(...))` return the registry or the app, not the bus: keep the bus in its own constant (`bus`, then `app = bus.use(modulePlugin())`).
 - **`effectsPlugin` is not in the type.** `use` must come before you read `typeof bus`. Chain `createBus(...).use(effectsPlugin(...))` in one binding.
 - **A policy loses the types.** It does not: `latest(handler)` keeps the payload, the result and the context of `handler`.
-- **Do not pass the context as a generic of `createCommand`.** It is the fourth generic, after the payload, the result and the type string, so you would have to write all four. Annotate `ctx` with `AppContext`, or put the handler in a module made with the `createModule` of `bus.ts`.
+- **Do not pass the context as a generic of `createAction`.** It is the fourth generic of the handler form, after the payload, the result and the type string, so you would have to write all four. Annotate `ctx` with `AppContext`, or put the handler in a module made with the `createModule` of `bus.ts`.
 
 ---
 Source: docs/migrating-from-saga.md
@@ -6014,7 +6061,7 @@ Give the flow a `traceGroupId` in the scope of the command, the job or the actio
 
 ```js
 import { createBus } from "nanoeffects";
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
 
 // createTracer: sends each trace event to the logger; consoleLogger: prints one line each
@@ -6025,7 +6072,7 @@ const bus = createBus({ trace })
   .use(tracePlugin());
 
 // the scope names the flow; traceGroupId is for the tracer, not a field of ctx
-const pay = createCommand("checkout/pay", async () => {}, {
+const pay = createAction("checkout/pay", async () => {}, {
   traceGroupId: "checkout",
 });
 ```
@@ -6423,7 +6470,7 @@ When a file is edited, the bundler loads its new version and runs it again, whil
 
 ## Replace modules by name
 
-Mounting a module whose name is taken replaces the mounted one. The old module is unmounted first — and with it its subscriptions, bound commands, sub-modules, and background tasks (their signals abort). The new version of a module file only has to mount again; nothing piles up.
+Mounting a module whose name is taken replaces the mounted one. The old module is unmounted first — and with it its subscriptions, bound handlers, sub-modules, and background tasks (their signals abort). The new version of a module file only has to mount again; nothing piles up.
 
 - **Names must be unique.** The name means “this is the new version of that module”, so two different modules with one name replace each other. The name is also the type of the module’s tasks in the trace.
 - **Pass `signal` to what the module does.** An unmount aborts the tasks, but a `fetch` or a loop that ignores `ctx.signal` runs on with the old code.