nanoeffects 0.34.0 → 0.36.0

package/dist/react.d.ts

@@ -1,6 +1,6 @@
-import { H as EventMap, T as EventKey, a as FreeActionCreator, q as Task, t as ActionCreator, v as Bus } from "./action-creator-DprJV-pN.js";
+import { H as EventMap, T as EventKey, a as FreeActionCreator, q as Task, t as ActionCreator, v as Bus } from "./action-creator-CXIq6GWK.js";
 import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
-import { t as PolicyFunction } from "./with-policy-Y12d-yx6.js";
+import { t as PolicyFunction } from "./with-policy-e4yx1vhN.js";
 import { t as StateOf } from "./state-of-C19H6BoV.js";
 //#region src/react/plugin.d.ts
 /** Tells whether two values are the same: `Object.is` unless the caller gives another. */

package/dist/redux.d.ts

@@ -1,4 +1,4 @@
-import { H as EventMap, v as Bus } from "./action-creator-DprJV-pN.js";
+import { H as EventMap, v as Bus } from "./action-creator-CXIq6GWK.js";
 import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
 //#region src/store/redux/middleware.d.ts
 /** What Redux passes through a middleware: an action is a plain object with a `type`. */

package/dist/scope.d.ts

@@ -1,5 +1,5 @@
-import { H as EventMap, I as WithSignal, c as Scope, f as Effect, m as Signaled, p as Effects, s as EmitScope, v as Bus } from "./action-creator-DprJV-pN.js";
-import { n as ScopeSlots, r as Scoped } from "./types-DxPZDzZG.js";
+import { H as EventMap, I as WithSignal, c as Scope, f as Effect, m as Signaled, p as Effects, s as EmitScope, v as Bus } from "./action-creator-CXIq6GWK.js";
+import { n as ScopeSlots, r as Scoped } from "./types-ByoeMqVh.js";
 //#region src/scope/effect.d.ts
 /**
  * Marks a function whose first parameter is `{ signal }` as an effect, so that

package/dist/signal.d.ts

@@ -1,24 +1,25 @@
-import { A as HandledCall, C as Emit, E as EventLike, H as EventMap, s as EmitScope, u as WithScope, v as Bus } from "./action-creator-DprJV-pN.js";
-import { n as FromSignal } from "./context-types-BiTMp_lW.js";
+import { A as HandledCall, C as Emit, E as EventLike, H as EventMap, I as WithSignal, s as EmitScope, u as WithScope, v as Bus } from "./action-creator-CXIq6GWK.js";
+import { n as FromSignal } from "./context-types-BO1QE6W2.js";
 //#region src/signal/fetch.d.ts
 /**
- * A `fetch` that carries a given signal, so the request stops when the signal aborts and the caller never passes
- * it. Give it to `fromSignal` and every task gets a `ctx.fetch` made from its own signal. A call that has a
- * `signal` of its own stops with whichever aborts first.
+ * A `fetch` that stops with its task: an effect, so `ctx` is the first argument and the request carries
+ * `ctx.signal`. The caller never passes the signal. A call that has a `signal` of its own in `init` stops with
+ * whichever aborts first. Outside a task pass `{ signal }` of the source, or `{}` in plain JavaScript.
+ *
+ * With `effectsPlugin({ fetch: signalFetch })` every task has a `ctx.fetch(input, init)` bound to itself.
  *
  * @example
  * ```ts
- * const bus = createBus().use(
- *   contextPlugin({ fetch: fromSignal(signalFetch) }),
- * );
- *
  * bus.on("search", latest(async (query, ctx) => {
- *   const response = await ctx.fetch(`/api?q=${query}`); // stops when the policy cancels the handler
+ *   const response = await signalFetch(ctx, `/api?q=${query}`); // stops when the policy cancels the handler
  *   ctx.emit("results", await response.json());
  * }));
+ *
+ * const withFetch = createBus().use(effectsPlugin({ fetch: signalFetch }));
+ * withFetch.on("search", latest(async (query, { fetch }) => fetch(`/api?q=${query}`)));
  * ```
  */
