nanoeffects 0.28.0 → 0.30.1

package/docs/ru/typescript.md

@@ -0,0 +1,170 @@
+# Работа с TypeScript
+
+> **[Уровень D](README.md#виды-проектов)**: доменная логика вне UI. Сначала прочитайте: [Руководство](guide.md#10-поддержка-typescript).
+
+Обработчики и модули лежат в разных файлах. Как написать action с обработчиком, чтобы TypeScript вывел payload и результат, и что добавить, когда обработчикам нужны поля шины (`ctx.store`, эффекты из `effectsPlugin`). Для одного файла и для JavaScript страница не нужна.
+
+## Action вместе с обработчиком
+
+Payload берётся из аннотированного параметра, результат — из тела; обобщение писать не надо.
+
+<!-- docs-check: skip - файл из examples/typescript, проверяется типами там -->
+```ts
+// user.ts
+import { createAction, createModule } from "nanoeffects/actions";
+
+export type User = { id: string; name: string };
+
+// payload: string, из `id: string`; результат: Promise<User>, из тела
+export const getUser = createAction(
+  "user/get",
+  async (id: string, { signal }) => {
+    const response = await fetch(`/api/users/${id}`, { signal });
+    const user: User = await response.json();
+    return user;
+  },
+);
+
+// createModule: m.use привязывает обработчик, который несёт action, пока модуль подключён
+export const userModule = createModule("user", (m) => {
+  m.use(getUser);
+});
+```
+
+Подключите модуль там, где создаёте шину. Результат типизируется по обработчику:
+
+<!-- docs-check: skip - файл из examples/typescript, проверяется типами там -->
+```ts
+// main.ts
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { getUser, userModule } from "./user";
+
+const bus = createBus();
+const app = bus.use(modulePlugin([userModule])); // подключает модули
+
+const user = bus.emit(getUser("1")); // Promise<User>
+```
+
+Что аннотировать и почему:
+
+| Часть | Аннотировать? | Почему |
+| ----- | ------------- | ------ |
+| payload (`id: string`) | да | у параметра функции нет типа, из которого можно вывести |
+| `ctx` | нет, для `signal` и полей, которые есть у каждой задачи | `signal`, `emit`, `on` и `run` есть на каждом `ctx` |
+| результат | нет | выводится из тела |
+
+Неверная payload при вызове (`getUser(1)`) — ошибка. Аннотируйте параметры, а не переменную: тип на всей переменной, например `const handler: Task<string, Events> = …`, фиксирует тип функции, и результат становится `unknown`.
+
+## Поля шины в `ctx`
+
+Типы шины живут на шине. `contextPlugin({ store })` и `effectsPlugin({ race })` делают `ctx.store` и `ctx.race` известными обработчикам **этой шины**. Action с обработчиком, созданное в другом файле, шины не видит, поэтому на его `ctx` нет `store`:
+
+<!-- docs-check: skip - намеренно показывает ошибку -->
+```ts
+export const getUser = createAction("user/get", (id: string, ctx) => {
+  ctx.store; // ошибка: Property 'store' does not exist
+});
+```
+
+Во время выполнения шина всё равно даёт задаче её поля, не знает об этом только проверка типов. Назовите типы шины один раз в файле, который её создаёт. `contextPlugin` берёт тип каждого поля из переданного значения, поэтому карта событий описывает только события. `EventsOf` читает из шины карту событий вместе с полями, добавленными плагинами. Код этого раздела лежит в [`examples/typescript-context`](../../examples/typescript-context).
+
+<!-- docs-check: skip - файл из examples/typescript-context, проверяется типами там -->
+```ts
+// bus.ts
+import { type Context, createBus, type EventsOf } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { contextPlugin } from "nanoeffects/context";
+import { effectsPlugin, race } from "nanoeffects/effects";
+
+// Events: имя события → payload; о ctx здесь ничего не пишется
+type Events = { "user/loaded": User };
+
+export const bus = createBus<Events>()
+  .use(contextPlugin({ store })) // ctx.store, тип выводится из значения `store`
+  .use(effectsPlugin({ race })); // ctx.race; каждый плагин возвращает ту же шину, типизированную своими полями
+
+// приложение шины: подключает модули и создаёт их с типами шины
+export const app = bus.use(modulePlugin()); // модулей пока нет: их подключает main.ts
+export const { createModule } = app; // createModule с типами шины
+
+export type AppEvents = EventsOf<typeof bus>; // карта событий и все поля ctx
+export type AppContext = Context<AppEvents>; // ctx обработчика этой шины: есть store и race
+```
+
+| Тип | Что это | Зачем его называть |
+| --- | ------- | ------------------ |
+| `EventsOf<typeof bus>` | карта событий шины с полями контекста плагинов (и `WithContext`, если вы его используете) | источник для `AppContext` |
+| `Context<AppEvents>` | `ctx`, который получает обработчик шины | аннотируйте `ctx` обработчика, переданного в `createAction` |
+
+Эти типы ничего не меняют во время выполнения. Они лишь сообщают проверке типов то, что шина уже делает.
+
+Аннотируйте `ctx` через `AppContext` там, где обработчик читает поле шины, и создавайте модуль через `createModule`, который экспортирует `bus.ts`, чтобы обработчики его `m.on` тоже видели поля:
+
+<!-- docs-check: skip - файл из examples/typescript-context, проверяется типами там -->
+```ts
+// user.ts
+import { createAction } from "nanoeffects/actions";
+import { type AppContext, createModule } from "./bus";
+
+export const getUser = createAction(
+  "user/get",
+  (id: string, { store, signal }: AppContext) => store.fetchUser(id, { signal }),
+);
+
+// createModule из bus.ts: обработчики модуля видят поля контекста шины
+export const userModule = createModule("user", (m) => {
+  m.use(getUser);
+  m.on("user/loaded", (user, { store }) => store.remember(user));
+});
+```
+
+<!-- docs-check: skip - файл из examples/typescript-context, проверяется типами там -->
+```ts
+// main.ts: модули подключаются здесь, потому что файлам модулей нужен `app`
+import { app, bus } from "./bus";
+import { getUser, userModule } from "./user";
+
+const unmount = app.mount(userModule); // запускает модуль; unmount() его отменяет
+const user = bus.emit(getUser("1")); // Promise<User>
+```
+
+`createModule` приложения только создаёт модуль: он его не подключает и не хранит связи с шиной. Поэтому приложение в `bus.ts` стартует без модулей. `createModule` из `nanoeffects/actions` остаётся для модуля, созданного без шины: там карту событий вы пишете сами, `createModule<AppEvents>("user", …)`.
+
+## Типы функции, принимающей сигнал
+
+Функция, которая делает запрос, должна принимать `signal` задачи, тогда прерывание задачи отменит запрос. `WithSignal` — тип такого параметра: объект с `signal`. Как `WithContext`, он нужен только для проверки типов и в бандл ничего не добавляет.
+
+```ts
+import type { WithSignal } from "nanoeffects";
+
+// WithSignal — { signal: AbortSignal }; ему подходит контекст задачи и просто { signal }
+const search = (query: string, { signal }: WithSignal) =>
+  fetch(`/search?q=${encodeURIComponent(query)}`, { signal });
+```
+
+Передавайте `ctx` (или `{ signal }`) при вызове. Эффекты из `nanoeffects/effects` (`retry`, `timeout`, `all`) вместо этого принимают необязательный сигнал, потому что вне задачи можно передать `{}`; это другой тип, и писать его не нужно.
+
+## Контракт отдельно от кода
+
+Если файл с action не должен импортировать код, который его реализует, создайте action без обработчика. Payload и результат вы пишете один раз как `Call`, а обработчик уходит в модуль, где аннотации ему не нужны. `Call` — ваше обещание: ничто не сверяет его с обработчиком, поэтому держите обработчик в модуле типизированным по нему:
+
+<!-- docs-check: skip - фрагмент файла выше -->
+```ts
+export const getUser = createAction<Call<string, Promise<User>>>("user/get"); // контракт
+
+createModule("user", (m) => {
+  // payload и результат берутся из Call, ctx — из приложения: аннотации нет
+  m.handle(getUser, (id, { store, signal }) => store.fetchUser(id, { signal }));
+});
+```
+
+Неверная payload, неверное поле `ctx` и неверный результат — ошибки.
+
+## Частые ошибки
+
+- **Поля нет на `ctx`.** `ctx` обработчика, переданного в `createAction`, не аннотирован: добавьте `: AppContext`. Обработчику, написанному прямо в `m.handle` или `m.on` модуля, созданного через `createModule` из `bus.ts`, это не нужно. У `ctx` по умолчанию полей вашей шины нет.
+- **`EventsOf<typeof bus>` равен `never`.** `bus` — не шина. `bus.use(actionsPlugin())` и `bus.use(modulePlugin(...))` возвращают реестр или приложение, а не шину: держите шину в её собственной константе (`bus`, затем `app = bus.use(modulePlugin())`).
+- **`effectsPlugin` нет в типе.** `use` должен идти раньше, чем вы читаете `typeof bus`. Стройте цепочку `createBus(...).use(effectsPlugin(...))` в одной привязке.
+- **Политика теряет типы?** Нет: `latest(handler)` сохраняет payload, результат и контекст `handler`.
+- **Не передавайте контекст обобщением `createAction`.** Это четвёртый параметр обобщения формы с обработчиком, после payload, результата и строки типа, так что пришлось бы писать все четыре. Аннотируйте `ctx` через `AppContext` или положите обработчик в модуль, созданный через `createModule` из `bus.ts`.

package/docs/ru/vue.md

@@ -0,0 +1,92 @@
+# nanoeffects в приложении на Vue
+
+> **[Уровень B](README.md#виды-проектов)**: SPA с async UI. Сначала прочитайте: [Руководство](guide.md#1-создание-шины-событий).
+
+Задача: компонент на Vue 3 должен сообщить шине, что значение изменилось (например, текст в поле поиска), и показать результат события (найденные элементы). Для этого `vuePlugin` даёт две функции. Работающий пример — шаблон `vue-ts` из [Проекта из шаблона](starter.md#начало-с-vue).
+
+Нужны Vue 3.3 или новее и установленная `nanoeffects`. Не знакомы с шиной? Сначала прочитайте [Руководство](guide.md).
+
+## Плагин на шине
+
+**Проблема.** Без помощи компонент пишет `watch(query, (value) => bus.emit(queryChanged(value)))` и собственную подписку в `onMounted` и `onUnmounted`. Эти строки копируются в каждый компонент, и в каждой копии что-нибудь забыто: очистка, проверка равенства или имя подписки в трассировке.
+
+**Когда.** Компонент Vue отправляет значения в шину, читает из неё события или делает и то и другое.
+
+`vuePlugin()` добавляет на шину две функции. Достаньте их из шины один раз в файле, который её создаёт, и импортируйте где нужно:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { vuePlugin } from "nanoeffects/vue";
+
+// createBus — шина событий, создаётся один раз вне Vue
+// vuePlugin — добавляет на шину watchEmitter и useEventRef
+export const bus = createBus().use(vuePlugin());
+export const { watchEmitter, useEventRef } = bus; // свободные функции: они не читают `this`
+```
+
+## Сообщение шине об изменении значения
+
+<!-- docs-check: continue -->
+
+`watchEmitter(source, event)` следит за `ref` или геттером и отправляет `event` с новым значением. При вызове он ничего не отправляет, а при размонтировании компонента останавливается. Это `watch`, который заканчивается `emit`, поэтому действуют правила `watch`: несколько изменений за один тик дают одно событие с последним значением, а изменение объекта в `ref` на месте его не запускает.
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — событие с именем; вызов строит { 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 — отправляет queryChanged(query), когда query меняется, но не при монтировании
+  watchEmitter(query, queryChanged);
+
+  return { query };
+};
+```
+
+Третий аргумент принимает параметры `equals`, `traceId` и `traceGroupId`:
+
+| Параметр | Когда использовать |
+| -------- | ------------------ |
+| `equals(previous, next)` | Новый объект с теми же полями не должен отправляться: `{ equals: (a, b) => a.id === b.id }`. |
+| `traceId` | Нужно имя подписки в [трассировке](tracing.md#какая-подписка-начала-цепочку). |
+| `traceGroupId` | Нужно назвать весь поток, который запускает эта отправка. |
+
+`watchEmitter` возвращает функцию, которая останавливает его досрочно. Она нужна вне компонента.
+
+## Показ результата события
+
+<!-- docs-check: continue -->
+
+`useEventRef(event, initial)` возвращает `ref`. Сначала в нём `initial`, затем payload каждого `event` шины. При размонтировании компонента `ref` перестаёт слушать. Если payload — функция, `ref` сохраняет её, а не вызывает.
+
+```js
+// found-list.js
+import { useEventRef } from "./bus";
+import { searchLoaded } from "./search";
+
+export const setup = () => {
+  // useEventRef — как ref([]), но значение устанавливает searchLoaded
+  const found = useEventRef(searchLoaded, []);
+
+  return { found };
+};
+```
+
+В TypeScript тип `ref` берётся из события: для `createAction<string[]>("search/loaded")` это `Ref<string[]>`, а для события без типа payload он берётся из `initial`.
+
+### Это не store
+
+`useEventRef` — state одного компонента. Каждый вызывающий его компонент хранит свою копию последней payload. Шина значений не хранит, поэтому событие, пришедшее до вызова, теряется. Чтобы делить значение между компонентами или сохранить его для будущих, держите его в store, например в Pinia, и записывайте туда из обработчика события. Либо вызовите `useEventRef` один раз в корневом компоненте и передайте `ref` вниз через `provide` и `inject`.

package/docs/semantics.md

@@ -1,7 +1,19 @@
 # Semantics
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 6.
+
 Guarantees and sharp edges. Read when something surprises you; not required to start.
 
+## Five rules to know first
+
+1. A handler is `(payload, ctx)`. Use `ctx.signal`, `ctx.emit` and `ctx.on`; the rest of `ctx` is optional.
+2. Pass `ctx.signal` to what the handler calls (`fetch`, a client), so an abort stops the work.
+3. An aborted task delivers no result and emits nothing.
+4. `emit` is synchronous: the first handler error is thrown, unless `onError` is set.
+5. Rejections of async handlers are not handled without `onError`.
+
+Details of each rule and the rest:
+
 - **An aborted task delivers no result.** If the task aborts before a promise settles, the promise rejects with the abort reason, even if the value was just produced in the same tick. `latest`, `debounce`, `all`, `race`, `take`, and the rest follow this rule.
 - **`emit` is a plain, synchronous loop** (see [Errors](errors.md)). A `ctx.emit` inside a handler is the same call: without `onError`, an error of a nested handler is thrown into the handler that emitted; with `onError` it goes there and `ctx.emit` does not throw.
 - **Rejections of async handlers** are not handled for you. Without `onError` they are unhandled rejections, which end a Node process by default. Use `onError` for async handlers.

package/docs/server.md

@@ -1,5 +1,7 @@
 # Stop work on a server when the client leaves
 
+> **Level C.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if you run a Node server (the examples use [Fastify](https://fastify.dev)) and want the work for a request, a socket or a queued job to stop when nobody needs it. It shows one pattern in three places: a request, a WebSocket and a worker.
 
 You need Node 18 or newer, `fastify` and `nanoeffects`. `api` below is your own client for another service: replace it with your requests.
@@ -37,7 +39,7 @@ The action loads a user. It tries the request up to three times, and gives up on
 import { createAction } from "nanoeffects/actions";
 import { retry, timeout } from "nanoeffects/effects";
 
-// createAction — a command with a handler: emit returns what the handler returns
+// createAction — an action with a handler: emit returns what the handler returns
 export const getUser = createAction("user/get", async (id, ctx) => {
   // one try: the request, with the signal of timeout so it can stop it
   const load = ({ signal }) => api.getUser(id, { signal });
@@ -78,7 +80,7 @@ app.get("/users/:id", async (request, reply) => {
   });
 
   try {
-    // emit with { signal } — aborting the controller aborts the command: timeout, retry and the request
+    // emit with { signal } — aborting the controller aborts the action: timeout, retry and the request
     const call = getUser(request.params.id);
     return await bus.emit(call, { signal: controller.signal });
   } catch (error) {
@@ -131,7 +133,7 @@ import { createAction } from "nanoeffects/actions";
 import { poll } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
-// createAction — a command with a handler
+// createAction — an action with a handler
 // latest — a new subscription stops the old one; key — but only the old one of the same socket
 export const watchPrices = createAction(
   "prices/watch",

package/docs/starter.md

@@ -1,5 +1,7 @@
 # Start a project from a template
 
+> **Level A.** Read first: nothing: this page makes a project for you.
+
 Use this page when you want a running project in one command instead of wiring Vite and the bus by hand. It makes a small app with a search box that waits for you to stop typing (`debounce`) and aborts the older request when a newer one starts (`latest`).
 
 You need Node 18 or newer.

package/docs/stores.md

@@ -1,5 +1,7 @@
 # Connect Redux, Zustand, MobX, or Pinia
 
+> **Level E.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when you **already have a store** and want async work with cancellation and policies next to it. It is not a reason to pick Redux (or any store).
 
 If you do not have a store yet, use `createBus` from the [Guide](guide.md).

package/docs/svelte.md

@@ -1,5 +1,7 @@
 # Use nanoeffects in a Svelte app
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when your app is in Svelte 5 and a component has to show the result of an event. `sveltePlugin` gives you one function for that, `eventStore`. To see it in a running project, start from the `svelte-ts` template in [Start a project from a template](starter.md#start-with-svelte).
 
 You need Svelte 5 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
@@ -78,4 +80,4 @@ bus.on(searchLoaded, (titles) => foundTitles.set(titles));
 ## Where to go next
 
 - The same job for React: [Build a sign-up form in React](react.md); for Vue: [Use nanoeffects in a Vue app](vue.md).
-- A policy in a component (a debounced save): in the script of a component make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Svelte runs the script once, so it needs no hook.
+- A policy in a component (a debounced save): in the script of a component make it once with [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus); Svelte runs the script once, so it needs no hook.

package/docs/tracing.md

@@ -1,9 +1,29 @@
 # Trace tasks
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 and 2.
+
 Find out what your app did and why: which events were emitted, which calls a policy cancelled or dropped, which request failed. You see it in the browser console, in Redux DevTools, or in the Performance panel.
 
 Tracing is optional. A bus works the same without it, and it costs almost nothing until you turn it on. If you only want to see what happens while you develop, jump to [Show every emit](#show-every-emit) and [Configure Redux DevTools](#configure-redux-devtools); the rest of the page is for apps that need to follow a flow or turn tracing off in a build.
 
+## On this page
+
+- [Attach a tracer](#attach-a-tracer)
+- [Show every emit](#show-every-emit)
+- [Show which subscription began a chain](#show-which-subscription-began-a-chain)
+- [Follow one flow with a traceGroupId](#follow-one-flow-with-a-tracegroupid)
+- [Name a listener](#name-a-listener)
+- [Keep the chain: `ctx.emit`, not `bus.emit`](#keep-the-chain-ctxemit-not-busemit)
+- [Turn the names off](#turn-the-names-off)
+- [Use built-in loggers](#use-built-in-loggers)
+  - [Cut volume in production](#cut-volume-in-production)
+  - [Keep the last events for an incident](#keep-the-last-events-for-an-incident)
+  - [Configure Redux DevTools](#configure-redux-devtools)
+  - [Find loops with `graphLogger`](#find-loops-with-graphlogger)
+  - [Send safe data to a tool](#send-safe-data-to-a-tool)
+  - [Write your own logger](#write-your-own-logger)
+- [Drop tracing from a build](#drop-tracing-from-a-build)
+
 ## Attach a tracer
 
 Pass `trace` to `createBus`. Make it with `createTracer` from `nanoeffects/trace`, which takes a logger (a function) or an array of them. The tracing code lives in that entry, so a bus without `trace` does not carry it.
@@ -39,7 +59,7 @@ Phases:
 - `cancel` — aborted after it started (superseded by `latest`, parent aborted, lost a `race`).
 - `drop` — never started (`leading` while busy, a `throttle` call replaced by a newer one, a `debounce` call replaced before its delay ended).
 
-`all` and `race` are traced when you pass them the handler `ctx`: the group is one task; every starter is a child `run` task.
+`all` and `race` are traced when you pass them the handler `ctx`: the group is one task; every function of the group is a child `run` task.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -86,7 +106,7 @@ The event changes nothing else: the other tasks keep their `parentId`, `rootId`
 
 ## Show which subscription began a chain
 
-**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of commands and retries.
+**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of actions and retries.
 
 **When.** The bus has a tracer and the project has several `useEmitter` or `bus.emitter` calls. The names come from `tracePlugin`: use it on the bus, or the `traceId` is ignored.
 
@@ -114,8 +134,8 @@ In a component, the same option goes in the options of the hook: `useEmitter(nam
 
 ```
 [nanoeffects] Profile · run start
-[nanoeffects]   user/save · command start
-[nanoeffects]   user/save · command done
+[nanoeffects]   user/save · action start
+[nanoeffects]   user/save · action done
 [nanoeffects] Profile · run done
 ```
 
@@ -155,7 +175,7 @@ const pay = createAction("checkout/pay", async () => {}, {
 ```
 
 ```
-[nanoeffects] [checkout] checkout/pay · command start
+[nanoeffects] [checkout] checkout/pay · action start
 ```
 
 The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", traceGroupId: "checkout" })`. `traceGroupId` works without `scopePlugin`, and needs `tracePlugin`.
@@ -185,7 +205,7 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 
 ```
 [nanoeffects] saveNotifier · run start
-[nanoeffects]   user/save · command start
+[nanoeffects]   user/save · action start
 [nanoeffects] saveNotifier · run done
 ```
 
@@ -230,7 +250,8 @@ const bus = createBus({
 | `reduxDevtools()` | Sends the emits to Redux DevTools, and with `policies` the stages of the handlers as `type/effect/phase`; state is `{ running }` |
 | `consoleLogger()` | Prints one line per phase, indented by task depth |
 | `performanceLogger()` | User Timing measures for the browser Performance panel |
-| `createTraceRecorder()` | Keeps events in `recorder.events`, for tests |
+| `createTraceRecorder()` | Keeps events in `recorder.events`: all of them for tests, or with `{ capacity }` the last N ([see below](#keep-the-last-events-for-an-incident)) |
+| `graphLogger()` | Builds the map of which event leads to which, finds loops while the app runs, and writes the map as Mermaid, Graphviz or JSON ([see below](#find-loops-with-graphlogger)) |
 
 ### Cut volume in production
 
@@ -246,8 +267,60 @@ createTracer(logger, {
 - `sample` is decided once per root task; every task below it follows, so a trace is never cut in the middle. Unsampled tasks cost almost nothing.
 - `filter` runs on each event before any logger sees it.
 
+### Keep the last events for an incident
+
+`createTraceRecorder()` with no option keeps every event, so a long session fills memory. That is fine in a test and wrong in a running app. Give it a `capacity` and it keeps only the last N events (a ring buffer): when something goes wrong, you still have what led up to it.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer } from "nanoeffects/trace";
+
+// A logger that keeps the last 500 events and drops the older ones.
+export const recorder = createTraceRecorder({ capacity: 500 });
+
+// Feed the recorder from the tracer.
+const trace = createTracer(recorder);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// incident.js
+import { recorder } from "./bus";
+
+// Keep what is safe to send. An event also has `payload` and `error`.
+const withoutPayload = ({ id, parentId, type, effect, phase }) => ({
+  id,
+  parentId,
+  type,
+  effect,
+  phase,
+});
+
+window.addEventListener("error", () => {
+  const events = recorder.events; // a snapshot, oldest event first
+  const safe = events.map(withoutPayload);
+  const body = JSON.stringify(safe);
+  navigator.sendBeacon("/api/incident", body);
+});
+```
+
+What to know before you send the events:
+
+- **`payload` and `error` can hold private data**: what a user typed, tokens, personal text. The recorder keeps them as they are and does not redact. Choose what to send, as `withoutPayload` does.
+- **There is no time on an event.** You get the order, not the duration. To add a time, wrap the recorder in a logger that stamps `performance.now()` on a copy of the event.
+- **An old `parentId` can point at an event that was pushed out.** When you build a tree from the events, treat an unknown `parentId` as a root.
+- **`recorder.events` is a snapshot with a `capacity`.** Each read builds a new array, so read it once at the moment you need it. Without a `capacity` it is one live array.
+- **A low `sample` thins the buffer.** `createTracer(recorder, { sample: 0.05 })` records 5% of root tasks, so the buffer may hold little when the incident comes. See [Cut volume in production](#cut-volume-in-production).
+- **A `capacity` that is not a positive integer** (`0`, a negative number, `NaN`) means no limit.
+
 ### Configure Redux DevTools
 
+<!-- docs-check: new -->
+
 Read-only (the bus owns no state, so there is no time travel). Does nothing when the extension is not installed. Has its own instance in the DevTools picker, apart from your store.
 
 Quiet by default, so you see what happened before you see how:
@@ -311,6 +384,58 @@ reduxDevtools({
 
 With two quick `search` emits and a `latest` handler, the default list is `search`, `search`. With `policies: true` it adds the `latest` stages of each call, for example `search/latest/cancel` for the first one.
 
+### Find loops with `graphLogger`
+
+Two handlers that emit each other's events never stop. `graphLogger` is a logger that finds such a loop while the app runs, writes a report once for it, and keeps the map of the events so you can draw it.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// graphLogger — the map of events and the loop finder, in one logger
+export const graph = graphLogger({ name: "app" });
+
+// createTracer — sends every task of the bus to the logger
+const trace = createTracer(graph);
+
+// tracePlugin — also reports each emit; the logger works without it, with a coarser map
+export const bus = createBus({ trace }).use(tracePlugin());
+
+// graph.cycles() lists the loops found; graph.toMermaid() draws the map
+```
+
+It reports a node that is in one chain three times, a storm of emits from outside any handler, and a chain that starts too many tasks. It writes to `console.warn`, or to `onCycle`, or to Redux DevTools with `devtools: true`. Nothing is stopped: to cut a loop use [`loopGuardPlugin`](loop-guard.md). The full walk-through, with scenarios you can run, is [Find and cut event loops](debugging-loops.md).
+
+### Send safe data to a tool
+
+A payload or an error can be anything: a class instance, a `Map`, a circular object, a function, an `Error` with a `cause`. A tool that gets such a value as it is can fail or show nothing. The built-in loggers make sure that what leaves your process is plain data:
+
+| Logger | What it does with a payload and an error |
+| ------ | ---------------------------------------- |
+| `reduxDevtools()` | Makes both plain data with `safeSerialize` before the extension gets them. An `Error` is sent as its message. `serialize` changes this. |
+| `performanceLogger()` | Sends ids and the phase; an error is text. A payload is not sent. |
+| `consoleLogger()` | Passes the value to `console`, which prints any value and keeps it open for you to inspect. |
+| `createTraceRecorder()` | Keeps the events as they are. `recorder.toJSON()` and `JSON.stringify(recorder)` give plain data. |
+| `graphLogger()` | Exports no payload unless you ask, and then makes it plain. |
+
+`safeSerialize(value)` is exported for your own logger. It never throws and never loops: an `Error` keeps its name, message, stack and cause, a cycle becomes `"[Circular]"`, a `Map` becomes `{ $map }`, a `Set` becomes `{ $set }`, an instance of a class keeps its own fields and its name as `$class`, and a getter is never called. A value that is too deep or too big is cut.
+
+```js
+import { createTracer, reduxDevtools, safeSerialize } from "nanoeffects/trace";
+
+const trace = createTracer(
+  reduxDevtools({
+    name: "app",
+    // serialize — runs on every payload and error before the extension gets it;
+    // hide a secret first, then make the rest plain
+    serialize: (value) => safeSerialize(value, { maxDepth: 4 }),
+  }),
+);
+```
+
+`serialize: false` sends values as they are, which is faster and can fail on a circular one.
+
 ### Write your own logger
 
 ```ts

package/docs/typescript.md

@@ -1,5 +1,7 @@
 # Use nanoeffects in a TypeScript app with many files
 
+> **Level D.** Read first: [Guide](guide.md#10-add-types-when-you-want-checking-optional).
+
 Read this page if your app is in TypeScript and the handlers and modules live in different files. It shows how to write an action with a handler so that TypeScript infers its payload and result, and what to add when the handlers need the fields of your bus (`ctx.store`, the effects of `effectsPlugin`). For one file or for JavaScript you do not need it.
 
 ## Write an action with its handler
@@ -23,7 +25,7 @@ export const getUser = createAction(
   },
 );
 
-// createModule: m.use binds the handler the command carries, while the module is mounted
+// createModule: m.use binds the handler the action carries, while the module is mounted
 export const userModule = createModule("user", (m) => {
   m.use(getUser);
 });

package/docs/vue.md

@@ -1,5 +1,7 @@
 # Use nanoeffects in a Vue app
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 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.
@@ -92,5 +94,5 @@ In TypeScript the type of the `ref` comes from the event: with `createAction<str
 ## 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.
+- A policy in a component (a debounced save): in `<script setup>` make it once with [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus); Vue runs the setup once, so it needs no hook.
 - Keep values in Pinia: [Connect Redux, Zustand, MobX, or Pinia](stores.md).