nanoeffects 0.21.0 → 0.23.0

package/llms-full.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ---
@@ -553,7 +553,7 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `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 |
 | `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 a Svelte store made from an event | You build a Svelte app |
+| `svelte-ts` | The `react-ts` app in Svelte 5, with `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -579,7 +579,7 @@ npm create nanoeffects@latest my-app -- --template vue-ts
 
 ### Start with Svelte
 
-`svelte-ts` is the search app of `react-ts` in Svelte 5. It needs no part of nanoeffects for Svelte: a Svelte store is any object with `subscribe`, so a small helper of the project, `src/event-store.ts`, makes a store from an event with `readable` and `bus.on`. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](react.md#show-the-last-value-of-an-event-as-state): a value that several components share belongs in a store of your own.
+`svelte-ts` is the search app of `react-ts` in Svelte 5. Its bus uses `sveltePlugin` from `nanoeffects/svelte`: `eventStore` makes a Svelte store from an event. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](svelte.md#it-is-not-a-store-of-the-app): a value that several components share belongs in a store of your own.
 
 ```bash
 npm create nanoeffects@latest my-app -- --template svelte-ts
@@ -603,7 +603,7 @@ npm create nanoeffects@latest my-app -- --template domains-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 with the same layout, a chat with four domains and mocks, see [Build a chat with domains, modules and a small server](chat-example.md).
+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).
 
@@ -692,6 +692,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve`, `Subject` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
+| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) |
 | `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) |
 | `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |
@@ -1744,7 +1745,8 @@ bus.on("load", async (id, { race, all, delay }) => {
   // race — same as race(ctx, …)
   const result = await race({
     data: ({ signal }) => fetchData(id, { signal }),
-    timeout: () => delay(5000), // delay — same as delay(ctx, 5000)
+    // a starter gets its own child with the same bound effects, so delay(5000) stops with the race
+    timeout: ({ delay }) => delay(5000),
   });
   if ("timeout" in result) throw new Error("timed out");
 
@@ -1827,28 +1829,35 @@ bus.on("watch", (_, ctx) => {
 - Under `latest`, subscriptions of a superseded run end with that run.
 - `ctx.off(event)` clears every handler of the event on the bus, not only the task’s.
 
-`take(ctx, event, options?)` waits for the next `event` and resolves with its payload:
+`take(ctx, event, options?)` waits for the next `event` and resolves with its payload. `event` is the name of an event or an action creator, as for `bus.on`:
 
 ```js
 import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
 import { take, timeout } from "nanoeffects/effects";
 
 const bus = createBus();
