nanoeffects 0.29.0 → 0.30.1

package/docs/ru/chat-example.md

@@ -0,0 +1,259 @@
+# Чат с сущностями, фичами, модулями и небольшим backend
+
+> **[Уровень D](README.md#виды-проектов)**: доменная логика вне UI. Сначала прочитайте: [Actions, jobs и модули](actions.md).
+
+Разбор приложения с несколькими фичами, которые реагируют друг на друга: где живёт каждый кусок логики. Пример — чат с комнатами, загружаемой историей, сообщениями, которые могут не отправиться, поиском по всем комнатам и новыми сообщениями, приходящими сами. Небольшой backend на Fastify сбоит по известному расписанию, поэтому каждая проблема на странице действительно происходит.
+
+Это пример уровня D. Для API откройте [Actions, jobs и модули](actions.md), а для проекта поменьше — шаблон `domains-ts` из [Проекта из шаблона](starter.md#начало-с-доменами).
+
+Код лежит в [`examples/chat`](../../examples/chat). Запустите его на [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat) или на своей машине:
+
+```bash
+cd examples/chat
+npm install
+npm run dev
+```
+
+`npm run dev` запускает backend и Vite вместе. Чтобы отключить сбои, запустите `CHAOS=off npm run dev`.
+
+## На этой странице
+
+- [Как ведёт себя backend при сбоях](#как-ведёт-себя-backend-при-сбоях)
+- [Как разделены файлы](#как-разделены-файлы)
+- [Загрузка истории без гонки](#загрузка-истории-без-гонки)
+- [Отправка сообщения, которое может не дойти](#отправка-сообщения-которое-может-не-дойти)
+- [Поиск, где одна комната медленная](#поиск-где-одна-комната-медленная)
+- [Ожидание комнаты перед отметкой результата](#ожидание-комнаты-перед-отметкой-результата)
+- [Опрос новых сообщений](#опрос-новых-сообщений)
+- [Где живёт каждое значение](#где-живёт-каждое-значение)
+
+## Как ведёт себя backend при сбоях
+
+Backend хранит данные в памяти и сбоит по фиксированному расписанию. Повторите каждый сценарий из таблицы:
+
+| Что вы делаете | Что делает backend | Раздел |
+| -------------- | ----------------- | ------ |
+| Выбираете комнату, затем другую, прежде чем покажется первая | Комната Random загружает историю за 1,2 с, медленнее остальных. | [Загрузка истории без гонки](#загрузка-истории-без-гонки) |
+| Отправляете сообщения | Каждая третья отправка отвечает 503. | [Отправка сообщения, которое может не дойти](#отправка-сообщения-которое-может-не-дойти) |
+| Отправляете `/fail hello` | Отвечает 400. | [Отправка сообщения, которое может не дойти](#отправка-сообщения-которое-может-не-дойти) |
+| Ищете слово, которое есть в Random | Random отвечает через 2,5 с. | [Поиск, где одна комната медленная](#поиск-где-одна-комната-медленная) |
+| Ждёте | Новое сообщение появляется каждые 4 с. | [Опрос новых сообщений](#опрос-новых-сообщений) |
+
+Пока вы это делаете, откройте панель Network в браузере. Запрос, который страница прерывает, показывается там как отменённый, а backend печатает для него `aborted: ...`.
+
+## Как разделены файлы
+
+Код разложен по слоям, и файл импортирует только из слоёв ниже себя. Компоненты только отправляют события и читают значения; backend они никогда не вызывают.
+
+| Путь | Слой | Задача |
+| ---- | ---- | ------ |
+| `src/shared/bus.ts` | shared | Создаёт шину. Не импортирует ни события, ни сущности, ни фичи. |
+| `src/shared/api.ts` | shared | Клиент backend: по одной функции на запрос. |
+| `src/entities/room/` | сущность | Список комнат и выбранная комната. |
+| `src/entities/message/` | сущность | История открытой комнаты, отправка сообщения и приходящее сообщение. |
+| `src/features/show-history/` | фича | Выбранная комната загружает свою историю. |
+| `src/features/search-messages/` | фича | Поиск по всем комнатам и открытие результата. |
+| `src/features/receive-messages/` | фича | Новые сообщения, запрашиваемые с интервалом. |
+| `src/ui/`, `src/app.ts` | верх | Компоненты и файл, который подключает модули. |
+| `server/` | | Backend на Fastify и скрипт, запускающий его вместе с Vite. |
+
+**Правило.** Сущность — вещь со своим state и командами (комната, сообщение). Она импортирует `shared` и больше ничего. Фича — сценарий, который связывает вещи: она импортирует `shared` и сущности и никогда другую фичу. Верх импортирует всё, что ниже. Никакие две сущности не импортируют друг друга, и никакие две фичи не импортируют друг друга, а тест в репозитории (`src/tests/architecture.test.ts`) падает, когда это случается.
+
+Именно из-за этого правила существует `show-history`. Выбор комнаты должен загружать её историю, но `room` не знает `message`, а `message` не знает `room`. Фича `show-history` — единственное место, которое знает обоих: она слушает `rooms/selected` и запускает job `messages/loadHistory`. То же для приходящего сообщения: `receive-messages` отправляет `incoming/received` — событие, которым владеет и которое слушает сущность `message`.
+
+В папке лежат её события (`room.ts`, не импортирующий шину), её работа (`room-handlers.ts`), state, которое она хранит (`room-store.ts`), и модуль (`room-module.ts`), который всё это связывает. Другой слой обращается к сущности через её actions, никогда через её обработчики или store. Все actions лежат в файле событий. Action без обработчика говорит, что что-то произошло, и любая фича может его слушать: `rooms/selected` слышат две. Action с обработчиком — это команда ровно с одним обработчиком, как `search/openResult` и `messages/mark`. Обработчик передаётся в `createAction`, поэтому action работает везде, где его вызывают, и может вернуть результат, а модуль привязывает его через `module.use` на всё время, пока он подключён. Job — тот же action с обработчиком, который ещё и отправляет свои исходы, но его обработчик привязывается в модуле (`module.handle`): job обычно работает под политикой, а тип его исходов точен, только когда обработчик не входит в тип.
+
+Слои взяты из [Feature-Sliced Design](https://feature-sliced.design/), сокращённого до трёх, которых хватает приложению такого размера.
+
+## Загрузка истории без гонки
+
+**Проблема.** Читатель кликает по медленной комнате, а потом по быстрой. Если медленный ответ приходит последним, он показывает не ту комнату, а рукописный флаг загрузки остаётся `true`, когда запрос прерывается.
+
+**Когда.** Загрузка стартует от выбора пользователя, который может измениться до её окончания.
+
+Job отправляет `pending`, когда стартует его обработчик, и ровно одно из `success`, `fail` и `cancel`, когда он заканчивается. `latest` вокруг обработчика прерывает старую загрузку, когда начинается новая, поэтому доставляется только новый результат, а старая отправляет `cancel`:
+
+```js
+// message.js
+import { createJob } from "nanoeffects/actions";
+
+// createJob — action с обработчиком, который ещё и отправляет pending, success, fail и cancel
+export const loadHistory = createJob("messages/loadHistory");
+```
+
+```js
+// message-handlers.js
+import { latest } from "nanoeffects/policies";
+
+// latest — загрузка для новой комнаты прерывает старую, и её результат никогда не доставляется
+export const fetchHistory = latest((roomId, { signal }) => api.loadHistory(roomId, { signal }));
+```
+
+Модуль даёт job работу и ведёт state по исходам, так что прерванная загрузка тоже сбрасывает флаг (см. [State работы job](actions.md#state-работы-job)):
+
+```js
+// message-module.js
+import { createModule } from "nanoeffects/actions";
+import { loadHistory } from "./message";
+import { fetchHistory } from "./message-handlers";
+
+export const messageModule = createModule("message", (module) => {
+  // handle — пока модуль подключён, он выполняет работу loadHistory
+  module.handle(loadHistory, fetchHistory);
+  module.on(loadHistory.pending, () => console.log("show the spinner"));
+  module.on(loadHistory.cancel, () => console.log("a newer load replaced it"));
+});
+```
+
+## Отправка сообщения, которое может не дойти
+
+**Проблема.** Сообщение должно появиться сразу, уйти в порядке отправки, быть повторено после сбоя и показаться неудавшимся, если так и не дошло. Исход `fail` содержит только ошибку, а не вызов, поэтому страница не может определить, какое сообщение упало.
+
+**Когда.** У action есть видимый результат, который может не получиться и должен сохранять порядок.
+
+`queue` сохраняет порядок, `retry` повторяет упавший вызов, а обработчик выбрасывает ошибку с идентификатором сообщения:
+
+```js
+import { retry } from "nanoeffects/effects";
+import { queue } from "nanoeffects/policies";
+
+class SendFailed extends Error {
+  constructor(localId, cause) {
+    super(cause.message);
+    this.localId = localId;
+  }
+}
+
+// 400 — это ответ: повторный запрос даст тот же ответ. 503 или потерянное соединение могут пройти.
+const isWorthRetrying = (error) => !(error.status < 500);
+
+// retry — повторить упавшую отправку, до 3 попыток с паузой 200 мс, если ответ не был «нет»
+const attempt = retry(
+  async (call, { signal }) => {
+    const message = await api.send(call.roomId, call.text, { signal });
+    return { localId: call.localId, message };
+  },
+  { times: 3, delay: 200, shouldRetry: isWorthRetrying },
+);
+
+// queue — сообщения уходят одно за другим, в порядке отправки
+export const deliver = queue(async (call, ctx) => {
+  try {
+    return await attempt(call, ctx);
+  } catch (error) {
+    throw new SendFailed(call.localId, error);
+  }
+});
+```
+
+Модуль добавляет сообщение на `pending`, отмечает его доставленным на `success` и отмечает сообщение, названное в ошибке, как неудавшееся на `fail`. Отправьте `/fail hello`, чтобы увидеть сбой, который не повторяется, и отправьте несколько сообщений, чтобы встретить 503, который повторяется.
+
+## Поиск, где одна комната медленная
+
+**Проблема.** Поиск опрашивает каждую комнату. Если он ждёт все, а одна комната медленная или сломана, читатель не видит ничего. Если он падает на первой ошибке, комнаты, которые ответили, теряются.
+
+**Когда.** Один action рассылает запросы в несколько источников, и частичный ответ лучше, чем никакого.
+
+`timeout` ограничивает каждый запрос, а `allSettled` ждёт окончания каждого запроса, удался он или нет. Обработчик хранит найденное и имена комнат, которые не ответили:
+
+```js
+import { allSettled, timeout } from "nanoeffects/effects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const rooms = [{ id: "general", name: "General" }, { id: "random", name: "Random" }];
+
+const searchRoom = (room, query) => ({ signal }) => api.searchRoom(room.id, query, { signal });
+
+// timeout — комната, не ответившая за 1,5 с, падает с ошибкой таймаута
+const askRoom = (room, query) => {
+  const request = searchRoom(room, query);
+  return (parent) => timeout(parent, 1500, request);
+};
+
+// debounce — дождаться тишины; latest — новый запрос прерывает старый поиск
+export const runSearch = debounce(
+  300,
+  latest(async (query, ctx) => {
+    // allSettled — спросить все комнаты сразу и дождаться каждой, как бы она ни закончила
+    const outcomes = await allSettled(ctx, rooms.map((room) => askRoom(room, query)));
+    return outcomes.map((outcome, index) => ({ room: rooms[index], outcome }));
+  }),
+);
+```
+
+`all` провалил бы весь поиск на первой медленной комнате, а здесь это неверное поведение. Про остальные эффекты см. [Эффекты](effects.md).
+
+## Ожидание комнаты перед отметкой результата
+
+**Проблема.** Читатель открывает результат поиска из другой комнаты. Сообщение нельзя отметить, пока не загрузилась история той комнаты, а обработчик не должен гадать, сколько это займёт.
+
+**Когда.** Фича запускает работу в сущности и должна продолжить после её исхода.
+
+`take` ждёт следующее событие с таким именем. Запускайте его до `emit`, который вызывает событие, чтобы ничего не пропустить:
+
+```js
+import { createAction } from "nanoeffects/actions";
+import { take } from "nanoeffects/effects";
+
+// createAction с обработчиком — команда для сущности message, с обработчиком, который её выполняет
+const markMessage = createAction("messages/mark", (messageId) => console.log("mark", messageId));
+
+// открытая комната, запоминается из события rooms/selected
+let selectedRoom = "general";
+
+export const goToResult = async (hit, ctx) => {
+  if (hit.roomId !== selectedRoom) {
+    // take — ждать следующее событие с таким именем; запускается до emit, чтобы ничего не пропустить
+    const loaded = take(ctx, "messages/loadHistory/success");
+    ctx.emit("rooms/selected", hit.roomId);
+    await loaded;
+  }
+  // ctx.emit с action, у которого есть обработчик — сущность message отмечает сообщение
+  ctx.emit(markMessage(hit.id));
+};
+```
+
+## Опрос новых сообщений
+
+**Проблема.** Новые сообщения приходят с backend, и страница должна запрашивать их с интервалом. Опрос должен прекращаться, когда фича выключена, а один упавший запрос не должен его останавливать.
+
+**Когда.** У фичи есть фоновая работа, которая живёт столько же, сколько сама фича.
+
+`poll` вызывает функцию время от времени с интервалом и заканчивается, когда её контекст прерывается. Модуль запускает задачу через `spawn`, а отключение модуля её прерывает:
+
+```js
+import { createModule } from "nanoeffects/actions";
+import { poll } from "nanoeffects/effects";
+
+const watchUpdates = async (_, ctx) => {
+  // номер последнего увиденного обновления; первый ответ лишь сообщает, где backend
+  let since;
+
+  const check = async () => {
+    try {
+      const updates = await api.loadUpdates(since, { signal: ctx.signal });
+      since = updates.seq;
+      for (const message of updates.messages) {
+        // ctx.emit — после прерывания ничего не доставляет
+        ctx.emit("incoming/received", message);
+      }
+    } catch {
+      // один упавший запрос не должен заканчивать опрос: следующий тик спросит снова
+    }
+  };
+
+  // poll — вызвать `check` сейчас и затем каждые 3 с; прерывание ctx (отключённый модуль) его заканчивает
+  await poll(ctx, check, 3000, { leading: true });
+};
+
+export const receiveMessagesModule = createModule("receive-messages", (module) => {
+  // spawn — фоновая задача, живущая столько же, сколько этот модуль
+  module.spawn(watchUpdates);
+});
+```
+
+В примере кнопка вызывает `app.unmount(receiveMessagesModule)` и `app.mount(receiveMessagesModule)`, так что вы можете увидеть, как опрос останавливается (панель Network больше не показывает запросов `updates`) и запускается.
+
+## Где живёт каждое значение
+
+Каждая сущность и каждая фича, у которых есть state, держат его в store [Zustand](https://zustand.docs.pmnd.rs/), который пишет модуль, а компонент читает через `useStore`. Каждый store перечисляет свои мутации, например `startLoading(roomId)` и `markFailed(localId)`, а модуль вызывает их с данными события: `module.on(loadHistory.pending, startLoading)`. Мутация, которая задаёт простые значения, передаёт `set` объект, как в `set({ searching: true })`. Store сущности message использует middleware `immer`, поэтому мутация, меняющая список, может менять его на месте, как в `state.messages.push(message)`, а store всё равно отдаёт React новый объект. Других записей state нет. Исключение — список комнат: он читается через один `useEventState` в провайдере в корне. `useEventState` — не store: событие, пришедшее до монтирования провайдера, теряется, а второй компонент получает свою копию. См. [Последнее значение события как state](react.md#последнее-значение-события-как-state).

package/docs/ru/chat-widget.md

@@ -0,0 +1,131 @@
+# Виджет чата, который слушает только пока открыт
+
+> **[Уровень D](README.md#виды-проектов)**: доменная логика вне UI. Сначала прочитайте: [Руководство](guide.md#1-создание-шины-событий).
+
+Чат с ботом за кнопкой-лаунчером, где закрытый чат ничего не стоит. «Закрыт» значит: нет подписок на шине, опроса, обработчика клавиатуры и запроса в полёте. Открытие включает всё это, закрытие выключает одним вызовом.
+
+Код лежит в [`examples/chat-widget`](../../examples/chat-widget): обычный DOM и TypeScript, поддельный бот в браузере, без backend. Запустите его на [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat-widget) или на своей машине:
+
+```bash
+cd examples/chat-widget
+npm install
+npm run dev
+```
+
+Это пример уровня D: логика живёт в одном модуле, а страница его только подключает и отключает. Для приложения с несколькими фичами см. [Чат с сущностями, фичами, модулями и небольшим backend](chat-example.md).
+
+## Что происходит при открытии и закрытии
+
+| Момент | Что происходит |
+| ------ | -------------- |
+| Открытие | Модуль подключается: подписывается обработчик бота, опрашиваются сообщения оператора, добавляется обработчик `Escape`. Панель рисуется и слушает шину. |
+| Пользователь отправляет текст | Тексты уходят боту по одному, в порядке отправки, с ограничением по времени и повтором. |
+| `Escape` | Модуль отправляет `chat/closeRequested`; лаунчер закрывает чат. |
+| Закрытие | Панель удаляется и отписывается, модуль отключается. Запрос в полёте прерывается, опрос останавливается, обработчик `Escape` исчезает. |
+
+## Файлы
+
+| Файл | Задача |
+| ---- | ------ |
+| `src/bus.ts` | Шина и `modulePlugin()` без модуля: лаунчер подключает модуль сам. |
+| `src/chat.ts` | Только события: `messageSent`, `messageAdded`, `typingChanged`, `closeRequested`. |
+| `src/chat-handlers.ts` | `askBot` (внутри `timeout` и `retry`) и `watchOperator` (`poll`): обычные `async`-функции, которые ничего не знают о странице. |
+| `src/chat-module.ts` | Список того, что живо, пока чат открыт. |
+| `src/panel.ts` | Вид: показывает строки, отправляет тексты, возвращает одну функцию, которая его удаляет. |
+| `src/main.ts` | Лаунчер: единственный файл, знающий и модуль, и панель; он слушает `closeRequested`, только пока чат открыт. |
+
+## Модуль виджета
+
+Модуль — список того, что живо, пока чат открыт. При отключении шина отменяет каждую его строку.
+
+<!-- docs-check: skip - остальные файлы примера лежат в examples/chat-widget -->
+```js
+// chat-module.js
+import { createModule } from "nanoeffects/actions";
+import { queue } from "nanoeffects/policies";
+import { closeRequested, messageSent } from "./chat";
+import { askBot, watchOperator } from "./chat-handlers";
+
+// задача, которая остаётся в ожидании, пока модуль не отключится; тогда её сигнал прерывается
+const untilAborted = (ctx) =>
+  new Promise((resolve) => {
+    ctx.signal.addEventListener("abort", resolve, { once: true });
+  });
+
+// DOM-обработчик, живущий столько же, сколько модуль: `signal` снимает его при прерывании
+const listenToEscape = async (_, ctx) => {
+  const onKey = (event) => {
+    if (event.key === "Escape") {
+      ctx.emit(closeRequested());
+    }
+  };
+  document.addEventListener("keydown", onKey, { signal: ctx.signal });
+  await untilAborted(ctx);
+};
+
+export const chatModule = createModule("chat", (module) => {
+  // module.run — запускает askBot как дочернюю задачу модуля, так что отключение её прерывает
+  const answer = (text) => module.run(askBot, text);
+  // on + queue — отвечать на тексты один за другим, в порядке отправки
+  module.on(messageSent, queue(answer));
+  // spawn — фоновая задача, живущая столько же, сколько модуль
+  module.spawn(watchOperator);
+  module.spawn(listenToEscape);
+});
+```
+
+Три детали, которые делают очистку полной:
+
+- **`module.run`, а не `askBot` напрямую.** Обработчик из `module.on` запускается как дочерняя задача той, что отправила событие (здесь панели). Отключение прекращает слушать, но не прерывает уже идущий запрос. `module.run` делает запрос дочерним для модуля.
+- **`queue`, а не `latest`.** `queue` сохраняет порядок, когда пользователь быстро отправляет два текста. [`latest`](policies.md) прервал бы первый ответ, что для разговора неверно.
+- **DOM-обработчик с `signal`.** `addEventListener` принимает параметр `signal` и отписывает обработчик при прерывании. До этого задача остаётся в ожидании: завершённая задача повторно не прерывается.
+
+## Открытие и закрытие из лаунчера
+
+`app.mount` возвращает функцию, которая отключает модуль, `bus.on` — функцию отписки. Лаунчер объединяет их и функцию, удаляющую панель, в один `close`.
+
+<!-- docs-check: skip - остальные файлы примера лежат в examples/chat-widget -->
+```js
+// main.js
+import { app, bus } from "./bus";
+import { closeRequested } from "./chat";
+import { chatModule } from "./chat-module";
+import { renderPanel } from "./panel";
+
+const button = document.querySelector("#chat-launcher");
+let close = null; // задано, пока чат открыт
+
+const open = () => {
+  const stopModule = app.mount(chatModule); // стартуют подписки, опрос и Escape
+  const stopPanel = renderPanel(document.body);
+  // модуль отправляет closeRequested по Escape; пока чат закрыт, этого не делает никто
+  const stopEscape = bus.on(closeRequested, () => close?.());
+  close = () => {
+    stopEscape();
+    stopPanel();
+    stopModule(); // всё, что запустил модуль, заканчивается, запрос в полёте тоже
+    close = null;
+  };
+};
+
+button.addEventListener("click", () => {
+  if (close) {
+    close();
+  } else {
+    open();
+  }
+});
+```
+
+Пока чат закрыт, у лаунчера нет подписок на шине. Остаётся только DOM-обработчик клика по кнопке.
+
+## Проверка очистки
+
+1. Откройте чат и отправьте текст. Бот отвечает примерно через секунду. Каждый третий вопрос падает, и повтор спрашивает снова.
+2. Отправьте текст и закройте чат до прихода ответа. Строка не появится, в том числе когда вы снова откроете чат.
+3. Посмотрите на блок «Listeners on the bus»: он показывает `bus.get(event).length` для четырёх событий и обновляется, когда чат открывается или закрывается. Закрыт: у каждого события `0`, и у «all events» тоже. Открыт: у каждого из четырёх по одной подписке, а «all events» — `4`. Так видно, что ничего не осталось подписанным.
+4. Подождите 10 с при закрытом чате. Оператор не опрашивается: строка от оператора не появляется.
+5. Нажмите `Escape` при закрытом чате. Ничего не происходит. Откройте чат и нажмите снова: он закрывается.
+6. Снова откройте чат. Старые строки вернулись, и опрос работает.
+
+`src/tests/chat-widget-example.test.ts` проверяет те же пункты без браузера.