nanoeffects 0.34.0 → 0.36.0

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/README.md

@@ -3,10 +3,11 @@
 nanoeffects выносит бизнес-логику и побочные эффекты из компонентов в обычные `async`-функции. Политики (`latest`, `debounce`, `queue`) и эффекты (`retry`, `timeout`, `poll`) решают гонки, повторы и отмену запросов.
 
 ```js
+// search.js
 import { createBus } from "nanoeffects";
 import { latest } from "nanoeffects/policies";
 
-const bus = createBus(); // шина событий
+export const bus = createBus(); // шина событий
 
 // Логика поиска живёт вне компонента; latest прерывает предыдущий запрос
 bus.on(
@@ -22,7 +23,33 @@ bus.on("found", (items) => render(items));
 bus.emit("search", "nano");
 ```
 
-Тот же пример с UI-фреймворком: [React](react.md), [Vue](vue.md), [Svelte](svelte.md). Готовые проекты: [Проект из шаблона](starter.md).
+В компоненте та же шина не требует лишнего кода. Пример на React; обработчик остаётся в `search.js`:
+
+```jsx
+// SearchBox.jsx
+import { useEffect, useState } from "react";
+import { bus } from "./search";
+
+export function SearchBox() {
+  const [items, setItems] = useState([]);
+
+  // on возвращает функцию отписки; если вернуть её из эффекта, подписка снимается при размонтировании
+  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>
+    </>
+  );
+}
+```
+
+Тот же пример по шагам: [React](react.md), [Vue](vue.md), [Svelte](svelte.md). Готовые проекты: [Проект из шаблона](starter.md).
 
 ## Установка
 

package/docs/ru/cancel-stale-requests.md

@@ -47,7 +47,7 @@ bus.on("results", (items) => render(items));
 
 Что заменить: `api.search` — ваша функция запроса. Она должна принимать `{ signal }` и передавать его в `fetch`. Без этого `latest` по-прежнему игнорирует старый результат, но запрос продолжает выполняться.
 
