nanoeffects 0.4.0 → 0.6.0

package/docs/package.md

@@ -6,9 +6,20 @@ 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/scope` | `scopePlugin`, `effect`: fields for one command, action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `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).

package/docs/scope.md

@@ -0,0 +1,226 @@
+# Pin context fields to a command, an action, a module or a call
+
+Optional, for domain logic. Use it when one command needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
+
+A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`, `logger`), except one: `effects`. Its functions take `{ signal }` as the first parameter, like `retry(ctx, fn)`, and go on `ctx` bound to the task, so you call `ctx.fetchJson(url)` instead of `fetchJson(ctx, url)`.
+
+You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
+
+## Turn scopes on
+
+Scopes are a plugin, so a bus that does not use them pays nothing.
+
+```js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+// scopePlugin — makes the scopes below work on this bus; returns the same bus
+const bus = createBus().use(scopePlugin());
+```
+
+- Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
+- Use it **after** `effectsPlugin` (an effect it adds later would be assigned over an effect of a scope with the same name) and **before** `modulePlugin` (it mounts the modules when it is used). `contextPlugin` and `createBus({ context })` can come in any order: a scope wins over them.
+
+## Give a command its own fields
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus().use(scopePlugin());
+
+// createCommand — third argument is the scope of this command
+const getUser = createCommand(
+  "user/get",
+  (id, { api, cache }) => {
+    // api and cache are on ctx for this command only
+    return cache.get(id) ?? api.getUser(id);
+  },
+  { api, cache: new Map() },
+);
+
+const user = await bus.emit(getUser("1")); // the handler has api and cache
+```
+
+The listeners of `"user/get"` get the same fields when the command is emitted, because the fields belong to the call.
+
+## Bind an effect to the task
+
+An effect is a function with `{ signal }` as its first parameter. In `effects` it is bound to the task, so it stops with the task.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { delay, race } from "nanoeffects/effects";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus().use(scopePlugin());
+
+// your own effect: first parameter is the task (only its signal is used)
+const fetchJson = (ctx, url) =>
+  fetch(url, { signal: ctx.signal }).then((response) => response.json());
+
+const loadFeed = createCommand(
+  "feed/load",
+  (url, { fetchJson, race, delay }) =>
+    // race, delay, fetchJson — bound to this task: no ctx argument
+    race({
+      feed: () => fetchJson(url),
+      timeout: () => delay(5000),
+    }),
+  // effects — built-in and your own functions share one object
+  { effects: { fetchJson, race, delay } },
+);
+
+const result = await bus.emit(loadFeed("/feed"));
+```
+
+- Put in `effects` only functions that take `ctx` first. A plain function (a formatter, a logger) belongs in `context`.
+- A function under any other key is copied as it is; a function in `effects` is bound.
+- `effects` is the one name a field of the scope cannot have.
+
+## Replace a field for one call
+
+The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
+
+```js
+import { createBus } from "nanoeffects";
+import { createCommand } from "nanoeffects/actions";
+import { scopePlugin } from "nanoeffects/scope";
+
+const bus = createBus().use(scopePlugin());
+const getUser = createCommand("user/get", (id, { api }) => api.getUser(id), {
+  api,
+});
+
+// the real api for this call
+await bus.emit(getUser("1"));
+
+// the second argument — a fake api, for this call only
+const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
+await bus.emit(getUser("1"), { api: fakeApi });
+```
+
+Rules for the second argument:
+
+- It works with an action or a command call (`emit(getUser("1"), scope)`, `ctx.emit(loaded(user), scope)`).
+- It does not work with the string form: in `emit("user/get", payload)` the second argument is the payload.
+- It can replace `effects` too: `{ effects: { delay: instantDelay } }`.
+- Fields of the library (`signal`, `emit`, …) in it are ignored.
+
+## Give an action, a job or a module its own fields
+
+```js
+import { createAction, createJob, createModule } from "nanoeffects/actions";
+
+// createAction — the listeners of this action's calls get the fields
+const userLoaded = createAction("user/loaded", { store });
+
+// createJob — the scope is the fourth argument, after the outcomes;
+// the handler and the listeners of the outcome get its fields
+const loadUser = createJob(
+  "user/load",
+  fetchUser,
+  { success: userLoaded, fail: "user/failed" },
+  { logger },
+);
+
+// createModule — third argument; everything the module owns gets the fields:
+// m.on listeners, m.handle handlers, m.spawn tasks
+const auditModule = createModule(
+  "audit",
+  (m) => {
+    m.on(userLoaded, (user, { logger }) => logger.info(user.id));
+  },
+  { logger },
+);
+```
+
+A module scope does not leak: a listener registered outside the module does not see it.
+
+## Which value wins
+
+When several places set the same field, the strongest one wins:
+
+| Strength | Where it is set |
+| -------- | --------------- |
+| 1 (strongest) | the second argument of `emit` |
+| 2 | the scope of the action, command or job |
+| 3 | the scope of the module that owns the handler |
+| 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
+
+The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
+
+## Keep a generic effect generic
+
+In `effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
+
+`effect(fn)`: mark the function where you declare it, then put it in the scope like any other value. No annotation, so a JavaScript editor shows the exact hint too.
+
+```js
+import { createCommand } from "nanoeffects/actions";
+import { effect } from "nanoeffects/scope";
+
+// effect — marks the function, so a scope binds it to the task; the editor keeps its generic
+const first = effect((ctx, items) => items[0]);
+
+const pick = createCommand("pick", (items, { first }) => first(items), {
+  first, // a plain key of the scope, not an entry of effects
+});
+```
+
+Call `effect` where you declare the function, as above, and not inline in the scope: TypeScript does not infer the scope from a generic call written there.
+
+`Effect<F>` (TypeScript): declare how the effect looks **after** it is bound, and keep it in `effects`.
+
+```ts
+import { createCommand } from "nanoeffects/actions";
+import type { Effect } from "nanoeffects/effects";
+
+// First — checker-only: how a handler calls the effect (no ctx)
+type First = <T>(items: T[]) => T;
+
+// Effect<First> — the function takes the task first and is typed as First once bound
+const first: Effect<First> = (ctx, items) => items[0];
+
+const pick = createCommand(
+  "pick",
+  (id: string, { first }) => first([id]), // string
+  { effects: { first } },
+);
+```
+
+`Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
+
+## Type the fields (optional)
+
+A handler of a command, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
+
+```ts
+import { createCommand } from "nanoeffects/actions";
+
+type User = { id: string; name: string };
+
+const getUser = createCommand(
+  "user/get",
+  async (id: string, ctx) => {
+    ctx.cache; // Map<string, User>, from the scope below
+    return ctx.cache.get(id);
+  },
+  { cache: new Map<string, User>() },
+);
+```
+
+- A field of a scope replaces a field of the same name from the bus in the type too.
+- An override in `emit` must match the type of the field it replaces: `emit(getUser("1"), { cache: 1 })` is an error.
+- A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
+- `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
+
+## Limits
+
+- No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
+- The fields of the bus are not in the handler of a command made with `createCommand(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
+- The string form of `emit` takes no scope.
+- `effect(fn)` works only as a value of a scope, not as an entry of `effects`.
+- A scope on a command, action, job or module is typed without the events of a bus, so `take` in its `effects` takes any event name.