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

package/docs/release/README.md

@@ -1,7 +1,59 @@
-```shell
- npm run ts-check 
- npm run build     
- npm version patch
- npm publish 
- git push origin develop --tag
+# Релиз
+
+Процесс выпуска новой версии RxToolkit.
+
+## Подготовка
+
+1. Убедитесь, что все изменения закоммичены
+2. Обновите CHANGELOG (если есть)
+3. Проверьте документацию
+
+## Команды релиза
+
+```bash
+# 1. Проверка типов
+npm run ts-check 
+
+# 2. Сборка проекта
+npm run build     
+
+# 3. Обновление версии
+npm version patch   # для патч-версии (0.4.18 -> 0.4.19)
+npm version minor   # для минорной версии (0.4.18 -> 0.5.0)
+npm version major   # для мажорной версии (0.4.18 -> 1.0.0)
+
+# 4. Публикация в npm
+npm publish 
+
+# 5. Пуш тегов в репозиторий
+git push origin develop --tags
+```
+
+## rc
+
+### Выпуск релиза-кандидата (RC)
+
+```bash
+# 1. Проверка типов
+npm run ts-check
+
+# 2. Сборка проекта
+npm run build
+
+# 3. Обновление версии до RC
+npm version prerelease --preid=rc
+# пример: 1.2.0 → 1.2.0-rc.0
+
+# 4. Публикация RC (НЕ latest!)
+npm publish --tag rc
+
+# 5. Пуш тегов
+git push origin develop --tags
+```
+
+### Переход с RC на stable
+```bash
+npm version <latest_version>
+npm publish
+git push origin develop --tags
 ```

package/docs/signals/README.md

@@ -6,65 +6,160 @@ RxSignals — это реактивная система управления с
 
 ### Signal
 
-Базовый класс для создания реактивных сигналов.
+Базовый класс для создания реактивных сигналов с изменяемым состоянием.
 
 **Пример использования:**
 
 ```typescript
+import { Signal } from '@fozy-labs/rx-toolkit';
+
 const name = new Signal('John');
 const age = new Signal(25);
 
-// Подписка на изменения
-const subscription = name.subscribe(newName => {
-  console.log(`Name changed to: ${newName}`);
-}); // Выведет: "Name changed to: John" при инициализации
+// Чтение значения (с отслеживанием зависимостей)
+console.log(name.get()); // "John"
 
-name.value = 'Jane'; // Выведет: "Name changed to: Jane"
+// Чтение значения без отслеживания
+console.log(name.peek()); // "John"
+
+// Запись нового значения
+name.set('Jane');
+
+// Подписка на изменения через RxJS Observable
+const subscription = name.obs.subscribe(newName => {
+  console.log(`Name changed to: ${newName}`);
+});
 
 // Отписка
 subscription.unsubscribe();
 ```
 
+**API Signal:**
+- `get()` — получить значение и зарегистрировать зависимость (для использования внутри Computed/Effect)
+- `peek()` — получить значение без регистрации зависимости
+- `set(value)` — установить новое значение
+- `obs` — RxJS Observable для подписки на изменения
+
 ### Computed
 
 Создает вычисляемое значение, которое автоматически обновляется при изменении зависимостей.
 
 ```typescript
+import { Signal, Computed } from '@fozy-labs/rx-toolkit';
+
 const firstName = new Signal('John');
 const lastName = new Signal('Doe');
 
-const fullName = new Computed(() => `${firstName.value} ${lastName.value}`);
+const fullName = new Computed(() => `${firstName.get()} ${lastName.get()}`);
 
-console.log(fullName.value); // "John Doe"
+console.log(fullName.get()); // "John Doe"
 
-firstName.value = 'Jane';
-console.log(fullName.value); // "Jane Doe"
+firstName.set('Jane');
+console.log(fullName.get()); // "Jane Doe"
+
+// Подписка на изменения
+fullName.obs.subscribe(name => console.log(name));
 ```
 
+**API Computed:**
+- `get()` — получить вычисленное значение с регистрацией зависимости
+- `peek()` — получить значение без регистрации зависимости
+- `obs` — RxJS Observable для подписки на изменения
+
 ### Effect
 
-Создает эффект, который выполняется при изменении используемых сигналов.
+Создает побочный эффект, который автоматически выполняется при изменении используемых сигналов.
 
 ```typescript
