nanoeffects 0.32.0 → 0.33.0

package/docs/ru/debugging-loops.md

@@ -16,6 +16,7 @@
 - [Обрыв цикла во время работы](#обрыв-цикла-во-время-работы)
 - [Падение теста при цикле](#падение-теста-при-цикле)
 - [Экспорт графа и payload](#экспорт-графа-и-payload)
+- [Подписки, которые не запускались](#подписки-которые-не-запускались)
 - [Как находится цикл](#как-находится-цикл)
 - [Ограничения](#ограничения)
 
@@ -278,6 +279,84 @@ console.log(JSON.stringify(data));
 
 Payload может быть экземпляром класса, `Map`, объектом с циклической ссылкой или `Error`, которые обычный `JSON.stringify` не примет. Экспорт превращает их в обычный JSON: у `Error` остаются имя, сообщение, стек и причина, цикл становится `"[Circular]"`, `Map` — `{ "$map": [...] }`, а экземпляр класса сохраняет собственные поля и имя класса в `$class`. Геттеры не вызываются, а слишком глубокое или слишком большое значение обрезается.
 
+## Подписки, которые не запускались
+
+Граф одного запуска показывает только то, что сделал этот запуск. Он не скажет, какие подписки есть в приложении, но ни один запуск до них не дошёл: мёртвый код или сценарий, который никто не тестирует. Чтобы их найти, объедините графы нескольких запусков и сравните результат с подписками шины.
+
+Что нужно заранее: шина использует `tracePlugin` и `graphLogger` (см. [Поиск цикла](#поиск-цикла)), а у каждой подписки есть имя функции или `traceId`. У анонимной подписки нет узла в графе, поэтому о ней не сообщается.
+
+1. Каждый запуск пишет свой граф в файл.
+2. Скрипт читает файлы и объединяет их через `mergeGraphs`.
+3. `findOrphans` сравнивает объединённый граф с `describeBus`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// graphLogger — карта того, что выполнилось
+export const graph = graphLogger({ name: "cart" });
+export const bus = createBus({ trace: createTracer(graph) }).use(tracePlugin());
+```
+
+```js
+// handlers.js
+import { bus } from "./bus";
+
+// подписка названа по функции; findOrphans сопоставляет это имя
+bus.on("cart/added", function recalcTotal() {});
+bus.on("cart/cleared", function resetTotal() {});
+```
+
+```js
+// graph-setup.js (setup-файл вашего тест-раннера)
+import { mkdirSync, writeFileSync } from "node:fs";
+import { afterAll } from "vitest";
+import { graph } from "./bus";
+
+afterAll(() => {
+  mkdirSync("graphs", { recursive: true });
+
+  // toJSON — граф этого запуска как обычные данные
+  const data = graph.toJSON();
+  writeFileSync(`graphs/${process.pid}.json`, JSON.stringify(data));
+});
+```
+
+```js
+// orphans.js (запустите после тестов)
+import { readdirSync, readFileSync } from "node:fs";
+import { describeBus, findOrphans, mergeGraphs } from "nanoeffects/trace";
+import { bus } from "./bus";
+import "./handlers";
+
+const files = readdirSync("graphs");
+const runs = files.map((file) => JSON.parse(readFileSync(`graphs/${file}`, "utf8")));
+
+// mergeGraphs — счётчики складываются, поэтому подписка, выполнявшаяся в любом запуске, становится узлом
+const all = mergeGraphs(...runs);
+
+// describeBus — подписки, которые держит шина, по событиям
+const described = describeBus(bus);
+
+// findOrphans — подписки, которые объединённый граф ни разу не видел
+console.log(findOrphans(described, all));
+// [{ event: "cart/cleared", listener: "resetTotal", kind: "unemitted" }]
+```
+
+У каждого элемента есть `kind`:
+
+| `kind` | Что значит | Что проверить |
+| ------ | ---------- | ------------- |
+| `unemitted` | Ни в одном запуске никто не отправил это событие. | Нужно ли ещё событие? Не хватает ли сценария? |
+| `unrun` | Событие отправлялось, а эта подписка не запускалась. | Условие или [политика](policies.md), из-за которых она не запускается. |
+
+Читайте список как подсказку, а не как ошибку. При малом числе запусков в нём много ложных записей, и сигналом он становится, когда запуски покрывают основные сценарии. Ограничения:
+
+- Две подписки с одним именем дают один узел, поэтому вторая никогда не попадёт в список. Дайте каждой своё имя или `traceId`.
+- Объединяйте запуски одной сборки. Переименованная подписка попадёт в список.
+- `mergeGraphs` не находит цикл, который замыкается только при объединении рёбер разных запусков. Смотрите `graph.cycles()` в каждом запуске.
+
 ## Как находится цикл
 
 `graphLogger` находит циклы двумя способами. Они дают два вида находок в `graph.cycles()`, которые различает поле `source`:

package/docs/ru/package.md

@@ -26,7 +26,7 @@
 | `nanoeffects/svelte` | `sveltePlugin`: добавляет `eventStore` на шину (нужен Svelte 5 или новее) | компоненты Svelte |
 | `nanoeffects/vue` | `vuePlugin`: добавляет `watchEmitter` и `useEventRef` на шину (нужен Vue 3.3 или новее) | компоненты Vue |
 | `nanoeffects/dev` | `devPlugin` (в production ничего не делает), `getLostSignalsCount` и `getLostSignals` для тестов | нужно находить утечки подписок и потерянные сигналы при разработке и в тестах |
-| `nanoeffects/trace` | `createTracer`, логгеры (`graphLogger` находит циклы событий) и `tracePlugin` (имена для трассировки) | нужно видеть, что выполнилось и почему |
+| `nanoeffects/trace` | `createTracer`, логгеры (`graphLogger` находит циклы событий; `mergeGraphs` и `findOrphans` находят подписки, до которых не дошёл ни один запуск) и `tracePlugin` (имена для трассировки) | нужно видеть, что выполнилось и почему |
 | `nanoeffects/testing` | `createMarbleBus`, `fakeTimersClock`: шина для тестов, где отправки и фазы записаны диаграммами | вы тестируете `latest`, `debounce`, `queue`, `retry` или `timeout` на поддельных таймерах |
 | `nanoeffects/guard` | `loopGuardPlugin`: отклоняет emit, который превысил бы предел цепочки | цикл не должен ронять приложение |
 

package/docs/ru/tracing.md

@@ -20,10 +20,13 @@
 - [Встроенные логгеры](#встроенные-логгеры)
   - [Сокращение объёма в production](#сокращение-объёма-в-production)
   - [Последние события на случай инцидента](#последние-события-на-случай-инцидента)
+  - [Время и незавершённые задачи](#время-и-незавершённые-задачи)
+  - [Поиск причины ошибки](#поиск-причины-ошибки)
   - [Настройка Redux DevTools](#настройка-redux-devtools)
   - [Поиск циклов через `graphLogger`](#поиск-циклов-через-graphlogger)
   - [Безопасные данные для инструмента](#безопасные-данные-для-инструмента)
   - [Собственный логгер](#собственный-логгер)
+  - [Остановка на событии](#остановка-на-событии)
 - [Удаление трассировки из сборки](#удаление-трассировки-из-сборки)
 
 ## Подключение трассировщика
@@ -254,7 +257,7 @@ console.log(describeBus(bus));
 
 **Когда.** Вы отлаживаете в разработке и хотите перейти от строки лога к коду.
 
-Передайте `source: true` в `tracePlugin`. Он читает место каждого вызова `bus.on` и `bus.once` один раз, при регистрации, и никогда при `emit`. События обработчика получают `source` (`file:line:column`), `consoleLogger({ source: true })` печатает его, а `describeBus(bus, { source: true })` его перечисляет. Обработчик без имени тоже попадает в трассировку, под типом своего события.
+Передайте `source: true` в `tracePlugin`. Он читает место каждого вызова `bus.on` и `bus.once` один раз, при регистрации, и никогда при `emit`. События обработчика получают `source` (`file:line:column`), `consoleLogger({ source: true })` печатает его, а `describeBus(bus, { source: true })` его перечисляет. Обработчик без имени тоже попадает в трассировку, под типом своего события и номером: `name/changed#1`, `name/changed#2`, в порядке регистрации. Два встроенных обработчика одного события — это две записи, а место остаётся в `source`. Добавление или перестановка вызовов `bus.on` меняет номера, поэтому дайте `traceId` обработчику, чьё имя должно остаться прежним между сборками.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -282,7 +285,7 @@ console.log(describeBus(bus, { source: true }));
 
 ```
 [nanoeffects] saveName · run start (file:///app/src/user.js:13:5)
-[nanoeffects] name/changed · run start (file:///app/src/user.js:14:5)
+[nanoeffects] name/changed#1 · run start (file:///app/src/user.js:14:5)
 { "name/changed": ["saveName (file:///app/src/user.js:13:5)", "<anonymous> (file:///app/src/user.js:14:5)"] }
 ```
 
@@ -334,7 +337,7 @@ const bus = createBus({
 | `reduxDevtools()` | Отправляет emit в Redux DevTools, а с `policies` — стадии обработчиков как `type/effect/phase`; state — `{ running }` |
 | `consoleLogger()` | Печатает по одной строке на фазу, с отступом по глубине задачи |
 | `performanceLogger()` | Измерения User Timing для панели Performance браузера |
-| `graphLogger()` | Строит карту того, какое событие к какому ведёт, находит циклы во время работы приложения и записывает карту как Mermaid, Graphviz или JSON ([см. ниже](#поиск-циклов-через-graphlogger)) |
+| `graphLogger()` | Строит карту того, какое событие к какому ведёт, находит циклы во время работы приложения и записывает карту как Mermaid, Graphviz или JSON ([см. ниже](#поиск-циклов-через-graphlogger)); [`mergeGraphs` и `findOrphans`](debugging-loops.md#подписки-которые-не-запускались) объединяют запуски и находят подписки, которые не запускались |
 | `createTraceRecorder()` | Хранит события в `recorder.events`: все — для тестов, либо с `{ capacity }` последние N ([см. ниже](#последние-события-на-случай-инцидента)) |
 
 ### Сокращение объёма в production
@@ -395,12 +398,91 @@ window.addEventListener("error", () => {
 Что нужно знать, прежде чем отправлять события:
 
 - **`payload` и `error` могут содержать приватные данные**: то, что ввёл пользователь, токены, личный текст. Рекордер хранит их как есть и не вычищает. Выбирайте, что отправлять, как это делает `withoutPayload`.
-- **У события нет времени.** Вы получаете порядок, а не длительность. Чтобы добавить время, оберните рекордер в логгер, который проставляет `performance.now()` на копии события.
+- **У события нет времени.** Вы получаете порядок, а не длительность. Время считает [`timingLogger`](#время-и-незавершённые-задачи).
 - **Старый `parentId` может указывать на событие, которое вытеснено.** Когда вы строите дерево из событий, считайте неизвестный `parentId` корнем.
 - **`recorder.events` с `capacity` — снимок.** Каждое чтение строит новый массив, поэтому читайте его один раз в нужный момент. Без `capacity` это один живой массив.
 - **Низкий `sample` разрежает буфер.** `createTracer(recorder, { sample: 0.05 })` записывает 5% корневых задач, поэтому к моменту инцидента в буфере может быть мало. См. [Сокращение объёма в production](#сокращение-объёма-в-production).
 - **`capacity`, не являющийся положительным целым** (`0`, отрицательное число, `NaN`), означает «без ограничения».
 
+### Время и незавершённые задачи
+
+У события нет времени, и по рекордеру нельзя узнать, какой обработчик медленный, сколько жил запрос до `cancel` и осталось ли что-то после размонтирования. `timingLogger` проставляет время на каждое событие при получении и связывает `start` с первой завершающей фазой (`done`, `error`, `cancel` или `drop`) той же задачи.
+
+Подайте его в трассировщик вместе с рекордером: `createTracer` принимает массив логгеров.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer, timingLogger } from "nanoeffects/trace";
+
+// createTraceRecorder: события в порядке прихода
+export const recorder = createTraceRecorder();
+
+// timingLogger: время каждого события и длительность задач
+export const timing = timingLogger();
+
+// createTracer: каждое событие получают оба логгера
+const trace = createTracer([recorder, timing]);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// check.js
+import { timing } from "./bus";
+
+// durations: задачи, которые завершились, с фазой конца и длительностью в мс
+const slow = timing.durations.filter((task) => task.ms > 500);
+console.log(slow);
+
+// pending: задачи, которые начались и не закончились
+const leftovers = timing.pending();
+if (leftovers.length > 0) {
+  throw new Error(`${leftovers.length} tasks are still open`);
+}
+```
+
+Что нужно знать:
+
+- **Часы.** Время берётся из `performance.now()`, а где его нет, из `Date.now()`. В тесте передайте свои часы: `timingLogger({ now })`.
+- **`capacity` режет только `durations`.** `timingLogger({ capacity: 200 })` хранит последние 200 завершённых задач. `pending()` не обрезается: утечка видна как растущий список.
+- **`clear()`** очищает оба списка. Вызывайте его между тестами.
+- **Логгер видит то, что пропустил трассировщик.** Задача, чей `start` отфильтрован или не попал в `sample`, не получит пару, и её завершение игнорируется.
+
+### Поиск причины ошибки
+
+Ошибка приходит одним событием, и не видно, что к ней привело. `chainOf` строит путь от корня до задачи по `parentId`. Передайте ему рекордер: тогда в путь попадут и подписчики, которые не шлют событий (обычный обработчик, который вызывает `ctx.emit`).
+
+```js
+// why.js
+import { chainOf } from "nanoeffects/trace";
+import { recorder } from "./bus";
+
+const failed = recorder.events.find((event) => event.phase === "error");
+
+// chainOf: путь от корня до упавшей задачи
+const path = chainOf(recorder, failed.id);
+
+const text = path.map((step) => step.type).join(" → ");
+console.log(text); // queryChanged → searchLoaded
+```
+
+У шага есть `type`, а также `effect` и `phase` (у подписчика без событий их нет), `source` и `traceGroupId`, когда они известны. Если передать вместо рекордера массив событий (снимок или файл), в пути будут только задачи с событиями.
+
+Чтобы видеть путь сразу в консоли, включите `chain` в `consoleLogger`:
+
+```js
+import { consoleLogger, createTracer } from "nanoeffects/trace";
+
+// consoleLogger: строка ошибки заканчивается путём от корня
+const trace = createTracer(consoleLogger({ chain: true }));
+// [nanoeffects] render · run error (queryChanged → render)
+```
+
+`chain` помнит последние 1000 задач. По умолчанию он выключен.
+
 ### Настройка Redux DevTools
 
 <!-- docs-check: new -->
@@ -532,6 +614,26 @@ const errorsOnly = (): TraceLogger => (event) => {
 };
 ```
 
+### Остановка на событии
+
+Нужно остановиться в отладчике, когда приходит определённое событие. Для этого не нужен API: это пять строк в собственном логгере.
+
+```js
+import { createTracer } from "nanoeffects/trace";
+
+// Логгер: останавливается в отладчике на начале задачи с этим type
+const stopOn = (type) => (event) => {
+  if (event.type === type && event.phase === "start") {
+    debugger; // браузер остановится здесь, если открыты DevTools
+  }
+};
+
+// createTracer: подайте логгер, как любой другой
+const trace = createTracer(stopOn("search"));
+```
+
+В отладчике посмотрите `event.payload` и поднимитесь по стеку: синхронная часть цепочки видна в нём целиком.
+
 ## Удаление трассировки из сборки
 
 Без трассировщика хуки почти ничего не стоят. `nanoeffects/trace` попадает в бандл, только если его импортируют.

package/docs/tracing.md

@@ -20,10 +20,13 @@ Tracing is optional. A bus works the same without it, and it costs almost nothin
 - [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)
+  - [Measure time and find open tasks](#measure-time-and-find-open-tasks)
+  - [Find the cause of an error](#find-the-cause-of-an-error)
   - [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)
+  - [Stop on an event](#stop-on-an-event)
 - [Drop tracing from a build](#drop-tracing-from-a-build)
 
 ## Attach a tracer
@@ -254,7 +257,7 @@ console.log(describeBus(bus));
 
 **When.** You debug in development and want to jump from a log line to the code.
 
-Pass `source: true` to `tracePlugin`. It reads the place of each `bus.on` and `bus.once` call once, when the listener is registered, and never on `emit`. The events of the listener get a `source` (`file:line:column`), `consoleLogger({ source: true })` prints it, and `describeBus(bus, { source: true })` lists it. An anonymous listener is reported too, under the type of its event.
+Pass `source: true` to `tracePlugin`. It reads the place of each `bus.on` and `bus.once` call once, when the listener is registered, and never on `emit`. The events of the listener get a `source` (`file:line:column`), `consoleLogger({ source: true })` prints it, and `describeBus(bus, { source: true })` lists it. An anonymous listener is reported too, under the type of its event and a number: `name/changed#1`, `name/changed#2`, in the order of registration. Two inline listeners on one event are two entries, and the place stays in `source`. Adding or reordering `bus.on` calls renumbers them, so give a `traceId` to a listener whose name must stay the same between builds.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -282,7 +285,7 @@ console.log(describeBus(bus, { source: true }));
 
 ```
 [nanoeffects] saveName · run start (file:///app/src/user.js:13:5)
-[nanoeffects] name/changed · run start (file:///app/src/user.js:14:5)
+[nanoeffects] name/changed#1 · run start (file:///app/src/user.js:14:5)
 { "name/changed": ["saveName (file:///app/src/user.js:13:5)", "<anonymous> (file:///app/src/user.js:14:5)"] }
 ```
 
@@ -335,7 +338,7 @@ const bus = createBus({
 | `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`: 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)) |
+| `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)); [`mergeGraphs` and `findOrphans`](debugging-loops.md#find-listeners-that-never-ran) join runs and find listeners that never ran |
 
 ### Cut volume in production
 
@@ -395,12 +398,91 @@ window.addEventListener("error", () => {
 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.
+- **There is no time on an event.** You get the order, not the duration. [`timingLogger`](#measure-time-and-find-open-tasks) measures time.
 - **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.
 
+### Measure time and find open tasks
+
+An event has no time, so the recorder cannot tell you which handler is slow, how long a request lived before `cancel`, or whether a test left something running. `timingLogger` stamps the time on each event when it gets it and pairs `start` with the first closing phase (`done`, `error`, `cancel` or `drop`) of the same task.
+
+Pass it to the tracer next to the recorder: `createTracer` takes an array of loggers.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer, timingLogger } from "nanoeffects/trace";
+
+// createTraceRecorder: events in the order they came
+export const recorder = createTraceRecorder();
+
+// timingLogger: the time of each event and the duration of tasks
+export const timing = timingLogger();
+
+// createTracer: both loggers get every event
+const trace = createTracer([recorder, timing]);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// check.js
+import { timing } from "./bus";
+
+// durations: the tasks that ended, with the closing phase and the time in ms
+const slow = timing.durations.filter((task) => task.ms > 500);
+console.log(slow);
+
+// pending: the tasks that started and have not ended
+const leftovers = timing.pending();
+if (leftovers.length > 0) {
+  throw new Error(`${leftovers.length} tasks are still open`);
+}
+```
+
+What to know:
+
+- **The clock.** Time comes from `performance.now()`, or `Date.now()` where there is none. In a test pass your own clock: `timingLogger({ now })`.
+- **`capacity` cuts only `durations`.** `timingLogger({ capacity: 200 })` keeps the last 200 ended tasks. `pending()` is never cut: a leak shows up as a growing list.
+- **`clear()`** empties both lists. Call it between tests.
+- **The logger sees what the tracer lets through.** A task whose `start` was filtered out or not sampled gets no pair, and its ending is ignored.
+
+### Find the cause of an error
+
+An error arrives as one event, and you cannot see what led to it. `chainOf` builds the path from the root to a task by `parentId`. Give it the recorder: then the listeners that send no event (a plain handler that calls `ctx.emit`) are in the path too.
+
+```js
+// why.js
+import { chainOf } from "nanoeffects/trace";
+import { recorder } from "./bus";
+
+const failed = recorder.events.find((event) => event.phase === "error");
+
+// chainOf: the path from the root to the failed task
+const path = chainOf(recorder, failed.id);
+
+const text = path.map((step) => step.type).join(" → ");
+console.log(text); // queryChanged → searchLoaded
+```
+
+A step has `type`, and `effect` and `phase` (a listener with no events has neither), `source` and `traceGroupId` when known. If you pass a list of events (a snapshot, a file) instead of the recorder, the path holds only the tasks that have events.
+
+To see the path right in the console, turn on `chain` in `consoleLogger`:
+
+```js
+import { consoleLogger, createTracer } from "nanoeffects/trace";
+
+// consoleLogger: the line of an error ends with the path from the root
+const trace = createTracer(consoleLogger({ chain: true }));
+// [nanoeffects] render · run error (queryChanged → render)
+```
+
+`chain` remembers the last 1000 tasks. It is off by default.
+
 ### Configure Redux DevTools
 
 <!-- docs-check: new -->
@@ -532,6 +614,26 @@ const errorsOnly = (): TraceLogger => (event) => {
 };
 ```
 
+### Stop on an event
+
+You want the debugger to stop when a certain event comes. No API is needed for that: it is five lines in a logger of your own.
+
+```js
+import { createTracer } from "nanoeffects/trace";
+
+// A logger that stops in the debugger at the start of a task with this type
+const stopOn = (type) => (event) => {
+  if (event.type === type && event.phase === "start") {
+    debugger; // the browser stops here when DevTools is open
+  }
+};
+
+// createTracer: pass the logger like any other
+const trace = createTracer(stopOn("search"));
+```
+
+In the debugger read `event.payload` and walk up the stack: the synchronous part of the chain is all there.
+
 ## Drop tracing from a build
 
 Without a tracer the hooks cost almost nothing. `nanoeffects/trace` is only bundled when imported.