nanoeffects 0.26.0 → 0.28.0

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

@@ -46,7 +46,7 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `react` | The same handler with `useEmitter` and `useEventState`, and `usePolicy` for a debounced save in a component | You build a React app |
 | `vanilla-ts` | The `vanilla` app in TypeScript | You want the compiler to check events and handlers |
 | `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
-| `domains-ts` | Commands, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
+| `domains-ts` | Actions with handlers, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
 | `vue-ts` | The `react-ts` app in Vue 3, with `watchEmitter` and `useEventRef` from `nanoeffects/vue` | You build a Vue 3 app |
 | `svelte-ts` | The `react-ts` app in Svelte 5, with `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
 
@@ -94,13 +94,13 @@ npm create nanoeffects@latest my-app -- --template domains-ts
 | ---- | --- |
 | `src/bus.ts` | Creates the bus. It imports no events and no domain. |
 | `src/app.ts` | Mounts the domains with `modulePlugin`. |
-| `src/domains/catalog/` | Searching products: `catalog.ts` (events and a command), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
+| `src/domains/catalog/` | Searching products: `catalog.ts` (events and an action with a handler), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
 | `src/domains/checkout/` | Placing an order: `checkout.ts` (a job), `checkout-handlers.ts` (`leading` and `retry`), `checkout-store.ts` (state written from the job's outcomes), `checkout-module.ts`. |
 | `src/ui/` | The components. None of them calls the fake server in `src/api.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 actions, 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

@@ -132,13 +132,13 @@ Every event of a task below another one has `rootId`, the id of the root of the
 
 **Problem.** A flow such as a checkout has several roots (a click, a timer, a store) and many branches. Parent ids give a tree, but you want to filter the log by the flow.
 
-**When.** One business flow runs through several commands, and you read the log by flow.
+**When.** One business flow runs through several actions, and you read the log by flow.
 
-Give the flow a `traceGroupId` in the scope of the command, the job or the action that starts it. Every task that it starts through `ctx.emit` or `ctx.run` has the same `traceGroupId`, and so does every trace event of those tasks. A task that declares its own `traceGroupId` uses it for itself and for what it starts.
+Give the flow a `traceGroupId` in the scope of the action or the job that starts it. Every task that it starts through `ctx.emit` or `ctx.run` has the same `traceGroupId`, and so does every trace event of those tasks. A task that declares its own `traceGroupId` uses it for itself and for what it starts.
 
 ```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",
 });
 ```
@@ -202,7 +202,7 @@ The names work wherever an event or a listener is made:
 | A listener, `bus.on` and `bus.once` | `{ traceId }` as the third argument |
 | A listener of a module or of an instance of `extendBus` | the same third argument of its `on` and `once` |
 | A method with `@On` or `@Once` | `{ traceId }` in the decorator |
-| A command, a job or an action | `traceGroupId` in its scope |
+| An action or a job | `traceGroupId` in its scope |
 
 ## Turn the names off
 

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