nanoeffects 0.26.0 → 0.28.0

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 |
 | ------------ | ---------- |
@@ -31,7 +31,7 @@ bus.emit("greet", "Bob"); // nobody listens
 
 Handlers run at once, in subscription order.
 
-`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus.
+`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus. `bus.get("greet")` gives the listeners that event has right now; `bus.get("greet").length === 0` tells that nobody listens any more (`"*"` gives the any-event listeners, which a named event does not include; `bus.get()` with no name gives every listener of every event). It takes the event name as a string: for an action creator use `creator.type`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -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/oop.md

@@ -310,7 +310,7 @@ export const SearchService = extendBus(bus, SearchServiceBase);
 
 Things to know:
 
-- The event is a name, an action creator or a command, as for `bus.on`. For a creator or a command the payload of the method is checked against it.
+- The event is a name or an action creator, as for `bus.on`. For a creator the payload of the method is checked against it.
 - The second argument, `wrap`, takes the bound handler and returns the one to subscribe: `latest`, or `(handler) => debounce(300, handler)`. A policy needs it: `latest(this.search)` wraps the function without `this`, and the bound handler is what `wrap` gets.
 - The subscriptions are made right after the constructor of `Base`. An event that is emitted inside that constructor does not reach them.
 - A subclass inherits them. A method that a subclass overrides is subscribed only if the override is decorated.

package/docs/package.md

@@ -7,12 +7,12 @@ 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` |
 | `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` |
-| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one command, action, job, module or `emit` (the types `Scope`, `Effect`) |
+| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve`, `Subject` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |

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.