nanoeffects 0.19.0 → 0.20.0

package/dist/vue.d.ts

@@ -0,0 +1,72 @@
+import { T as EventKey, h as Bus, r as FreeActionCreator, t as ActionCreator, z as EventMap } from "./action-creator-Bpa8BUS9.js";
+import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
+import { t as StateOf } from "./state-of-C19H6BoV.js";
+import { ShallowRef, WatchSource, WatchStopHandle } from "vue";
+//#region src/vue/plugin.d.ts
+/** Tells whether two values are the same. */
+type Equals<V> = (previous: V, next: V) => boolean;
+/** The third argument of `watchEmitter`. */
+type WatchEmitterOptions<V> = OriginOptions & {
+  /** Tells whether a new value is the same as the previous one, for a new object with the same fields. */
+  equals?: Equals<V>;
+};
+/** What `vuePlugin` adds to the bus. */
+type VueApi<E extends EventMap> = {
+  /**
+   * Watches a ref or a getter and emits `event` with its new value when it changes. It
+   * does not emit when it is called, and it stops with the effect scope (a component) that
+   * called it. Like Vue's `watch`, it runs before the next render, so several changes in
+   * one tick emit once, with the last value. The method does not read `this`, so
+   * `export const { watchEmitter } = bus` gives a free function. It returns the function
+   * that stops it early.
+   */
+  watchEmitter: {
+    <K extends EventKey<E>>(source: WatchSource<E[K]>, event: K, options?: WatchEmitterOptions<E[K]>): WatchStopHandle;
+    /** A creator without a payload type: the payload comes from the event map. */
+    <K extends EventKey<E>>(source: WatchSource<E[K]>, creator: FreeActionCreator<K>, options?: WatchEmitterOptions<E[K]>): WatchStopHandle;
+    <P, T extends string>(source: WatchSource<P>, creator: ActionCreator<P, T>, options?: WatchEmitterOptions<P>): WatchStopHandle;
+  };
+  /**
+   * A ref that starts as `initial`, and that every emit of `event` sets to its payload
+   * while the effect scope (a component) that called it lives. A function payload is stored,
+   * not called. The bus keeps no values, so an event emitted before the call is not seen. It
+   * is state of one component, not a store. The method does not read `this`, so
+   * `export const { useEventRef } = bus` gives a free function.
+   */
+  useEventRef: {
+    <K extends EventKey<E>, S>(event: K, initial: StateOf<E[K], S>): ShallowRef<StateOf<E[K], S>>;
+    /** A creator without a payload type: the payload comes from the event map. */
+    <K extends EventKey<E>, S>(creator: FreeActionCreator<K>, initial: StateOf<E[K], S>): ShallowRef<StateOf<E[K], S>>;
+    <P, T extends string>(creator: ActionCreator<P, T>, initial: P): ShallowRef<P>;
+  };
+};
+/**
+ * Adds `bus.watchEmitter(source, event)` and `bus.useEventRef(event, initial)`: the two
+ * jobs of a Vue component with the bus. `watchEmitter` tells the bus when a value of the
+ * component changes, and `useEventRef` keeps the last payload of an event in a ref. Pass
+ * `{ equals }` to `watchEmitter` for values that `Object.is` tells apart although they are
+ * the same, and `{ traceId }` and `{ traceGroupId }` to name the subscription and the flow
+ * in the trace of the bus. Needs `vue` 3.3 or newer. Returns the same bus.
+ *
+ * @example
+ * ```ts
+ * import { createBus } from "nanoeffects";
+ * import { createAction } from "nanoeffects/actions";
+ * import { vuePlugin } from "nanoeffects/vue";
+ * import { ref } from "vue";
+ *
+ * export const bus = createBus().use(vuePlugin());
+ * export const { watchEmitter, useEventRef } = bus; // free functions
+ *
+ * const nameChanged = createAction<string>("name/changed");
+ * const nameSaved = createAction<string[]>("name/saved");
+ *
+ * // inside setup():
+ * const name = ref("Adam");
+ * watchEmitter(name, nameChanged); // nameChanged("…") on every change of name, not on mount
+ * const saved = useEventRef(nameSaved, []); // Ref<string[]>, set by every nameSaved
+ * ```
+ */
+export declare const vuePlugin: () => <E extends EventMap>(bus: Bus<E>) => Bus<E> & VueApi<E>;
+//#endregion
+export type { VueApi };

package/dist/vue.js

@@ -0,0 +1 @@
+import{t as e}from"./origin-key-BbWN3gmN.js";import{onScopeDispose as t,shallowRef as n,watch as r}from"vue";const i=()=>i=>{function a(t,n,a){return r(t,(t,r)=>{let o=r,s=t;if(a?.equals?.(o,s))return;let c=typeof n==`function`?n(s):{type:n,payload:t},l=Reflect.get(i,e);l?l(c,a??{}):i.emit(c)})}function o(e,r){let a=n(r),o=e;return t(i.on(o,e=>{a.value=e})),a}return Object.assign(i,{watchEmitter:a,useEventRef:o})};export{i as vuePlugin};

package/dist/{with-policy-C_mX7S54.d.ts → with-policy-BeH8wCkX.d.ts}

@@ -1,4 +1,4 @@
-import { R as EventMap, U as Task, V as PayloadOf } from "./action-creator-HFA_LZOH.js";
+import { H as PayloadOf, W as Task, z as EventMap } from "./action-creator-Bpa8BUS9.js";
 //#region src/policies/with-policy.d.ts
 /** What `withPolicy` returns: the task as a plain function that can be cancelled. */
 type PolicyFunction<P, R> = {

package/docs/README.md

@@ -18,6 +18,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | Domain logic off the UI | [Actions, commands, modules](actions.md) |
 | Already on Redux / Zustand / MobX / Pinia | [Stores](stores.md) |
 | A React form with async checks | [Build a sign-up form in React](react.md) |
+| A Vue app | [Use nanoeffects in a Vue app](vue.md) |
 | Old responses overwrite new ones | [Cancel stale requests](cancel-stale-requests.md) |
 | Debounced input that must also cancel the old request | [Debounce and abort](debounce-and-abort.md) |
 | A second click sends a second request | [Prevent a double submit](prevent-double-submit.md) |
@@ -32,6 +33,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 - [Effects and cancellation](effects.md) — `retry`, `timeout`, `poll`, `take`, `all`, …
 - [Actions, commands, jobs and modules](actions.md)
 - [Sign-up form in React](react.md) — one form: races, double submit, retry
+- [nanoeffects in a Vue app](vue.md) — `watchEmitter` and `useEventRef`
 - [Context fields](context.md) — store or client on every task
 - [Use the bus from a class](oop.md) — `extendBus`, `@WithBus`, `@On`, and `dispose()` for the subscriptions of an instance
 - [TypeScript in many files](typescript.md) — keep the types of the bus in commands and modules

package/docs/actions.md

@@ -6,6 +6,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
@@ -252,11 +254,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.

package/docs/chat-example.md

@@ -0,0 +1,241 @@
+# 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).

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/starter.md

@@ -47,6 +47,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
@@ -60,6 +61,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.
@@ -76,11 +87,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 |
 | ---- | --- |

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: