nanoeffects 0.1.0 → 0.2.1

package/docs/effects.md

@@ -8,13 +8,13 @@ An abort only raises a flag: your code decides to stop. `nanoeffects/effects` ha
 import { cancellable } from "nanoeffects/effects";
 
 bus.on(
-	"wait",
-	latest((_, ctx) =>
-		cancellable(ctx, ({ resolve, onCancel }) => {
-			const timer = setTimeout(resolve, 5000);
-			onCancel(() => clearTimeout(timer));
-		}),
-	),
+  "wait",
+  latest((_, ctx) =>
+    cancellable(ctx, ({ resolve, onCancel }) => {
+      const timer = setTimeout(resolve, 5000);
+      onCancel(() => clearTimeout(timer));
+    }),
+  ),
 );
 ```
 
@@ -28,8 +28,8 @@ bus.on(
 import { onAbort } from "nanoeffects/effects";
 
 bus.on("connect", (url, ctx) => {
-	const socket = new WebSocket(url);
-	onAbort(ctx, () => socket.close());
+  const socket = new WebSocket(url);
+  onAbort(ctx, () => socket.close());
 });
 ```
 
@@ -39,8 +39,8 @@ bus.on("connect", (url, ctx) => {
 
 ```ts
 const { user, posts } = await allSettled(ctx, {
-	user: ({ signal }) => fetchUser(id, { signal }),
-	posts: ({ signal }) => fetchPosts(id, { signal }),
+  user: ({ signal }) => fetchUser(id, { signal }),
+  posts: ({ signal }) => fetchPosts(id, { signal }),
 });
 
 if (user.status === "fulfilled") render(user.value);
@@ -52,7 +52,7 @@ A task context has `on` and `off`, like the bus. A subscription made with `ctx.o
 
 ```ts
 bus.on("watch", (_, ctx) => {
-	ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
+  ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
 });
 ```
 
@@ -66,13 +66,13 @@ bus.on("watch", (_, ctx) => {
 import { take, timeout } from "nanoeffects/effects";
 
 bus.on("login", async (user, ctx) => {
-	const reason = await take(ctx, "logout"); // resolves on the next logout
-	cleanup(user, reason);
+  const reason = await take(ctx, "logout"); // resolves on the next logout
+  cleanup(user, reason);
 
-	// wait for a matching event, but not longer than 5 s
-	const id = await timeout(ctx, 5000, ({ signal }) =>
-		take(ctx, "saved", { signal, predicate: (id) => id === draft.id }),
-	);
+  // wait for a matching event, but not longer than 5 s
+  const id = await timeout(ctx, 5000, ({ signal }) =>
+    take(ctx, "saved", { signal, predicate: (id) => id === draft.id }),
+  );
 });
 ```
 
@@ -82,25 +82,43 @@ bus.on("login", async (user, ctx) => {
 
 ## retry, timeout, poll
 
+These three have two forms. As a **Task wrapper** they take a function `(payload, ctx) => result` and return one, so they go straight into `on`, next to the policies, with no `ctx` in their arguments. As a **call inside a body** they take `ctx` first.
+
 ```ts
 import { poll, retry, timeout } from "nanoeffects/effects";
 
+const loadUser = (id: string, { signal }) => fetchUser(id, { signal });
+
+// wrappers: up to 4 attempts with a backoff, each within 5 s; a newer call supersedes the older
+bus.on(
+  "load",
+  latest(
+    retry(timeout(5000, loadUser), {
+      times: 4,
+      delay: (attempt) => 2 ** attempt * 100,
+      shouldRetry: (error) => !isFatal(error),
+    }),
+  ),
+);
+
+// calls refresh every 10 s until the task is aborted
+bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+
+// a wrapped Task runs as a child of a handler with ctx.run: the only place where ctx is written
+bus.on("open", async (id, ctx) => {
+  const user = await ctx.run(retry(timeout(5000, loadUser)), id);
+});
+
+// one call inside a body: ctx first
 bus.on("load", async (id, ctx) => {
-	// up to 4 attempts, backoff between them; stops when the task aborts
-	const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), {
-		times: 4,
-		delay: (attempt) => 2 ** attempt * 100,
-		shouldRetry: (error) => !isFatal(error),
-	});
-
-	// aborts the starter's signal and rejects with a TimeoutError after 5 s
-	const data = await timeout(ctx, 5000, ({ signal }) => fetchData(id, { signal }));
-
-	// calls refresh every 10 s; resolves when the task aborts
-	await poll(ctx, () => refresh(), 10_000);
+  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 4 });
+  const data = await timeout(ctx, 5000, ({ signal }) => fetchData(id, { signal }));
+  await poll(ctx, () => refresh(), 10_000);
 });
 ```
 
+Use the wrapper form for a whole handler or a whole `ctx.run`, and the `ctx` form for one call in the middle of a body. The forms are told apart by the first argument: a function (`retry`), a number (`timeout`), a number or a function (`poll`) is a wrapper; an object is `ctx`. Each attempt or call of a wrapper gets a context of its own, a child of the caller's, so an abort of the caller reaches it and an abort of one attempt (a timeout) does not reach the caller. The attempt number is passed only in the `ctx` form.
+
 - `retry`: `times` is the total number of attempts (default 3), `delay` is a number or `(attempt, error) => ms`, `shouldRetry(error, attempt)` can stop early. `fn` gets the attempt number, starting at 1. On abort it rejects with the abort reason.
 - `timeout`: the error is a `DOMException` named `TimeoutError`, like `AbortSignal.timeout`. It rejects even if the starter ignores its signal.
 - `poll`: like patronum `interval`. The first call comes after `ms` (`leading: true` also calls at once), and the next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap with the next call; `waitForFn: true` starts each pause when the call ends instead, so calls never overlap. `fn` gets the call number from 0. An error from `fn` stops polling and rejects; an abort ends it normally and clears the timer.
@@ -114,6 +132,6 @@ await delay(ctx, () => 200 + Math.random() * 200); // 200 to 400 ms
 
 - All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
 
-In every effect `ctx` is the first argument: `delay(ctx, ms)`, `all(ctx, effects)`, `allSettled(ctx, effects)`, `race(ctx, effects)`, `cancellable(ctx, executor)`, `onAbort(ctx, fn)`, `retry(ctx, fn, options)`, `timeout(ctx, ms, starter)`, `poll(ctx, fn, ms, options)`, `take(ctx, event, options)`. It is required; outside a task pass `{}` or any object with a `signal`.
+The other effects wait inside a body, so `ctx` is their first argument: `delay(ctx, ms)`, `all(ctx, effects)`, `allSettled(ctx, effects)`, `race(ctx, effects)`, `cancellable(ctx, executor)`, `onAbort(ctx, fn)`, `take(ctx, event, options)`, and `retry`, `timeout` and `poll` in their `ctx` form. It is required; outside a task pass `{}` or any object with a `signal`.
 
 For `fetch` and other APIs that take a signal, pass `ctx.signal`. A timeout without `race`: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])`.

