@fozy-labs/rx-toolkit 0.4.17 → 0.5.0-rc.0

package/docs/usage/react/README.md

@@ -9,43 +9,47 @@ RxToolkit предоставляет набор React хуков для эффе
 Подписывается на изменения сигнала и возвращает текущее значение.
 
 ```tsx
-import { useSignal } from '@fozy-labs/rx-toolkit';
+import { Signal, Computed, useSignal } from '@fozy-labs/rx-toolkit';
+
+const counter$ = Signal.create(0);
+const doubled$ = Signal.compute(() => counter$() * 2);
 
 function Counter() {
-  const count = useSignal(countSignal);
-  
-  return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={() => countSignal.value++}>
-        Increment
-      </button>
-    </div>
-  );
+    const count = useSignal(counter$);
+    const doubled = useSignal(doubled$);
+
+    return (
+        <div>
+            <p>Count: {count}</p>
+            <p>Doubled: {doubled}</p>
+            <button onClick={() => counter$.set(counter$.peek() + 1)}>
+                Increment
+            </button>
+        </div>
+    );
 }
 ```
 
 **Особенности:**
-- Автоматическая подписка и отписка
-- Использует `useSyncExternalStore` для оптимальной производительности
+- Автоматическая подписка и отписка при размонтировании
 - Не вызывает ре-рендер, если значение не изменилось
 
 ### useObservable
 
 Подписывается на RxJS Observable и возвращает текущее значение.
 
-```typescript
+```tsx
 import { useObservable } from '@fozy-labs/rx-toolkit';
 import { interval, map } from 'rxjs';
 
 const timer$ = interval(1000).pipe(
-  map(count => `Timer: ${count}`)
+    map(count => `Timer: ${count}`)
 );
 
 function Timer() {
-  const timerValue = useObservable(timer$, 'Timer: 0');
-  
-  return <div>{timerValue}</div>;
+    const timerValue = useObservable(timer$, 'Timer: 0');
+    
+    return <div>{timerValue}</div>;
 }
 ```
 
@@ -53,10 +57,13 @@ function Timer() {
 - `observable$` — RxJS Observable для подписки
 - `initialValue` — начальное значение до первой эмиссии
 
+**Особенности:**
+- Требует начальное значение, если Observable асинхронный
+- Автоматическая переподписка при смене Observable
+
 ### useSyncObservable
 
 Синхронная версия `useObservable` для Observable, которые могут выдать значение немедленно.
-Если Observable не может выдать значение сразу, будет выброшена ошибка.
 
 ```tsx
 import { useSyncObservable } from '@fozy-labs/rx-toolkit';
@@ -65,68 +72,100 @@ import { BehaviorSubject } from 'rxjs';
 const data$ = new BehaviorSubject('initial data');
 
 function DataComponent() {
-  const data = useSyncObservable(data$);
-  
-  return <div>Data: {data}</div>;
+    const data = useSyncObservable(data$);
+    
+    return <div>Data: {data}</div>;
 }
 ```
 
 **Отличия от useObservable:**
 - Не требует начального значения
-- Получает значение синхронно при первом рендере
-- Подходит для BehaviorSubject и других синхронных Observable
+- Подходит для BehaviorSubject, ReplaySubject и сигналов
+- Выбросит ошибку, если Observable не эмитит значение синхронно
+
+---
 
 ## RxQuery хуки
 
 ### useResourceAgent
 
-Подписывается на состояние ресурса и автоматически инициирует запрос.
+Подписывается на состояние ресурса и автоматически инициирует запрос при монтировании или изменении аргументов.
 
 ```tsx
 import { useResourceAgent, SKIP } from '@fozy-labs/rx-toolkit';
-import { userResource } from '../api/userResource.ts';
+import { userResource } from '../api/userResource';
 
