nanoeffects 0.25.0 → 0.27.0

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

@@ -261,6 +261,8 @@ export const Cache = extendBus(bus, CacheBase);
 
 ## Subscribe a method with `@On` and `@Once`
 
+`On` here is a decorator. The main entry also exports a type named `On`, the type of `bus.on`; they are different things in different imports, and a file that needs both can rename one: `import { On as OnDecorator } from "nanoeffects/oop"`.
+
 A decorator turns a method into a handler of an event for each instance, with `this` bound. You write no `this.on` in the constructor, and `dispose()` ends the subscription too.
 
 The bus and the events are the same as above, in TypeScript:

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` |

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

@@ -0,0 +1,90 @@
+# Know what is stable
+
+Use this page to decide what you can rely on. It says which imports are stable, what counts as a breaking change, which versions are supported, and which call forms stay.
+
+## See which entries are stable
+
+A stable entry follows the rules below. An unstable entry can change in any minor release; every change is written in the [CHANGELOG](../CHANGELOG.md), and nothing promises a deprecation period first.
+
+| Import | Status | Note |
+| ------ | ------ | ---- |
+| `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`, `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` |
+| `nanoeffects/match` | Unstable | `matchPlugin` |
+| `nanoeffects/signal` | Unstable | `signalPlugin` |
+| `nanoeffects/context` | Unstable | `contextPlugin` |
+| `nanoeffects/oop` | Unstable | `Emitter`, `extendBus`, `On`, `Once`, `WithBus`, `disposeBus` |
+| `nanoeffects/observable` | Unstable | `createObserve`, `Subject` |
+| `nanoeffects/redux` | Unstable | `createEffectsMiddleware` |
+| `nanoeffects/react` | Unstable | `reactPlugin`, `usePolicy` |
+| `nanoeffects/svelte` | Unstable | `sveltePlugin` |
+| `nanoeffects/vue` | Unstable | `vuePlugin` |
+| `nanoeffects/dev` | Unstable | `devPlugin` |
+
+The adapters (`react`, `vue`, `svelte`, `redux`) are unstable because they follow the APIs of other libraries and have had little use. They can become stable after the library has been in use for a while.
+
+## Know what is a breaking change
+
+For a stable entry, these changes are breaking:
+
+- A change in what a call does at run time.
+- A change in a type that stops code that compiled before from compiling.
+- A removed or renamed export.
+
+A stricter type that only finds mistakes in code that was already wrong is not breaking. It ships in a minor release with a note in the CHANGELOG.
+
+These are not covered by the promise:
+
+- Any unstable entry.
+- The text of the messages of `nanoeffects/dev`.
+- The payload details of trace events. The shape of an event (`id`, `parentId`, `rootId`, `type`, `effect`, `phase`) is covered; the contents of `payload` are not.
+
+Before version 1.0.0, a breaking change ships in a minor release under `### Breaking` in the CHANGELOG. From 1.0.0 it ships only in a major release.
+
+A deprecated export keeps working and is removed only in a major release. `RaceStarter` is deprecated: use `StarterOf` instead.
+
+## Check the supported versions
+
+| What | Supported |
+| ---- | --------- |
+| 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 | 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`) |
+
+The library has no dependencies. React, Vue and Svelte are optional peer dependencies of their own entries only.
+
+## Rely on these call forms
+
+`retry`, `timeout` and `poll` have three call forms, and all three stay:
+
+```js
+import { createBus } from "nanoeffects";
+import { race, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("open", async (id, ctx) => {
+  // with ctx: you pass the context, the function gets the signal
+  const user = await retry(ctx, ({ signal }) => fetchUser(id, { signal }), { times: 3 });
+
+  // as a starter: a group (race, all, allSettled, timeout) calls it with its child
+  const result = await race(ctx, {
+    user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
+  });
+});
+
+// as a Task: a function of (payload, ctx), which bus.on and ctx.run call
+bus.on("reload", retry((id, { signal }) => fetchUser(id, { signal }), { times: 3 }));
+```
+
+The forms are told apart by the arguments: a context first is the form with `ctx`; a function called with a payload and a context is the Task; the same function called by a group with one argument, its child, is the starter. The rule is part of the contract and does not depend on how many parameters your function declares.
+
+`all` and `allSettled` take options only in the form with `ctx`, `all(ctx, effects, { concurrency })`. The form without `ctx` has one argument, so a second one would look like the `ctx` form. `race` takes no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. See [Effects](effects.md#run-several-starters-together).

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",
 });
 ```