nanoeffects 0.29.0 → 0.31.0

package/docs/examples.md

@@ -0,0 +1,60 @@
+# Examples
+
+> **Levels A to F.** Read first: [README](README.md#the-ladder-from-a-to-f).
+
+Examples to run in the browser and to read. Every folder lives in `examples/` of the repository and is type-checked with the project. Two of them are explained step by step: [Build a chat](chat-example.md) and [Build a chat widget](chat-widget.md).
+
+## Try it in the browser
+
+All three are the same search box: type fast and only one request starts (`debounce`); type again while a request runs and the older one is aborted (`latest`). StackBlitz runs them with no install.
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`playground`](../examples/playground) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground) | Plain DOM and one file: the smallest setup. The page lists the requests, so the abort is visible. |
+| [`playground-react`](../examples/playground-react) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground-react) | The same search in a React component, with the bus outside React. |
+| [`playground-devtools`](../examples/playground-devtools) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground-devtools) | The same search with its emits and stopped calls sent to Redux DevTools. |
+
+## Bigger projects
+
+React and TypeScript projects that show where logic goes when an app has several features.
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`chat`](../examples/chat) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat) | Rooms, history under `latest`, ordered sends under `queue` and `retry`, search under `allSettled`, polling with `poll`. Explained in [Build a chat](chat-example.md). |
+| [`pokedex`](../examples/pokedex) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/pokedex) | Real requests to PokeAPI: a search with `debounce`, `latest`, `timeout` and `retry`, abilities with `allSettled`. |
+| [`spells`](../examples/spells) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/spells) | The smallest example: a search in one file, one action that carries its handler. |
+| [`chat-widget`](../examples/chat-widget) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat-widget) | A chat behind a launcher button: opening mounts one module, closing unmounts it. Explained in [Build a chat widget](chat-widget.md). |
+| [`counter`](../examples/counter) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/counter) | The counter of the redux-saga tutorial, without a store and with Redux Toolkit. |
+| [`rickandmorty`](../examples/rickandmorty) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/rickandmorty) | Characters with React Query: requests are actions that get its abort signal. |
+| [`trades`](../examples/trades) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/trades) | A live stream over a WebSocket: `retry`, `latest` and `throttle`. |
+
+## Backend examples
+
+Small [Fastify](https://fastify.dev) apps with no database. They need Node 18 or newer: run `npm install` and `npm start` in the folder. More in [Stop work on a server](server.md).
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`api-server`](../examples/api-server) | A server over PokeAPI: `timeout`, `retry`, `allSettled`, and an abort when the client leaves. |
+| [`job-worker`](../examples/job-worker) | A queue worker: `queue`, `retry`, `timeout`, counts from the outcomes of a job. |
+| [`ws-server`](../examples/ws-server) | A WebSocket server: one controller per socket, `latest` with a `key`. |
+
+## Recipes
+
+Each file is one job, written as a short program with a comment on every nanoeffects call.
+
+| File | Job | Docs |
+| ---- | --- | ---- |
+| [`search.ts`](../examples/search.ts) | A search box that waits for quiet and aborts the older request. | [Policies](policies.md) |
+| [`backoff.ts`](../examples/backoff.ts) | Retry a flaky request with a growing pause. | [Effects](effects.md#backoff) |
+| [`registration-form.ts`](../examples/registration-form.ts) | A sign-up form: a username check that does not race. | [React form](react.md) |
+| [`scope.ts`](../examples/scope.ts) | An action with its own effects and a test that replaces one. | [Working with context](context.md) |
+| [`modules.ts`](../examples/modules.ts) | Domain logic with no UI, mounted and unmounted as one unit. | [Actions](actions.md) |
+| [`redux.ts`](../examples/redux.ts) | Redux Toolkit actions that also reach the bus. | [State managers](stores.md) |
+| [`guide.ts`](../examples/guide.ts) | The code of every step of the guide. | [Guide](guide.md) |
+
+## TypeScript projects
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`typescript`](../examples/typescript) | Name the event map once and use it in modules and actions. |
+| [`typescript-context`](../examples/typescript-context) | Give `ctx` the fields of your bus and type them from one place. |

