nanoeffects 0.0.0-stage → 0.2.0

package/docs/effects.md

@@ -0,0 +1,137 @@
+# Effects and cancellation
+
+An abort only raises a flag: your code decides to stop. `nanoeffects/effects` has helpers for the usual cases.
+
+`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function). `cancellable(ctx, executor)` is a promise tied to the task signal; it works like `new Promise`, but the executor gets one object, `{ resolve, reject, onCancel }`, with `onCancel` for cleanups:
+
+```ts
+import { cancellable } from "nanoeffects/effects";
+
+bus.on(
+  "wait",
+  latest((_, ctx) =>
+    cancellable(ctx, ({ resolve, onCancel }) => {
+      const timer = setTimeout(resolve, 5000);
+      onCancel(() => clearTimeout(timer));
+    }),
+  ),
+);
+```
+
+- If the task aborts before the promise settles, cleanups run (last registered first) and the promise rejects with the abort reason.
+- If the task is already aborted, the executor does not run.
+- After the promise settles, the abort listener is removed and cleanups are dropped.
+
+`onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if already aborted) and returns a function that unsubscribes:
+
+```ts
+import { onAbort } from "nanoeffects/effects";
+
+bus.on("connect", (url, ctx) => {
+  const socket = new WebSocket(url);
+  onAbort(ctx, () => socket.close());
+});
+```
+
+## allSettled
+
+`allSettled(ctx, effects)` is `all` that waits for every starter and never fails because of one: each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`, in the shape of the input (object or array). Nothing is cancelled when a starter fails. Only an abort of `ctx` rejects it.
+
+```ts
+const { user, posts } = await allSettled(ctx, {
+  user: ({ signal }) => fetchUser(id, { signal }),
+  posts: ({ signal }) => fetchPosts(id, { signal }),
+});
+
+if (user.status === "fulfilled") render(user.value);
+```
+
+## Subscribing from a task: ctx.on, ctx.off, take
+
+A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts, so it cannot outlive the work that needed it:
+
+```ts
+bus.on("watch", (_, ctx) => {
+  ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
+});
+```
+
+- The returned function unsubscribes sooner. After the task is aborted, `ctx.on` does nothing.
+- A policy passes its handler a child context, so under `latest` the subscriptions of a superseded run end with it.
+- `ctx.off` is the bus `off`: `ctx.off(event)` clears every handler of the event, not only the task's.
+
+`take(ctx, event, options?)` waits for the next `event` and resolves with its payload:
+
+```ts
+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);
+
+  // 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 }),
+  );
+});
+```
+
+- It sees only events emitted after the call, takes one, and unsubscribes.
+- `options.predicate` skips payloads it rejects; `options.signal` stops the wait, which is how a `race` or `timeout` starter cancels it.
+- On abort of the task or of `options.signal` it unsubscribes and rejects with the abort reason. It is traced as a `take` group.
+
+## 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) => {
+  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.
+- A pause can be a function wherever a time is given, for backoff or jitter: `retry`'s `delay` gets `(attempt, error)`, `poll`'s `ms` gets the number of the call the pause leads to, and `delay` itself takes a function called once when it starts:
+
+```ts
+retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, ...
+poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows down to once a minute
+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.
+
+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

@@ -0,0 +1,23 @@
+# Errors and unheard events
+
+`emit` is a plain loop over the handlers, like in nanoevents: if a handler throws, the remaining handlers are skipped and the error reaches the caller of `emit`. A rejected promise of an async handler is left unhandled.
+
+Pass `onError` to isolate handlers instead. Then every handler runs, and thrown errors and rejections of async handlers (including ones wrapped in `latest`, `debounce` and the like) go to `onError`; an `onError` that throws is logged to `console.error`.
+
+```ts
+const bus = createBus<Events>({
+  onError: (error, { type, payload }) => report(error, type, payload),
+});
+```
+
+## Events that nobody listens to
+
+A typo in an event name, `emit("serch")`, does nothing and says nothing. `onUnhandled` is called when an event is emitted and nobody listens to it (a listener of every event, `"*"`, counts). It is not called for commands, which always have a handler to run. Use it as a warning in development:
+
+```ts
+const bus = createBus<Events>({
+  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

@@ -0,0 +1,36 @@
+# 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.
+
+## 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, whose signals abort. So the new version of a module file only has to mount again, and nothing piles up.
+
+- **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.
+
+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`
+
+`bus.use(devPlugin({ app }))` reports what is easy to miss while developing:
+
+```ts
+import { devPlugin } from "nanoeffects/dev";
+
+const app = bus.use(modulePlugin([userModule]));
+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.
+- **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.
+
+It changes no behavior: it wraps `bus.on`, `app.mount` and `app.unmount` and adds messages.
+
+### 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, 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/observable.md

@@ -0,0 +1,22 @@
+# Observable: events as streams
+
+`createObserve(bus)` from `nanoeffects/observable` turns an event of the bus into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is, and nothing here depends on them.
+
+```ts
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";
+import { createObserve } from "nanoeffects/observable";
+
+const observe = createObserve(bus);
+
+// events of the bus as a stream
+from(observe("typed"))
+  .pipe(debounceTime(300), distinctUntilChanged(), switchMap(searchRequest))
+  .subscribe((items) => bus.emit("results", items));
+```
+
+- `observe(event)` returns an Observable of the payloads of that event. Each `subscribe` is a `bus.on` of its own, and `unsubscribe()` removes it.
+- `subscribe` takes a function or an object with `next`.
+- The stream never completes and never fails: events are the only thing that arrives. Errors of the handler of the subscriber belong to the subscriber.
+- A subscription made this way is not tied to a task, so end it yourself: `onAbort(ctx, subscription.unsubscribe)` inside a task, or with the signal of a module.
+- For cancellation, policies and tracing keep to `bus.on` with `latest`, `debounce`, `queue`: they know about tasks. The Observable is for the places where a stream is already the way you work.

package/docs/policies.md

@@ -0,0 +1,53 @@
+# Policies
+
+A policy wraps a handler and decides what happens when calls overlap. Every policy takes `key` in its options (see below), so each key has its own state.
+
+| Policy                         | Overlapping calls                                                          |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| `latest(fn)`                   | the previous run is aborted and its result dropped                        |
+| `leading(fn)`                  | new calls are dropped while a run is going                                |
+| `debounce(ms, fn, options?)`   | run after `ms` of quiet                                                    |
+| `throttle(ms, fn, options?)`   | at most one run per `ms`                                                   |
+| `queue(fn, options?)`          | one after another, in order                                                |
+
+`debounce` and `throttle` take `leading` and `trailing`:
+
+- `throttle(ms, fn)` works like lodash `throttle` (and patronum): a call made when the throttle is idle, at least `ms` after the previous call and the previous run, runs at once (`leading`, default `true`); calls made while it waits are held, and the latest of them runs when the window closes (`trailing`, default `true`). Under a steady stream of calls it runs every `ms`. `leading: false` makes even the first call wait for the end of its window; `trailing: false` drops the calls made during a window.
+- `debounce(ms, fn)` runs the last call after `ms` of quiet (`trailing`, default `true`). `leading: true` also runs the first call of a burst at once, and then the trailing run happens only if more calls follow it. `leading: true, trailing: false` runs only the first call of a burst.
+- With both options `false` nothing runs.
+- `throttle` and `debounce` are checked against lodash itself: the tests feed random sequences of calls to both and compare the moments `fn` runs.
+
+`key` gives each key its own state, so calls with different keys do not affect each other:
+
+```ts
+// one latest run per user instead of one for all of them
+bus.on("load", latest(loadUser, { key: (user) => user.id }));
+
+// uploads of the same file go one after another, different files in parallel
+bus.on("upload", queue(upload, { key: (file) => file.name }));
+```
+
+The state of a key is dropped when that key goes idle, so keys can be unbounded (ids, urls).
+
+## Queue
+
+`queue(fn, options?)` runs the calls of a handler one after another, in the order they arrived, instead of dropping or replacing them like `leading` and `latest` do:
+
+```ts
+import { queue } from "nanoeffects/policies";
+
+bus.on(
+  "save",
+  queue(async (draft, { signal }) => {
+    await api.save(draft, { signal });
+  }),
+);
+
+bus.emit("save", a); // runs now
+bus.emit("save", b); // waits for a, then runs
+```
+
+- `concurrency` (default 1) is how many calls may run at the same time.
+- `limit` caps how many calls may wait, and `overflow` says what to drop when the line is full: the new call (`"drop-new"`, the default) or the oldest waiting one (`"drop-old"`). A dropped call resolves with `undefined`. `queue(fn, { limit: 1, overflow: "drop-old" })` keeps only the latest call while one is running and runs it when the current one is done; `limit: 0` lets nothing wait.
+- Every call returns a promise with the result of its own run. An error rejects only that call and the queue goes on.
+- A waiting call whose task aborts is skipped and resolves with `undefined`. When the task of a running call aborts, its slot is freed at once and its result is dropped, so pass `signal` to what `fn` does: a `fn` that ignores it can overlap with the next run.

package/docs/semantics.md

@@ -0,0 +1,7 @@
+# Semantics
+
+- **An aborted task delivers no result.** If the task aborts before a promise settles, the promise rejects with the abort reason, even if the value was just produced in the same tick. `latest`, `debounce`, `all`, `race`, `take` and the rest follow this rule.
+- **`emit` is a plain, synchronous loop** (see "Errors in handlers"). A `ctx.emit` inside a handler is the same call: without `onError` an error of a nested handler is thrown into the handler that emitted; with `onError` it goes there and `ctx.emit` does not throw.
+- **Rejections of async handlers** are not handled for you. Without `onError` they are unhandled rejections, which end a Node process by default. Use `onError` for async handlers.
+- **`leading` releases its lock when the task aborts**, not only when `fn` settles. A `fn` that ignores the abort signal can then overlap with the next run, so pass `ctx.signal` to what `fn` does.
+- **Effects start their function synchronously**, so an event emitted right after the call reaches a `take` inside it.

package/docs/stores.md

@@ -0,0 +1,50 @@
+# Redux, Zustand, MobX
+
+## Redux
+
+`createEffectsMiddleware()` from `nanoeffects/redux` gives you a bus and the Redux middleware that feeds it: the effects of an app in one place, without sagas. Every action goes to the bus after the reducers have handled it, so a handler that reads the store sees the new state, and every task gets `ctx.store` (`dispatch` and `getState`).
+
+```ts
+type Events = { userRequested: string } & WithContext<{ store: ReduxStoreApi<RootState> }>;
+
+const effects = createEffectsMiddleware<Events>();
+
+const store = configureStore({
+  reducer,
+  middleware: (getDefault) => getDefault().concat(effects.middleware),
+});
+
+effects.bus.on(userRequested, latest(async (id, { store, signal }) => {
+  store.dispatch(userLoaded(await fetchUser(id, { signal })));
+}));
+```
+
+It looks after what is easy to get wrong:
+
+- **A handler does not loop on its own action.** An action that a handler dispatches through `ctx.store` and that has the type the handler works on does not go back to the bus. The action is not marked or changed: the middleware remembers which task dispatched it. Other handlers of that type do not get it either. Longer cycles, `a` to `b` to `a`, are yours to avoid.
+- **A failing handler does not break `dispatch`.** Errors go to `onError` (default `console.error`), as in Redux Toolkit listeners. Reducers still throw to the caller.
+- **The store gets to the tasks by itself**, though the bus is made before the store: `ctx.store` appears when the middleware is added.
+
+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.
+
+```ts
+// Zustand
+const stop = store.subscribe((state, previous) => {
+  if (state.user !== previous.user) bus.emit(userChanged, state.user);
+});
+
+// MobX
+const stop = reaction(() => store.user, (user) => bus.emit(userChanged, user));
+
+bus.on(userChanged, latest((user, { signal }) => sync(user, { signal })));
+```
+
+Stop watching with what the store returned: `onAbort(ctx, stop)` inside a task, or `m.signal.addEventListener("abort", stop)` in a module.
+
+The other way, give the store to the tasks, `createBus({ context: { store } })`, and change it from a handler: `setState` for Zustand, an action of the MobX store (it wraps `runInAction`). A handler that changes the value it was started by emits the event again, so watch the smallest part of the state. For a MobX `flow`, `onAbort(ctx, () => promise.cancel())` cancels it with the task.