nanoeffects 0.29.0 → 0.31.0

package/docs/ru/migrating-from-rxjs.md

@@ -0,0 +1,197 @@
+# nanoeffects рядом с RxJS
+
+> **[Уровень E](README.md#виды-проектов)**: для тех, кто знает RxJS. Сначала прочитайте: [Руководство](guide.md#1-создание-шины-событий).
+
+nanoeffects не заменяет RxJS, они делят работу: RxJS формирует потоки значений, nanoeffects выполняет побочные эффекты, которые запускают события. Операторы сопоставлены, поле поиска и цикл опроса показаны в обоих вариантах, перечислено то, что остаётся в RxJS.
+
+## Разделение работы
+
+| Задача | Использовать |
+| ------ | ------------ |
+| Начать запрос, когда что-то происходит, отменить его, когда приходит более новый, повторить, ограничить по времени | nanoeffects |
+| Знать, какая задача что запустила, логировать и трассировать | nanoeffects ([Трассировка](tracing.md)) |
+| Объединять несколько потоков, хранить накопленное значение, буферизовать, окна, слияние во времени | RxJS |
+| Работать с потоком как со значением (`map`, `scan`, `combineLatest`) | RxJS |
+
+Обработчик в nanoeffects — одна функция на событие. Конвейер в RxJS — цепочка операторов над потоком. Если ваш конвейер — несколько операторов, заканчивающихся `switchMap` и запросом, он помещается в обработчик с политикой и становится короче. Конвейер, который объединяет потоки, остаётся в RxJS.
+
+## Соответствие
+
+| RxJS | nanoeffects |
+| ---- | ----------- |
+| `mergeMap` | `bus.on(event, handler)`: каждое событие запускает задачу |
+| `switchMap` | [`latest`](policies.md) |
+| `exhaustMap` | [`leading`](policies.md) |
+| `concatMap` | [`queue`](policies.md) |
+| `debounceTime` | [`debounce`](policies.md) |
+| `throttleTime` | [`throttle`](policies.md) |
+| `groupBy` + `switchMap` | `latest(handler, { key })` |
+| `retry`, `retryWhen` | [`retry`, `backoff`](effects.md) |
+| `timeout` | [`timeout`](effects.md) |
+| `interval` + `switchMap` | [`poll`](effects.md) |
+| `takeUntil(stop$)` | `ctx.signal` и [`take`](effects.md), чтобы дождаться события остановки |
+| `forkJoin` | [`all`](effects.md) |
+| `race` | [`race`](effects.md) |
+| `firstValueFrom(fromEvent(…))` | [`take(ctx, event)`](effects.md) |
+| `Subject` | `bus.emit` и `bus.on` |
+| `map`, `filter`, `scan`, `combineLatest`, `buffer`, `window`, `share` | остаются в RxJS |
+| `distinctUntilChanged` | проверка в обработчике или в подписке на store (см. [State managers](stores.md)) |
+
+Политика и оператор различаются в одном. `switchMap` отбрасывает старый внутренний поток. `latest` прерывает старую задачу через её `signal`, так что `fetch`, получивший сигнал, останавливается. Передавайте сигнал дальше, иначе работа продолжится в фоне.
+
+## Переписанное поле поиска
+
+Та же задача в RxJS: дождаться паузы, пропустить повторы, отменить старый запрос.
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+// RxJS
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map, switchMap } from "rxjs/operators";
+
+fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+    switchMap((query) => api.searchStream(query)),
+  )
+  .subscribe((items) => render(items));
+```
+
+Та же задача в nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus(); // шина: события и обработчики
+
+// latest: новый поиск прерывает запрос в полёте
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce: запуск после 300 мс без нового "typed"
+bus.on("typed", debounce(300, searchLatest));
+
+bus.on("results", (items) => render(items));
+
+const input = document.querySelector("#search"); // поле поиска
+input.addEventListener("input", (event) => bus.emit("typed", event.target.value));
+```
+
+Пропуска повторяющихся значений здесь нет. Добавьте в обработчик `if (query === lastQuery) return;` или оставьте этот единственный шаг в RxJS (следующий раздел).
+
+## Переписанный цикл опроса
+
+Проверять статус задачи каждые 5 секунд. Повторять упавшую проверку и остановиться, когда пользователь покидает экран.
+
+Та же задача в RxJS: `timer` тикает, `exhaustMap` пропускает тик, пока идёт проверка, `retry` повторяет упавшую проверку, `takeUntil` останавливает.
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+// RxJS
+import { timer } from "rxjs";
+import { exhaustMap, retry, takeUntil } from "rxjs/operators";
+
+timer(5000, 5000)
+  .pipe(
+    exhaustMap(() => api.statusStream().pipe(retry({ count: 3, delay: 500 }))),
+    takeUntil(leave$),
+  )
+  .subscribe((status) => render(status));
+```
+
+Та же задача в nanoeffects. `poll` тикает, `retry` повторяет одну проверку, а `race` завершает цикл на первом событии `"leave"`:
+
+```js
+import { createBus } from "nanoeffects";
+import { poll, race, retry, take } from "nanoeffects/effects";
+
+const bus = createBus(); // шина: события и обработчики
+
+bus.on("watch", async (_, ctx) => {
+  // одна проверка, до 3 попыток, 500 мс между ними
+  const checkStatus = async () => {
+    const status = await retry(ctx, () => api.status({ signal: ctx.signal }), {
+      times: 3,
+      delay: 500,
+    });
+    ctx.emit("status", status);
+  };
+
+  await race(ctx, {
+    // poll без ctx: проверка каждые 5 с; waitForFn: следующая пауза начинается после окончания проверки
+    polling: poll(5000, checkStatus, { waitForFn: true }),
+    // take без ctx: завершается на ближайшем "leave", а race останавливает опрос
+    leave: take("leave"),
+  });
+});
+
+bus.on("status", (status) => render(status));
+
+bus.emit("watch"); // старт
+bus.emit("leave"); // остановка
+```
+
+От конвейера отличаются две вещи:
+
+- `waitForFn: true` играет роль `exhaustMap`: проверки никогда не пересекаются. Без него `poll` держит ровный темп, и медленная проверка может пересечься со следующей.
+- Если падают все 3 попытки, ошибка останавливает `poll`, как ошибка завершает Observable. Чтобы продолжать опрос после упавшей проверки, поймайте ошибку внутри `checkStatus` и отправьте событие `"error"`.
+
+## Совместное использование в одном приложении
+
+Оставьте RxJS там, где удобно мыслить потоком, а события передавайте между RxJS и шиной в любом направлении.
+
+**Шина → RxJS.** `createObserve(bus)` даёт Observable события ([Observable](observable.md)).
+
+**RxJS → шина.** `bus.emitter(action)` возвращает callback, отправляющий action, так что он годится как аргумент `subscribe` ([State managers](stores.md) описывают плагин).
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // добавляет bus.emitter
+```
+
+```js
+// filters.js
+import { createAction } from "nanoeffects/actions";
+
+export const filtersChanged = createAction("filters/changed"); // обычный action creator
+```
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+import { combineLatest } from "rxjs";
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+import { filtersChanged } from "./filters";
+
+// RxJS: объединить два потока в одно значение; nanoeffects этого не делает
+const subscription = combineLatest([query$, category$]).subscribe(
+  bus.emitter(filtersChanged), // вызывает bus.emit(filtersChanged(value))
+);
+
+// nanoeffects: один отменяемый запрос на каждое изменение фильтров
+bus.on(
+  filtersChanged,
+  latest(async ([query, category], { signal }) => {
+    const items = await api.search(query, category, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+Подписка не привязана к задаче. Вызовите `subscription.unsubscribe()`, когда экран исчезает.
+
+## Отличия
+
+- **Нет потоков значений.** Обработчик получает одну payload и запускает задачу. Нет `pipe`, нет оператора для последующих значений.
+- **Прерывание заменяет отписку для работы в полёте.** Остановленная задача останавливается через её `signal`. Передайте его в `fetch` или в клиент.
+- **Ошибки не часть потока.** Упавшая задача отклоняет собственный Promise. Без `onError` на шине об ошибке никто больше не узнает ([Ошибки](errors.md)).
+- **Нет завершения.** Шина событий не заканчивается. Задача заканчивается, когда кончается её работа или прерывается её сигнал.
+- **Нет marble-тестов.** Тестируйте настоящий обработчик с поддельными таймерами.

package/docs/ru/migrating-from-saga.md

@@ -0,0 +1,97 @@
+# Переход с redux-saga
+
+> **[Уровень E](README.md#виды-проектов)**: для тех, кто знает redux-saga. Сначала прочитайте: [Руководство](guide.md#1-создание-шины-событий).
+
+Для тех, кто знает redux-saga и ищет те же задачи в nanoeffects. Имена сопоставлены, одна сага переписана, перечислено то, у чего аналога нет. Саму библиотеку страница не объясняет: начните с [Руководства](guide.md).
+
+## Соответствие
+
+| redux-saga | nanoeffects |
+| ---------- | ----------- |
+| `takeEvery` | `bus.on(event, handler)` |
+| `takeLatest` | [`latest`](policies.md) |
+| `takeLeading` | [`leading`](policies.md) |
+| `debounce`, `throttle` | [`debounce`, `throttle`](policies.md) (те же правила, что у lodash) |
+| `call(fn, x)` | `await ctx.run(task, x)` |
+| `fork(fn, x)` | `ctx.run(task, x)` без `await` |
+| `spawn(fn, x)` | `ctx.emit(event, x)` или `bus.emit(event, x)` |
+| `put(action)` | `ctx.emit(action)` |
+| `take(pattern)` | [`take(ctx, event, { predicate })`](effects.md), где `event` — имя или action creator |
+| `select` | [поле контекста](context.md), например `store` |
+| `all`, `race` | [`all`, `race`](effects.md) |
+| `retry`, `delay` | [`retry`, `delay`](effects.md) |
+| `cancel(task)` | `ctx.abort()` на контексте или более новый вызов под `latest` |
+| `eventChannel` | `bus.emitter(action)` как callback подписки |
+| `actionChannel` | [`queue`](policies.md) и другие политики |
+
+## Переписанная сага
+
+Сага на каждый новый запрос запускает поиск, отменяет предыдущий и повторяет упавший вызов:
+
+<!-- docs-check: skip - код redux-saga, не nanoeffects -->
+```js
+// redux-saga
+function* search({ payload }) {
+  const items = yield retry(3, 1000, api.search, payload);
+  yield put(found(items));
+}
+function* watchSearch() {
+  yield takeLatest("search", search);
+}
+```
+
+Та же задача в nanoeffects:
+
+```js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus(); // шина: события и обработчики
+
+const search = (query, { signal }) => api.search(query, { signal });
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // latest: новый "search" прерывает этот запуск; ctx.signal прерван
+    const load = retry(search, { times: 3, delay: 1000 }); // retry: до 3 попыток с паузой 1 с
+    const items = await ctx.run(load, query); // дочерняя задача, прерывается вместе с этим обработчиком
+    ctx.emit("found", items); // как put
+  }),
+);
+```
+
+Задачи — обычные `async`-функции. `ctx.signal` заменяет `cancel`: передайте его в `fetch` или в ваш клиент, и запрос остановится.
+
+[Пример counter](../../examples/counter) показывает счётчик, `takeLatest` с `delay`, отмену и падающий вызов. В нём две страницы: без store и с Redux Toolkit.
+
+## Запуск задачи без ожидания
+
+`fork` и `spawn` различаются тем, что происходит, когда вызывающий прерывается. Выбирайте по этому признаку.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus(); // шина: события и обработчики
+
+const loadSidebar = (_, { signal }) => api.sidebar({ signal });
+
+bus.on("page-opened", async (_, ctx) => {
+  // как fork: дочерняя задача этой, прерывается вместе с ней
+  const warmUp = ctx.run(loadSidebar);
+  warmUp.catch(console.error); // никто её не ждёт, так что обработайте ошибку здесь
+
+  // как spawn: новая задача, не останавливается, когда эта прервана
+  ctx.emit("analytics", { page: "home" });
+});
+```
+
+## Отличия
+
+- **Ошибки поднимаются только через `await`.** `await ctx.run(task)` и `all(ctx, …)` выбрасывают ошибку дочерней задачи вызывающему. Дочерняя задача, которую никто не ждёт, не прерывает родителя, в отличие от fork в redux-saga. Обработайте ошибку сами, как выше. См. [Ошибки](errors.md).
+- **Прерывание идёт вниз.** Прерывание задачи прерывает её дочерние задачи. Дочерняя задача не прерывает соседей.
+- **Эффекты — не данные.** `yield call(fn)` возвращает описание, которое тест может сравнить. Здесь `await` вызывает функцию. Тестируйте настоящий обработчик с поддельными таймерами, как тесты этой библиотеки.
+- **Нет генераторов.** Последовательные сценарии — это `async`-функции с `await take(ctx, event)`.
+- **Нет `END` канала.** Задача останавливается, когда прерывается её сигнал.
+- **Одна payload.** У задачи один аргумент, поэтому передавайте объект там, где сага передаёт несколько.

package/docs/ru/motivation.md

@@ -0,0 +1,47 @@
+# Зачем нужна nanoeffects
+
+> **[Уровень A](README.md#виды-проектов)**: небольшое приложение, виджет или MVP.
+
+Страница объясняет, зачем нужна библиотека. nanoeffects выносит бизнес-логику и побочные эффекты из компонентов React, Vue или Svelte в обычные `async`-функции: с отменой, повторами и контекстом для зависимостей. API здесь не объясняется: начните с [Руководства](guide.md).
+
+## Вынесение логики из пользовательского интерфейса
+
+Компоненты с запросами, таймерами и гонками трудно тестировать и легко сломать. Обычное решение — вынести логику в сервисы и чистые функции. Тогда каждому сервису нужно одно и то же: отменять ненужную работу, повторять запросы, делиться зависимостями и показывать, что выполнилось и почему.
+
+Привычные инструменты требуют многого: redux-saga описывает эту логику генераторами, RxJS — потоками и операторами. nanoeffects оставляет обычные `async`-функции и добавляет одну идею — `AbortSignal`.
+
+Ещё один способ вынести логику — контейнеры внедрения зависимостей (DI), например в Angular или в отдельных библиотеках. В nanoeffects контейнера нет, но внедрять зависимости можно на уровне контракта: обработчик берёт нужное из `ctx`, а что именно дать, решает шина. См. [Поля контекста](context.md).
+
+Шина событий — основа библиотеки, но не главная ценность: любой эмиттер отправляет события (`nanoevents` весит около 100 байт, [таких библиотек ещё десятки](https://github.com/gajus/sister#similar-libraries)). nanoeffects добавляет:
+
+- отменяемые задачи, политики и эффекты;
+- контекст — небольшой контейнер зависимостей;
+- actions и модули, чтобы сгруппировать фичу;
+- [трассировку](tracing.md) с адаптером для Redux DevTools.
+
+Библиотека работает с тем, что уже есть в проекте: рецепты и небольшие адаптеры для [stores](stores.md) (Redux Toolkit, Zustand, MobX, Pinia), мост к [RxJS](migrating-from-rxjs.md), помощники для [React](react.md), [Vue](vue.md) и [Svelte](svelte.md). Для старта ничего переписывать не нужно.
+
+## Микрофронтенды
+
+В микрофронтендах каждое приложение может принести свои версии одних и тех же библиотек. Хуже всего библиотеки state и событий: они хранят **внутреннее state и идентичность** (store, контекст, класс). Две копии или версии такой библиотеки не сливаются и молча перестают видеть друг друга. Разные версии и копии не только работают несогласованно: они тянут больше кода и ресурсов, чем одна согласованная копия. Поэтому цель — максимально простой проект с минимумом общих зависимостей, которые хранят state.
+
+В Module Federation это видно сразу. Каждый remote добавляет свою копию, пока команды не договорятся о `singleton` и диапазоне версий. [Руководство Nx по версиям библиотек](https://nx.dev/docs/kb/manage-library-versions-with-module-federation) описывает последствия: библиотеки с внутренним state конфликтуют, а метод, которого нет в одной версии, ломает вызывающих, написанных под другую.
+
+Реальные случаи из библиотек, с которыми сравнивали nanoeffects:
+
+| Библиотека | Что идёт не так | Источник |
+| ---------- | --------------- | -------- |
+| Redux, React Redux | Общая библиотека компонентов использует `react-redux`. Каждый микрофронтенд должен взять ту же версию, иначе `react-redux` «странно ломается». | [react-redux#1949](https://github.com/reduxjs/react-redux/issues/1949) |
+| Redux | Store доступен только внутри `Provider`. Каждому под-приложению нужен свой провайдер, но при внедрении модуля второй создавать нельзя. Редьюсеры, продублированные в хосте и модуле, усугубляют проблему. | [Redux on Module Federation](https://dev.to/manomano-tech-team/how-to-work-with-redux-on-module-federation-13gm) |
+| Effector | Библиотека с `effector-react/scope`, собранная в другой проект, получает два экземпляра. `useStore` приложения не видит её `Provider`: «no scope found». | [effector#727](https://github.com/effector/effector/issues/727) |
+| RxJS | Две копии дают два класса `Observable`. Типы одной версии не подходят другой, а операторы, добавленные в одну копию, отсутствуют в другой. Совет — «одна версия в `node_modules`». | [RxJS#2984](https://github.com/ReactiveX/rxjs/issues/2984), [neo4j-javascript-driver#978](https://github.com/neo4j/neo4j-javascript-driver/issues/978) |
+
+У nanoeffects нет зависимостей и state уровня модуля: шина — объект, который вы создаёте сами. Две копии или версии пакета на одной странице дают две независимые шины. Глобально ничего не регистрируется, `Provider` не нужен, хост не выбирает версию за вас.
+
+## Что делает nanoeffects
+
+- **Нет зависимостей и глобального state.** Её безопасно поставлять в SDK рядом с кодом хост-приложения. Запись `singleton` в конфиге Module Federation не нужна.
+- **Помещается в жёсткий бюджет.** На весь сторонний код SDK часто дают несколько килобайт. `createBus` весит около 1,4 кБ в gzip (1,3 кБ в brotli). Политики, эффекты и actions — отдельные точки входа: импортируйте их, когда нужно. См. [Точки входа пакета](package.md).
+- **Легко начать.** Вся модель — `on` и `emit`. Отмена, повторы и остальное — обычные функции поверх. [Руководство](guide.md) и [Переход с redux-saga](migrating-from-saga.md) сопоставляют знакомые имена.
+- **`emit` может вернуть ответ.** [Action с обработчиком](actions.md) возвращает результат, и один модуль может спросить другой и дождаться ответа. Голые события так не умеют. Именно этого больше всего не хватало вариантам на Redux.
+- **Легко отлаживать.** Событийный код читать трудно: виден эффект, а не вызвавшее его событие. Каждая задача знает своего родителя, поэтому [трассировка](tracing.md) показывает цепочку событий. Логгеры работают с консолью, панелью Performance и Redux DevTools.

package/docs/ru/observable.md

@@ -0,0 +1,233 @@
+# Превращение событий в Observable
+
+> **[Уровень F](README.md#виды-проектов)**: платформа, SDK или долгоживущее приложение. Сначала прочитайте: [Руководство](guide.md#1-создание-шины-событий).
+
+Для приложения, которое уже работает с Observable или RxJS и получает событие шины как поток. Если вы начинаете с нуля, берите `bus.on` с политиками: они отменяют работу и видны в трассировках.
+
+В той же точке входа есть `events`: он передаёт событие в цикл `for await` и не требует библиотеки потоков. См. [Чтение события циклом `for await`](#чтение-события-циклом-for-await).
+
+`createObserve(bus)` из `nanoeffects/observable` превращает событие шины в Observable по предложению TC39 (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS и другие библиотеки потоков принимают его как есть. Сама точка входа от них не зависит.
+
+## Событие как поток
+
+Проблема: поле поиска отправляет `typed` на каждую клавишу. Нужно дождаться паузы и пропустить повторы знакомыми операторами.
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+import { createBus } from "nanoeffects";
+import { createObserve } from "nanoeffects/observable";
+import { from } from "rxjs";
+import { debounceTime, distinctUntilChanged } from "rxjs/operators";
+
+const bus = createBus(); // шина: события и обработчики
+const observe = createObserve(bus); // observe(event) даёт Observable на имя события
+
+const typed$ = from(observe("typed")); // RxJS оборачивает его через from()
+
+const subscription = typed$
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query)); // обратно в шину
+```
+
+- `observe(event)` возвращает Observable нагрузок этого события. Каждый `subscribe` — отдельный `bus.on`; `unsubscribe()` его снимает.
+- `subscribe` принимает функцию или объект с `next`.
+- Типы следуют карте событий: `observe("typed")` — это `Observable<string>`, когда `typed` содержит строку.
+
+## Отправка потока в шину
+
+Проблема: `.subscribe((value) => bus.emit(action(value)))` повторяет шину и action в каждой подписке. `bus.emitter(action)` из `emitterPlugin` возвращает готовый callback для `subscribe`. Он подходит любому источнику с функцией `next`: потоку RxJS, callback store, DOM-обработчику.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { emitterPlugin } from "nanoeffects/actions";
+
+export const bus = createBus().use(emitterPlugin()); // добавляет bus.emitter
+```
+
+```js
+// search.js
+import { createAction } from "nanoeffects/actions";
+
+export const queryChanged = createAction("search/queryChanged"); // обычный action creator
+```
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+import { fromEvent } from "rxjs";
+import { debounceTime, distinctUntilChanged, map } from "rxjs/operators";
+import { bus } from "./bus";
+import { queryChanged } from "./search";
+
+const input = document.querySelector("#search"); // поле поиска
+
+const subscription = fromEvent(input, "input")
+  .pipe(
+    map((event) => event.target.value),
+    debounceTime(300),
+    distinctUntilChanged(),
+  )
+  .subscribe(bus.emitter(queryChanged)); // вызывает bus.emit(queryChanged(value))
+
+bus.on(queryChanged, (query) => console.log("search for", query));
+```
+
+Observable может быть откуда угодно, не только из `createObserve`. `subscription.unsubscribe()` останавливает его; шина о нём не знает. Передавайте callback в `subscribe` как есть и не вызывайте `bus.emitter(...)` внутри операторов на каждое значение.
+
+## Чтение и запись одного события через Subject
+
+Проблема: `createObserve` только читает. Коду для потоков часто нужно ещё и отправлять значения в то же событие, а передавать для этого шину и имя события неудобно.
+
+`Subject` — одно событие шины как один объект. `subscribe` слушает, `next` отправляет. В нём нет `complete`, `error` и повтора значений: событие шины не заканчивается, а шина значений не хранит.
+
+```js
+import { createBus } from "nanoeffects";
+import { Subject } from "nanoeffects/observable";
+
+const bus = createBus(); // шина: события и обработчики
+
+const typed = new Subject(bus, "typed"); // Subject — событие "typed" как поток, в который можно ещё и писать
+
+const subscription = typed.subscribe((text) => console.log(text)); // как bus.on("typed", …)
+typed.next("hello"); // как bus.emit("typed", "hello"): срабатывают и обработчики bus.on, и подписчики
+subscription.unsubscribe(); // снимает только эту подписку
+```
+
+- `next` работает и отдельно от subject, поэтому `input.addEventListener("input", (event) => typed.next(event.target.value))` и `store.subscribe(typed.next)` обёртки не требуют.
+- Подписчик, добавленный позже, не получает значение, отправленное раньше. Если он должен получить значение, добавьте в RxJS `startWith` или `shareReplay`.
+- RxJS принимает `Subject` так же, как `createObserve`: `from(typed)`. Это не `Subject` из RxJS (нет `error`, `complete` или `pipe`), поэтому он не подходит там, где нужен тот тип.
+
+### Расширение для именованного потока
+
+Проблема: имя события повторяется везде, где создаётся поток. Подкласс фиксирует его один раз.
+
+```js
+import { createBus } from "nanoeffects";
+import { Subject } from "nanoeffects/observable";
+
+class TypedText extends Subject {
+  constructor(bus) {
+    super(bus, "typed"); // событие закреплено классом
+  }
+
+  next(text) {
+    super.next(text.trim()); // метод подкласса заменяет метод Subject
+  }
+}
+
+const bus = createBus(); // шина: события и обработчики
+const typed = new TypedText(bus);
+typed.next("  hello "); // отправляет "typed" со значением "hello"
+```
+
+### Использование внутри класса с шиной
+
+У класса, созданного через `extendBus`, есть свои `on` и `emit`. Передайте `this` как источник, и подписка принадлежит экземпляру, так что `dispose()` её завершает ([Классы с шиной](oop.md)).
+
+## Работа в обработчике вместо `switchMap`
+
+Observable хорошо формирует значения. Запрос лучше выполнять в обработчике с политикой: у него есть `signal`, и трассировка его показывает. Разделите работу: RxJS заканчивается на значении, шина запускает запрос.
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+import { latest } from "nanoeffects/policies";
+
+// RxJS: сформировать значения (debounce, пропуск повторов), затем передать их шине
+from(observe("typed"))
+  .pipe(debounceTime(300), distinctUntilChanged())
+  .subscribe((query) => bus.emit("search", query));
+
+// nanoeffects: один отменяемый запрос; новый "search" прерывает старый
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+```
+
+`switchMap` отбрасывает старый внутренний поток. `latest` прерывает старую задачу через `signal`, так что `fetch`, получивший сигнал, действительно останавливается.
+
+## Чтение события циклом `for await`
+
+Проблема: задаче нужно обрабатывать payload одного события по порядку и остановиться, когда экран закроется. `take` ждёт одну payload, а в обработчике негде разместить цикл.
+
+`events(source, event, options)` из `nanoeffects/observable` возвращает асинхронный итератор нагрузок. Он слушает с момента вызова, так что payload, пришедшая до первого чтения, сохраняется. `source` — шина или контекст задачи; с контекстом цикл заканчивается ещё и когда задача прерывается.
+
+```js
+import { createBus } from "nanoeffects";
+import { events } from "nanoeffects/observable";
+
+const bus = createBus();
+const controller = new AbortController();
+
+// events — payload "query/changed" по одной; хранит последние 3, пока цикл занят
+const queries = events(bus, "query/changed", {
+  signal: controller.signal,
+  buffer: 3,
+});
+
+async function watchQueries() {
+  for await (const query of queries) {
+    console.log("search for", query); // выполняется один раз на payload, по порядку
+  }
+}
+
+watchQueries().catch((reason) => console.log("stopped:", reason)); // прерывание отклоняет цикл
+bus.emit("query/changed", "cat");
+controller.abort("screen closed"); // цикл заканчивается с этой причиной
+```
+
+| Параметр | Что делает | По умолчанию |
+| -------- | ---------- | ------------ |
+| `signal` | Завершает цикл. Ожидающее чтение отклоняется с причиной прерывания. | нет |
+| `buffer` | Наибольшее число нагрузок, которые хранятся, пока цикл занят. | `Infinity` |
+| `overflow` | Какая payload уходит, когда буфер полон: `"drop-oldest"` или `"drop-newest"`. | `"drop-oldest"` |
+
+- `break`, `return` и выброс ошибки внутри цикла отписывают обработчик.
+- Без `buffer` цикл, который никогда не читает, хранит каждую payload. Для медленного цикла задайте `buffer`.
+- Событие шины не заканчивается, поэтому цикл заканчивается только по `break`, `signal` или задаче.
+- Внутри задачи `events(ctx, "query/changed")` не нуждается в `signal`: окончание задачи и есть конец.
+
+## Преобразование обратно в поток или Promise
+
+| Что нужно | Как писать |
+| --------- | ---------- |
+| Поток событий с операторами | `from(observe("event"))` |
+| Следующее событие как Promise | `firstValueFrom(from(observe("event")))`; внутри задачи то же делает `take(ctx, "event")` и учитывает прерывание |
+| События шины как класс RxJS `Observable` (для `instanceof` или `pipe` как метода) | `new Observable((subscriber) => observe("event").subscribe(subscriber))` |
+| Прерывание задачи как поток | `fromEvent(ctx.signal, "abort")`, для `takeUntil` |
+| Последнее значение для новых подписчиков | `from(observe("event")).pipe(shareReplay(1))`; Observable сам ничего не воспроизводит |
+
+События, сработавшие до `subscribe`, теряются: Observable горячий, как `bus.on`. Добавьте `startWith(initial)` или `shareReplay`, когда позднему подписчику нужно значение.
+
+## Завершение подписки
+
+Подписка из `observe` не привязана к задаче и сама не завершится. Выберите один способ:
+
+<!-- docs-check: skip - нужен rxjs, от которого проект не зависит -->
+```js
+import { fromEvent, from } from "rxjs";
+import { takeUntil } from "rxjs/operators";
+import { onAbort } from "nanoeffects/effects";
+
+bus.on("screen-opened", (_, ctx) => {
+  // takeUntil: остановить поток, когда задача прервётся
+  from(observe("typed"))
+    .pipe(takeUntil(fromEvent(ctx.signal, "abort")))
+    .subscribe((query) => bus.emit("search", query));
+
+  // или: onAbort вызывает unsubscribe за вас
+  const subscription = observe("scrolled").subscribe(updatePosition);
+  onAbort(ctx, subscription.unsubscribe);
+});
+```
+
+Вне задачи вызовите `subscription.unsubscribe()` сами, когда экран исчезает, или используйте сигнал модуля.
+
+## Ограничения
+
+- Поток никогда не завершается и не падает: приходят только события. Ошибку вашего подписчика шина обрабатывает, только если задан `onError` ([Ошибки](errors.md)).
+- `observe` обращается к шине при вызове `subscribe`, а не при создании. Создайте его один раз и вызывайте сколько нужно.
+- Операторы, хранящие state (`scan`, `buffer`, `window`), живут в RxJS. Шина значений не хранит. Полное разделение работы см. в [nanoeffects рядом с RxJS](migrating-from-rxjs.md).