package/docs/errors.md

@@ -6,7 +6,7 @@ Pass `onError` to isolate handlers instead. Then every handler runs, and thrown
 
 ```ts
 const bus = createBus<Events>({
-	onError: (error, { type, payload }) => report(error, type, payload),
+  onError: (error, { type, payload }) => report(error, type, payload),
 });
 ```
 
@@ -16,8 +16,8 @@ A typo in an event name, `emit("serch")`, does nothing and says nothing. `onUnha
 
 ```ts
 const bus = createBus<Events>({
-	onUnhandled: import.meta.env.DEV
-		? ({ type }) => console.warn(`Nobody listens to "${type}"`)
-		: void 0,
+  onUnhandled: import.meta.env.DEV
+    ? ({ type }) => console.warn(`Nobody listens to "${type}"`)
+    : void 0,
 });
 ```

package/docs/guide.md

@@ -0,0 +1,229 @@
+# Guide
+
+From a bus with two calls to an app with modules, one step at a time. Every step builds on the one before, and the code is in [`examples/guide.ts`](../examples/guide.ts), where it is type-checked and run by a test.
+
+## 1. A bus
+
+`on` subscribes, `emit` calls the subscribers, and `on` returns the function that unsubscribes, as in nanoevents.
+
+```ts
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
+
+const unbind = bus.on("greet", (name) => console.log(`hello ${name}`));
+
+bus.emit("greet", "Ada"); // hello Ada
+unbind();
+bus.emit("greet", "Bob"); // nobody listens now
+```
+
+The handlers run at once, in the order they subscribed. That is all a bus is; the rest of the guide is what you can put on top.
+
+## 2. Types
+
+Describe the events once, and `on` and `emit` are checked. An event without data is `void`.
+
+```ts
+type Events = {
+  greet: string;
+  moved: { x: number; y: number };
+  reset: void;
+};
+
+const bus = createBus<Events>();
+
+bus.on("moved", ({ x, y }) => console.log(x + y));
+bus.emit("moved", { x: 1, y: 2 });
+bus.emit("reset");
+bus.emit("moved", { x: "1" }); // error: x is a number
+bus.emit("jumped", 1); // error: there is no such event
+```
+
+The map is optional: a bus without it takes any string and gives the payload as `unknown`.
+
+## 3. The context of a handler
+
+The second argument is the context of this call. A handler can emit events through it.
+
+```ts
+bus.on("moved", ({ x, y }, ctx) => {
+  if (x < 0) ctx.emit("outOfBounds", { x, y });
+});
+```
+
+Each call of a handler is a **task**, and `ctx` is what the task knows about itself: its `signal`, a way to `abort` it, and `emit`, `on`, `run`. A task that is aborted stops emitting.
+
+## 4. Three ways to name an event
+
+`emit` and `on` take the event as a string, as an object `{ type, payload }`, or as a function that has a `type` property.
+
+```ts
+bus.emit("moved", { x: 1, y: 2 }); // a string, and the payload next to it
+
+bus.emit({ type: "moved", payload: { x: 2, y: 2 } }); // an object, the shape of a Redux action
+
+const moved = createAction("moved");
+bus.emit(moved({ x: 3, y: 2 })); // what an action creator makes is such an object
+bus.on(moved, ({ x }) => console.log(x)); // and it names the event in `on` too
+```
+
+The third way is a function. A function with a `type` is a **command**: `emit` tells the subscribers of its type, then runs it, and **returns what it returns**.
+
+```ts
+import { createAction, createCommand } from "nanoeffects/actions";
+
+const double = createCommand("math/double", (value: number) => value * 2);
+
+bus.emit(double, 21); // 42
+```
+
+Strings are for the plain case, objects for actions that other code already makes, functions for requests that need a result.
+
+## 5. A command needs a handler
+
+A command made with a function carries its handler, as above. More often it is only a contract, a name with the types of the request and the result, and the code that does the work is registered separately: in another file, or a fake one in a test.
+
+```ts
+import { createCommand, createCommands } from "nanoeffects/actions";
+
+const getUser = createCommand<string, Promise<User>>("user/get"); // no handler yet
+
+const bus = createBus<Events>();
+const commands = createCommands(bus); // the handlers of this bus
+
+bus.emit(getUser, "1"); // throws: No handler for command "user/get"
+
+const unregister = commands.handle(getUser, (id) => api.user(id));
+const user = await bus.emit(getUser, "1"); // what the handler returned
+
+unregister(); // the command has no handler again
+```
+
+- `handle` returns the function that removes the handler, like `on`.
+- If a command has several handlers, the one registered last runs. A handler registered here wins over the one the command was made with.
+- Each bus has its own registry, so every test can bring its own handlers.
+- A [module](#10-modules) registers handlers for itself and removes them when it is unmounted.
+
+## 6. The first policy
+
+Often a handler is called again before the last call has finished: a user types another letter, a button is clicked twice. A **policy** wraps the handler and decides what happens then. It is used in place of the handler:
+
+```ts
+import { latest } from "nanoeffects/policies";
+
+// a newer search aborts the older one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    await api.search(query, { signal });
+  }),
+);
+```
+
+The aborted call learns about it through `signal`: pass it to `fetch` and the request is cancelled. Nothing else changes: the handler is the same function with the same arguments.
+
+## 7. More policies
+
+| Policy     | When calls overlap                          |
+| ---------- | ------------------------------------------- |
+| `latest`   | the previous call is aborted                |
+| `leading`  | new calls are dropped while one runs        |
+| `debounce` | runs after a pause in the calls             |
+| `throttle` | runs at most once in a time window          |
+| `queue`    | one after another, in order                 |
+
+Even a plain function works, it is just called less often. And policies nest:
+
+```ts
+import { debounce, queue, throttle } from "nanoeffects/policies";
+
+bus.on("scroll", throttle(100, (position) => updateScrollbar(position)));
+bus.on("typed", debounce(300, (text) => validate(text)));
+bus.on("save", queue(async (draft, { signal }) => api.save(draft, { signal })));
+
+// wait for quiet, then keep only the latest
+bus.on("search", debounce(300, latest(async (query, { signal }) => api.search(query, { signal }))));
+```
+
+More in [policies](policies.md).
+
+## 8. The first effects
+
+An **effect** adds what an async handler usually needs. `retry` and `timeout` wrap a handler the way a policy does, so they go into `on` with the policies and need no `ctx`:
+
+```ts
+import { retry, timeout } from "nanoeffects/effects";
+
+const search = (query: string, { signal }) => api.search(query, { signal });
+
+// 5 seconds for each try, up to 3 tries, and a newer query supersedes the whole thing
+bus.on("typed", latest(retry(timeout(5000, search), { times: 3 })));
+```
+
+When the handler needs the result, `ctx.run` runs the wrapped function as a child task: it is aborted with the handler, and it is the one place where `ctx` is written.
+
+```ts
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await ctx.run(retry(timeout(5000, search), { times: 3 }), query);
+    ctx.emit("results", items);
+  }),
+);
+```
+
+For one call in the middle of a handler, the effect takes `ctx` first: `await retry(ctx, () => api.search(q, { signal: ctx.signal }))`. More in [effects](effects.md).
+
+## 9. Several things at once, and waiting
+
+```ts
+import { all, take } from "nanoeffects/effects";
+
+bus.on("search", async (id, ctx) => {
+  const { user, posts } = await all(ctx, {
+    user: ({ signal }) => api.user(id, { signal }),
+    posts: ({ signal }) => api.posts(id, { signal }),
+  });
+});
+
+bus.on("typed", async (query, ctx) => {
+  const position = await take(ctx, "scroll"); // resolves with the next scroll
+});
+```
+
+`all` runs the starters together and fails, and cancels the rest, when one fails. `take` waits for the next event of a name. `ctx.on` subscribes as the task and ends with it. More in [effects](effects.md).
+
+## 10. Modules
+
+A module is what one part of the app does, in one place: its handlers, its commands, its background tasks. Unmounting it undoes all of that.
+
+```ts
+import { createModule, modulePlugin } from "nanoeffects/actions";
+
+const greeting = createModule<Events>("greeting", (m) => {
+  m.on("greet", (name) => console.log(`hello ${name}`));
+  m.handle(getUser, (id) => api.user(id)); // a contract gets its handler here
+  m.use(double); // a command that carries a handler: the module brings it
+});
+
+const app = bus.use(modulePlugin([greeting]));
+app.unmount(greeting); // the subscriptions and the handler are gone
+```
+
+Modules are also what makes [hot reload](hmr.md) work. More in [actions](actions.md).
+
+## 11. Errors and typos
+
+```ts
+const bus = createBus<Events>({
+  onError: (error) => report(error), // a failing handler does not stop the others
+  onUnhandled: ({ type }) => console.warn(`nobody listens to ${type}`), // a typo in a name
+});
+```
+
+More in [errors](errors.md).
+
+## Where next
+
+[Context fields](context.md) (a store or a client in every task) · [Tracing](tracing.md) · [Redux, Zustand, MobX](stores.md) · [Semantics](semantics.md)

package/docs/hmr.md

@@ -1,74 +1,36 @@
-# Hot reload (HMR)
+# Hot reload and development diagnostics
 
-When a file is edited in development, the bundler loads its new version and runs it again, while the page and the rest of the code stay alive. For a bus that means three things can go wrong:
-
-1. **Handlers pile up.** The file that calls `bus.on(...)` runs again, and the old handlers are still subscribed: every event is handled twice, then three times.
-2. **The bus is made again.** A file that has `createBus()` runs again: the new bus has none of the subscriptions of the files that did not reload.
-3. **Old work goes on.** Tasks that the old code started keep running with the old logic.
-
-Tasks that are tied to a signal can be ended, and modules are the unit that does it, so the answer is modules.
+When a file is edited in development, the bundler loads its new version and runs it again, while the page and the rest of the code stay alive. For a bus that can go wrong in three ways: a file that calls `bus.on(...)` subscribes a second time, a file that makes the bus makes a new one, and tasks of the old code keep running.
 
 ## Modules are replaced by name
 
-Mounting a module whose name is taken replaces the mounted one: the old module is unmounted first, and with it its subscriptions, its bound commands, its sub-modules and its background tasks (their signals abort). So the new version of a module file only has to mount again.
+Mounting a module whose name is taken replaces the mounted one. The old module is unmounted first, and with it its subscriptions, its bound commands, its sub-modules and its background tasks, whose signals abort. So the new version of a module file only has to mount again, and nothing piles up.
 
-```ts
-// bus.ts: made once, kept across reloads
-import { createBus } from "nanoeffects";
-import { registerModules } from "nanoeffects/actions";
+- **Names must be unique.** The name says "this is the new version of that module", so two different modules with one name replace each other. The name is also the type of the module's tasks in the trace.
+- **Pass `signal` to what the module does.** An unmount aborts the tasks, but a `fetch` or a loop that ignores `ctx.signal` runs on with the old code.
+- **Sub-modules** (`m.use(...)`) are replaced by name inside their parent. A reload of the parent module replaces it with all its children.
+- Keep the bus and the app in a file that is not reloaded, or in what your bundler keeps across reloads, so a reload does not make a new bus that the other files do not talk to.
 
