nanoeffects 0.26.0 → 0.27.0

package/docs/actions.md

@@ -1,4 +1,4 @@
-# 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.
 
@@ -10,7 +10,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.
 
@@ -24,10 +26,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
@@ -37,27 +39,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",
@@ -73,57 +72,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 })`.
+
+- Wrap the handler in a policy: `createAction("search", latest(fn))`.
 
-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.
+An action with no handler is an event. Emitting it does not throw, and `onUnhandled` hears about it when nobody listens.
 
-- Wrap the handler in a policy: `createCommand("search", latest(fn))`.
-- `command.match(action)` narrows like an action creator’s `match`.
+### Bind a handler later
 
-**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.
+**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`:
+
+```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 };
+};
+```
 
-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 }`.
+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.
 
@@ -147,7 +188,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);
 ```
 
@@ -202,18 +243,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
@@ -250,7 +291,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
 ```
 
@@ -281,37 +322,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 },

package/docs/chat-example.md

@@ -2,7 +2,7 @@
 
 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:
 
@@ -48,7 +48,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.
 
@@ -179,11 +179,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";
@@ -247,6 +247,6 @@ 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.

package/docs/context.md

@@ -15,7 +15,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.
 

package/docs/errors.md

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

package/docs/guide.md

@@ -1,6 +1,6 @@
 # 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 |
 | ------------ | ---------- |
@@ -115,7 +115,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.
 
@@ -303,7 +303,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.
 
@@ -324,10 +324,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
@@ -344,36 +344,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();
@@ -383,7 +383,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.
 
@@ -391,16 +391,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
@@ -417,7 +417,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);
 });
 ```
@@ -442,8 +442,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).
 

package/docs/hmr.md

@@ -10,7 +10,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.

package/docs/motivation.md

@@ -1,8 +1,14 @@
 # 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 problem: a shared dependency is a shared risk
+## 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.
+
+## 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.
 
@@ -31,9 +37,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

package/docs/package.md

@@ -7,7 +7,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` |