nanoeffects 0.29.0 → 0.30.1

package/docs/context.md

@@ -1,8 +1,31 @@
-# Put your own fields on every task
+# Working with context
 
-Optional: put a store, client, or logger on every task. Skip until many handlers need the same dependency.
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus).
 
-## Pass values at runtime
+Optional: put a store, client or logger on every task, or give fields to one action, module or call. Skip until many handlers need the same dependency.
+
+## On this page
+
+- [Context fields](#context-fields)
+  - [Pass values at runtime](#pass-values-at-runtime)
+  - [Type the fields (optional)](#type-the-fields-optional)
+  - [Build a field from the signal of each task](#build-a-field-from-the-signal-of-each-task)
+- [Scope: fields for an action, a module and a call](#scope-fields-for-an-action-a-module-and-a-call)
+  - [Turn scopes on](#turn-scopes-on)
+  - [Give an action its own fields](#give-an-action-its-own-fields)
+  - [Bind an effect to the task](#bind-an-effect-to-the-task)
+  - [Replace a field for one call](#replace-a-field-for-one-call)
+  - [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
+  - [Which value wins](#which-value-wins)
+  - [Keep a generic effect generic](#keep-a-generic-effect-generic)
+  - [Type the fields of a scope](#type-the-fields-of-a-scope)
+  - [Limits](#limits)
+
+## Context fields
+
+### Pass values at runtime
+
+<!-- docs-check: new -->
 
 ```js
 import { createBus } from "nanoeffects";
@@ -15,15 +38,17 @@ bus.on("save", (draft, { store }) => {
 });
 ```
 
-That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
+Here `store` is your own object: a store, an API client, a logger, anything. That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
 
 Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may be a function `(task) => fields` when the value depends on the task.
 
-To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
+To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#effectsplugin).
+
+To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](context.md#scope-fields-for-an-action-a-module-and-a-call).
 
-To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+### Type the fields (optional)
 
-## Type the fields (optional)
+<!-- docs-check: new -->
 
 In TypeScript, `contextPlugin` (from `nanoeffects/context`) puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
 
@@ -45,7 +70,9 @@ bus.on("save", (draft, { store }) => store.put(draft));
 - A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
 - The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
 
-## Build a field from the signal of each task
+### Build a field from the signal of each task
+
+<!-- docs-check: new -->
 
 Problem: an HTTP client or a database handle should stop when the task is aborted. Without help, every handler passes `ctx.signal` to it by hand, and one forgotten call leaves a request running.
 
@@ -77,7 +104,7 @@ bus.on("user/open", async (id, ctx) => {
 - The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.
 - Without `contextPlugin` a `fromSignal` marker is only an object.
 
-### Name the fields in the event map instead
+#### Name the fields in the event map instead
 
 `createBus<Events>({ context: { store } })` also types the fields, but through the event map: `WithContext` is checker-only and says which fields the handlers of this bus have. Use it when you cannot call `use`, for example for the bus that `createEffectsMiddleware` makes.
 
@@ -89,3 +116,288 @@ type Events = { save: Draft } & WithContext<{ store: Store }>;
 
 const bus = createBus<Events>({ context: { store } });
 ```
+
+## Scope: fields for an action, a module and a call
+
+Optional, for domain logic. Use it when one action needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
+
+A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `$effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
+
+You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
+
+### Turn scopes on
+
+<!-- docs-check: new -->
+
+Scopes are a plugin, so a bus that does not use them pays nothing.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scopes below work on this bus; returns the same bus
+export const bus = createBus().use(scopePlugin());
+```
+
+The bus is in one file and the actions in files named after their domain, so the next example imports `bus` from here. Each section after it keeps its own `bus.js` and domain file, as if it were an app of its own.
+
+- Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
+- Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
+
+### Give an action its own fields
+
+<!-- docs-check: new -->
+
+<!-- docs-check: continue -->
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — third argument is the scope of this action
+export const getUser = createAction(
+  "user/get",
+  (id, { api, cache }) => {
+    // api and cache are on ctx for this action only
+    return cache.get(id) ?? api.getUser(id);
+  },
+  { api, cache: new Map() },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+const user = await bus.emit(getUser("1")); // the handler has api and cache
+```
+
+The listeners of `"user/get"` get the same fields when the action is emitted, because the fields belong to the call.
+
+### Bind an effect to the task
+
+<!-- docs-check: new -->
+
+An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
+
+```js
+// feed.js
+import { createAction } from "nanoeffects/actions";
+import { delay, race } from "nanoeffects/effects";
+
+// your own effect: first parameter is the task (only its signal is used)
+const fetchJson = (ctx, url) =>
+  fetch(url, { signal: ctx.signal }).then((response) => response.json());
+
+export const loadFeed = createAction(
+  "feed/load",
+  (url, { fetchJson, race, delay }) =>
+    // race, delay, fetchJson — bound to this task: no ctx argument
+    race({
+      feed: () => fetchJson(url),
+      timeout: () => delay(5000),
+    }),
+  // $effects — built-in and your own functions share one object
+  { $effects: { fetchJson, race, delay } },
+);
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+import { bus } from "./bus";
+import { loadFeed } from "./feed";
+
+const result = await bus.emit(loadFeed("/feed"));
+```
+
+- Put in `$effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
+- A function under any other key is copied as it is; a function in `$effects` is bound.
+- `$effects` is the one name with a meaning. A field called `effects` is an ordinary field: `{ effects: { retries: 3 } }` puts that object on `ctx`, and nothing in it is bound.
+
+### Replace a field for one call
+
+<!-- docs-check: new -->
+
+The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+export const getUser = createAction(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+// the real api for this call
+await bus.emit(getUser("1"));
+
+// the second argument — a fake api, for this call only
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+await bus.emit(getUser("1"), { api: fakeApi });
+```
+
+Rules for the second argument:
+
+- It works with the call of an action (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
+- It does not work with the string form: in `emit("user/get", payload)` the second argument is the payload.
+- It can replace `$effects` too: `{ $effects: { delay: instantDelay } }`.
+- Fields of the library (`signal`, `emit`, …) in it are ignored.
+
+### Give an action, a job or a module its own fields
+
+<!-- docs-check: new -->
+
+```js
+// user.js
+import { createAction, createJob } from "nanoeffects/actions";
+
+// createAction — the listeners of this action's calls get the fields
+export const userLoaded = createAction("user/loaded", { store });
+
+// createJob — the scope is the fourth argument, after the outcomes;
+// the handler and the listeners of the outcome get its fields
+export const loadUser = createJob(
+  "user/load",
+  fetchUser,
+  { success: userLoaded, fail: "user/failed" },
+  { logger },
+);
+```
+
+```js
+// audit-module.js
+import { createModule } from "nanoeffects/actions";
+import { userLoaded } from "./user";
+
+// createModule — third argument; everything the module owns gets the fields:
+// m.on listeners, m.handle handlers, m.spawn tasks
+export const auditModule = createModule(
+  "audit",
+  (m) => {
+    m.on(userLoaded, (user, { logger }) => logger.info(user.id));
+  },
+  { logger },
+);
+```
+
+If the outcome action (`success` or `fail`) has a scope of its own, its listeners see the job's fields with the action's own fields over them; the handler of the job sees only the job's.
+
+A module scope does not leak: a listener registered outside the module does not see it.
+
+### Which value wins
+
+<!-- docs-check: new -->
+
+When several places set the same field, the strongest one wins:
+
+| Strength | Where it is set |
+| -------- | --------------- |
+| 1 (strongest) | the second argument of `emit` |
+| 2 | the scope of the action or job |
+| 3 | the scope of the module that owns the handler |
+| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
+
+The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. The name `traceGroupId` is reserved: the tracer reads it, and it is not put on `ctx` ([Follow one flow](tracing.md#follow-one-flow-with-a-tracegroupid)). A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+
+### Keep a generic effect generic
+
+<!-- docs-check: new -->
+
+In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+
+`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
+
+```js
+// pick.js
+import { createAction } from "nanoeffects/actions";
+import { effect } from "nanoeffects/scope";
+
+// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
+const first = effect((ctx, items) => items[0]);
+
+export const pick = createAction("pick", (items, { first }) => first(items), {
+  first, // a plain key of the scope, not an entry of `$effects`
+});
+```
+
+Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
+
+`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `$effects`.
+
+```ts
+import { createAction } from "nanoeffects/actions";
+import type { Effect } from "nanoeffects/effects";
+
+// First — checker-only: how a handler calls the effect (no ctx)
+type First = <T>(items: T[]) => T;
+
+// Effect<First> — the function takes the task first and is typed as First once bound
+const first: Effect<First> = (ctx, items) => items[0];
+
+const pick = createAction(
+  "pick",
+  (id: string, { first }) => first([id]), // string
+  { $effects: { first } },
+);
+```
+
+`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
+
+### Type the fields of a scope
+
+<!-- docs-check: new -->
+
+A handler of an action, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+
+```ts
+import { createAction } from "nanoeffects/actions";
+
+type User = { id: string; name: string };
+
+const getUser = createAction(
+  "user/get",
+  async (id: string, ctx) => {
+    ctx.cache; // Map<string, User>, from the scope below
+    return ctx.cache.get(id);
+  },
+  { cache: new Map<string, User>() },
+);
+```
+
+- A field of a scope replaces a field of the same name from the bus in the type too.
+- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
+- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
+- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
+
+### Limits
+
+<!-- docs-check: new -->
+
+- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
+- The fields of the bus are not in the handler of an action made with `createAction(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
+- The string form of `emit` takes no scope.
+- `effect(fn)` works only as a value of a scope, not as an entry of `$effects`.
+- A scope on an action, job or module is typed without the events of a bus, so `take` in its `$effects` takes any event name.

package/docs/debounce-and-abort.md

@@ -1,4 +1,6 @@
-# Debounce a request and abort the previous one
+# Pause between requests
+
+> **Level B.** Read first: [Policies](policies.md).
 
 Read this page if you debounce user input (a search box, an autosave, a resize handler) and you also want the request in flight to stop when a new one starts. `debounce` alone waits for a pause. It does not cancel a request that already started. This page shows the two policies together, the order to put them in, and when to use `throttle` instead.
 

package/docs/debugging-loops.md

@@ -0,0 +1,283 @@
+# Find and cut event loops
+
+> **Level F.** Read first: [Trace tasks](tracing.md#attach-a-tracer). To only cut a loop, go to [`loopGuardPlugin`](loop-guard.md).
+
+A loop is two handlers that emit each other's events, or one handler that emits its own. This page finds a loop, shows it, and stops it. Every scenario below is a runnable file in [`examples/debug`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/debug), and a page with buttons and Redux DevTools is in [`examples/debug-playground`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/debug-playground).
+
+## On this page
+
+- [Start from the symptom](#start-from-the-symptom)
+- [Find a loop](#find-a-loop)
+- [Read a report](#read-a-report)
+- [Draw the graph](#draw-the-graph)
+- [See the loop in Redux DevTools](#see-the-loop-in-redux-devtools)
+- [Find a loop that no chain shows](#find-a-loop-that-no-chain-shows)
+- [Break the loop](#break-the-loop)
+- [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)
+- [Know the limits](#know-the-limits)
+
+## Start from the symptom
+
+| What you see | Likely cause | Go to |
+| ------------ | ------------ | ----- |
+| The page freezes | A loop of microtasks or a synchronous loop | [Find a loop](#find-a-loop), then [Cut a loop at run time](#cut-a-loop-at-run-time) |
+| A request repeats on its own | A handler emits the event that starts it | [Read a report](#read-a-report) |
+| `RangeError: Maximum call stack size exceeded` | A synchronous loop through `emit` | [Find a loop](#find-a-loop) |
+| A component renders again and again | A value is sent to the bus on every render | [Find a loop that no chain shows](#find-a-loop-that-no-chain-shows) |
+| You do not know which event leads to which | No map of the events | [Draw the graph](#draw-the-graph) |
+
+## Find a loop
+
+`graphLogger` is a trace logger. Pass it to `createTracer` like any other logger. It builds the map of which event leads to which, and writes a report once when a chain passes the same event three times. Add `tracePlugin` so that it also sees every emit and the names of your listeners. It works without the plugin, with a coarser map.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// graphLogger — the map of events and the loop finder, in one logger
+export const graph = graphLogger({ name: "cart" });
+
+// createTracer — sends every task of the bus to the logger
+const trace = createTracer(graph);
+
+// tracePlugin — reports every emit, so the graph also shows events that nothing listens to
+export const bus = createBus({ trace }).use(tracePlugin());
+```
+
+The handlers are the part of your app that has the loop. Here a cart and a total update each other:
+
+```js
+// cart-handlers.js
+import { bus } from "./bus";
+
+// traceId — the name of the listener in the graph and in the report
+bus.on(
+  "cart/changed",
+  (cart, ctx) => {
+    ctx.emit("total/changed", cart);
+  },
+  { traceId: "recalcTotal" },
+);
+
+bus.on(
+  "total/changed",
+  (total, ctx) => {
+    ctx.emit("cart/changed", total);
+  },
+  { traceId: "syncCart" },
+);
+```
+
+`graphLogger` costs a lookup for each task. Use it while you develop, or with `createTracer(graph, { sample })` in production.
+
+## Read a report
+
+<!-- docs-check: continue -->
+
+The report is one `console.warn` for each loop:
+
+```text
+[nanoeffects cart] cycle: recalcTotal → total/changed → syncCart → cart/changed → recalcTotal (repeated 3 times, started at cart/changed)
+  recalcTotal at src/cart-handlers.js:6; syncCart at src/cart-handlers.js:14   (only with devPlugin)
+  handlers feed each other: break the loop with a condition, or emit a different event for the result
+```
+
+- **The path** goes from the first turn of the loop back to it. A named listener shows its event before it.
+- **`started at`** is the first event of the chain.
+- **`at file:line`** appears when you also use [`devPlugin`](hmr.md#report-leaks-with-devplugin).
+- **The last line** is advice for this shape of loop.
+
+To receive the finding in code, pass `onCycle`. It replaces the console report:
+
+```js
+// report.js
+import { graphLogger } from "nanoeffects/trace";
+
+export const graph = graphLogger({
+  // onCycle — called once for each loop; the finding has a path, the repeats and the root
+  onCycle: (finding) => {
+    console.error(finding.kind, finding.path.join(" → "));
+  },
+});
+```
+
+`graph.cycles()` lists the loops found so far, with `turns`: how many times a loop went round after it was found. It also lists cycles that no single chain showed, when the edges of different runs close a loop (`source: "graph"`).
+
+## Draw the graph
+
+<!-- docs-check: continue -->
+
+The graph has a count on each edge, and the edges of a cycle are marked. Write it in the format your tool reads:
+
+```js
+// draw.js
+import { graph } from "./bus";
+
+// Mermaid: paste it into a README, a pull request or https://mermaid.live
+const mermaid = graph.toMermaid({ group: "prefix" }); // group the events by the part before "/"
+
+// Graphviz: dot -Tsvg graph.dot > graph.svg
+const dot = graph.toDot();
+
+// plain data for your own tools
+const data = graph.toJSON();
+
+console.log(mermaid, dot, data);
+```
+
+```mermaid
+flowchart LR
+  n0["cart/changed"]
+  n1["recalcTotal"]
+  n2["total/changed"]
+  n3["syncCart"]
+  n0 -->|x21| n1
+  n1 -->|x20| n2
+  n2 -->|x20| n3
+  n3 -->|x20| n0
+  linkStyle 0,1,2,3 stroke:red,stroke-width:2px
+```
+
+The counts (`x21`) are how many times each edge was seen; they depend on how long the loop ran.
+
+## See the loop in Redux DevTools
+
+`devtools: true` sends each finding to the extension as a `cycle/detected` action. Put `reduxDevtools` next to it to also see the emits:
+
+```js
+// devtools-bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, reduxDevtools, tracePlugin } from "nanoeffects/trace";
+
+// devtools: true — one cycle/detected action for each loop, with the path
+const graph = graphLogger({ name: "app", devtools: true });
+
+// reduxDevtools — the emits of the bus as actions
+const trace = createTracer([reduxDevtools({ name: "app" }), graph]);
+
+export const bus = createBus({ trace }).use(tracePlugin());
+```
+
+Redux DevTools is a browser extension, so open the page in its own tab and pick the instance in its list. Without the extension nothing is sent and nothing throws. You can try it with the buttons of [`examples/debug-playground`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/debug-playground).
+
+## Find a loop that no chain shows
+
+Some loops have no chain of emits:
+
+- **A component that emits on every render.** `useEmitter` and a `bus.emit` in an effect run outside any handler, so each emit is a root. `graphLogger` counts such emits for each event, and reports a **storm** when one event comes 100 times in a second. Change the limit with `storm: { count, perMs }`, or turn it off with `storm: false`.
+- **A `bus.emit` inside a handler.** It starts a new chain, so the handler that calls it again does not look like a loop. Use `ctx.emit` inside handlers to keep the chain.
+- **A chain of generated names** (`step/${n}`) never repeats a name. `graphLogger` reports a **runaway** chain when one root starts more than `maxSteps` tasks (5000 by default).
+
+```js
+// storm.js
+import { graphLogger } from "nanoeffects/trace";
+
+export const graph = graphLogger({
+  storm: { count: 50, perMs: 1000 }, // 50 emits of one event in a second from outside
+  maxSteps: 2000, // 2000 tasks started by one root
+  ignore: ["tree/visit"], // a recursion on purpose is not counted
+});
+```
+
+## Break the loop
+
+| Shape | Fix |
+| ----- | --- |
+| A handler emits its own event | Emit a different event for the result (`user/loaded`, not `user/load`). |
+| Two handlers feed each other | Add the condition that ends it, or send the result to a third event that nothing in the loop listens to. |
+| A job whose outcome has the type of its trigger | Give the outcomes their own types. |
+| A component emits on every render | Pass `equals` to `useEmitter`, so the same value is not an emit, or `debounce` the handler. |
+| A failure re-emits the event that failed | Stop after a number of tries with `retry`, not with an event. |
+
+## Cut a loop at run time
+
+The report does not stop a loop. For a loop that must not take the page down, add [`loopGuardPlugin`](loop-guard.md). It refuses the emit that would pass 50 repeats, or a chain of 1000 emits, and reports it:
+
+```js
+// guarded-bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+const graph = graphLogger({ name: "app" });
+const trace = createTracer(graph);
+
+// loopGuardPlugin — cuts the loop that the graph reports
+export const bus = createBus({ trace })
+  .use(tracePlugin())
+  .use(loopGuardPlugin({ maxRepeats: 50 }));
+```
+
+The guard is independent of the logger: use either one alone.
+
+## Fail a test on a loop
+
+Run a flow of the app and check that the graph has no cycle. A loop that someone adds later fails the build.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// the bus.js of "Find a loop": the graph logger on the tracer of the bus
+export const graph = graphLogger({ name: "cart" });
+export const bus = createBus({ trace: createTracer(graph) }).use(tracePlugin());
+```
+
+```js
+// cart-handlers.js
+import { bus } from "./bus";
+
+bus.on("checkout/started", (_order, ctx) => {
+  ctx.emit("checkout/paid");
+});
+```
+
+```js
+// cycles.test.js
+import { expect, test } from "vitest";
+import { bus, graph } from "./bus";
+import "./cart-handlers";
+
+test("the checkout flow has no event cycles", () => {
+  // run the flow the way a user would
+  bus.emit("checkout/started");
+
+  // cycles() — empty when the graph has no loop
+  expect(graph.cycles()).toEqual([]);
+});
+```
+
+## Export the graph and the payloads
+
+The exports leave payloads out, because a payload can hold private data. Ask for them when you need them:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// the bus.js of "Find a loop": the graph logger on the tracer of the bus
+export const graph = graphLogger({ name: "cart" });
+export const bus = createBus({ trace: createTracer(graph) }).use(tracePlugin());
+```
+
+```js
+// payloads.js
+import { graph } from "./bus";
+
+// payload: true — adds the last payload and error of each node, made safe
+const data = graph.toJSON({ payload: true });
+
+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.
+
+## Know the limits
+
+- A chain that repeats on purpose is reported. List its event in `ignore`.
+- The report is made once for each loop. `turns` in `graph.cycles()` keeps counting.