nanoeffects 0.31.2 → 0.33.0

package/llms-full.txt

@@ -581,6 +581,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)
@@ -1032,6 +1033,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).
@@ -1286,7 +1321,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.
@@ -7317,7 +7353,7 @@ 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 `|`.
 
 ---
 Source: docs/semantics.md
@@ -7695,6 +7731,102 @@ test("a newer search stops the older one at every step", async () => {
 - **A handler that never emits.** `devPlugin` sees a lost signal by an emit after the cancel; a handler that only writes elsewhere is seen by the linter alone.
 - **Shadowed names.** The rule uses no scope analysis, so an inner variable named `signal` can hide a lost signal.
 
+---
+Source: docs/testing.md
+
+# 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.
+
 ---
 Source: docs/tracing.md
 
@@ -7713,15 +7845,20 @@ 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)
   - [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
@@ -7886,7 +8023,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";
@@ -7909,6 +8046,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 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";
+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#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)"] }
+```
+
+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.
@@ -7951,7 +8170,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
 
@@ -8011,12 +8230,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 -->
@@ -8148,6 +8446,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.
@@ -8165,6 +8483,132 @@ conditions: ["notrace"]
 
 In a build from the sources, `define: { __NANOEFFECTS_TRACE__: "false" }` does the same. With the condition set, that build’s types have no `trace` option: `createBus({ trace })` is a type error. `nanoeffects/trace` has no `notrace` build. The saving is about 0.4 kB gzip of the whole library.
 
+---
+Source: docs/debugging-cases.md
+
+# 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.
+
 ---
 Source: docs/debugging-loops.md
 
@@ -8186,6 +8630,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)
 
@@ -8448,6 +8893,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/llms.txt

@@ -60,8 +60,10 @@ Rules that generated code often gets wrong:
 
 - [Semantics](docs/semantics.md): exact rules of emit, abort and ordering
 - [Keep the signal through a handler](docs/pass-the-signal.md): every way a policy handler loses `ctx.signal`, and the lint rules and `devPlugin` check that find it
-- [Trace tasks](docs/tracing.md): loggers, Redux DevTools, `graphLogger`, the `notrace` build
-- [Find and cut event loops](docs/debugging-loops.md): symptoms, `graphLogger`, the graph as Mermaid, Graphviz or JSON, Redux DevTools
+- [Test time with diagrams](docs/testing.md): `createMarbleBus` and `fakeTimersClock`; emits and phases as diagrams on fake timers
+- [Trace tasks](docs/tracing.md): loggers, `timingLogger` for durations and open tasks, `chainOf` for the cause of an error, Redux DevTools, `graphLogger`, the `notrace` build
+- [Debugging cases](docs/debugging-cases.md): who listens to an event, what began a chain, why a request stopped
+- [Find and cut event loops](docs/debugging-loops.md): symptoms, `graphLogger`, the graph as Mermaid, Graphviz or JSON, Redux DevTools, `mergeGraphs` and `findOrphans` for listeners no run reached
 - [Cut a loop with loopGuardPlugin](docs/loop-guard.md): limits on repeats, depth and emits from outside
 - [Turn events into Observables](docs/observable.md): `createObserve`, `Subject`, `events` (an event as a `for await` loop)
 - [Hot reload and development diagnostics](docs/hmr.md): `devPlugin`