-const hot = import.meta.hot;
+A `bus.on` outside a module returns the function that unsubscribes: hand it to the dispose hook of your bundler, or put the subscription in a module.
 
-export const bus: Bus<Events> = hot?.data.bus ?? createBus<Events>();
-export const app: ModuleApi<Events> = hot?.data.app ?? registerModules(bus);
-if (hot) {
-	hot.data.bus = bus;
-	hot.data.app = app;
-}
-```
+## `nanoeffects/dev`
 
-On the first run `hot.data` is empty and the bus and the app are made; on a reload the same ones are taken back. The same code is in `examples/hmr.ts`, which is type-checked with the rest of the project.
+`bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
 
 ```ts
-// user.module.ts: the module, and nothing else
-export const userModule = createModule<Events>("user", (m) => {
-	m.handle(getUser, fetchUser);
-	m.on("login", latest(loadProfile));
-});
-```
-
-```ts
-// main.ts: mounts the modules, and takes the new version of a module on reload
-import { app } from "./bus";
-import { userModule } from "./user.module";
-
-app.mount(userModule);
+import { devPlugin } from "nanoeffects/dev";
 
-// replaces the old "user" module with the new version
-import.meta.hot?.accept("./user.module", (next) => next && app.mount(next.userModule));
+const app = bus.use(modulePlugin([userModule]));
+bus.use(devPlugin({ app }));
 ```
 
