nanoeffects 0.3.0 → 0.5.0

package/docs/policies.md

@@ -1,41 +1,93 @@
 # 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.
+Use this page when handlers overlap in a SPA (search-as-you-type, double submit, leave page). A **policy** wraps a handler and decides what happens then.
 
-| 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                                                |
+Start with `latest`. The table and sections below are the rest of the reference.
 
-`debounce` and `throttle` take `leading` and `trailing`:
+## Abort the previous run
 
-- `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.
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
 
-`key` gives each key its own state, so calls with different keys do not affect each other:
+const bus = createBus();
 
-```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 }));
+// latest — a newer run aborts the older one
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal — lets latest cancel this request, not only drop its result
+    await api.search(query, { signal });
+  }),
+);
 ```
 
-The state of a key is dropped when that key goes idle, so keys can be unbounded (ids, urls).
+Pass `signal` to `fetch` (and the like) so the request cancels.
+
+## Choose a policy
+
+Every policy accepts `key` in its options (see [Isolate state by key](#isolate-state-by-key)).
+
+| Policy | Overlapping calls |
+| ------ | ----------------- |
+| `latest(fn)` | previous run aborted, result dropped |
+| `leading(fn)` | new calls 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 |
+
+## Configure debounce and throttle
+
+`debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.
+
+**Throttle** (`throttle(ms, fn)`):
+
+- Default `leading: true`, `trailing: true`.
+- A call when the throttle is idle (at least `ms` after the previous call and run) runs at once.
+- Calls made while it waits are held; the latest runs when the window closes.
+- Under a steady stream it runs every `ms`.
+- `leading: false` — even the first call waits for the end of its window.
+- `trailing: false` — drop calls made during a window.
+
+**Debounce** (`debounce(ms, fn)`):
+
+- Default `trailing: true` — run the last call after `ms` of quiet.
+- `leading: true` — also run the first call of a burst at once; the trailing run happens only if more calls follow.
+- `leading: true, trailing: false` — only the first call of a burst.
+- Both `false` — nothing runs.
+
+## Isolate state by key
 
-## Queue
+`key` gives each key its own state. Calls with different keys do not affect each other. Idle keys are dropped, so keys can be unbounded (ids, urls).
 
-`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:
+```js
+import { createBus } from "nanoeffects";
+import { latest, queue } from "nanoeffects/policies";
 
-```ts
+const bus = createBus();
+
+// one latest run per user id
+bus.on(
+  "load",
+  latest(loadUser, { key: (user) => user.id }),
+);
+
+// uploads of the same file go one after another
+bus.on(
+  "upload",
+  queue(upload, { key: (file) => file.name }),
+);
+```
+
+## Run calls one after another with `queue`
+
+```js
+import { createBus } from "nanoeffects";
 import { queue } from "nanoeffects/policies";
 
+const bus = createBus();
+
+// queue — one after another, in order
 bus.on(
   "save",
   queue(async (draft, { signal }) => {
@@ -43,11 +95,22 @@ bus.on(
   }),
 );
 
-bus.emit("save", a); // runs now
-bus.emit("save", b); // waits for a, then runs
+bus.emit("save", draftA); // runs now
+bus.emit("save", draftB); // waits for draftA, 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.
+| Option | Meaning |
+| ------ | ------- |
+| `concurrency` | how many calls may run at once (default `1`) |
+| `limit` | how many calls may wait |
+| `overflow` | when the line is full: `"drop-new"` (default) or `"drop-old"` |
+
+A dropped call resolves with `undefined`. `queue(fn, { limit: 1, overflow: "drop-old" })` keeps only the latest waiting call. `limit: 0` lets nothing wait.
+
+Every call returns a promise with the result of its own run. An error rejects only that call; the queue continues.
+
+**Abort:**
+
+- A waiting call whose task aborts is skipped and resolves with `undefined`.
+- When a running call aborts, its slot is freed at once and its result is dropped.
+- Pass `signal` into what `fn` does. A `fn` that ignores it can overlap with the next run.

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).

package/docs/semantics.md

@@ -1,7 +1,9 @@
 # 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.
+Guarantees and sharp edges. Read when something surprises you; not required to start.
+
+- **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](errors.md)). 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.
+- **`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 — 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.