@fozy-labs/rx-toolkit 0.4.1

package/docs/signals/README.md

@@ -0,0 +1,119 @@
+# RxSignals
+
+RxSignals — это реактивная система управления состоянием, вдохновленная современными фреймворками типа SolidJS и Angular Signals. Она предоставляет эффективные инструменты для создания реактивных приложений.
+
+## Основные концепции
+
+### Signal
+
+Базовый класс для создания реактивных сигналов.
+
+**Пример использования:**
+
+```typescript
+const name = new Signal('John');
+const age = new Signal(25);
+
+// Подписка на изменения
+const subscription = name.subscribe(newName => {
+  console.log(`Name changed to: ${newName}`);
+});
+
+name.value = 'Jane'; // Выведет: "Name changed to: Jane"
+
+// Отписка
+subscription.unsubscribe();
+```
+
+### Computed
+
+Создает вычисляемое значение, которое автоматически обновляется при изменении зависимостей.
+
+```typescript
+const firstName = new Signal('John');
+const lastName = new Signal('Doe');
+
+const fullName = new Computed(() => `${firstName.value} ${lastName.value}`);
+
+console.log(fullName.value); // "John Doe"
+
+firstName.value = 'Jane';
+console.log(fullName.value); // "Jane Doe"
+```
+
+### Effect
+
+Создает эффект, который выполняется при изменении используемых сигналов.
+
+```typescript
+const count = new Signal(0);
+const message = new Signal('Hello');
+
+const sub = new Effect(() => {
+    // Выведет: "Hello: 0" при инициализации
+  console.log(`${message.value}: ${count.value}`);
+});
+
+count.value = 1; // Выведет: "Hello: 1"
+message.value = 'Hi'; // Выведет: "Hi: 1"
+
+// Остановка эффекта
+sub.unsubscribe();
+```
+
+### LocalSignal
+
+Сигнал, который синхронизируется с локальным хранилищем (localStorage).
+// TODO убрать zod из core, добавить возможность передавать "driver".
+
+```typescript
+import { LocalSignal } from '@fozy-labs/rx-toolkit';
+
+const selectedFilter$ = new LocalSignal({
+    key: 'projects-list-selected-filter',
+    defaultValue: FILTER.ALL,
+    zodSchema: z.enum(FILTER),
+});
+```
+
+## Operators (Операторы)
+
+### batched
+Группирует несколько обновлений в одну транзакцию для оптимизации производительности.
+// TODO: проверить, тк не используется в fozy, добавить пример использования
+
+### mapSignals
+// TODO: добавить описание
+
+
+### signalize
+
+Преобразует Observable в Signal.
+
+```typescript
+import { signalize } from '@fozy-labs/rx-toolkit';
+import { interval } from 'rxjs';
+import { Effect } from "src/signal/base/Effect";
+
+// Создаем Observable, который эмитит значение каждую секунду
+const timer$ = interval(1000).pipe(
+    startWith(0),
+);
+
+// Преобразуем Observable в Signal
+const tick$ = signalize(timer$);
+
+// Теперь можно использовать timerSignal как обычный Signal
+new Effect(() => {
+    console.log(`Timer: ${tick$.value}`);
+})
+```
+
+### filterUpdates
+
+Фильтрует обновления сигнала.
+// TODO: добавить пример использования, подумать над целесообразностью
+
+## React Integration
+
+См. [React интеграция](../usage/react/README.md) для подробной информации о том, как использовать RxSignals в React приложениях.

package/docs/usage/react/README.md