-Vite calls the callback with the new version of `./user.module`, `main.ts` stays alive, and `app.mount` swaps the module. With webpack, `module.hot.accept("./user.module", () => app.mount(require("./user.module").userModule))` does the same.
-
-## What to keep in mind
-
-- **Keep the bus and the app in `import.meta.hot.data`** (or in a file that never reloads), as above. Otherwise a reload of that file makes a new bus, and the modules that did not reload talk to the old one.
-- **Names must be unique.** The name is what says "this is the new version of that module", so two different modules with one name replace each other. The name is also the type of the module's tasks in the trace.
-- **Pass `signal` to what the module does.** An unmount aborts the tasks, but a `fetch` or a loop that ignores `ctx.signal` runs on. This is the same advice as everywhere else, and in development it also stops old code from writing to the new state.
-- **Sub-modules** (`m.use(...)`) are replaced by name inside their parent. A reload of the parent module replaces it with all its children.
-
-## Handlers without modules
-
-A plain `bus.on` returns the function that unsubscribes. Give it to the dispose hook of the file:
-
-```ts
-if (import.meta.hot) {
-	import.meta.hot.dispose(bus.on("search", latest(runSearch)));
-}
-```
+- **Listeners that pile up.** When more than `maxListeners` (default 10) listeners of one event were added and not unsubscribed, one warning names the event and the count: a file that is reloaded and subscribes again, or an unsubscribe that is never called. The count follows the function that `on` returns, and `bus.off(event, fn)` is not seen.
+- **Modules.** With `app` it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
+- **Options.** `leaks: false` and `modules: false` switch a diagnostic off, `maxListeners` sets the limit, `log` receives the messages instead of the console.
+- **Disconnect.** `bus.use(devPlugin(...))` returns the function that stops the diagnostics and puts `bus.on` and `app.mount` back.
 
