nanoeffects 0.3.0 → 0.5.0

package/docs/tracing.md

@@ -1,111 +1,126 @@
-# Tracing
+# Trace tasks
 
-## Tracing
+Reference for long-lived apps that need to observe task phases, Redux DevTools, or a build without tracing. Not part of onboarding.
 
-Pass `trace` to `createBus` to observe every task phase. 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.
+## Attach a tracer
 
-```ts
+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.
+
+```js
 import { createBus } from "nanoeffects";
 import { createTracer } from "nanoeffects/trace";
 
-const bus = createBus<Events>({
+const bus = createBus({
+  // createTracer — observe every task phase
   trace: createTracer((event) => console.log(event)),
 });
 ```
 
 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).     |
-| `type`    | Event type the task works on.                                        |
-| `effect`  | `latest`, `debounce`, `throttle`, `leading`, `run`, `all` or `race`. |
-| `phase`   | `start`, `done`, `error`, `cancel` or `drop`.                        |
-| `payload` | Event payload.                                                       |
-| `error`   | Thrown value, only for `error`.                                      |
+| Field | Meaning |
+| ----- | ------- |
+| `id` | Unique task id within the bus |
+| `parent` | Id of the task that started this one (absent for handler tasks) |
+| `type` | Event type the task works on |
+| `effect` | `latest`, `debounce`, `throttle`, `leading`, `run`, `all`, `race`, … |
+| `phase` | `start`, `done`, `error`, `cancel`, or `drop` |
+| `payload` | Event payload |
+| `error` | Thrown value, only for `error` |
 
 Phases:
 
-- `start`: the work began.
-- `done` / `error`: it finished or threw.
-- `cancel`: it was aborted after it started (superseded by `latest`, parent aborted, lost a `race`).
-- `drop`: it never started (`leading` while busy, a `throttle` call replaced by a newer one, a `debounce` call replaced before its delay ended).
+- `start` — the work began.
+- `done` / `error` — it finished or threw.
+- `cancel` — aborted after it started (superseded by `latest`, parent aborted, lost a `race`).
+- `drop` — never started (`leading` while busy, a `throttle` call replaced by a newer one, a `debounce` call replaced before its delay ended).
 
-`all` and `race` are traced when you pass them the handler `ctx`: the group is one task, every starter is a child `run` task.
+`all` and `race` are traced when you pass them the handler `ctx`: the group is one task; every starter is a child `run` task.
+
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
+
+const bus = createBus();
 
-```ts
 bus.on("load", async (id, ctx) => {
-  await all(ctx, { user: () => fetchUser(id), posts: () => fetchPosts(id) });
+  await all(ctx, {
+    user: () => fetchUser(id),
+    posts: () => fetchPosts(id),
+  });
 });
 ```
 
-## Loggers
+## Use built-in loggers
 
-A logger is a function `(event: TraceEvent) => void` (the `TraceLogger` type). `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.
+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.
 
-```ts
+```js
 import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, reduxDevtools } from "nanoeffects/trace";
 
-const bus = createBus<Events>({
+const bus = createBus({
   trace: createTracer([reduxDevtools({ name: "app" }), consoleLogger()]),
 });
 ```
 
-`nanoeffects/trace` ships `createTracer` and these loggers, each a factory that returns a `TraceLogger`:
-
-| Logger                  | What it does                                                                         |
-| ----------------------- | ------------------------------------------------------------------------------------ |
-| `reduxDevtools()`       | Sends tasks to Redux DevTools as `type/effect/phase`; state is `{ running }`.        |
-| `consoleLogger()`       | Prints one line per phase, indented by task depth.                                   |
-| `performanceLogger()`   | Records User Timing measures for the Timings track of the browser Performance panel. |
-| `createTraceRecorder()` | Keeps events in `recorder.events`, for tests.                                        |
+| Logger | What it does |
+| ------ | ------------ |
+| `reduxDevtools()` | Sends tasks to Redux DevTools 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 |
 
-### Production: filter and sampling
+### Cut volume in production
 
-`createTracer(loggers, options)` can cut the volume:
+```js
+import { createTracer } from "nanoeffects/trace";
 
-```ts
 createTracer(logger, {
-  sample: 0.05, // trace 5% of the handler calls (a share, or a function of { type, payload })
-  filter: (event) => event.phase === "error", // and keep only failures
+  sample: 0.05, // trace 5% of handler calls (share, or function of { type, payload })
+  filter: (event) => event.phase === "error", // keep only failures
 });
 ```
 
-- `sample` is decided once per root task (one handler call) and every task below it follows, so a trace is never cut in the middle. Tasks that are not sampled cost almost nothing: their effects run without tracing.
+- `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.
 
-Notes on `reduxDevtools`: it is read-only (the bus owns no state, so there is no time travel) and does nothing when the extension is not installed. It has its own instance in the DevTools picker, apart from your store.
+### Configure Redux DevTools
 
-It is quiet by default, so the log stays readable:
+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.
 
-- **A task is one action**, sent when it ends (`done`, `error`, `cancel`, `drop`). The tasks that are running are in the state, `{ running }`. `starts: true` also sends every start.
-- **Only the top is shown**: the handler tasks and the effects they start (`retry`, `timeout`, ...). The attempts and starters under them are hidden. `depth: 0` shows the handler tasks only, `depth: 3` more, `Infinity` everything.
-- `maxAge: 200` sets how many actions DevTools keeps (its own default is 50).
+Quiet by default:
+
+- **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.
+- `maxAge: 200` — how many actions DevTools keeps (its default is 50).
+
+```js
+import { reduxDevtools } from "nanoeffects/trace";
 
-```ts
 reduxDevtools({ name: "app", depth: 0 }); // one line per handler call
-reduxDevtools({ name: "app", starts: true, depth: Infinity }); // everything, for a hunt for a bug
+reduxDevtools({ name: "app", starts: true, depth: Infinity }); // everything
 ```
 
-For more control, `createTracer(logger, { filter, sample })` cuts events before any logger sees them.
-
-To write your own, return a `TraceLogger`:
+### Write your own logger
 
 ```ts
 import type { TraceLogger } from "nanoeffects";
 
 const errorsOnly = (): TraceLogger => (event) => {
-  if (event.phase === "error") report(event.error);
+  if (event.phase === "error") {
+    report(event.error);
+  }
 };
 ```
 
-## Removing tracing from a build
+## Drop tracing from a build
 
-Without a tracer the hooks cost almost nothing (a lookup that finds no tracer), and `nanoeffects/trace` is a separate entry that is only bundled when imported. To also drop the tracing code from the core, use the `notrace` export condition: the package ships a second build of `index`, `effects`, `policies` and `actions` made with `__NANOEFFECTS_TRACE__` set to `false`, so the bundler removes the tracer calls.
+Without a tracer the hooks cost almost nothing. `nanoeffects/trace` is only bundled when imported.
 
-```ts
+To also drop tracing code from the core, use the `notrace` export condition. The package ships a second build of `index`, `effects`, `policies`, and `actions` with `__NANOEFFECTS_TRACE__` set to `false`.
+
+```js
 // vite / rolldown
 resolve: { conditions: ["notrace"] }
 // webpack
@@ -114,4 +129,4 @@ resolve: { conditionNames: ["notrace", "import", "..."] }
 conditions: ["notrace"]
 ```
 
-In a build of your own from the sources, `define: { __NANOEFFECTS_TRACE__: "false" }` does the same. With the condition set, the types of that build have no `trace` option: `createBus({ trace })` is a type error, so tracing cannot be left on by mistake (`scripts/notrace-types.mjs` makes `BusOptions.trace` `never` there). `nanoeffects/trace` has no `notrace` build. The saving is about 0.4 kB gzip of the whole library.
+In a build from the sources, `define: { __NANOEFFECTS_TRACE__: "false" }` does the same. With the condition set, that build’s types have no `trace` option: `createBus({ trace })` is a type error. `nanoeffects/trace` has no `notrace` build. The saving is about 0.4 kB gzip of the whole library.

package/docs/typescript.md

@@ -0,0 +1,153 @@
+# Use nanoeffects in a TypeScript app with many files
+
+Read this page if your app is in TypeScript and the commands and modules live in different files. It shows how to write a command so that TypeScript infers its payload and result, and what to add when the handlers need the fields of your bus (`ctx.store`, the effects of `effectsPlugin`). For one file or for JavaScript you do not need it.
+
+## Write a command with its handler
+
+Give `createCommand` the handler and write nothing else. The payload comes from the annotated parameter, the result from the body. You do not write a generic.
+
+<!-- docs-check: skip - a file of examples/typescript, type-checked there -->
+```ts
+// user.ts
+import { createCommand, createModule } from "nanoeffects/actions";
+
+export type User = { id: string; name: string };
+
+// payload: string, from `id: string`; result: Promise<User>, from the body
+export const getUser = createCommand(
+  "user/get",
+  async (id: string, { signal }) => {
+    const response = await fetch(`/api/users/${id}`, { signal });
+    const user: User = await response.json();
+    return user;
+  },
+);
+
+// createModule: m.use binds the handler the command carries, while the module is mounted
+export const userModule = createModule("user", (m) => {
+  m.use(getUser);
+});
+```
+
+Mount the module where you create the bus. The result is typed from the handler:
+
+<!-- docs-check: skip - a file of examples/typescript, type-checked there -->
+```ts
+// main.ts
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { getUser, userModule } from "./user";
+
+const bus = createBus();
+const app = bus.use(modulePlugin([userModule])); // mounts the modules
+
+const user = bus.emit(getUser("1")); // Promise<User>
+```
+
+What you annotate, and why:
+
+| Part | Annotated? | Why |
+| ---- | ---------- | --- |
+| payload (`id: string`) | yes | a function parameter has no type to infer from |
+| `ctx` | no, for `signal` and the fields every task has | `signal`, `emit`, `on` and `run` are on every `ctx` |
+| result | no | inferred from the body |
+
+A wrong payload at the call (`getUser(1)`) is an error. Annotate the parameters, not the variable: a type on the whole variable, such as `const handler: Task<string, Events> = …`, fixes the type of the function, and the result becomes `unknown`.
+
+## Give `ctx` the fields of your bus
+
+Types of a bus live on the bus. `contextPlugin({ store })` and `effectsPlugin({ race })` make `ctx.store` and `ctx.race` known to the handlers of **that bus**. A command made in another file does not see the bus, so its `ctx` has no `store`:
+
+<!-- docs-check: skip - shows the error on purpose -->
+```ts
+export const getUser = createCommand("user/get", (id: string, ctx) => {
+  ctx.store; // error: Property 'store' does not exist
+});
+```
+
+At runtime the bus still gives the task its fields. Only the checker does not know it. Name the types of the bus once, in the file that creates it. `contextPlugin` takes the type of each field from the value you pass, so the event map holds only events. `EventsOf` reads the event map from the bus, with the fields that the plugins added. The code of this section is in [`examples/typescript-context`](../examples/typescript-context).
+
+<!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
+```ts
+// bus.ts
+import { type Context, contextPlugin, createBus, type EventsOf } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
+import { effectsPlugin, race } from "nanoeffects/effects";
+
+// Events: event name → payload; nothing about ctx is written here
+type Events = { "user/loaded": User };
+
+export const bus = createBus<Events>()
+  .use(contextPlugin({ store })) // ctx.store, typed from the value `store`
+  .use(effectsPlugin({ race })); // ctx.race; each plugin returns the same bus, typed with its fields
+
+// the app of the bus: mounts modules and creates them with the types of the bus
+export const app = bus.use(modulePlugin()); // no modules yet: main.ts mounts them
+export const { createModule } = app; // createModule with the types of the bus
+
+export type AppEvents = EventsOf<typeof bus>; // the event map and all fields of ctx
+export type AppContext = Context<AppEvents>; // ctx of a handler of this bus: has store and race
+```
+
+| Type | What it is | Why you name it |
+| ---- | ---------- | --------------- |
+| `EventsOf<typeof bus>` | the event map of the bus, with the context fields of the plugins (and of `WithContext`, if you use it) | the source of `AppContext` |
+| `Context<AppEvents>` | the `ctx` that a handler of the bus gets | annotate the `ctx` of a handler given to `createCommand` |
+
+These types change nothing at runtime. They only tell the checker what the bus already does.
+
+Annotate `ctx` with `AppContext` where the handler reads a field of the bus, and create the module with the `createModule` that `bus.ts` exports, so its `m.on` handlers see the fields too:
+
+<!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
+```ts
+// user.ts
+import { createCommand } from "nanoeffects/actions";
+import { type AppContext, createModule } from "./bus";
+
+export const getUser = createCommand(
+  "user/get",
+  (id: string, { store, signal }: AppContext) => store.fetchUser(id, { signal }),
+);
+
+// createModule from bus.ts: handlers of the module see the context fields of the bus
+export const userModule = createModule("user", (m) => {
+  m.use(getUser);
+  m.on("user/loaded", (user, { store }) => store.remember(user));
+});
+```
+
+<!-- docs-check: skip - a file of examples/typescript-context, type-checked there -->
+```ts
+// main.ts: the modules are mounted here, because the module files need `app`
+import { app, bus } from "./bus";
+import { getUser, userModule } from "./user";
+
+const unmount = app.mount(userModule); // starts the module; unmount() undoes it
+const user = bus.emit(getUser("1")); // Promise<User>
+```
+
+`createModule` of the app only creates the module: it does not mount it, and it keeps no link to the bus. That is why the app in `bus.ts` starts without modules. `createModule` from `nanoeffects/actions` stays for a module made without a bus: there you write the event map yourself, `createModule<AppEvents>("user", …)`.
+
+## Keep the contract apart from the code
+
+When the file with the command must not import the code that implements it, make the command without a handler. Here you write the payload and the result once, as generics, and the handler goes to a module, where it needs no annotation:
+
+<!-- docs-check: skip - fragment of the file above -->
+```ts
+export const getUser = createCommand<string, Promise<User>>("user/get"); // the contract
+
+createModule("user", (m) => {
+  // payload and result come from the command, ctx from the app: no annotation
+  m.handle(getUser, (id, { store, signal }) => store.fetchUser(id, { signal }));
+});
+```
+
+A wrong payload, a wrong field of `ctx` and a wrong result are errors.
+
+## Check your setup
+
+- **A field is missing on `ctx`.** The `ctx` of a handler given to `createCommand` is not annotated: add `: AppContext`. A handler written inline in `m.handle` or `m.on` of a module made with the `createModule` of `bus.ts` does not need it. The default `ctx` has no fields of your bus.
+- **`EventsOf<typeof bus>` is `never`.** `bus` is not a bus. `bus.use(commandsPlugin())` and `bus.use(modulePlugin(...))` return the registry or the app, not the bus: keep the bus in its own constant (`bus`, then `app = bus.use(modulePlugin())`).
+- **`effectsPlugin` is not in the type.** `use` must come before you read `typeof bus`. Chain `createBus(...).use(effectsPlugin(...))` in one binding.
+- **A policy loses the types.** It does not: `latest(handler)` keeps the payload, the result and the context of `handler`.
+- **Do not pass the context as a generic of `createCommand`.** It is the fourth generic, after the payload, the result and the type string, so you would have to write all four. Annotate `ctx` with `AppContext`, or put the handler in a module made with the `createModule` of `bus.ts`.