+const stopRequested = createAction("stop"); // an event with a name; calling it builds the action
 
 bus.on("login", async (user, ctx) => {
   const reason = await take(ctx, "logout"); // resolves on the next logout
   cleanup(user, reason);
 
+  // an action creator works the same, and its payload type is the type of the result
+  const stopped = await take(ctx, stopRequested);
+  console.log(stopped);
+
   // wait for a matching event, but not longer than 5 s
-  const id = await timeout(ctx, 5000, ({ signal }) =>
-    take(ctx, "saved", { signal, predicate: (savedId) => savedId === draft.id }),
+  const id = await timeout(ctx, 5000, (child) =>
+    take(child, "saved", { predicate: (savedId) => savedId === draft.id }),
   );
 });
 ```
 
 - Sees only events emitted after the call, takes one, and unsubscribes.
+- With an action creator the result has the payload type of the creator. A creator made without a payload type (`createAction("saved")`) takes it from the event map of the bus.
 - `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
-- `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
+- `options.signal` stops the wait. In a starter of `race`, `all` or `timeout` pass `child` as the first argument instead: it already carries the signal.
 - On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
 
 ## Run several starters together
@@ -1877,6 +1886,29 @@ bus.on("open", async (id, ctx) => {
 
 `race(ctx, effects)` settles with the first starter that finishes and cancels the others.
 
+```js
+import { createBus } from "nanoeffects";
+import { delay, race, take } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("save", async (draft, ctx) => {
+  // race — the first starter to finish wins, the other is cancelled
+  const result = await race(ctx, {
+    waited: (child) => delay(child, 1000),
+    cancelled: (child) => take(child, "cancel"),
+  });
+
+  if ("waited" in result) {
+    ctx.emit("saved", draft);
+  }
+});
+```
+
+**A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options: `({ signal }) => fetchUser(id, { signal })`. The same holds for `all`, `allSettled` and `timeout`.
+
+If `ctx` is `{}` or a bare `{ signal }` (outside a task), `child` has only `signal` and `abort`, so it fits `delay` and `poll` but not `take`, which needs a bus.
+
 ## Pass `ctx` outside a task
 
 Effects that wait inside a body take `ctx` first: `delay`, `all`, `allSettled`, `race`, `cancellable`, `onAbort`, `take`, and the `ctx` forms of `retry` / `timeout` / `poll`. Outside a task, pass `{}` or any object with a `signal`.
@@ -1934,7 +1966,7 @@ If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until
 
 Recipe without a UI framework: [`examples/modules.ts`](../examples/modules.ts).
 
-A chat with four domains, jobs under policies and effects, and a stream tied to a module: [Build a chat with domains, modules and a small server](chat-example.md).
+A chat with two entities and three features, jobs under policies and effects, and a stream tied to a module: [Build a chat with entities, features, modules and a small server](chat-example.md).
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
@@ -2287,7 +2319,7 @@ Redux’s `dispatch` → reducers updates **state**. It does not give you first-
 
 `createEffectsMiddleware(bus)` does the same job: after the reducer runs, the action also hits the nanoeffects bus you pass to it. Keep RTK for state; use policies and effects for async.
 
-Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts).
+Skip this section if you are not already on Redux. The recipe as a file, type-checked with the project: [`examples/redux.ts`](../examples/redux.ts). To run it, open the [counter example](../examples/counter): `redux.html` is a counter with Redux Toolkit and this middleware.
 
 ```js
 // bus.js
@@ -3062,6 +3094,215 @@ Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the c
 
 A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).
 
