nanoeffects 0.4.0 → 0.5.0

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";

package/docs/package.md

@@ -6,9 +6,19 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | ------ | ------------- |
 | `nanoeffects` | `createBus`, the types |
 | `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
-| `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, … |
-| `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin` |
+| `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
+| `nanoeffects/actions` | `createAction`, `createCommand`, `createJob`, `createModule`, `modulePlugin`, `commandsPlugin` |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve` |
+| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) |
 | `nanoeffects/trace` | `createTracer` and the loggers |
+
+## Give the docs to an AI assistant
+
+The package ships two plain-text files for assistants that write code with it:
+
+- `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
+- `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+
+Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. Both match the installed version.

package/docs/policies.md

@@ -16,6 +16,7 @@ const bus = createBus();
 bus.on(
   "search",
   latest(async (query, { signal }) => {
+    // signal — lets latest cancel this request, not only drop its result
     await api.search(query, { signal });
   }),
 );

package/docs/react.md

@@ -0,0 +1,157 @@
+# Build a sign-up form in React
+
+Use this page when a React screen starts requests on user input and you need them not to race: a username check while typing, a submit button, a flaky network. It builds one registration form. The bus lives outside React; the component only subscribes to it.
+
+You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
+
+## See what goes wrong without a bus
+
+A registration form has three problems that `useEffect` and `fetch` leave to you:
+
+- **A stale answer.** The user types `ann`, then `anna`. The answer for `ann` arrives last and says the name is free, although `anna` is taken.
+- **A double submit.** A second click on "Sign up" sends a second request while the first one is running.
+- **A flaky network.** One failed request should be retried, but a "name is taken" answer should not.
+
+Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one place, outside the component.
+
+## Wire the bus once
+
+Put the bus and its handlers in their own file. Create it once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
+
+```js
+// registration.js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+import { debounce, latest, leading } from "nanoeffects/policies";
+
+// fetch rejects with a TypeError when the network fails; an HTTP error is a plain Error
+const isNetworkError = (error) => error instanceof TypeError;
+
+export const bus = createBus(); // the bus: created once, at the top of the module
+
+// debounce — wait 300 ms of quiet; latest — abort the check of the previous name
+bus.on(
+  "username/typed",
+  debounce(
+    300,
+    latest(async (name, ctx) => {
+      // api — your client; pass ctx.signal so latest can cancel the request itself
+      const available = await api.usernameAvailable(name, { signal: ctx.signal });
+      ctx.emit("username/checked", { name, available });
+    }),
+  ),
+);
+
+// leading — a second click is ignored while the first sign up is running
+bus.on(
+  "form/submitted",
+  leading(async (form, ctx) => {
+    const signUp = () => api.signUp(form, { signal: ctx.signal });
+    try {
+      // retry — up to 3 tries, 500 ms apart, and only when the network failed
+      const user = await retry(ctx, signUp, {
+        times: 3,
+        delay: 500,
+        shouldRetry: isNetworkError,
+      });
+      ctx.emit("form/succeeded", user);
+    } catch (error) {
+      ctx.emit("form/failed", error.message);
+    }
+  }),
+);
+```
+
+The handlers know nothing about React. A test can emit `username/typed` and read `username/checked` without rendering anything: the same wiring is tested in [`examples/registration-form.ts`](../examples/registration-form.ts) and `src/tests/registration-form.test.ts`.
+
+## Connect the form
+
+The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount.
+
+```jsx
+// SignUpForm.jsx
+import { useEffect, useState } from "react";
+import { bus } from "./registration"; // the bus of the previous snippet
+
+export function SignUpForm() {
+  const [name, setName] = useState("");
+  const [password, setPassword] = useState("");
+  const [available, setAvailable] = useState(null); // null: not checked yet
+  const [status, setStatus] = useState("idle"); // idle, sending, done or failed
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    // bus.on — listen for what the handlers report; each call returns an unsubscribe function
+    const unbindChecked = bus.on("username/checked", (result) => {
+      setAvailable(result.available);
+    });
+    const unbindSucceeded = bus.on("form/succeeded", () => setStatus("done"));
+    const unbindFailed = bus.on("form/failed", (message) => {
+      setStatus("failed");
+      setError(message);
+    });
+
+    return () => {
+      unbindChecked();
+      unbindSucceeded();
+      unbindFailed();
+    };
+  }, []);
+
+  function handleName(event) {
+    const value = event.target.value;
+    setName(value);
+    setAvailable(null);
+    bus.emit("username/typed", value); // bus.emit — the handler debounces and checks the name
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    setStatus("sending");
+    bus.emit("form/submitted", { name, password }); // a second click is dropped by leading
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={name} onChange={handleName} placeholder="Username" />
+      {available === false && <p>This name is taken</p>}
+      <input
+        type="password"
+        value={password}
+        onChange={(event) => setPassword(event.target.value)}
+      />
+      <button type="submit" disabled={status === "sending"}>Sign up</button>
+      {status === "failed" && <p>{error}</p>}
+      {status === "done" && <p>Welcome!</p>}
+    </form>
+  );
+}
+```
+
+The `disabled` button is only for the look. The form stays correct without it: `leading` drops a second submit while the first one runs.
+
+In development, React StrictMode runs the effect twice (subscribe, unsubscribe, subscribe). That is safe here, because the cleanup removes exactly what the effect added.
+
+## Stop running work when the form closes
+
+Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
+
+```js
+import { latest } from "nanoeffects/policies";
+
+// the username check of registration.js, with one new line
+const checkName = latest(async (name, ctx) => {
+  // ctx.on — a subscription of this task; aborting the task also drops the result
+  ctx.on("form/closed", () => ctx.abort());
+  const available = await api.usernameAvailable(name, { signal: ctx.signal });
+  ctx.emit("username/checked", { name, available });
+});
+```
+
+In the component, add `bus.emit("form/closed")` to the cleanup function of the effect. This is optional: skip it when finishing a request after unmount does no harm, as for a cheap check.
+
+## Where to go next
+
+- The policies behind this form: [Policies](policies.md).
+- `retry`, `timeout` and the other effects: [Effects](effects.md).
+- A state library instead of `useState`: [Stores](stores.md).