nanoeffects 0.3.0 → 0.5.0

package/docs/guide.md

@@ -1,229 +1,338 @@
 # 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.
+Climb one step at a time: small bus → policies → effects → commands and modules. Stop when your project has what it needs.
 
-## 1. A bus
+| Your project | Stop after |
+| ------------ | ---------- |
+| Widget / prototype | §1–2 |
+| SPA with async UI | §3–4 |
+| Unreliable network / long flows | §5–6 |
+| Domain logic off the UI | §7–9 |
 
-`on` subscribes, `emit` calls the subscribers, and `on` returns the function that unsubscribes, as in nanoevents.
+Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 
-```ts
+## 1. Create a bus
+
+`on` subscribes. `emit` calls the subscribers. `on` returns the unsubscribe function.
+
+```js
 import { createBus } from "nanoeffects";
 
-const bus = createBus();
+const bus = createBus(); // event bus; each handler call is a task
 
-const unbind = bus.on("greet", (name) => console.log(`hello ${name}`));
+const unbind = bus.on("greet", (name) => {
+  console.log(`hello ${name}`);
+});
 
 bus.emit("greet", "Ada"); // hello Ada
 unbind();
-bus.emit("greet", "Bob"); // nobody listens now
+bus.emit("greet", "Bob"); // nobody listens
 ```
 
-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.
+Handlers run at once, in subscription order.
 
-## 2. Types
+`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus.
 
-Describe the events once, and `on` and `emit` are checked. An event without data is `void`.
+```js
+import { createBus } from "nanoeffects";
 
-```ts
-type Events = {
-  greet: string;
-  moved: { x: number; y: number };
-  reset: void;
-};
+const bus = createBus();
 
-const bus = createBus<Events>();
+// once — runs at most once, then unsubscribes
+bus.once("ready", () => console.log("ready"));
+bus.emit("ready"); // ready
+bus.emit("ready"); // nobody listens
 
-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
+bus.on("tick", () => {});
+bus.off(); // clear every subscription
 ```
 
-The map is optional: a bus without it takes any string and gives the payload as `unknown`.
+## 2. Use the handler context
 
-## 3. The context of a handler
+The second argument is the **task** context for this call. Emit further events through it. Pass `ctx.signal` to `fetch` when you cancel work.
 
-The second argument is the context of this call. A handler can emit events through it.
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
 
-```ts
 bus.on("moved", ({ x, y }, ctx) => {
-  if (x < 0) ctx.emit("outOfBounds", { x, y });
+  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.
+`ctx` has `signal`, `abort`, `emit`, `on`, and `run`. An aborted task stops emitting and delivers no result.
 
-## 4. Three ways to name an event
+## 3. Abort the previous run with `latest`
 
-`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
-```
+A handler is often called again before the last call finished (typing, double-clicks). A **policy** wraps the handler and decides what happens then. Start with `latest`: a newer call aborts the older one through `signal`.
 
-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";
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
 
-const double = createCommand("math/double", (value: number) => value * 2);
+const bus = createBus();
 
-bus.emit(double, 21); // 42
+// latest — a newer run aborts the older one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    await api.search(query, { signal });
+  }),
+);
 ```
 
-Strings are for the plain case, objects for actions that other code already makes, functions for requests that need a result.
+Same `on`, same handler shape. More in [Policies](policies.md).
 
-## 5. A command needs a handler
+## 4. Pick another policy when overlap differs
 
-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.
+| Policy | When calls overlap |
+| ------ | ------------------ |
+| `latest` | previous call is aborted |
+| `leading` | new calls drop while one runs |
+| `debounce` | runs after a pause |
+| `throttle` | at most once per window |
+| `queue` | one after another |
 
-```ts
-import { createCommand, commandsPlugin } from "nanoeffects/actions";
-
-const getUser = createCommand<string, Promise<User>>("user/get"); // no handler yet
-
-const bus = createBus<Events>();
-const commands = bus.use(commandsPlugin()); // 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.
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest, queue, throttle } from "nanoeffects/policies";
 
-## 6. The first policy
+const bus = createBus();
 
-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:
+// throttle — at most once per 100 ms
+bus.on("scroll", throttle(100, (position) => {
+  updateScrollbar(position);
+}));
 
-```ts
-import { latest } from "nanoeffects/policies";
+// debounce — run after 300 ms of quiet
+bus.on("typed", debounce(300, (text) => {
+  validate(text);
+}));
 
-// a newer search aborts the older one
+// queue — one save after another, in order
 bus.on(
-  "search",
-  latest(async (query, { signal }) => {
-    await api.search(query, { signal });
+  "save",
+  queue(async (draft, { signal }) => {
+    await api.save(draft, { 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.
+// nest: wait for quiet, then keep only the latest search
+const searchLatest = latest(async (query, { signal }) => {
+  await api.search(query, { signal });
+});
+bus.on("search", debounce(300, searchLatest));
+```
 