-// Автоматическая инициация
 function UserProfile({ userId }: { userId: string | null }) {
-  const userState = useResourceAgent(userResource, userId ? { id: userId } : SKIP);
-
-  if (userState.isLoading || !userId) return <div>Загрузка...</div>;
-  if (userState.isError) return <div>Ошибка: {userState.error?.message}</div>;
-  
-  return (
-    <div>
-      <h1>{userState.data?.name}</h1>
-      <p>{userState.data?.email}</p>
-    </div>
-  );
+    const userQuery = useResourceAgent(
+        userResource, 
+        userId ? { id: userId } : SKIP
+    );
+
+    if (userQuery.isInitialLoading) {
+        return <div>Загрузка...</div>;
+    }
+    
+    if (userQuery.isError) {
+        return <div>Ошибка: {String(userQuery.error)}</div>;
+    }
+    
+    if (userQuery.isReloading) {
+        // Показываем данные + индикатор перезагрузки
+    }
+    
+    return (
+        <div>
+            <h1>{userQuery.data?.name}</h1>
+            <p>{userQuery.data?.email}</p>
+        </div>
+    );
 }
 ```
 
+**Возвращаемое значение (ResourceQueryState):**
+
+| Поле               | Тип         | Описание                              |
+|--------------------|-------------|---------------------------------------|
+| `isLoading`        | `boolean`   | Любая загрузка (первая или повторная) |
+| `isInitialLoading` | `boolean`   | Первая загрузка (данных еще нет)      |
+| `isReloading`      | `boolean`   | Перезагрузка (данные уже есть)        |
+| `isDone`           | `boolean`   | Завершен ли запрос                    |
+| `isSuccess`        | `boolean`   | Успешно ли завершен последний запрос  |
+| `isError`          | `boolean`   | Произошла ли ошибка                   |
+| `isLocked`         | `boolean`   | Заблокирован ли ресурс для операцией  |
+| `error`            | `unknown`   | Объект ошибки                         |
+| `data`             | `D["Data"]` | Данные ресурса                        |
+| `args`             | `D["Args"]` | Аргументы последнего запроса          |
+
 **Особенности:**
 - Автоматическая подписка на состояние ресурса
 - Умная инициация: не повторяет запрос для тех же аргументов
-- Поддержка SKIP токена для ручного управления
+- Поддержка `SKIP` токена для условного пропуска запроса
+- При смене аргументов показывает предыдущие данные во время загрузки новых
 
 ### useOperationAgent
 
-Подписывается на состояние операции для отслеживания выполнения мутаций.
+Создает агент операции и возвращает кортеж `[trigger, state]`.
 
 ```tsx
 import { useOperationAgent } from '@fozy-labs/rx-toolkit';
