@fozy-labs/rx-toolkit 0.4.1 → 0.4.2

package/dist/query/types/Operation.types.d.ts

@@ -1,4 +1,4 @@
-import { ReadableSignalLike } from "../../signal";
+import { ReadableSignalLike } from "../../signals";
 import { FallbackOnNever } from "../../query/types/shared.types";
 import { ResourceDefinition, ResourceInstance } from "./Resource.types";
 /**
@@ -20,21 +20,62 @@ export type OperationCreateOptions<D extends OperationDefinition> = {
  * Настройки связи операции с ресурсом
  */
 export type LinkOptions<D extends OperationDefinition, RD extends ResourceDefinition> = {
+    /**
+     * Целевой ресурс, с которым связывается операция
+     * @required
+     */
     resource: ResourceInstance<RD>;
+    /**
+     * Функция для получения аргументов ресурса из аргументов операции.
+     * Используется для определения какой именно элемент в кэше ресурса нужно обновить
+     * @required
+     */
     forwardArgs: (args: D["Args"]) => RD["Args"];
+    /**
+     * Флаг для инвалидации (очистки) кэша ресурса после выполнения операции.
+     * При true - кэш будет очищен и ресурс будет перезагружен при следующем обращении
+     * @optional @default false
+     */
     invalidate?: boolean;
+    /**
+     * Флаг для блокировки ресурса во время выполнения операции.
+     * При true - ресурс будет заблокирован и не сможет выполнять новые запросы
+     * @optional @default false
+     */
     lock?: boolean;
+    /**
+     * Функция для обновления кэша ресурса после успешного выполнения операции.
+     * Получает draft объект для мутации, аргументы операции и результат операции
+     * @optional
+     */
     update?: (tools: {
+        /** Immer draft объект для мутации кэша ресурса */
         draft: RD["Data"];
+        /** Аргументы, с которыми была вызвана операция */
         args: D["Args"];
+        /** Результат выполнения операции */
         data: D["Data"];
     }) => void | RD["Data"] | Promise<RD["Data"]>;
+    /**
+     * Функция для оптимистичного обновления кэша ресурса ДО выполнения операции.
+     * Позволяет обновить UI немедленно, до получения ответа от сервера
+     * @optional
+     */
     optimisticUpdate?: (tools: {
+        /** Immer draft объект для мутации кэша ресурса */
         draft: RD["Data"];
+        /** Аргументы, с которыми была вызвана операция */
         args: D["Args"];
-    }) => void | RD["Data"] | Promise<D["Data"]>;
+    }) => void | RD["Data"] | Promise<RD["Data"]>;
+    /**
+     * Функция для создания нового элемента в кэше ресурса.
+     * Используется когда операция создает новую сущность, которую нужно добавить в кэш
+     * @optional
+     */
     create?: (tools: {
+        /** Аргументы, с которыми была вызвана операция */
         args: D["Args"];
+        /** Результат выполнения операции */
         data: D["Data"];
     }) => RD["Data"] | Promise<RD["Data"]>;
 };

package/dist/query/types/Resource.types.d.ts

@@ -1,5 +1,6 @@
-import { ReadableSignalLike } from "../../signal";
+import { ReadableSignalLike } from "../../signals";
 import { FallbackOnNever } from "../../query/types/shared.types";
+import { Patch as ImmerPatch } from "immer";
 /**
  * Функция создания ресурса
  */
@@ -72,6 +73,16 @@ export type ResourceQueryState<D extends ResourceDefinition> = {
     /** Аргументы запроса */
     args: D["Args"] | undefined;
 };
+/**
+ * Транзакция ресурса
+ */
+export type ResourceTransaction = {
+    patches: ImmerPatch[];
+    inversePatches: ImmerPatch[];
+    status: 'pending' | 'committed' | 'aborted';
+    abort(): void;
+    commit(): void;
+};
 /**
  * Эте не ссылка в "классическом" понимании, а абстракция
  * для работы с элементом кеша ресурса.
@@ -82,9 +93,13 @@ export type ResourceRefInstanse<D extends ResourceDefinition> = {
         unlock: () => void;
     };
     unlockOne(): void;
+    /**
+     * @deprecated
+     */
     update(updateFn: (data: D['Data']) => D['Data']): {
         rollback: () => void;
     };
+    patch(patchFn: (data: D['Data']) => void): ResourceTransaction | null;
     invalidate(): void;
     create(data: D['Data']): void;
 };

package/dist/query/types/devtools.d.ts

