@fozy-labs/rx-toolkit 0.5.3-rc.1 → 0.5.3

package/dist/signals/signals/Computed.js

@@ -1,7 +1,8 @@
-import { distinctUntilChanged, ReplaySubject, share, map, finalize } from "rxjs";
+import { distinctUntilChanged, finalize, map, ReplaySubject, share } from "rxjs";
+import { normalizeSignalOptions } from "../../signals/types";
 import { ComputeCache, DependencyTracker } from "../base";
 import { Effect } from "./Effect";
-import { Signal } from "./Signal";
+import { State } from "./State";
 export class Computed {
     _computeFn;
     _state$;
@@ -13,12 +14,19 @@ export class Computed {
     _computeCache = new ComputeCache();
     constructor(_computeFn, options) {
         this._computeFn = _computeFn;
-        const lsOptions = {
-            base: Computed.name,
-            ...(typeof options === 'string' ? { name: options } : options),
-            _skipValues: [Computed._EMPTY],
+        const opts = normalizeSignalOptions(options);
+        const stateOptions = {
+            key: opts.key,
+            name: opts.name,
+            base: opts.base ?? Computed.name,
+            isDisabled: opts.isDisabled,
+            beforeDevtoolsPush: (value, push) => {
+                if (value !== Computed._EMPTY) {
+                    push(value);
+                }
+            },
         };
-        this._state$ = Signal.state(Computed._EMPTY, lsOptions);
+        this._state$ = State.create(Computed._EMPTY, stateOptions);
         this.obs = this._state$.obs.pipe(map((value) => {
             if (value === Computed._EMPTY) {
                 return this._start();
@@ -36,7 +44,7 @@ export class Computed {
         DependencyTracker.track({
             getRang: () => {
                 if (!this._effect) {
-                    throw new Error('Effect in not started. Possibly maximum call stack size exceeded.');
+                    throw new Error("Effect in not started. Possibly maximum call stack size exceeded.");
                 }
                 return this._effect._getRang();
             },
@@ -65,7 +73,7 @@ export class Computed {
         });
         this._computeCache.clear();
         if (initialValue === Computed._EMPTY) {
-            throw new Error('Computed value is not initialized');
+            throw new Error("Computed value is not initialized");
         }
         return initialValue;
     }
@@ -77,7 +85,7 @@ export class Computed {
         this._state$.set(Computed._EMPTY);
     }
     // === static ===
-    static _EMPTY = Symbol('empty');
+    static _EMPTY = Symbol("empty");
     static create(computeFn, options) {
         const lc = new Computed(computeFn, options);
         function computedFn() {

package/dist/signals/signals/Effect.js

@@ -15,6 +15,7 @@ export class Effect {
         this._rang = 0;
         const legacySubscriptions = this._subscriptions;
         this._subscriptions = new Map();
+        // eslint-disable-next-line prefer-const -- assigned after closure capture
         let scheduler;
         // Стабильная функция для планирования выполнения эффекта
         const scheduledFn = () => {
@@ -52,7 +53,7 @@ export class Effect {
         stopTracking();
         isTrackedContext = false;
         // Сохраняем teardown функцию, если она была возвращена
-        if (typeof optionalTeardown === 'function') {
+        if (typeof optionalTeardown === "function") {
             this._teardown = optionalTeardown;
         }
         scheduler = Batcher.scheduler(this._rang);

package/dist/signals/signals/LocalState.d.ts

@@ -0,0 +1,44 @@
+import { Observable } from "rxjs";
+import { ZodType } from "zod/v4";
+import { type SignalOptionsOrKey, type StatefulSignalFn } from "../../signals/types";
+type StorageLike = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+};
+type Options<T> = {
+    zodSchema?: ZodType<T>;
+    key: string;
+    userId?: string;
+    /**
+     * @deprecated use checkEffect instead
+     */
+    validator$?: Observable<(value: T) => boolean>;
+    checkEffect?: (value: T) => boolean;
+    driver?: StorageLike;
+    defaultValue: T;
+    devtoolsOptions?: SignalOptionsOrKey;
+};
+export declare class LocalState<T = string | null | number | undefined> {
+    private _state$;
+    private _computed;
+    private readonly _options;
+    readonly obs: Observable<T>;
+    private get _driver();
+    constructor(options: Options<T>);
+    set(value: T): void;
+    peek(): T;
+    get(): T;
+    clear(): void;
+    private _getStorageValue;
+    private _setStorageValue;
+    private _deleteStorageValue;
+    static KEY_PREFIX: string;
+    static DEFAULT_DRIVER: Storage;
+    static create<T = string | null | number | undefined>(options: Options<T>): StatefulSignalFn<T>;
+}
+/**
+ * @deprecated use LocalState instead
+ */
+export declare const LocalSignal: typeof LocalState;
+export {};

package/dist/signals/signals/{LocalSignal.js → LocalState.js}

@@ -1,15 +1,19 @@
 import { z } from "zod/v4";
 import { signalize } from "../operators";
 import { Computed } from "./Computed";
-import { State } from "@/signals/signals/State";
-const NONE = Symbol('NONE');
-export class LocalSignal {
+import { State } from "./State";
+const NONE = Symbol("NONE");
+export class LocalState {
     _state$;
     _computed;
     _options;
     obs;
+    get _driver() {
+        return this._options.driver || LocalState.DEFAULT_DRIVER;
+    }
     constructor(options) {
-        let initialValue = LocalSignal._getStorageValue(options);
+        this._options = options;
+        let initialValue = this._getStorageValue(options);
         if (initialValue === NONE) {
             initialValue = options.defaultValue;
         }
@@ -29,10 +33,9 @@ export class LocalSignal {
             return value;
         }, options.devtoolsOptions);
         this.obs = this._computed.obs;
-        this._options = options;
     }
     set(value) {
-        LocalSignal._setStorageValue(this._options, value);
+        this._setStorageValue(this._options, value);
         this._state$.set(value);
     }
     peek() {
@@ -41,23 +44,13 @@ export class LocalSignal {
     get() {
         return this._computed.get();
     }
-    // === static ===
-    static KEY_PREFIX = '__LSValue__';
-    static DRIVER = localStorage;
-    static create(options) {
-        const localSignal = new LocalSignal(options);
-        function signalFn() {
-            return localSignal.get();
-        }
-        signalFn.peek = () => localSignal.peek();
-        signalFn.get = () => localSignal.get();
-        signalFn.set = (value) => localSignal.set(value);
-        signalFn.obs = localSignal.obs;
-        return signalFn;
+    clear() {
+        this._deleteStorageValue(this._options);
+        this._state$.set(this._options.defaultValue);
     }
-    static _getStorageValue(options) {
-        const storageKey = `${LocalSignal.KEY_PREFIX}:${options.key}`;
-        const item = LocalSignal.DRIVER.getItem(storageKey);
+    _getStorageValue(options) {
+        const storageKey = `${LocalState.KEY_PREFIX}:${options.key}`;
+        const item = this._driver.getItem(storageKey);
         if (!item)
             return NONE;
         const schema = z.record(z.string(), options.zodSchema || z.any());
@@ -66,23 +59,64 @@ export class LocalSignal {
             console.warn(`Invalid value for key "${options.key}" in localStorage`, parsed.error);
             return NONE;
         }
-        const subKey = options.userId ? `user:${options.userId}` : 'common';
+        const subKey = options.userId ? `user:${options.userId}` : "common";
         if (!(subKey in parsed.data)) {
             return NONE;
         }
         return parsed.data[subKey];
     }
-    static _setStorageValue(options, value) {
-        const storageKey = `${LocalSignal.KEY_PREFIX}:${options.key}`;
-        const item = LocalSignal.DRIVER.getItem(storageKey) || '{}';
+    _setStorageValue(options, value) {
+        const storageKey = `${LocalState.KEY_PREFIX}:${options.key}`;
+        const item = this._driver.getItem(storageKey) || "{}";
         const schema = z.record(z.string(), options.zodSchema || z.any());
         const parsed = schema.safeParse(JSON.parse(item));
         let data = parsed.data ?? {};
         if (!parsed.success) {
             data = {};
         }
-        const subKey = options.userId ? `user:${options.userId}` : 'common';
+        const subKey = options.userId ? `user:${options.userId}` : "common";
         data[subKey] = value;
-        LocalSignal.DRIVER.setItem(storageKey, JSON.stringify(data));
+        this._driver.setItem(storageKey, JSON.stringify(data));
+    }
+    _deleteStorageValue(options) {
+        const storageKey = `${LocalState.KEY_PREFIX}:${options.key}`;
+        const item = this._driver.getItem(storageKey);
+        if (!item)
+            return;
+        const schema = z.record(z.string(), options.zodSchema || z.any());
+        const parsed = schema.safeParse(JSON.parse(item));
+        const data = parsed.data ?? {};
+        if (!parsed.success) {
+            this._driver.removeItem(storageKey);
+            return;
+        }
+        const subKey = options.userId ? `user:${options.userId}` : "common";
+        if (!data[subKey])
+            return;
+        delete data[subKey];
+        if (Object.keys(data).length === 0) {
+            this._driver.removeItem(storageKey);
+            return;
+        }
+        this._driver.setItem(storageKey, JSON.stringify(data));
+    }
+    // === static ===
+    static KEY_PREFIX = "__LSValue__";
+    static DEFAULT_DRIVER = localStorage;
+    static create(options) {
+        const localState = new LocalState(options);
+        function signalFn() {
+            return localState.get();
+        }
+        signalFn.peek = () => localState.peek();
+        signalFn.get = () => localState.get();
+        signalFn.set = (value) => localState.set(value);
+        signalFn.clear = () => localState.clear();
+        signalFn.obs = localState.obs;
+        return signalFn;
     }
 }
+/**
+ * @deprecated use LocalState instead
+ */
+export const LocalSignal = LocalState;

package/dist/signals/signals/Signal.d.ts

@@ -1,12 +1,13 @@
-import type { StateDevtoolsOptions } from "@/common/devtools";
-import { SignalFn } from "@/signals/types";
-import { Effect, State } from "@/signals/signals";
+import type { SignalOptionsOrKey } from "../../signals/types";
+import { SignalFn } from "../../signals/types";
+import { Effect } from "./Effect";
+import { State } from "./State";
 export declare class Signal<T> extends State<T> {
     /** @deprecated use `State` instead */
-    constructor(initialValue: T, options?: StateDevtoolsOptions);
+    constructor(initialValue: T, options?: SignalOptionsOrKey<T>);
     /** @deprecated use `state` instead */
-    static create<T>(initialValue: T, options?: StateDevtoolsOptions): SignalFn<T>;
-    static state<T>(initialValue: T, options?: StateDevtoolsOptions): SignalFn<T>;
-    static compute<T>(computeFn: () => T, options?: StateDevtoolsOptions): import("@/signals/types").ComputeFn<T>;
+    static create<T>(initialValue: T, options?: SignalOptionsOrKey<T>): SignalFn<T>;
+    static state<T>(initialValue: T, options?: SignalOptionsOrKey<T>): SignalFn<T>;
+    static compute<T>(computeFn: () => T, options?: SignalOptionsOrKey<T>): import("../../signals/types").ComputeFn<T>;
     static effect(effectFn: () => void): Effect;
 }

package/dist/signals/signals/Signal.js

@@ -1,6 +1,9 @@
-import { Computed, Effect, State } from "@/signals/signals";
+import { Computed } from "./Computed";
+import { Effect } from "./Effect";
+import { State } from "./State";
 export class Signal extends State {
     /** @deprecated use `State` instead */
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
     constructor(initialValue, options) {
         super(initialValue, options);
     }

package/dist/signals/signals/State.d.ts

@@ -1,15 +1,14 @@
 import { BehaviorSubject } from "rxjs";
-import { StateDevtoolsOptions } from "@/common/devtools";
-import { SignalFn } from "@/signals/types";
+import { SignalFn, SignalOptionsOrKey } from "../../signals/types";
 export declare class State<T> {
-    private readonly _stateDevtools;
+    private readonly _hooks;
     private _rang;
     protected readonly bs$: BehaviorSubject<T>;
     readonly obs: import("rxjs").Observable<T>;
-    constructor(initialValue: T, options?: StateDevtoolsOptions);
+    constructor(initialValue: T, options?: SignalOptionsOrKey<T>);
     peek(): T;
     set(value: T): void;
     get(): T;
     private static _finalizationRegistry;
-    static create<T>(initialValue: T, options?: StateDevtoolsOptions): SignalFn<T>;
+    static create<T>(initialValue: T, options?: SignalOptionsOrKey<T>): SignalFn<T>;
 }

package/dist/signals/signals/State.js

@@ -1,19 +1,27 @@
 import { BehaviorSubject } from "rxjs";
+import { normalizeSignalOptions } from "../../signals/types";
 import { Batcher, DependencyTracker, Devtools } from "../base";
 export class State {
-    _stateDevtools;
+    _hooks;
     _rang = 0;
     bs$;
     obs;
     constructor(initialValue, options) {
         this.bs$ = new BehaviorSubject(initialValue);
         this.obs = this.bs$.asObservable();
-        this._stateDevtools = Devtools.createState(initialValue, {
-            base: State.name,
-            ...(typeof options === 'string' ? { name: options } : options)
+        const opts = normalizeSignalOptions(options);
+        const hooks = [];
+        const devtoolsHook = Devtools.createSignalHooks(initialValue, {
+            ...opts,
+            base: opts.base ?? State.name,
         });
-        if (this._stateDevtools) {
-            State._finalizationRegistry.register(this, this._stateDevtools);
+        if (devtoolsHook)
+            hooks.push(devtoolsHook);
+        if (opts.hooks)
+            hooks.push(...opts.hooks);
+        this._hooks = hooks.length > 0 ? hooks : null;
+        if (this._hooks) {
+            State._finalizationRegistry.register(this, this._hooks);
         }
     }
     peek() {
@@ -24,7 +32,11 @@ export class State {
             return;
         }
         Batcher.run(() => {
-            this._stateDevtools?.(value);
+            if (this._hooks) {
+                for (const hook of this._hooks) {
+                    hook.onChange?.(value);
+                }
+            }
             this.bs$.next(value);
         });
     }
@@ -37,8 +49,10 @@ export class State {
         return this.bs$.getValue();
     }
     // === static ===
-    static _finalizationRegistry = new FinalizationRegistry((heldValue) => {
-        heldValue('$COMPLETED');
+    static _finalizationRegistry = new FinalizationRegistry((hooks) => {
+        for (const hook of hooks) {
+            hook.onDispose?.();
+        }
     });
     static create(initialValue, options) {
         const ls = new State(initialValue, options);

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

@@ -1,5 +1,5 @@
-export * from './State';
-export * from './Computed';
-export * from './Effect';
-export * from './Signal';
-export * from './LocalSignal';
+export * from "./State";
+export * from "./Computed";
+export * from "./Effect";
+export * from "./LocalState";
+export * from "./Signal";

package/dist/signals/signals/index.js

@@ -1,6 +1,5 @@
-// Порядок важен:
-export * from './State';
-export * from './Computed';
-export * from './Effect';
-export * from './Signal';
-export * from './LocalSignal';
+export * from "./State";
+export * from "./Computed";
+export * from "./Effect";
+export * from "./LocalState";
+export * from "./Signal";

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

@@ -0,0 +1,16 @@
+export interface SignalLifecycleHook<T = any> {
+    onInit?: (value: T) => void;
+    onChange?: (newValue: T) => void;
+    onDispose?: () => void;
+}
+export type TBeforeDevtoolsPushFn<T = any> = (newValue: T, push: (v: T) => void) => void;
+export interface SignalOptions<T = any> {
+    key?: string;
+    /** @deprecated use key */
+    name?: string;
+    base?: string;
+    isDisabled?: boolean;
+    beforeDevtoolsPush?: TBeforeDevtoolsPushFn<T>;
+    hooks?: SignalLifecycleHook<T>[];
+}
+export type SignalOptionsOrKey<T = any> = SignalOptions<T> | string;

package/dist/signals/types/SignalOptions.js

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

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

@@ -1 +1,3 @@
-export * from './signals.types';
+export * from "./signals.types";
+export * from "./SignalOptions";
+export * from "./normalizeSignalOptions";

package/dist/signals/types/index.js

@@ -1 +1,3 @@
-export * from './signals.types';
+export * from "./signals.types";
+export * from "./SignalOptions";
+export * from "./normalizeSignalOptions";

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

@@ -0,0 +1,2 @@
+import { SignalOptions, SignalOptionsOrKey } from "./SignalOptions";
+export declare function normalizeSignalOptions<T>(options?: SignalOptionsOrKey<T>): SignalOptions<T>;

package/dist/signals/types/normalizeSignalOptions.js

@@ -0,0 +1,10 @@
+export function normalizeSignalOptions(options) {
+    if (!options)
+        return {};
+    if (typeof options === "string")
+        return { key: options };
+    if (options.name && !options.key) {
+        return { ...options, key: options.name };
+    }
+    return options;
+}

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

@@ -10,7 +10,11 @@ export interface ReadableSignalFnLike<T> extends ReadableSignalLike<T> {
 export interface WriteableSignalLike<T> {
     set(value: T): void;
 }
-export interface SignalFn<T> extends ReadableSignalFnLike<T>, WriteableSignalLike<T> {
+export interface ClearableSignalLike<_T> {
+    clear(): void;
+}
+export interface StatefulSignalFn<T> extends ReadableSignalFnLike<T>, WriteableSignalLike<T>, ClearableSignalLike<T> {
 }
-export interface ComputeFn<T> extends ReadableSignalFnLike<T> {
+export interface SignalFn<T> extends ReadableSignalFnLike<T>, WriteableSignalLike<T> {
 }
+export type ComputeFn<T> = ReadableSignalFnLike<T>;

package/docs/CHANGELOG.md

@@ -1,32 +1,111 @@
-# CHANGELOG
-
-## Что нового в 0.5.0
-
-[Гайд по миграции](./migrations/0.5.0.md)
-
-### RxSignals
-
-- **Функциональный API (рекомендуется)**: `Signal.create()`, `Signal.compute()`, `Signal.effect()`
-- **Cleanup функции в Effect**: поддержка возврата teardown функции
-- **Без complete()**: теперь нет необходимости вызывать `complete()` для Signal и Computed
-- **Ленивый Computed**: вычисление только при наличии подписок
-
-### RxQuery
-
-- **Расширенные состояния**: `isInitialLoading`, `isReloading`, `isLocked`
-- **ResourceRef API**: низкоуровневый доступ к кэшу с поддержкой транзакций
-- **Patch транзакции**: изменения с возможностью commit/abort
-- **Lifecycle хуки**: `onCacheEntryAdded`, `onQueryStarted`
-- **resetAllQueriesCache()**: сброс всего кэша
-
-### React
-
-- **useResourceRef**: хук для работы с ResourceRef
-
-### Devtools
-
-- **BatchStrategy**: настройка стратегии обновлений (`'sync'`, `'microtask'`, `'task'`)
-
-### Конфигурация
-
-- **DefaultOptions**: расширенная конфигурация (`onQueryError`, `getScopeName`)
+# CHANGELOG
+
+## [Unreleased]
+
+### Fixed
+- Fixed `useResourceRef` memoization for object arguments — ref no longer recreated every render
+- Fixed missing type exports from `src/query/` — consumers can now import `ResourceDefinition`, `CommandDefinition`, etc.
+
+### Changed
+- `ResourceRefInstanse` renamed to `ResourceRefInstance` (deprecated alias preserved)
+- `FrowardInfo` renamed to `ForwardInfo` (internal type)
+- `Opertation/` directory renamed to `Operation/`
+- Replaced `any` types with proper types in `useResourceAgent` and `ResourceDuplicator`
+
+### Added
+- Unit tests for query core modules
+- Smoke tests for React hooks
+- Integration tests for query exports
+
+### Deprecated
+- `ResourceRefInstanse` — use `ResourceRefInstance` (will be removed in v0.6.0)
+
+
+## [0.5.3-rc.2] — 2026-02-23
+
+### Added
+
+- `createCommand()` — создание команды (мутации/действия), заменяет `createOperation()`
+- `useCommandAgent()` — React-хук для работы с командой
+- `LocalState` — замена `LocalSignal` с новыми возможностями
+- `LocalState.clear()` — метод удаления значения из хранилища и сброса к значению по умолчанию
+- Опция `driver` для `LocalState` — возможность подключить кастомное хранилище (вместо `localStorage`)
+
+### Changed
+
+- `LocalSignal` переименован в `LocalState`
+- Все вызовы `Signal.create()` в кодовой базе заменены на `Signal.state()` (внутренний рефакторинг)
+
+### Deprecated
+
+- `createOperation()` → используйте `createCommand()` (будет удалён в v0.6.0)
+- `useOperationAgent()` → используйте `useCommandAgent()` (будет удалён в v0.6.0)
+- Все Operation-типы переименованы в Command-типы: `OperationDefinition` → `CommandDefinition`, `OperationInstance` → `CommandInstance`, `OperationCreateOptions` → `CommandCreateOptions`, `OperationCreateFn` → `CommandCreateFn`, `OperationQueryState` → `CommandQueryState`
+- `OperationAgentInstanse` (с опечаткой) → `CommandAgentInstance` — исправлена опечатка в имени типа
+- `LocalSignal` → используйте `LocalState`
+
+### Fixed
+
+- Исправления в документации и демо-примерах
+
+## [0.5.3-rc.1] — 2026-02-22
+
+### Added
+
+- Новый примитив **State** — замена `Signal` с идентичным API
+- `Signal.state()` — рекомендуемый статический метод создания сигнала
+
+### Deprecated
+
+- `Signal` помечен как `@deprecated` — используйте `State` вместо него
+- `Signal.create()` помечен как `@deprecated` — используйте `Signal.state()` / `State.create()`
+
+## [0.5.2] — 2025-12-19
+
+### Fixed
+
+- Исправлена работа `SKIP_TOKEN`
+
+## [0.5.1] — 2025-12-19
+
+### Fixed
+
+- Исправление типизации
+
+## [0.5.0] — 2025-12-18
+
+[Гайд по миграции с 0.4.x](./migrations/0.5.0.md)
+
+### Breaking Changes
+
+- Удалены хуки `useObservable` и `useSyncObservable`
+- Сигналы больше не наследуют `Observable` — используйте `.obs` для подписки
+- Удалены `.value`, `.getValue()`, `.next()` — заменены на `signal()`, `.get()`, `.set()`
+- Нет необходимости вызывать `complete()` для Signal и Computed
+
+### Added
+
+#### Signals
+- **Функциональный API**: `Signal.create()`, `Signal.compute()`, `Signal.effect()`
+- **Ленивый Computed**: вычисление только при наличии подписок
+- Cleanup-функции в `Effect` (возврат teardown)
+
+#### Query
+- **Расширенные состояния**: `isInitialLoading`, `isReloading`, `isLocked`
+- **ResourceRef API**: низкоуровневый доступ к кэшу с поддержкой транзакций (patch с commit/abort)
+- **Lifecycle хуки**: `onCacheEntryAdded`, `onQueryStarted`
+- `resetAllQueriesCache()` — сброс всего кэша
+
+#### React
+- `useResourceRef` — хук для работы с ResourceRef
+
+### Changed
+
+- **BatchStrategy**: настройка стратегии обновлений (`'sync'`, `'microtask'`, `'task'`)
+- **DefaultOptions**: расширенная конфигурация (`onQueryError`, `getScopeName`)
+
+[0.5.3-rc.2]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.3-rc.1...v0.5.3-rc.2
+[0.5.3-rc.1]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.2...v0.5.3-rc.1
+[0.5.2]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/fozy-labs/rx-toolkit/compare/v0.4.18...v0.5.0