nanoeffects 0.19.0 → 0.20.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/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/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.
 
 ---
@@ -552,6 +552,7 @@ 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 |
 
 ```bash
 npm create nanoeffects@latest my-app -- --template react
@@ -565,6 +566,16 @@ 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 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.
@@ -581,11 +592,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).
 
 | File | Job |
 | ---- | --- |
@@ -668,6 +681,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) |
 
@@ -770,7 +784,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
@@ -949,7 +963,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
@@ -962,7 +976,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:
@@ -1882,6 +1896,8 @@ 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 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)).
 
 ## Return a value from `emit` with a command
@@ -2128,11 +2144,39 @@ app.commands.handle(getUser, fakeUser); // in a test
 app.dispose(); // unmounts every module
 ```
 
+`mount` and `unmount` take any number of modules. Use it to start the domains of an app yourself, at the moment you choose and in the order you give, when you do not give them to `modulePlugin`:
+
+```js
+import { createModule } from "nanoeffects/actions";
+import { app } from "./bus";
+
+const userModule = createModule("user", (m) => {
+  m.on("user/loaded", (user) => console.log(user));
+});
+const orderModule = createModule("order", (m) => {
+  m.on("order/placed", (order) => console.log(order));
+});
+
+// mount — start both modules, left to right
+const stop = app.mount(userModule, orderModule);
+
+// the returned function stops them again, last mounted first (orderModule, then userModule)
+stop();
+
+// the same for modules that you already have in an array: spread it
+const modules = [userModule, orderModule];
+app.mount(...modules);
+app.unmount(...modules); // also in reverse order
+```
+
+If the `setup` of one module throws, the modules of that call that were already mounted are unmounted again and the error is thrown, so a call mounts all of its modules or none. A module that is mounted already is skipped.
+
 - **Unmounting undoes everything** the module did: subscriptions, bound commands, sub-modules, and background tasks (aborted).
 - **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
 - **Registry.** If `bus.use(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
 - A disposed app cannot mount modules.
-- **The given modules are mounted on the first use** of the app or the bus (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`), so the plugins you use after `modulePlugin` still reach them. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
+- **The given modules are mounted at the end of the block that made the app**, or at the first use of the app or the bus if that comes first (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`). Nothing needs to use the app: `bus.use(modulePlugin([a, b]))` is enough to start them. The plugins that you use after `modulePlugin` in the same block still reach them, because the modules wait until that block has finished. A plugin used after an `await` can come too late: use every plugin before the first `await`. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
+- **To mount by hand instead**, pass no modules: `modulePlugin()` starts nothing, and `app.mount(...)` starts the modules when you want.
 - Module context = task context plus `handle`, `use`, and `spawn`:
   - `handle` — give a command a handler (contract, or override).
   - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
@@ -3259,6 +3303,351 @@ export const Search = ({ wait }) => {
 - A state library instead of `useState`: [Stores](stores.md).
 - React Query or SWR instead of your own state: [Use nanoeffects with React Query and SWR](query-libraries.md).
 
+---
+Source: docs/chat-example.md
+
+# 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.
+
+## 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 { take } from "nanoeffects/effects";
+
+// the room that is open, kept from the rooms/selected event
+let selectedRoom = "general";
+
+export const openResult = 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("messages/marked", 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).
+
+---
+Source: docs/vue.md
+
+# 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).
+
 ---
 Source: docs/context.md
 
@@ -4140,6 +4529,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:
@@ -4697,7 +5100,7 @@ Source: docs/migrating-from-rxjs.md
 
 # 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
 
@@ -4779,6 +5182,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/llms.txt

@@ -9,13 +9,13 @@ 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/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/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
 
 - [Guide](docs/guide.md): bus, handler context, policies, effects, commands and modules, step by step
-- [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla` or `react`) with a bus, `debounce` and `latest`
+- [Start a project from a template](docs/starter.md): `npm create nanoeffects` makes a Vite project (`vanilla`, `react`, `vue-ts` and others, in JavaScript or TypeScript) with a bus, `debounce` and `latest`
 - [Why nanoeffects exists](docs/motivation.md): no dependencies and no global state for SDKs and Module Federation, and why not Redux, Effector or RxJS
 - [Package entries](docs/package.md): which import holds what
 - [Plugins](docs/plugins.md): every plugin of a bus, what `bus.use` returns, and the order to use them in
@@ -35,6 +35,8 @@ Rules that generated code often gets wrong:
 - [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
 - [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`
+- [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)
 - [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