nanoeffects 0.28.0 → 0.29.0

package/docs/query-libraries.md

@@ -1,8 +1,21 @@
-# Use nanoeffects with React Query and SWR
+# Use nanoeffects with React Query, SWR and RTK Query
 
-Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one action that both libraries call.
+Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query), [SWR](https://swr.vercel.app) or [RTK Query](https://redux-toolkit.js.org/rtk-query/overview) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one action that the libraries call, then three recipes for the parts around it: a client that stops with the request, a live stream into the cache, and a refetch on a bus event.
 
-You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
+You need a React project, `nanoeffects`, and one of the libraries. `api` below is your own client: replace it with your requests.
+
+## On this page
+
+- [Decide who owns what](#decide-who-owns-what)
+- [Make the action](#make-the-action)
+- [Call it from React Query](#call-it-from-react-query)
+- [Call it from SWR](#call-it-from-swr)
+- [Let the bus know the result](#let-the-bus-know-the-result)
+- [Call it from RTK Query](#call-it-from-rtk-query)
+- [Give the client its signal once](#give-the-client-its-signal-once)
+- [Push a live stream into the cache](#push-a-live-stream-into-the-cache)
+- [Refetch queries when the bus says so](#refetch-queries-when-the-bus-says-so)
+- [Know the limits](#know-the-limits)
 
 ## Decide who owns what
 
@@ -63,7 +76,7 @@ import { getUser } from "./user";
 export function Profile({ id }) {
   const { isLoading, data, error } = useQuery({
     queryKey: ["user", id],
-    // emit — runs the command; { signal } ties its task to the signal of React Query
+    // emit — runs the action; { signal } ties its task to the signal of React Query
     queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
   });
 
@@ -115,9 +128,264 @@ export const userLoaded = createAction("user/loaded");
 
 Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the action with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job).
 
+## Call it from RTK Query
+
+<!-- docs-check: new -->
+
+RTK Query gives the `queryFn` of an endpoint a `signal` in its second argument, so the call is the same as with React Query: pass it to `emit`. This page does not set up the store; see [Stores](stores.md) for that.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — lets emit take { signal }
+export const bus = createBus().use(signalPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction with a handler — emit returns what the handler returns
+export const getUser = createAction("user/get", (id, { signal }) =>
+  api.getUser(id, { signal }),
+);
+```
+
+```js
+// api-slice.js
+import { createApi, fakeBaseQuery } from "@reduxjs/toolkit/query/react";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export const userApi = createApi({
+  reducerPath: "userApi",
+  baseQuery: fakeBaseQuery(), // RTK Query — every endpoint brings its own queryFn
+  endpoints: (build) => ({
+    getUser: build.query({
+      // emit — runs the action; { signal } ties its task to the request of RTK Query
+      queryFn: async (id, { signal }) => {
+        const user = await bus.emit(getUser(id), { signal });
+        return { data: user };
+      },
+    }),
+  }),
+});
+```
+
+## Give the client its signal once
+
+<!-- docs-check: new -->
+
+Problem: the action passes `signal` to every call of `api`, and one forgotten `{ signal }` leaves a request running after the query is gone. `fromSignal` builds the client from the signal of each task, so the handler cannot forget it. Use it when many actions share one client. A single action is simpler as it is in [Make the action](#make-the-action).
+
+`fromSignal` marks a field of `contextPlugin`. The client is made when a handler first reads `ctx.http`, from the `ctx.signal` of that task. More in [Context fields](context.md#build-a-field-from-the-signal-of-each-task).
+
+```js
+// bus.js
+import axios from "axios";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal, signalPlugin } from "nanoeffects/signal";
+
+// fromSignal — http is a new axios client for each task, bound to the signal of that task
+const http = fromSignal((signal) => axios.create({ baseURL: "/api", signal }));
+
+// contextPlugin — every handler gets ctx.http
+const context = contextPlugin({ http });
+
+// signalPlugin — emit takes { signal }, so the signal of the query reaches the task
+export const bus = createBus().use(signalPlugin()).use(context);
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// the handler never sees a signal: ctx.http stops when the task aborts
+export const getUser = createAction("user/get", async (id, { http }) => {
+  const response = await http.get(`/users/${id}`);
+  return response.data;
+});
+```
+
+```jsx
+// Profile.jsx
+import { useQuery } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export function Profile({ id }) {
+  const { data } = useQuery({
+    queryKey: ["user", id],
+    // emit — the signal of React Query aborts the task, and with it the request of ctx.http
+    queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
+  });
+
+  return <p>{data?.name}</p>;
+}
+```
+
+## Push a live stream into the cache
+
+<!-- docs-check: new -->
+
+Problem: prices arrive from a socket, and the component should show the newest one without a refetch. The socket code emits an event on the bus; the component reads those events with `events` and writes each into the cache. Both libraries have an entry point for pushed data: `setQueryData` in React Query and `useSWRSubscription` in SWR.
+
+`events` gives the payloads to a `for await` loop. `buffer: 1` keeps only the newest price while a write is running. The abort in the cleanup ends the loop and removes the listener. More in [Read an event with a `for await` loop](observable.md#read-an-event-with-a-for-await-loop).
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the socket code and the components share
+export const bus = createBus();
+```
+
+```js
+// prices.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the event the socket code emits for every new price
+export const priceChanged = createAction("price/changed");
+```
+
+```jsx
+// Price.jsx
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { events } from "nanoeffects/observable";
+import { bus } from "./bus";
+import { priceChanged } from "./prices";
+
+export function Price({ symbol }) {
+  const queryClient = useQueryClient();
+  const { data } = useQuery({
+    queryKey: ["price", symbol],
+    queryFn: () => api.getPrice(symbol), // the first value; the stream keeps it fresh
+  });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    // events — the newest price event, one at a time
+    const prices = events(bus, priceChanged, {
+      signal: controller.signal,
+      buffer: 1,
+    });
+
+    async function follow() {
+      for await (const price of prices) {
+        if (price.symbol === symbol) {
+          queryClient.setQueryData(["price", symbol], price.value); // write into the cache
+        }
+      }
+    }
+
+    follow().catch((error) => {
+      if (!controller.signal.aborted) throw error; // the abort ends the loop; anything else is a bug
+    });
+
+    return () => controller.abort(); // the component left: the loop ends, the listener goes
+  }, [queryClient, symbol]);
+
+  return <p>{data}</p>;
+}
+```
+
+SWR does the same with `useSWRSubscription` from `swr/subscription`. Its subscribe function gets `next` to push a value and returns the cleanup:
+
+```jsx
+// Price.jsx
+import useSWRSubscription from "swr/subscription";
+import { events } from "nanoeffects/observable";
+import { bus } from "./bus";
+import { priceChanged } from "./prices";
+
+export function Price({ symbol }) {
+  const { data } = useSWRSubscription(["price", symbol], (_key, { next }) => {
+    const controller = new AbortController();
+    // events — the newest price event, one at a time
+    const prices = events(bus, priceChanged, {
+      signal: controller.signal,
+      buffer: 1,
+    });
+
+    async function follow() {
+      for await (const price of prices) {
+        if (price.symbol === symbol) {
+          next(null, price.value); // SWR — push the value to the hook
+        }
+      }
+    }
+
+    follow().catch((error) => {
+      if (!controller.signal.aborted) next(error);
+    });
+
+    return () => controller.abort(); // SWR calls this when the last component of the key leaves
+  });
+
+  return <p>{data}</p>;
+}
+```
+
+## Refetch queries when the bus says so
+
+<!-- docs-check: new -->
+
+Problem: a save in one part of the app should refresh the lists in another. The save emits an event, and the component that owns the queries listens for it. One `AbortController` ends every listener of the component, instead of one `unbind` for each. For a single listener, `return bus.on(…)` from the effect is shorter.
+
+This needs `signalPlugin`, because `{ signal }` in the options of `on` is read by the plugin. Without it the listeners stay after the component leaves.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — on takes { signal } and removes the listener when it aborts
+export const bus = createBus().use(signalPlugin());
+```
+
+```js
+// user-events.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — events the save code emits
+export const userSaved = createAction("user/saved");
+export const userDeleted = createAction("user/deleted");
+```
+
+```jsx
+// UserList.jsx
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { userDeleted, userSaved } from "./user-events";
+
+export function UserList() {
+  const queryClient = useQueryClient();
+  const { data } = useQuery({ queryKey: ["users"], queryFn: () => api.listUsers() });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const { signal } = controller;
+    const refresh = () => queryClient.invalidateQueries({ queryKey: ["users"] });
+
+    // on with { signal } — both listeners go when the component leaves
+    bus.on(userSaved, refresh, { signal });
+    bus.on(userDeleted, refresh, { signal });
+
+    return () => controller.abort();
+  }, [queryClient]);
+
+  return <ul>{data?.map((user) => <li key={user.id}>{user.name}</li>)}</ul>;
+}
+```
+
 ## Know the limits
 
-- **Without the plugin, `{ signal }` is ignored.** The action runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
+- **Without the plugin, `{ signal }` is ignored,** in `emit` and in the options of `on`. The action runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
 - **Only the call forms take it.** `bus.emit(getUser(id), { signal })` works; `bus.emit("user/get", id, { signal })` does not.
 - **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Actions that fetch are async, so this only matters for a sync handler that sets up a callback.
 - **Give each request its own signal for an event.** For an action with a handler or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.

package/docs/react.md

@@ -4,6 +4,16 @@ Use this page when a React screen starts requests on user input and you need the
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
+## On this page
+
+- [See what goes wrong without a bus](#see-what-goes-wrong-without-a-bus)
+- [Wire the bus once](#wire-the-bus-once)
+- [Connect the form](#connect-the-form)
+- [Stop running work when the form closes](#stop-running-work-when-the-form-closes)
+- [Show the last value of an event as state](#show-the-last-value-of-an-event-as-state)
+- [Keep a debounced handler between renders](#keep-a-debounced-handler-between-renders)
+- [Where to go next](#where-to-go-next)
+
 ## See what goes wrong without a bus
 
 A registration form has three problems that `useEffect` and `fetch` leave to you:
@@ -75,7 +85,7 @@ The handlers know nothing about React. A test can emit `username/typed` and read
 
 <!-- docs-check: continue -->
 
-The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount.
+The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount. If the component already holds an `AbortSignal`, `bus.on(event, handler, { signal })` ends the listener with it; see [`signalPlugin`](plugins.md#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin).
 
 ```jsx
 // SignUpForm.jsx
@@ -276,4 +286,4 @@ export const Search = ({ wait }) => {
 - A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
 - `retry`, `timeout` and the other effects: [Effects](effects.md).
 - A state library instead of `useState`: [Stores](stores.md).
-- React Query or SWR instead of your own state: [Use nanoeffects with React Query and SWR](query-libraries.md).
+- React Query or SWR instead of your own state: [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).

package/docs/scope.md

@@ -6,6 +6,18 @@ A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`,
 
 You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
 
+## On this page
+
+- [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 (optional)](#type-the-fields-optional)
+- [Limits](#limits)
+
 ## Turn scopes on
 
 Scopes are a plugin, so a bus that does not use them pays nothing.
@@ -36,7 +48,7 @@ import { createAction } from "nanoeffects/actions";
 export const getUser = createAction(
   "user/get",
   (id, { api, cache }) => {
-    // api and cache are on ctx for this command only
+    // api and cache are on ctx for this action only
     return cache.get(id) ?? api.getUser(id);
   },
   { api, cache: new Map() },
@@ -185,7 +197,7 @@ 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, command or job |
+| 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` |
 

package/docs/semantics.md

@@ -2,6 +2,16 @@
 
 Guarantees and sharp edges. Read when something surprises you; not required to start.
 
+## Five rules to know first
+
+1. A handler is `(payload, ctx)`. Use `ctx.signal`, `ctx.emit` and `ctx.on`; the rest of `ctx` is optional.
+2. Pass `ctx.signal` to what the handler calls (`fetch`, a client), so an abort stops the work.
+3. An aborted task delivers no result and emits nothing.
+4. `emit` is synchronous: the first handler error is thrown, unless `onError` is set.
+5. Rejections of async handlers are not handled without `onError`.
+
+Details of each rule and the rest:
+
 - **An aborted task delivers no result.** If the task aborts before a promise settles, the promise rejects with the abort reason, even if the value was just produced in the same tick. `latest`, `debounce`, `all`, `race`, `take`, and the rest follow this rule.
 - **`emit` is a plain, synchronous loop** (see [Errors](errors.md)). A `ctx.emit` inside a handler is the same call: without `onError`, an error of a nested handler is thrown into the handler that emitted; with `onError` it goes there and `ctx.emit` does not throw.
 - **Rejections of async handlers** are not handled for you. Without `onError` they are unhandled rejections, which end a Node process by default. Use `onError` for async handlers.

package/docs/server.md

@@ -37,7 +37,7 @@ The action loads a user. It tries the request up to three times, and gives up on
 import { createAction } from "nanoeffects/actions";
 import { retry, timeout } from "nanoeffects/effects";
 
-// createAction — a command with a handler: emit returns what the handler returns
+// createAction — an action with a handler: emit returns what the handler returns
 export const getUser = createAction("user/get", async (id, ctx) => {
   // one try: the request, with the signal of timeout so it can stop it
   const load = ({ signal }) => api.getUser(id, { signal });
@@ -78,7 +78,7 @@ app.get("/users/:id", async (request, reply) => {
   });
 
   try {
-    // emit with { signal } — aborting the controller aborts the command: timeout, retry and the request
+    // emit with { signal } — aborting the controller aborts the action: timeout, retry and the request
     const call = getUser(request.params.id);
     return await bus.emit(call, { signal: controller.signal });
   } catch (error) {
@@ -131,7 +131,7 @@ import { createAction } from "nanoeffects/actions";
 import { poll } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
-// createAction — a command with a handler
+// createAction — an action with a handler
 // latest — a new subscription stops the old one; key — but only the old one of the same socket
 export const watchPrices = createAction(
   "prices/watch",

package/docs/stability.md

@@ -72,8 +72,8 @@ import { race, retry } from "nanoeffects/effects";
 const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
-  // with ctx: you pass the context, the function gets the signal
-  const user = await retry(ctx, ({ signal }) => fetchUser(id, { signal }), { times: 3 });
+  // with ctx: you pass the context, and the function takes the signal from it
+  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 3 });
 
   // as a starter: a group (race, all, allSettled, timeout) calls it with its child
   const result = await race(ctx, {

package/docs/tracing.md

@@ -4,6 +4,22 @@ Find out what your app did and why: which events were emitted, which calls a pol
 
 Tracing is optional. A bus works the same without it, and it costs almost nothing until you turn it on. If you only want to see what happens while you develop, jump to [Show every emit](#show-every-emit) and [Configure Redux DevTools](#configure-redux-devtools); the rest of the page is for apps that need to follow a flow or turn tracing off in a build.
 
+## On this page
+
+- [Attach a tracer](#attach-a-tracer)
+- [Show every emit](#show-every-emit)
+- [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)
+- [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)
+  - [Configure Redux DevTools](#configure-redux-devtools)
+  - [Write your own logger](#write-your-own-logger)
+- [Drop tracing from a build](#drop-tracing-from-a-build)
+
 ## Attach a tracer
 
 Pass `trace` to `createBus`. Make it with `createTracer` from `nanoeffects/trace`, which takes a logger (a function) or an array of them. The tracing code lives in that entry, so a bus without `trace` does not carry it.
@@ -86,7 +102,7 @@ The event changes nothing else: the other tasks keep their `parentId`, `rootId`
 
 ## 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.
+**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 actions 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.
 
@@ -114,8 +130,8 @@ In a component, the same option goes in the options of the hook: `useEmitter(nam
 
 ```
 [nanoeffects] Profile · run start
-[nanoeffects]   user/save · command start
-[nanoeffects]   user/save · command done
+[nanoeffects]   user/save · action start
+[nanoeffects]   user/save · action done
 [nanoeffects] Profile · run done
 ```
 
@@ -155,7 +171,7 @@ const pay = createAction("checkout/pay", async () => {}, {
 ```
 
 ```
-[nanoeffects] [checkout] checkout/pay · command start
+[nanoeffects] [checkout] checkout/pay · action start
 ```
 
 The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", traceGroupId: "checkout" })`. `traceGroupId` works without `scopePlugin`, and needs `tracePlugin`.
@@ -185,7 +201,7 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 
 ```
 [nanoeffects] saveNotifier · run start
-[nanoeffects]   user/save · command start
+[nanoeffects]   user/save · action start
 [nanoeffects] saveNotifier · run done
 ```
 
@@ -230,7 +246,7 @@ const bus = createBus({
 | `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 |
+| `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)) |
 
 ### Cut volume in production
 
@@ -246,8 +262,60 @@ createTracer(logger, {
 - `sample` is decided once per root task; every task below it follows, so a trace is never cut in the middle. Unsampled tasks cost almost nothing.
 - `filter` runs on each event before any logger sees it.
 
+### Keep the last events for an incident
+
+`createTraceRecorder()` with no option keeps every event, so a long session fills memory. That is fine in a test and wrong in a running app. Give it a `capacity` and it keeps only the last N events (a ring buffer): when something goes wrong, you still have what led up to it.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer } from "nanoeffects/trace";
+
+// A logger that keeps the last 500 events and drops the older ones.
+export const recorder = createTraceRecorder({ capacity: 500 });
+
+// Feed the recorder from the tracer.
+const trace = createTracer(recorder);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// incident.js
+import { recorder } from "./bus";
+
+// Keep what is safe to send. An event also has `payload` and `error`.
+const withoutPayload = ({ id, parentId, type, effect, phase }) => ({
+  id,
+  parentId,
+  type,
+  effect,
+  phase,
+});
+
+window.addEventListener("error", () => {
+  const events = recorder.events; // a snapshot, oldest event first
+  const safe = events.map(withoutPayload);
+  const body = JSON.stringify(safe);
+  navigator.sendBeacon("/api/incident", body);
+});
+```
+
+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.
+- **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.
+
 ### Configure Redux DevTools
 
+<!-- docs-check: new -->
+
 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, so you see what happened before you see how:

package/docs/typescript.md

@@ -23,7 +23,7 @@ export const getUser = createAction(
   },
 );
 
-// createModule: m.use binds the handler the command carries, while the module is mounted
+// createModule: m.use binds the handler the action carries, while the module is mounted
 export const userModule = createModule("user", (m) => {
   m.use(getUser);
 });