nanoeffects 0.4.0 → 0.6.0

package/docs/effects.md

@@ -84,16 +84,94 @@ Each attempt or call of a wrapper gets its own child context. Abort of the calle
 - `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 (backoff or jitter):
+A pause can be a function wherever a time is given. For retries with a cap and jitter, see [Back off between retries](#back-off-between-retries):
 
 ```js
-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 to once a minute
-await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+import { createBus } from "nanoeffects";
+import { delay, poll, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("sync", async (_, ctx) => {
+  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 to once a minute
+  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+});
 ```
 
 All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
 
+## Back off between retries
+
+Use this when a server or network fails under load. Retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. Make the pause grow with each attempt, and add jitter so clients spread out.
+
+The shortest form is a `delay` function. It needs no import:
+
+```js
+import { retry } from "nanoeffects/effects";
+
+const loadWithRetry = retry(loadUser, {
+  times: 5,
+  delay: (attempt) => 2 ** attempt * 100, // 200, 400, 800, 1600 ms
+});
+```
+
+When you also want a cap and jitter, build the function with `backoff`:
+
+```js
+import { backoff, retry } from "nanoeffects/effects";
+
+const loadWithRetry = retry(loadUser, {
+  times: 5,
+  // backoff — pause 200, 400, 800, … ms, never over 5 s, a random part of it
+  delay: backoff({ base: 200, max: 5000, jitter: true }),
+});
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `base` | pause before the second attempt, in ms (default `100`) |
+| `factor` | each pause is this many times longer (default `2`) |
+| `max` | longest pause, in ms (default none) |
+| `jitter` | `true` picks a random pause from 0 up to the computed one (default `false`) |
+
+- With `jitter: true` a pause can be close to 0, so treat `base` as a scale, not a minimum.
+- `retry` counts attempts from 1. `poll` counts calls from 0, so with `poll` the first pause is `base / factor`.
+- The result is a plain function `(attempt) => ms`, so it also fits `delay(ctx, …)`.
+
+## Put selected effects on `ctx`
+
+If handlers call the same helpers often, put them on the task once. A handler then destructures them like `signal`, with no `ctx` argument. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
+
+```js
+import { createBus } from "nanoeffects";
+import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
+
+// effectsPlugin — add race, all and delay to the context of every task; returns the same bus
+const bus = createBus().use(effectsPlugin({ race, all, delay }));
+
+bus.on("load", async (id, { race, all, delay }) => {
+  // race — same as race(ctx, …)
+  const result = await race({
+    data: ({ signal }) => fetchData(id, { signal }),
+    timeout: () => delay(5000), // delay — same as delay(ctx, 5000)
+  });
+  if ("timeout" in result) throw new Error("timed out");
+
+  // all — same as all(ctx, …)
+  const { user, posts } = await all({
+    user: ({ signal }) => fetchUser(id, { signal }),
+    posts: ({ signal }) => fetchPosts(id, { signal }),
+  });
+});
+```
+
+- The key is the name the effect gets on `ctx`. `race`, `all`, `allSettled`, `take` and `delay` are typed by hand.
+- Your own function works too if its first parameter is `{ signal }` (an *effect*): `effectsPlugin({ fetchJson })` gives `ctx.fetchJson(url)`. TypeScript removes the first parameter from its type; for a generic function see [keep a generic effect generic](scope.md#keep-a-generic-effect-generic).
+- Leave `retry`, `timeout` and `poll` out: bound to the task they would look like their handler wrappers.
+- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
+- Free forms keep working: `race(ctx, …)`.
+
 ## Tie a promise to the task signal
 
 `delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
@@ -179,7 +257,7 @@ bus.on("login", async (user, ctx) => {
 ```
 
 - Sees only events emitted after the call, takes one, and unsubscribes.
-- `options.predicate` skips payloads it rejects.
+- `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
 - `options.signal` stops the wait (how a `race` or `timeout` starter cancels it).
 - On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
 

package/docs/guide.md

@@ -47,6 +47,28 @@ bus.on("tick", () => {});
 bus.off(); // clear every subscription
 ```
 
+### Listen to every event
+
+`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
+import { createBus } from "nanoeffects";
+
+const bus = createBus();
+
+// "*" — runs for every event, after the listeners of that event
+const unbind = bus.on("*", (payload, ctx) => {
+  console.log(ctx.type, payload);
+});
+
+bus.emit("greet", "Ada"); // greet Ada
+bus.emit("moved", { x: 1, y: 2 }); // moved { x: 1, y: 2 }
+unbind();
+```
+
+- An event that only `"*"` listens to counts as heard, so `onUnhandled` does not fire for it.
+- `bus.off("*")` removes every `"*"` listener; `bus.off()` clears the whole bus, `"*"` included.
+
 ## 2. Use the handler context
 
 The second argument is the **task** context for this call. Emit further events through it. Pass `ctx.signal` to `fetch` when you cancel work.
@@ -294,6 +316,8 @@ Modules also make [hot reload](hmr.md) work. Full API in [Actions](actions.md);
 Describe events once when you want `on` / `emit` checked. An event without data is `void`. Skip this while you are learning the bus.
 
 ```ts
+import { createBus } from "nanoeffects";
+
 // Events — event name → payload for this bus (checker only)
 type Events = {
   greet: string;

package/docs/migrating-from-effector.md

@@ -0,0 +1,293 @@
+# Coming from Effector
+
+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.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Hold state (`createStore`, `combine`, `restore`) | Effector, or any store: [Stores](stores.md) |
+| Derive state from events (`.on`, `sample` into a store) | Effector, or any store |
+| Run a request when an event happens, cancel, retry, time out, trace | nanoeffects |
+
+nanoeffects has no store. `createStore` can be replaced by any store you like, for example Zustand: a store and its `set` do the job of `createStore` and `.on`. [Stores](stores.md) shows how each of Zustand, Redux, MobX, Jotai and others calls the bus. If you keep Effector, use nanoeffects only for the effects that `createEffect` runs with little control over overlapping calls.
+
+## Find the equivalent
+
+| Effector | nanoeffects |
+| -------- | ----------- |
+| `createEvent()` | an event name on the bus, or [`createAction`](actions.md) |
+| 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` | not provided: keep a flag in your store, or read it from [Tracing](tracing.md) |
+| `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 |
+| `debounce`, `throttle` from patronum | [`debounce`, `throttle`](policies.md) (same rules as lodash, checked in tests) |
+| take only the last effect call | [`latest`](policies.md) |
+| `attach` | a [context field](context.md): the handler reads it from `ctx` |
+| `fork()` and scope | one `createBus()` per scope |
+| `createStore`, `combine`, `restore` | any store, such as Zustand, Redux, MobX or Jotai: see [Stores](stores.md) |
+| `watch`, `createWatch` | `bus.on(event, handler)` |
+| `event.prepend(fn)` | a function that you write, `(event) => ({ key, value })`; the bus needs nothing |
+| `useStoreMap({ store, keys, fn })` | a selector of your store; with `useState` the component keeps the value |
+| `event.watch((e) => e.preventDefault())` | call `event.preventDefault()` in the `onSubmit` handler |
+
+## Rewrite an effect
+
+A search that runs on every query, and reacts to the result:
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+// Effector
+import { createEffect, createEvent, createStore, sample } from "effector";
+
+const queryChanged = createEvent();
+const searchFx = createEffect((query) => api.search(query));
+const $items = createStore([]).on(searchFx.doneData, (_, items) => items);
+
+sample({ clock: queryChanged, target: searchFx });
+```
+
+If the user types fast, several `searchFx` calls overlap, and the old ones are not cancelled. The same job in nanoeffects, with the old request cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer query aborts the request in flight
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("found", items);
+});
+
+bus.on("query-changed", debounce(300, search)); // debounce: run after 300 ms of quiet
+```
+
+The store (`$items`) is not here. Keep it in Effector and update it from the `found` event, or replace it with a store of your choice. The next example does that with Zustand.
+
+### Keep the state in Zustand
+
+Without Effector, something must hold `$items`. A Zustand store does it: `create` replaces `createStore`, and `setState` replaces `.on(searchFx.doneData, …)`. The handler writes the result to the store directly, so the `found` event is not needed. A component reads the store with a selector, as `useUnit($items)` did.
+
+```jsx
+// search-zustand.jsx
+import { create } from "zustand";
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+// create — Zustand: the store replaces $items
+const useSearchStore = create(() => ({ items: [] }));
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest — a newer query aborts the request in flight; debounce — wait 300 ms of quiet
+const search = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  useSearchStore.setState({ items }); // Zustand: replaces .on(searchFx.doneData, …)
+});
+
+bus.on("query-changed", debounce(300, search));
+
+export function Search() {
+  const items = useSearchStore((state) => state.items); // Zustand: a selector reads items
+
+  return (
+    <div>
+      <input onChange={(event) => bus.emit("query-changed", event.target.value)} />
+      <ul>
+        {items.map((item) => (
+          <li key={item.id}>{item.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+`bus.emit("query-changed", …)` in `onChange` does the work of calling the `queryChanged` event. To also start a task when the store changes, see [Zustand in Stores](stores.md#zustand).
+
+## Rewrite a form
+
+The form from the [Forms recipe of the Effector docs](https://effector.dev/en/recipes/react/forms/) has five parts: an event for a change of a field (`fieldUpdate`), a store for the values (`$form`), an event for the submit (`formSubmitted`), an effect that sends them (`sendFormFx`), and a `sample` that reads the store when the form is submitted. Four of them keep state or wire units together. Only the effect has a counterpart in nanoeffects.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```jsx
+// Effector (adapted from the Effector docs)
+import { createEffect, createEvent, createStore, sample } from "effector";
+import { useStoreMap } from "effector-react";
+
+const formSubmitted = createEvent();
+const fieldUpdate = createEvent();
+
+const sendFormFx = createEffect((params) => {
+  console.log(params);
+});
+
+const $form = createStore({});
+$form.on(fieldUpdate, (form, { key, value }) => ({ ...form, [key]: value }));
+
+// sample: when the form is submitted, read $form and run the effect with it
+sample({ clock: formSubmitted, source: $form, target: sendFormFx });
+
+// prepend: turn a DOM event into the { key, value } that fieldUpdate takes
+const handleChange = fieldUpdate.prepend((event) => ({
+  key: event.target.name,
+  value: event.target.value,
+}));
+
+const Field = ({ name, type, label }) => {
+  const value = useStoreMap({
+    store: $form,
+    keys: [name],
+    fn: (values) => values[name] ?? "",
+  });
+
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={handleChange} />
+    </div>
+  );
+};
+
+const App = () => (
+  <form onSubmit={formSubmitted}>
+    <Field name="login" label="Login" />
+    <Field name="password" type="password" label="Password" />
+    <button type="submit">Submit!</button>
+  </form>
+);
+
+formSubmitted.watch((event) => {
+  event.preventDefault();
+});
+```
+
+The same form with nanoeffects. The values live in React state: nanoeffects holds none, and any store of [Stores](stores.md) works the same way. The effect becomes a handler of the submit event. The values travel in the event, so no `sample` and no `source` are needed. First the bus, in its own file:
+
+```js
+// form-bus.js
+import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: events and their handlers
+
+// bus.on — the job of sendFormFx: runs when the form is submitted
+bus.on("form/submitted", (values) => {
+  console.log(values);
+});
+```
+
+Then the form. `useState` does the work of `$form`, `fieldUpdate` and `prepend`; the event handler does the work of the `watch` that called `preventDefault`:
+
+```jsx
+// App.jsx
+import { useState } from "react";
+import { bus } from "./form-bus"; // the bus of the previous snippet
+
+function Field({ name, type, label, value, onChange }) {
+  return (
+    <div>
+      {label} <input name={name} type={type} value={value} onChange={onChange} />
+    </div>
+  );
+}
+
+export function App() {
+  const [form, setForm] = useState({}); // the values of the form, as $form held them
+
+  // one handler for every field, as handleChange was
+  function handleChange(event) {
+    const { name, value } = event.target;
+    setForm((current) => ({ ...current, [name]: value }));
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault(); // the page must not reload; no separate watcher is needed
+    bus.emit("form/submitted", form); // bus.emit — the values go in the event
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Field name="login" label="Login" value={form.login ?? ""} onChange={handleChange} />
+      <Field
+        name="password"
+        type="password"
+        label="Password"
+        value={form.password ?? ""}
+        onChange={handleChange}
+      />
+      <button type="submit">Submit!</button>
+    </form>
+  );
+}
+```
+
+`useStoreMap` re-renders only the field whose value changed. Here every field re-renders with the form, which is fine for a small form. If it matters, use the selector of your store (Zustand and Jotai have one).
+
+If the values live in a store outside React, give the store to the handlers with `createBus({ context: { store } })` ([Context fields](context.md)) and read it in the handler, as `sample` read `$form`.
+
+### Replace the log with a request
+
+`sendFormFx` only logs. A real sign-up sends a request, and then the double click and the network matter. `leading` drops a second submit while the first one runs, and `ctx.signal` lets the request be cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and their handlers
+
+// leading — a second submit is ignored while the request is running
+bus.on(
+  "form/submitted",
+  leading(async (values, ctx) => {
+    // api — your client; ctx.signal lets the request be cancelled
+    await api.signUp(values, { signal: ctx.signal });
+  }),
+);
+```
+
+Retrying a failed network request, and cancelling when the form closes, are in [Build a sign-up form in React](react.md).
+
+## Use both in one app
+
+Keep the Effector stores, and run the effects on the bus. A store calls the bus through `bus.emitter`, and the handler sends the result back as an event that the store listens to.
+
+<!-- docs-check: skip - needs effector, which the project does not depend on -->
+```js
+import { createEvent, createStore } from "effector";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const queryChanged = createAction("query/changed"); // a plain action creator
+
+const found = createEvent(); // Effector: the result comes back as an event
+const $items = createStore([]).on(found, (_, items) => items);
+const $query = createStore("");
+
+// watch calls back on every change of the store; bus.emitter turns it into an emit
+$query.watch(bus.emitter(queryChanged));
+
+bus.on(
+  queryChanged,
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    found(items); // back to Effector
+  }),
+);
+```
+
+## 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)).
+- **No `pending`.** A running task is visible through [Tracing](tracing.md), not through a store. A flag in your store set at the start and the end of the handler does the job.
+- **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`.
+- **The event carries the data.** `sample({ source })` reads a store at the moment of the clock. Here the sender puts the values in the event (`bus.emit("form/submitted", form)`), or the handler reads a store from a [context field](context.md).
+- **Scopes are buses.** `fork()` becomes a `createBus()` per scope (a test, a request on the server).

package/docs/migrating-from-rxjs.md

@@ -0,0 +1,127 @@
+# Use nanoeffects next to RxJS
+
+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 one search box both ways, and lists what stays in RxJS.
+
+## Split the work
+
+| Job | Use |
+| --- | --- |
+| Start a request when something happens, cancel it when a newer one arrives, retry it, time it out | nanoeffects |
+| Know which task started which, log and trace it | nanoeffects ([Tracing](tracing.md)) |
+| Combine several streams, keep a running value, buffer, window, merge over time | RxJS |
+| Work with a stream as a value (`map`, `scan`, `combineLatest`) | RxJS |
+
+A handler in nanoeffects is one function per event. A pipeline in RxJS is a chain of operators over a stream. If your pipeline is a few operators that end in `switchMap` and a request, it fits a handler with a policy and is shorter. If it combines streams, it stays.
+
+## Find the equivalent
+
+| RxJS | nanoeffects |
+| ---- | ----------- |
+| `mergeMap` | `bus.on(event, handler)`: every event starts a task |
+| `switchMap` | [`latest`](policies.md) |
+| `exhaustMap` | [`leading`](policies.md) |
+| `concatMap` | [`queue`](policies.md) |
+| `debounceTime` | [`debounce`](policies.md) |
+| `throttleTime` | [`throttle`](policies.md) |
+| `groupBy` + `switchMap` | `latest(handler, { key })` |
+| `retry`, `retryWhen` | [`retry`, `backoff`](effects.md) |
+| `timeout` | [`timeout`](effects.md) |
+| `interval` + `switchMap` | [`poll`](effects.md) |
+| `takeUntil(stop$)` | `ctx.signal`, and [`take`](effects.md) to wait for the stop event |
+| `forkJoin` | [`all`](effects.md) |
+| `race` | [`race`](effects.md) |
+| `firstValueFrom(fromEvent(…))` | [`take(ctx, event)`](effects.md) |
+| `Subject` | `bus.emit` and `bus.on` |
+| `map`, `filter`, `scan`, `combineLatest`, `buffer`, `window`, `share` | stay in RxJS |
+| `distinctUntilChanged` | a check in the handler, or in the store subscription (see [Stores](stores.md)) |
+
+A policy and an operator differ in one thing. `switchMap` drops the old inner stream. `latest` aborts the old task through its `signal`, so a `fetch` that got the signal stops. Pass the signal on, or the work goes on in the background.
+
+## Rewrite a search box
+
+The same job in RxJS: wait for a pause, skip repeats, cancel the old request.
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+// RxJS
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map, switchMap } from "rxjs/operators";
+
+fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+    switchMap((query) => api.searchStream(query)),
+  )
+  .subscribe((items) => render(items));
+```
+
+The same job in nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+// latest: a newer search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: run after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+
+bus.on("results", (items) => render(items));
+
+const input = document.querySelector("#search"); // the search box
+input.addEventListener("input", (event) => bus.emit("typed", event.target.value));
+```
+
+The skip of repeated values is not here. Add `if (query === lastQuery) return;` to the handler, or keep that one step in RxJS (next section).
+
+## Use both in one app
+
+Keep RxJS where a stream is how you think, and let events cross to the bus in either direction.
+
+**Bus to RxJS.** `createObserve(bus)` gives an Observable of an event ([Observables](observable.md)).
+
+**RxJS to bus.** `bus.emitter(action)` returns a callback that emits the action, so it is the argument of `subscribe` ([Stores](stores.md) has the plugin).
+
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
+```js
+import { combineLatest } from "rxjs";
+import { createBus } from "nanoeffects";
+import { createAction, emitterPlugin } from "nanoeffects/actions";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus().use(emitterPlugin()); // adds bus.emitter
+
+const filtersChanged = createAction("filters/changed"); // a plain action creator
+
+// RxJS: combine two streams into one value; nanoeffects does not do that
+const subscription = combineLatest([query$, category$]).subscribe(
+  bus.emitter(filtersChanged), // calls bus.emit(filtersChanged(value))
+);
+
+// nanoeffects: one cancellable request per change of the filters
+bus.on(
+  filtersChanged,
+  latest(async ([query, category], { signal }) => {
+    const items = await api.search(query, category, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+The subscription is not tied to a task. Call `subscription.unsubscribe()` when the screen goes away.
+
+## What is different
+
+- **No streams of values.** A handler gets one payload and runs a task. There is no `pipe`, no operator for the values that follow.
+- **Abort replaces unsubscribe for work in flight.** A stopped task is stopped through its `signal`. Pass it to `fetch` or to the client.
+- **Errors are not part of the stream.** A failed task rejects its own promise. Without `onError` on the bus nobody else hears it ([Errors](errors.md)).
+- **No completion.** An event bus does not end. A task ends when its work ends or its signal aborts.
+- **No marble tests.** Test with the real handler and fake timers.

package/docs/migrating-from-saga.md

@@ -0,0 +1,93 @@
+# Coming from redux-saga
+
+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
+
+| redux-saga | nanoeffects |
+| ---------- | ----------- |
+| `takeEvery` | `bus.on(event, handler)` |
+| `takeLatest` | [`latest`](policies.md) |
+| `takeLeading` | [`leading`](policies.md) |
+| `debounce`, `throttle` | [`debounce`, `throttle`](policies.md) (same rules as lodash) |
+| `call(fn, x)` | `await ctx.run(task, x)` |
+| `fork(fn, x)` | `ctx.run(task, x)` without `await` |
+| `spawn(fn, x)` | `ctx.emit(event, x)` or `bus.emit(event, x)` |
+| `put(action)` | `ctx.emit(action)` |
+| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md) |
+| `select` | a [context field](context.md), such as `store` |
+| `all`, `race` | [`all`, `race`](effects.md) |
+| `retry`, `delay` | [`retry`, `delay`](effects.md) |
+| `cancel(task)` | `ctx.abort()` on the context, or a newer call under `latest` |
+| `eventChannel` | `bus.emitter(action)` as the callback of the subscription |
+| `actionChannel` | [`queue`](policies.md) and the other policies |
+
+## Rewrite a saga
+
+A saga that searches on every new query, cancels the older request, and retries a failed one:
+
+<!-- docs-check: skip - redux-saga code, not nanoeffects -->
+```js
+// redux-saga
+function* search({ payload }) {
+  const items = yield retry(3, 1000, api.search, payload);
+  yield put(found(items));
+}
+function* watchSearch() {
+  yield takeLatest("search", search);
+}
+```
+
+The same job in nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // the bus: events and handlers
+
+const search = (query, { signal }) => api.search(query, { signal });
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // latest: a newer "search" aborts this run; ctx.signal is aborted
+    const load = retry(search, { times: 3, delay: 1000 }); // retry: up to 3 attempts, 1 s apart
+    const items = await ctx.run(load, query); // child task, aborted with this handler
+    ctx.emit("found", items); // like put
+  }),
+);
+```
+
+Tasks are plain `async` functions. `ctx.signal` replaces `cancel`: pass it to `fetch` or to your client, and the request stops.
+
+## Start a task without waiting
+
+`fork` and `spawn` differ in what happens when the caller is aborted. Pick by that.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // the bus: events and handlers
+
+const loadSidebar = (_, { signal }) => api.sidebar({ signal });
+
+bus.on("page-opened", async (_, ctx) => {
+  // like fork: a child of this task, aborted with it
+  const warmUp = ctx.run(loadSidebar);
+  warmUp.catch(console.error); // nobody awaits it, so handle the error here
+
+  // like spawn: a new task, not stopped when this one is aborted
+  ctx.emit("analytics", { page: "home" });
+});
+```
+
+## What is different
+
+- **Errors go up only through `await`.** `await ctx.run(task)` and `all(ctx, …)` throw the error of a child to the caller. A child that nobody awaits does not abort its parent, as a forked child does in redux-saga: handle it yourself, as above. See [Errors](errors.md).
+- **Abort goes down.** Aborting a task aborts its children. A child does not abort its siblings.
+- **Effects are not data.** `yield call(fn)` returns a description that a test can compare. Here `await` calls the function. Test with the real handler and fake timers, as the tests of this library do.
+- **No generators.** Sequential flows are `async` functions with `await take(ctx, event)`.
+- **No `END` of a channel.** A task stops when its signal aborts.
+- **One payload.** A task has one argument, so pass an object where a saga passes several.

package/docs/observable.md

@@ -4,6 +4,7 @@ Use this page only when you already work in Observables / RxJS. Prefer `bus.on`
 
 `createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
 
+<!-- docs-check: skip - needs rxjs, which the project does not depend on -->
 ```js
 import { from } from "rxjs";
 import { debounceTime, distinctUntilChanged, switchMap } from "rxjs/operators";