nanoeffects 0.29.0 → 0.31.0

package/docs/react.md

@@ -1,30 +1,34 @@
 # 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.
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
+The task is a registration form. While the user types a name, the form asks the backend whether it is free, and the "Sign up" button submits the form. That makes the requests race: the answer to an old input can arrive after the answer to a new one and show a wrong result. This page shows how to solve it with nanoeffects. The bus lives outside React; the component only subscribes to it.
+
+Steps 1 and 2 are required, step 3 is not. The last two sections are extra.
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
 ## On this page
 
-- [See what goes wrong without a bus](#see-what-goes-wrong-without-a-bus)
-- [Wire the bus once](#wire-the-bus-once)
-- [Connect the form](#connect-the-form)
-- [Stop running work when the form closes](#stop-running-work-when-the-form-closes)
+- [Problems of the form without a bus](#problems-of-the-form-without-a-bus)
+- [1. The bus and the handlers](#1-the-bus-and-the-handlers)
+- [2. The form component](#2-the-form-component)
+- [3. Stop requests when the form closes](#3-stop-requests-when-the-form-closes)
 - [Show the last value of an event as state](#show-the-last-value-of-an-event-as-state)
 - [Keep a debounced handler between renders](#keep-a-debounced-handler-between-renders)
 - [Where to go next](#where-to-go-next)
 
-## See what goes wrong without a bus
+## Problems of the form 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 race in the name check.** The user types `ann`, then `anna`, and every input sends a "is the name free" request. 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
+## 1. The bus and the handlers
 
 Keep the bus in a file of its own, and the handlers of the form in another. Create the bus once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
 
@@ -81,7 +85,7 @@ bus.on(
 
 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
+## 2. The form component
 
 <!-- docs-check: continue -->
 
@@ -152,11 +156,11 @@ The `disabled` button is only for the look. The form stays correct without it: `
 
 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
+## 3. Stop requests when the form closes
 
 <!-- docs-check: continue -->
 
-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`:
+This step is optional. 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";
@@ -278,12 +282,37 @@ export const Search = ({ wait }) => {
 - Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
 - To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
 - `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
-- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+- Without a React component, use [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus).
+
+### Write a policy without its function
+
+**Problem.** `usePolicy` puts the callback of the latest render into the policy itself, so it needs a policy that has no function yet. If you passed your own function there, it would be easy to pass the wrong one.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
 
 ## Where to go next
 
 - The policies behind this form: [Policies](policies.md).
-- A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
+- A policy as a plain function without a bus: [`withPolicy`: call a policy outside a bus](policies.md#withpolicy-call-a-policy-outside-a-bus).
 - `retry`, `timeout` and the other effects: [Effects](effects.md).
 - A state library instead of `useState`: [Stores](stores.md).
 - React Query or SWR instead of your own state: [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).

package/docs/recipes.md

@@ -0,0 +1,528 @@
+# Common tasks
+
+> **Levels A to E.** Read first: [README](../README.md).
+
+Each task below starts with the problem, then a short solution. Where the page has more to say, the last line links to it. The tasks go from the simplest to the most involved.
+
+## On this page
+
+- [Events and handlers](#events-and-handlers)
+  - [A handler needs an API client, a store or a logger](#a-handler-needs-an-api-client-a-store-or-a-logger)
+  - [One handler fails, the others must still run](#one-handler-fails-the-others-must-still-run)
+  - [A typo in an event name](#a-typo-in-an-event-name)
+- [Races and repeated actions in the UI](#races-and-repeated-actions-in-the-ui)
+  - [An old response overwrites a new one](#an-old-response-overwrites-a-new-one)
+  - [A search box sends a request on every key](#a-search-box-sends-a-request-on-every-key)
+  - [A second click sends a second request](#a-second-click-sends-a-second-request)
+  - [Messages must go out in order](#messages-must-go-out-in-order)
+  - [A "Delete" button in a list blocks the other rows](#a-delete-button-in-a-list-blocks-the-other-rows)
+- [An unreliable network and long flows](#an-unreliable-network-and-long-flows)
+  - [A request fails sometimes: retry and backoff](#a-request-fails-sometimes-retry-and-backoff)
+  - [A request hangs: timeout](#a-request-hangs-timeout)
+  - [Refresh data every N seconds: poll](#refresh-data-every-n-seconds-poll)
+  - [Wait for another event inside a handler: take](#wait-for-another-event-inside-a-handler-take)
+  - [Load several things at once: all](#load-several-things-at-once-all)
+  - [Take the fastest answer: race](#take-the-fastest-answer-race)
+- [Features and domain logic](#features-and-domain-logic)
+  - [Get the result of emit](#get-the-result-of-emit)
+  - [Group a feature with its handlers: modules](#group-a-feature-with-its-handlers-modules)
+  - [Do not leave subscriptions after a widget closes](#do-not-leave-subscriptions-after-a-widget-closes)
+- [Stop work on a server](#stop-work-on-a-server)
+- [Debugging: what ran and why](#debugging-what-ran-and-why)
+- [Other libraries in the project](#other-libraries-in-the-project)
+- [Classes and TypeScript](#classes-and-typescript)
+  - [Use the bus in a class](#use-the-bus-in-a-class)
+  - [Keep the types of the bus in many files](#keep-the-types-of-the-bus-in-many-files)
+- [Examples of whole apps](#examples-of-whole-apps)
+
+## Events and handlers
+
+### A handler needs an API client, a store or a logger
+
+Many handlers use the same `api` client or logger. Importing it in every handler file ties the handlers to one client and makes tests harder. Put it on the bus once, and every task gets it on `ctx`.
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus({ context }) — every task gets these fields on ctx
+const bus = createBus({ context: { api, logger } });
+
+bus.on("save", async (draft, { api, logger }) => {
+  await api.save(draft);
+  logger.info("saved");
+});
+```
+
+More: [Context fields](context.md).
+
+### One handler fails, the others must still run
+
+Two handlers listen to `order/placed`: one sends analytics, the other saves the order. By default the first error stops the loop, so a broken analytics call can keep the order from being saved. With `onError` every handler runs and the errors go to one place.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  // onError — isolates the handlers: a thrown error goes here and the next handler still runs
+  onError: (error, { type }) => report(error, type),
+});
+
+const sendAnalytics = (order) => {
+  throw new Error(`analytics is down for ${order.id}`);
+};
+const saveOrder = (order) => console.log("saved", order.id);
+
+bus.on("order/placed", sendAnalytics); // throws
+bus.on("order/placed", saveOrder); // still runs
+
+bus.emit("order/placed", { id: 1 }); // saved 1
+```
+
+More: [Errors and unheard events](errors.md#isolate-failing-handlers).
+
+### A typo in an event name
+
+`emit("serch")` does not fail: no one listens to that name, so nothing happens, and you look for the bug in the handler. `onUnhandled` warns about an event that nobody heard. Turn it on in development.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  // onUnhandled — called when an event has no listeners
+  onUnhandled: ({ type }) => console.warn(`Nobody listens to "${type}"`),
+});
+
+bus.on("search", (query) => console.log(query));
+
+bus.emit("serch", "nano"); // warning: Nobody listens to "serch"
+```
+
+More: [Warn when nobody listens](errors.md#warn-when-nobody-listens).
+
+## Races and repeated actions in the UI
+
+### An old response overwrites a new one
+
+A user types `re`, then `react`. Two requests are in flight. The server answers `react` fast and `re` slowly, so the answer for `re` arrives last and replaces the right list with the wrong one. This is what a plain React effect does:
+
+```jsx
+import { useEffect, useState } from "react";
+
+export function Search({ query }) {
+  const [items, setItems] = useState([]);
+
+  useEffect(() => {
+    // two requests are in flight, and the one that finishes last wins, even the older one
+    api.search(query).then(setItems);
+  }, [query]);
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Move the request into a handler with `latest`: a new `search` aborts the previous request, and the aborted one delivers no result.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// latest — a new "search" aborts the previous one and drops its result
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal — lets the browser cancel the request itself
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+
+bus.on("results", (items) => render(items));
+```
+
+More: [Cancel stale requests](cancel-stale-requests.md), [Policies](policies.md#latest-abort-the-previous-run), and the component side in [Build a sign-up form in React](react.md).
+
+### A search box sends a request on every key
+
+Typing `react` sends five requests, and the list flickers. `debounce` waits for a pause in typing; `latest` aborts the request that is still in flight.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// latest — a new search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce — start after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+```
+
+More: [Pause between requests](debounce-and-abort.md).
+
+### A second click sends a second request
+
+A user double-clicks "Sign up" on a slow network, and two accounts are created. `leading` drops every call that comes while the first one still runs.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// leading — a call that comes while the previous one runs is dropped
+bus.on(
+  "form/submitted",
+  leading(async (form, { signal }) => {
+    await api.signUp(form, { signal });
+  }),
+);
+```
+
+More: [Prevent a double submit](prevent-double-submit.md).
+
+### Messages must go out in order
+
+In a chat, a user sends `Hello` and then `How are you?` within a second. Two parallel requests can reach the server in the wrong order. `queue` sends the next message only after the previous one is delivered.
+
+```js
+import { createBus } from "nanoeffects";
+import { queue } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// queue — the next message waits until the previous one is delivered
+bus.on(
+  "message/sent",
+  queue(async (message, { signal }) => {
+    await api.sendMessage(message, { signal });
+  }),
+);
+```
+
+More: [Policies, `queue`](policies.md#run-calls-one-after-another-with-queue).
+
+### A "Delete" button in a list blocks the other rows
+
+You protect "Delete" with `leading`. While one row is deleted, clicks on the other rows are dropped too, because the whole handler has one state. `key` gives every row its own state.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// leading with key — every row id has its own state, so other rows are not blocked
+bus.on(
+  "row/deleted",
+  leading(
+    async (row, { signal }) => {
+      await api.deleteRow(row.id, { signal });
+    },
+    { key: (row) => row.id },
+  ),
+);
+```
+
+More: [Policies, `key`](policies.md#key-isolate-state-by-key).
+
+## An unreliable network and long flows
+
+### A request fails sometimes: retry and backoff
+
+A request fails once in a while because of the network. `retry` repeats it. If the server is overloaded, repeating at once makes it worse, so use `backoff` to make the pause longer with each attempt.
+
+```js
+import { createBus } from "nanoeffects";
+import { backoff, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+// retry — repeat the request after an error, up to 4 attempts
+const loadWithRetry = retry((id, { signal }) => api.getUser(id, { signal }), {
+  times: 4,
+  // backoff — the pause grows (200, 400, 800 ms) with a random part, so clients do not retry at the same moment
+  delay: backoff({
+    base: 200,
+    max: 5000,
+    jitter: true,
+  }),
+});
+
+bus.on("user/opened", loadWithRetry);
+```
+
+More: [`backoff`](effects.md#backoff).
+
+### A request hangs: timeout
+
+A request does not fail and does not answer, and the spinner spins forever. `timeout` rejects the call after the time you set and aborts the request.
+
+```js
+import { createBus } from "nanoeffects";
+import { timeout } from "nanoeffects/effects";
+
+const bus = createBus();
+
+// timeout — reject with TimeoutError and abort the request after 5 s
+const loadOnce = timeout(5000, (id, { signal }) => api.getUser(id, { signal }));
+
+bus.on("user/opened", loadOnce);
+```
+
+More: [`timeout`](effects.md#timeout).
+
+### Refresh data every N seconds: poll
+
+A dashboard must refresh its numbers every ten seconds while it is open. `poll` is an effect: it calls your function on a timer and ends when the task is aborted, so a closed dashboard does not keep asking.
+
+```js
+import { createBus } from "nanoeffects";
+import { poll } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("dashboard/opened", async (_, ctx) => {
+  // stop the polling when the user leaves
+  ctx.on("dashboard/closed", () => ctx.abort());
+
+  // poll — call refresh every 10 s until the task is aborted
+  await poll(ctx, () => refresh(), 10_000);
+});
+```
+
+More: [`poll`](effects.md#poll).
+
+### Wait for another event inside a handler: take
+
+After a login the handler must wait for the user to log out before it cleans up. Instead of a flag and a second handler, `take` pauses the handler until the next event with that name.
+
+```js
+import { createBus } from "nanoeffects";
+import { take } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("login", async (user, ctx) => {
+  // take — pause this handler until the next "logout"
+  const reason = await take(ctx, "logout");
+  cleanup(user, reason);
+});
+```
+
+More: [`take`](effects.md#take).
+
+### Load several things at once: all
+
+A profile page needs the user and the posts. Loading them one after another is slow. `all` runs both requests together and aborts the second one if the first fails.
+
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("profile/opened", async (id, ctx) => {
+  // all — run both requests together; if one fails, the other is aborted. child carries the signal of its own request
+  const { user, posts } = await all(ctx, {
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
+  });
+
+  ctx.emit("profile/loaded", { user, posts });
+});
+```
+
+### Take the fastest answer: race
+
+The same data lives on two servers, and you want the answer of the faster one. `race` returns the first answer and aborts the other request.
+
+```js
+import { createBus } from "nanoeffects";
+import { race } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("user/opened", async (id, ctx) => {
+  // race — the first answer wins, the slower request is aborted
+  const result = await race(ctx, {
+    primary: (child) => api.getUser(id, child),
+    backup: (child) => api.getUserFromBackup(id, child),
+  });
+
+  const user = "primary" in result ? result.primary : result.backup;
+  ctx.emit("user/loaded", user);
+});
+```
+
+More: [`all`](effects.md#all), [`race`](effects.md#race).
+
+## Features and domain logic
+
+### Get the result of emit
+
+`emit` of a plain event returns nothing, so to get an answer you need a second event. An action with a handler returns the result of its handler right from `emit`.
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// createAction with a handler — emit runs it and returns what it returns
+const double = createAction("math/double", (value) => value * 2);
+
+const result = bus.emit(double(21)); // 42
+```
+
+More: [Actions, jobs and modules](actions.md).
+
+### Group a feature with its handlers: modules
+
+A feature has several subscriptions, and you must remember to remove each one. A module registers them together and removes them all with one `unmount`.
+
+```js
+import { createBus } from "nanoeffects";
+import { createModule, modulePlugin } from "nanoeffects/actions";
+
+// createModule — one feature; unmount cancels everything it registered
+const greeting = createModule("greeting", (m) => {
+  m.on("greet", (name) => console.log(`hello ${name}`));
+});
+
+const bus = createBus();
+const app = bus.use(modulePlugin([greeting]));
+
+app.unmount(greeting); // the subscription is gone
+```
+
+More: [Modules](actions.md#modules) and [the guide](guide.md#9-mount-a-domain-as-a-module).
+
+### Do not leave subscriptions after a widget closes
+
+A chat widget subscribes to the bus when it opens. If it closes without unsubscribing, the handlers stay: memory grows with every open, and they still update a widget that is gone. A module that you mount on open and unmount on close leaves nothing behind.
+
+```js
+import { createBus } from "nanoeffects";
+import { createModule, modulePlugin } from "nanoeffects/actions";
+
+// the module owns the listeners of the widget
+const chatModule = createModule("chat", (m) => {
+  m.on("message/received", (message) => render(message));
+});
+
+const bus = createBus();
+const app = bus.use(modulePlugin());
+
+const stop = app.mount(chatModule); // the widget is opened: the listeners are on the bus
+
+stop(); // the widget is closed: no listeners are left
+console.log(bus.get("message/received").length); // 0
+```
+
+More: [Build a chat widget](chat-widget.md).
+
+## Stop work on a server
+
+A client closes the tab, but the server goes on asking other services for it. Create an `AbortController` for the request, abort it when the connection closes, and pass its signal to `emit`: `timeout`, `retry` and the request itself stop.
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — emit accepts { signal }
+const bus = createBus().use(signalPlugin());
+
+const getUser = createAction("user/get", (id, { signal }) => api.getUser(id, { signal }));
+
+export async function handleRequest(request, reply) {
+  const controller = new AbortController();
+
+  // close — the client left: abort everything started for this request
+  reply.raw.on("close", () => controller.abort());
+
+  // the task, and the requests it made, stop with the controller
+  return bus.emit(getUser(request.params.id), { signal: controller.signal });
+}
+```
+
+More: [Stop work on a server](server.md), including WebSocket and queue workers.
+
+## Debugging: what ran and why
+
+An effect fired and you cannot tell which event caused it. The tracer logs every task with its parent, so you see the chain of events.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// createTracer — send every task to the console
+const trace = createTracer(consoleLogger());
+
+// tracePlugin — also report every emit
+const bus = createBus({ trace }).use(tracePlugin());
+
+bus.on("search", (query, ctx) => ctx.emit("results", [query]));
+bus.emit("search", "nano"); // the log shows: search · emit, then results · emit with search as the cause
+```
+
+More: [Trace tasks](tracing.md). To reload modules without a page refresh, see [Hot reload](hmr.md).
+
+## Other libraries in the project
+
+- **Redux Toolkit, Zustand, MobX or Pinia.** [Connect a store](stores.md).
+- **React Query, SWR or RTK Query.** [Query libraries](query-libraries.md).
+- **RxJS.** [Use nanoeffects next to RxJS](migrating-from-rxjs.md) and [Observables](observable.md).
+- **Moving from redux-saga.** [Coming from redux-saga](migrating-from-saga.md).
+- **Moving from Effector.** [Coming from Effector](migrating-from-effector.md).
+- **Moving from mitt or nanoevents.** [Coming from mitt](migrating-from-mitt.md).
+
+## Classes and TypeScript
+
+### Use the bus in a class
+
+Your logic lives in classes, and each instance must remove its subscriptions when it is no longer needed. `Emitter` gives every instance its own bus and a `dispose` that removes all of its subscriptions.
+
+```js
+import { Emitter } from "nanoeffects/oop";
+
+// Emitter — every instance gets its own bus with on, once, off, emit and dispose
+class VideoService extends Emitter {
+  constructor() {
+    super();
+    this.on("played", () => console.log("playing"));
+  }
+}
+
+const video = new VideoService();
+video.emit("played");
+
+video.dispose(); // removes every subscription of this instance
+```
+
+More: [Use the bus from a class](oop.md).
+
+### Keep the types of the bus in many files
+
+Handlers and modules are in different files, and TypeScript must know the payloads and the fields of `ctx`. See [TypeScript in many files](typescript.md).
+
+## Examples of whole apps
+
+- **A form with a username check and a submit, in React.** [Build a sign-up form in React](react.md).
+- **A whole app in layers: entities, features, modules, a server.** [Build a chat](chat-example.md).
+- **A widget that listens only while it is open.** [Build a chat widget](chat-widget.md).
+- **Vue.** [Use nanoeffects in a Vue app](vue.md).
+- **Svelte.** [Use nanoeffects in a Svelte app](svelte.md).
+- **A ready project.** [Start a project from a template](starter.md).