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

package/docs/devtools/README.md

@@ -1,70 +1,140 @@
 # Devtools
 
-RxToolkit предоставляет интеграцию с популярными инструментами разработчика для отладки реактивных приложений в реальном времени. Вы можете отслеживать изменения сигналов, выполнение операций и состояние ресурсов, анализировать граф зависимостей и исследовать поведение реактивной системы.
+RxToolkit предоставляет интеграцию с популярными инструментами разработчика для отладки реактивных приложений в реальном времени. Вы можете отслеживать изменения сигналов, выполнение операций и состояние ресурсов.
 
-**Отслеживает изменения состояния:**
-- Сигналов (Signal/Computed)
-- Ресурсов и операций (Resource/Operation)
+**Отслеживает изменения:**
+- Сигналов (Signal / Computed)
+- Ресурсов и операций (Resource / Operation)
+
+---
 
 ## Redux DevTools
 
 Популярное браузерное расширение для отладки состояния приложений. **RxToolkit включает встроенный адаптер `reduxDevtools()`**.
 
-**Установка:**
-1. Установите [расширение](https://github.com/reduxjs/redux-devtools) для браузера
+### Установка
+
+1. Установите [расширение Redux DevTools](https://github.com/reduxjs/redux-devtools) для браузера
 2. Подключите в коде:
 
 ```typescript
 import { DefaultOptions, reduxDevtools } from '@fozy-labs/rx-toolkit';
 
 DefaultOptions.update({ 
-  DEVTOOLS: reduxDevtools() 
+    DEVTOOLS: reduxDevtools() 
 });
 ```
 
+### Опции reduxDevtools
+
+```typescript
+reduxDevtools({
+    // Имя приложения в DevTools
+    name: 'MyApp',
+    
+    // Стратегия батчинга обновлений
+    batchStrategy: 'microtask', // 'sync' | 'microtask' | 'task'
+    
+    // Задержка для стратегии 'task' (мс)
+    taskDelay: 0,
+})
+```
+
+**Стратегии батчинга (batchStrategy):**
+
+| Стратегия     | Описание                                                                                                        |
+|---------------|-----------------------------------------------------------------------------------------------------------------|
+| `'sync'`      | Синхронное выполнение без батчинга. Каждое обновление отправляется немедленно. Интегрируется с Batcher сигналов |
+| `'microtask'` | **(default)** Пакование в микротаске. Все обновления в текущем синхронном потоке объединяются                   |
+| `'task'`      | Пакование в макротаске (setTimeout) с настраиваемой задержкой                                                   |
+
+---
+
 ## @reatom/devtools
 
-Npm пакет, содержащий отладчик, работающий прямо в браузере.
-Совместим по API с `rx-toolkit`.
-После подключения в углу страницы появляется кнопка,
-которая открывает панель инструментов.
+Npm пакет с встроенным отладчиком, работающим прямо в браузере. После подключения в углу страницы появляется кнопка, которая открывает панель инструментов.
+
+### Установка
 
-**Установка:**
 ```bash
 npm install @reatom/devtools
 ```
 
-**Подключение:**
+### Подключение
+
 ```typescript
 import { DefaultOptions } from '@fozy-labs/rx-toolkit';
 import { createDevtools } from '@reatom/devtools';
 
 DefaultOptions.update({
-  DEVTOOLS: createDevtools({ 
-    initVisibility: true 
-  })
+    DEVTOOLS: createDevtools({ 
+        initVisibility: true // Показать панель при загрузке
+    })
 });
 ```
 
 **Может пригодиться:**
-- Если в вашей среде не удобно или проблематично установить браузерное расширение.
-- Если вы уже работали с Reatom.
+- Если в вашей среде неудобно или проблематично установить браузерное расширение
+- Для мобильной отладки
+
+---
+
+## DefaultOptions
+
+`DefaultOptions.update()` позволяет настроить глобальные опции RxToolkit:
+
+```typescript
+import { DefaultOptions, reduxDevtools } from '@fozy-labs/rx-toolkit';
+import { Observable } from 'rxjs';
+
+DefaultOptions.update({
+    // Devtools интеграция
+    DEVTOOLS: reduxDevtools(),
+    
+    // Глобальный обработчик ошибок запросов
+    onQueryError: (error) => {
+        console.error('Query error:', error);
+        // Можно отправить в систему мониторинга
+        errorTracker.capture(error);
+    },
+    
+    // Функция для получения имени текущего scope (полезно для SSR)
+    getScopeName: () => {
+        return currentRequestId ?? null;
+    },
+});
+```
+
+### Параметры DefaultOptions
+
+| Параметр | Тип | Описание |
+|----------|-----|----------|
+| `DEVTOOLS` | `DevtoolsLike \| null` | Интеграция с devtools |
+| `onQueryError` | `(error: unknown) => void` | Глобальный обработчик ошибок запросов |
+| `getScopeName` | `() => string \| null` | Получение имени текущего scope |
+
+---
 
 ## Практики
 
 ### Development-режим
 
-Подключайте devtools только в разработке:
+Подключайте devtools только в режиме разработки:
 
 ```typescript
-// Node.js/Webpack
+// Node.js / Webpack
 if (process.env.NODE_ENV !== 'production') {
-  DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+    DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
 }
 
 // Vite
 if (import.meta.env.DEV) {
-  DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+    DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+}
+
+// Next.js
+if (process.env.NODE_ENV === 'development') {
+    DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
 }
 ```
 
@@ -74,22 +144,85 @@ if (import.meta.env.DEV) {
 
 ```typescript
 if (typeof window !== 'undefined' && process.env.NODE_ENV !== 'production') {
-  DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+    DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
 }
 ```
 
 ### Несколько инструментов
 
-Можно комбинировать несколько devtools:
+Можно комбинировать несколько devtools с помощью `combineDevtools`:
 
 ```typescript
-import { combineDevtools, reduxDevtools } from '@fozy-labs/rx-toolkit';
+import { combineDevtools, reduxDevtools, DefaultOptions } from '@fozy-labs/rx-toolkit';
 import { createDevtools } from '@reatom/devtools';
 
 DefaultOptions.update({
-  DEVTOOLS: combineDevtools(
-    reduxDevtools({ name: 'MyApp' }),
-    createDevtools({ initVisibility: true })
-  )
+    DEVTOOLS: combineDevtools(
+        reduxDevtools({ name: 'MyApp' }),
+        createDevtools({ initVisibility: true })
+    )
 });
 ```
+
+### Именование для devtools
+
+При создании сигналов и запросов можно указывать имена для удобной отладки:
+
+```typescript
+// Сигналы
+const count$ = new Signal(0, 'counter');
+const user$ = new Signal(null, { name: 'currentUser' });
+
+// Ресурсы и операции
+const userResource = createResource({
+    queryFn: fetchUser,
+    devtoolsName: 'user-resource', // Имя в devtools
+});
+
+const updateUser = createOperation({
+    queryFn: updateUserApi,
+    devtoolsName: 'update-user',
+});
+
+// Отключение devtools для конкретного сигнала
+const internalSignal = new Signal(0, { isDisabled: true });
+
+// Отключение devtools для ресурса
+const internalResource = createResource({
+    queryFn: fetchInternal,
+    devtoolsName: false, // Не отслеживать
+});
+```
+
+---
+
+## DevtoolsLike интерфейс
+
+Если вам нужно создать кастомную интеграцию с devtools:
+
+```typescript
+interface DevtoolsLike {
+    state<T>(name: string, initState: T): DevtoolsStateLike<T>;
+}
+
+interface DevtoolsStateLike<T = any> {
+    (newState: T): void;
+}
+```
+
+**Пример кастомного devtools:**
+
+```typescript
+const customDevtools: DevtoolsLike = {
+    state(name, initState) {
+        console.log(`[INIT] ${name}:`, initState);
+        
+        return (newState) => {
+            console.log(`[UPDATE] ${name}:`, newState);
+        };
+    }
+};
+
+DefaultOptions.update({ DEVTOOLS: customDevtools });
+```
+

package/docs/migrations/0.5.0.md

@@ -0,0 +1,73 @@
+# Миграция с версии 0.4.x на 0.5.0
+
+### Сигналы больше не наследуются от Observable
+
+```typescript
+// Было
+signal.subscribe(fn); // ❌
+signal.pipe()         // ❌
+
+// Стало
+signal.obs.subscribe(fn); // ✅
+signal.obs.pipe()         // ✅
+```
+
+### Сигналы больше не поддерживают `value`, `getValue()` и `next()`
+
+```typescript
+// Было
+signal.value;      // ❌
+signal.getValue(); // ❌
+signal.next(val);  // ❌
+singal.value += 1; // ❌
+
+// Стало
+signal()         // ✅
+signal.get();    // ✅
+signal.set(val); // ✅
+```
+
+### Computed, на который нет подписок, пересчитывается при каждом обращении.
+
+```typescripttypescript
+// Было
+const comp$ = new Computed(() => myHeavyCalc(singal.value)); // ✅ пересчитывается
+comp$.get();                // ✅ берется из кеша
+comp.subscribe(() => {});   // ✅ берется из кеша
+comp$.get();                // ✅ берется из кеша
+
+// Стало
+const comp$ = Signal.compute(() => myHeavyCalc(singal())); // ✅ ждет
+comp$.get();                // ✅ пересчитывается
+comp$.subscribe(() => {});  // ✅ пересчитывается
+comp$.get();                // ✅ берется из кеша
+```
+
+### Нет необходимости вызывать `complete()` для Signal и Computed
+
+```typescript
+// Было
+const signal = new Signal(0);
+// Что-то делаем
+signal.complete();   // ❌
+
+// Стало
+const signal = Signal.create(0);
+// Что-то делаем
+// Ничего не нужно вызывать  ✅
+```
+
+### Новый функциональный API для создания сигналов (рекомендуется)
+
+```typescript
+// Было
+const signal = new Signal(0);
+const computed = new Computed(() => signal.value * 2);
+signal.value += 1; // ❌
+
+
+// Стало
+const signal = Signal.create(0);
+const computed = Signal.compute(() => signal() * 2);
+signal.set(signal.peek() + 1); // ✅
+```

package/docs/options/README.md

@@ -0,0 +1,89 @@
+# Глобальные настройки
+
+RxToolkit предоставляет `DefaultOptions` для настройки глобального поведения библиотеки. Все настройки опциональны и применяются ко всему приложению.
+
+## API
+
+### DefaultOptions.update()
+
+Обновляет глобальные настройки библиотеки.
+
+```typescript
+import { DefaultOptions } from '@fozy-labs/rx-toolkit';
+
+DefaultOptions.update({
+    DEVTOOLS: reduxDevtools(),
+    onQueryError: (error) => console.error(error),
+    getScopeName: () => MyScopeLibarary.getCurrentScopeName(),
+});
+```
+
+## Параметры
+
+### DEVTOOLS
+
+**См.** [Документация Devtools](../devtools/README.md)
+
+---
+
+### onQueryError
+
+**Тип:** `(error: unknown) => void | null`  
+**По умолчанию:** `null`
+
+Глобальный обработчик ошибок для всех запросов (Resources и Operations). Вызывается при каждой ошибке запроса.
+
+```typescript
+import { DefaultOptions } from '@fozy-labs/rx-toolkit';
+import * as Sentry from '@sentry/browser';
+
+DefaultOptions.update({
+    onQueryError: (error) => {
+        // Логирование
+        console.error('[RxToolkit Query Error]', error);
+        
+        // Отправка в систему мониторинга
+        Sentry.captureException(error, {
+            tags: { source: 'rx-toolkit-query' }
+        });
+        
+        // Уведомление пользователя
+        if (error instanceof NetworkError) {
+            toast.error('Проблема с сетью. Попробуйте позже.');
+        } else if (error instanceof AuthError) {
+            redirectToLogin();
+        }
+    }
+});
+```
+
+---
+
+### getScopeName
+
+**Тип:** `(() => string | null) | null`  
+**По умолчанию:** `null`
+
+Функция для получения имени текущего scope. Полезно для SSR, изоляции данных между запросами или многопользовательских приложений.
+
+```typescript
+import { DefaultOptions } from '@fozy-labs/rx-toolkit';
+
+// SSR: изоляция данных между запросами
+let currentRequestId: string | null = null;
+
+DefaultOptions.update({
+    getScopeName: () => currentRequestId
+});
+
+// В middleware сервера
+app.use((req, res, next) => {
+    currentRequestId = req.id;
+    res.on('finish', () => {
+        currentRequestId = null;
+    });
+    next();
+});
+```
+
+---