-Several: `import.meta.hot.dispose(() => { off1(); off2(); })`. Handlers inside modules do not need this.
+It changes no behavior: it wraps `bus.on`, `app.mount` and `app.unmount` and adds messages.
 
-## Redux and stores
+### In production
 
-With `createEffectsMiddleware`, keep the effects object in `import.meta.hot.data` as well, so the store keeps the same middleware, and register the effects in modules. For a new reducer use `store.replaceReducer(...)` as usual. A store of Zustand or MobX that lives in its own file and is passed in `context` can keep its state across reloads with the means of that library.
+`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition, which Vite and webpack set in production mode, so `bus.use(devPlugin({ app }))` can stay without a guard: it touches nothing and costs a few bytes. If you want even the call gone, guard it (`if (import.meta.env.DEV)` in Vite). An app that does not import the entry does not carry it.

package/docs/policies.md

@@ -37,10 +37,10 @@ The state of a key is dropped when that key goes idle, so keys can be unbounded
 import { queue } from "nanoeffects/policies";
 
 bus.on(
-	"save",
-	queue(async (draft, { signal }) => {
-		await api.save(draft, { signal });
-	}),
+  "save",
+  queue(async (draft, { signal }) => {
+    await api.save(draft, { signal });
+  }),
 );
 
 bus.emit("save", a); // runs now

package/docs/stores.md

@@ -27,8 +27,6 @@ It looks after what is easy to get wrong:
 
 Options are those of `createBus` (except `context`, which adds fields next to `store`) and `filter`, which keeps the actions it rejects away from the bus. Values that are not plain actions (thunks) go through untouched. Nothing here depends on Redux.
 
-To use your own bus, `nanoeffectsMiddleware(bus, { filter })` is the middleware alone: it sends actions to the bus after the reducers and nothing more. Give the store to the tasks yourself with `createBus({ context: { store } })`, or lazily, `context: { get store() { return store; } }` (typed with `WithContext`), since the store needs the middleware and the middleware needs the bus.
-
 ## Zustand, MobX and other stores
 
 No adapter is needed: a store tells about its changes, and `bus.emit` is a call.

package/docs/tracing.md

@@ -9,7 +9,7 @@ import { createBus } from "nanoeffects";
 import { createTracer } from "nanoeffects/trace";
 
 const bus = createBus<Events>({
-	trace: createTracer((event) => console.log(event)),
+  trace: createTracer((event) => console.log(event)),
 });
 ```
 
