nanoeffects 0.26.0 → 0.27.0

package/docs/plugins.md

@@ -10,14 +10,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`
 
@@ -54,27 +54,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";
@@ -94,7 +94,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` |
@@ -102,20 +102,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,
 });
 
@@ -129,13 +129,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
@@ -242,7 +242,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";
@@ -258,8 +258,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]));
@@ -274,12 +274,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.

package/docs/query-libraries.md

@@ -1,6 +1,6 @@
 # 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.
 
@@ -16,9 +16,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
@@ -34,11 +34,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
@@ -73,13 +73,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
@@ -103,7 +103,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
@@ -113,14 +113,14 @@ 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).

package/docs/scope.md

@@ -1,6 +1,6 @@
-# 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)`.
 
@@ -19,21 +19,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
@@ -50,7 +50,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
 
@@ -58,14 +58,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
@@ -111,9 +111,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 },
@@ -134,7 +134,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.
@@ -199,13 +199,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`
 });
 ```
@@ -215,7 +215,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)
@@ -224,7 +224,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 } },
@@ -235,14 +235,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
@@ -260,7 +260,7 @@ 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.

package/docs/server.md

@@ -16,9 +16,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
@@ -30,15 +30,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
@@ -91,7 +91,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
 
@@ -123,17 +123,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) => {
@@ -147,7 +147,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.
 

package/docs/stability.md

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

package/docs/starter.md

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

package/docs/tracing.md

@@ -138,7 +138,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
@@ -149,7 +149,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",
 });
 ```

package/docs/typescript.md

@@ -1,20 +1,20 @@
 # 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 });
@@ -56,11 +56,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
 });
 ```
@@ -93,7 +93,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.
 
@@ -102,10 +102,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 }),
 );
@@ -145,14 +145,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 }));
 });
 ```
@@ -161,8 +161,8 @@ 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`.