package/docs/guide.md

@@ -1,13 +1,15 @@
 # Guide
 
-Climb one step at a time: small bus → policies → effects → handlers and modules. Stop when your project has what it needs.
+> **Levels A to D.** Read first: [README](../README.md) (install and the first example).
 
-| 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 |
+Climb one step at a time: small bus → policies → effects → handlers and modules. Stop when your project has what it needs. Install the package first: `npm install nanoeffects` (details in the [README](../README.md#install)). The levels A to D are described in the [map of the docs](README.md#the-ladder-from-a-to-f).
+
+| Level | Your project | Stop after |
+| ----- | ------------ | ---------- |
+| A | Widget / prototype | §1–2 |
+| B | SPA with async UI | §3–4 |
+| C | Unreliable network / long flows | §5–6 |
+| D | Domain logic off the UI | §7–9 |
 
 Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 
@@ -22,7 +24,7 @@ Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 - [5. Add retry and timeout](#5-add-retry-and-timeout)
 - [6. Run work in parallel or wait for an event](#6-run-work-in-parallel-or-wait-for-an-event)
 - [7. Name events three ways](#7-name-events-three-ways)
-- [8. Bind a handler to an action later](#8-bind-a-handler-to-an-action-later)
+- [8. Replace a handler on the fly](#8-replace-a-handler-on-the-fly)
 - [9. Mount a domain as a module](#9-mount-a-domain-as-a-module)
 - [10. Add types when you want checking (optional)](#10-add-types-when-you-want-checking-optional)
 - [11. Isolate errors and warn on typos](#11-isolate-errors-and-warn-on-typos)
@@ -48,7 +50,12 @@ bus.emit("greet", "Bob"); // nobody listens
 
 Handlers run at once, in subscription order.
 
-`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. `bus.get("greet")` gives the listeners that event has right now; `bus.get("greet").length === 0` tells that nobody listens any more (`"*"` gives the any-event listeners, which a named event does not include; `bus.get()` with no name gives every listener of every event). It takes the event name as a string: for an action creator use `creator.type`.
+Four more calls cover most of what you need from the bus itself:
+
+- `bus.once(event, handler)` 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, `"*"` included. `ctx.off` is the same `off` as the bus's, so `ctx.off()` also clears the whole bus.
+- `bus.get("greet")` gives the listeners that event has right now, so `bus.get("greet").length === 0` tells that nobody listens any more. `"*"` gives the any-event listeners, which a named event does not include; `bus.get()` with no name gives every listener of every event. It takes the event name as a string: for an action creator use `creator.type`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -66,6 +73,8 @@ bus.off(); // clear every subscription
 
 ### Listen to every event
 
+You can skip this and the next section on a first read.
+
 `bus.on("*", fn)` runs for every event of the bus. It is for logging, debugging, or forwarding events elsewhere. The handler gets the payload and the task context as usual, and `ctx.type` is the name of the event.
 
 ```js
@@ -88,7 +97,7 @@ unbind();
 
 ### Pick events with a function
 
-To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
+This is for level B and later. To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
 
 <!-- docs-check: new -->
 
@@ -234,7 +243,7 @@ const searchLatest = latest(async (query, { signal }) => {
 bus.on("search", debounce(300, searchLatest));
 ```
 
-Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
+Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [`withPolicy`: call a policy outside a bus](policies.md#withpolicy-call-a-policy-outside-a-bus).
 
 ## 5. Add retry and timeout
 
@@ -289,7 +298,7 @@ import { all, delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 // all — run together; one failure cancels the rest
-// child — the context of that starter: it has the `signal`, so the request stops with the group
+// child — the context of that request: it has the `signal`, so the request stops with the group
 bus.on("search", async (id, ctx) => {
   const { user, posts } = await all(ctx, {
     user: (child) => api.user(id, child),
@@ -364,9 +373,11 @@ bus.emit(double(21)); // 42
 
 Use strings for the plain case. Use objects when other code already builds actions. Give `createAction` a handler when you need a result from `emit`.
 
-## 8. Bind a handler to an action later
+## 8. Replace a handler on the fly
+
+**Problem.** The handler of an action is in the file of the feature, but a test needs a fake, or another layer owns the work. If the handler sits in `createAction`, the event file is tied to the work.
 
-An action may carry its handler, as `double` above, or get it later from a registry — another file, or a fake in a test. An action with no handler is an event until one is bound.
+**What to do.** Create the action without a handler: it is an event. Bind the real handler with `setHandler` when the bus is made. Later, `actions.handle` binds a newer handler that wins until you remove it.
 
 ```js
 // user.js
@@ -378,26 +389,32 @@ export const getUser = createAction("user/get"); // no handler yet: an event
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { actionsPlugin } from "nanoeffects/actions";
+import { actionsPlugin, setHandler } from "nanoeffects/actions";
+import { getUser } from "./user";
 
 export const bus = createBus();
-// actionsPlugin — registry of handlers for this bus
-export const actions = bus.use(actionsPlugin());
+
+// setHandler — binds the real handler to the action
+const realUser = setHandler(getUser, (id) => api.user(id));
+
+// actionsPlugin — the registry of bound handlers of this bus
+export const actions = bus.use(actionsPlugin([realUser]));
 ```
 
 ```js
 import { bus, actions } from "./bus";
 import { getUser } from "./user";
 
-bus.emit(getUser("1")); // nothing is bound: only an event
+const user = await bus.emit(getUser("1")); // the real handler answers
 
-const unregister = actions.handle(getUser, (id) => api.user(id));
-const user = await bus.emit(getUser("1"));
+// actions.handle — a newer binding wins, for example a fake in a test
+const restore = actions.handle(getUser, (id) => ({ id, name: "test" }));
+const fake = await bus.emit(getUser("1")); // the fake answers
 
-unregister();
+restore(); // the real handler answers again
 ```
 
-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).
+Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can bind handlers and remove them on unmount. More in [Actions](actions.md#bind-a-handler-later).
 
 ## 9. Mount a domain as a module
 

package/docs/hmr.md

@@ -1,5 +1,7 @@
 # Hot reload and development diagnostics
 
+> **Level F.** Read first: [Actions, jobs and modules](actions.md).
+
 Use this page in development with modules and hot reload. Skip until you mount domains with `modulePlugin`.
 
 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:
@@ -37,11 +39,43 @@ bus.use(devPlugin());
 
 - **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.** For the app of `modulePlugin` (or the `app` option) 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.
+- **Where a named listener was made.** For a listener with a `traceId`, it notes the file and the line of the `bus.on` call, while the listener is subscribed. [`graphLogger`](debugging-loops.md#read-a-report) shows it in a loop report, so you can open the handler that closes the loop.
+- **Handlers that ignore the signal.** When a handler emits after its task was aborted (a newer call of `latest`, an unmounted module), the bus drops that emit. One warning then names the handler and the event: the handler did not stop when it was cancelled, usually because `ctx.signal` never reached the request. [Details](#find-a-handler-that-ignores-the-signal)
+- **Options.** `abandoned: false`, `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.
 
+### Find a handler that ignores the signal
+
+A policy such as `latest` cancels the older call by aborting its `ctx.signal`. A handler that does not pass the signal to its request keeps running, and its result arrives after the newer one. The policy drops that result, so nothing looks wrong until the handler does something else with it.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // the signal is not passed, so an older request is not cancelled
+    const items = await fetch(`/api?q=${query}`).then((response) => response.json());
+    ctx.emit("results", items);
+  }),
+);
+```
+
+With `devPlugin`, the second `search` aborts the first call. When the first call then emits `results`, the bus drops the emit and the plugin warns once:
+
+```text
+[nanoeffects] the handler of "search" emitted "results" after its task was aborted, so the emit was dropped. The handler kept running after it was cancelled: pass ctx.signal to the request (fetch(url, { signal: ctx.signal })) or give ctx to an effect (retry(ctx, ...)).
+```
+
+The check lives in the plugin only: the policies and the bus carry no code for it, and in production `nanoeffects/dev` is empty. It sees the handlers that emit or subscribe with `ctx.on` after the cancel; a handler that never does is not seen.
+
+A linter finds the same mistake before the code runs, and much more of it: a handler with no `ctx`, a step that does not get the signal while another does, the calls of `Promise.all`, the callbacks of `retry` and `timeout`, a pause, a stream, `bus.emit` in a handler. [Keep the signal through a handler](pass-the-signal.md) lists every situation, what catches it and how to fix it, and shows the setup for ESLint, oxlint and Biome.
+
 ### Keep the import 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())` can stay without a guard: it touches nothing and costs a few bytes.

package/docs/loop-guard.md

@@ -0,0 +1,109 @@
+# Cut a loop with `loopGuardPlugin`
+
+> **Level F.** Read first: [Plugins](plugins.md#use-a-plugin). To find a loop before you cut it, see [Find and cut event loops](debugging-loops.md).
+
+Two handlers that emit each other's events never stop. A loop made of `await` and timers burns CPU and network. A loop made of microtasks freezes the page, because the browser never gets a turn to draw. A report cannot stop any of them. `loopGuardPlugin` can: it follows the chain of emits and refuses the emit that would pass a limit.
+
+Use it as a safety net, also in production. It needs no tracer and changes nothing while a chain stays under the limits. It is opt-in: a bus that does not use it behaves as before.
+
+## On this page
+
+- [Cut a loop](#cut-a-loop)
+- [Choose what happens at the limit](#choose-what-happens-at-the-limit)
+- [Limit the emits that come from outside](#limit-the-emits-that-come-from-outside)
+- [Leave a recursion out](#leave-a-recursion-out)
+- [Know what it does not do](#know-what-it-does-not-do)
+
+## Cut a loop
+
+The plugin counts how many times the same event is in the chain of emits that led to an emit. The chain follows `ctx.emit`, also across `await`, timers and microtasks. An emit that would pass a limit is refused, and the loop ends there. Other chains go on, and the next emit from outside starts a chain at zero.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+// loopGuardPlugin — refuses the emit that would pass a limit of a chain
+export const bus = createBus().use(
+  loopGuardPlugin({
+    maxRepeats: 50, // one event may be in a chain 50 times
+    maxDepth: 1000, // a chain may be 1000 emits long, whatever the names are
+  }),
+);
+```
+
+| Option | Default | Cuts |
+| ------ | ------- | ---- |
+| `maxRepeats` | 50 | The same event in one chain too often: a loop. |
+| `maxDepth` | 1000 | A chain that is too long, also when every event has a new name (`step/${n}`). |
+| `maxPerSecond` | none | Emits of one event from outside any handler that come too fast ([below](#limit-the-emits-that-come-from-outside)). |
+| `ignore` | none | Event names that the repeat count skips ([below](#leave-a-recursion-out)). |
+
+## Choose what happens at the limit
+
+`onLimit` says what the refused emit does. Either way the plugin reports the finding once for each path. The report has the path of the loop and never the payload.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { LoopError, loopGuardPlugin } from "nanoeffects/guard";
+
+export const bus = createBus().use(
+  loopGuardPlugin({
+    onLimit: "drop", // "drop" (default): the emit is not sent; "throw": it throws a LoopError
+    // report — replaces the default console.error
+    report: (finding) => console.error(finding.limit, finding.path.join(" → ")),
+  }),
+);
+
+// with onLimit: "throw", the emit that was refused throws, and the error names the path
+try {
+  bus.emit("cart/changed");
+} catch (error) {
+  if (error instanceof LoopError) {
+    console.log(error.limit, error.path);
+  }
+}
+```
+
+- **`"drop"`** is the default. The emit returns as if nobody listened, so no new error appears in an async handler.
+- **`"throw"`** shows the loop with a stack. In an async handler the error becomes a rejection: handle it with `onError`.
+
+A loop that is cut can leave the state of the app half done: the handlers that ran have done their part, the ones after the cut have not. Fix the loop, and keep the guard as a net.
+
+## Limit the emits that come from outside
+
+A component that emits on every render has no chain: each emit comes from outside any handler. `maxPerSecond` counts them for each event.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+// maxPerSecond — over 100 emits of one event in a second from outside are refused
+export const bus = createBus().use(loopGuardPlugin({ maxPerSecond: 100 }));
+```
+
+It is off by default, because a burst of many emits can be right (a stream of messages).
+
+## Leave a recursion out
+
+A chain that repeats on purpose is cut too. A handler that emits `tree/visit` for each level of a tree, or one that emits `tick` again after a timer for hours, passes `maxRepeats`. List its event in `ignore`. `maxDepth` still applies to it.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+export const bus = createBus().use(
+  loopGuardPlugin({
+    ignore: ["tree/visit"], // names, or a function of the name
+  }),
+);
+```
+
+## Know what it does not do
+
+- **It does not abort the chain.** It refuses one emit, at the edge where the limit is passed. The handlers that already run, run to the end.
+- **It follows `ctx.emit`.** A `bus.emit` called from inside a handler is not part of the chain: it starts a new one with the counts at zero. Use `ctx.emit` inside handlers.
+- **It does not find a loop.** To see the path of a loop, and loops that go through components, use `graphLogger` ([Find and cut event loops](debugging-loops.md)).

package/docs/migrating-from-effector.md

@@ -1,5 +1,7 @@
 # Coming from Effector
 
+> **Level E, for readers who know Effector.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
 
 ## On this page
@@ -31,7 +33,7 @@ nanoeffects has no store. `createStore` can be replaced by any store you like, f
 | event call `loaded(user)` | `bus.emit("loaded", user)` |
 | `createEffect(handler)` | a handler: `bus.on(event, handler)` |
 | effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
-| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)) |
+| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#the-state-of-a-job)) |
 | `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
 | `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
 | `sample({ filter })` | an `if` in the handler |
@@ -329,7 +331,7 @@ bus.on(
 ## What is different
 
 - **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
-- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)). Policies report to the job, so the flag also follows `latest`, `leading`, `debounce`, `throttle` and `queue`; that section says when to count instead. A running task is also visible through [Tracing](tracing.md).
+- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#the-state-of-a-job)). Policies report to the job, so the flag also follows `latest`, `leading`, `debounce`, `throttle` and `queue`; that section says when to count instead. A running task is also visible through [Tracing](tracing.md).
 - **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
 - **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
 - **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.

package/docs/migrating-from-mitt.md

@@ -1,6 +1,8 @@
-# Coming from mitt, nanoevents or EventEmitter
+# Coming from mitt and nanoevents
 
-Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, Node's `EventEmitter`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
+> **Level A, for readers who know mitt or nanoevents.** Read first: nothing: the bus is the same idea.
+
+Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
 
 ## When to switch
 
@@ -15,8 +17,8 @@ If handlers stay synchronous, keep your emitter. nanoeffects costs about 1.4 kB
 
 ## Find the equivalent
 
-| mitt / EventEmitter | nanoeffects |
-| ------------------- | ----------- |
+| mitt / nanoevents | nanoeffects |
+| ----------------- | ----------- |
 | `emitter.on("a", handler)` | `bus.on("a", handler)` |
 | `emitter.off("a", handler)` | call the function that `bus.on` returned, or `bus.off("a")` for all handlers of `a` |
 | `emitter.emit("a", payload)` | `bus.emit("a", payload)` |

package/docs/migrating-from-rxjs.md

@@ -1,5 +1,7 @@
 # Use nanoeffects next to RxJS
 
+> **Level E, for readers who know RxJS.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if your project uses RxJS and you wonder what nanoeffects takes over. It does not replace RxJS. The two split the work: RxJS shapes streams of values, nanoeffects runs the side effects that events start. It maps the operators, shows a search box and a polling loop both ways, and lists what stays in RxJS.
 
 ## Split the work

package/docs/migrating-from-saga.md

@@ -1,5 +1,7 @@
 # Coming from redux-saga
 
+> **Level E, for readers who know redux-saga.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if you know redux-saga and want to find the same job in nanoeffects. It maps the names, shows one saga rewritten, and lists what has no equivalent. It does not teach the library: start with the [Guide](guide.md).
 
 ## Find the equivalent

package/docs/motivation.md

@@ -1,16 +1,22 @@
 # Why nanoeffects exists
 
-Read this page to see why the library exists and when to pick it. The main reason is to take business logic and side effects out of React, Vue or Svelte components and write them as plain `async` functions, with cancellation, retries and a context for dependencies. The second part of the page is for SDKs, core libraries and micro-frontend shells, where a shared dependency is a shared risk. It does not teach the API: start with the [Guide](guide.md).
+> **Level A.** Read first: [README](../README.md).
 
-## The main reason: logic outside the UI
+Read this page to see why the library exists. It moves business logic and side effects out of React, Vue or Svelte components into plain `async` functions, with cancellation, retries and a context for dependencies. It does not teach the API: start with the [Guide](guide.md).
+
+## Moving logic out of the UI
 
 Components that hold requests, timers and races are hard to test and easy to break. The usual cure is services and pure functions outside the UI, and then every service needs the same things: to cancel work that is no longer wanted, to retry, to share dependencies, and to show what ran and why.
 
-The common tools ask a lot: redux-saga writes this logic as generators, and RxJS as streams and operators. nanoeffects keeps ordinary `async` functions and adds one idea, the `AbortSignal`. The event bus is its heart but not its value: any emitter can send events (`nanoevents` is about 100 bytes, and there are [dozens more](https://github.com/gajus/sister#similar-libraries)). What nanoeffects adds is cancellable tasks, policies and effects, a context that works as a small container for dependencies, actions and modules to group a feature, and [tracing](tracing.md) with an adapter for Redux DevTools. It also fits what a project already has: recipes and small adapters for [stores](stores.md) (Redux Toolkit, Zustand, MobX, Pinia), an [RxJS](migrating-from-rxjs.md) bridge, and helpers for [React](react.md), [Vue](vue.md) and [Svelte](svelte.md), so nothing has to be rewritten to start.
+The common tools ask a lot: redux-saga writes this logic as generators, and RxJS as streams and operators. nanoeffects keeps ordinary `async` functions and adds one idea, the `AbortSignal`.
+
+Another way to take logic out of the UI is a dependency injection (DI) container, such as the one in Angular or in any DI library. nanoeffects has no container, but it can do dependency injection at the level of the contract: a handler takes what it needs from `ctx`, and the bus decides what to give. See [Context fields](context.md).
 
-## When the constraint is a shared library
+The event bus is the heart of the library but not its value: any emitter can send events (`nanoevents` is about 100 bytes, and there are [dozens more](https://github.com/gajus/sister#similar-libraries)). What nanoeffects adds is cancellable tasks, policies and effects, a context that works as a small container for dependencies, actions and modules to group a feature, and [tracing](tracing.md) with an adapter for Redux DevTools. It also fits what a project already has: recipes and small adapters for [stores](stores.md) (Redux Toolkit, Zustand, MobX, Pinia), an [RxJS](migrating-from-rxjs.md) bridge, and helpers for [React](react.md), [Vue](vue.md) and [Svelte](svelte.md), so nothing has to be rewritten to start.
 
-A shared library (an SDK, a core package, a platform shell) is loaded by many apps. Whatever it depends on, the apps depend on too. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other.
+## Micro-frontends
+
+In micro-frontends every app can bring its own versions of the same libraries. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other. Different versions and copies also do more than work out of step: they load more code and use more resources than one agreed copy would. So the goal is a project that is as simple as possible, with as few shared dependencies that hold state as possible.
 
 Module Federation makes this visible. Each remote can bring its own copy unless every team agrees on a `singleton` and a version range. The [Nx guide on library versions](https://nx.dev/docs/kb/manage-library-versions-with-module-federation) lists the result: libraries with internal state conflict, and a missing method in one version breaks callers written for another.
 
@@ -23,25 +29,12 @@ Real cases from the libraries nanoeffects was compared with:
 | Effector | A library that uses `effector-react/scope` and is bundled into another project gets two instances. Its `Provider` is not seen by `useStore` of the app: "no scope found". | [effector#727](https://github.com/effector/effector/issues/727) |
 | RxJS | Two copies give two `Observable` classes. Types of one version do not fit the other, and operators added to one copy are missing on the other. The advice is "one version in `node_modules`". | [RxJS#2984](https://github.com/ReactiveX/rxjs/issues/2984), [neo4j-javascript-driver#978](https://github.com/neo4j/neo4j-javascript-driver/issues/978) |
 
-A library that is **not** a shared singleton cannot break this way. nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
-
-## Why not the alternatives
+nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
 
-| Option | Why it did not fit |
-| ------ | ------------------ |
-| Redux (with sagas) | A store and a provider shared by every consumer, which is the risk above. `redux-saga` also has no cheap way to get an answer back from an event: effects talk through the store. |
-| Effector | A graph with global identity. A version or scope mismatch between the SDK and the app reaches the whole infrastructure. |
-| Zustand | Good state, but it is a store, not a way to run and cancel work. It is the natural place to hold state next to nanoeffects: see [Stores](stores.md). |
-| RxJS | Flexible, but learning its ecosystem (operators, subjects, schedulers) is a high entry cost for every developer who touches the SDK. The package is also not small: [Bundlephobia](https://bundlephobia.com/package/rxjs) reports 17.3 kB minified and gzipped for 7.8.2. |
-
-## What the library does instead
+## What the library does
 
 - **No dependencies, no global state.** It is safe to ship inside an SDK next to whatever the host app runs. It does not need a `singleton` entry in the Module Federation config.
 - **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and actions are separate entries you import only when you need them. See [Package entries](package.md).
-- **Simple first.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
+- **Easy to start.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
 - **`emit` can return an answer.** An [action with a handler](actions.md) returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
 - **Easy to debug.** Event-driven code is hard to follow: you see an effect and not the event that caused it. Every task knows its parent, so [tracing](tracing.md) shows the chain of events, with loggers for the console, the Performance panel and Redux DevTools.
-
-## When this is not the right tool
-
-nanoeffects holds no state. If you need a store, keep Redux, Zustand or Effector and let the bus run the async work: [Stores](stores.md). If you already have streams everywhere, keep RxJS: [Use nanoeffects next to RxJS](migrating-from-rxjs.md).

package/docs/observable.md

@@ -1,5 +1,7 @@
 # Turn events into Observables
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) step 1.
+
 Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
 The same entry has `events`, which needs no stream library: it gives an event to a `for await` loop. See [Read an event with a `for await` loop](#read-an-event-with-a-for-await-loop).

package/docs/oop.md

@@ -1,5 +1,7 @@
 # Use the bus from a class
 
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus) step 1.
+
 Use this page when **your domain logic lives in classes**: a service, a store or a controller that needs the bus inside its methods. There are two ways to give a class the methods of a bus, and both remember what each instance subscribed to, so `dispose()` ends it all:
 
 | You want | Use |
@@ -7,7 +9,7 @@ Use this page when **your domain logic lives in classes**: a service, a store or
 | every `new Service()` to be an independent emitter | `extends Emitter` |
 | the instances to share a bus, or to use plugins | `extends extendBus(bus)` |
 
-If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
+If your logic is plain functions, stay with [modules](actions.md#modules): a module is the same idea without a class.
 
 ## On this page
 

package/docs/package.md

@@ -1,5 +1,7 @@
 # Choose a package entry
 
+> **Levels A to F.** Read first: [README](../README.md).
+
 Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
 
 ## Start with these three
@@ -28,7 +30,8 @@ Each row is optional. The "when" column says what need brings you to it.
 | `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) | Svelte components |
 | `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) | Vue components |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) | you look for leaks in development |
-| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) | you want to see what ran and why |
+| `nanoeffects/trace` | `createTracer`, the loggers (`graphLogger` finds event loops) and `tracePlugin` (names for the trace) | you want to see what ran and why |
+| `nanoeffects/guard` | `loopGuardPlugin`: refuses the emit that would pass a limit of a chain | a loop must not take the app down |
 
 The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists all of them, what each returns, and the order to use them in.