nanoeffects 0.31.2 → 0.33.0

package/docs/debugging-cases.md

@@ -0,0 +1,122 @@
+# Debugging cases
+
+> **Level F.** Read first: [Trace tasks](tracing.md#attach-a-tracer).
+
+Read this page when something goes wrong and you want to know who listens to an event, what began a chain, or why a request stopped. Each case below is a short snippet that you can run. For loops, see [Find and cut event loops](debugging-loops.md).
+
+## On this page
+
+- [Find who listens to an event](#find-who-listens-to-an-event)
+- [Find which task began a chain](#find-which-task-began-a-chain)
+- [Find out why a request stopped](#find-out-why-a-request-stopped)
+- [Know what is missing](#know-what-is-missing)
+
+## Find who listens to an event
+
+**Problem.** You read an emit and want to know what it starts.
+
+Name the listeners with functions or a `traceId`, use `tracePlugin`, and call `describeBus`:
+
+```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);
+
+// describeBus: the listeners of each event, in the order they run
+console.log(describeBus(bus));
+```
+
+```
+{ "name/changed": ["saveName", "audit"] }
+```
+
+Details: [List who listens](tracing.md#list-who-listens).
+
+## Find which task began a chain
+
+**Problem.** A request ran and you do not know what asked for it.
+
+Every task of a trace has a `rootId` and a `parentId`. The recorder keeps them, so you can walk up from the request to the emit that began it:
+
+```js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// createTraceRecorder: keeps the last events in memory
+const recorder = createTraceRecorder();
+const trace = createTracer(recorder);
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
+
+function loadUser(id, ctx) {
+  ctx.emit("user/loading", id);
+}
+
+bus.on("user/open", loadUser);
+bus.emit("user/open", 7);
+
+// each event says which task is its parent
+for (const event of recorder.events) {
+  console.log(event.id, event.parentId, event.type, event.phase);
+}
+```
+
+Details: [Show which subscription began a chain](tracing.md#show-which-subscription-began-a-chain) and [Keep the chain: `ctx.emit`, not `bus.emit`](tracing.md#keep-the-chain-ctxemit-not-busemit).
+
+## Find out why a request stopped
+
+**Problem.** A search request never finished and no error appeared.
+
+A policy that stops a call reports `cancel` or `drop` in the trace. Pick the call and read its last phase:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { createTraceRecorder, createTracer, tracePlugin } from "nanoeffects/trace";
+
+const recorder = createTraceRecorder();
+const trace = createTracer(recorder);
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
+
+// latest: a new search stops the one that is still running
+const search = latest(async (query, ctx) => {
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  ctx.emit("search/loaded", query);
+});
+
+bus.on("search/changed", search, { traceId: "search" });
+bus.emit("search/changed", "a");
+bus.emit("search/changed", "ab");
+
+// a "cancel" phase on the first call says that the second one stopped it
+const phases = recorder.events.map((event) => `${event.type}:${event.phase}`);
+console.log(phases);
+```
+
+Details: [Trace tasks](tracing.md) and [Cancel stale requests](cancel-stale-requests.md).
+
+## Know what is missing
+
+- **No browser extension or UI of its own.** Use [Redux DevTools](tracing.md#configure-redux-devtools), the console or the Performance panel.
+- **No map from the source code.** `describeBus` lists the listeners registered so far, and `graphLogger` shows the events that happened. A listener that is not registered yet is not on the map.
+- **No click-through from the log to the code.** With `tracePlugin({ source: true })` an event carries the `file:line:column` of its listener ([Find the line of a listener](tracing.md#find-the-line-of-a-listener)), but a link in a UI is yours to build.
+- **No names from a compiler.** Function names give a name for free; a minifier can shorten them, so use `traceId` where a name must stay stable.
+- **No replay and no time travel.** The recorder keeps what happened and cannot run it again.

package/docs/debugging-loops.md

@@ -16,6 +16,7 @@ A loop is two handlers that emit each other's events, or one handler that emits
 - [Cut a loop at run time](#cut-a-loop-at-run-time)
 - [Fail a test on a loop](#fail-a-test-on-a-loop)
 - [Export the graph and the payloads](#export-the-graph-and-the-payloads)
+- [Find listeners that never ran](#find-listeners-that-never-ran)
 - [Know how a loop is found](#know-how-a-loop-is-found)
 - [Know the limits](#know-the-limits)
 
@@ -278,6 +279,84 @@ console.log(JSON.stringify(data));
 
 A payload can be a class instance, a `Map`, a circular object or an `Error`, which a plain `JSON.stringify` cannot take. The exports make them plain JSON: an `Error` keeps its name, message, stack and cause, a cycle becomes `"[Circular]"`, a `Map` becomes `{ "$map": [...] }`, and an instance of a class keeps its own fields and its name as `$class`. Getters are never called, and a value that is too deep or too big is cut.
 
+## Find listeners that never ran
+
+A graph of one run shows what that run did. It cannot tell you which listeners the app has but no run ever reached: dead code, or a scenario nobody tests. To find them, join the graphs of several runs, then compare the result with the listeners the bus holds.
+
+Prerequisites: the bus uses `tracePlugin` and `graphLogger` (see [Find a loop](#find-a-loop)), and each listener has a function name or a `traceId`. An anonymous listener has no node in the graph, so it is never reported.
+
+1. Each run writes its graph to a file.
+2. A script reads the files and joins them with `mergeGraphs`.
+3. `findOrphans` compares the joined graph with `describeBus`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// graphLogger — the map of what ran
+export const graph = graphLogger({ name: "cart" });
+export const bus = createBus({ trace: createTracer(graph) }).use(tracePlugin());
+```
+
+```js
+// handlers.js
+import { bus } from "./bus";
+
+// the listener is named by its function; findOrphans matches this name
+bus.on("cart/added", function recalcTotal() {});
+bus.on("cart/cleared", function resetTotal() {});
+```
+
+```js
+// graph-setup.js (the setup file of your test runner)
+import { mkdirSync, writeFileSync } from "node:fs";
+import { afterAll } from "vitest";
+import { graph } from "./bus";
+
+afterAll(() => {
+  mkdirSync("graphs", { recursive: true });
+
+  // toJSON — the graph of this run as plain data
+  const data = graph.toJSON();
+  writeFileSync(`graphs/${process.pid}.json`, JSON.stringify(data));
+});
+```
+
+```js
+// orphans.js (run it after the tests)
+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 — counts add up, so a listener that ran in any run is a node
+const all = mergeGraphs(...runs);
+
+// describeBus — the listeners the bus holds, by event
+const described = describeBus(bus);
+
+// findOrphans — the listeners the joined graph never saw run
+console.log(findOrphans(described, all));
+// [{ event: "cart/cleared", listener: "resetTotal", kind: "unemitted" }]
+```
+
+Each item has a `kind`:
+
+| `kind` | Meaning | What to check |
+| ------ | ------- | ------------- |
+| `unemitted` | Nothing emitted the event in any run. | Is the event still used? Is a scenario missing? |
+| `unrun` | The event was emitted, this listener did not run. | A condition or a [policy](policies.md) that never lets it run. |
+
+Read the list as a hint, not as a failure. With few runs it holds many false items, and it only becomes a signal when the runs cover the main scenarios. Know the limits:
+
+- Two listeners with one name are one node, so the second one is never reported. Give each a distinct name or `traceId`.
+- Merge runs of one build. A listener that was renamed shows up as an orphan.
+- `mergeGraphs` does not find a loop that only closes when the edges of two runs are joined. Use `graph.cycles()` in each run.
+
 ## Know how a loop is found
 
 `graphLogger` finds loops in two ways. They give two kinds of finding in `graph.cycles()`, told apart by `source`:

package/docs/migrating-from-rxjs.md

@@ -194,4 +194,4 @@ The subscription is not tied to a task. Call `subscription.unsubscribe()` when t
 - **Abort replaces unsubscribe for work in flight.** A stopped task is stopped through its `signal`. Pass it to `fetch` or to the client.
 - **Errors are not part of the stream.** A failed task rejects its own promise. Without `onError` on the bus nobody else hears it ([Errors](errors.md)).
 - **No completion.** An event bus does not end. A task ends when its work ends or its signal aborts.
-- **No marble tests.** Test with the real handler and fake timers.
+- **Marble tests are a smaller tool.** [`createMarbleBus`](testing.md) writes the emits and the phases of tasks as diagrams on fake timers. It has no hot or cold sources and no `|`.

package/docs/package.md

@@ -30,7 +30,8 @@ Each row is optional. The "when" column says what need brings you to it.
 | `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) | Svelte components |
 | `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) | Vue components |
 | `nanoeffects/dev` | `devPlugin` (no-op in production), `getLostSignalsCount` and `getLostSignals` for tests | you look for leaks and lost signals in development and in tests |
-| `nanoeffects/trace` | `createTracer`, the loggers (`graphLogger` finds event loops) and `tracePlugin` (names for the trace) | you want to see what ran and why |
+| `nanoeffects/trace` | `createTracer`, the loggers (`graphLogger` finds event loops; `mergeGraphs` and `findOrphans` find listeners no run reached) and `tracePlugin` (names for the trace) | you want to see what ran and why |
+| `nanoeffects/testing` | `createMarbleBus`, `fakeTimersClock`: a bus for tests, with emits and phases as diagrams | you test `latest`, `debounce`, `queue`, `retry` or `timeout` with fake timers |
 | `nanoeffects/guard` | `loopGuardPlugin`: refuses the emit that would pass a limit of a chain | a loop must not take the app down |
 
 The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists all of them, what each returns, and the order to use them in.

package/docs/recipes.md

@@ -29,6 +29,7 @@ Each task below starts with the problem, then a short solution. Where the page h
   - [Do not leave subscriptions after a widget closes](#do-not-leave-subscriptions-after-a-widget-closes)
 - [Stop work on a server](#stop-work-on-a-server)
 - [Debugging: what ran and why](#debugging-what-ran-and-why)
+- [Test a policy with fake timers](#test-a-policy-with-fake-timers)
 - [Other libraries in the project](#other-libraries-in-the-project)
 - [Classes and TypeScript](#classes-and-typescript)
   - [Use the bus in a class](#use-the-bus-in-a-class)
@@ -480,6 +481,40 @@ bus.emit("search", "nano"); // the log shows: search · emit, then results · em
 
 More: [Trace tasks](tracing.md). To reload modules without a page refresh, see [Hot reload](hmr.md).
 
+## Test a policy with fake timers
+
+A test of `latest` or `debounce` is full of `advanceTimersByTime` numbers, and nobody can tell from them what the test proves. Write the emits and the phases as diagrams instead.
+
+```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; a frame is 10 ms
+  const marbles = createMarbleBus({ clock: fakeTimersClock(vi) });
+  marbles.bus.on("search/changed", latest(search), { traceId: "search" });
+
+  // "a-b": two emits, at frame 0 and frame 2
+  const result = await marbles.run({
+    emits: { "search/changed": { marble: "a-b" } },
+    frames: 12,
+  });
+
+  // s start, c cancel, d done
+  result.expect({ "search/changed:latest": "s-(cs)----d----" });
+});
+```
+
+More: [Test time with diagrams](testing.md).
+
 ## Other libraries in the project
 
 - **Redux Toolkit, Zustand, MobX or Pinia.** [Connect a store](stores.md).

package/docs/ru/debugging-cases.md

@@ -0,0 +1,122 @@
+# Случаи отладки
+
+> **[Уровень F](README.md#виды-проектов)**: платформа, SDK или долгоживущее приложение. Сначала прочитайте: [Трассировка задач](tracing.md#подключение-трассировщика).
+
+Прочитайте эту страницу, когда что-то идёт не так и нужно понять, кто слушает событие, что начало цепочку или почему остановился запрос. Каждый случай ниже — короткий пример, который можно запустить. О циклах читайте в разделе [Поиск и обрыв циклов событий](debugging-loops.md).
+
+## На этой странице
+
+- [Кто слушает событие](#кто-слушает-событие)
+- [Какая задача начала цепочку](#какая-задача-начала-цепочку)
+- [Почему запрос остановился](#почему-запрос-остановился)
+- [Чего не хватает](#чего-не-хватает)
+
+## Кто слушает событие
+
+**Проблема.** Вы читаете emit и хотите знать, что он запускает.
+
+Назовите обработчики функциями или через `traceId`, подключите `tracePlugin` и вызовите `describeBus`:
+
+```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);
+
+// describeBus: обработчики каждого события в порядке запуска
+console.log(describeBus(bus));
+```
+
+```
+{ "name/changed": ["saveName", "audit"] }
+```
+
+Подробнее: [Список подписчиков события](tracing.md#список-подписчиков-события).
+
+## Какая задача начала цепочку
+
+**Проблема.** Запрос выполнился, а вы не знаете, что его запросило.
+
+У каждой задачи трассировки есть `rootId` и `parentId`. Recorder хранит их, поэтому от запроса можно подняться к emit, который начал цепочку:
+
+```js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// createTraceRecorder: хранит последние события в памяти
+const recorder = createTraceRecorder();
+const trace = createTracer(recorder);
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
+
+function loadUser(id, ctx) {
+  ctx.emit("user/loading", id);
+}
+
+bus.on("user/open", loadUser);
+bus.emit("user/open", 7);
+
+// каждое событие говорит, какая задача его родитель
+for (const event of recorder.events) {
+  console.log(event.id, event.parentId, event.type, event.phase);
+}
+```
+
+Подробнее: [Какая подписка начала цепочку](tracing.md#какая-подписка-начала-цепочку) и [Сохранение цепочки: `ctx.emit` вместо `bus.emit`](tracing.md#сохранение-цепочки-ctxemit-вместо-busemit).
+
+## Почему запрос остановился
+
+**Проблема.** Запрос поиска не завершился, а ошибки нет.
+
+Политика, которая останавливает вызов, пишет в трассировку `cancel` или `drop`. Найдите вызов и прочитайте его последнюю фазу:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { createTraceRecorder, createTracer, tracePlugin } from "nanoeffects/trace";
+
+const recorder = createTraceRecorder();
+const trace = createTracer(recorder);
+
+const bus = createBus({ trace })
+  .use(tracePlugin());
+
+// latest: новый поиск останавливает тот, что ещё выполняется
+const search = latest(async (query, ctx) => {
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  ctx.emit("search/loaded", query);
+});
+
+bus.on("search/changed", search, { traceId: "search" });
+bus.emit("search/changed", "a");
+bus.emit("search/changed", "ab");
+
+// фаза "cancel" у первого вызова говорит, что его остановил второй
+const phases = recorder.events.map((event) => `${event.type}:${event.phase}`);
+console.log(phases);
+```
+
+Подробнее: [Трассировка задач](tracing.md) и [Отмена устаревших запросов](cancel-stale-requests.md).
+
+## Чего не хватает
+
+- **Нет расширения для браузера и своего интерфейса.** Используйте [Redux DevTools](tracing.md#настройка-redux-devtools), консоль или панель Performance.
+- **Нет карты по исходному коду.** `describeBus` показывает обработчики, зарегистрированные к этому моменту, а `graphLogger` — события, которые произошли. Обработчик, который ещё не зарегистрирован, на карте не появится.
+- **Нет перехода из лога в код.** С `tracePlugin({ source: true })` событие несёт `file:line:column` своего обработчика ([Строка кода обработчика](tracing.md#строка-кода-обработчика)), но ссылку в интерфейсе вы делаете сами.
+- **Нет имён от компилятора.** Имена функций дают имя бесплатно; минификатор может их сократить, поэтому используйте `traceId`, где имя должно быть стабильным.
+- **Нет повтора и путешествий во времени.** Recorder хранит то, что случилось, и не умеет запускать это заново.

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/migrating-from-rxjs.md

@@ -194,4 +194,4 @@ bus.on(
 - **Прерывание заменяет отписку для работы в полёте.** Остановленная задача останавливается через её `signal`. Передайте его в `fetch` или в клиент.
 - **Ошибки не часть потока.** Упавшая задача отклоняет собственный Promise. Без `onError` на шине об ошибке никто больше не узнает ([Ошибки](errors.md)).
 - **Нет завершения.** Шина событий не заканчивается. Задача заканчивается, когда кончается её работа или прерывается её сигнал.
-- **Нет marble-тестов.** Тестируйте настоящий обработчик с поддельными таймерами.
+- **Marble-тесты — инструмент поменьше.** [`createMarbleBus`](testing.md) записывает отправки и фазы задач диаграммами на поддельных таймерах. В нём нет горячих и холодных источников и нет `|`.

package/docs/ru/package.md

@@ -26,7 +26,8 @@
 | `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, который превысил бы предел цепочки | цикл не должен ронять приложение |
 
 Плагины с именами `...Plugin` подключаются через `bus.use`. Страница [Плагины](plugins.md) перечисляет их все, говорит, что каждый возвращает и в каком порядке их подключать.

package/docs/ru/recipes.md

@@ -29,6 +29,7 @@
   - [Не оставлять подписки после закрытия виджета](#не-оставлять-подписки-после-закрытия-виджета)
 - [Остановка работы на backend](#остановка-работы-на-backend)
 - [Отладка: что выполнилось и почему](#отладка-что-выполнилось-и-почему)
+- [Тест политики на поддельных таймерах](#тест-политики-на-поддельных-таймерах)
 - [Другие библиотеки в проекте](#другие-библиотеки-в-проекте)
 - [ООП и TypeScript](#ооп-и-typescript)
   - [Шина в классе](#шина-в-классе)
@@ -480,6 +481,40 @@ bus.emit("search", "nano"); // в логе: search · emit, затем results
 
 Подробнее: [Трассировка задач](tracing.md). Чтобы перезагружать модули без обновления страницы, см. [Hot reload](hmr.md).
 
+## Тест политики на поддельных таймерах
+
+Тест `latest` или `debounce` полон чисел `advanceTimersByTime`, и по ним никто не поймёт, что тест доказывает. Запишите отправки и фазы диаграммами.
+
+```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: шина, которая записывает трассировку; кадр — 10 мс
+  const marbles = createMarbleBus({ clock: fakeTimersClock(vi) });
+  marbles.bus.on("search/changed", latest(search), { traceId: "search" });
+
+  // "a-b": две отправки, в кадре 0 и в кадре 2
+  const result = await marbles.run({
+    emits: { "search/changed": { marble: "a-b" } },
+    frames: 12,
+  });
+
+  // s старт, c отмена, d готово
+  result.expect({ "search/changed:latest": "s-(cs)----d----" });
+});
+```
+
+Подробнее: [Тесты времени диаграммами](testing.md).
+
 ## Другие библиотеки в проекте
 
 - **Redux Toolkit, Zustand, MobX или Pinia.** [Подключение store](stores.md).