nanoeffects 0.19.1 → 0.21.0

package/docs/chat-example.md

@@ -0,0 +1,246 @@
+# Build a chat with domains, 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.
+
+It is a level D example. Start with [Actions, commands, jobs and modules](actions.md) for the API, or with the `domains-ts` template in [Start a project from a template](starter.md#start-with-domains) for a smaller project.
+
+The code is in [`examples/chat`](../examples/chat). Run it on [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat), or on your machine:
+
+```bash
+cd examples/chat
+npm install
+npm run dev
+```
+
+`npm run dev` starts the server and Vite together. Start it with `CHAOS=off npm run dev` to turn the failures off.
+
+## Read how the server fails
+
+The server keeps its data in memory. These rules are on purpose, and they are the same every run, so you can follow each section below by doing what the table says:
+
+| What you do | What the server does | Section |
+| ----------- | -------------------- | ------- |
+| Select a room, then another before the first is shown | The room Random loads its history in 1.2 s, slower than the others. | [Load a history that must not race](#load-a-history-that-must-not-race) |
+| Send messages | Every third send answers 503. | [Send a message that can fail](#send-a-message-that-can-fail) |
+| Send `/fail hello` | Answers 400. | [Send a message that can fail](#send-a-message-that-can-fail) |
+| Search a word that is in Random | Random answers after 2.5 s. | [Search where one room is slow](#search-where-one-room-is-slow) |
+| Wait | A new message appears every 4 s. | [Poll for new messages](#poll-for-new-messages) |
+
+Open the Network panel of the browser while you do this. A request that the page aborts shows as cancelled there, and the server prints `aborted: ...` for it.
+
+## See how the files are split
+
+Each domain is a folder. 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. |
+
+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.
+
+## Load a history that must not race
+
+**Problem.** The reader clicks a slow room and then a fast one. If the slow answer arrives last, it shows the wrong room, and a hand-written loading flag stays `true` when a request is aborted.
+
+**When.** A load starts from a user choice that can change before it ends.
+
+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
+import { createJob } from "nanoeffects/actions";
+
+// createJob — a command that also sends pending, success, fail and cancel
+export const loadHistory = createJob("messages/loadHistory");
+```
+
+```js
+// messages-handlers.js
+import { latest } from "nanoeffects/policies";
+
+// latest — a load for a newer room aborts the older one, and its result is never delivered
+export const fetchHistory = latest((roomId, { signal }) => api.loadHistory(roomId, { signal }));
+```
+
+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
+import { createModule } from "nanoeffects/actions";
+import { loadHistory } from "./messages";
+import { fetchHistory } from "./messages-handlers";
+
+export const messagesModule = createModule("messages", (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"));
+  module.on(loadHistory.cancel, () => console.log("a newer load replaced it"));
+});
+```
+
+## Send a message that can fail
+
+**Problem.** A message must appear at once, go out in the order it was sent, be tried again after a failure, and show as failed if it never arrives. The outcome `fail` carries only the error, not the call, so the page cannot tell which message failed.
+
+**When.** An action has a visible result that can fail and that must keep its order.
+
+`queue` keeps the order, `retry` tries a failed call again, and the handler throws an error that carries the id of the message:
+
+```js
+import { retry } from "nanoeffects/effects";
+import { queue } from "nanoeffects/policies";
+
+class SendFailed extends Error {
+  constructor(localId, cause) {
+    super(cause.message);
+    this.localId = localId;
+  }
+}
+
+// A 400 is an answer: asking again gives the same answer. A 503 or a lost connection may pass.
+const isWorthRetrying = (error) => !(error.status < 500);
+
+// retry — try a failed send again, up to 3 attempts, 200 ms apart, unless the answer was a "no"
+const attempt = retry(
+  async (call, { signal }) => {
+    const message = await api.send(call.roomId, call.text, { signal });
+    return { localId: call.localId, message };
+  },
+  { times: 3, delay: 200, shouldRetry: isWorthRetrying },
+);
+
+// queue — messages go out one after another, in the order they were sent
+export const deliver = queue(async (call, ctx) => {
+  try {
+    return await attempt(call, ctx);
+  } catch (error) {
+    throw new SendFailed(call.localId, error);
+  }
+});
+```
+
+The module adds the message on `pending`, marks it delivered on `success`, and marks the message named by the error as failed on `fail`. Send `/fail hello` to see a failure that is not tried again, and send a few messages to meet the 503 that is.
+
+## Search where one room is slow
+
+**Problem.** A search asks every room. If it waits for all of them and one room is slow or broken, the reader sees nothing. If it fails on the first error, the rooms that answered are lost.
+
+**When.** One action fans out to several sources and a partial answer is better than none.
+
+`timeout` limits each request, and `allSettled` waits for every request to end, whether it succeeded or failed. The handler keeps the hits and the names of the rooms that did not answer:
+
+```js
+import { allSettled, timeout } from "nanoeffects/effects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const rooms = [{ id: "general", name: "General" }, { id: "random", name: "Random" }];
+
+const searchRoom = (room, query) => ({ signal }) => api.searchRoom(room.id, query, { signal });
+
+// timeout — a room that does not answer in 1.5 s fails with a timeout error
+const askRoom = (room, query) => {
+  const request = searchRoom(room, query);
+  return (parent) => timeout(parent, 1500, request);
+};
+
+// debounce — wait for quiet; latest — a newer query aborts the older search
+export const runSearch = debounce(
+  300,
+  latest(async (query, ctx) => {
+    // allSettled — ask every room at once and wait for all of them, however each one ends
+    const outcomes = await allSettled(ctx, rooms.map((room) => askRoom(room, query)));
+    return outcomes.map((outcome, index) => ({ room: rooms[index], outcome }));
+  }),
+);
+```
+
+`all` would fail the whole search on the first slow room, which is the wrong behavior here. See [Effects](effects.md) for the others.
+
+## Wait for a room before marking a result
+
+**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.
+
+`take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
+
+```js
+import { createCommand } from "nanoeffects/actions";
+import { take } from "nanoeffects/effects";
+
+// createCommand — an order for the messages domain, 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
+let selectedRoom = "general";
+
+export const goToResult = async (hit, ctx) => {
+  if (hit.roomId !== selectedRoom) {
+    // take — wait for the next event of that name; started before the emit so nothing is missed
+    const loaded = take(ctx, "messages/loadHistory/success");
+    ctx.emit("rooms/selected", hit.roomId);
+    await loaded;
+  }
+  // ctx.emit with a command — the messages domain marks the message
+  ctx.emit(markMessage(hit.id));
+};
+```
+
+## Poll for new messages
+
+**Problem.** New messages come from the server, and the page has to ask for them at an interval. The polling must stop when the feature is switched off, and one failed request must not stop it.
+
+**When.** A feature has background work that lives as long as the feature does.
+
+`poll` calls a function now and then at an interval, and ends when its context is aborted. A module starts the task with `spawn`, and unmounting the module aborts it:
+
+```js
+import { createModule } from "nanoeffects/actions";
+import { poll } from "nanoeffects/effects";
+
+const watchUpdates = async (_, ctx) => {
+  // the number of the last update seen; the first answer only tells where the server is
+  let since;
+
+  const check = async () => {
+    try {
+      const updates = await api.loadUpdates(since, { signal: ctx.signal });
+      since = updates.seq;
+      for (const message of updates.messages) {
+        // ctx.emit — after an abort it delivers nothing
+        ctx.emit("incoming/received", message);
+      }
+    } catch {
+      // one failed request must not end the polling: the next tick asks again
+    }
+  };
+
+  // poll — call `check` now and then every 3 s; an abort of ctx (an unmounted module) ends it
+  await poll(ctx, check, 3000, { leading: true });
+};
+
+export const incomingModule = createModule("incoming", (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.
+
+## 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).
+
+## 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).

package/docs/migrating-from-rxjs.md

@@ -1,6 +1,6 @@
 # Use nanoeffects next to RxJS
 
-Read this page if your project uses RxJS and you wonder what nanoeffects takes over. It does not replace RxJS. The two split the work: RxJS shapes streams of values, nanoeffects runs the side effects that events start. It maps the operators, shows one search box both ways, and lists what stays in RxJS.
+Read this page if your project uses RxJS and you wonder what nanoeffects takes over. It does not replace RxJS. The two split the work: RxJS shapes streams of values, nanoeffects runs the side effects that events start. It maps the operators, shows a search box and a polling loop both ways, and lists what stays in RxJS.
 
 ## Split the work
 
@@ -82,6 +82,63 @@ input.addEventListener("input", (event) => bus.emit("typed", event.target.value)
 
 The skip of repeated values is not here. Add `if (query === lastQuery) return;` to the handler, or keep that one step in RxJS (next section).
 
+## Rewrite a polling loop
+
+Check a job status every 5 seconds. Retry a failed check, and stop when the user leaves the screen.
+
+The same job in RxJS: `timer` ticks, `exhaustMap` skips a tick while a check runs, `retry` repeats a failed check, `takeUntil` stops it.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+// RxJS
+import { timer } from "rxjs";
+import { exhaustMap, retry, takeUntil } from "rxjs/operators";
+
+timer(5000, 5000)
+  .pipe(
+    exhaustMap(() => api.statusStream().pipe(retry({ count: 3, delay: 500 }))),
+    takeUntil(leave$),
+  )
+  .subscribe((status) => render(status));
+```
+
+The same job in nanoeffects. `poll` ticks, `retry` repeats one check, and `race` ends the loop on the first `"leave"` event:
+
+```js
+import { createBus } from "nanoeffects";
+import { poll, race, retry, take } from "nanoeffects/effects";
+
+const bus = createBus(); // the bus: events and handlers
+
+bus.on("watch", async (_, ctx) => {
+  // one check, up to 3 attempts, 500 ms between them
+  const checkStatus = async () => {
+    const status = await retry(ctx, () => api.status({ signal: ctx.signal }), {
+      times: 3,
+      delay: 500,
+    });
+    ctx.emit("status", status);
+  };
+
+  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 }),
+    // take: resolves at the next "leave", and race stops the polling
+    leave: ({ signal }) => take(ctx, "leave", { signal }),
+  });
+});
+
+bus.on("status", (status) => render(status));
+
+bus.emit("watch"); // start
+bus.emit("leave"); // stop
+```
+
+Two things differ from the pipeline:
+
+- `waitForFn: true` plays the role of `exhaustMap`: checks never overlap. Without it `poll` keeps a steady rate, and a slow check can overlap the next one.
+- If all 3 attempts fail, the error stops `poll`, as an error ends an Observable. To keep polling after a failed check, catch it inside `checkStatus` and emit an `"error"` event.
+
 ## Use both in one app
 
 Keep RxJS where a stream is how you think, and let events cross to the bus in either direction.

package/docs/package.md

@@ -16,6 +16,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/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) |
 

package/docs/plugins.md

@@ -82,7 +82,7 @@ import { modulePlugin } from "nanoeffects/actions";
 
 const bus = createBus();
 
-// modulePlugin — mounts userModule on the first use of the app or the bus, and returns the app
+// modulePlugin — mounts userModule at the end of this block, or at the first use if that is earlier, and returns the app
 const app = bus.use(modulePlugin([userModule]));
 
 app.unmount(userModule); // its listeners, bound commands and tasks are gone
@@ -261,7 +261,7 @@ export const bus = createBus()
 // commandsPlugin — the registry of command handlers; keep it to bind handlers later
 export const commands = bus.use(commandsPlugin());
 
-// modulePlugin — mounts userModule on the first use; keep app to mount and unmount later
+// modulePlugin — mounts userModule at the end of this block; keep app to mount and unmount later
 export const app = bus.use(modulePlugin([userModule]));
 
 // devPlugin — reports leaks and modules while you develop; keep disconnect to remove it
@@ -274,7 +274,7 @@ The plugins give the same result in any order. Use them as they read best, and p
 
 Two things happen because modules are mounted late:
 
-- **Modules start on the first use.** `modulePlugin([userModule])` mounts `userModule` when the app or the bus is first used: the first `bus.emit`, or the first call of `app.mount`, `app.unmount`, `app.isMounted`, `app.dispose` or the read of `app.commands`. By then every plugin is on the bus, so a module and the tasks it spawns have the fields, effects and scopes of the plugins you used after `modulePlugin`, and `m.on(fn, handler)` works with `matchPlugin`.
+- **Modules start at the end of the block.** `modulePlugin([userModule])` mounts `userModule` when the synchronous block that made it has finished, or earlier if the app or the bus is used first: the first `bus.emit`, or the first call of `app.mount`, `app.unmount`, `app.isMounted`, `app.dispose` or the read of `app.commands`. By then every plugin used in the same block is on the bus, so a module and the tasks it spawns have the fields, effects and scopes of the plugins you used after `modulePlugin`, and `m.on(fn, handler)` works with `matchPlugin`. A plugin used after an `await` can come too late: use every plugin before the first `await`. With no module, `modulePlugin()` starts nothing until the first use.
 - **Listeners keep their place.** A `bus.on` after `bus.use(modulePlugin(...))` is held until the modules are mounted, then made, in the order you wrote them. The listeners of a module therefore stay ahead of the ones registered after the plugin, and behind the ones registered before it. The function `bus.on` returns works before and after.
 
 Other plugins do not need an order for another reason:

package/docs/policies.md

@@ -36,6 +36,33 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
+## Call a policy without its function
+
+**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+
+**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them as before: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+
 ## Configure debounce and throttle
 
 `debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.

package/docs/query-libraries.md

@@ -122,3 +122,5 @@ Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the c
 - **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Commands that fetch are async, so this only matters for a sync handler that sets up a callback.
 - **Give each request its own signal for an event.** For a command or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
 - **The signal reaches the tasks that this `emit` starts**, with the listeners of the command's type and the `ctx.run` children. A separate `bus.emit` that the handler makes is not linked: pass `{ signal: ctx.signal }` to it.
+
+A whole small app, with a search, a filter, pages and a detail panel, is in the [Rick and Morty example](../examples/rickandmorty).

package/docs/react.md

@@ -248,8 +248,8 @@ export const Search = ({ wait }) => {
       const found = await api.search(query, { signal });
       setItems(found);
     },
-    // the second argument builds the policy once; task runs the callback above
-    (task) => debounce(wait, task),
+    // debounce(wait) — the second argument builds the policy once around the callback above
+    debounce(wait),
     // deps — list what the second argument reads; a new wait makes a new policy
     [wait],
   );
@@ -265,7 +265,9 @@ export const Search = ({ wait }) => {
 
 - `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
 - A pending call is cancelled on unmount and when `deps` change.
-- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
+- To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
+- `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
 - Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
 
 ## Where to go next

package/docs/starter.md

@@ -47,6 +47,8 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `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 |
+| `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 |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -60,6 +62,26 @@ The TypeScript templates are the same apps with the same files, written in `.ts`
 npm create nanoeffects@latest my-app -- --template react-ts
 ```
 
+### Start with Vue
+
+`vue-ts` is the search app of `react-ts` in Vue 3 with `<script setup lang="ts">`. Its bus uses `vuePlugin` from `nanoeffects/vue`: `watchEmitter` sends the query to the bus when it changes, and `useEventRef` keeps the result of the search in a `ref`. Like `useEventState` in React, `useEventRef` is [not a store](vue.md#it-is-not-a-store): a value that several components share belongs in a store such as Pinia.
+
+```bash
+npm create nanoeffects@latest my-app -- --template vue-ts
+```
+
+`npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
+
+### 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.
+
+```bash
+npm create nanoeffects@latest my-app -- --template svelte-ts
+```
+
+`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+
 ### Start with domains
 
 `domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
@@ -76,11 +98,13 @@ 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).
+
 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).
 
 ## Read the files
 
-Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for components).
+Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
 
 | File | Job |
 | ---- | --- |

package/docs/typescript.md

@@ -129,6 +129,20 @@ const user = bus.emit(getUser("1")); // Promise<User>
 
 `createModule` of the app only creates the module: it does not mount it, and it keeps no link to the bus. That is why the app in `bus.ts` starts without modules. `createModule` from `nanoeffects/actions` stays for a module made without a bus: there you write the event map yourself, `createModule<AppEvents>("user", …)`.
 
+## Type a function that takes the signal
+
+A function that makes a request should take the `signal` of the task, so aborting the task cancels the request. `WithSignal` is the type for that parameter: an object with a `signal`. It is checker-only, like `WithContext`: it adds nothing to your bundle.
+
+```ts
+import type { WithSignal } from "nanoeffects";
+
+// WithSignal — { signal: AbortSignal }; a task context fits it, and so does { signal } on its own
+const search = (query: string, { signal }: WithSignal) =>
+  fetch(`/search?q=${encodeURIComponent(query)}`, { signal });
+```
+
+Pass `ctx` (or `{ signal }`) when you call it. The effects of `nanoeffects/effects` (`retry`, `timeout`, `all`) take an optional signal instead, because outside a task you may pass `{}`; that is a different type, and you do not write it.
+
 ## 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:

package/docs/vue.md

@@ -0,0 +1,96 @@
+# Use nanoeffects in a Vue app
+
+Use this page when your app is in Vue 3 and a component has to talk to the bus: tell it that a value changed, and show the result of an event. `vuePlugin` gives you two functions for that. To see them in a running project, start from the `vue-ts` template in [Start a project from a template](starter.md#start-with-vue).
+
+You need Vue 3.3 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.** Without help, a component writes `watch(query, (value) => bus.emit(queryChanged(value)))` and its own subscription in `onMounted` and `onUnmounted`. The same few lines are copied into every component, and each copy forgets something: the cleanup, the equality check, or the name of the subscription in the trace.
+
+**When.** A Vue component sends values to the bus, reads events from it, or both.
+
+`vuePlugin()` adds two functions to the bus. Take them out of the bus once, in the file that makes it, and import them where you need them:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { vuePlugin } from "nanoeffects/vue";
+
+// createBus — the event bus, created once outside Vue
+// vuePlugin — adds watchEmitter and useEventRef to the bus
+export const bus = createBus().use(vuePlugin());
+export const { watchEmitter, useEventRef } = bus; // free functions: they do not read `this`
+```
+
+## Tell the bus that a value changed
+
+<!-- docs-check: continue -->
+
+`watchEmitter(source, event)` watches a `ref` or a getter and emits `event` with the new value after it changes. It does not emit when it is called, and it stops when the component unmounts. It is `watch` that ends with an emit, so it follows the rules of `watch`: several changes in one tick emit once, with the last value, and a `ref` that holds an object that you change in place does not trigger it.
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — an event with a name; calling it builds { type, payload }
+export const queryChanged = createAction("search/queryChanged");
+export const searchLoaded = createAction("search/loaded");
+```
+
+```js
+// query-box.js
+import { ref } from "vue";
+import { watchEmitter } from "./bus";
+import { queryChanged } from "./search";
+
+export const setup = () => {
+  const query = ref("");
+
+  // watchEmitter — emits queryChanged(query) when query changes, never on mount
+  watchEmitter(query, queryChanged);
+
+  return { query };
+};
+```
+
+The third argument takes the options `equals`, `traceId` and `traceGroupId`:
+
+| Option | Use it when |
+| ------ | ----------- |
+| `equals(previous, next)` | A new object with the same fields should not emit: `{ equals: (a, b) => a.id === b.id }`. |
+| `traceId` | You want the subscription to have a name in the [trace](tracing.md#show-which-subscription-began-a-chain). |
+| `traceGroupId` | You want to name the whole flow that the emit starts. |
+
+`watchEmitter` returns the function that stops it early, for use outside a component.
+
+## Show the result of an event
+
+<!-- docs-check: continue -->
+
+`useEventRef(event, initial)` returns a `ref` that starts as `initial`, and that every `event` of the bus sets to its payload. It stops listening when the component unmounts. A payload that is a function is stored, not called.
+
+```js
+// found-list.js
+import { useEventRef } from "./bus";
+import { searchLoaded } from "./search";
+
+export const setup = () => {
+  // useEventRef — like ref([]), but searchLoaded sets the value
+  const found = useEventRef(searchLoaded, []);
+
+  return { found };
+};
+```
+
+In TypeScript the type of the `ref` comes from the event: with `createAction<string[]>("search/loaded")` it is `Ref<string[]>`, and for an event with no payload type it comes from `initial`.
+
+### It is not a store
+
+`useEventRef` is state of one component. Each component that calls it keeps its own copy of the last payload, and the bus keeps no values, so an event that came before the call is lost. To share a value between components, or to keep it for components that mount later, keep it in a store such as Pinia and write to it from a handler of the event. Or call `useEventRef` once in a component at the root and pass the `ref` down with `provide` and `inject`.
+
+## Where to go next
+
+- The same two jobs for React: [Build a sign-up form in React](react.md).
+- 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).