@@ -0,0 +1,6 @@
+export interface DevtoolsStateLike<T = any> {
+    (newState: T): void;
+}
+export interface DevtoolsLike {
+    state<T>(name: string, initState: T): DevtoolsStateLike<T>;
+}

package/dist/react-hooks/useSignal.d.ts

@@ -1,2 +1,2 @@
-import type { ReadableSignalLike } from "../signal/base/types";
+import { ReadableSignalLike } from "../signals";
 export declare function useSignal<T>(signal$: ReadableSignalLike<T>): T;

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

@@ -0,0 +1,6 @@
+export declare const Batcher: {
+    scheduler(rang: number): {
+        schedule: (fn: () => void) => void;
+    };
+    batch<T>(fn: () => T): T;
+};

package/dist/signals/base/Batcher.js

@@ -0,0 +1,55 @@
+const Scheduled = {
+    map: new Map(),
+    lowestRang: -1,
+    isLocked: false,
+    set(rang, fn) {
+        if (rang < this.lowestRang)
+            this.lowestRang = rang;
+        if (!this.map.has(rang)) {
+            this.map.set(rang, new Set());
+        }
+        this.map.get(rang).add(fn);
+    },
+    done() {
+        this.lowestRang = -1;
+        this.map.clear();
+    },
+    handleInfinity() {
+        const fns = this.map.get(Infinity);
+        this.map.delete(Infinity);
+        fns?.forEach((fn) => fn());
+        this.done();
+    },
+    run() {
+        if (this.map.size === 1 && this.map.has(Infinity))
+            return this.handleInfinity();
+        if (this.map.size === 0)
+            return this.done();
+        const iterationRang = this.lowestRang;
+        this.lowestRang += 1;
+        const fns = this.map.get(iterationRang);
+        this.map.delete(iterationRang);
+        fns?.forEach((fn) => fn());
+        this.run();
+    },
+};
+export const Batcher = {
+    scheduler(rang) {
+        return {
+            schedule: (fn) => {
+                if (!Scheduled.isLocked)
+                    return fn();
+                Scheduled.set(rang, fn);
+            }
+        };
+    },
+    batch(fn) {
+        if (Scheduled.isLocked)
+            return fn();
+        Scheduled.isLocked = true;
+        const v = fn();
+        Scheduled.run();
+        Scheduled.isLocked = false;
+        return v;
+    },
+};

package/dist/{signal → signals}/base/Computed.d.ts

@@ -1,10 +1,13 @@
 import { SubscriptionLike } from "rxjs";
-import { ReadableSignalLike } from "../../signal/base/types";
+import { ReadableSignalLike } from "./types";
 import { Signal } from "./Signal";
 export declare class Computed<T> extends Signal<T> implements SubscriptionLike, ReadableSignalLike<T> {
     private static _EMPTY;
     private _effect;
-    constructor(computeFn: () => T, doLog?: boolean);
+    constructor(computeFn: () => T, options?: {
+        disableDevtools?: boolean;
+        devtoolsName?: string;
+    });
     unsubscribe(): void;
     complete(): void;
 }

package/dist/{signal → signals}/base/Computed.js

