nanoeffects 0.35.0 → 0.36.0

package/docs/ru/recipes.md

@@ -16,6 +16,8 @@
   - [Второй клик отправляет второй запрос](#второй-клик-отправляет-второй-запрос)
   - [Сообщения должны уходить по порядку](#сообщения-должны-уходить-по-порядку)
   - [Кнопка «Удалить» в списке блокирует соседние строки](#кнопка-удалить-в-списке-блокирует-соседние-строки)
+  - [Несколько компонентов запрашивают одни и те же данные](#несколько-компонентов-запрашивают-одни-и-те-же-данные)
+  - [Форма сохраняет один и тот же текст дважды](#форма-сохраняет-один-и-тот-же-текст-дважды)
 - [Ненадёжная сеть и длинные сценарии](#ненадёжная-сеть-и-длинные-сценарии)
   - [Запрос иногда падает: retry и backoff](#запрос-иногда-падает-retry-и-backoff)
   - [Запрос зависает: timeout](#запрос-зависает-timeout)
@@ -23,6 +25,8 @@
   - [Дождаться другого события внутри обработчика: take](#дождаться-другого-события-внутри-обработчика-take)
   - [Загрузить несколько ресурсов сразу: all](#загрузить-несколько-ресурсов-сразу-all)
   - [Взять самый быстрый ответ: race](#взять-самый-быстрый-ответ-race)
+  - [API разрешает только N запросов в секунду](#api-разрешает-только-n-запросов-в-секунду)
+  - [Много мелких событий, один запрос](#много-мелких-событий-один-запрос)
 - [Фичи и доменная логика](#фичи-и-доменная-логика)
   - [Получить результат от emit](#получить-результат-от-emit)
   - [Сгруппировать фичу с её обработчиками: модули](#сгруппировать-фичу-с-её-обработчиками-модули)
@@ -238,6 +242,49 @@ bus.on(
 
 Подробнее: [Политики, `key`](policies.md#key-разделение-state-по-ключу).
 
+### Несколько компонентов запрашивают одни и те же данные
+
+Страница показывает пользователя в шапке, в сайдбаре и в комментарии, и все три запрашивают пользователя `1` в одном такте. Это три одинаковых запроса. `dedupe` заставляет вызовы с одним id делить один запрос. Используйте его для чтения, а не для записи.
+
+```js
+import { createBus } from "nanoeffects";
+import { dedupe } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// dedupe — вызов для id, который уже загружается, ждёт этот запрос
+bus.on(
+  "user/needed",
+  dedupe(async (id, ctx) => {
+    const user = await api.getUser(id, { signal: ctx.signal });
+    ctx.emit("user/loaded", user);
+  }),
+);
+```
+
+Подробнее: [Политики, `dedupe`](policies.md#dedupe-общий-запуск-для-одинаковых-вызовов).
+
+### Форма сохраняет один и тот же текст дважды
+
+Форма сохраняется при каждом изменении. Пользователь набрал букву и стёр её, и тот же текст снова уходит на сервер. `distinct` пропускает вызов, чей payload равен последнему.
+
+```js
+import { createBus } from "nanoeffects";
+import { distinct } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// distinct — текст, равный последнему сохранённому, пропускается
+bus.on(
+  "draft/changed",
+  distinct(async (text, { signal }) => {
+    await api.saveDraft(text, { signal });
+  }),
+);
+```
+
+Подробнее: [Политики, `distinct`](policies.md#distinct-пропуск-повторного-payload).
+
 ## Ненадёжная сеть и длинные сценарии
 
 ### Запрос иногда падает: retry и backoff
@@ -369,6 +416,49 @@ bus.on("user/opened", async (id, ctx) => {
 
 Подробнее: [`all`](effects.md#all), [`race`](effects.md#race).
 
+### API разрешает только N запросов в секунду
+
+API геокодирования разрешает 5 запросов в секунду. Список из 40 адресов отправляет 40 запросов сразу, и большинство падает с `429`. `rateLimit` запускает пять и держит остальные, пока окно не сдвинется.
+
+```js
+import { createBus } from "nanoeffects";
+import { rateLimit } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// rateLimit — за секунду могут начаться пять запросов, остальные ждут своей очереди
+bus.on(
+  "address/geocode",
+  rateLimit(5, 1000, async (address, ctx) => {
+    const place = await api.geocode(address, { signal: ctx.signal });
+    ctx.emit("address/found", place);
+  }),
+);
+```
+
+Подробнее: [Политики, `rateLimit`](policies.md#ratelimit-соблюдение-квоты).
+
+### Много мелких событий, один запрос
+
+Страница отправляет событие аналитики на каждый клик, 30 запросов в минуту. Серверу удобнее один запрос со всеми. `batch` собирает события, пришедшие за окно, и отправляет их вместе.
+
+```js
+import { createBus } from "nanoeffects";
+import { batch } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// batch — всё, что пришло за 500 мс, уходит одним запросом
+bus.on(
+  "analytics/event",
+  batch(500, async (events, { signal }) => {
+    await api.sendEvents(events, { signal });
+  }),
+);
+```
+
+Подробнее: [Политики, `batch`](policies.md#batch-отправка-нескольких-вызовов-одним).
+
 ## Фичи и доменная логика
 
 ### Получить результат от emit

package/llms-full.txt

@@ -568,6 +568,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)
@@ -575,6 +577,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)
@@ -790,6 +794,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
@@ -921,6 +968,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
@@ -1300,7 +1390,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
@@ -1754,6 +1844,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
@@ -1785,6 +1899,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).
 
@@ -1832,6 +1950,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.
@@ -1917,6 +2067,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/llms.txt

@@ -23,7 +23,7 @@ Rules that generated code often gets wrong:
 
 ## Async UI and unreliable networks
 
-- [Policies](docs/policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, and `key`; `withPolicy` makes one a plain function without a bus
+- [Policies](docs/policies.md): `latest`, `leading`, `debounce`, `throttle`, `queue`, `dedupe`, `distinct`, `rateLimit`, `batch`, and `key`; `withPolicy` makes one a plain function without a bus
 - [Cancel stale requests and fix race conditions](docs/cancel-stale-requests.md): an older response overwrites a newer one; `latest`, `debounce`, `retry`, `timeout` in one recipe
 - [Pause between requests](docs/debounce-and-abort.md): `debounce` outside, `latest` inside, and when to use `throttle`
 - [Prevent a double submit](docs/prevent-double-submit.md): `leading`, one run per item with `key`, retry only on network errors

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nanoeffects",
-	"version": "0.35.0",
+	"version": "0.36.0",
 	"description": "Business logic and side effects outside UI components, as plain async functions. Tiny, no dependencies.",
 	"keywords": [
 		"event-bus",
@@ -226,7 +226,7 @@
 		{
 			"name": "policies (all)",
 			"path": "dist/policies.js",
-			"limit": "2.71 kB"
+			"limit": "3.71 kB"
 		},
 		{
 			"name": "effects (all)",