nanoeffects 0.35.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,5 +1,5 @@
-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-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 stops with its task: an effect, so `ctx` is the first argument and the request carries

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/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

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
@@ -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/recipes.md

@@ -16,6 +16,8 @@ Each task below starts with the problem, then a short solution. Where the page h
   - [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)
+  - [Several components ask for the same data](#several-components-ask-for-the-same-data)
+  - [A form saves the same text twice](#a-form-saves-the-same-text-twice)
 - [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)
@@ -23,6 +25,8 @@ Each task below starts with the problem, then a short solution. Where the page h
   - [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)
+  - [An API allows only N requests per second](#an-api-allows-only-n-requests-per-second)
+  - [Many small events, one request](#many-small-events-one-request)
 - [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)
@@ -238,6 +242,49 @@ bus.on(
 
 More: [Policies, `key`](policies.md#key-isolate-state-by-key).
 
+### Several components ask for the same data
+
+A page shows a user in the header, in a sidebar and in a comment, and all three ask for user `1` in the same tick. That is three identical requests. `dedupe` makes the calls for one id share a single request. Use it for reads, not for writes.
+
+```js
+import { createBus } from "nanoeffects";
+import { dedupe } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// dedupe — a call for an id that is loading already waits for that request
+bus.on(
+  "user/needed",
+  dedupe(async (id, ctx) => {
+    const user = await api.getUser(id, { signal: ctx.signal });
+    ctx.emit("user/loaded", user);
+  }),
+);
+```
+
+More: [Policies, `dedupe`](policies.md#dedupe-share-one-run-between-equal-calls).
+
+### A form saves the same text twice
+
+A form saves on every change. A user types a letter and deletes it, and the same text goes to the server again. `distinct` skips a call whose payload equals the last one.
+
+```js
+import { createBus } from "nanoeffects";
+import { distinct } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// distinct — a text equal to the last saved one is skipped
+bus.on(
+  "draft/changed",
+  distinct(async (text, { signal }) => {
+    await api.saveDraft(text, { signal });
+  }),
+);
+```
+
+More: [Policies, `distinct`](policies.md#distinct-skip-a-repeated-payload).
+
 ## An unreliable network and long flows
 
 ### A request fails sometimes: retry and backoff
@@ -369,6 +416,49 @@ bus.on("user/opened", async (id, ctx) => {
 
 More: [`all`](effects.md#all), [`race`](effects.md#race).
 
+### An API allows only N requests per second
+
+A geocoding API allows 5 requests per second. A list of 40 addresses sends 40 requests at once, and most fail with `429`. `rateLimit` starts five and holds the rest until the window slides.
+
+```js
+import { createBus } from "nanoeffects";
+import { rateLimit } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// rateLimit — five requests may start per second, the others wait their turn
+bus.on(
+  "address/geocode",
+  rateLimit(5, 1000, async (address, ctx) => {
+    const place = await api.geocode(address, { signal: ctx.signal });
+    ctx.emit("address/found", place);
+  }),
+);
+```
+
+More: [Policies, `rateLimit`](policies.md#ratelimit-stay-under-a-quota).
+
+### Many small events, one request
+
+A page sends an analytics event on every click, 30 requests a minute. The server prefers one request with all of them. `batch` collects the events that come within a window and sends them together.
+
+```js
+import { createBus } from "nanoeffects";
+import { batch } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// batch — everything that comes within 500 ms goes in one request
+bus.on(
+  "analytics/event",
+  batch(500, async (events, { signal }) => {
+    await api.sendEvents(events, { signal });
+  }),
+);
+```
+
+More: [Policies, `batch`](policies.md#batch-send-many-calls-as-one).
+
 ## Features and domain logic
 
 ### Get the result of emit

package/docs/ru/package.md

@@ -7,7 +7,7 @@
 | Импорт | Что внутри |
 | ------ | ---------- |
 | `nanoeffects` | `createBus`, типы |
-| `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` |
 
 ## Остальные импорты

package/docs/ru/policies.md

@@ -6,6 +6,30 @@
 
 Начните с `latest`. Остальные политики — в таблице и разделах ниже.
 
+## На этой странице
+
+- [`latest`: прерывание предыдущего запуска](#latest-прерывание-предыдущего-запуска)
+- [Таблица политик](#таблица-политик)
+- [Справочник политик](#справочник-политик)
+  - [`latest`](#latest)
+  - [`leading`](#leading)
+  - [`debounce`](#debounce)
+  - [`throttle`](#throttle)
+  - [`queue`](#queue)
+  - [`dedupe`](#dedupe)
+  - [`distinct`](#distinct)
+  - [`rateLimit`](#ratelimit)
+  - [`batch`](#batch)
+  - [`key`](#key)
+- [Настройка debounce и throttle](#настройка-debounce-и-throttle)
+- [`key`: разделение state по ключу](#key-разделение-state-по-ключу)
+- [Очередь событий через `queue`](#очередь-событий-через-queue)
+- [`dedupe`: общий запуск для одинаковых вызовов](#dedupe-общий-запуск-для-одинаковых-вызовов)
+- [`distinct`: пропуск повторного payload](#distinct-пропуск-повторного-payload)
+- [`rateLimit`: соблюдение квоты](#ratelimit-соблюдение-квоты)
+- [`batch`: отправка нескольких вызовов одним](#batch-отправка-нескольких-вызовов-одним)
+- [`withPolicy`: вызов политики вне шины](#withpolicy-вызов-политики-вне-шины)
+
 ## `latest`: прерывание предыдущего запуска
 
 ```js
@@ -37,6 +61,10 @@ bus.on(
 | `debounce(ms, fn, options?)` | запуск после `ms` тишины |
 | `throttle(ms, fn, options?)` | не больше одного запуска за `ms` |
 | `queue(fn, options?)` | один за другим, по порядку |
+| `dedupe(fn, options?)` | вызовы с одним ключом делят идущий запуск |
+| `distinct(fn, options?)` | вызов с тем же payload, что и последний, пропускается |
+| `rateLimit(limit, ms, fn, options?)` | не больше `limit` запусков за `ms`, остальные ждут |
+| `batch(ms, fn, options?)` | payload одного окна попадают в `fn` одним массивом |
 
 ## Справочник политик
 
@@ -82,6 +110,38 @@ bus.on(
 
 Подробнее: [Очередь событий через `queue`](#очередь-событий-через-queue).
 
+### `dedupe`
+
+Вызовы с одним ключом, пришедшие во время запуска, ждут этот запуск и получают его результат. Ничего не кэшируется.
+
+Сигнатура: `dedupe(fn, options?)`.
+
+Подробнее: [`dedupe`: общий запуск для одинаковых вызовов](#dedupe-общий-запуск-для-одинаковых-вызовов).
+
+### `distinct`
+
+Вызов, чей payload равен последнему, пропускается и завершается значением `undefined`.
+
+Сигнатура: `distinct(fn, options?)`.
+
+Подробнее: [`distinct`: пропуск повторного payload](#distinct-пропуск-повторного-payload).
+
+### `rateLimit`
+
+В любом окне из `ms` начинается не больше `limit` запусков. Остальные вызовы ждут своей очереди.
+
+Сигнатура: `rateLimit(limit, ms, fn, options?)`.
+
+Подробнее: [`rateLimit`: соблюдение квоты](#ratelimit-соблюдение-квоты).
+
+### `batch`
+
+Собирает payload, пришедшие за окно в `ms`, и вызывает `fn` один раз со всеми ними.
+
+Сигнатура: `batch(ms, fn, options?)`.
+
+Подробнее: [`batch`: отправка нескольких вызовов одним](#batch-отправка-нескольких-вызовов-одним).
+
 ### `key`
 
 Параметр каждой политики. Он разделяет state политики по признаку, например по id: вызовы с разными ключами не влияют друг на друга.
@@ -167,6 +227,134 @@ bus.emit("save", draftB); // ждёт draftA, затем выполняется
 - Когда прерывается выполняющийся вызов, его слот освобождается сразу, а результат отбрасывается.
 - Передавайте `signal` в то, что делает `fn`. `fn`, который его игнорирует, может пересечься со следующим запуском.
 
+## `dedupe`: общий запуск для одинаковых вызовов
+
+> **Уровень B или C.** Подходит для чтения, которое несколько частей экрана запускают одновременно.
+
+**Проблема.** Три компонента в одном такте запрашивают пользователя `1`. Без политики это три одинаковых запроса.
+
+**Когда.** Для чтения, которое безопасно повторять: профиль, конфиг, список по id. Для записи используйте [`leading`](prevent-double-submit.md) или [`queue`](#очередь-событий-через-queue): см. правило прерывания ниже.
+
+`dedupe` запускает `fn` для первого вызова. Вызов с тем же ключом, пришедший, пока идёт этот запуск, ждёт его и получает его результат или его ошибку. Когда запуск закончился, `dedupe` его забывает, и следующий вызов запускает `fn` заново. Это не кэш: старое значение он не вернёт никогда.
+
+```js
+import { dedupe, withPolicy } from "nanoeffects/policies";
+
+// dedupe — вызовы с одним id делят один запрос
+const policy = dedupe((id, { signal }) => api.getUser(id, { signal }));
+
+// withPolicy — обычная функция, поэтому пример показывает результат каждого вызова
+const loadUser = withPolicy(policy);
+
+// два вызова, один запрос: оба получают одного пользователя
+const [first, second] = await Promise.all([loadUser(1), loadUser(1)]);
+```
+
+На шине выглядит так же: `bus.on("user/load", dedupe(handler))`. Чтобы получить результат `emit`, используйте action или job ([Actions](actions.md)).
+
+| Параметр | Значение |
+| -------- | -------- |
+| `key` | что делает два вызова «одинаковыми». По умолчанию сам payload, сравнивается как ключ `Map`. Объекты не совпадают, пока `key` не скажет как. `key: () => "all"` даёт один общий запуск на все вызовы |
+
+**Прерывание:**
+
+- Вызов, чья задача прервана, завершается значением `undefined`. Остальные продолжают.
+- Запуск принадлежит задаче первого вызова. Если эта задача прерывается, пока другие ещё ждут, запуск прерывается и начинается заново со следующим вызовом, поэтому `fn` может выполниться дважды для одного запроса. Для чтения это нормально, для записи — нет.
+- Передавайте `signal` в то, что делает `fn`, как для любой политики.
+
+## `distinct`: пропуск повторного payload
+
+> **Уровень B.** Подходит, когда одно и то же значение приходит снова и снова, а повторять работу не нужно.
+
+**Проблема.** Форма сохраняется при каждом изменении. Пользователь набрал букву и стёр её, и тот же текст снова уходит на сервер.
+
+`distinct` сравнивает payload каждого вызова с payload последнего пропущенного вызова. Равный payload пропускается: `fn` не запускается, а вызов завершается значением `undefined`. Политика помнит один payload, но не результат.
+
+```js
+import { distinct, withPolicy } from "nanoeffects/policies";
+
+// distinct — запускается, только если текст отличается от последнего пропущенного
+const policy = distinct(async (text) => {
+  await api.save(text);
+});
+const save = withPolicy(policy);
+
+await save("hello"); // выполняется
+await save("hello"); // пропущен, завершается значением undefined
+await save("hello!"); // выполняется: текст изменился
+```
+
+| Параметр | Значение |
+| -------- | -------- |
+| `equals(previous, next)` | говорит, одинаковы ли два payload. По умолчанию `Object.is` |
+| `key` | каждый ключ помнит свой payload |
+
+- Payload считается увиденным с момента начала его запуска, поэтому такой же payload, пришедший во время запуска, тоже пропускается.
+- Он забывается, когда запуск завершился ошибкой или его задача прервана, поэтому повтор с тем же payload выполнится.
+- Память ключа остаётся после запуска. В отличие от других политик, `distinct` не удаляет простаивающие ключи, поэтому давайте `key` значения из ограниченного набора (id формы, а не id запроса).
+
+## `rateLimit`: соблюдение квоты
+
+> **Уровень C.** Подходит, когда API разрешает N запросов за период.
+
+**Проблема.** API геокодирования разрешает 5 запросов в секунду. Список из 40 адресов отправляет 40 запросов сразу, и большинство падает с `429`.
+
+`rateLimit(limit, ms, fn)` разрешает начаться не больше чем `limit` запускам в любом окне из `ms` миллисекунд. Окно скользящее: оно отсчитывается назад от каждого вызова. Вызов сверх лимита ждёт и начинается по порядку, когда самый старый старт выходит из окна.
+
+```js
+import { rateLimit, withPolicy } from "nanoeffects/policies";
+
+// rateLimit — за секунду могут начаться 5 запусков, остальные ждут своей очереди
+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"];
+
+// первые пять начинаются сразу, шестой — через секунду
+const results = await Promise.all(addresses.map(geocode));
+```
+
+| Параметр | Значение |
+| -------- | -------- |
+| `overflow` | `"wait"` (по умолчанию) держит вызов, пока он не сможет начаться. `"drop"` отбрасывает вызов, который застал окно полным: он завершается значением `undefined` |
+| `key` | у каждого ключа своё окно, например по одному на пользователя |
+
+- Политика ограничивает **старты**, а не число одновременных запусков, и не ждёт окончания запуска. Для обоих ограничений напишите `queue(rateLimit(5, 1000, fn), { concurrency: 2 })`: вызов держит свой слот в очереди, пока ждёт окна.
+- Вызов, чья задача прервана во время ожидания, выходит из очереди. Прерывание уже начавшегося запуска не возвращает его место в окне: запрос уже отправлен.
+- `limit` меньше 1 считается равным 1.
+
+## `batch`: отправка нескольких вызовов одним
+
+> **Уровень C.** Подходит, когда работа дешевле оптом: события для аналитики, строки лога, запрос «дай эти id».
+
+**Проблема.** Страница отправляет событие аналитики на каждый клик, 30 запросов в минуту. Серверу удобнее один запрос со всеми.
+
+`batch(ms, fn)` открывает окно в `ms` на первом вызове и собирает payload, пришедшие за это время. Когда окно закрывается, `fn` запускается один раз с массивом из них, в порядке вызовов. Окно не сдвигается, когда приходят новые вызовы, поэтому постоянный поток отправляется каждые `ms`, а не только когда он затих.
+
+```js
+import { batch, withPolicy } from "nanoeffects/policies";
+
+// batch — fn получает массив всего, что пришло за 500 мс
+const policy = batch(500, async (events) => {
+  await api.sendEvents(events);
+});
+const track = withPolicy(policy);
+
+track({ name: "open" });
+track({ name: "click" }); // один запрос с обоими событиями, через 500 мс после первого
+```
+
+| Параметр | Значение |
+| -------- | -------- |
+| `maxSize` | отправить пакет сразу, когда в нём набралось столько payload |
+| `key` | каждый ключ собирает свой пакет, например по одному на пользователя |
+
+- Каждый вызов завершается тем, что `fn` вернул для его пакета: одно и то же значение для всех или одна и та же ошибка. `batch` не делит результат-массив между вызовами.
+- Вызов, чья задача прервана, пока пакет собирается, выходит из него и завершается значением `undefined`. Когда вышли все вызовы, ничего не запускается.
+- `fn` получает контекст первого вызова, который ещё ждёт. Если эта задача прерывается, пока идёт `fn`, запуск прерывается, и все вызовы этого пакета завершаются значением `undefined`. Запуск не повторяется: часть массового вызова могла уже выполниться.
+
 ## `withPolicy`: вызов политики вне шины
 
 **Проблема.** Нужен обработчик ввода с debounce или запрос по принципу «побеждает последний» для вашей собственной функции, но шины в коде нет: DOM-обработчик, callback клика, функция в сервисе. Политике на каждом вызове нужен контекст, поэтому `debounce(300, search)("re")` сам по себе не работает.