nanoeffects 0.10.0 → 0.12.0

package/docs/tracing.md

@@ -21,12 +21,14 @@ Each `TraceEvent` has:
 | Field | Meaning |
 | ----- | ------- |
 | `id` | Unique task id within the bus |
-| `parent` | Id of the task that started this one (absent for handler tasks) |
+| `parentId` | Id of the task that started this one (absent for handler tasks) |
+| `rootId` | Id of the root task of the chain; absent on the root itself, and it is the same through a listener that reports nothing |
 | `type` | Event type the task works on |
-| `effect` | `latest`, `debounce`, `throttle`, `leading`, `run`, `all`, `race`, … |
+| `effect` | `latest`, `debounce`, `throttle`, `leading`, `run`, `all`, `race`, …; `emit` for the emit event of `tracePlugin` |
 | `phase` | `start`, `done`, `error`, `cancel`, or `drop` |
 | `payload` | Event payload |
 | `error` | Thrown value, only for `error` |
+| `traceGroupId` | The flow of the task, when it or a task above has one |
 
 Phases:
 
@@ -51,6 +53,150 @@ bus.on("load", async (id, ctx) => {
 });
 ```
 
+## Show every emit
+
+**When.** You want the log to say what was emitted, also when nothing listens or the listener is a plain function. Without it the trace has only the tasks that report: a policy (`latest`, ...) or a `ctx.run`.
+
+`tracePlugin` reports one event for each emit, with `effect: "emit"` and `phase: "done"`, before the handlers run. `type` is the event name and `payload` is what was emitted. A `ctx.emit` has the task that emits as its `parentId`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+export const bus = createBus({ trace: createTracer(consoleLogger()) })
+  .use(tracePlugin()); // tracePlugin: reports each emit as an event
+```
+
+```js
+import { bus } from "./bus";
+
+bus.emit("search", "nano"); // logs: search · emit done
+```
+
+The event changes nothing else: the other tasks keep their `parentId`, `rootId` and `traceGroupId`. Without the plugin the trace has no `emit` events.
+
+- **What counts as an emit.** Every `bus.emit`, also the ones a library makes for you: a job emits its `pending` and `success` (or `fail`, `cancel`), so one call of a job is several `emit` events.
+- **Cost.** One small task per emit, about 60 ns on a bus that already has a tracer (a bus with a tracer and no plugin: about 250 ns more than a bus without one). `sample` and `filter` of `createTracer` cut it in the log, not in the work.
+
+## Show which subscription began a chain
+
+**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of commands and retries.
+
+**When.** The bus has a tracer and the project has several `useEmitter` or `bus.emitter` calls. The names come from `tracePlugin`: use it on the bus, or the `traceId` is ignored.
+
+Give each one a `traceId`. When the bus has a tracer, the emit is made from a root task with that `traceId` as its `type` and `run` as its effect. What the event starts is below it. Without a tracer nothing changes.
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// createTracer: reports every task phase to the console
+const bus = createBus({ trace: createTracer(consoleLogger()) })
+  .use(tracePlugin()) // tracePlugin: makes the root task that traceId names
+  .use(emitterPlugin());
+
+const cartChanged = createAction("cart/changed");
+
+// emitter: a callback for a store; traceId names it in the trace
+const emitCartChanged = bus.emitter(cartChanged, { traceId: "cartStore" });
+```
+
+In a component, the same option goes in the options of the hook: `useEmitter(nameChanged, name, { traceId: "Profile" })`. In the console:
+
+```
+[nanoeffects] Profile · run start
+[nanoeffects]   user/save · command start
+[nanoeffects]   user/save · command done
+[nanoeffects] Profile · run done
+```
+
+A `traceId` is a string you choose and keep stable: the name of the component or of the store. Without one the root has the type of the event.
+
+Two things to know:
+
+- **`sample` sees the `traceId`.** The root of an emitter is a task like any other, so a `sample` function gets `{ type, payload }` with the `traceId` as the `type` and the emitted action as the `payload`. A function that matches on the type of the event, such as `event.type === "search"`, does not pick a root that has another `traceId`; match the `traceId`, or the `payload.type`.
+- **Inside a handler, emit with `ctx.emit`.** `ctx.emit` keeps the chain: what it starts is below the handler. A plain `bus.emit` inside a handler starts a new root with no parent and no `rootId`, so the trace loses the link.
+
+Every event of a task below another one has `rootId`, the id of the root of the chain, also when a listener, which reports nothing, stands in between. `parentId` is the task directly above, which can be such a listener.
+
+## Follow one flow with a traceGroupId
+
+**Problem.** A flow such as a checkout has several roots (a click, a timer, a store) and many branches. Parent ids give a tree, but you want to filter the log by the flow.
+
+**When.** One business flow runs through several commands, and you read the log by flow.
+
+Give the flow a `traceGroupId` in the scope of the command, the job or the action that starts it. Every task that it starts through `ctx.emit` or `ctx.run` has the same `traceGroupId`, and so does every trace event of those tasks. A task that declares its own `traceGroupId` uses it for itself and for what it starts.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// tracePlugin: reads traceGroupId from the scope of a call
+const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+
+// the scope names the flow; traceGroupId is for the tracer, not a field of ctx
+const pay = createCommand("checkout/pay", async () => {}, {
+  traceGroupId: "checkout",
+});
+```
+
+```
+[nanoeffects] [checkout] checkout/pay · command start
+```
+
+The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", traceGroupId: "checkout" })`. `traceGroupId` works without `scopePlugin`, and needs `tracePlugin`.
+
+## Name a listener
+
+**Problem.** The log shows what started a chain and what it started, but a listener of an event reports nothing, so you cannot tell which of several listeners ran.
+
+**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`.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+
+// traceId: the name of this listener in the trace
+bus.on("name/changed", saveName, { traceId: "saveNotifier" });
+bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
+```
+
+```
+[nanoeffects] saveNotifier · run start
+[nanoeffects]   user/save · command start
+[nanoeffects] saveNotifier · run done
+```
+
+## 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.
+
+The names work wherever an event or a listener is made:
+
+| Where | How to name it |
+| ----- | -------------- |
+| `useEmitter` and `bus.emitter` | `{ traceId, traceGroupId }` in the options |
+| A Redux dispatch | `createEffectsMiddleware(bus, { traceId, traceGroupId })` |
+| A listener, `bus.on` and `bus.once` | `{ traceId }` as the third argument |
+| A listener of a module or of an instance of `extendBus` | the same third argument of its `on` and `once` |
+| A method with `@On` or `@Once` | `{ traceId }` in the decorator |
+| A command, a job or an action | `traceGroupId` in its scope |
+
+## Turn the names off
+
+`tracePlugin` is optional, and none of it changes how your code runs:
+
+- **Without the plugin**, or on a bus without a tracer, `traceId` and `traceGroupId` are ignored. Handlers run as they are, with the same results, errors and rejections, and `onError` sees the same errors.
+- **The types are the same** with and without the plugin, so you can use it only in development: `if (isDev) bus.use(tracePlugin())` compiles in both builds.
+- **A `traceGroupId` in a scope** is never put on `ctx`.
+
 ## Use built-in loggers
 
 A logger is `(event) => void`. `createTracer` takes one logger or an array. A logger that throws is reported to `console.error` and never breaks the task or the other loggers.
