nanoeffects 0.22.0 → 0.23.1

package/llms-full.txt

@@ -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).
 
@@ -1745,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");
 
@@ -1847,8 +1848,8 @@ bus.on("login", async (user, ctx) => {
   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 }),
   );
 });
 ```
@@ -1856,7 +1857,7 @@ bus.on("login", async (user, ctx) => {
 - 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
@@ -1885,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`.
@@ -1942,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)).
 
@@ -3070,6 +3094,212 @@ 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.
+
+One detail matters: 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
 
@@ -3356,7 +3586,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.
 
@@ -3388,21 +3618,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 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.
 
-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.
+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
 
@@ -3413,7 +3649,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
@@ -3421,7 +3657,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
@@ -3431,12 +3667,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"));
@@ -3526,7 +3762,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:
 
@@ -3534,7 +3770,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
@@ -3547,7 +3783,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));
 };
 ```
@@ -3585,23 +3821,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
@@ -5364,9 +5600,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

@@ -34,8 +34,9 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.22.0",
+	"version": "0.23.1",
 	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -167,14 +167,17 @@
 		"@biomejs/biome": "2.5.15",
 		"@commitlint/cli": "21.2.3",
 		"@commitlint/config-conventional": "21.2.3",
+		"@fastify/websocket": "^11.3.4",
 		"@reduxjs/toolkit": "^2.13.0",
 		"@size-limit/esbuild": "^14.2.0",
 		"@size-limit/file": "^14.2.0",
 		"@tanstack/react-query": "^5.105.0",
 		"@types/react": "^19.3.0",
 		"@types/react-dom": "^19.3.0",
+		"@types/ws": "^8.18.2",
 		"@vitejs/plugin-react": "^6.1.2",
 		"archunit": "^2.5.4",
+		"fastify": "^5.12.7",
 		"happy-dom": "^21.0.4",
 		"immer": "^10.2.0",
 		"jotai": "^3.0.1",
@@ -212,17 +215,17 @@
 		{
 			"name": "policies (all)",
 			"path": "dist/policies.js",
-			"limit": "2.65 kB"
+			"limit": "2.7 kB"
 		},
 		{
 			"name": "effects (all)",
 			"path": "dist/effects.js",
-			"limit": "2.45 kB"
+			"limit": "2.5 kB"
 		},
 		{
 			"name": "actions (all)",
 			"path": "dist/actions.js",
-			"limit": "3.02 kB"
+			"limit": "3.1 kB"
 		},
 		{
 			"name": "match (plugin)",

package/dist/context-CJGW6OWj.js

@@ -1 +0,0 @@
-const e=(e,t)=>{globalThis.console?.error(`[nanoeffects] ${e}`,t)},t=()=>{},n=/* @__PURE__ */ new WeakMap,r=t=>{let r=n.get(t);if(r)return r;let i=/* @__PURE__ */ new Set;return n.set(t,i),t.addEventListener(`abort`,()=>{let n=[...i];i.clear();for(let{fn:r}of n)try{r(t.reason)}catch(t){e(`abort callback failed`,t)}},{once:!0}),i},i=(e,n)=>{let{signal:i}=e;if(!i)return t;if(i.aborted)return n(i.reason),t;let a=r(i),o={fn:n};return a.add(o),()=>{a.delete(o)}},a=e=>{let t=new AbortController;return{controller:t,unlink:i({signal:e},e=>t.abort(e))}},o=Symbol(),s=typeof __NANOEFFECTS_TRACE__>`u`||__NANOEFFECTS_TRACE__,c=/* @__PURE__ */ new WeakMap;let l;const u=()=>l,d=()=>{},f=(e,t,n,r)=>{let i=s&&c.get(e);i&&i.tracer.report(i.ref,t,n,r)},p=(e,t)=>{let n=s&&c.get(e);n&&n.tracer.rename?.(n.ref,t)},m=(e,t)=>{let n=s&&c.get(e);return n?n.tracer.settler(n.ref,t):d},h=(e,t,n)=>{let r=s&&c.get(e);return r?r.tracer.run(r.ref,t,e.signal,n):n()},g=(e,t)=>typeof e==`function`?e(t):e,_=({event:e,bus:t,tracer:n,parent:r})=>{let{controller:u,unlink:f}=a(r?.signal),{signal:p}=u,m=s&&n?{tracer:n,ref:n.task(e,r?.ref)}:void 0,v=(...e)=>{if(p.aborted&&!x[o])return;let n=t?.emit,r=l;l=m?.ref;try{return n?.(...e)}finally{l=r}},y=(...e)=>{if(p.aborted)return d;let n=t?.on,r=n?.(...e);if(!r)return d;let a=i({signal:p},r);return()=>{a(),r()}},b=async(r,...i)=>{p.throwIfAborted();let a=i[0],o=_({event:{type:e.type,payload:a},bus:t,tracer:n,parent:{signal:p,ref:m?.ref}});try{return await h(o.ctx,`run`,()=>r(a,o.ctx))}finally{o.unlink()}},x={...g(t?.ctx,e),type:e.type,payload:e.payload,signal:p,abort:e=>u.abort(e),emit:v,on:y,off:t?.off??d,run:b};return t?.addContext?.(x),m&&c.set(x,m),{ctx:x,unlink:f}},v=(e,t)=>{let n=s?c.get(e):void 0;return _({event:{type:t??e.type??``,payload:e.payload},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e},tracer:n?.tracer,parent:{signal:e.signal,ref:n?.ref}})};export{p as a,s as c,e as d,v as i,o as l,_ as n,h as o,u as r,f as s,m as t,i as u};

package/dist/notrace/context-yYU3_9lq.js

@@ -1 +0,0 @@
-const e=(e,t)=>{globalThis.console?.error(`[nanoeffects] ${e}`,t)},t=()=>{},n=/* @__PURE__ */ new WeakMap,r=t=>{let r=n.get(t);if(r)return r;let i=/* @__PURE__ */ new Set;return n.set(t,i),t.addEventListener(`abort`,()=>{let n=[...i];i.clear();for(let{fn:r}of n)try{r(t.reason)}catch(t){e(`abort callback failed`,t)}},{once:!0}),i},i=(e,n)=>{let{signal:i}=e;if(!i)return t;if(i.aborted)return n(i.reason),t;let a=r(i),o={fn:n};return a.add(o),()=>{a.delete(o)}},a=e=>{let t=new AbortController;return{controller:t,unlink:i({signal:e},e=>t.abort(e))}},o=Symbol();let s;const c=()=>s,l=()=>{},u=(e,t,n,r)=>{},d=(e,t)=>l,f=(e,t,n)=>n(),p=(e,t)=>typeof e==`function`?e(t):e,m=({event:e,bus:t,tracer:n,parent:r})=>{let{controller:c,unlink:u}=a(r?.signal),{signal:d}=c,h=(...e)=>{if(d.aborted&&!v[o])return;let n=t?.emit,r=s;s=void 0;try{return n?.(...e)}finally{s=r}},g=(...e)=>{if(d.aborted)return l;let n=t?.on,r=n?.(...e);if(!r)return l;let a=i({signal:d},r);return()=>{a(),r()}},_=async(r,...i)=>{d.throwIfAborted();let a=i[0],o=m({event:{type:e.type,payload:a},bus:t,tracer:n,parent:{signal:d,ref:void 0}});try{return await f(o.ctx,`run`,()=>r(a,o.ctx))}finally{o.unlink()}},v={...p(t?.ctx,e),type:e.type,payload:e.payload,signal:d,abort:e=>c.abort(e),emit:h,on:g,off:t?.off??l,run:_};return t?.addContext?.(v),{ctx:v,unlink:u}},h=(e,t)=>m({event:{type:t??e.type??``,payload:e.payload},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e},tracer:void 0,parent:{signal:e.signal,ref:void 0}});export{f as a,i as c,h as i,e as l,m as n,u as o,c as r,o as s,d as t};