@@ -36,7 +36,7 @@ Phases:
 
 ```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) });
 });
 ```
 
@@ -49,7 +49,7 @@ import { createBus } from "nanoeffects";
 import { consoleLogger, createTracer, reduxDevtools } from "nanoeffects/trace";
 
 const bus = createBus<Events>({
-	trace: createTracer([reduxDevtools({ name: "app" }), consoleLogger()]),
+  trace: createTracer([reduxDevtools({ name: "app" }), consoleLogger()]),
 });
 ```
 
@@ -57,7 +57,7 @@ const bus = createBus<Events>({
 
 | Logger                  | What it does                                                                         |
 | ----------------------- | ------------------------------------------------------------------------------------ |
-| `reduxDevtools()`       | Sends each phase to Redux DevTools as `type/effect/phase`; state is `{ running }`.   |
+| `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.                                        |
@@ -68,15 +68,28 @@ const bus = createBus<Events>({
 
 ```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 the handler calls (a share, or a function of { type, payload })
+  filter: (event) => event.phase === "error", // and 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.
 - `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.
+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.
+
+It is quiet by default, so the log stays readable:
+
+- **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).
+
+```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
+```
+
+For more control, `createTracer(logger, { filter, sample })` cuts events before any logger sees them.
 
 To write your own, return a `TraceLogger`:
 
@@ -84,7 +97,7 @@ To write your own, return a `TraceLogger`:
 import type { TraceLogger } from "nanoeffects";
 
 const errorsOnly = (): TraceLogger => (event) => {
-	if (event.phase === "error") report(event.error);
+  if (event.phase === "error") report(event.error);
 };
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "Typed event bus where every handler is a task with an AbortSignal, plus policies (latest, debounce, throttle, queue), effects (retry, timeout, poll) and tracing. About 1.2 kB gzip.",
 	"keywords": [
 		"event-bus",
@@ -87,21 +87,31 @@
 		"./observable": {
 			"types": "./dist/observable.d.ts",
 			"import": "./dist/observable.js"
+		},
+		"./dev": {
+			"production": {
+				"types": "./dist/dev.d.ts",
+				"default": "./dist/production/dev.js"
+			},
+			"types": "./dist/dev.d.ts",
+			"import": "./dist/dev.js"
 		}
 	},
 	"scripts": {
 		"build": "tsdown && node scripts/notrace-types.mjs",
 		"prepublishOnly": "pnpm build",
-		"check": "biome check ./src ./examples ./integration",
-		"format": "npx @biomejs/biome check --write --unsafe ./src ./examples ./integration",
+		"check": "biome check ./src ./examples ./integration ./scripts",
+		"format": "npx @biomejs/biome check --write --unsafe ./src ./examples ./integration ./scripts",
 		"tsgo": "tsc --noEmit",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"prepare": "lefthook install",
 		"lint:package": "publint && attw --pack . --profile esm-only",
 		"size": "size-limit",
-		"verify": "pnpm tsgo && pnpm check && pnpm test && pnpm build && pnpm test:integration && pnpm lint:package && pnpm size",
-		"test:integration": "vitest run --config vitest.integration.config.ts"
+		"verify": "pnpm tsgo && pnpm check && pnpm test && pnpm build && pnpm test:integration && pnpm smoke && pnpm lint:package && pnpm size",
+		"test:integration": "vitest run --config vitest.integration.config.ts",
+		"smoke": "node scripts/smoke.mjs && node scripts/smoke.mjs --notrace",
+		"consumer-check": "node scripts/consumer-check.mjs"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.5",
@@ -160,6 +170,16 @@
 			"name": "observable",
 			"path": "dist/observable.js",
 			"limit": "0.5 kB"
+		},
+		{
+			"name": "dev",
+			"path": "dist/dev.js",
+			"limit": "1 kB"
+		},
+		{
+			"name": "dev (production)",
+			"path": "dist/production/dev.js",
+			"limit": "100 B"
 		}
 	]
 }