@@ -3,16 +3,20 @@ import { Effect } from "./Effect";
 export class Computed extends Signal {
     static _EMPTY = Symbol('empty');
     _effect;
-    constructor(computeFn, doLog = false) {
+    constructor(computeFn, options) {
         let initialValue = Computed._EMPTY;
         const effect = new Effect(() => {
             if (initialValue === Computed._EMPTY) {
                 initialValue = computeFn();
                 return;
             }
+            this._rang = effect._rang;
             this.value = computeFn();
-        }, doLog);
-        super(initialValue);
+        });
+        super(initialValue, {
+            devtoolsName: 'Computed',
+            ...options,
+        });
         this._effect = effect;
     }
     unsubscribe() {

package/dist/{signal → signals}/base/Effect.d.ts

@@ -1,9 +1,9 @@
 import { SubscriptionLike } from "rxjs";
 export declare class Effect implements SubscriptionLike {
-    private _doLog;
-    closed: boolean;
     private _subscriptions;
-    constructor(effectFn: (runInTrackedContext: (fn: () => void) => void) => void, _doLog?: boolean);
+    closed: boolean;
+    _rang: number;
+    constructor(effectFn: (ctx: (fn: () => void) => void) => void);
     /**
      * Выполняет функцию в tracked-контексте, подписываясь на Tracker.
      */

package/dist/signals/base/Effect.js

@@ -0,0 +1,51 @@
+import { Batcher } from "./Batcher";
+import { Tracker } from "./Tracker";
+export class Effect {
+    _subscriptions = [];
+    closed = false;
+    _rang = 0;
+    constructor(effectFn) {
+        this._runInTrackedContext(effectFn, false);
+    }
+    /**
+     * Выполняет функцию в tracked-контексте, подписываясь на Tracker.
+     */
+    _runInTrackedContext(effectFn, isAsyncRun = false) {
+        // Отписываемся от предыдущих подписок
+        if (!isAsyncRun) {
+            this._rang = 0;
+            this._subscriptions.forEach((sub) => sub.unsubscribe());
+            this._subscriptions = [];
+        }
+        let isTrackedContext = true;
+        // TODO подумать как организовать планировщик при асинхронном запуске
+        let scheduler;
+        const scheduledFn = () => {
+            this._runInTrackedContext(effectFn);
+        };
+        // Подписываемся на Tracker. Во время выполнения подпишемся на все tracked наблюдатели.
+        const trackerSub = Tracker.tracked$.subscribe((tracked) => {
+            if (!isTrackedContext)
+                return;
+            if (tracked.rang <= this._rang) {
+                this._rang = tracked.rang + 1;
+            }
+            this._subscriptions.push(tracked.obsv$.subscribe(() => {
+                if (isTrackedContext) {
+                    return;
+                }
+                scheduler.schedule(scheduledFn);
+            }));
+        });
+        effectFn((fn) => {
+            this._runInTrackedContext(fn, true);
+        });
+        trackerSub.unsubscribe();
+        isTrackedContext = false;
+        scheduler = Batcher.scheduler(this._rang);
+    }
+    unsubscribe() {
+        this.closed = true;
+        this._subscriptions.forEach((sub) => sub.unsubscribe());
+    }
+}

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

@@ -0,0 +1,4 @@
+export declare const Indexer: {
+    currentIndex: number;
+    getIndex(): number;
+};

package/dist/signals/base/Indexer.js

@@ -0,0 +1,6 @@
+export const Indexer = {
+    currentIndex: 0,
+    getIndex() {
+        return this.currentIndex++;
+    }
+};

package/dist/{signal → signals}/base/ReadonlySignal.d.ts

@@ -2,6 +2,8 @@ import { Observable, Subscriber, TeardownLogic } from "rxjs";
 import { SyncObservable } from "./SyncObservable";
 import type { ReadableSignalLike } from "./types";
 export declare class ReadonlySignal<T> extends SyncObservable<T> implements ReadableSignalLike<T> {
+    private readonly _devtools;
+    private static _logIdIndex;
     constructor(subscribe?: (this: Observable<T>, subscriber: Subscriber<T>) => TeardownLogic);
     get value(): T;
     peek(): T;

package/dist/signals/base/ReadonlySignal.js

@@ -0,0 +1,30 @@
+import { SharedOptions } from "../../query/core/SharedOptions";
+import { SyncObservable } from "./SyncObservable";
+import { Tracker } from "./Tracker";
+export class ReadonlySignal extends SyncObservable {
+    _devtools;
+    static _logIdIndex = 0;
+    constructor(subscribe) {
+        super(subscribe);
+        const stateDevtools = SharedOptions.DEVTOOLS?.state;
+        if (stateDevtools) {
+            const id = ReadonlySignal._logIdIndex++;
+            const key = `ReadonlySignal:i=${id}`;
+            const initialValue = this.peek();
+            this._devtools = stateDevtools(key, initialValue);
+        }
+    }
+    get value() {
+        Tracker.next_legacy(this);
+        return super.value;
+    }
+    peek() {
+        return super.value;
+    }
+    /**
+     * @deprecated
+     */
+    get() {
+        return this.value;
+    }
+}

package/dist/{signal → signals}/base/Signal.d.ts

@@ -1,7 +1,13 @@
 import { BehaviorSubject, Observable } from "rxjs";
 import { type ReadableSignalLike, UnaryFunction } from "./types";
+type SignalOptions = {
+    disableDevtools?: boolean;
+    devtoolsName?: string;
+};
 export declare class Signal<T> extends BehaviorSubject<T> implements ReadableSignalLike<T> {
-    constructor(initialValue: T);
+    private readonly _devtools;
+    protected _rang: number;
+    constructor(initialValue: T, options?: SignalOptions);
     protected _onChange(value: T): void;
     get value(): T;
     set value(value: T);
@@ -11,6 +17,10 @@ export declare class Signal<T> extends BehaviorSubject<T> implements ReadableSig
      * @deprecated use `value` instead.
      */
     get(): T;
+    /**
+     * @deprecated use `peek()` instead.
+     */
+    getValue(): T;
     /**
      * @deprecated use `next(value)` instead.
      */
@@ -28,3 +38,4 @@ export declare class Signal<T> extends BehaviorSubject<T> implements ReadableSig
     pipe<A extends Observable<any>, B extends Observable<any>, C extends Observable<any>, D extends Observable<any>, E extends Observable<any>, F extends Observable<any>, G extends Observable<any>, H extends Observable<any>, I extends Observable<any>>(op1: UnaryFunction<Signal<T>, A>, op2: UnaryFunction<A, B>, op3: UnaryFunction<B, C>, op4: UnaryFunction<C, D>, op5: UnaryFunction<D, E>, op6: UnaryFunction<E, F>, op7: UnaryFunction<F, G>, op8: UnaryFunction<G, H>, op9: UnaryFunction<H, I>, ...operations: UnaryFunction<Observable<any>, Observable<any>>[]): Observable<unknown>;
     asReadonly(): ReadableSignalLike<T>;
 }
+export {};

package/dist/{signal → signals}/base/Signal.js

@@ -1,14 +1,28 @@
+import { SharedOptions } from "../../query/core/SharedOptions";
 import { BehaviorSubject } from "rxjs";
+import { Batcher } from "./Batcher";
+import { Indexer } from "./Indexer";
 import { Tracker } from "./Tracker";
 export class Signal extends BehaviorSubject {
-    constructor(initialValue) {
+    _devtools;
+    _rang = 0;
+    constructor(initialValue, options) {
         super(initialValue);
+        const stateDevtools = SharedOptions.DEVTOOLS?.state;
+        if (stateDevtools && options?.disableDevtools !== true) {
+            const id = Indexer.getIndex();
+            const key = `${options?.devtoolsName || 'Signal'}:i=${id}`;
+            this._devtools = stateDevtools(key, initialValue);
+        }
     }
     _onChange(value) {
-        super.next(value);
+        Batcher.batch(() => {
+            this._devtools?.(value);
+            super.next(value);
+        });
     }
     get value() {
-        Tracker.next(this);
+        Tracker.next(this._rang, this);
         return super.value;
     }
     set value(value) {
@@ -26,6 +40,12 @@ export class Signal extends BehaviorSubject {
     get() {
         return this.value;
     }
+    /**
+     * @deprecated use `peek()` instead.
+     */
+    getValue() {
+        return super.getValue();
+    }
     /**
      * @deprecated use `next(value)` instead.
      */

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

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

package/dist/signals/base/Tracker.js

@@ -0,0 +1,13 @@
+import { Subject } from "rxjs";
+export const Tracker = {
+    /** @deprecated */
+    tracked_legacy$: new Subject(),
+    /** @deprecated */
+    next_legacy(value) {
+        Tracker.tracked_legacy$.next(value);
+    },
+    tracked$: new Subject(),
+    next(rang, observable) {
+        Tracker.tracked$.next({ rang, obsv$: observable, });
+    }
+};

package/dist/{signal → signals}/base/types.d.ts

@@ -12,4 +12,3 @@ export interface UnaryFunction<T, R> {
 }
 export type SignalOperatorFn<T, R> = UnaryFunction<ReadableSignalLike<T>, ReadableSignalLike<R>>;
 export type MonoTypeSignalOperatorFn<T> = SignalOperatorFn<T, T>;
-export type ObservableToSignalFn<T> = UnaryFunction<Observable<T>, ReadableSignalLike<T>>;

package/dist/signals/base/types.js

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

package/dist/{signal → signals}/extends/LocalSignal.d.ts

@@ -1,6 +1,6 @@
 import { ZodType } from "zod/v4";
 import { Observable } from "rxjs";
-import { Computed } from "../../signal/base";
+import { Computed } from "../base";
 type Options<T> = {
     zodSchema?: ZodType<T>;
     key: string;

package/dist/{signal → signals}/extends/LocalSignal.js

@@ -1,6 +1,6 @@
-import { signalize } from "../../signal/operators";
 import { z } from "zod/v4";
-import { Computed } from "../../signal/base";
+import { Computed } from "../base";
+import { signalize } from "../operators";
 const NullOrString = z.string().nullable();
 const NONE = Symbol('NONE');
 export class LocalSignal extends Computed {
@@ -56,7 +56,7 @@ export class LocalSignal extends Computed {
                 return checkEffect(value) ? value : defaultValue;
             }
             return value;
-        });
+        }, { devtoolsName: 'LocalSignal' });
         this._options = _options;
     }
     _onChange(value) {

package/dist/{signal → signals}/operators/filterUpdates.js

@@ -1,5 +1,5 @@
 import { createOperatorSubscriber } from "rxjs/internal/operators/OperatorSubscriber";
-import { ReadonlySignal } from "../../signal/base/ReadonlySignal";
+import { ReadonlySignal } from "../base";
 export function filterUpdates(predicate, thisArg) {
     return (source) => new ReadonlySignal((destination) => {
         let index = 0;

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

@@ -0,0 +1,3 @@
+export * from './filterUpdates';
+export * from './mapSignals';
+export * from './signalize';

package/dist/signals/operators/index.js

@@ -0,0 +1,3 @@
+export * from './filterUpdates';
+export * from './mapSignals';
+export * from './signalize';

package/dist/{signal → signals}/operators/mapSignals.js

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

package/dist/{signal → signals}/operators/signalize.d.ts

@@ -1,3 +1,3 @@
 import { Observable } from "rxjs";
-import { ReadonlySignal } from "../../signal/base";
+import { ReadonlySignal } from "../base";
 export declare function signalize<T>(observable: Observable<T>): ReadonlySignal<T>;

package/dist/{signal → signals}/operators/signalize.js

@@ -1,4 +1,4 @@
-import { ReadonlySignal } from "../../signal/base";
+import { ReadonlySignal } from "../base";
 export function signalize(observable) {
     return new ReadonlySignal((destination) => {
         return observable.subscribe(destination);

package/docs/devtools/README.md

@@ -0,0 +1,95 @@
+# Devtools
+
+RxToolkit предоставляет интеграцию с популярными инструментами разработчика для отладки реактивных приложений в реальном времени. Вы можете отслеживать изменения сигналов, выполнение операций и состояние ресурсов, анализировать граф зависимостей и исследовать поведение реактивной системы.
+
+**Отслеживает изменения состояния:**
+- Сигналов (Signal/Computed)
+- Ресурсов и операций (Resource/Operation)
+
+## Redux DevTools
+
+Популярное браузерное расширение для отладки состояния приложений. **RxToolkit включает встроенный адаптер `reduxDevtools()`**.
+
+**Установка:**
+1. Установите [расширение](https://github.com/reduxjs/redux-devtools) для браузера
+2. Подключите в коде:
+
+```typescript
+import { DefaultOptions, reduxDevtools } from '@fozy-labs/rx-toolkit';
+
+DefaultOptions.update({ 
+  DEVTOOLS: reduxDevtools() 
+});
+```
+
+## @reatom/devtools
+
+Npm пакет, содержащий отладчик, работающий прямо в браузере.
+Совместим по API с `rx-toolkit`.
+После подключения в углу страницы появляется кнопка,
+которая открывает панель инструментов.
+
+**Установка:**
+```bash
+npm install @reatom/devtools
+```
+
+**Подключение:**
+```typescript
+import { DefaultOptions } from '@fozy-labs/rx-toolkit';
+import { createDevtools } from '@reatom/devtools';
+
+DefaultOptions.update({
+  DEVTOOLS: createDevtools({ 
+    initVisibility: true 
+  })
+});
+```
+
+**Может пригодиться:**
+- Если в вашей среде не удобно или проблематично установить браузерное расширение.
+- Если вы уже работали с Reatom.
+
+## Практики
+
+### Development-режим
+
+Подключайте devtools только в разработке:
+
+```typescript
+// Node.js/Webpack
+if (process.env.NODE_ENV !== 'production') {
+  DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+}
+
+// Vite
+if (import.meta.env.DEV) {
+  DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+}
+```
+
+### SSR-совместимость
+
+Защитите от выполнения на сервере:
+
+```typescript
+if (typeof window !== 'undefined' && process.env.NODE_ENV !== 'production') {
+  DefaultOptions.update({ DEVTOOLS: reduxDevtools() });
+}
+```
+
+### Несколько инструментов
+
+Можно комбинировать несколько devtools:
+
+```typescript
+import { combineDevtools, reduxDevtools } from '@fozy-labs/rx-toolkit';
+import { createDevtools } from '@reatom/devtools';
+
+DefaultOptions.update({
+  DEVTOOLS: combineDevtools(
+    reduxDevtools({ name: 'MyApp' }),
+    createDevtools({ initVisibility: true })
+  )
+});
+```