-export declare const signalFetch: (signal: AbortSignal) => typeof fetch;
+export declare const signalFetch: (ctx: WithSignal, input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 //#endregion
 //#region src/signal/from-signal.d.ts
 /**

package/dist/signal.js

@@ -1 +1 @@
-import{i as e}from"./caller-DULg_ZYV.js";import{t}from"./onAbort-BgMfspK4.js";import{n}from"./promise-CSLpzwSR.js";import{n as r}from"./bus-Cmk4U1hQ.js";import{t as i}from"./signal-field-key-CWT-3OXC.js";const a=e=>(t,n)=>{let r=n?.signal,i=r?AbortSignal.any([e,r]):e;return fetch(t,{...n,signal:i})},o=e=>({[i]:e}),s=(n,r)=>{let i=(e,i,a)=>{let o=a?.signal;if(!o)return n(e,i,a);let s=n(e,r?(e,t)=>(c(),i(e,t)):i,a),c=t({signal:o},s);return()=>{c(),s()}};return(t,n,r)=>e(()=>i(t,n,r))},c=e=>typeof e==`object`&&!!e,l=(e,t)=>{let n=t[0];if(!c(n)||!c(e)&&typeof e!=`function`)return;let r=Reflect.get(n,`signal`);return r instanceof AbortSignal?r:void 0},u=(e,i,a,o)=>{let s=t({signal:e},e=>{for(let{target:t}of i)t.abort(e)});return n(o)?o.then(s,s):r(a)&&s(),o},d=()=>e=>{let t,n,r=e.addContext;e.addContext=e=>{r?.(e),t?.push({target:e}),n?.aborted&&e.abort(n.reason)};let i=e.emit;e.emit=(e,...r)=>{let a=l(e,r);if(!(a||t))return i(e,...r);let o=t,s=n,c=[];t=a?c:void 0,n=a;let d;try{d=i(e,...r)}finally{t=o,n=s}return a?u(a,c,e,d):d};let a=e.on,o=e.once;return e.on=s(a,!1),e.once=s(o,!0),e};export{o as fromSignal,a as signalFetch,d as signalPlugin};
+import{i as e}from"./caller-DULg_ZYV.js";import{t}from"./onAbort-BgMfspK4.js";import{n}from"./promise-CSLpzwSR.js";import{n as r}from"./bus-Cmk4U1hQ.js";import{t as i}from"./signal-field-key-CWT-3OXC.js";const a=(e,t,n)=>{let r=n?.signal,i=r&&e.signal?AbortSignal.any([e.signal,r]):r??e.signal;return fetch(t,{...n,signal:i})},o=e=>({[i]:e}),s=(n,r)=>{let i=(e,i,a)=>{let o=a?.signal;if(!o)return n(e,i,a);let s=n(e,r?(e,t)=>(c(),i(e,t)):i,a),c=t({signal:o},s);return()=>{c(),s()}};return(t,n,r)=>e(()=>i(t,n,r))},c=e=>typeof e==`object`&&!!e,l=(e,t)=>{let n=t[0];if(!c(n)||!c(e)&&typeof e!=`function`)return;let r=Reflect.get(n,`signal`);return r instanceof AbortSignal?r:void 0},u=(e,i,a,o)=>{let s=t({signal:e},e=>{for(let{target:t}of i)t.abort(e)});return n(o)?o.then(s,s):r(a)&&s(),o},d=()=>e=>{let t,n,r=e.addContext;e.addContext=e=>{r?.(e),t?.push({target:e}),n?.aborted&&e.abort(n.reason)};let i=e.emit;e.emit=(e,...r)=>{let a=l(e,r);if(!(a||t))return i(e,...r);let o=t,s=n,c=[];t=a?c:void 0,n=a;let d;try{d=i(e,...r)}finally{t=o,n=s}return a?u(a,c,e,d):d};let a=e.on,o=e.once;return e.on=s(a,!1),e.once=s(o,!0),e};export{o as fromSignal,a as signalFetch,d as signalPlugin};

package/dist/svelte.d.ts

@@ -1,4 +1,4 @@
-import { H as EventMap, T as EventKey, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-DprJV-pN.js";
+import { H as EventMap, T as EventKey, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-CXIq6GWK.js";
 import { t as StateOf } from "./state-of-C19H6BoV.js";
 import { Readable } from "svelte/store";
 //#region src/svelte/plugin.d.ts

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { H as EventMap, v as Bus, y as BusOptions } from "./action-creator-DprJV-pN.js";
+import { H as EventMap, v as Bus, y as BusOptions } from "./action-creator-CXIq6GWK.js";
 //#region src/testing/clock.d.ts
 /** What the runner needs from time: move it forward, and read it. */
 type Clock = {

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-import { B as Tracer, H as EventMap, J as TaskInfo, K as Phase, V as EffectName, X as TraceEvent, Y as Trace, Z as TraceLogger, v as Bus } from "./action-creator-DprJV-pN.js";
+import { B as Tracer, H as EventMap, J as TaskInfo, K as Phase, V as EffectName, X as TraceEvent, Y as Trace, Z as TraceLogger, v as Bus } from "./action-creator-CXIq6GWK.js";
 //#region src/graph/serialize.d.ts
 type JsonValue = null | boolean | number | string | JsonValue[] | {
   [key: string]: JsonValue;

package/dist/{types-DxPZDzZG.d.ts → types-ByoeMqVh.d.ts}

@@ -1,5 +1,5 @@
-import { H as EventMap, c as Scope, l as WithFields, p as Effects } from "./action-creator-DprJV-pN.js";
-import { t as BoundOf } from "./plugin-2d3uuW7o.js";
+import { H as EventMap, c as Scope, l as WithFields, p as Effects } from "./action-creator-CXIq6GWK.js";
+import { t as BoundOf } from "./plugin-B8La3K9m.js";
 //#region src/scope/types.d.ts
 /**
  * The slots `scopePlugin` fills for `modulePlugin`. They are not on `Bus`: a bus

package/dist/vue.d.ts

@@ -1,4 +1,4 @@
-import { H as EventMap, T as EventKey, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-DprJV-pN.js";
+import { H as EventMap, T as EventKey, a as FreeActionCreator, t as ActionCreator, v as Bus } from "./action-creator-CXIq6GWK.js";
 import { t as OriginOptions } from "./origin-key-CxK0SkeG.js";
 import { t as StateOf } from "./state-of-C19H6BoV.js";
 import { ShallowRef, WatchSource, WatchStopHandle } from "vue";

package/dist/{with-policy-Y12d-yx6.d.ts → with-policy-e4yx1vhN.d.ts}

@@ -1,4 +1,4 @@
-import { G as PayloadOf, H as EventMap, q as Task } from "./action-creator-DprJV-pN.js";
+import { G as PayloadOf, H as EventMap, q as Task } from "./action-creator-CXIq6GWK.js";
 //#region src/policies/with-policy.d.ts
 /** What `withPolicy` returns: the task as a plain function that can be cancelled. */
 type PolicyFunction<P, R> = {

package/docs/README.md

@@ -3,10 +3,11 @@
 nanoeffects moves business logic and side effects out of UI components into plain `async` functions. Policies (`latest`, `debounce`, `queue`) and effects (`retry`, `timeout`, `poll`) handle races, retries and cancellation.
 
 ```js
+// search.js
 import { createBus } from "nanoeffects";
 import { latest } from "nanoeffects/policies";
 
-const bus = createBus(); // event bus
+export const bus = createBus(); // event bus
 
 // The search logic lives outside the component; latest aborts the previous request
 bus.on(
@@ -22,7 +23,33 @@ bus.on("found", (items) => render(items));
 bus.emit("search", "nano");
 ```
 
-The same example with a UI framework: [React](react.md), [Vue](vue.md), [Svelte](svelte.md). Ready projects: [Start a project from a template](starter.md).
+In a component, the same bus needs no extra code. This is React; the handler stays in `search.js`:
+
+```jsx
+// SearchBox.jsx
+import { useEffect, useState } from "react";
+import { bus } from "./search";
+
+export function SearchBox() {
+  const [items, setItems] = useState([]);
+
+  // on returns the unbind function; returning it removes the listener on unmount
+  useEffect(() => bus.on("found", setItems), []);
+
+  return (
+    <>
+      <input onChange={(event) => bus.emit("search", event.target.value)} />
+      <ul>
+        {items.map((item) => (
+          <li key={item.id}>{item.title}</li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
+The same example step by step: [React](react.md), [Vue](vue.md), [Svelte](svelte.md). Ready projects: [Start a project from a template](starter.md).
 
 ## Install
 

package/docs/cancel-stale-requests.md

@@ -47,7 +47,7 @@ bus.on("results", (items) => render(items));
 
 What to replace: `api.search` is your own request function. It must accept `{ signal }` and give it to `fetch`. Without it, `latest` still ignores the old result, but the request keeps running.
 
-To make the mistake impossible, bind the signal once: `contextPlugin({ fetch: fromSignal(signalFetch) })` gives every handler a `ctx.fetch` that stops with the handler ([how](pass-the-signal.md#bind-the-signal-once)). To find the requests that already forget it, use `devPlugin` while you develop, and `getLostSignalsCount(bus)` in a test ([how](pass-the-signal.md#count-lost-signals-in-a-test)).
+To make the mistake impossible, bind the signal once: `signalFetch(ctx, url)` is a `fetch` that stops with the handler, and `effectsPlugin({ fetch: signalFetch })` gives every handler a `ctx.fetch` of it ([how](pass-the-signal.md#bind-the-signal-once)). To find the requests that already forget it, use `devPlugin` while you develop, and `getLostSignalsCount(bus)` in a test ([how](pass-the-signal.md#count-lost-signals-in-a-test)).
 
 Result: `emit("search", "ab")` followed by `emit("search", "abc")` shows only the results for `abc`, and the request for `ab` is cancelled.
 

package/docs/context.md

@@ -99,7 +99,7 @@ bus.on("user/open", async (id, ctx) => {
 });
 ```
 
-- `signalFetch` from the same entry is a `fetch` bound to a signal, so `fetch: fromSignal(signalFetch)` gives every handler a `ctx.fetch` that stops with the task. [Bind the signal once](pass-the-signal.md#bind-the-signal-once)
+- For `fetch` you need no `fromSignal`: `signalFetch(ctx, url)` from the same entry stops with the task, and `effectsPlugin({ fetch: signalFetch })` gives every handler a `ctx.fetch`. [Bind the signal once](pass-the-signal.md#bind-the-signal-once)
 - `make` runs at the first read, so a handler that never uses `ctx.http` pays nothing for it.
 - A task that `ctx.run` starts builds its own value from its own signal, so aborting the child stops only the child's requests.
 - The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.

package/docs/package.md

@@ -9,7 +9,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | Import | What is in it |
 | ------ | ------------- |
 | `nanoeffects` | `createBus`, the types |
-| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
+| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue`, `dedupe`, `distinct`, `rateLimit`, `batch` |
 | `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
 
 ## Add the rest when you need it
@@ -21,7 +21,7 @@ Each row is optional. The "when" column says what need brings you to it.
 | `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` | `emit` must return a result, or domain logic leaves the UI |
 | `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events | `on` must take a function that picks events |
 | `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value | a store or client must be on every task |
-| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal`; `fromSignal` and `signalFetch`: a client or a `fetch` made from the signal of each task | an outside `AbortSignal` (request, React Query) must stop tasks, or a handler must not pass the signal by hand |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal`; `signalFetch(ctx, url)`: a `fetch` that stops with its task; `fromSignal`: a client made from the signal of each task | an outside `AbortSignal` (request, React Query) must stop tasks, or a handler must not pass the signal by hand |
 | `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` | you write classes, not functions |
 | `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) | one action or module needs its own fields |
 | `nanoeffects/redux` | `createEffectsMiddleware` | you already use Redux |

package/docs/pass-the-signal.md

@@ -22,25 +22,36 @@ A policy such as `latest` cancels an older call by aborting its `ctx.signal`. Th
 
 ## Bind the signal once
 
-The surest fix is a handler with no signal in it. Make the client from the signal of the task, once, and the handler calls `ctx.fetch` and cannot forget anything. `signalFetch` is a `fetch` bound to a signal; `fromSignal` builds it for each task.
+The surest fix is a handler that never writes a signal. `signalFetch` is a `fetch` that takes `ctx` first, like `retry(ctx, ...)`: the request carries `ctx.signal`, so there is nothing to forget.
 
 ```js
-// bus.js
-import { createBus } from "nanoeffects";
-import { contextPlugin } from "nanoeffects/context";
-import { fromSignal, signalFetch } from "nanoeffects/signal";
-import axios from "axios";
+// search-handlers.js
+import { latest } from "nanoeffects/policies";
+import { signalFetch } from "nanoeffects/signal";
+import { bus } from "./bus";
 
-// fromSignal — ctx.fetch is made from the signal of the task that reads it
-export const bus = createBus().use(
-  contextPlugin({
-    fetch: fromSignal(signalFetch),
-    // your own client too: it is made from the signal of each task
-    http: fromSignal((signal) => axios.create({ signal })),
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // signalFetch — fetch with ctx.signal: it stops when the policy cancels the handler
+    const response = await signalFetch(ctx, `/api?q=${query}`);
+    ctx.emit("results", await response.json());
   }),
 );
 ```
 
+To get `ctx.fetch` in every handler, put the effect on the context once. `effectsPlugin` binds it to each task, so the handler drops the `ctx` argument:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { effectsPlugin } from "nanoeffects/effects";
+import { signalFetch } from "nanoeffects/signal";
+
+// effectsPlugin — ctx.fetch is signalFetch bound to the task that reads it
+export const bus = createBus().use(effectsPlugin({ fetch: signalFetch }));
+```
+
 ```js
 // search-handlers.js
 import { latest } from "nanoeffects/policies";
@@ -48,10 +59,27 @@ import { bus } from "./bus";
 
 bus.on(
   "search",
-  latest(async (query, ctx) => {
-    // no signal here: ctx.fetch stops when the policy cancels the handler
-    const response = await ctx.fetch(`/api?q=${query}`);
-    ctx.emit("results", await response.json());
+  latest(async (query, { fetch, emit }) => {
+    // no signal and no ctx argument: fetch stops when the policy cancels the handler
+    const response = await fetch(`/api?q=${query}`);
+    emit("results", await response.json());
+  }),
+);
+```
+
+A client that is not an effect, such as an `axios` instance, is made from the signal of each task with `fromSignal`:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal } from "nanoeffects/signal";
+import axios from "axios";
+
+// fromSignal — ctx.http is made from the signal of the task that reads it
+export const bus = createBus().use(
+  contextPlugin({
+    http: fromSignal((signal) => axios.create({ signal })),
   }),
 );
 ```
@@ -123,7 +151,7 @@ Each row is a situation where the signal is easy to lose. The right column says
 | A function takes the signal and never uses it: `search(query, options) { return fetch(url); }` | Pass the signal on inside it. Only type information finds this in the linter; a test finds it for sure | types | |
 | The signal is wired by hand: `signal.addEventListener("abort", ...)` | Nothing, the handler is not checked step by step | accepted | |
 | `bus.emit` in a handler | Use `ctx.emit`: only it is dropped after the handler was cancelled | yes | |
-| A request that keeps running after the cancel, on Node | Pass the signal, or use `ctx.fetch` | | yes |
+| A request that keeps running after the cancel, on Node | Pass the signal, or use `signalFetch(ctx, url)` | | yes |
 | Results emitted after the cancel | The handler ignored the signal. Pass it, or check `ctx.signal.aborted` | | yes |
 | `ctx.on` after the cancel | The same | | yes |
 

package/docs/policies.md

@@ -6,6 +6,30 @@ Use this page when handlers overlap in a SPA (search-as-you-type, double submit,
 
 Start with `latest`. The table and sections below are the rest of the reference.
 
+## On this page
+
+- [`latest`: abort the previous run](#latest-abort-the-previous-run)
+- [Choose a policy](#choose-a-policy)
+- [Look up a policy](#look-up-a-policy)
+  - [`latest`](#latest)
+  - [`leading`](#leading)
+  - [`debounce`](#debounce)
+  - [`throttle`](#throttle)
+  - [`queue`](#queue)
+  - [`dedupe`](#dedupe)
+  - [`distinct`](#distinct)
+  - [`rateLimit`](#ratelimit)
+  - [`batch`](#batch)
+  - [`key`](#key)
+- [Configure debounce and throttle](#configure-debounce-and-throttle)
+- [`key`: isolate state by key](#key-isolate-state-by-key)
+- [Run calls one after another with `queue`](#run-calls-one-after-another-with-queue)
+- [`dedupe`: share one run between equal calls](#dedupe-share-one-run-between-equal-calls)
+- [`distinct`: skip a repeated payload](#distinct-skip-a-repeated-payload)
+- [`rateLimit`: stay under a quota](#ratelimit-stay-under-a-quota)
+- [`batch`: send many calls as one](#batch-send-many-calls-as-one)
+- [`withPolicy`: call a policy outside a bus](#withpolicy-call-a-policy-outside-a-bus)
+
 ## `latest`: abort the previous run
 
 ```js
@@ -24,7 +48,7 @@ bus.on(
 );
 ```
 
-Pass `signal` to `fetch` (and the like) so the request cancels. To not pass it at all, bind it once: with `ctx.fetch` the request stops with the handler and there is nothing to forget ([Keep the signal through a handler](pass-the-signal.md#bind-the-signal-once)).
+Pass `signal` to `fetch` (and the like) so the request cancels. To not pass it at all, bind it once: with `signalFetch(ctx, url)` the request stops with the handler and there is nothing to forget ([Keep the signal through a handler](pass-the-signal.md#bind-the-signal-once)).
 
 ## Choose a policy
 
@@ -37,6 +61,10 @@ Every policy accepts `key` in its options (see [`key`: isolate state by key](#ke
 | `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 |
+| `dedupe(fn, options?)` | calls with the same key share the run that is going |
+| `distinct(fn, options?)` | a call with the same payload as the last one is skipped |
+| `rateLimit(limit, ms, fn, options?)` | at most `limit` runs start per `ms`, the rest wait |
+| `batch(ms, fn, options?)` | payloads of one window go to `fn` as one array |
 
 Each policy has a short entry in [Look up a policy](#look-up-a-policy).
 
@@ -84,6 +112,38 @@ Signature: `queue(fn, options?)`.
 
 More: [Run calls one after another with `queue`](#run-calls-one-after-another-with-queue).
 
+### `dedupe`
+
+Calls with the same key that come while a run is going wait for that run and get its result. Nothing is cached.
+
+Signature: `dedupe(fn, options?)`.
+
+More: [`dedupe`: share one run between equal calls](#dedupe-share-one-run-between-equal-calls).
+
+### `distinct`
+
+A call whose payload equals the last one is skipped and resolves with `undefined`.
+
+Signature: `distinct(fn, options?)`.
+
+More: [`distinct`: skip a repeated payload](#distinct-skip-a-repeated-payload).
+
+### `rateLimit`
+
+At most `limit` runs start in any window of `ms`. The other calls wait for their turn.
+
+Signature: `rateLimit(limit, ms, fn, options?)`.
+
+More: [`rateLimit`: stay under a quota](#ratelimit-stay-under-a-quota).
+
+### `batch`
+
+Collects the payloads that come in a window of `ms` and calls `fn` once with all of them.
+
+Signature: `batch(ms, fn, options?)`.
+
+More: [`batch`: send many calls as one](#batch-send-many-calls-as-one).
+
 ### `key`
 
 An option of every policy. It splits the state of the policy by a property, for example by id: calls with different keys do not affect each other.
@@ -169,6 +229,134 @@ Every call returns a promise with the result of its own run. An error rejects on
 - 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.
 
+## `dedupe`: share one run between equal calls
+
+> **Level B or C.** Use it for reads that several parts of the screen start at the same time.
+
+**Problem.** Three components ask for user `1` in the same tick. Without a policy that is three identical requests.
+
+**When.** A read that is safe to repeat: a profile, a config, a list by id. For a write use [`leading`](prevent-double-submit.md) or [`queue`](#run-calls-one-after-another-with-queue): see the abort rule below.
+
+`dedupe` starts `fn` for the first call. A call with the same key that comes while that run is going waits for it and gets its result, or its error. When the run ends, `dedupe` forgets it, and the next call starts `fn` again. It is not a cache: it never returns an old value.
+
+```js
+import { dedupe, withPolicy } from "nanoeffects/policies";
+
+// dedupe — callers with the same id share one request
+const policy = dedupe((id, { signal }) => api.getUser(id, { signal }));
+
+// withPolicy — a plain function, so the example shows the result of each call
+const loadUser = withPolicy(policy);
+
+// two callers, one request: both get the same user
+const [first, second] = await Promise.all([loadUser(1), loadUser(1)]);
+```
+
+On a bus it looks the same, `bus.on("user/load", dedupe(handler))`. To get the result of `emit` use an action or a job ([Actions](actions.md)).
+
+| Option | Meaning |
+| ------ | ------- |
+| `key` | what makes two calls "the same". Default: the payload itself, compared like a `Map` key. Objects never match unless `key` says how. `key: () => "all"` shares one run between every call |
+
+**Abort:**
+
+- A caller whose task aborts resolves with `undefined`. The others go on.
+- The run belongs to the task of the first caller. If that task aborts while others still wait, the run is aborted and started again with the next caller, so `fn` can run twice for one request. That is fine for a read and wrong for a write.
+- Pass `signal` into what `fn` does, as for any policy.
+
+## `distinct`: skip a repeated payload
+
+> **Level B.** Use it when the same value keeps arriving and repeating the work is a waste.
+
+**Problem.** A form saves on every change. A user types a letter and deletes it, and the same text goes to the server again.
+
+`distinct` compares the payload of each call with the payload of the last call it let through. An equal payload is skipped: `fn` does not run and the call resolves with `undefined`. It remembers one payload, never a result.
+
+```js
+import { distinct, withPolicy } from "nanoeffects/policies";
+
+// distinct — runs only when the text differs from the last one it let through
+const policy = distinct(async (text) => {
+  await api.save(text);
+});
+const save = withPolicy(policy);
+
+await save("hello"); // runs
+await save("hello"); // skipped, resolves undefined
+await save("hello!"); // runs: the text changed
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `equals(previous, next)` | tells whether two payloads are the same. Default: `Object.is` |
+| `key` | each key remembers its own payload |
+
+- The payload counts as seen from the moment its run starts, so the same payload that arrives while the run goes is skipped too.
+- It is forgotten when the run fails or its task aborts, so a retry with the same payload runs.
+- The memory of a key stays after the run. Unlike other policies, `distinct` does not drop idle keys, so give `key` values from a bounded set (a form id, not a request id).
+
+## `rateLimit`: stay under a quota
+
+> **Level C.** Use it when an API allows N requests per period.
+
+**Problem.** A geocoding API allows 5 requests per second. A list of 40 addresses sends 40 requests at once, and most of them fail with `429`.
+
+`rateLimit(limit, ms, fn)` lets at most `limit` runs start in any window of `ms` milliseconds. The window slides: it is counted back from each call. A call over the limit waits and starts, in order, when the oldest start leaves the window.
+
+```js
+import { rateLimit, withPolicy } from "nanoeffects/policies";
+
+// rateLimit — 5 runs may start per second, the rest wait their turn
+const policy = rateLimit(5, 1000, (address, { signal }) => {
+  return api.geocode(address, { signal });
+});
+const geocode = withPolicy(policy);
+
+const addresses = ["10 Main St", "22 Oak Ave", "5 Pine Rd", "8 Elm St", "3 Lake Dr", "9 Hill Ln"];
+
+// the first five start at once, the sixth a second later
+const results = await Promise.all(addresses.map(geocode));
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `overflow` | `"wait"` (default) keeps a call until it can start. `"drop"` drops a call that finds the window full: it resolves with `undefined` |
+| `key` | each key has its own window, for example one per user |
+
+- It limits **starts**, not how many runs go at the same time, and it does not wait for a run to end. For both limits write `queue(rateLimit(5, 1000, fn), { concurrency: 2 })`: a call keeps its slot in the queue while it waits for the window.
+- A call whose task aborts while it waits leaves the line. Aborting a run that has started does not give its place in the window back: the request was sent.
+- A `limit` below 1 is 1.
+
+## `batch`: send many calls as one
+
+> **Level C.** Use it when work is cheaper in bulk: events for analytics, log lines, "get these ids".
+
+**Problem.** A page sends an analytics event for every click, 30 requests a minute. The server prefers one request with all of them.
+
+`batch(ms, fn)` opens a window of `ms` at the first call and collects the payloads that come in it. When the window closes, `fn` runs once with an array of them, in the order of the calls. The window does not move when more calls come, so a steady stream is sent every `ms`, not only when it stops.
+
+```js
+import { batch, withPolicy } from "nanoeffects/policies";
+
+// batch — fn gets an array of everything that came within 500 ms
+const policy = batch(500, async (events) => {
+  await api.sendEvents(events);
+});
+const track = withPolicy(policy);
+
+track({ name: "open" });
+track({ name: "click" }); // one request with both events, 500 ms after the first
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `maxSize` | send the batch at once when it holds this many payloads |
+| `key` | each key collects its own batch, for example one per user |
+
+- Every call resolves with what `fn` returned for its batch: the same value for all, or the same error. `batch` does not split an array result between callers.
+- A call whose task aborts while the batch is collecting leaves it and resolves with `undefined`. When every call has left, nothing runs.
+- `fn` gets the context of the first caller that is still waiting. If that task aborts while `fn` runs, the run is aborted and every caller of that batch resolves with `undefined`. The run is not repeated: part of a bulk call may have happened.
+
 ## `withPolicy`: call a policy outside a bus
 
 **Problem.** You want a debounced input handler or a "latest request wins" fetch for your own function, but the code has no bus: a DOM handler, a click callback, a function in a service. A policy needs a context on every call, so `debounce(300, search)("re")` does not work on its own.

package/docs/react.md

@@ -8,6 +8,47 @@ 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.
 
+The shortest version: a name field that asks the backend whether the name is free. The rest of the page builds a whole form from it.
+
+```js
+// username.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus, created once
+
+// the name check, outside the component; latest aborts the check of the previous name
+bus.on(
+  "username/typed",
+  latest(async (name, ctx) => {
+    const available = await api.usernameAvailable(name, { signal: ctx.signal });
+    ctx.emit("username/checked", available);
+  }),
+);
+```
+
+```jsx
+// NameField.jsx
+import { useEffect, useState } from "react";
+import { bus } from "./username";
+
+export function NameField() {
+  const [available, setAvailable] = useState(null); // null: not checked yet
+
+  // on returns the unbind function; returning it removes the listener on unmount
+  useEffect(() => bus.on("username/checked", setAvailable), []);
+
+  return (
+    <>
+      <input onChange={(event) => bus.emit("username/typed", event.target.value)} />
+      {available === false && <p>This name is taken</p>}
+    </>
+  );
+}
+```
+
+The handler knows nothing about React, and the component knows nothing about requests.
+
 ## On this page
 
 - [Problems of the form without a bus](#problems-of-the-form-without-a-bus)