package/dist/bus-RUiw8f9p.js

@@ -1 +0,0 @@
-import{n as e}from"./onAbort-BgMfspK4.js";import{a as t,n,r}from"./context-BXQ6Einm.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=/* @__PURE__ */ new WeakSet,n=n=>{let r=e[n]??[];if(!t.has(r))return e[n]=r,r;let i=[...r];return e[n]=i,i},r=(t,r)=>{if(!r){e[t]=[];return}let i=(e[t]??[]).indexOf(r);i>=0&&n(t).splice(i,1)};return{get:n=>{let r=e[n]??[];return t.add(r),r},add:(e,t)=>(n(e).push(t),()=>{r(e,t)}),remove:r}},l=(e,t,n)=>Reflect.apply(e,null,[t,n]),u=(s={})=>{let u=c(),d=(e,t)=>u.add(o(e),t),f=(e,t)=>u.remove(o(e),t),p=(t,a)=>{let{onError:o}=s,{ctx:c}=n(a,m,s.trace,{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)}},m={on:d,off:f,emit:(e,i)=>{let c=o(e),d=a(e,i),f={type:c,payload:d},h=[...u.get(c),...u.get(`*`)];h.length===0&&typeof e!=`function`&&s.onUnhandled?.(f);for(let e of h)p(e,f);if(typeof e==`function`){let{ctx:i}=n(f,m,s.trace,{ref:r()}),a=m.commands?.run??l;return t(i,`command`,()=>a(e,d,i))}},commands:s.commands,context:s.context,trace:s.trace};return m};export{s as n,u as t};