@@ -0,0 +1,144 @@
+# React интеграция
+
+RxToolkit предоставляет набор React хуков для эффективной интеграции с реактивными системами библиотеки. Все хуки оптимизированы для минимальных ре-рендеров и максимальной производительности.
+
+## Основные хуки
+
+### useSignal
+
+Подписывается на изменения сигнала и возвращает текущее значение.
+
+```tsx
+import { useSignal } from '@fozy-labs/rx-toolkit';
+
+function Counter() {
+  const count = useSignal(countSignal);
+  
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => countSignal.value++}>
+        Increment
+      </button>
+    </div>
+  );
+}
+```
+
+**Особенности:**
+- Автоматическая подписка и отписка
+- Использует `useSyncExternalStore` для оптимальной производительности
+- Не вызывает ре-рендер, если значение не изменилось
+
+### useObservable
+
+Подписывается на RxJS Observable и возвращает текущее значение.
+
+```typescript
+import { useObservable } from '@fozy-labs/rx-toolkit';
+import { interval, map } from 'rxjs';
+
+const timer$ = interval(1000).pipe(
+  map(count => `Timer: ${count}`)
+);
+
+function Timer() {
+  const timerValue = useObservable(timer$, 'Timer: 0');
+  
+  return <div>{timerValue}</div>;
+}
+```
+
+**Параметры:**
+- `observable$` — RxJS Observable для подписки
+- `initialValue` — начальное значение до первой эмиссии
+
+### useSyncObservable
+
+Синхронная версия `useObservable` для Observable, которые могут выдать значение немедленно.
+Если Observable не может выдать значение сразу, будет выброшена ошибка.
+
+```tsx
+import { useSyncObservable } from '@fozy-labs/rx-toolkit';
+import { BehaviorSubject } from 'rxjs';
+
+const data$ = new BehaviorSubject('initial data');
+
+function DataComponent() {
+  const data = useSyncObservable(data$);
+  
+  return <div>Data: {data}</div>;
+}
+```
+
+**Отличия от useObservable:**
+- Не требует начального значения
+- Получает значение синхронно при первом рендере
+- Подходит для BehaviorSubject и других синхронных Observable
+
+## RxQuery хуки
+
+### useResourceAgent
+
+Подписывается на состояние ресурса и автоматически инициирует запрос.
+
+```tsx
+import { useResourceAgent, SKIP } from '@fozy-labs/rx-toolkit';
+import { userResource } from '../api/userResource.ts';
+
+// Автоматическая инициация
+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>
+  );
+}
+```
+
+**Особенности:**
+- Автоматическая подписка на состояние ресурса
+- Умная инициация: не повторяет запрос для тех же аргументов
+- Поддержка SKIP токена для ручного управления
+
+### useOperationAgent
+
+Подписывается на состояние операции для отслеживания выполнения мутаций.
+
+```tsx
+import { useOperationAgent } from '@fozy-labs/rx-toolkit';
+import { updateUserOperation } from '../api/updateUserOperation.ts';
+import { User } from '../types/user.ts';
+
+function EditUserForm({ user }: { user: User }) {
+    const [updateUser, updateUserQuery] = 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('Пользователь обновлен');
+        } catch (error) {
+            alert('Ошибка при обновлении пользователя');
+        }
+    };
+
+    return (
+        <form onSubmit={handleSubmit}>
+            <input name="name" defaultValue={user.name} />
+            <input name="email" defaultValue={user.email} />
+            <button type="submit" disabled={updateUserQuery.isLoading}>
+                {updateUserQuery.isLoading ? 'Обновление...' : 'Обновить'}
+            </button>
+            {updateUserQuery.isError && <p>Ошибка: {updateUserQuery.error?.message}</p>}
+        </form>
+    );
+}
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@fozy-labs/rx-toolkit",
+  "version": "0.4.1",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "rimraf ./dist && tsc && tsc-alias",
+    "build:watch": "rimraf ./dist && (concurrently \"tsc -w\" \"tsc-alias -w\")",
+    "ts-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@reatom/devtools": "0.13.1"
+  },
+  "devDependencies": {
+    "rimraf": "6.0.1",
+    "tsc-alias": "^1.8.16",
+    "tsconfig-paths": "4.2.0",
+    "concurrently": "9.2.0",
+    "typescript": "5.9.2",
+    "zod": "4.1.11"
+  },
+  "peerDependencies": {
+    "react": "19.1.1",
+    "rxjs": "7.8.2",
+    "zod": "4.1.11"
+  },
+  "description": "Набор инструментов для реактивного управления состоянием, построенный поверх RxJS.",
+  "author": "Vladimir Panev <vova6255@gmail.com>",
+  "homepage": "https://github.com/fozy-labs/rx-toolkit",
+  "license": "MIT",
+  "keywords": ["react", "rxjs", "toolkit", "state-management"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fozy-labs/rx-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fozy-labs/rx-toolkit/issues"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "preferGlobal": false
+}