nanoeffects 0.7.0 → 0.9.0

package/docs/react.md

@@ -16,19 +16,26 @@ Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one p
 
 ## 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.
+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.
 
 ```js
-// registration.js
+// bus.js
 import { createBus } from "nanoeffects";
+
+export const bus = createBus(); // the bus: created once, at the top of the module
+```
+
+The handlers know the bus and the bus knows nothing of them. They register when `registration.js` is imported, once, when the app starts:
+
+```js
+// registration.js
 import { retry } from "nanoeffects/effects";
 import { debounce, latest, leading } from "nanoeffects/policies";
+import { bus } from "./bus";
 
 // 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",
@@ -66,12 +73,15 @@ The handlers know nothing about React. A test can emit `username/typed` and read
 
 ## Connect the form
 
+<!-- docs-check: continue -->
+
 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
+import { bus } from "./bus"; // the bus of the previous snippet
+import "./registration"; // registers the handlers; the app does this once, when it starts
 
 export function SignUpForm() {
   const [name, setName] = useState("");
@@ -134,6 +144,8 @@ In development, React StrictMode runs the effect twice (subscribe, unsubscribe,
 
 ## Stop running work 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`:
 
 ```js
@@ -150,8 +162,52 @@ const checkName = latest(async (name, ctx) => {
 
 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.
 
+## Keep a debounced handler between renders
+
+**Problem.** A component runs again on every render. A policy made in its body, such as `debounce(300, search)`, is made again each time and loses its timer. A policy made once keeps the callback of the first render, which reads old props and state.
+
+**When.** A handler in a component needs a policy, and you do not need a bus: a search box, an autosave, a submit that must not fire twice.
+
+`usePolicy(callback, make, deps)` keeps one function between renders. It calls the `callback` of the latest render, so an inline callback sees fresh state. It cancels pending calls when the component unmounts.
+
+```jsx
+import { useState } from "react";
+import { debounce } from "nanoeffects/policies";
+import { usePolicy } from "nanoeffects/react";
+
+export const Search = ({ wait }) => {
+  const [items, setItems] = useState([]);
+
+  // usePolicy — a stable function; the first argument is the latest render's callback
+  const onChange = usePolicy(
+    async (query, { signal }) => {
+      const found = await api.search(query, { signal });
+      setItems(found);
+    },
+    // the second argument builds the policy once; task runs the callback above
+    (task) => debounce(wait, task),
+    // deps — list what the second argument reads; a new wait makes a new policy
+    [wait],
+  );
+
+  return (
+    <div>
+      <input onChange={(event) => onChange(event.target.value)} />
+      <p>{items.length} found</p>
+    </div>
+  );
+};
+```
+
+- `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
+- A pending call is cancelled on unmount and when `deps` change.
+- Do not write `usePolicy(debounce(300, callback))`. The policy would be made on every render or keep a stale callback.
+- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+
 ## 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).
 - `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 and SWR](query-libraries.md).

package/docs/scope.md

@@ -11,27 +11,29 @@ You give a scope to the thing that uses it. A call can replace it. Nothing else
 Scopes are a plugin, so a bus that does not use them pays nothing.
 
 ```js
+// bus.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());
+export const bus = createBus().use(scopePlugin());
 ```
 
+The bus is in one file and the commands and actions in files named after their domain, so the next example imports `bus` from here. Each section after it keeps its own `bus.js` and domain file, as if it were an app of its own.
+
 - 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.
+- Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
 
 ## Give a command its own fields
 
+<!-- docs-check: continue -->
+
 ```js
-import { createBus } from "nanoeffects";
+// user.js
 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(
+export const getUser = createCommand(
   "user/get",
   (id, { api, cache }) => {
     // api and cache are on ctx for this command only
@@ -39,6 +41,11 @@ const getUser = createCommand(
   },
   { api, cache: new Map() },
 );
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 const user = await bus.emit(getUser("1")); // the handler has api and cache
 ```
@@ -50,18 +57,15 @@ The listeners of `"user/get"` get the same fields when the command is emitted, b
 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";
+// feed.js
 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(
+export const loadFeed = createCommand(
   "feed/load",
   (url, { fetchJson, race, delay }) =>
     // race, delay, fetchJson — bound to this task: no ctx argument
@@ -72,6 +76,19 @@ const loadFeed = createCommand(
   // $effects — built-in and your own functions share one object
   { $effects: { fetchJson, race, delay } },
 );
+```
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { scopePlugin } from "nanoeffects/scope";
+
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+import { bus } from "./bus";
+import { loadFeed } from "./feed";
 
 const result = await bus.emit(loadFeed("/feed"));
 ```
@@ -85,14 +102,27 @@ const result = await bus.emit(loadFeed("/feed"));
 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
+// bus.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,
-});
+export const bus = createBus().use(scopePlugin());
+```
+
+```js
+// user.js
+import { createCommand } from "nanoeffects/actions";
+
+export const getUser = createCommand(
+  "user/get",
+  (id, { api }) => api.getUser(id),
+  { api },
+);
+```
+
+```js
+import { bus } from "./bus";
+import { getUser } from "./user";
 
 // the real api for this call
 await bus.emit(getUser("1"));
@@ -112,23 +142,30 @@ Rules for the second argument:
 ## Give an action, a job or a module its own fields
 
 ```js
-import { createAction, createJob, createModule } from "nanoeffects/actions";
+// user.js
+import { createAction, createJob } from "nanoeffects/actions";
 
 // createAction — the listeners of this action's calls get the fields
-const userLoaded = createAction("user/loaded", { store });
+export 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(
+export const loadUser = createJob(
   "user/load",
   fetchUser,
   { success: userLoaded, fail: "user/failed" },
   { logger },
 );
+```
+
+```js
+// audit-module.js
+import { createModule } from "nanoeffects/actions";
+import { userLoaded } from "./user";
 
 // createModule — third argument; everything the module owns gets the fields:
 // m.on listeners, m.handle handlers, m.spawn tasks
-const auditModule = createModule(
+export const auditModule = createModule(
   "audit",
   (m) => {
     m.on(userLoaded, (user, { logger }) => logger.info(user.id));
@@ -161,13 +198,14 @@ In `$effects` a function loses its first parameter, and TypeScript cannot keep a
 `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
+// pick.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), {
+export const pick = createCommand("pick", (items, { first }) => first(items), {
   first, // a plain key of the scope, not an entry of `$effects`
 });
 ```