nanoeffects 0.31.2 → 0.33.0

package/docs/ru/testing.md

@@ -0,0 +1,92 @@
+# Тесты времени диаграммами
+
+> **[Уровень B](README.md#виды-проектов)**: SPA с async UI. Сначала прочитайте: [Политики](policies.md).
+
+Тест `latest`, `debounce`, `queue`, `retry` или `timeout` — это тест времени. С поддельными таймерами время прячется в числах (`advanceTimersByTime(30)`), а список вызовов вы проверяете вручную. Эта страница показывает, как записать расписание и ожидание двумя короткими диаграммами, как это делают marble-тесты RxJS.
+
+Нужен тест-раннер с поддельными таймерами (Vitest или Jest). Сам хелпер его не импортирует.
+
+## Тест политики диаграммой
+
+**Проблема.** Нужен тест, который говорит: второй поиск отменяет первый, и завершается только второй.
+
+**Когда.** Политика или эффект решает, что и когда выполняется, и ответ зависит от времени между событиями.
+
+1. Создайте шину через `createMarbleBus`. Она записывает трассировку своих задач и даёт `run`.
+2. Зарегистрируйте обработчик на `marbles.bus`, как в приложении.
+3. Вызовите `run` с диаграммой отправок. Один символ — один кадр (по умолчанию 10 мс).
+4. Вызовите `expect` с диаграммой фаз, которую ждёте.
+
+```js
+// search.test.js
+import { it, vi } from "vitest";
+import { latest } from "nanoeffects/policies";
+import { createMarbleBus, fakeTimersClock } from "nanoeffects/testing";
+
+// поиск, который занимает 50 мс
+function search(query) {
+  return new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+it("latest cancels the search that is running", async () => {
+  vi.useFakeTimers();
+
+  // createMarbleBus: шина, которая записывает трассировку, и run, который двигает время по кадрам
+  const marbles = createMarbleBus({ clock: fakeTimersClock(vi) });
+
+  // latest: новый поиск отменяет выполняющийся
+  marbles.bus.on("search/changed", latest(search), { traceId: "search" });
+
+  // "a-b": отправить "x" в кадре 0 и "xy" в кадре 2
+  const result = await marbles.run({
+    emits: { "search/changed": { marble: "a-b", values: { a: "x", b: "xy" } } },
+    frames: 12,
+  });
+
+  // s старт, c отмена, d готово: в кадре 2 второй поиск отменяет первый, и завершается в кадре 7
+  result.expect({ "search/changed:latest": "s-(cs)----d----" });
+});
+```
+
+Когда строка не совпала, `expect` бросает ошибку с двумя диаграммами одна под другой:
+
+```
+marble row "search/changed:latest" differs
+  expected  s-(cs)----d----
+  received  s-(cs)---d-----
+```
+
+Такой же тест для `queue` и `debounce` лежит в [`examples/testing`](../../examples/testing). Запустите его командой `pnpm vitest run examples/testing`.
+
+## Чтение диаграмм
+
+В диаграмме один символ или одна группа в скобках на кадр.
+
+| Символ | В `emits` | В результате |
+| ------ | --------- | ------------ |
+| `-` | ничего не происходит | ничего не происходит |
+| буква или цифра | отправляет событие со значением `values[символ]` (без `values` — сам символ) | `s` старт, `d` готово, `e` ошибка, `c` отмена, `x` отброшено |
+| `(ab)` | две отправки в одном кадре, в таком порядке | две фазы в одном кадре, в порядке, в котором они произошли |
+
+Другие символы (`|`, пробелы) вызывают ошибку с названием диаграммы и позицией.
+
+У задачи в результате есть строка `type:effect`: `search/changed:latest` — задача политики `latest`, `search:run` — обработчик с именем `search`. Вызовите `result.rows()`, чтобы напечатать все строки, и скопируйте нужные в `expect`. В `expect` можно написать один эффект (`latest`), если он есть в одной строке. Если он есть в двух, ошибка попросит полный ключ.
+
+## Кадр и число кадров
+
+Кадр — 10 мс. Чтобы изменить его, передайте `frame` в `createMarbleBus`. Кадр события — его время, делённое на длину кадра, с округлением вниз: таймер на 100 мс, начатый в кадре 0, заканчивается в кадре 10, поэтому для него нужно `frames` не меньше 11.
+
+`frames` — число кадров для запуска. Без него хелпер выполняет столько, сколько в самой длинной диаграмме `emits`. Работа, которая дольше диаграммы, обрезается, поэтому задавайте `frames`, когда обработчик занимает время.
+
+## Другие часы
+
+`fakeTimersClock(vi)` двигает поддельные таймеры и читает `Date.now()`. Тест включает поддельные таймеры сам (`vi.useFakeTimers()`) и оставляет `Date` поддельным, как по умолчанию. Jest работает так же: `fakeTimersClock(jest)`.
+
+Часами служит любой объект с `advance(ms)` и `now()`. `advance` может вернуть промис.
+
+## Чего нет
+
+- **Нужен трассировщик.** Хелпер читает трассировку шины, поэтому у `nanoeffects/testing` нет сборки `notrace`.
+- **Одна строка на все вызовы.** Два вызова одного обработчика делят строку, поэтому `(sd)` показывает порядок фаз, а не то, к какому вызову они относятся.
+- **Нет данных в диаграммах.** Диаграмма показывает, когда, а не что. Значения проверяйте тест-раннером как обычно.
+- **Не алфавит RxJS.** Нет горячих и холодных источников и нет `|` для конца потока.

package/docs/ru/tracing.md

@@ -13,15 +13,20 @@
 - [Какая подписка начала цепочку](#какая-подписка-начала-цепочку)
 - [Один поток через traceGroupId](#один-поток-через-tracegroupid)
 - [Имя обработчика](#имя-обработчика)
+- [Список подписчиков события](#список-подписчиков-события)
+- [Строка кода обработчика](#строка-кода-обработчика)
 - [Сохранение цепочки: `ctx.emit` вместо `bus.emit`](#сохранение-цепочки-ctxemit-вместо-busemit)
 - [Отключение имён](#отключение-имён)
 - [Встроенные логгеры](#встроенные-логгеры)
   - [Сокращение объёма в production](#сокращение-объёма-в-production)
   - [Последние события на случай инцидента](#последние-события-на-случай-инцидента)
+  - [Время и незавершённые задачи](#время-и-незавершённые-задачи)
+  - [Поиск причины ошибки](#поиск-причины-ошибки)
   - [Настройка Redux DevTools](#настройка-redux-devtools)
   - [Поиск циклов через `graphLogger`](#поиск-циклов-через-graphlogger)
   - [Безопасные данные для инструмента](#безопасные-данные-для-инструмента)
   - [Собственный логгер](#собственный-логгер)
+  - [Остановка на событии](#остановка-на-событии)
 - [Удаление трассировки из сборки](#удаление-трассировки-из-сборки)
 
 ## Подключение трассировщика
@@ -186,7 +191,7 @@ const pay = createAction("checkout/pay", async () => {}, {
 
 **Когда.** У события больше одного обработчика, и вы читаете трассировку, чтобы увидеть, кто сделал работу.
 
-Дайте обработчику `traceId` при регистрации. Плагин делает каждый его вызов задачей с этим именем, а то, что он отправляет через `ctx.emit`, становится дочерним. `off` работает как раньше. Это работает и в модуле (`m.on(event, handler, { traceId })`), и на экземпляре, созданном через `extendBus`.
+Обработчик получает имя своей функции, если регистрируете именованную функцию (`function saveName() {}`), поэтому лог приложения, которое никто не размечал, уже читается. Стрелка без имени остаётся как есть. Чтобы выбрать имя или назвать стрелку, дайте обработчику `traceId` при регистрации: он главнее имени функции. Плагин делает каждый вызов именованного обработчика задачей с этим именем, а то, что он отправляет через `ctx.emit`, становится дочерним. Минификатор может сократить имена функций в production-сборке: используйте `traceId`, где имя должно быть стабильным, и для обработчика, который возвращает политика (`latest(fn)`): у него нет собственного имени. `off` работает как раньше. Это работает и в модуле (`m.on(event, handler, { traceId })`), и на экземпляре, созданном через `extendBus`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -209,6 +214,88 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 [nanoeffects] saveNotifier · run done
 ```
 
+## Список подписчиков события
+
+**Проблема.** Чтобы узнать, что запустит emit, приходится искать в коде каждый `bus.on` этого события.
+
+**Когда.** Вы читаете чужое приложение или тест должен охранять подключения шины.
+
+`describeBus(bus)` возвращает обработчики каждого события на данный момент: по именам и в порядке добавления. Имя — это `traceId`, иначе имя функции, иначе `"<anonymous>"`. Функция читает то, что хранит `tracePlugin`, поэтому на шине без плагина или без трассировщика, а также в сборке `notrace` она возвращает `{}`. Она ничего не запускает и не меняет шину.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, describeBus, tracePlugin } from "nanoeffects/trace";
+
+function saveName(name) {
+  console.log("save", name);
+}
+
+function audit(name) {
+  console.log("audit", name);
+}
+
+const trace = createTracer(consoleLogger());
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
+
+bus.on("name/changed", saveName);
+bus.on("name/changed", audit);
+bus.on("saved", () => {}, { traceId: "refreshView" });
+
+// describeBus: карта событий и имён обработчиков
+console.log(describeBus(bus));
+```
+
+```
+{ "name/changed": ["saveName", "audit"], saved: ["refreshView"] }
+```
+
+## Строка кода обработчика
+
+**Проблема.** Лог говорит, что выполнился `saveNotifier`, и приходится искать в коде `bus.on`, который его зарегистрировал. У стрелки без имени нет имени вообще, поэтому её нет и в логе.
+
+**Когда.** Вы отлаживаете в разработке и хотите перейти от строки лога к коду.
+
+Передайте `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";
+import { consoleLogger, createTracer, describeBus, tracePlugin } from "nanoeffects/trace";
+
+// source: печатать, где зарегистрирован обработчик
+const trace = createTracer(consoleLogger({ source: true }));
+
+// source: читать место каждого bus.on один раз, при регистрации
+const bus = createBus({ trace })
+  .use(tracePlugin({ source: true }));
+
+function saveName(name) {
+  console.log("save", name);
+}
+
+bus.on("name/changed", saveName);
+bus.on("name/changed", (name) => console.log("audit", name));
+
+bus.emit("name/changed", "Eva");
+
+// describeBus: те же места, ничего не запуская
+console.log(describeBus(bus, { source: true }));
+```
+
+```
+[nanoeffects] saveName · run start (file:///app/src/user.js:13: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)"] }
+```
+
+Ограничения:
+
+- **Минифицированный или собранный код** даёт строку сборки. Включите source maps (`node --enable-source-maps` или source maps браузера), чтобы увидеть исходную строку.
+- **`ctx.on`, вызванный вручную** внутри обработчика, показывает строку в библиотеке. `on` модуля и экземпляра, созданного через `extendBus`, а также `on` у `matchPlugin`, `signalPlugin` и `devPlugin` показывают вашу строку при любом порядке плагинов и в бандле.
+- **Нет стека**, например при `Error.stackTraceLimit = 0`: `source` не ставится, обработчик работает как обычно.
+- **По умолчанию выключено.** Чтение стека стоит немного на каждую регистрацию, поэтому включайте его в разработке.
+
 ## Сохранение цепочки: `ctx.emit` вместо `bus.emit`
 
 Внутри обработчика отправляйте через `ctx.emit`. Он сохраняет цепочку: запущенные им задачи становятся дочерними для обработчика, а у его событий есть `rootId` цепочки. Обычный `bus.emit` внутри обработчика запускает новый корень без `parentId` и без `rootId`, так что трассировка теряет связь. Шина не может об этом предупредить, потому что не знает, какой обработчик сейчас выполняется.
@@ -250,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
@@ -311,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 -->
@@ -448,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/testing.md

@@ -0,0 +1,92 @@
+# Test time with diagrams
+
+> **Level B.** Read first: [Policies](policies.md).
+
+A test of `latest`, `debounce`, `queue`, `retry` or `timeout` is a test of time. With fake timers the time hides in numbers (`advanceTimersByTime(30)`), and you check a list of calls by hand. This page shows how to write the schedule and the expectation as two short diagrams, as RxJS marble tests do.
+
+You need a test runner with fake timers (Vitest or Jest). The helper does not import one.
+
+## Test a policy with a diagram
+
+**Problem.** You want a test that says: a second search cancels the first one, and only the second finishes.
+
+**When.** A policy or an effect decides what runs when, and the answer depends on the time between events.
+
+1. Create a bus with `createMarbleBus`. It records the trace of its tasks and gives you `run`.
+2. Register the handler on `marbles.bus`, as you do in your app.
+3. Call `run` with a diagram of the emits. One character is one frame (10 ms by default).
+4. Call `expect` with a diagram of the phases that you expect.
+
+```js
+// search.test.js
+import { it, vi } from "vitest";
+import { latest } from "nanoeffects/policies";
+import { createMarbleBus, fakeTimersClock } from "nanoeffects/testing";
+
+// a search that takes 50 ms
+function search(query) {
+  return new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+it("latest cancels the search that is running", async () => {
+  vi.useFakeTimers();
+
+  // createMarbleBus: a bus that records its trace, and a run that moves time frame by frame
+  const marbles = createMarbleBus({ clock: fakeTimersClock(vi) });
+
+  // latest: a new search cancels the one that is running
+  marbles.bus.on("search/changed", latest(search), { traceId: "search" });
+
+  // "a-b": emit "x" at frame 0 and "xy" at frame 2
+  const result = await marbles.run({
+    emits: { "search/changed": { marble: "a-b", values: { a: "x", b: "xy" } } },
+    frames: 12,
+  });
+
+  // s start, c cancel, d done: at frame 2 the second search cancels the first, and it is done at frame 7
+  result.expect({ "search/changed:latest": "s-(cs)----d----" });
+});
+```
+
+When a row differs, `expect` throws an error with both diagrams one under the other:
+
+```
+marble row "search/changed:latest" differs
+  expected  s-(cs)----d----
+  received  s-(cs)---d-----
+```
+
+The same test for `queue` and `debounce` is in [`examples/testing`](../examples/testing). Run it with `pnpm vitest run examples/testing`.
+
+## Read the diagrams
+
+A diagram has one character, or one group in parentheses, for each frame.
+
+| Character | In `emits` | In the result |
+| --------- | ---------- | ------------- |
+| `-` | nothing happens | nothing happens |
+| a letter or digit | emits the event with `values[character]` (the character itself without `values`) | `s` start, `d` done, `e` error, `c` cancel, `x` drop |
+| `(ab)` | two emits in one frame, in this order | two phases in one frame, in the order they happened |
+
+Other characters (`|`, spaces) throw an error that names the diagram and the position.
+
+A task has a row in the result named `type:effect`: `search/changed:latest` is the task of the `latest` policy, `search:run` is the listener named `search`. Call `result.rows()` to print every row, then copy the ones you want into `expect`. In `expect` you can write the effect alone (`latest`) when one row has it. If two rows have it, the error asks for the full key.
+
+## Set the frame and the number of frames
+
+A frame is 10 ms. Pass `frame` to `createMarbleBus` to change it. The frame of an event is its time divided by the frame, rounded down: a timer of 100 ms that starts at frame 0 ends in frame 10, so `frames` must be 11 or more to show it.
+
+`frames` is the number of frames to run. Without it the helper runs as many as the longest `emits` diagram has. Work that outlives the diagram is cut, so set `frames` when a handler takes time.
+
+## Use another clock
+
+`fakeTimersClock(vi)` moves fake timers and reads `Date.now()`. A test turns fake timers on itself (`vi.useFakeTimers()`) and leaves `Date` faked, which is the default. Jest works the same way: `fakeTimersClock(jest)`.
+
+Any object with `advance(ms)` and `now()` is a clock. `advance` may return a promise.
+
+## Know what is not there
+
+- **It needs a tracer.** The helper reads the trace of the bus, so there is no `notrace` build of `nanoeffects/testing`.
+- **One row for all calls.** Two calls of one listener share a row, so `(sd)` shows the order in which phases happened, not which call they belong to.
+- **No payloads in diagrams.** The diagram shows when, not what. Check the values with your test runner as usual.
+- **Not the RxJS alphabet.** There are no hot or cold sources and no `|` for the end of a stream.