nanoeffects 0.31.1 → 0.32.0

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

@@ -27,6 +27,7 @@
 | `nanoeffects/vue` | `vuePlugin`: добавляет `watchEmitter` и `useEventRef` на шину (нужен Vue 3.3 или новее) | компоненты Vue |
 | `nanoeffects/dev` | `devPlugin` (в production ничего не делает), `getLostSignalsCount` и `getLostSignals` для тестов | нужно находить утечки подписок и потерянные сигналы при разработке и в тестах |
 | `nanoeffects/trace` | `createTracer`, логгеры (`graphLogger` находит циклы событий) и `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).

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,6 +13,8 @@
 - [Какая подписка начала цепочку](#какая-подписка-начала-цепочку)
 - [Один поток через traceGroupId](#один-поток-через-tracegroupid)
 - [Имя обработчика](#имя-обработчика)
+- [Список подписчиков события](#список-подписчиков-события)
+- [Строка кода обработчика](#строка-кода-обработчика)
 - [Сохранение цепочки: `ctx.emit` вместо `bus.emit`](#сохранение-цепочки-ctxemit-вместо-busemit)
 - [Отключение имён](#отключение-имён)
 - [Встроенные логгеры](#встроенные-логгеры)
@@ -186,7 +188,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 +211,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 })` его перечисляет. Обработчик без имени тоже попадает в трассировку, под типом своего события.
+
+```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 · 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`, так что трассировка теряет связь. Шина не может об этом предупредить, потому что не знает, какой обработчик сейчас выполняется.

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.

package/docs/tracing.md

@@ -13,6 +13,8 @@ Tracing is optional. A bus works the same without it, and it costs almost nothin
 - [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)
+- [List who listens](#list-who-listens)
+- [Find the line of a listener](#find-the-line-of-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)
@@ -186,7 +188,7 @@ The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", trac
 
 **When.** An event has more than one listener and you read the trace to see which one did the work.
 
-Give the listener a `traceId` when you register it. The plugin makes each call of it a task with that name, and what it emits with `ctx.emit` is below it. `off` works as before. It also works in a module (`m.on(event, handler, { traceId })`) and on an instance made by `extendBus`.
+A listener is named by its function when you register one with a name (`function saveName() {}`), so a log of an app that nobody annotated is already readable. An inline arrow has no name and stays as it is. To choose the name, or to name an arrow, give the listener a `traceId` when you register it; it wins over the function name. The plugin makes each call of a named listener a task with that name, and what it emits with `ctx.emit` is below it. A minifier can shorten function names in a production build: use `traceId` where a name must stay stable, and for a handler that a policy returns (`latest(fn)`), which has no name of its own. `off` works as before. It also works in a module (`m.on(event, handler, { traceId })`) and on an instance made by `extendBus`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -209,6 +211,88 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 [nanoeffects] saveNotifier · run done
 ```
 
+## List who listens
+
+**Problem.** To know what an emit will start, you search the code for every `bus.on` of that event.
+
+**When.** You read an app that you did not write, or a test must guard the wiring of the bus.
+
+`describeBus(bus)` returns the listeners that each event has right now, by name and in the order they were added. A name is the `traceId`, else the function name, else `"<anonymous>"`. It reads what `tracePlugin` keeps, so it returns `{}` on a bus without the plugin or a tracer, and in the `notrace` build. It does not run anything and does not change the bus.
+
+```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: the map of events to listener names
+console.log(describeBus(bus));
+```
+
+```
+{ "name/changed": ["saveName", "audit"], saved: ["refreshView"] }
+```
+
+## Find the line of a listener
+
+**Problem.** The log says that `saveNotifier` ran, and you must search the code for the `bus.on` that registered it. An inline arrow has no name at all, so it is not in the log.
+
+**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.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, describeBus, tracePlugin } from "nanoeffects/trace";
+
+// source: print where the listener was registered
+const trace = createTracer(consoleLogger({ source: true }));
+
+// source: read the place of each bus.on, once at registration
+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: the same places, without running anything
+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)
+{ "name/changed": ["saveName (file:///app/src/user.js:13:5)", "<anonymous> (file:///app/src/user.js:14:5)"] }
+```
+
+Know the limits:
+
+- **Minified or bundled code** gives the line of the bundle. Turn on source maps (`node --enable-source-maps`, or the browser's) to see the original line.
+- **`ctx.on` called by hand** inside a handler shows the line in the library as its place. The `on` of a module and of an instance made by `extendBus`, and the `on` of `matchPlugin`, `signalPlugin` and `devPlugin`, show your line, in any order of plugins and in a bundle.
+- **No stack**, as with `Error.stackTraceLimit = 0`, gives no `source`. The listener runs as usual.
+- **The default is off.** Reading a stack costs a little for each registration, so turn it on in development.
+
 ## Keep the chain: `ctx.emit`, not `bus.emit`
 
 Inside a handler, emit with `ctx.emit`. It keeps the chain: what it starts is below the handler, and its events have the `rootId` of the chain. A plain `bus.emit` inside a handler starts a new root with no `parentId` and no `rootId`, so the trace loses the link. The bus cannot warn about it, because it does not know which handler is running.