@fozy-labs/rx-toolkit 0.5.3 → 0.6.0

package/dist/query-v2/types/snapshot.types.d.ts

@@ -1,21 +0,0 @@
-/** Full API snapshot for SSR */
-export interface TApiSnapshot {
-    /** Format version (integer counter) */
-    version: number;
-    /** keyPrefix of the API instance */
-    keyPrefix: string | null;
-    /** Resource snapshots keyed by resource key */
-    resources: Record<string, TResourceSnapshot>;
-}
-/** Single resource snapshot */
-export interface TResourceSnapshot {
-    /** Cache entries keyed by serialized args */
-    entries: Record<string, TResourceV2SnapshotSlice>;
-}
-/** Single cache entry snapshot */
-export interface TResourceV2SnapshotSlice<TData = unknown> {
-    status: "success";
-    args: unknown;
-    data: TData;
-    updatedAt: number;
-}

package/dist/query-v2/types/snapshot.types.js

@@ -1 +0,0 @@
-export {};

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

@@ -1,379 +0,0 @@
-
-# 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,
-        });
-    }
-    
-}
-
-
-// ...
-```

package/docs/migrations/query-v2.md

@@ -1,171 +0,0 @@
-# Миграция с Query v1 на Query v2
-
-> ⚠️ Query v2 — **экспериментальный модуль**. v1 продолжает поддерживаться.
-
-## Сосуществование v1 и v2
-
-Оба модуля могут использоваться одновременно в одном приложении без конфликтов. Они полностью изолированы:
-- v1: импорты из `@fozy-labs/rx-toolkit` (`createResource`, `createCommand`)
-- v2: импорты из `@fozy-labs/rx-toolkit` через namespace `queryV2`
-
-```typescript
-// v1
-import { createResource, useResourceAgent } from '@fozy-labs/rx-toolkit';
-
-// v2
-import { unstable_queryV2 } from '@fozy-labs/rx-toolkit';
-const api = unstable_queryV2.createApi({ /* ... */ });
-```
-
-Кэши v1 и v2 не пересекаются. Можно мигрировать ресурсы по одному.
-
----
-
-## Маппинг концепций
-
-### createResource → createApi + api.createResource
-
-```typescript
-// v1
-const userResource = createResource({
-    queryFn: fetchUser,
-    cacheLifetime: 30000,
-    devtoolsName: 'user',
-});
-
-// v2
-const api = unstable_queryV2.createApi({
-    plugins: [new unstable_queryV2.ReactHooksPlugin()],
-});
-const userResource = api.createResource({
-    key: 'user',
-    queryFn: fetchUser,
-    cacheLifetime: 30000,
-});
-```
-
-**Ключевые отличия:**
-- Ресурс создаётся через API-инстанс, а не как standalone
-- `devtoolsName` заменён на `key` + `beforeDevtoolsPush`
-- Общая конфигурация (cacheLifetime, serialization) задаётся на уровне API
-
-### Resource → ResourceV2
-
-| v1 | v2 | Примечание |
-|----|----|-----------|
-| `createResource(opts)` | `api.createResource(opts)` | Через API-инстанс |
-| `queryFn(args, tools)` | `queryFn(args, { abortSignal })` | Та же сигнатура tools |
-| `select` | — | Убрано, трансформация вне ресурса |
-| `devtoolsName` | `key` + `beforeDevtoolsPush` | Ключ для snapshot и devtools |
-| `compareArgsFn` | `compareArg` | Переименовано |
-
-### Command → Вне scope v2
-
-В v2 нет прямого аналога `createCommand`. Мутации реализуются через:
-- Прямые вызовы API + `ref.createPatch()` для оптимистичных обновлений
-- `ref.invalidate()` для инвалидации после мутации
-
-```typescript
-// v1: Command с link
-const updateUser = createCommand({
-    queryFn: updateUserApi,
-    link(add) {
-        add({
-            resource: userResource,
-            forwardArgs: (args) => ({ id: args.id }),
-            update: ({ draft, args }) => { draft.name = args.name; },
-        });
-    },
-});
-
-// v2: Прямой вызов + патч
-async function updateUser(id: string, name: string) {
-    const ref = userResource.useResourceV2Ref({ id });
-    const patch = ref.createPatch(draft => { draft.name = name; });
-    try {
-        await fetch(`/api/users/${id}`, { method: 'PATCH', body: JSON.stringify({ name }) });
-        patch?.commit();
-    } catch {
-        patch?.abort();
-    }
-}
-```
-
-### Boolean flags → Machine states
-
-```typescript
-// v1
-if (query.isLoading) { /* ... */ }
-if (query.isSuccess) { /* ... */ }
-if (query.isError) { /* ... */ }
-
-// v2 — агент предоставляет те же флаги
-if (state.isLoading) { /* ... */ }
-if (state.isSuccess) { /* ... */ }
-if (state.isError) { /* ... */ }
-
-// v2 — дополнительно: машина состояний
-if (state.status === 'pending') { /* ... */ }
-if (state.status === 'refreshing') { /* ... */ }
-if (state.isInitialLoading) { /* первая загрузка */ }
-if (state.isRefreshing) { /* обновление с данными */ }
-```
-
-### useResourceAgent → useResourceV2Agent
-
-```typescript
-// v1
-import { useResourceAgent } from '@fozy-labs/rx-toolkit';
-const query = useResourceAgent(userResource, { id: '1' });
-
-// v2 (через ReactHooksPlugin)
-const state = userResource.useResourceV2Agent({ id: '1' });
-```
-
-**Изменения:**
-- Хук вызывается на самом ресурсе (метод, добавленный плагином)
-- Не нужен отдельный импорт хука
-- Для пропуска запроса используется `SKIP` вместо условного вызова
-
-### useResourceRef → useResourceV2Ref
-
-```typescript
-// v1
-import { useResourceRef } from '@fozy-labs/rx-toolkit';
-const ref = useResourceRef(userResource, { id: '1' });
-ref.patch(draft => { draft.name = 'new'; });
-
-// v2 (через ReactHooksPlugin)
-const ref = userResource.useResourceV2Ref({ id: '1' });
-const patch = ref.createPatch(draft => { draft.name = 'new'; });
-patch?.commit(); // или patch?.abort();
-```
-
-**Изменения:**
-- `patch()` → `createPatch()` с явным `commit/abort`
-- Добавлен `ref.create(data)` для предзаполнения кэша
-- `ref.lock()` возвращает `{ unlock }` для разблокировки
-
-### resetAllQueriesCache → api.resetAll
-
-```typescript
-// v1
-import { resetAllQueriesCache } from '@fozy-labs/rx-toolkit';
-resetAllQueriesCache();
-
-// v2
-api.resetAll();
-```
-
----
-
-## Новое в v2
-
-| Функция | Описание |
-|---------|----------|
-| **Плагины** | Расширяемая архитектура (`ReactHooksPlugin` и др.) |
-| **Machine states** | Типизированные состояния вместо boolean-флагов |
-| **SSR Snapshots** | `getSnapshot()` / `initialSnapshot` для серверного рендеринга |
-| **API factory** | Единая точка конфигурации |
-| **Очередь патчей** | Несколько независимых оптимистичных обновлений |
-| **SKIP_TOKEN** | Пропуск запроса с типобезопасностью |