+---
+Source: docs/server.md
+
+# Stop work on a server when the client leaves
+
+Read this page if you run a Node server (the examples use [Fastify](https://fastify.dev)) and want the work for a request, a socket or a queued job to stop when nobody needs it. It shows one pattern in three places: a request, a WebSocket and a worker.
+
+You need Node 18 or newer, `fastify` and `nanoeffects`. `api` below is your own client for another service: replace it with your requests.
+
+## Why a server needs this
+
+A browser tab that closes stops its own requests. A server does not: if a client leaves, the requests that the server made for it keep running, and so do their retries. On a busy server that is wasted work and a slower service for everyone else.
+
+The fix is one `AbortController` for each unit of work that the client owns, and one rule: **when the client goes, abort the controller.** `signalPlugin` lets `bus.emit` take that signal, so `timeout`, `retry` and the request itself stop.
+
+| Unit of work | Created when | Aborted when |
+| ------------ | ------------ | ------------ |
+| An HTTP request | the route starts | the connection closes before the answer |
+| 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
+
+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.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// createBus — the bus the server shares
+// signalPlugin — lets emit take { signal }, so a closed connection can abort the work
+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.
+
+```js
+// user.js
+import { createCommand } 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) => {
+  // 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
+  const attempt = () => timeout(ctx, 5000, load);
+  // retry — up to 3 tries, 500 ms apart
+  return retry(ctx, attempt, { times: 3, delay: 500 });
+});
+```
+
+## Stop the work of a request
+
+<!-- docs-check: continue -->
+
+Make a controller when the route starts. Listen to `close` of the **response** (`reply.raw`): it ends when the connection ends. `request.raw` also emits `close`, but it does so when the request body has been read, not when the client leaves, so it is the wrong event here.
+
+```js
+// server.js
+import Fastify from "fastify";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export const app = Fastify();
+
+// the controllers of the requests that are still being answered, for the shutdown below
+export const inFlight = new Set();
+
+app.get("/users/:id", async (request, reply) => {
+  const controller = new AbortController();
+  inFlight.add(controller);
+
+  // close on the response — the connection ended; if the answer was not finished, the client left
+  reply.raw.on("close", () => {
+    inFlight.delete(controller);
+    if (!reply.raw.writableFinished) {
+      controller.abort();
+    }
+  });
+
+  try {
+    // emit with { signal } — aborting the controller aborts the command: timeout, retry and the request
+    const call = getUser(request.params.id);
+    return await bus.emit(call, { signal: controller.signal });
+  } catch (error) {
+    // nobody is left to answer when the client closed the connection
+    if (reply.raw.destroyed) {
+      return reply;
+    }
+    return reply.code(502).send({ error: String(error) });
+  }
+});
+```
+
+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.
+
+## Stop the server
+
+<!-- docs-check: continue -->
+
+Keep the controllers of the requests in flight in a set. On SIGTERM (what a container sends) or SIGINT (Ctrl+C), abort them all, then close the app. A request that is aborted this way answers with an error, and `app.close()` waits for the connections to end.
+
+```js
+// shutdown.js
+import { app, inFlight } from "./server";
+
+// SIGTERM is what a container sends, SIGINT is Ctrl+C
+for (const name of ["SIGTERM", "SIGINT"]) {
+  process.on(name, async () => {
+    for (const controller of inFlight) {
+      controller.abort();
+    }
+    await app.close();
+    process.exit(0);
+  });
+}
+```
+
+The route above fills `inFlight` and empties it in the `close` listener. The [api-server example](../examples/api-server) does the same, with a limit of two seconds for the close.
+
+## Tie a WebSocket to its work
+
+<!-- docs-check: continue -->
+
+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.
+
+```js
+// prices.js
+import { createCommand } from "nanoeffects/actions";
+import { poll } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+// createCommand — 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(
+  "prices/watch",
+  latest(
+    async (call, ctx) => {
+      // poll — call the function now and every second, until the task is aborted
+      await poll(ctx, () => call.send(`${call.symbol}: ${Math.random()}`), 1000, {
+        leading: true,
+      });
+    },
+    { key: (call) => call.socketId },
+  ),
+);
+```
+
+Without the `key`, one policy serves the whole command, and a new subscription on one socket would stop the subscription on another.
+
+Then the route. Each socket gets an id and a controller.
+
+```js
+// sockets.js
+import websocket from "@fastify/websocket";
+import Fastify from "fastify";
+import { bus } from "./bus";
+import { watchPrices } from "./prices";
+
+const sockets = Fastify();
+sockets.register(websocket);
+
+let lastSocketId = 0;
+
+sockets.register(async (instance) => {
+  instance.get("/prices", { websocket: true }, (socket) => {
+    lastSocketId += 1;
+    const socketId = lastSocketId;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    // close — the client left: stop everything started for this socket
+    socket.on("close", () => controller.abort());
+
+    socket.on("message", (data) => {
+      const send = (text) => socket.send(text);
+      const call = watchPrices({ socketId, symbol: String(data), send });
+      // emit with { signal } — the call stops when the socket closes
+      bus.emit(call, { signal });
+    });
+  });
+});
+```
+
+The [ws-server example](../examples/ws-server) adds a close for a silent socket, made of `race`, `take` and `delay`.
+
+## Run a queue worker
+
+A worker takes jobs from a client and answers at once, and the work goes on in the background. Use `createJob` with `queue` to limit how many run together, `retry` and `timeout` to give up, and the outcomes of the job (`pending`, `success`, `fail`, `cancel`) to count them. Give every `emit` of the job the same signal; aborting it at shutdown cancels the jobs that are left.
+
+Two details matter:
+
+- Bind the handler with `commands.handle(job, queue(...))` (or `m.handle` in a module), not as the second argument of `createJob`. Only a bound handler lets the job learn from the policy when a call really starts, so `pending` is sent at the start and not at the call.
+- A call that is still waiting in the queue when the signal aborts never starts, and the job sends no outcome for it. Count such calls yourself if you need the totals to add up.
+
+The [job-worker example](../examples/job-worker) has all of it: the counts, `GET /stats`, and a shutdown in three steps (stop taking jobs, wait, abort the rest).
+
+## Examples
+
+| Folder | What it shows |
+| ------ | ------------- |
+| [`api-server`](../examples/api-server) | A Fastify server over PokeAPI: `timeout`, `retry`, `allSettled`, and the abort when the client leaves |
+| [`ws-server`](../examples/ws-server) | A WebSocket server: one controller for each socket, `latest` with a `key`, an idle close |
+| [`job-worker`](../examples/job-worker) | A queue worker: `queue`, `retry`, `timeout`, counts from the outcomes, a three-step shutdown |
+
 ---
 Source: docs/react.md
 
@@ -3348,7 +3589,7 @@ export const Search = ({ wait }) => {
 ---
 Source: docs/chat-example.md
 
-# Build a chat with domains, modules and a small server
+# Build a chat with entities, features, modules and a small server
 
 Use this page when your app has several features that react to each other and you want to see where each piece of logic goes. The example is a chat with rooms, a history that loads, messages that can fail to send, a search across all rooms, and new messages that arrive on their own. A small Fastify server in the example answers every request, and it misbehaves on a known schedule, so each problem on this page really happens.
 
@@ -3380,21 +3621,27 @@ Open the Network panel of the browser while you do this. A request that the page
 
 ## See how the files are split
 
-Each domain is a folder. The components only emit events and read values; they never call the server.
+The code is in layers, and a file imports only from the layers below it. The components only emit events and read values; they never call the server.
 
-| Path | Job |
-| ---- | --- |
-| `src/bus.ts` | Creates the bus. It imports no events and no domain. |
-| `src/app.ts` | Mounts the four domains. |
-| `src/api.ts` | The client of the server: one function per request. |
-| `server/` | The Fastify server and the script that starts it with Vite. |
-| `src/domains/rooms/` | The list of rooms and the selected room. |
-| `src/domains/messages/` | The history of the open room and sending a message. |
-| `src/domains/search/` | Searching every room and opening a result. |
-| `src/domains/incoming/` | New messages, asked for at an interval. |
-| `src/ui/` | The components. |
+| Path | Layer | Job |
+| ---- | ----- | --- |
+| `src/shared/bus.ts` | shared | Creates the bus. It imports no events, no entity and no feature. |
+| `src/shared/api.ts` | shared | The client of the server: one function per request. |
+| `src/entities/room/` | entity | The list of rooms and the selected room. |
+| `src/entities/message/` | entity | The history of the open room, sending a message, and a message that arrives. |
+| `src/features/show-history/` | feature | A selected room loads its history. |
+| `src/features/search-messages/` | feature | Searching every room and opening a result. |
+| `src/features/receive-messages/` | feature | New messages, asked for at an interval. |
+| `src/ui/`, `src/app.ts` | top | The components, and the file that mounts the modules. |
+| `server/` | | The Fastify server and the script that starts it with Vite. |
+
+**The rule.** An entity is a thing with its own state and orders (a room, a message). It imports `shared` and nothing else. A feature is a scenario that connects things: it imports `shared` and entities, and never another feature. The top imports anything below. No two entities import each other and no two features import each other, and a test in the repository (`src/tests/architecture.test.ts`) fails when one does.
+
+That rule is why `show-history` exists. Selecting a room must load its history, but `room` does not know `message` and `message` does not know `room`. The feature `show-history` is the one place that knows both: it listens to `rooms/selected` and starts the job `messages/loadHistory`. The same goes for a message that arrives: `receive-messages` emits `incoming/received`, an event that the `message` entity owns and listens to.
 
-A domain folder has its events (`rooms.ts`, which imports no bus), its work (`rooms-handlers.ts`), the state it keeps (`rooms-store.ts`) and a module (`rooms-module.ts`) that wires them. A domain reacts to another domain by listening to its events, never by importing its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any domain may listen: `rooms/selected` is heard by three. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
+A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its events and commands, never through its handlers or its store. Events and commands both live in the events file. An event (`createAction`) says that something happened, and any feature may listen: `rooms/selected` is heard by two. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
+
+The layers come from [Feature-Sliced Design](https://feature-sliced.design/), reduced to the three that an app of this size needs.
 
 ## Load a history that must not race
 
@@ -3405,7 +3652,7 @@ A domain folder has its events (`rooms.ts`, which imports no bus), its work (`ro
 A job sends `pending` when its handler starts and exactly one of `success`, `fail` and `cancel` when it ends. `latest` around the handler aborts the older load when a newer one starts, so only the newer result is delivered, and the older one sends `cancel`:
 
 ```js
-// messages.js
+// message.js
 import { createJob } from "nanoeffects/actions";
 
 // createJob — a command that also sends pending, success, fail and cancel
@@ -3413,7 +3660,7 @@ export const loadHistory = createJob("messages/loadHistory");
 ```
 
 ```js
-// messages-handlers.js
+// message-handlers.js
 import { latest } from "nanoeffects/policies";
 
 // latest — a load for a newer room aborts the older one, and its result is never delivered
@@ -3423,12 +3670,12 @@ export const fetchHistory = latest((roomId, { signal }) => api.loadHistory(roomI
 The module gives the job its work and keeps the state from the outcomes, so an aborted load clears the flag too (see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job)):
 
 ```js
-// messages-module.js
+// message-module.js
 import { createModule } from "nanoeffects/actions";
-import { loadHistory } from "./messages";
-import { fetchHistory } from "./messages-handlers";
+import { loadHistory } from "./message";
+import { fetchHistory } from "./message-handlers";
 
-export const messagesModule = createModule("messages", (module) => {
+export const messageModule = createModule("message", (module) => {
   // handle — this module does the work of loadHistory while it is mounted
   module.handle(loadHistory, fetchHistory);
   module.on(loadHistory.pending, () => console.log("show the spinner"));
@@ -3518,7 +3765,7 @@ export const runSearch = debounce(
 
 **Problem.** The reader opens a search result from another room. The message cannot be marked until that room's history has loaded, and the handler must not guess how long that takes.
 
-**When.** A handler starts work in another domain and needs to continue after its outcome.
+**When.** A feature starts work in an entity and needs to continue after its outcome.
 
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
@@ -3526,7 +3773,7 @@ export const runSearch = debounce(
 import { createCommand } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
-// createCommand — an order for the messages domain, with the handler that does it
+// createCommand — an order for the message entity, with the handler that does it
 const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
 
 // the room that is open, kept from the rooms/selected event
@@ -3539,7 +3786,7 @@ export const goToResult = async (hit, ctx) => {
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  // ctx.emit with a command — the messages domain marks the message
+  // ctx.emit with a command — the message entity marks the message
   ctx.emit(markMessage(hit.id));
 };
 ```
@@ -3577,23 +3824,23 @@ const watchUpdates = async (_, ctx) => {
   await poll(ctx, check, 3000, { leading: true });
 };
 
-export const incomingModule = createModule("incoming", (module) => {
+export const receiveMessagesModule = createModule("receive-messages", (module) => {
   // spawn — a background task that lives as long as this module
   module.spawn(watchUpdates);
 });
 ```
 
-In the example a button calls `app.unmount(incomingModule)` and `app.mount(incomingModule)`, so you can watch the polling stop (the Network panel shows no more `updates` requests) and start.
+In the example a button calls `app.unmount(receiveMessagesModule)` and `app.mount(receiveMessagesModule)`, so you can watch the polling stop (the Network panel shows no more `updates` requests) and start.
 
 ## Know where each value lives
 
-Each domain keeps its state in a [Zustand](https://zustand.docs.pmnd.rs/) store that the module writes and a component reads with `useStore`. Each store lists its mutations, such as `startLoading(roomId)` and `markFailed(localId)`, and a module calls them with the data of an event: `module.on(loadHistory.pending, startLoading)`. A mutation that sets plain values gives `set` an object, as in `set({ searching: true })`. The store of the messages uses the `immer` middleware, so a mutation that changes a list can change it in place, as in `state.messages.push(message)`, and the store still gives React a new object. Nothing else writes the state. The list of rooms is the exception: it is read with one `useEventState` in a provider at the root. `useEventState` is not a store: an event that came before the provider mounted is lost, and a second component gets its own copy. See [Show the last value of an event as state](react.md#show-the-last-value-of-an-event-as-state).
+Each entity and each feature that has state keeps it in a [Zustand](https://zustand.docs.pmnd.rs/) store that the module writes and a component reads with `useStore`. Each store lists its mutations, such as `startLoading(roomId)` and `markFailed(localId)`, and a module calls them with the data of an event: `module.on(loadHistory.pending, startLoading)`. A mutation that sets plain values gives `set` an object, as in `set({ searching: true })`. The store of the message entity uses the `immer` middleware, so a mutation that changes a list can change it in place, as in `state.messages.push(message)`, and the store still gives React a new object. Nothing else writes the state. The list of rooms is the exception: it is read with one `useEventState` in a provider at the root. `useEventState` is not a store: an event that came before the provider mounted is lost, and a second component gets its own copy. See [Show the last value of an event as state](react.md#show-the-last-value-of-an-event-as-state).
 
 ## Where to go next
 
 - The API of commands, jobs and modules: [Actions, commands, jobs and modules](actions.md).
 - Policies such as `latest` and `queue`: [Policies](policies.md). Effects such as `allSettled`, `take` and `poll`: [Effects](effects.md).
-- A smaller project with two domains: [Start with domains](starter.md#start-with-domains).
+- A smaller project with two domains: [Start with domains](starter.md#start-with-domains). Its two domains do not talk to each other, so it needs no layers.
 
 ---
 Source: docs/vue.md
@@ -3695,6 +3942,91 @@ In TypeScript the type of the `ref` comes from the event: with `createAction<str
 - A policy in a component (a debounced save): in `<script setup>` make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Vue runs the setup once, so it needs no hook.
 - Keep values in Pinia: [Connect Redux, Zustand, MobX, or Pinia](stores.md).
 
+---
+Source: docs/svelte.md
+
+# Use nanoeffects in a Svelte app
+
+Use this page when your app is in Svelte 5 and a component has to show the result of an event. `sveltePlugin` gives you one function for that, `eventStore`. To see it in a running project, start from the `svelte-ts` template in [Start a project from a template](starter.md#start-with-svelte).
+
+You need Svelte 5 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
+
+## Add the plugin to the bus
+
+**Problem.** A Svelte component reads a value with `$store`. An event of the bus is not a store, so without help the component writes its own `readable` and its own `bus.on`, and has to remember to stop listening. The same few lines are copied into every component.
+
+**When.** A component shows the payload of an event, such as the result of a search.
+
+`sveltePlugin()` adds `eventStore` to the bus. Take it out of the bus once, in the file that makes it, and import it where you need it:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { sveltePlugin } from "nanoeffects/svelte";
+
+// createBus — the event bus, created once outside Svelte
+// sveltePlugin — adds eventStore to the bus
+export const bus = createBus().use(sveltePlugin());
+export const { eventStore } = bus; // a free function: it does not read `this`
+```
+
+## Show the result of an event
+
+<!-- docs-check: continue -->
+
+`eventStore(event, initial)` returns a Svelte store. Its value is `initial` at first and the payload of every `event` after that. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. A payload that is a function is stored, not called.
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — an event with a name; calling it builds { type, payload }
+export const searchLoaded = createAction("search/loaded");
+```
+
+<!-- docs-check: skip - a .svelte file -->
+```svelte
+<script>
+  import { eventStore } from "./bus";
+  import { searchLoaded } from "./search";
+
+  // eventStore — like a store of [], but searchLoaded sets the value
+  const found = eventStore(searchLoaded, []);
+</script>
+
+<ul>
+  {#each $found as title (title)}
+    <li>{title}</li>
+  {/each}
+</ul>
+```
+
+In TypeScript the type of the store comes from the event: with `createAction<string[]>("search/loaded")` it is `Readable<string[]>`, and for an event with no payload type it comes from `initial`.
+
+To send a value to the bus, call `bus.emit` from the handler of the event, for example `oninput`. Nothing is emitted when the component mounts, so no plugin function is needed for that direction.
+
+### It is not a store of the app
+
+The bus listens only while something reads the store: the first `$found` starts it, and the last one stops it. The bus keeps no values, so an event that came while nothing read the store is lost, and a component that mounts later starts from `initial`. To keep a value for components that come later, keep it in a store of your own and write to it from a handler of the event:
+
+```js
+// found-store.js
+import { writable } from "svelte/store";
+import { bus } from "./bus";
+import { searchLoaded } from "./search";
+
+// writable — a Svelte store that you keep for the whole app
+export const foundTitles = writable([]);
+
+// bus.on — copy every searchLoaded into the store, whether or not a component is open
+bus.on(searchLoaded, (titles) => foundTitles.set(titles));
+```
+
+## Where to go next
+
+- The same job for React: [Build a sign-up form in React](react.md); for Vue: [Use nanoeffects in a Vue app](vue.md).
+- A policy in a component (a debounced save): in the script of a component make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Svelte runs the script once, so it needs no hook.
+
 ---
 Source: docs/context.md
 
@@ -4633,7 +4965,7 @@ Read this page if you know redux-saga and want to find the same job in nanoeffec
 | `fork(fn, x)` | `ctx.run(task, x)` without `await` |
 | `spawn(fn, x)` | `ctx.emit(event, x)` or `bus.emit(event, x)` |
 | `put(action)` | `ctx.emit(action)` |
-| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md) |
+| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md), where `event` is a name or an action creator |
 | `select` | a [context field](context.md), such as `store` |
 | `all`, `race` | [`all`, `race`](effects.md) |
 | `retry`, `delay` | [`retry`, `delay`](effects.md) |
@@ -4681,6 +5013,8 @@ bus.on(
 
 Tasks are plain `async` functions. `ctx.signal` replaces `cancel`: pass it to `fetch` or to your client, and the request stops.
 
+To see the counter, `takeLatest` with `delay`, a cancel and a failing call running, open the [counter example](../examples/counter): it has a page without a store and a page with Redux Toolkit.
+
 ## Start a task without waiting
 
 `fork` and `spawn` differ in what happens when the caller is aborted. Pick by that.
@@ -5269,9 +5603,9 @@ bus.on("watch", async (_, ctx) => {
 
   await race(ctx, {
     // poll: a check every 5 s; waitForFn: the next pause starts after the check ends
-    polling: ({ signal }) => poll({ signal }, checkStatus, 5000, { waitForFn: true }),
+    polling: (child) => poll(child, checkStatus, 5000, { waitForFn: true }),
     // take: resolves at the next "leave", and race stops the polling
-    leave: ({ signal }) => take(ctx, "leave", { signal }),
+    leave: (child) => take(child, "leave"),
   });
 });
 

package/llms.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ## Start here
@@ -34,9 +34,11 @@ Rules that generated code often gets wrong:
 - [Actions, commands, jobs and modules](docs/actions.md): `createAction`, `createCommand`, `createJob`, `createModule`
 - [Connect Redux, Zustand, MobX, or Pinia](docs/stores.md): the Redux middleware and callbacks of other stores
 - [Use nanoeffects with React Query and SWR](docs/query-libraries.md): call a command from `queryFn` or the SWR fetcher; `signalPlugin` passes the abort of the library to the task
+- [Stop work on a server when the client leaves](docs/server.md): one `AbortController` for each request or socket, `signalPlugin`, a clean shutdown, and a queue worker; Fastify examples
 - [Build a sign-up form in React](docs/react.md): a form with a username check, a submit that cannot fire twice, and retry; `useEventState` shows an event as state, `usePolicy` keeps a debounced handler between renders
-- [Build a chat with domains, modules and a small server](docs/chat-example.md): rooms, a history under `latest`, a send under `queue` and `retry`, a search with `allSettled` and `timeout`, new messages polled with `poll`
+- [Build a chat with entities, features, modules and a small server](docs/chat-example.md): rooms, a history under `latest`, a send under `queue` and `retry`, a search with `allSettled` and `timeout`, new messages polled with `poll`
 - [Use nanoeffects in a Vue app](docs/vue.md): `vuePlugin` adds `watchEmitter` (a value of a component to the bus) and `useEventRef` (an event as a ref)
+- [Use nanoeffects in a Svelte app](docs/svelte.md): `sveltePlugin` adds `eventStore` (an event as a Svelte store)
 - [Context fields](docs/context.md): put a store or client on every task
 - [Scopes](docs/scope.md): fields for one command, action, job, module or `emit`, and a way to replace them in a test
 - [Use the bus from a class](docs/oop.md): `Emitter`, `extendBus`, `@WithBus`, `@On`, `@Once`, and `dispose()` for the subscriptions of an instance