-Чтобы ошибка стала невозможной, привяжите сигнал один раз: `contextPlugin({ fetch: fromSignal(signalFetch) })` даёт каждому обработчику `ctx.fetch`, который останавливается вместе с обработчиком ([как](pass-the-signal.md#привязка-сигнала-один-раз)). Чтобы найти запросы, которые сигнал уже забывают, используйте `devPlugin` при разработке, а в тесте `getLostSignalsCount(bus)` ([как](pass-the-signal.md#подсчёт-потерянных-сигналов-в-тесте)).
+Чтобы ошибка стала невозможной, привяжите сигнал один раз: `signalFetch(ctx, url)` — это `fetch`, который останавливается вместе с обработчиком, а `effectsPlugin({ fetch: signalFetch })` даёт каждому обработчику `ctx.fetch` из него ([как](pass-the-signal.md#привязка-сигнала-один-раз)). Чтобы найти запросы, которые сигнал уже забывают, используйте `devPlugin` при разработке, а в тесте `getLostSignalsCount(bus)` ([как](pass-the-signal.md#подсчёт-потерянных-сигналов-в-тесте)).
 
 Результат: после `emit("search", "ab")` и `emit("search", "abc")` вы увидите только результаты для `abc`, а запрос для `ab` отменится.
 

package/docs/ru/context.md

@@ -99,7 +99,7 @@ bus.on("user/open", async (id, ctx) => {
 });
 ```
 
-- `signalFetch` из той же точки входа — это `fetch`, привязанный к сигналу, поэтому `fetch: fromSignal(signalFetch)` даёт каждому обработчику `ctx.fetch`, который останавливается вместе с задачей. [Привязка сигнала один раз](pass-the-signal.md#привязка-сигнала-один-раз)
+- Для `fetch` `fromSignal` не нужен: `signalFetch(ctx, url)` из той же точки входа останавливается вместе с задачей, а `effectsPlugin({ fetch: signalFetch })` даёт каждому обработчику `ctx.fetch`. [Привязка сигнала один раз](pass-the-signal.md#привязка-сигнала-один-раз)
 - `make` запускается при первом чтении, поэтому обработчик, который никогда не использует `ctx.http`, ничего за него не платит.
 - Задача, которую запускает `ctx.run`, строит своё значение из своего сигнала, так что прерывание дочерней задачи останавливает только её запросы.
 - Поле не копируется через `{ ...ctx }`, и `Object.keys(ctx)` его не перечисляет. Если вы копируете контекст, сначала прочитайте `ctx.http`.

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` |
 
 ## Остальные импорты
@@ -17,7 +17,7 @@
 | `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` | `emit` должен вернуть результат или доменная логика уходит из UI |
 | `nanoeffects/match` | `matchPlugin`: `on`, `once` и `off` принимают функцию-фильтр вместо имени события | подписываться нужно по условию, а не по имени |
 | `nanoeffects/context` | `contextPlugin`: ваши собственные поля (store, клиент) на `ctx` каждой задачи, с типами по значению | store или клиент должен быть на каждой задаче |
-| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` привязывает задачи этого `emit` к внешнему `AbortSignal`; `fromSignal` и `signalFetch`: клиент или `fetch`, созданный из сигнала каждой задачи | внешний `AbortSignal` (запрос, React Query) должен останавливать задачи или обработчик не должен передавать сигнал вручную |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` привязывает задачи этого `emit` к внешнему `AbortSignal`; `signalFetch(ctx, url)`: `fetch`, который останавливается вместе с задачей; `fromSignal`: клиент, созданный из сигнала каждой задачи | внешний `AbortSignal` (запрос, React Query) должен останавливать задачи или обработчик не должен передавать сигнал вручную |
 | `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: методы шины на классе, подписки каждого экземпляра заканчиваются через `dispose()` | вы пишете классы, а не функции |
 | `nanoeffects/scope` | `scopePlugin`, `effect`: поля для одного action, задачи, модуля или `emit` (типы `Scope`, `Effect`) | одному action или модулю нужны свои поля |
 | `nanoeffects/redux` | `createEffectsMiddleware` | вы уже используете Redux |

package/docs/ru/pass-the-signal.md

@@ -22,25 +22,36 @@
 
 ## Привязка сигнала один раз
 
-Надёжнее всего обработчик, в котором сигнала нет вообще. Создайте клиент из сигнала задачи один раз, и обработчик вызывает `ctx.fetch`, ничего не забывая. `signalFetch` — это `fetch`, привязанный к сигналу; `fromSignal` создаёт его для каждой задачи.
+Надёжнее всего обработчик, в котором сигнал не пишется вообще. `signalFetch` — это `fetch`, который принимает `ctx` первым аргументом, как `retry(ctx, ...)`: запрос несёт `ctx.signal`, и забыть нечего.
 
 ```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 создаётся из сигнала задачи, которая его читает
-export const bus = createBus().use(
-  contextPlugin({
-    fetch: fromSignal(signalFetch),
-    // и ваш клиент тоже: он создаётся из сигнала каждой задачи
-    http: fromSignal((signal) => axios.create({ signal })),
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // signalFetch — fetch с ctx.signal: останавливается, когда политика отменяет обработчик
+    const response = await signalFetch(ctx, `/api?q=${query}`);
+    ctx.emit("results", await response.json());
   }),
 );
 ```
 
+Чтобы `ctx.fetch` был в каждом обработчике, положите эффект на контекст один раз. `effectsPlugin` привязывает его к каждой задаче, поэтому обработчик обходится без аргумента `ctx`:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { effectsPlugin } from "nanoeffects/effects";
+import { signalFetch } from "nanoeffects/signal";
+
+// effectsPlugin — ctx.fetch это signalFetch, привязанный к задаче, которая его читает
+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) => {
-    // сигнала здесь нет: ctx.fetch останавливается, когда политика отменяет обработчик
-    const response = await ctx.fetch(`/api?q=${query}`);
-    ctx.emit("results", await response.json());
+  latest(async (query, { fetch, emit }) => {
+    // ни сигнала, ни аргумента ctx: fetch останавливается, когда политика отменяет обработчик
+    const response = await fetch(`/api?q=${query}`);
+    emit("results", await response.json());
+  }),
+);
+```
+
+Клиент, который не является эффектом, например экземпляр `axios`, создаётся из сигнала каждой задачи через `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 создаётся из сигнала задачи, которая его читает
+export const bus = createBus().use(
+  contextPlugin({
+    http: fromSignal((signal) => axios.create({ signal })),
   }),
 );
 ```
@@ -105,7 +133,7 @@ bus.on(
 | Ситуация | Что сделать | Линтер | devPlugin |
 | -------- | ----------- | :----: | :-------: |
 | У обработчика нет `ctx`: `latest(async (query) => ...)` | Возьмите `(query, ctx)` и передайте `ctx.signal` | да | |
-| `ctx` взят, но в запрос не передан | Передайте `{ signal: ctx.signal }` в каждый запрос или привяжите его один раз: `ctx.fetch` ([выше](#привязка-сигнала-один-раз)) | да | да |
+| `ctx` взят, но в запрос не передан | Передайте `{ signal: ctx.signal }` в каждый запрос или привяжите его один раз: `signalFetch(ctx, url)` ([выше](#привязка-сигнала-один-раз)) | да | да |
 | Один шаг передаёт сигнал, другой нет | Передайте его каждому шагу | да | да |
 | Сигнал лежит в переменной: `const options = { signal: ctx.signal }` | Ничего: переменная с сигналом считается | принимает | |
 | Вызовы идут вместе: `Promise.all([a(), b()])` | Передайте сигнал каждому вызову, а не одному | да | |
@@ -123,7 +151,7 @@ bus.on(
 | Функция принимает сигнал и не использует его: `search(query, options) { return fetch(url); }` | Передайте сигнал дальше внутри неё. В линтере это находит только информация о типах; тест находит наверняка | типы | |
 | Сигнал подключён вручную: `signal.addEventListener("abort", ...)` | Ничего: такой обработчик не проверяется по шагам | принимает | |
 | `bus.emit` в обработчике | Используйте `ctx.emit`: только его отбрасывают после отмены обработчика | да | |
-| Запрос продолжает идти после отмены, на Node | Передайте сигнал или используйте `ctx.fetch` | | да |
+| Запрос продолжает идти после отмены, на Node | Передайте сигнал или используйте `signalFetch(ctx, url)` | | да |
 | Результаты отправлены после отмены | Обработчик проигнорировал сигнал. Передайте его или проверьте `ctx.signal.aborted` | | да |
 | `ctx.on` после отмены | То же | | да |
 

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
@@ -24,7 +48,7 @@ bus.on(
 );
 ```
 
-Передайте `signal` в `fetch` (и подобные вызовы), чтобы запрос отменялся. Чтобы не передавать его вообще, привяжите сигнал один раз: с `ctx.fetch` запрос останавливается вместе с обработчиком, и забыть нечего ([Сохранение сигнала в обработчике](pass-the-signal.md#привязка-сигнала-один-раз)).
+Передайте `signal` в `fetch` (и подобные вызовы), чтобы запрос отменялся. Чтобы не передавать его вообще, привяжите сигнал один раз: с `signalFetch(ctx, url)` запрос останавливается вместе с обработчиком, и забыть нечего ([Сохранение сигнала в обработчике](pass-the-signal.md#привязка-сигнала-один-раз)).
 
 ## Таблица политик
 
@@ -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")` сам по себе не работает.

package/docs/ru/react.md

@@ -8,6 +8,47 @@
 
 Нужен проект на React с установленной `nanoeffects`. Форма общается с вашим клиентом, `api` ниже: замените его своими запросами.
 
+Самый короткий вариант: поле имени, которое спрашивает backend, свободно ли оно. Остальная страница строит из него форму целиком.
+
+```js
+// username.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // шина, создаётся один раз
+
+// проверка имени вне компонента; latest прерывает проверку предыдущего имени
+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 возвращает функцию отписки; если вернуть её из эффекта, подписка снимается при размонтировании
+  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>}
+    </>
+  );
+}
+```
+
+Обработчик ничего не знает о React, а компонент ничего не знает о запросах.
+
 ## На этой странице
 
 - [Проблемы формы без шины](#проблемы-формы-без-шины)