nanoeffects 0.34.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/docs/ru/svelte.md

@@ -6,6 +6,47 @@
 
 Нужны Svelte 5 или новее и установленная `nanoeffects`. Не знакомы с шиной? Сначала прочитайте [Руководство](guide.md).
 
+Самый короткий вариант: поле поиска, которое показывает найденное обработчиком. Плагин для этого не нужен; разделы ниже добавляют помощник, который сокращает компонент.
+
+```js
+// search.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // шина, создаётся один раз
+
+// логика поиска вне компонента; latest прерывает предыдущий запрос
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("found", items);
+  }),
+);
+```
+
+Обработчик ничего не знает об UI, а компонент только отправляет `search` и слушает `found`.
+
+<!-- docs-check: skip - a .svelte file -->
+```svelte
+<script>
+  import { bus } from "./search";
+
+  let items = $state([]);
+
+  // on возвращает функцию отписки; $effect вызывает её при очистке
+  $effect(() => bus.on("found", (found) => (items = found)));
+</script>
+
+<input oninput={(event) => bus.emit("search", event.target.value)} />
+<ul>
+  {#each items as item (item.id)}
+    <li>{item.title}</li>
+  {/each}
+</ul>
+```
+
+
 ## Плагин на шине
 
 **Проблема.** Компонент Svelte читает значение через `$store`, а событие шины — не store. Без помощи компонент пишет свой `readable` и `bus.on` и должен не забыть отписаться. Эти строки копируются в каждый компонент.

package/docs/ru/vue.md

@@ -6,6 +6,51 @@
 
 Нужны Vue 3.3 или новее и установленная `nanoeffects`. Не знакомы с шиной? Сначала прочитайте [Руководство](guide.md).
 
+Самый короткий вариант: поле поиска, которое показывает найденное обработчиком. Плагин для этого не нужен; разделы ниже добавляют помощник, который сокращает компонент.
+
+```js
+// search.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // шина, создаётся один раз
+
+// логика поиска вне компонента; latest прерывает предыдущий запрос
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("found", items);
+  }),
+);
+```
+
+Обработчик ничего не знает об UI, а компонент только отправляет `search` и слушает `found`.
+
+<!-- docs-check: skip - a .vue file -->
+```vue
+<script setup>
+import { onUnmounted, ref } from "vue";
+import { bus } from "./search";
+
+const items = ref([]);
+
+// on возвращает функцию отписки; при размонтировании вызываем её
+const unbind = bus.on("found", (found) => {
+  items.value = found;
+});
+onUnmounted(unbind);
+</script>
+
+<template>
+  <input @input="bus.emit('search', $event.target.value)" />
+  <ul>
+    <li v-for="item in items" :key="item.id">{{ item.title }}</li>
+  </ul>
+</template>
+```
+
+
 ## Плагин на шине
 
 **Проблема.** Без помощи компонент пишет `watch(query, (value) => bus.emit(queryChanged(value)))` и собственную подписку в `onMounted` и `onUnmounted`. Эти строки копируются в каждый компонент, и в каждой копии что-нибудь забыто: очистка, проверка равенства или имя подписки в трассировке.

package/docs/svelte.md

@@ -6,6 +6,47 @@ Use this page when your app is in Svelte 5 and a component has to show the resul
 
 You need Svelte 5 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
 
+The shortest version: a search box that shows what the handler found. No plugin is needed for this; the sections below add a helper that shortens the component.
+
+```js
+// search.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus, created once
+
+// the search logic, outside the component; latest aborts the previous request
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("found", items);
+  }),
+);
+```
+
+The handler knows nothing about the UI, and the component only sends `search` and listens to `found`.
+
+<!-- docs-check: skip - a .svelte file -->
+```svelte
+<script>
+  import { bus } from "./search";
+
+  let items = $state([]);
+
+  // on returns the unbind function; $effect calls it on cleanup
+  $effect(() => bus.on("found", (found) => (items = found)));
+</script>
+
+<input oninput={(event) => bus.emit("search", event.target.value)} />
+<ul>
+  {#each items as item (item.id)}
+    <li>{item.title}</li>
+  {/each}
+</ul>
+```
+
+
 ## Add the plugin to the bus
 
 **Problem.** A Svelte component reads a value with `$store`. An event of the bus is not a store, so without help the component writes its own `readable` and its own `bus.on`, and has to remember to stop listening. The same few lines are copied into every component.

package/docs/vue.md

@@ -6,6 +6,51 @@ Use this page when your app is in Vue 3 and a component has to talk to the bus:
 
 You need Vue 3.3 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
 
+The shortest version: a search box that shows what the handler found. No plugin is needed for this; the sections below add a helper that shortens the component.
+
+```js
+// search.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+export const bus = createBus(); // the bus, created once
+
+// the search logic, outside the component; latest aborts the previous request
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query, { signal: ctx.signal });
+    ctx.emit("found", items);
+  }),
+);
+```
+
+The handler knows nothing about the UI, and the component only sends `search` and listens to `found`.
+
+<!-- docs-check: skip - a .vue file -->
+```vue
+<script setup>
+import { onUnmounted, ref } from "vue";
+import { bus } from "./search";
+
+const items = ref([]);
+
+// on returns the unbind function; unmounting calls it
+const unbind = bus.on("found", (found) => {
+  items.value = found;
+});
+onUnmounted(unbind);
+</script>
+
+<template>
+  <input @input="bus.emit('search', $event.target.value)" />
+  <ul>
+    <li v-for="item in items" :key="item.id">{{ item.title }}</li>
+  </ul>
+</template>
+```
+
+
 ## Add the plugin to the bus
 
 **Problem.** Without help, a component writes `watch(query, (value) => bus.emit(queryChanged(value)))` and its own subscription in `onMounted` and `onUnmounted`. The same few lines are copied into every component, and each copy forgets something: the cleanup, the equality check, or the name of the subscription in the trace.