nanoeffects 0.29.0 → 0.30.1

package/docs/ru/server.md

@@ -0,0 +1,204 @@
+# Остановка работы на backend, когда клиент ушёл
+
+> **[Уровень C](README.md#виды-проектов)**: сложная бизнес-логика. Сначала прочитайте: [Руководство](guide.md#1-создание-шины-событий).
+
+Работа backend на Node.js (в примерах [Fastify](https://fastify.dev)) для запроса, сокета или задачи из очереди должна прекращаться, когда она никому не нужна. Один приём в трёх местах: запрос, WebSocket и воркер.
+
+Нужны Node 18 или новее, `fastify` и `nanoeffects`. `api` ниже — ваш клиент другого сервиса: замените его своими запросами.
+
+## Зачем это backend
+
+Закрытая вкладка браузера останавливает свои запросы. Backend так не умеет: когда клиент ушёл, запросы, которые backend сделал для него, и их повторы продолжаются. На загруженном backend это лишняя работа и замедление для остальных клиентов.
+
+Решение: один `AbortController` на каждую единицу работы клиента и одно правило — **когда клиент уходит, прервите контроллер.** `signalPlugin` позволяет `bus.emit` принять этот сигнал, и `timeout`, `retry` и сам запрос останавливаются.
+
+| Единица работы | Создаётся, когда | Прерывается, когда |
+| -------------- | ---------------- | ------------------ |
+| HTTP-запрос | стартует маршрут | соединение закрылось до ответа |
+| WebSocket | сокет подключился | сокет закрылся |
+| Задача из очереди | задача принята | backend выключается |
+
+## Шина и action
+
+Шина и action лежат в файлах, которые ничего не знают о HTTP, так что тот же action может выполняться в маршруте, тесте или воркере.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// createBus — шина, общая для backend
+// signalPlugin — позволяет emit принимать { signal }, чтобы закрытое соединение могло прервать работу
+export const bus = createBus().use(signalPlugin());
+```
+
+Action загружает пользователя: до трёх попыток, каждая прерывается через пять секунд. `ctx.signal` — сигнал задачи: он прерывается, когда прерывается контроллер запроса.
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+import { retry, timeout } from "nanoeffects/effects";
+
+// createAction — action с обработчиком: emit возвращает то, что вернул обработчик
+export const getUser = createAction("user/get", async (id, ctx) => {
+  // одна попытка: запрос с сигналом timeout, чтобы тот мог его остановить
+  const load = ({ signal }) => api.getUser(id, { signal });
+  // timeout — провалить попытку через 5 с
+  const attempt = () => timeout(ctx, 5000, load);
+  // retry — до 3 попыток с паузой 500 мс
+  return retry(ctx, attempt, { times: 3, delay: 500 });
+});
+```
+
+## Остановка работы запроса
+
+<!-- docs-check: continue -->
+
+Создайте контроллер при старте маршрута. Слушайте `close` у **ответа** (`reply.raw`): он наступает, когда соединение заканчивается. `request.raw` тоже отправляет `close`, но когда тело запроса прочитано, а не когда клиент ушёл, поэтому он не подходит.
+
+```js
+// server.js
+import Fastify from "fastify";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export const app = Fastify();
+
+// контроллеры запросов, на которые ещё отвечают, для остановки backend ниже
+export const inFlight = new Set();
+
+app.get("/users/:id", async (request, reply) => {
+  const controller = new AbortController();
+  inFlight.add(controller);
+
+  // close у ответа — соединение закончилось; если ответ не был завершён, клиент ушёл
+  reply.raw.on("close", () => {
+    inFlight.delete(controller);
+    if (!reply.raw.writableFinished) {
+      controller.abort();
+    }
+  });
+
+  try {
+    // emit с { signal } — прерывание контроллера прерывает action: timeout, retry и сам запрос
+    const call = getUser(request.params.id);
+    return await bus.emit(call, { signal: controller.signal });
+  } catch (error) {
+    // отвечать некому, когда клиент закрыл соединение
+    if (reply.raw.destroyed) {
+      return reply;
+    }
+    return reply.code(502).send({ error: String(error) });
+  }
+});
+```
+
+После прерывания action отклоняется с причиной прерывания. Блок `catch` выше игнорирует её, когда соединения уже нет, потому что отвечать некому.
+
+## Остановка backend
+
+<!-- docs-check: continue -->
+
+Храните контроллеры запросов в полёте в множестве. По SIGTERM (его посылает контейнер) или SIGINT (Ctrl+C) прервите их все и закройте приложение. Прерванный запрос отвечает ошибкой, а `app.close()` ждёт окончания соединений.
+
+```js
+// shutdown.js
+import { app, inFlight } from "./server";
+
+// SIGTERM посылает контейнер, SIGINT — это Ctrl+C
+for (const name of ["SIGTERM", "SIGINT"]) {
+  process.on(name, async () => {
+    for (const controller of inFlight) {
+      controller.abort();
+    }
+    await app.close();
+    process.exit(0);
+  });
+}
+```
+
+Маршрут выше наполняет `inFlight` и очищает его в обработчике `close`. [Пример api-server](../../examples/api-server) делает то же самое, с лимитом в две секунды на закрытие.
+
+## Привязка WebSocket к его работе
+
+<!-- docs-check: continue -->
+
+Сокет живёт минуты, и в нём работает несколько задач (подписка, heartbeat), поэтому контроллер принадлежит сокету, а каждый его `emit` получает тот же сигнал. Закрытие сокета останавливает все задачи.
+
+Сначала action. Оно отправляет цену сразу, а затем каждую секунду, пока его задача не будет прервана.
+
+```js
+// prices.js
+import { createAction } from "nanoeffects/actions";
+import { poll } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+// createAction — action с обработчиком
+// latest — новая подписка останавливает старую; key — но только старую того же сокета
+export const watchPrices = createAction(
+  "prices/watch",
+  latest(
+    async (call, ctx) => {
+      // poll — вызывать функцию сразу и каждую секунду, пока задача не будет прервана
+      await poll(ctx, () => call.send(`${call.symbol}: ${Math.random()}`), 1000, {
+        leading: true,
+      });
+    },
+    { key: (call) => call.socketId },
+  ),
+);
+```
+
+Без `key` одна политика обслуживает весь action, и новая подписка на одном сокете остановила бы подписку на другом.
+
+Затем маршрут. Каждый сокет получает идентификатор и контроллер.
+
+```js
+// sockets.js
+import websocket from "@fastify/websocket";
+import Fastify from "fastify";
+import { bus } from "./bus";
+import { watchPrices } from "./prices";
+
+const sockets = Fastify();
+sockets.register(websocket);
+
+let lastSocketId = 0;
+
+sockets.register(async (instance) => {
+  instance.get("/prices", { websocket: true }, (socket) => {
+    lastSocketId += 1;
+    const socketId = lastSocketId;
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    // close — клиент ушёл: остановить всё, что запущено для этого сокета
+    socket.on("close", () => controller.abort());
+
+    socket.on("message", (data) => {
+      const send = (text) => socket.send(text);
+      const call = watchPrices({ socketId, symbol: String(data), send });
+      // emit с { signal } — вызов останавливается, когда сокет закрывается
+      bus.emit(call, { signal });
+    });
+  });
+});
+```
+
+[Пример ws-server](../../examples/ws-server) добавляет закрытие молчащего сокета, собранное из `race`, `take` и `delay`.
+
+## Воркер очереди
+
+Воркер принимает задачи от клиента, сразу отвечает и продолжает работу в фоне. `createJob` с `queue` ограничивает число одновременных задач, `retry` и `timeout` позволяют сдаваться, а исходы задачи (`pending`, `success`, `fail`, `cancel`) помогают их считать. Передавайте каждому `emit` задачи один и тот же сигнал: его прерывание при остановке отменит оставшиеся задачи.
+
+Важная деталь: вызов, который ещё ждёт в очереди, когда сигнал прерывается, не стартует, и задача не отправляет для него исхода. Если итоги должны сходиться, считайте такие вызовы сами.
+
+В [примере job-worker](../../examples/job-worker) есть всё: счётчики, `GET /stats` и остановка в три шага (перестать принимать задачи, подождать, прервать остальные).
+
+## Примеры
+
+| Папка | Что показывает |
+| ----- | -------------- |
+| [`api-server`](../../examples/api-server) | Backend на Fastify поверх PokeAPI: `timeout`, `retry`, `allSettled` и прерывание, когда клиент ушёл |
+| [`ws-server`](../../examples/ws-server) | Backend с WebSocket: по контроллеру на сокет, `latest` с `key`, закрытие простаивающего |
+| [`job-worker`](../../examples/job-worker) | Воркер очереди: `queue`, `retry`, `timeout`, счётчики по исходам, остановка в три шага |

package/docs/ru/starter.md

@@ -0,0 +1,118 @@
+# Проект из шаблона
+
+> **[Уровень A](README.md#виды-проектов)**: небольшое приложение, виджет или MVP.
+
+Одна команда создаёт работающий проект, и Vite с шиной подключать вручную не нужно. Проект — небольшое приложение с полем поиска. Оно ждёт, пока вы перестанете печатать (`debounce`), и прерывает старый запрос при новом (`latest`).
+
+Нужен Node 18 или новее.
+
+## Создание проекта
+
+Замените `my-app` на имя новой папки.
+
+```bash
+npm create nanoeffects@latest my-app
+```
+
+```bash
+pnpm create nanoeffects my-app
+```
+
+```bash
+yarn create nanoeffects my-app
+```
+
+```bash
+bun create nanoeffects my-app
+```
+
+Если шаблон не указан, команда спросит его. Папка должна быть новой или пустой, иначе команда остановится и не перезапишет файлы.
+
+Затем выполните шаги, которые напечатала команда:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Откройте адрес, который напечатает Vite, и наберите что-нибудь в поле. Поддельный backend отвечает 800 мс, поэтому видно, как прерывается старый запрос.
+
+## Выбор шаблона
+
+Передайте `--template`, чтобы пропустить вопрос. С npm перед параметром ставьте `--`.
+
+| Шаблон | Что показывает | Когда брать |
+| ------ | -------------- | ----------- |
+| `vanilla` | Шина, одно событие и обработчик с `debounce` и `latest`, обычный DOM-код | Вы без фреймворка или хотите увидеть одну шину |
+| `react` | Тот же обработчик с `useEmitter` и `useEventState`, а также `usePolicy` для сохранения с debounce в компоненте | Вы пишете приложение на React |
+| `vanilla-ts` | Приложение `vanilla` на TypeScript | Хотите, чтобы компилятор проверял события и обработчики |
+| `react-ts` | Приложение `react` на TypeScript | Вы пишете приложение на React с TypeScript |
+| `domains-ts` | Actions с обработчиками, job и модули; логика разложена по доменным папкам, а React — тонкий слой | В приложении больше одной фичи, и логику нужно вынести из UI |
+| `vue-ts` | Приложение `react-ts` на Vue 3, с `watchEmitter` и `useEventRef` из `nanoeffects/vue` | Вы пишете приложение на Vue 3 |
+| `svelte-ts` | Приложение `react-ts` на Svelte 5, с `eventStore` из `nanoeffects/svelte` | Вы пишете приложение на Svelte |
+
+```bash
+npm create nanoeffects@latest my-app -- --template react
+```
+
+В шаблонах `react` `useEventState` хранит найденные элементы в компоненте. Это не глобальный store: другой компонент получит свою копию. Чтобы делить значение между компонентами, возьмите state manager: [State managers](stores.md).
+
+TypeScript-шаблоны — те же приложения с теми же файлами в `.ts` и `.tsx`. События создаёт `createAction<Payload>`, поэтому обработчики и `useEventState` берут типы из событий, и аннотации в компоненте не нужны. Перед сборкой `npm run build` проверяет типы (`tsc --noEmit`).
+
+```bash
+npm create nanoeffects@latest my-app -- --template react-ts
+```
+
+### Начало с Vue
+
+`vue-ts` — приложение поиска из `react-ts` на Vue 3 с `<script setup lang="ts">`. Шина использует `vuePlugin` из `nanoeffects/vue`: `watchEmitter` отправляет запрос в шину при его изменении, а `useEventRef` хранит результат поиска в `ref`. Как и `useEventState` в React, `useEventRef` — [не store](vue.md#это-не-store). Значение, общее для нескольких компонентов, храните в store, например в Pinia.
+
+```bash
+npm create nanoeffects@latest my-app -- --template vue-ts
+```
+
+`npm run build` проверяет типы файлов `.vue` через `vue-tsc`. Ему нужен TypeScript 5, поэтому шаблон от него зависит.
+
+### Начало со Svelte
+
+`svelte-ts` — приложение поиска из `react-ts` на Svelte 5. Шина использует `sveltePlugin` из `nanoeffects/svelte`: `eventStore` превращает событие в store Svelte. В компоненте `$found` читает его, а Svelte сам подписывается и отписывается. Запрос уходит в шину из обработчика `oninput`, поэтому при монтировании компонента ничего не отправляется. Store слушает, только пока его что-то читает, и [не является store приложения](svelte.md#это-не-store-приложения). Значение, общее для нескольких компонентов, храните в своём store.
+
+```bash
+npm create nanoeffects@latest my-app -- --template svelte-ts
+```
+
+`npm run build` проверяет типы файлов `.svelte` через `svelte-check`. Ему нужен TypeScript 5, поэтому шаблон от него зависит.
+
+### Начало с доменами
+
+`domains-ts` — не то же поле поиска на TypeScript. Он показывает, где живёт логика, когда в приложении несколько фич. Каждый домен — папка в `src/domains/`: события домена, их обработка и модуль, который её подключает. React-компоненты только отправляют события и читают значения.
+
+```bash
+npm create nanoeffects@latest my-app -- --template domains-ts
+```
+
+| Путь | Задача |
+| ---- | ------ |
+| `src/bus.ts` | Создаёт шину. Не импортирует ни события, ни домены. |
+| `src/app.ts` | Подключает домены через `modulePlugin`. |
+| `src/domains/catalog/` | Поиск товаров: `catalog.ts` (события и action с обработчиком), `catalog-handlers.ts` (`debounce` и `latest`), `catalog-module.ts`. |
+| `src/domains/checkout/` | Оформление заказа: `checkout.ts` (job), `checkout-handlers.ts` (`leading` и `retry`), `checkout-store.ts` (state, записываемое из исходов задачи), `checkout-module.ts`. |
+| `src/ui/` | Компоненты. Ни один из них не вызывает поддельный backend из `src/api.ts`. |
+
+Пример побольше — чат, где части реагируют друг на друга, — в [Чат с сущностями, фичами, модулями и небольшим backend](chat-example.md). Слоёв там больше, чем в `domains-ts`. Когда домены должны реагировать друг на друга, чат делит их на сущности и фичи, и домены не импортируют друг друга.
+
+Actions, jobs и модули объясняет страница [Actions, jobs и модули](actions.md). Шаблон хранит найденные товары в провайдере Context с одним `useEventState`, а state заказа — в отдельном store, потому что `useEventState` — [не store](react.md#последнее-значение-события-как-state).
+
+## Файлы
+
+Каждый шаблон, кроме `domains-ts`, делит код как [Руководство](guide.md): один файл — одна задача. В TypeScript-шаблонах файлы имеют расширение `.ts` (`.tsx` у компонентов React, `.vue` у Vue, `.svelte` у Svelte).
+
+| Файл | Задача |
+| ---- | ------ |
+| `src/bus.js` | Создаёт шину. Не импортирует события. |
+| `src/search.js` | Называет события через `createAction`. Не импортирует шину. |
+| `src/search-handlers.js` | Обрабатывает события через `debounce` и `latest`. Знает и шину, и события. |
+| `src/api.js` | Поддельный backend. Замените его своими запросами. |
+
+Каждый вызов nanoeffects в этих файлах снабжён комментарием. Чтобы адаптировать проект, замените `src/api.js`, затем переименуйте события и обработчик.