-## 7. More policies
+Full options: [Policies](policies.md).
 
-| 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                 |
+## 5. Add retry and timeout
 
-Even a plain function works, it is just called less often. And policies nest:
+An **effect** adds what an async handler usually needs. `retry` and `timeout` wrap a handler like a policy, so they go into `on` with no `ctx` in their arguments.
 
-```ts
-import { debounce, queue, throttle } from "nanoeffects/policies";
+```js
+import { createBus } from "nanoeffects";
+import { retry, timeout } from "nanoeffects/effects";
+import { latest } 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 })));
+const bus = createBus();
 
-// wait for quiet, then keep only the latest
-bus.on("search", debounce(300, latest(async (query, { signal }) => api.search(query, { signal }))));
-```
+const search = (query, { signal }) => api.search(query, { signal });
 
-More in [policies](policies.md).
+// timeout — fail one try after 5 s
+const searchOnce = timeout(5000, search);
+// retry — up to 3 tries
+const searchWithRetry = retry(searchOnce, { times: 3 });
 
-## 8. The first effects
+// latest — a newer typed query aborts the whole retry chain
+bus.on("typed", latest(searchWithRetry));
+```
 
-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`:
+When the handler itself needs the result, `ctx.run` runs the wrapped function as a child task (aborted with the parent):
 
-```ts
+```js
+import { createBus } from "nanoeffects";
 import { retry, timeout } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
 
-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.
+const bus = createBus();
+const search = (query, { signal }) => api.search(query, { signal });
 
-```ts
 bus.on(
   "search",
   latest(async (query, ctx) => {
-    const items = await ctx.run(retry(timeout(5000, search), { times: 3 }), query);
+    const load = retry(timeout(5000, search), { times: 3 });
+    const items = await ctx.run(load, query); // child task; aborted with this one
     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).
+For one call in the middle of a body: `await retry(ctx, () => api.search(q, { signal: ctx.signal }))`. More in [Effects](effects.md).
 
-## 9. Several things at once, and waiting
+## 6. Run work in parallel or wait for an event
 
-```ts
+```js
+import { createBus } from "nanoeffects";
 import { all, take } from "nanoeffects/effects";
 
+const bus = createBus();
+
+// all — run together; one failure cancels the rest
 bus.on("search", async (id, ctx) => {
   const { user, posts } = await all(ctx, {
     user: ({ signal }) => api.user(id, { signal }),
     posts: ({ signal }) => api.posts(id, { signal }),
   });
+  ctx.emit("loaded", { user, posts });
 });
 
+// take — wait for the next event of that name
 bus.on("typed", async (query, ctx) => {
-  const position = await take(ctx, "scroll"); // resolves with the next scroll
+  const position = await take(ctx, "scroll");
+  ctx.emit("scrolled", { query, position });
 });
 ```
 
-`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).
+More in [Effects](effects.md).
 
-## 10. Modules
+## 7. Name events three ways
 
-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.
+`emit` and `on` take a string, an object `{ type, payload }` (a Redux action fits), or a function with a `type` property (action creators and commands).
 
-```ts
-import { createModule, modulePlugin } from "nanoeffects/actions";
+```js
+import { createBus } from "nanoeffects";
+import { createAction, createCommand } from "nanoeffects/actions";
+
+const bus = createBus();
+
+bus.emit("moved", { x: 1, y: 2 });
+bus.emit({ type: "moved", payload: { x: 2, y: 2 } });
+
+// createAction — names an event; calling it builds { type, payload }
+const moved = createAction("moved");
+bus.emit(moved({ x: 3, y: 2 }));
+bus.on(moved, ({ x }) => console.log(x));
+
+// createCommand — like an action, but emit runs a handler and returns its result
+const double = createCommand("math/double", (value) => value * 2);
+bus.emit(double(21)); // 42
+```
+
+Use strings for the plain case. Use objects when other code already builds actions. Use commands when you need a result from `emit`.
+
+## 8. Register a command handler
+
+A command may carry its handler, or only be a **contract** (name + types) with the work registered elsewhere — another file, or a fake in a test.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand, commandsPlugin } from "nanoeffects/actions";
+
+const getUser = createCommand("user/get"); // contract — no handler yet
+
+const bus = createBus();
+// commandsPlugin — registry of handlers for this bus
+const commands = bus.use(commandsPlugin());
+
+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"));
+
+unregister();
+```
 
-const greeting = createModule<Events>("greeting", (m) => {
+Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can register handlers and remove them on unmount. More in [Actions](actions.md).
+
+## 9. Mount a domain as a module
+
+**Problem.** A feature owns several things on the bus: who answers `getUser`, who listens to `greet`, maybe a command that already carries its handler. With plain `bus.on` / `commands.handle` you must remember every unsubscribe when the feature goes away. Miss one and listeners pile up.
+
+**When.** Domain logic lives on the bus, off the UI, and you need one mount / one unmount for that feature. Skip modules while a few top-level `bus.on` calls are enough.
+
+**What you do.** `createModule(name, setup)` describes the feature. `bus.use(modulePlugin([…]))` mounts it. `app.unmount(module)` undoes everything the setup registered.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand, createModule, modulePlugin } from "nanoeffects/actions";
+
+const getUser = createCommand("user/get"); // contract — no handler yet
+const double = createCommand("math/double", (value) => value * 2); // carries its handler
+
+const bus = createBus();
+
+// createModule — one feature; name is stable for hot reload replace
+const greeting = createModule("greeting", (m) => {
+  // m.on — like bus.on, removed automatically on unmount
   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
+
+  // m.handle — this module answers getUser while mounted
+  m.handle(getUser, (id) => api.user(id));
+
+  // m.use — register a command that already has a handler, for this module’s life
+  m.use(double);
 });
 
+// modulePlugin — mount modules on the bus
 const app = bus.use(modulePlugin([greeting]));
-app.unmount(greeting); // the subscriptions and the handler are gone
+bus.emit("greet", "Ada"); // hello Ada
+app.unmount(greeting); // greet listener and getUser binding are gone
 ```
 
-Modules are also what makes [hot reload](hmr.md) work. More in [actions](actions.md).
+- **`m.on`** — same job as `bus.on`, scoped to the module’s lifetime.
+- **`m.handle`** — bind a handler to a contract command; gone on unmount.
+- **`m.use`** — bring a command that already carries a handler (or a sub-module). Prefer `handle` when the handler must die with the feature.
 
-## 11. Errors and typos
+Modules also make [hot reload](hmr.md) work. Full API in [Actions](actions.md); a longer recipe in [`examples/modules.ts`](../examples/modules.ts).
+
+## 10. Add types when you want checking (optional)
+
+Describe events once when you want `on` / `emit` checked. An event without data is `void`. Skip this while you are learning the bus.
 
 ```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
+import { createBus } from "nanoeffects";
+
+// Events — event name → payload for this bus (checker only)
+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
+// bus.emit("jumped", 1); // error
+```
+
+Without a map, any string event is allowed and the payload is `unknown`.
+
+## 11. Isolate errors and warn on typos
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  onError: (error) => report(error), // isolate failing handlers
+  onUnhandled: ({ type }) => console.warn(`nobody listens to ${type}`),
 });
 ```
 
-More in [errors](errors.md).
+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)
+| Need | Page |
+| ---- | ---- |
+| Store or client on every task | [Context fields](context.md) |
+| Redux / Zustand / MobX | [Stores](stores.md) |
+| Observe tasks | [Tracing](tracing.md) |
+| Guarantees | [Semantics](semantics.md) |
+| Which import | [Package entries](package.md) |

package/docs/hmr.md

@@ -1,36 +1,48 @@
 # 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 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.
+Use this page in development with modules and hot reload. Skip until you mount domains with `modulePlugin`.
 
-## Modules are replaced by name
+When a file is edited, 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:
 
-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.
+1. A file that calls `bus.on(...)` subscribes a second time.
+2. A file that makes the bus makes a new one.
+3. Tasks of the old code keep running.
 
-- **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.
+## Replace modules by name
+
+Mounting a module whose name is taken replaces the mounted one. The old module is unmounted first — and with it its subscriptions, bound commands, sub-modules, and background tasks (their signals abort). The new version of a module file only has to mount again; nothing piles up.
+
+- **Names must be unique.** The name means “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.
+- **Sub-modules** (`m.use(...)`) are replaced by name inside their parent. A reload of the parent 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 other files do not talk to.
 
 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.
 
-## `nanoeffects/dev`
+## Report leaks with `devPlugin`
 
 `bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
 
-```ts
+```js
+import { createBus } from "nanoeffects";
+import { modulePlugin } from "nanoeffects/actions";
 import { devPlugin } from "nanoeffects/dev";
 
+const bus = createBus();
 const app = bus.use(modulePlugin([userModule]));
+// devPlugin — warn on piled-up listeners; log module mount/replace/unmount
 bus.use(devPlugin({ app }));
 ```
 
-- **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.
+- **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. The count follows the function that `on` returns; `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.
+- **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.
 
-It changes no behavior: it wraps `bus.on`, `app.mount` and `app.unmount` and adds messages.
+It changes no behavior: it wraps `bus.on`, `app.mount`, and `app.unmount` and adds messages.
+
+### Keep the import in production
 
-### In production
+`nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin({ app }))` can stay without a guard: it touches nothing and costs a few bytes.
 
-`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.
+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.