-import { updateUserOperation } from '../api/updateUserOperation.ts';
-import { User } from '../types/user.ts';
+import { updateUserOperation } from '../api/updateUserOperation';
 
 function EditUserForm({ user }: { user: User }) {
-    const [updateUser, updateUserQuery] = useOperationAgent(updateUserOperation);
+    const [updateUser, updateState] = useOperationAgent(updateUserOperation);
 
     const handleSubmit = async (event: React.FormEvent) => {
         event.preventDefault();
         const formData = new FormData(event.target as HTMLFormElement);
+        
         try {
-            await agent.initiate({ id: user.id, data: formData });
-            alert('Пользователь обновлен');
+            const result = await updateUser({ 
+                id: user.id, 
+                data: Object.fromEntries(formData) 
+            });
+            console.log('Обновлено:', result);
         } catch (error) {
-            alert('Ошибка при обновлении пользователя');
+            console.error('Ошибка:', error);
         }
     };
 
@@ -134,11 +173,184 @@ function EditUserForm({ user }: { user: User }) {
         <form onSubmit={handleSubmit}>
             <input name="name" defaultValue={user.name} />
             <input name="email" defaultValue={user.email} />
-            <button type="submit" disabled={updateUserQuery.isLoading}>
-                {updateUserQuery.isLoading ? 'Обновление...' : 'Обновить'}
+            
+            <button type="submit" disabled={updateState.isLoading}>
+                {updateState.isLoading ? 'Сохранение...' : 'Сохранить'}
             </button>
-            {updateUserQuery.isError && <p>Ошибка: {updateUserQuery.error?.message}</p>}
+            
+            {updateState.isError && (
+                <p className="error">Ошибка: {String(updateState.error)}</p>
+            )}
         </form>
     );
 }
 ```
+
+**Возвращаемое значение:**
+```typescript
+[
+    trigger: (args: Args) => Promise<Data>,  // Функция запуска операции
+    state: OperationQueryState               // Текущее состояние
+]
+```
+
+**trigger функция:**
+- Возвращает Promise с результатом операции
+- При ошибке Promise реджектится
+- Функция стабильна (не меняется между рендерами)
+
+**state объект:**
+
+| Поле          | Тип         | Описание                  |
+|---------------|-------------|---------------------------|
+| `isInitiated` | `boolean`   | Была ли операция запущена |
+| `isLoading`   | `boolean`   | Выполняется ли операция   |
+| `isDone`      | `boolean`   | Завершена ли операция     |
+| `isSuccess`   | `boolean`   | Успешно ли завершена      |
+| `isError`     | `boolean`   | Произошла ли ошибка       |
+| `error`       | `unknown`   | Объект ошибки             |
+| `data`        | `D["Data"]` | Результат операции        |
+
+### useResourceRef
+
+Возвращает ссылку на элемент кэша ресурса для низкоуровневых операций.
+
+```tsx
+import { useResourceRef, useResourceAgent } from '@fozy-labs/rx-toolkit';
+import { todoResource } from '../api/todoResource';
+
+function TodoItem({ todo }: { todo: Todo }) {
+    const todoQuery = useResourceAgent(todoResource, undefined);
+    const todoRef = useResourceRef(todoResource, undefined);
+    
+    const [pendingTransaction, setPendingTransaction] = useState(null);
+    
+    const handleToggle = () => {
+        // Создаем транзакцию для изменения
+        const transaction = todoRef.patch((draft) => {
+            const item = draft.items.find(i => i.id === todo.id);
+            if (item) item.completed = !item.completed;
+        });
+        
+        if (transaction) {
+            setPendingTransaction(transaction);
+        }
+    };
+    
+    const handleSave = async () => {
+        try {
+            await saveToServer(todo.id, !todo.completed);
+            pendingTransaction?.commit();
+        } catch {
+            pendingTransaction?.abort(); // Откатить изменения
+        }
+        setPendingTransaction(null);
+    };
+    
+    return (
+        <div>
+            <input 
+                type="checkbox" 
+                checked={todo.completed}
+                onChange={handleToggle}
+            />
+            {pendingTransaction && (
+                <>
+                    <button onClick={handleSave}>Сохранить</button>
+                    <button onClick={() => {
+                        pendingTransaction.abort();
+                        setPendingTransaction(null);
+                    }}>
+                        Отмена
+                    </button>
+                </>
+            )}
+        </div>
+    );
+}
+```
+
+**Возвращаемое значение (ResourceRefInstanse):**
+
+| Метод | Описание |
+|-------|----------|
+| `has` | Проверка наличия элемента в кэше |
+| `lock()` | Блокировка ресурса, возвращает `{ unlock }` |
+| `unlockOne()` | Снятие одной блокировки |
+| `patch(fn)` | Создание patch-транзакции |
+| `invalidate()` | Инвалидация кэша |
+| `create(data)` | Создание элемента в кэше |
+
+
+---
+
+## Паттерны использования
+
+### Store класс
+
+```tsx
+import { Signal, useSignal } from '@fozy-labs/rx-toolkit';
+
+class CounterStore {
+    count$ = Signal.create(0, 'counter');
+    doubled$ = Signal.compute(() => this.count$() * 2);
+    
+    increment = () => this.count$.set(this.count$.peek() + 1);
+    decrement = () => this.count$.set(this.count$.peek() - 1);
+    reset = () => this.count$.set(0);
+}
+
+// Singleton
+const counterStore = new CounterStore();
+
+function Counter() {
+    const count = useSignal(counterStore.count$);
+    const doubled = useSignal(counterStore.doubled$);
+    
+    return (
+        <div>
+            <p>{count} × 2 = {doubled}</p>
+            <button onClick={counterStore.increment}>+</button>
+            <button onClick={counterStore.decrement}>-</button>
+            <button onClick={counterStore.reset}>Reset</button>
+        </div>
+    );
+}
+```
+
+### Условные запросы
+
+```tsx
+function UserStats({ userId, showStats }) {
+    const statsQuery = useResourceAgent(
+        statsResource,
+        showStats && userId ? { userId } : SKIP
+    );
+    
+    if (!showStats) return null;
+    
+    return <StatsDisplay data={statsQuery.data} />;
+}
+```
+
+### Комбинирование ресурсов
+
+```tsx
+function Dashboard() {
+    const userQuery = useResourceAgent(userResource, { id: currentUserId });
+    const settingsQuery = useResourceAgent(settingsResource, undefined);
+    
+    const isLoading = userQuery.isLoading || settingsQuery.isLoading;
+    const isError = userQuery.isError || settingsQuery.isError;
+    
+    if (isLoading) return <Loader />;
+    if (isError) return <Error />;
+    
+    return (
+        <div>
+            <UserInfo user={userQuery.data} />
+            <Settings settings={settingsQuery.data} />
+        </div>
+    );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fozy-labs/rx-toolkit",
-  "version": "0.4.17",
+  "version": "0.5.0-rc.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
@@ -11,16 +11,16 @@
   },
   "devDependencies": {
     "concurrently": "9.2.0",
-    "rimraf": "6.0.1",
+    "rimraf": "6.1.2",
     "tsc-alias": "^1.8.16",
     "tsconfig-paths": "4.2.0",
     "typescript": "5.9.2",
     "zod": "4.1.11"
   },
   "peerDependencies": {
-    "react": "19.1.1",
-    "rxjs": "7.8.2",
-    "zod": "4.1.11"
+    "react": "^19.0.0",
+    "rxjs": "^7.0.0",
+    "zod": "^4.0.0"
   },
   "description": "Набор инструментов для реактивного управления состоянием, построенный поверх RxJS.",
   "author": "Vladimir Panev <vova6255@gmail.com>",

