@fozy-labs/rx-toolkit 0.5.3-rc.1 → 0.5.3

package/docs/CONTRIBUTING.md

@@ -0,0 +1,230 @@
+# Contributing
+
+Руководство для контрибьюторов проекта **@fozy-labs/rx-toolkit**.
+
+## Содержание
+
+- [Contributing](#contributing)
+  - [Содержание](#содержание)
+  - [Быстрый старт](#быстрый-старт)
+  - [Структура проекта](#структура-проекта)
+  - [Разработка](#разработка)
+    - [Исходный код (`src/`)](#исходный-код-src)
+    - [Интерактивные примеры (`apps/demos/`)](#интерактивные-примеры-appsdemos)
+    - [Документация (`docs/`)](#документация-docs)
+  - [Тесты](#тесты)
+  - [Инструменты разработки](#инструменты-разработки)
+  - [Соглашения](#соглашения)
+    - [Именование файлов](#именование-файлов)
+    - [Протокол сигналов](#протокол-сигналов)
+    - [Код и документация](#код-и-документация)
+    - [Коммиты](#коммиты)
+    - [CHANGELOG](#changelog)
+    - [index.ts](#indexts)
+  - [AI-assisted разработка](#ai-assisted-разработка)
+  - [Релиз](#релиз)
+
+
+## Быстрый старт
+
+```bash
+# Клонирование
+git clone https://github.com/fozy-labs/rx-toolkit.git
+cd rx-toolkit
+
+# Установка зависимостей
+npm install
+
+# Проверка типов
+npm run ts-check
+
+# Запуск тестов
+npm run test
+
+# Сборка
+npm run build
+```
+
+
+## Структура проекта
+
+```
+rx-toolkit/
+├── .github/              # AI-промпты, инструкции, скиллы
+├── src/                  # Исходный код библиотеки
+│   ├── signals/          # Реактивные примитивы (Signal, Computed, Effect)
+│   ├── query/            # Кеш-менеджер (Resource, Command)
+│   └── common/           # Утилиты, devtools, React-хуки
+├── apps/
+│   └── demos/            # Интерактивные примеры (React + Vite + MDX)
+├── docs/                 # Документация
+└── dist/                 # Результат сборки (не коммитится)
+```
+
+
+## Разработка
+
+### Исходный код (`src/`)
+
+Библиотека состоит из трёх "модулей":
+
+| Модуль | Путь | Описание                                                            |
+|--------|------|---------------------------------------------------------------------|
+| **Signals** | `src/signals/` | Реактивные примитивы: `State`, `Computed`, `Effect`, операторы и тд |
+| **Query** | `src/query/` | Кеш-менеджер: `Resource`, `Command`, агенты, `SKIP_TOKEN` и тд      |
+| **Common** | `src/common/` | Общие утилиты, интеграция с DevTools, React-хуки и тд                 |
+
+> **Алиас путей:** `@/` → `src/`.
+
+
+### Интерактивные примеры (`apps/demos/`)
+
+Демо-приложение на **React 19 + Vite + MDX + Tailwind CSS + HeroUI**.
+Примеры можно запускать и редактировать прямо в браузере благодаря `react-live`.
+
+```bash
+cd apps/demos
+npm install
+npm run dev            # http://localhost:3000
+```
+
+
+**Структура примеров:**
+
+```
+apps/demos/src/
+├── pages/             # MDX-страницы (SignalsPage, QueriesPage, HomePage)
+├── examples/
+│   ├── signals/       # Примеры для сигналов
+│   └── query/         # Примеры для query
+├── components/        # LiveExample, QueryTabs и другие компоненты
+└── utils/             # Утилиты для fetch-запросов
+```
+
+> При изменении кода в `src/` рассмотрите необходимость добавления интерактивного примера в `apps/demos/`.
+
+
+### Документация (`docs/`)
+
+Документация на **русском языке**:
+
+| Файл                   | Содержание                     |
+|------------------------|--------------------------------|
+| `docs/signals/`        | Реактивные примитивы           |
+| `docs/query/`          | Query кеш-менеджер             |
+| `docs/usage/react/`    | React-хуки                     |
+| `docs/devtools/`       | Интеграция с Redux DevTools    |
+| `docs/options/`        | Глобальные настройки           |
+| `docs/migrations/`     | Гайды миграции между версиями  |
+| `docs/contributing/`   | Руководства для контрибьюторов |
+| `docs/CHANGELOG.md`    | История изменений              |
+| `docs/CONTRIBUTING.md` | Руководство для контрибьюторов |
+
+> При изменении кода в `src/` рассмотрите необходимость обновления соответствующей документации в `docs/`.
+
+
+## Тесты
+
+Используется **Vitest** с окружением `jsdom`.
+
+```bash
+npm run test            # Однократный запуск
+npm run test:watch      # Watch-режим
+npm run test:coverage   # Отчёт о покрытии
+npm run test:ui         # Vitest UI в браузере
+```
+
+- Тесты размещаются рядом с кодом: `MyModule.test.ts`
+- Интеграционные — в `src/__tests__/integration/`
+
+
+## Инструменты разработки
+
+### Команды
+
+```bash
+npm run lint           # Проверка линтером (ESLint)
+npm run lint:fix       # Автоисправление ошибок линтера
+npm run format         # Форматирование кода (Prettier)
+npm run format:check   # Проверка форматирования без изменений
+```
+
+> `apps/demos/` имеет отдельную конфигурацию ESLint: `cd apps/demos && npx eslint src/`
+
+### Настройка редактора
+
+Рекомендуемые расширения VS Code:
+- **Prettier** (`esbenp.prettier-vscode`)
+- **ESLint** (`dbaeumer.vscode-eslint`)
+
+Включите `editor.formatOnSave: true` для автоматического форматирования при сохранении.
+
+### Git blame
+
+Файл `.git-blame-ignore-revs` исключает коммиты массового форматирования из `git blame`. GitHub учитывает его автоматически. Для локальной настройки:
+
+```bash
+git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
+
+## Соглашения
+
+### Именование файлов
+
+- Классы/типы — **PascalCase**: `Signal.ts`, `ReadonlySignal.ts`
+- Фабрики/утилиты — **camelCase**: `createResource.ts`, `deepEqual.ts`
+- Типы — суффиксы: `XDefinition`, `XInstance` и тд
+
+
+### Протокол сигналов
+
+```typescript
+signal()       // или signal.get()
+signal.peek()  // получить без подписки
+signal.set(v)  // установить значение
+signal.obs     // RxJS Observable
+```
+
+
+### Код и документация
+
+- Код и комментарии в коде — **на английском**
+- Документация (`docs/`) — **на русском**
+- AI кастомизация (`.github/`) — **на английском**
+
+
+### Коммиты
+
+Используются [Conventional Commits](https://www.conventionalcommits.org/), но со следующими адоптациями:
+- `chore(..)` (вместо `docs(..)`) - при настройке AI окружения (промпты, инструкции, скиллы и тд)
+- `thoughts(..)` (вместо `docs(..)`) - коммиты сгенерированные AI при работе над `.thoughts`
+
+
+### CHANGELOG
+
+Используется формат [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+### index.ts
+
+- `src/index.ts` — единственная точка экспорта публичного API.
+- `<module>/index.ts` — точка экспорта для конкретного "модуля".
+
+
+## AI-assisted разработка
+
+Проект настроен для работы с **GitHub Copilot**.
+
+[//]: # (For humans only guide:)
+Описание подхода: [docs/contributing/ai-assisted-development.md](contributing/ai-assisted-development.md).
+
+
+## Релиз
+
+Релизы делятся на:
+- **RC** — не стабильные релизы
+- **Stable** — стабильные релизы
+
+[//]: # (For humans only guide:)
+Инструкция по выпуску описана тут [docs/contributing/release/README.md](contributing/release/README.md).
+

package/docs/contributing/ai-assisted-development.md

@@ -0,0 +1,47 @@
+
+## AI-assisted разработка
+
+Проект настроен для работы с **GitHub Copilot**. 
+
+Ниже описаны файлы, которые автоматически подключаются к AI-ассистенту.
+
+### Файлы конфигурации
+
+| Файл                              | Назначение                                     |
+|-----------------------------------|------------------------------------------------|
+| `.github/skills/`                 | Скиллы                                         |
+| `.github/instructions/`           | Правила для работы с определенными каталогами. |
+| `.github/prompts/`                | Готовые промпты (комманды)                     |
+| `.github/copilot-instructions.md` | Основные правила проекта. Загружается всегда.  |
+
+### Workflow разработки фичей
+
+Для фич используется поэтапный AI-workflow:
+
+```
+Research → [review] → Design → [review] → Plan → [review] → Implement → [review]
+```
+
+Артефакты каждой фазы сохраняются в:
+
+```
+.thoughts/<date>_<feature-name>/
+├── 01-research/
+├── 02-design/
+├── 03-plan/
+└── 04-implement/
+```
+
+
+### Как начать
+
+1. Для запуска полного workflow фичи — используйте промпт `00-compined.prompt.md`
+2. Для отдельных фаз — соответствующий промпт (`01-research`, `02-design`, и т.д.)
+
+#### 00-compined.prompt.md
+
+- Агент выполнит все этапы в одной петле, время на ревью составит - до 25 минут. 
+- При старте или по завершению ревью - измените статус в `README.md` этавпа на один из:
+  - Review (в процессе)
+  - Approved (принято)
+  - Redraft (есть замечания, нужно доработать) - создайте и опишите замечания в файле `REVEIW.md`

package/docs/contributing/query-v2/README.md

@@ -0,0 +1,379 @@
+
+# Query v2 RFC
+
+Цель Query v2 — создать более чистую, предсказуемую и расширяемую архитектуру для загрузки данных и кеширования.
+
+Для этого мы в экспериментальном виде реализуем "Api" и "ResourceV2".
+
+## Motivation
+
+Есть проблемы, нужно их решить:
+
+1. Сложности работы с внутренним API пакета, и его расширением.
+2. Отсутствие надежной системы очистки кеша - текущая не сбрасывает состояние полностью.
+3. Отсутствие возможности группировки разных API (ресурсов и комманд), для передачи им общих настроек, изоляции и одновременной очистки.
+4. Нет поддержки SSR
+
+## New package API
+
+### createApi
+
+`createApi` - это новая, никак не зависящая от старых реализаций, функция для создания группы ресурсов (в дальнейшем и операций).
+
+| Опция                | Тип                                      | По умолчанию      | Режим         | Описание                                                                                                                                             |
+|----------------------|------------------------------------------|-------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `keyPrefix`          | `string` \| `null` \| `undefined`        | null              |               | Префикс для ключей ресурсов                                                                                                                          |
+| `keyStrategy`        | `'serialize'` \| `'compare`              | `'serialize'`     |               | Режим хранения и сравнения кеша.  `serialize` хранит ключ кеша в виде строки. `compare` это старый способо, когда ключем являлось значние аргументов |
+| `serializeArgs`      | `TSerializeArgsFn`                       | `stableStringify` | `'serialize'` | Функция для сериализации аргументов в строку.                                                                                                        |
+| `compareArg`         | `TCompareArgsFn`                         | `shallowEqual`    | `compare`     | Функция для сравнения аргументов.                                                                                                                    |
+| `initialSnapshot`    | `TApiSnapshot`  \| `null` \| `undefined` | null              | `'serialize'` | Снимок для инициализации API с набором данных.                                                                                                       |
+| `cacheLifetime`      | `number`                                 | 120_000           |               | Время жизни кеша в миллисекундах. После истечения этого времени, кеш будет считаться устаревшим.                                                     |
+| `plugins`            | `TApiPlugin[]`                           | []                |               | Массив плагинов для расширения функциональности API.                                                                                                 |
+| `maxSnapshotDataAge` | `number`                                 | 5_000             | `'serialize'` | От какого возраста данных в спашноте необходима инвалидация.                                                                                         |
+| `doCacheArgs`        | `boolean`                                | false             | `serialize`   | Кешировать ли результат сериализации аргументов.                                                                                                     |
+
+| Свойство              | Тип                  | Описание                                                                                       |
+|-----------------------|----------------------|------------------------------------------------------------------------------------------------|
+| `resetAll()`          | `() => void`         | Метод для сброса всего состояния API.                                                          |
+| `createResource(...)` | `TCreateResourceFn`  | Метод для создания ресурса. Принимает определение ресурса и возвращает экземпляр `ResourceV2`. |
+| `getSnapshot()`       | `() => TApiSnapshot` | Метод для получения снимка текущего состояния API.                                             |
+
+### api.createResource
+
+`api.createResource` - это метод для создания ресурса (`ResourceV2`).
+
+| Опция                | Тип                            | По умолчанию                           | Описание                                                                                                                     |
+|----------------------|--------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `key`                | `string`                       | Обязятелен для `'serialize'` стратегии | Уникальный ключ ресурса. Использует для логирования в девтулс. Если указан, то будет проверятся на уникальнось в рамках api. |
+| `queryFn`            | `TQueryFn`                     | Обязателен                             | Функция для выполнения запроса. Должна возвращать промис.                                                                    |
+| `onCacheEntryAdded`  | `TResourceOnCacheEntryAddedFn` |                                        | Хук, который вызывается при добавлении новой записи в кеш.                                                                   |
+| `onQueryStarted`     | `TResourceOnQueryStartedFn`    |                                        | Хук, который вызывается при запуске запроса.                                                                                 |
+| `serializeArgs`      | `TSerializeArgsFn`             | createApi опция (stableStringify)      | Функция для сериализации аргументов в строку.                                                                                |
+| `compareArg`         | `TCompareArgsFn`               | createApi опция (shallowEqual)         | Функция для сравнения аргументов.                                                                                            |
+| `cacheLifetime`      | `number`                       | createApi опция (60_000)               | Время жизни кеша для этого ресурса в миллисекундах.                                                                          |
+| `beforeDevtoolsPush` | `TBeforeDevtoolsPushFn`        |                                        | Хук, который вызывается перед отправкой данных в Devtools. Позволяет модифицировать данные.                                  |
+| `maxSnapshotDataAge` | `number`                       | createApi опция (5_000)                | От какого возраста данных в спашноте необходима инвалидация.                                                                 |
+| `doCacheArgs`        | `boolean`                      | createApi опция (false)                | Кешировать ли результат сериализации аргументов.                                                                             |
+
+| Свойство                   | Тип                           | Описание                                                                           |
+|----------------------------|-------------------------------|------------------------------------------------------------------------------------|
+| `createAgent()`            | `CreateResourceV2AgentFn`     | Метод для создания агента ресурса, который позволяет управлять состоянием ресурса. |
+| `query(args, doForse)`     | `TResourveV2QueryFn`          | Метод для выполнения запроса с заданными аргументами. Возвращает промис.           |
+| `query$(args, doForse)`    | `TResourveV2QuerySignalFn`    | Метод для получения сигнала состояния запроса с заданными аргументами.             |
+| `entry(args, doInitiate)`  | `TGetResourceV2EntryFn`       | Метод для получения объекта кеша.                                                  | 
+| `entry$(args, doInitiate)` | `TGetResourceV2EntrySignalFn` | Метод для получения сигнала объекта кеша.                                          |
+
+
+С react плагином:
+
+| Свойство            | Тип              | Описание                                                                                                                  |
+|---------------------|------------------|---------------------------------------------------------------------------------------------------------------------------|
+| `useResource(args)` | `TUseResourceV2` | Хук для выполнения запроса с заданными аргументами. Возвращает массив с состоянием запроса и функцией для его обновления. |
+
+
+### TApiSnapshot
+
+`TApiSnapshot` - это тип, представляет сериализуемый снимок состояния API, 
+который может быть использован для инициализации состояния с предопределенным набором данных (например для дегидрации/гидрации).
+Для гарантии совместимости содержит в себе текущую версию формата, `keyPrefix` и тип.
+
+### TResourveV2QueryFn
+
+```ts
+type TResourveV2QueryFn = <D extends TResourceV2Definition>(
+    args: D['queryFnArgs'],
+    force: boolean
+) => TResourceV2Cache
+```
+
+### ICacheEntry
+`ICacheEntry` - представляет собой реактивную единицу кеша, хранит Machine.
+
+
+## Махиники
+
+### Machine
+`Machine` - это класс, который хранит state и инкапсулирует логику управление state. `Machine` содержит методы для перехода к другим `Machine`.
+
+### Patch'es
+
+`Patch` - это абстрактное представление изменений, которые могут быть применены к данным ресурса.
+Патчи позволяют реализовать оптимистичные обновления.
+В отличие от некоторых других реализаций, патчи в ResourceV2 (как и в V1), защищены от ряда race conditions, благодаря `originalData`.
+
+```
+// Все валидные committed - пропускаем и убираем из очереди
+// Все aborted - применяем и убираем из очереди
+// Все pending - применяем и оставляем в очереди
+// Все commited (которые после pending) - применяем, но оставляем в очереди
+// Все aborted (которые после pending) - откатываем, но оставляем в очереди
+// Если после aborted нет pending - пропускаем и убираем из очереди
+// Те после применения всех транзакций, очередь должна начинаться с первой pending транзакции (если есть), включая все, что после неё.
+// (Подробнее в коде V1) (у V1 проблема: если race conditions все же происходит, то patch "зависает")
+```
+
+## Naming Convention
+
+- Все interface и type начинаются с `I` или `T`
+- Все что непосредственно относится к ResourceV2, должно содежраь в названии `ResourceV2`, чтобы не путать с текущей реализацией.
+
+## Примеры
+
+### Пример создания API используя публичное API пакета:
+
+```ts
+const mainApi = createApi({
+    keyPrefix: 'main',
+    onQueryError(ctx) {
+        // ...
+    }
+});
+
+// ===
+
+import { mainContracts } from '@/my-shared/contracts';
+
+const getUserById = mainApi.createResource({
+    queryFn: mainContracts.fetchUserById,
+    key: 'getUserById',
+});
+
+```
+
+
+### Strong typing
+
+Важно, сохрнить сильные стороны текущей реализации, в том числе сильную типизацию:
+
+```ts
+const mainApi = createApi({
+    plugins: [new ReactHooksPlugin()] // Новое: Модифицируем типы, добавлям хуки в русурс
+});
+
+const getUserById = mainApi.createResource({
+    queryFn: mainContracts.fetchUserById, // Тип getUserById определится автоматически
+});
+
+
+// ===
+
+const userQuery = getUserById.useResource(userId ?? SKIP) // Типипизция допускает передачу только userId и SKIP
+```
+
+### Пример вне фреймворка:
+
+
+```ts
+
+// Используем агента
+class UserStore {
+    private getUserByIdAgent = getUserById.createAgent();
+    selectedUserId$ = Signal.compute(() => this.getUserByIdAgent.state$().args);
+
+    selectedUser$ = Signal.compute(() => this.getUserByIdAgent.state$().data);
+    
+    selectUserId(userId: number) {
+        this.getUserByIdAgent.start(userId);
+    }
+}
+
+
+// Или используем "query select"
+
+class UserStore {
+    private getUserByIdAgent = getUserById.createAgent();
+    selectedUserId$ = Signal.state<number | null>(null);
+
+    selectedUser$ = Signal.compute<User | null>(() => {
+        if (!this.selectedUserId$()) return null;
+        return this.getUserByIdAgent.query$(this.selectedUserId$()).data;
+    });
+
+    selectUserId(userId: number) {
+        this.selectedUserId$.set(userId);
+    }
+}
+```
+
+Разница между `start` и `query$`:
+1) `start` устанавливает fresh аргументы, напрямую и возвращает промис
+2) `query$` тоже устанавливает fresh аргументы, но `query$` - это сигнал, он возращает текущее состояние запроса.
+
+Прямой доступ к ResourceV2 vs agent:
+1) Agent может хранить fresh и stale аргументы.
+2) Agent реализует Stale-While-Revalidate стратегию, позволяя получать не актуальные данные, пока новые загружаются.
+3) Agent предоставляет более удобное API.
+
+
+### Пример опций createApi
+
+```ts
+const mainApi = createApi({
+    keyPrefix: 'main', // Префикс ключа
+    mode: 'serialize', // Режим хранения хранения и сравнения кеша
+    serializeFn: (args) => fastJson(args), // Функция сериализации аргументов
+    onQueryError({ type, payload }) { /*...*/ }, // Хук ошибки
+    snapshot: JSON.parse(hydrateData.mainApiSnapshot), // Снимок для инициализации API с набором данных
+});
+
+mainApi.resetAll(); // Сбросить все состояние
+mainApi.createResource(/*...*/) // Содать ресурс
+mainApi.getSnapshot(); // Получить снимок текущего состояния API
+```
+
+
+## Внутрянка
+
+### Как кеш (state machine) типизируется:
+
+```ts
+type TMachine<ARGS, DATA> =
+    MachinePanding<ARGS, DATA>
+    | MachineIdle<ARGS, DATA> //...
+
+class MachineIdle<ARGS, DATA> {
+    state: TResourceV2IdleState;
+    
+    constructor(state: TResourceV2IdleState) {
+        this.state = state;
+    }
+    
+    start(args: D['queryFnArgs']) {
+        return new MachinePending({
+            status: 'pending',
+            args,
+            error: null,
+            data: null,
+            updatedAt: null,
+        });
+    }
+    
+    /* другие методы, которые могут понадобиться для idle состояния */
+
+    static create() {
+        return new MachineIdle({
+            status: 'idle',
+            args: null,
+            error: null,
+            data: null,
+            updatedAt: null,
+        });
+    }
+}
+
+class MachinePending<ARGS, DATA> {
+    state: TResourceV2PendingState;
+    
+    constructor(state: TResourceV2PendingState) {
+        this.state = state;
+    }
+    
+    errorHappened(error: Error) {
+        return new MachineError({
+            status: 'error',
+            args: this.state.args,
+            error,
+            data: null,
+            updatedAt: null,
+        });
+    }
+    
+    successHappened(data: DATA) {
+        return new MachineSuccess({
+            status: 'success',
+            args: this.state.args,
+            error: null,
+            data,
+            updatedAt: Date.now(),
+        });
+    }
+    
+    /* другие методы, которые могут понадобиться для pending состояния */
+    
+    static create(args: ARGS) {
+        return new MachinePending({
+            status: 'pending',
+            args,
+            originalData: NO_VALUE,
+        });
+    }
+}
+
+// Лучше, чтобы MachineSuccess и MachineRefreshing наследовались от общего класса (чтобы не дублировать код связанный с патчами)
+class MachineSuccess<ARGS, DATA> {
+    state: TResourceV2SuccessState;
+
+    constructor(state: TResourceV2SuccessState) {
+        this.state = state;
+    }
+
+    invalidate() {
+        return new MachineRefreshing({
+            status: 'refreshing',
+            args: this.state.args,
+            data: this.state.data,
+            updatedAt: this.state.updatedAt,
+        });
+    }
+
+    addPatch(patch: TResourceV2Patch) {
+        const originalData = this.state.originalData === NO_VALUE
+            ? this.state.data
+            : this.state.originalData;
+        
+        const patches = (this.state.patches ?? []).concat(tr);
+        
+        return new MachineSuccess({
+            status: 'success',
+            args: this.state.args,
+            data: Patcher.resolvePatches(originalData, patches),
+            updatedAt: Date.now(),
+            originalData,
+            patches,
+        });
+    }
+    
+    finishPatch(type: 'commit' | 'abort', patch: TResourceV2Patch) {
+        const { originalData, patches } = Patcher.finishPatch(
+            this.state.originalData,
+            this.state.patches,
+            type,
+            patch
+        );
+        
+        const machine = new MachineSuccess({
+            status: 'success',
+            args: this.state.args,
+            data: !!originalData?.length 
+                ? Patcher.resolvePatches(originalData, patches) 
+                : originalData,
+            updatedAt: Date.now(),
+            originalData,
+            patches,
+        });
+    }
+    
+    createPatch(patchFn: TPatchFn<D['queryFnReturn']>) {
+        const patch = Patcher.createPatch(patchFn, this.state.data);
+        
+        const state = this.addPatch(patch);
+        
+        return { state, patch };
+    }
+
+    /* другие методы, которые могут понадобиться для pending состояния */
+
+    static deploy(snapshotSlice: TResourceV2SnapshotSlice<D>) {
+        return new MachineSuccess({
+            status: 'success',
+            args: snapshotSlice.args,
+            data: snapshotSlice.data,
+            updatedAt: snapshotSlice.updatedAt,
+        });
+    }
+    
+}
+
+
+// ...
+```