+import { Signal, Effect } from '@fozy-labs/rx-toolkit';
+
 const count = new Signal(0);
 const message = new Signal('Hello');
 
-const sub = new Effect(() => {
-    // Выведет: "Hello: 0" при инициализации
-  console.log(`${message.value}: ${count.value}`);
+const effect = new Effect(() => {
+  // Выведет: "Hello: 0" при инициализации
+  console.log(`${message.get()}: ${count.get()}`);
 });
 
-count.value = 1; // Выведет: "Hello: 1"
-message.value = 'Hi'; // Выведет: "Hi: 1"
+count.set(1); // Выведет: "Hello: 1"
+message.set('Hi'); // Выведет: "Hi: 1"
 
 // Остановка эффекта
-sub.unsubscribe();
+effect.unsubscribe();
+```
+
+**Cleanup функция (teardown):**
+
+Effect поддерживает возврат функции очистки, которая вызывается перед следующим выполнением или при отписке:
+
+```typescript
+const effect = new Effect(() => {
+  const timer = setInterval(() => console.log(count.get()), 1000);
+  
+  // Cleanup - вызывается перед повторным выполнением эффекта
+  return () => {
+    clearInterval(timer);
+  };
+});
+```
+
+## Функциональный стиль API
+
+Для более компактного синтаксиса доступны статические методы `Signal.create()`, `Signal.compute()` и `Signal.effect()`:
+
+```typescript
+import { Signal } from '@fozy-labs/rx-toolkit';
+
+class CounterStore {
+    // Создание сигнала в функциональном стиле (вызывается как функция)
+    count$ = Signal.create(0);
+    
+    // Computed в функциональном стиле
+    doubled$ = Signal.compute(() => this.count$() * 2);
+    squared$ = Signal.compute(() => (this.doubled$() / 2) ** 2);
+
+    increment = () => this.count$.set(this.count$.peek() + 1);
+    decrement = () => this.count$.set(this.count$.peek() - 1);
+    reset = () => this.count$.set(0);
+}
+
+const store = new CounterStore();
+
+// Чтение значения - вызов как функции
+console.log(store.count$()); // 0
+console.log(store.doubled$()); // 0
+
+store.increment();
+console.log(store.count$()); // 1
+console.log(store.doubled$()); // 2
+console.log(store.squared$()); // 1
+```
+
+**API функциональных сигналов:**
+- `signal$()` — вызов как функции возвращает значение (аналог `get()`)
+- `signal$.peek()` — получить значение без отслеживания
+- `signal$.set(value)` — установить значение
+- `signal$.obs` — RxJS Observable
+
+### ReadonlySignal
+
+Базовый класс для сигналов только для чтения. Используется внутри `signalize` и для создания кастомных сигналов.
+
+```typescript
+import { ReadonlySignal } from '@fozy-labs/rx-toolkit';
+
+const customSignal = new ReadonlySignal((subscriber) => {
+    // Логика подписки
+    subscriber.next(initialValue);
+    return () => {
+        // Cleanup
+    };
+});
 ```
 
 ### LocalSignal
 
-Сигнал, который синхронизируется с локальным хранилищем (localStorage).
-// TODO убрать zod из core, добавить возможность передавать "driver".
+Сигнал, который автоматически синхронизируется с `localStorage`.
 
 ```typescript
 import { z } from 'zod/v4';
@@ -77,25 +172,33 @@ enum FILTER {
     MEETINGS = 'meetings',
 }
 
-const selectedFilter$ = new LocalSignal({
+const selectedFilter$ = LocalSignal.create({
     key: 'memberships-list-selected-filter',
     defaultValue: FILTER.ALL,
-    zodSchema: z.enum(FILTER),
+    zodSchema: z.nativeEnum(FILTER), // Опционально: валидация через Zod
 });
-```
 
-## Operators (Операторы)
+// Использование
+console.log(selectedFilter$.peek()); // Значение из localStorage или FILTER.ALL
+selectedFilter$.set(FILTER.CHANNELS); // Сохраняется в localStorage
+```
 
-### mapSignals
-// TODO: добавить описание
+**Опции LocalSignal:**
+- `key` — ключ для localStorage
+- `defaultValue` — значение по умолчанию
+- `zodSchema` — опциональная Zod-схема для валидации
+- `userId` — опциональный идентификатор пользователя для изоляции данных
+- `checkEffect` — функция валидации значения
+- `devtoolsOptions` — настройки для devtools
 
+## Операторы
 
 ### signalize
 
-Преобразует Observable в Signal.
+Преобразует RxJS Observable в Signal. Позволяет использовать любой Observable как реактивный сигнал.
 
 ```typescript
-import { interval } from 'rxjs';
+import { interval, startWith } from 'rxjs';
 import { signalize, Effect } from '@fozy-labs/rx-toolkit';
 
 // Создаем Observable, который эмитит значение каждую секунду
@@ -106,17 +209,87 @@ const timer$ = interval(1000).pipe(
 // Преобразуем Observable в Signal
 const tick$ = signalize(timer$);
 
-// Теперь можно использовать timerSignal как обычный Signal
+// Теперь можно использовать tick$ как обычный Signal
 new Effect(() => {
-    console.log(`Timer: ${tick$.value}`);
-})
+    console.log(`Timer: ${tick$.get()}`);
+});
+
+// Доступ к значению без подписки
+console.log(tick$.peek());
+```
+
+## Батчинг обновлений (Batcher)
+
+RxSignals автоматически группирует множественные обновления сигналов в один цикл обновления. Это обеспечивает:
+- Консистентность состояния
+- Оптимальную производительность
+- Предсказуемый порядок выполнения эффектов
+
+```typescript
+const a = Signal.create(1);
+const b = Signal.create((2);
+const sum = Signal.compute(() => a() + b());
+
+new Effect(() => {
+    console.log(`Sum: ${sum()}`);
+});
+
+// Оба изменения обрабатываются в одном батче
+Batcher.run(() => {
+    a.set(10);
+    b.set(20);
+});
+// Effect выведет: "Sum: 30" (один раз, а не два)
+```
+
+## Интеграция с RxJS
+
+Сигналы полностью совместимы с RxJS. Каждый сигнал предоставляет `obs` — стандартный RxJS Observable:
+
+```typescript
+import { filter, take, debounceTime } from 'rxjs';
+import { Signal, Computed, signalize } from '@fozy-labs/rx-toolkit';
+
+const clicks = Signal.create(0);
+
+// Используем RxJS операторы
+const tenClicks$ = clicks.obs.pipe(
+    filter(value => value === 10),
+    take(1)
+);
+
+tenClicks$.subscribe(() => {
+    console.log('Reached 10 clicks!');
+});
+
+// Или наоборот - превращаем Observable в Signal
+const debouncedClicks$ = signalize(
+    clicks.obs.pipe(
+        debounceTime(300)
+    )
+);
+
+// Теперь debouncedClicks$ можно использовать в Computed/Effect
+const doubled = Signal.compute(() => debouncedClicks$() * 2);
 ```
 
-### filterUpdates
+## Devtools
+
+Сигналы поддерживают интеграцию с Redux DevTools для отладки:
+
+```typescript
+import { Signal } from '@fozy-labs/rx-toolkit';
+
+// С именем для devtools
+const count$ = Signal.create(0, 'counter');
 
-Фильтрует обновления сигнала.
-// TODO: добавить пример использования, подумать над целесообразностью
+// Или с расширенными опциями
+const user$ = Signal.create(null, {
+    isDisabled: false, // Отключить отслеживание в devtools
+});
+```
 
-## React Integration
+## React интеграция
 
 См. [React интеграция](../usage/react/README.md) для подробной информации о том, как использовать RxSignals в React приложениях.
+