@@ -66,7 +212,7 @@ const bus = createBus({
 
 | Logger | What it does |
 | ------ | ------------ |
-| `reduxDevtools()` | Sends tasks to Redux DevTools as `type/effect/phase`; state is `{ running }` |
+| `reduxDevtools()` | Sends the emits to Redux DevTools, and with `policies` the stages of the handlers as `type/effect/phase`; state is `{ running }` |
 | `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`, for tests |
@@ -89,19 +235,49 @@ createTracer(logger, {
 
 Read-only (the bus owns no state, so there is no time travel). Does nothing when the extension is not installed. Has its own instance in the DevTools picker, apart from your store.
 
-Quiet by default:
+Quiet by default, so you see what happened before you see how:
+
+- **One action per emit**, named after the event (`search`), with its payload. This needs `bus.use(tracePlugin())` (see [Show every emit](#show-every-emit)); without it the default log is empty, and the logger prints one `console.warn` when the first handler task ends with no emit before it.
+- **A failed handler** is sent as `search/latest/error`.
+- Nothing else: no start, no `done`, no policy stages, no effects.
+
+Turn on more when you need it:
 
-- **A task is one action**, sent when it ends (`done`, `error`, `cancel`, `drop`). Running tasks are in `{ running }`. `starts: true` also sends every start.
-- **Only the top is shown**: handler tasks and the effects they start. Attempts and starters under them are hidden. `depth: 0` — handlers only; `depth: 3` — more; `Infinity` — everything.
+- `policies` — the stages of the handler tasks, as `event/policy/phase`. `true` shows every phase, a list shows those phases, a function gets `{ effect, phase }`.
+- `starts: true` — also send the start of each shown task. Running tasks are in the state `{ running }`.
+- `depth: 1` — also the effects a handler starts (`retry`, `timeout`); `depth: Infinity` — everything below.
 - `maxAge: 200` — how many actions DevTools keeps (its default is 50).
 
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, reduxDevtools, tracePlugin } from "nanoeffects/trace";
+
+// reduxDevtools: sends the trace to the extension; it has the emits and the failures only
+const logger = reduxDevtools({ name: "app" });
+
+export const bus = createBus({ trace: createTracer(logger) })
+  .use(tracePlugin()); // tracePlugin: makes the emit events
+```
+
 ```js
 import { reduxDevtools } from "nanoeffects/trace";
 
-reduxDevtools({ name: "app", depth: 0 }); // one line per handler call
-reduxDevtools({ name: "app", starts: true, depth: Infinity }); // everything
+// debugging a race: which calls did a policy cancel or drop?
+reduxDevtools({ name: "app", policies: ["cancel", "drop"] });
+
+// every stage of every policy, one function for the choice
+reduxDevtools({
+  name: "app",
+  policies: ({ effect, phase }) => effect === "latest" && phase !== "start",
+});
+
+// the old log: every stage, and the effects below the handlers
+reduxDevtools({ name: "app", policies: true, depth: 1 });
 ```
 
+With two quick `search` emits and a `latest` handler, the default list is `search`, `search`. With `policies: true` it adds the `latest` stages of each call, for example `search/latest/cancel` for the first one.
+
 ### Write your own logger
 
 ```ts

package/llms-full.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; `usePolicy`; needs React), `nanoeffects/trace`, `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; `usePolicy`; needs React), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ---
@@ -566,7 +566,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `nanoeffects/observable` | `createObserve` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) |
-| `nanoeffects/trace` | `createTracer` and the loggers |
+| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |
 
 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.
 
@@ -680,6 +680,7 @@ Add one of these when you meet its need. None of them is required.
 | [`signalPlugin`](#tie-an-emit-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
 | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) | `on` that listens to a group of events which a function picks. | `nanoeffects/match` | The same bus, typed with the new overloads |
 | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) | A callback that emits an action, to give to a state manager. | `nanoeffects/actions` | The same bus, with `emitter` |
+| [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) | `traceId` and `traceGroupId` for a trace: the root of an emitter, a flow, a named listener. | `nanoeffects/trace` | The same bus |
 | [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) | A React hook that emits when a value of a component changes. | `nanoeffects/react` | The same bus, with `useEmitter` |
 | [`devPlugin`](#find-leaks-while-you-develop-devplugin) | Warnings about listeners that pile up, and messages about modules, while you develop. | `nanoeffects/dev` | A function that disconnects it |
 
@@ -723,6 +724,20 @@ bus.emit(getUser("1"), { signal: controller.signal }); // runs the command
 controller.abort(); // ctx.signal of the handler aborts with it
 ```
 
+### Name the origin and the flow of a trace: `tracePlugin`
+
+With a tracer on the bus, the plugin lets a trace say which subscription began a chain (`traceId` of `useEmitter` and `bus.emitter`), follow one flow by a `traceGroupId`, and show which listener ran (`bus.on(event, handler, { traceId })`). Without the plugin the options are ignored. More in [Tracing](tracing.md#show-which-subscription-began-a-chain).
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// tracePlugin — names the roots, groups and listeners of the trace
+const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+
+bus.on("name/changed", saveName, { traceId: "saveNotifier" }); // a listener you can find in the log
+```
+
 ### Listen to a group of events: `matchPlugin`
 
 `on`, `once` and `off` take a function that picks the events, such as every `user/*` event. A type guard narrows the payload. The subscription listens to every event, so for a few known events `on(creator, handler)` is cheaper. More in the [Guide](guide.md#pick-events-with-a-function).
@@ -759,7 +774,7 @@ $name.listen(bus.emitter(nameChanged)); // every change of $name emits nameChang
 
 ### Tell the bus when a React value changes: `reactPlugin`
 
-`useEmitter(event, value)` emits after a render commits with a new value. It does not emit on mount, and not twice under StrictMode. It needs React 18 or newer. More in [Stores](stores.md#react-sharing-a-value-across-components).
+`useEmitter(event, value, options?)` emits after a render commits with a new value. It does not emit on mount, and not twice under StrictMode. The options are `{ equals, traceId, traceGroupId }`; the last two name the emit in the [trace](tracing.md#show-which-subscription-began-a-chain). It needs React 18 or newer. More in [Stores](stores.md#react-sharing-a-value-across-components).
 
 ```jsx
 import { useState } from "react";
@@ -2126,6 +2141,10 @@ String event names (`"user/requested"`) work the same. Use your usual RTK action
 
 The only option is `filter`, which keeps rejected actions away from the bus. Options of the bus (`onError`, `context`, `trace`) go to `createBus`. Use one bus for one store. Values that are not plain actions (thunks) go through untouched. Nothing here depends on the `redux` package at runtime.
 
+### Show which dispatch began a chain
+
+With a tracer and `tracePlugin` on the bus, each dispatched action reaches the bus from a root task of the trace. Name it with `traceId`, and put the flow in a group with `traceGroupId`: `createEffectsMiddleware(bus, { traceId: "store", traceGroupId: "checkout" })`. Without a `traceId` the root has the type of the action. Without the plugin the options are ignored. More in [Tracing](tracing.md#show-which-subscription-began-a-chain).
+
 ### Type `ctx.store` (optional)
 
 Only if you want TypeScript to know `store` on handlers. **Skip this in JavaScript** — the middleware already puts `store` on the task at runtime. These lines do not connect the store across the app.
@@ -2504,7 +2523,7 @@ export function Results() {
 Two limits to know:
 
 - **All consumers re-render** on any change of the context value. Split it into two contexts (`query` and `items`) if that is slow.
-- **A new object counts as a change.** For a value that is rebuilt with the same content, pass a third argument that says when two values are the same: `useEmitter(profileChanged, profile, (previous, next) => previous.id === next.id)`.
+- **A new object counts as a change.** For a value that is rebuilt with the same content, pass `equals` in the options, the third argument, to say when two values are the same: `useEmitter(profileChanged, profile, { equals: (previous, next) => previous.id === next.id })`. The same object takes `traceId` and `traceGroupId`, which name the subscription and the flow in the [trace](tracing.md#show-which-subscription-began-a-chain).
 
 `useEmitter` emits after the render, not at the moment of `setQuery`. To emit on every call, even with the same value, call an emitter from the event handler (`bus.emitter(action)`, see [Zustand](#zustand)) instead.
 
@@ -3308,7 +3327,7 @@ When several places set the same field, the strongest one wins:
 | 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. A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+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
 
@@ -3583,6 +3602,8 @@ Things to know:
 - On a class that `extendBus` did not make, a decorator does nothing.
 - Both the decorators of the language and `experimentalDecorators` work. Your compiler has to support the one you use: TypeScript 5 or newer for the first, and the `experimentalDecorators` option for the second.
 
+Name a method for the [trace](tracing.md#name-a-listener) with `{ traceId }`, as the second argument or, after a wrapper, the third: `@On(queryChanged, { traceId: "searcher" })` or `@On(queryChanged, latest, { traceId: "searcher" })`. It needs `tracePlugin` on the bus and is ignored without it.
+
 ## Decorate the class with `@WithBus`
 
 `@WithBus(bus)` does what `extendBus(bus, Base)` does, as a class decorator. `@WithBus()` makes a bus for the class.
@@ -4540,12 +4561,14 @@ Each `TraceEvent` has:
 | Field | Meaning |
 | ----- | ------- |
 | `id` | Unique task id within the bus |
-| `parent` | Id of the task that started this one (absent for handler tasks) |
+| `parentId` | Id of the task that started this one (absent for handler tasks) |
+| `rootId` | Id of the root task of the chain; absent on the root itself, and it is the same through a listener that reports nothing |
 | `type` | Event type the task works on |
-| `effect` | `latest`, `debounce`, `throttle`, `leading`, `run`, `all`, `race`, … |
+| `effect` | `latest`, `debounce`, `throttle`, `leading`, `run`, `all`, `race`, …; `emit` for the emit event of `tracePlugin` |
 | `phase` | `start`, `done`, `error`, `cancel`, or `drop` |
 | `payload` | Event payload |
 | `error` | Thrown value, only for `error` |
+| `traceGroupId` | The flow of the task, when it or a task above has one |
 
 Phases:
 
@@ -4570,6 +4593,150 @@ bus.on("load", async (id, ctx) => {
 });
 ```
 
+## Show every emit
+
+**When.** You want the log to say what was emitted, also when nothing listens or the listener is a plain function. Without it the trace has only the tasks that report: a policy (`latest`, ...) or a `ctx.run`.
+
+`tracePlugin` reports one event for each emit, with `effect: "emit"` and `phase: "done"`, before the handlers run. `type` is the event name and `payload` is what was emitted. A `ctx.emit` has the task that emits as its `parentId`.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+export const bus = createBus({ trace: createTracer(consoleLogger()) })
+  .use(tracePlugin()); // tracePlugin: reports each emit as an event
+```
+
+```js
+import { bus } from "./bus";
+
+bus.emit("search", "nano"); // logs: search · emit done
+```
+
+The event changes nothing else: the other tasks keep their `parentId`, `rootId` and `traceGroupId`. Without the plugin the trace has no `emit` events.
+
+- **What counts as an emit.** Every `bus.emit`, also the ones a library makes for you: a job emits its `pending` and `success` (or `fail`, `cancel`), so one call of a job is several `emit` events.
+- **Cost.** One small task per emit, about 60 ns on a bus that already has a tracer (a bus with a tracer and no plugin: about 250 ns more than a bus without one). `sample` and `filter` of `createTracer` cut it in the log, not in the work.
+
+## Show which subscription began a chain
+
+**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of commands and retries.
+
+**When.** The bus has a tracer and the project has several `useEmitter` or `bus.emitter` calls. The names come from `tracePlugin`: use it on the bus, or the `traceId` is ignored.
+
+Give each one a `traceId`. When the bus has a tracer, the emit is made from a root task with that `traceId` as its `type` and `run` as its effect. What the event starts is below it. Without a tracer nothing changes.
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// createTracer: reports every task phase to the console
+const bus = createBus({ trace: createTracer(consoleLogger()) })
+  .use(tracePlugin()) // tracePlugin: makes the root task that traceId names
+  .use(emitterPlugin());
+
+const cartChanged = createAction("cart/changed");
+
+// emitter: a callback for a store; traceId names it in the trace
+const emitCartChanged = bus.emitter(cartChanged, { traceId: "cartStore" });
+```
+
+In a component, the same option goes in the options of the hook: `useEmitter(nameChanged, name, { traceId: "Profile" })`. In the console:
+
+```
+[nanoeffects] Profile · run start
+[nanoeffects]   user/save · command start
+[nanoeffects]   user/save · command done
+[nanoeffects] Profile · run done
+```
+
+A `traceId` is a string you choose and keep stable: the name of the component or of the store. Without one the root has the type of the event.
+
+Two things to know:
+
+- **`sample` sees the `traceId`.** The root of an emitter is a task like any other, so a `sample` function gets `{ type, payload }` with the `traceId` as the `type` and the emitted action as the `payload`. A function that matches on the type of the event, such as `event.type === "search"`, does not pick a root that has another `traceId`; match the `traceId`, or the `payload.type`.
+- **Inside a handler, emit with `ctx.emit`.** `ctx.emit` keeps the chain: what it starts is below the handler. A plain `bus.emit` inside a handler starts a new root with no parent and no `rootId`, so the trace loses the link.
+
+Every event of a task below another one has `rootId`, the id of the root of the chain, also when a listener, which reports nothing, stands in between. `parentId` is the task directly above, which can be such a listener.
+
+## Follow one flow with a traceGroupId
+
+**Problem.** A flow such as a checkout has several roots (a click, a timer, a store) and many branches. Parent ids give a tree, but you want to filter the log by the flow.
+
+**When.** One business flow runs through several commands, and you read the log by flow.
+
+Give the flow a `traceGroupId` in the scope of the command, the job or the action that starts it. Every task that it starts through `ctx.emit` or `ctx.run` has the same `traceGroupId`, and so does every trace event of those tasks. A task that declares its own `traceGroupId` uses it for itself and for what it starts.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// tracePlugin: reads traceGroupId from the scope of a call
+const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+
+// the scope names the flow; traceGroupId is for the tracer, not a field of ctx
+const pay = createCommand("checkout/pay", async () => {}, {
+  traceGroupId: "checkout",
+});
+```
+
+```
+[nanoeffects] [checkout] checkout/pay · command start
+```
+
+The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", traceGroupId: "checkout" })`. `traceGroupId` works without `scopePlugin`, and needs `tracePlugin`.
+
+## Name a listener
+
+**Problem.** The log shows what started a chain and what it started, but a listener of an event reports nothing, so you cannot tell which of several listeners ran.
+
+**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`.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+const bus = createBus({ trace: createTracer(consoleLogger()) }).use(tracePlugin());
+
+// traceId: the name of this listener in the trace
+bus.on("name/changed", saveName, { traceId: "saveNotifier" });
+bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
+```
+
+```
+[nanoeffects] saveNotifier · run start
+[nanoeffects]   user/save · command start
+[nanoeffects] saveNotifier · run done
+```
+
+## 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.
+
+The names work wherever an event or a listener is made:
+
+| Where | How to name it |
+| ----- | -------------- |
+| `useEmitter` and `bus.emitter` | `{ traceId, traceGroupId }` in the options |
+| A Redux dispatch | `createEffectsMiddleware(bus, { traceId, traceGroupId })` |
+| A listener, `bus.on` and `bus.once` | `{ traceId }` as the third argument |
+| A listener of a module or of an instance of `extendBus` | the same third argument of its `on` and `once` |
+| A method with `@On` or `@Once` | `{ traceId }` in the decorator |
+| A command, a job or an action | `traceGroupId` in its scope |
+
+## Turn the names off
+
+`tracePlugin` is optional, and none of it changes how your code runs:
+
+- **Without the plugin**, or on a bus without a tracer, `traceId` and `traceGroupId` are ignored. Handlers run as they are, with the same results, errors and rejections, and `onError` sees the same errors.
+- **The types are the same** with and without the plugin, so you can use it only in development: `if (isDev) bus.use(tracePlugin())` compiles in both builds.
+- **A `traceGroupId` in a scope** is never put on `ctx`.
+
 ## Use built-in loggers
 
 A logger is `(event) => void`. `createTracer` takes one logger or an array. A logger that throws is reported to `console.error` and never breaks the task or the other loggers.
@@ -4585,7 +4752,7 @@ const bus = createBus({
 
 | Logger | What it does |
 | ------ | ------------ |
-| `reduxDevtools()` | Sends tasks to Redux DevTools as `type/effect/phase`; state is `{ running }` |
+| `reduxDevtools()` | Sends the emits to Redux DevTools, and with `policies` the stages of the handlers as `type/effect/phase`; state is `{ running }` |
 | `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`, for tests |
@@ -4608,19 +4775,49 @@ createTracer(logger, {
 
 Read-only (the bus owns no state, so there is no time travel). Does nothing when the extension is not installed. Has its own instance in the DevTools picker, apart from your store.
 
-Quiet by default:
+Quiet by default, so you see what happened before you see how:
+
+- **One action per emit**, named after the event (`search`), with its payload. This needs `bus.use(tracePlugin())` (see [Show every emit](#show-every-emit)); without it the default log is empty, and the logger prints one `console.warn` when the first handler task ends with no emit before it.
+- **A failed handler** is sent as `search/latest/error`.
+- Nothing else: no start, no `done`, no policy stages, no effects.
 
-- **A task is one action**, sent when it ends (`done`, `error`, `cancel`, `drop`). Running tasks are in `{ running }`. `starts: true` also sends every start.
-- **Only the top is shown**: handler tasks and the effects they start. Attempts and starters under them are hidden. `depth: 0` — handlers only; `depth: 3` — more; `Infinity` — everything.
+Turn on more when you need it:
+
+- `policies` — the stages of the handler tasks, as `event/policy/phase`. `true` shows every phase, a list shows those phases, a function gets `{ effect, phase }`.
+- `starts: true` — also send the start of each shown task. Running tasks are in the state `{ running }`.
+- `depth: 1` — also the effects a handler starts (`retry`, `timeout`); `depth: Infinity` — everything below.
 - `maxAge: 200` — how many actions DevTools keeps (its default is 50).
 
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, reduxDevtools, tracePlugin } from "nanoeffects/trace";
+
+// reduxDevtools: sends the trace to the extension; it has the emits and the failures only
+const logger = reduxDevtools({ name: "app" });
+
+export const bus = createBus({ trace: createTracer(logger) })
+  .use(tracePlugin()); // tracePlugin: makes the emit events
+```
+
 ```js
 import { reduxDevtools } from "nanoeffects/trace";
 
-reduxDevtools({ name: "app", depth: 0 }); // one line per handler call
-reduxDevtools({ name: "app", starts: true, depth: Infinity }); // everything
+// debugging a race: which calls did a policy cancel or drop?
+reduxDevtools({ name: "app", policies: ["cancel", "drop"] });
+
+// every stage of every policy, one function for the choice
+reduxDevtools({
+  name: "app",
+  policies: ({ effect, phase }) => effect === "latest" && phase !== "start",
+});
+
+// the old log: every stage, and the effects below the handlers
+reduxDevtools({ name: "app", policies: true, depth: 1 });
 ```
 
+With two quick `search` emits and a `latest` handler, the default list is `search`, `search`. With `policies: true` it adds the `latest` stages of each call, for example `search/latest/cancel` for the first one.
+
 ### Write your own logger
 
 ```ts

package/llms.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; `usePolicy`; needs React), `nanoeffects/trace`, `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter`; `usePolicy`; needs React), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
 - `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
 
 ## Start here

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -201,7 +201,7 @@
 		{
 			"name": "actions (all)",
 			"path": "dist/actions.js",
-			"limit": "2.86 kB"
+			"limit": "2.87 kB"
 		},
 		{
 			"name": "match (plugin)",
@@ -239,7 +239,7 @@
 			"ignore": [
 				"react"
 			],
-			"limit": "1.15 kB"
+			"limit": "1.18 kB"
 		},
 		{
 			"name": "dev",

package/dist/bus-CkTHUAvq.js

@@ -1 +0,0 @@
-import{n as e}from"./onAbort-BgMfspK4.js";import{a as t,n,r}from"./context-COgyNlrC.js";import{n as i}from"./promise-CSLpzwSR.js";import{n as a,t as o}from"./event-0RIBGYqS.js";const s=`*`,c=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{for(let t of Reflect.ownKeys(e))delete e[t];for(let e of Reflect.ownKeys(t))delete t[e]}}},l=Symbol(),u=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,l,{value:e,enumerable:!1}),r},d=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&l in e)return e[l]},f=(e,t,n)=>Reflect.apply(e,null,[t,n]),p=(s={})=>{let l=c(),u=(e,t)=>l.add(o(e),t),p=(e,t)=>{let n=u(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(o(e),t)},h=(t,a)=>{let{onError:o}=s,{ctx:c}=n({event:a,bus:g,tracer:s.trace,parent:{ref:r()}});if(!o){t(a.payload,c);return}let l=t=>{try{o(t,a)}catch(t){e(`onError failed`,t)}};try{let e=t(a.payload,c);i(e)&&Promise.resolve(e).catch(l)}catch(e){l(e)}},g={on:u,once:p,off:m,emit:(e,i)=>{let c=o(e),u=a(e,i),p={type:c,payload:u},m=d(e),_=[...l.get(c),...l.get(`*`)];_.length===0&&!m&&s.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:e}=n({event:p,bus:g,tracer:s.trace,parent:{ref:r()}}),i=g.commands?.run??f;return t(e,`command`,()=>i(m,u,e))}},use:e=>e(g),ctx:s.context,trace:s.trace};return g};export{s as a,u as i,d as n,p as r,l as t};

package/dist/context-COgyNlrC.js

@@ -1 +0,0 @@
-import{t as e}from"./onAbort-BgMfspK4.js";const t=t=>{let n=new AbortController;return{controller:n,unlink:e({signal:t},e=>n.abort(e))}},n=Symbol(),r=typeof __NANOEFFECTS_TRACE__>`u`||__NANOEFFECTS_TRACE__,i=/* @__PURE__ */ new WeakMap;let a;const o=()=>a,s=()=>{},c=(e,t,n,a)=>{let o=r&&i.get(e);o&&o.tracer.report(o.ref,t,n,a)},l=(e,t)=>{let n=r&&i.get(e);return n?n.tracer.settler(n.ref,t):s},u=(e,t,n)=>{let a=r&&i.get(e);return a?a.tracer.run(a.ref,t,e.signal,n):n()},d=(e,t)=>typeof e==`function`?e(t):e,f=({event:o,bus:c,tracer:l,parent:p})=>{let{controller:m,unlink:h}=t(p?.signal),{signal:g}=m,_=r&&l?{tracer:l,ref:l.task(o,p?.ref)}:void 0,v=(...e)=>{if(g.aborted&&!x[n])return;let t=c?.emit,r=a;a=_?.ref;try{return t?.(...e)}finally{a=r}},y=(...t)=>{if(g.aborted)return s;let n=c?.on,r=n?.(...t);if(!r)return s;let i=e({signal:g},r);return()=>{i(),r()}},b=async(e,...t)=>{g.throwIfAborted();let n=t[0],r=f({event:{type:o.type,payload:n},bus:c,tracer:l,parent:{signal:g,ref:_?.ref}});try{return await u(r.ctx,`run`,()=>e(n,r.ctx))}finally{r.unlink()}},x={...d(c?.ctx,o),type:o.type,payload:o.payload,signal:g,abort:e=>m.abort(e),emit:v,on:y,off:c?.off??s,run:b};return c?.addContext?.(x),_&&i.set(x,_),{ctx:x,unlink:h}},p=(e,t)=>{let n=r?i.get(e):void 0;return f({event:{type:t??e.type??``,payload:e.payload},bus:{emit:e.emit,on:e.on,off:e.off,ctx:e},tracer:n?.tracer,parent:{signal:e.signal,ref:n?.ref}})};export{u as a,p as i,f as n,c as o,o as r,n as s,l as t};

package/dist/notrace/bus-BmCTo8BG.js

@@ -1 +0,0 @@
-import{a as e,l as t,n,r}from"./context-yYU3_9lq.js";import{n as i}from"./promise-CSLpzwSR.js";const a=e=>typeof e==`string`?e:e.type,o=(e,t)=>typeof e==`object`?e.payload:t,s=`*`,c=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{for(let t of Reflect.ownKeys(e))delete e[t];for(let e of Reflect.ownKeys(t))delete t[e]}}},l=Symbol(),u=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,l,{value:e,enumerable:!1}),r},d=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&l in e)return e[l]},f=(e,t,n)=>Reflect.apply(e,null,[t,n]),p=(s={})=>{let l=c(),u=(e,t)=>l.add(a(e),t),p=(e,t)=>{let n=u(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(a(e),t)},h=(e,a)=>{let{onError:o}=s,{ctx:c}=n({event:a,bus:g,tracer:s.trace,parent:{ref:r()}});if(!o){e(a.payload,c);return}let l=e=>{try{o(e,a)}catch(e){t(`onError failed`,e)}};try{let t=e(a.payload,c);i(t)&&Promise.resolve(t).catch(l)}catch(e){l(e)}},g={on:u,once:p,off:m,emit:(t,i)=>{let c=a(t),u=o(t,i),p={type:c,payload:u},m=d(t),_=[...l.get(c),...l.get(`*`)];_.length===0&&!m&&s.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:t}=n({event:p,bus:g,tracer:s.trace,parent:{ref:r()}}),i=g.commands?.run??f;return e(t,`command`,()=>i(m,u,t))}},use:e=>e(g),ctx:s.context,trace:s.trace};return g};export{a,s as i,p as n,u as r,l as t};

package/dist/onAbort-BgMfspK4.js

@@ -1 +0,0 @@
-const e=(e,t)=>{globalThis.console?.error(`[nanoeffects] ${e}`,t)},t=()=>{},n=/* @__PURE__ */ new WeakMap,r=t=>{let r=n.get(t);if(r)return r;let i=/* @__PURE__ */ new Set;return n.set(t,i),t.addEventListener(`abort`,()=>{let n=[...i];i.clear();for(let{fn:r}of n)try{r(t.reason)}catch(t){e(`abort callback failed`,t)}},{once:!0}),i},i=(e,n)=>{let{signal:i}=e;if(!i)return t;if(i.aborted)return n(i.reason),t;let a=r(i),o={fn:n};return a.add(o),()=>{a.delete(o)}};export{e as n,i as t};