package/dist/query/api/cleanAllQueriesCache.d.ts

@@ -1 +0,0 @@
-export declare function cleanAllQueriesCache(): void;

package/dist/query/api/cleanAllQueriesCache.js

@@ -1,4 +0,0 @@
-import { CleanAllQueriesSignal } from "../core/CleanAllQueriesSignal";
-export function cleanAllQueriesCache() {
-    CleanAllQueriesSignal.clean();
-}

package/dist/query/core/CleanAllQueriesSignal.js

@@ -1,11 +0,0 @@
-import { Subject } from "rxjs";
-import { Batcher } from "../../signals";
-export class CleanAllQueriesSignal {
-    static subject$ = new Subject();
-    static clean$ = CleanAllQueriesSignal.subject$;
-    static clean() {
-        Batcher.batch(() => {
-            CleanAllQueriesSignal.subject$.next();
-        });
-    }
-}

package/dist/signals/base/Tracker.d.ts

@@ -1,10 +0,0 @@
-import { type Observable, Subject } from "rxjs";
-type TrackedValue = {
-    rang: number;
-    obsv$: Observable<unknown>;
-};
-export declare const Tracker: {
-    tracked$: Subject<TrackedValue>;
-    next(rang: number, observable: Observable<unknown>): void;
-};
-export {};

package/dist/signals/base/Tracker.js

@@ -1,7 +0,0 @@
-import { Subject } from "rxjs";
-export const Tracker = {
-    tracked$: new Subject(),
-    next(rang, observable) {
-        Tracker.tracked$.next({ rang, obsv$: observable, });
-    }
-};

package/dist/signals/base/types.d.ts

@@ -1,23 +0,0 @@
-import type { Observable } from "rxjs";
-export interface ReadableSignalLike<T = unknown> extends Observable<T> {
-    get value(): T;
-    peek(): T;
-    /**
-     * @deprecated use `value` instead.
-     */
-    get(): T;
-}
-export interface SignalLike<T = unknown> extends ReadableSignalLike<T> {
-    set value(value: T);
-    next(value: T): void;
-    asReadonly(): ReadableSignalLike<T>;
-    /**
-     * @deprecated use `value` instead.
-     */
-    set(value: T): void;
-}
-export interface UnaryFunction<T, R> {
-    (source: T): R;
-}
-export type SignalOperatorFn<T, R> = UnaryFunction<ReadableSignalLike<T>, ReadableSignalLike<R>>;
-export type MonoTypeSignalOperatorFn<T> = SignalOperatorFn<T, T>;

package/dist/signals/operators/filterUpdates.d.ts

@@ -1,5 +0,0 @@
-import { type TruthyTypesOf } from "rxjs";
-import type { MonoTypeSignalOperatorFn, SignalOperatorFn } from "../base";
-export declare function filterUpdates<T, S extends T>(predicate: (value: T, index: number) => value is S): SignalOperatorFn<T, S>;
-export declare function filterUpdates<T>(predicate: BooleanConstructor): SignalOperatorFn<T, TruthyTypesOf<T>>;
-export declare function filterUpdates<T>(predicate: (value: T, index: number) => boolean): MonoTypeSignalOperatorFn<T>;

package/dist/signals/operators/filterUpdates.js

@@ -1,18 +0,0 @@
-import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
-import { ReadonlySignal } from "../base";
-export function filterUpdates(predicate, thisArg) {
-    return (source) => new ReadonlySignal((destination) => {
-        let index = 0;
-        let isFirst = true;
-        source.subscribe(createOperatorSubscriber(destination, (value) => {
-            if (isFirst) {
-                isFirst = false;
-                destination.next(value);
-                return;
-            }
-            const result = predicate.call(thisArg, value, index++);
-            if (result)
-                destination.next(value);
-        }));
-    });
-}

package/dist/signals/operators/mapSignals.d.ts

@@ -1,3 +0,0 @@
-import type { SignalOperatorFn } from "../base";
-export declare function mapSignals<T, R, A>(project: (this: A, value: T, index: number) => R): SignalOperatorFn<T, R>;
-export declare function mapSignals<T, R, A>(project: (this: A, value: T, index: number) => R, thisArg: A): SignalOperatorFn<T, R>;

package/dist/signals/operators/mapSignals.js

@@ -1,10 +0,0 @@
-import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
-import { ReadonlySignal } from "../base";
-export function mapSignals(project, thisArg) {
-    return (source) => new ReadonlySignal((destination) => {
-        let index = 0;
-        source.subscribe(createOperatorSubscriber(destination, (value) => {
-            destination.next(project.call(thisArg, value, index++));
-        }));
-    });
-}