@fozy-labs/rx-toolkit 0.5.4 → 0.6.2

package/dist/query/types/plugin-hkt.d.ts

@@ -0,0 +1,64 @@
+import type { IPlugin } from "./api";
+/**
+ * Base Higher-Kinded Type for plugin resource augmentation.
+ *
+ * Plugin authors extend this and override `resourceType` / `commandType`
+ * using `this['_TArgs']` and `this['_TData']` to refer to the resource's
+ * type parameters.
+ *
+ * @example
+ * ```ts
+ * interface MyPluginHKT extends PluginHKT {
+ *   readonly resourceType: { myHook: (args: this['_TArgs']) => this['_TData'] };
+ * }
+ * ```
+ */
+export interface PluginHKT {
+    /** @phantom — substituted with the resource/command TArgs at application site */
+    readonly _TArgs: unknown;
+    /** @phantom — substituted with the resource/command TData at application site */
+    readonly _TData: unknown;
+    /** Override in subinterfaces to declare resource augmentation shape. */
+    readonly resourceType: {};
+    /** Override in subinterfaces to declare command augmentation shape. */
+    readonly commandType: {};
+}
+/**
+ * "Apply" a PluginHKT — substitute TArgs/TData and extract the resource augmentation type.
+ *
+ * Mechanism: intersect the HKT interface with concrete `{ _TArgs: TArgs; _TData: TData }`.
+ * Because `resourceType` references `this['_TArgs']`/`this['_TData']`, and `this` in the
+ * intersection resolves to the merged type, the phantom parameters become concrete.
+ */
+type ApplyPluginResourceHKT<F extends PluginHKT, TArgs, TData> = (F & {
+    readonly _TArgs: TArgs;
+    readonly _TData: TData;
+})["resourceType"];
+type ApplyPluginCommandHKT<F extends PluginHKT, TArgs, TData> = (F & {
+    readonly _TArgs: TArgs;
+    readonly _TData: TData;
+})["commandType"];
+/**
+ * Extract and apply the resource augmentation from a single plugin type.
+ * Returns `{}` if the plugin does not declare an HKT (graceful degradation).
+ *
+ * Uses bounded `infer H extends PluginHKT` to reject `undefined` from optional `_hkt`.
+ */
+type ExtractResourceAugment<P, TArgs, TData> = P extends {
+    readonly _hkt: infer H extends PluginHKT;
+} ? ApplyPluginResourceHKT<H, TArgs, TData> : {};
+type ExtractCommandAugment<P, TArgs, TData> = P extends {
+    readonly _hkt: infer H extends PluginHKT;
+} ? ApplyPluginCommandHKT<H, TArgs, TData> : {};
+/** Standard union-to-intersection utility. */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Combine resource augmentations from all plugins in the tuple.
+ * Maps each `TPlugins[number]` through `ExtractResourceAugment`, then intersects the results.
+ *
+ * - `readonly [ReactHooksPlugin, OtherPlugin]` → `{ useResource: ... } & { otherHook: ... }`
+ * - `readonly IPlugin[]` (default) → `{}` (no augmentation)
+ */
+export type CombinePluginResourceAugments<TPlugins extends readonly IPlugin[], TArgs, TData> = UnionToIntersection<ExtractResourceAugment<TPlugins[number], TArgs, TData>>;
+export type CombinePluginCommandAugments<TPlugins extends readonly IPlugin[], TArgs, TData> = UnionToIntersection<ExtractCommandAugment<TPlugins[number], TArgs, TData>>;
+export type { ApplyPluginResourceHKT, ApplyPluginCommandHKT, ExtractResourceAugment, ExtractCommandAugment, UnionToIntersection, };

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

@@ -0,0 +1,49 @@
+import type { ArgsOrVoidOrSkip, TResourceSnapshot } from "../../query";
+import type { ReadableSignalFnLike } from "../../signals/types";
+import type { IQueryCacheEntry, TCacheEntryAddedContext, TQueryStartedContext } from "./cache";
+import type { Args, ArgsOrVoid, Keyed } from "./common";
+import type { TResourceAgentState } from "./state";
+export interface IResource<TArgs, TData> {
+    trigger(args: Args<TArgs>, doForce?: boolean): void;
+    refresh(args: Args<TArgs>): void;
+    getEntry(args: ArgsOrVoid<TArgs>, doInitiate?: boolean): IQueryCacheEntry<TArgs, TData> | null;
+    getEntry$(args: ArgsOrVoid<TArgs>, doInitiate?: boolean): ReadableSignalFnLike<IQueryCacheEntry<TArgs, TData> | null>;
+    getEntries(): IterableIterator<IQueryCacheEntry<TArgs, TData>>;
+    createAgent(): IResourceAgent<TArgs, TData>;
+    serialize(args: Args<TArgs>): string;
+    toKeyed(args: Args<TArgs>): Keyed<TArgs>;
+}
+export interface IResourceAgent<TArgs, TData> {
+    state$: ReadableSignalFnLike<TResourceAgentState<TArgs, TData>>;
+    start(): void;
+    set(args: ArgsOrVoidOrSkip<TArgs>, mark?: boolean): void;
+    retry(): void;
+    refresh(): void;
+    get args(): TArgs | null;
+}
+export interface TResourceOptions<TArgs, TData> {
+    queryFn: (args: TArgs, abortSignal: AbortSignal) => Promise<TData>;
+    key?: string;
+    retentionTime?: number | false;
+    serializeArgs?: (args: TArgs) => string;
+    onCacheEntryAdded?: (args: TArgs, ctx: TCacheEntryAddedContext<TArgs, TData>) => void;
+    onQueryStarted?: (args: TArgs, ctx: TQueryStartedContext<TArgs, TData>) => void | Promise<void>;
+    snapshotValidTime?: number | false;
+    sync?: boolean;
+    getDevtoolsKey?: (args: Keyed<TArgs>) => string;
+}
+export interface IResourceConfig<TArgs, TData> {
+    queryFn: (args: TArgs, abortSignal: AbortSignal) => Promise<TData>;
+    key?: string;
+    retentionTime: number | false;
+    serializeArgs: (args: TArgs) => string;
+    onCacheEntryAdded?: (args: TArgs, ctx: TCacheEntryAddedContext<TArgs, TData>) => void;
+    onQueryStarted?: (args: TArgs, ctx: TQueryStartedContext<TArgs, TData>) => void | Promise<void>;
+    getDevtoolsKey?: (args: Keyed<TArgs>) => string;
+    /** Pre-populated entries from snapshot hydration (key → snapshot meta). */
+    snapshot?: TResourceSnapshot;
+    /** Cross-tab sync hook: called before queryFn to check if another tab has cached data. */
+    beforeQuery?: (resourceKey: string, entryKey: string) => Promise<{
+        data: TData;
+    } | null>;
+}

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

@@ -0,0 +1,27 @@
+export interface TResourceSnapshotEntry {
+    status: string;
+    args: unknown;
+    data: unknown;
+    updatedAt: number;
+    isStale?: boolean;
+}
+export interface TResourceSnapshot {
+    entries: Record<string, TResourceSnapshotEntry>;
+}
+export interface TApiSnapshot {
+    version: number;
+    keyPrefix: string | null;
+    timestamp: number;
+    resources: Record<string, TResourceSnapshot>;
+}
+export interface ISyncMessage {
+    type: "REQ" | "RES";
+    reqId: string;
+    keys: [string, string, string];
+    data?: unknown;
+}
+export interface ISyncDriver {
+    connect(onMessage: (msg: ISyncMessage) => void): void;
+    disconnect(): void;
+    send(message: ISyncMessage): void;
+}

package/dist/query/types/snapshot.js

@@ -0,0 +1,2 @@
+// ==================== Snapshot Types ====================
+export {};

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

@@ -0,0 +1,24 @@
+import type { TAgentStatus } from "./common";
+export interface TResourceAgentState<TArgs, TData> {
+    status: TAgentStatus;
+    data: TData | null;
+    error: unknown;
+    args: TArgs | null;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isRefreshing: boolean;
+    isRefreshError: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    retry: () => void;
+    refresh: () => void;
+}
+export interface TCommandAgentState<TArgs, TData> {
+    status: "idle" | "pending" | "success" | "error";
+    data: TData | null;
+    error: unknown;
+    args: TArgs | null;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+}

package/dist/signals/base/ComputeCache.js

@@ -1,4 +1,4 @@
-import { DependencyTracker } from "../../signals";
+import { DependencyTracker } from "./DependencyTracker";
 /**
  * Кеш для хранения вычисленного значения и его зависимостей
  */

package/dist/signals/base/Devtools.js

@@ -1,14 +1,13 @@
 import { SharedOptions } from "../../common/options/SharedOptions";
-import { Indexer } from "./Indexer";
 export const Devtools = {
     createState(initialValue, optionsDry = {}) {
-        const options = typeof optionsDry === "string" ? { name: optionsDry } : optionsDry;
+        const options = typeof optionsDry === "string" ? { key: optionsDry } : optionsDry;
         if (options.isDisabled)
             return null;
         const createStateDevtools = SharedOptions.DEVTOOLS?.state;
         if (!createStateDevtools)
             return null;
-        const key = createKey(options.key ?? options.name, options.base);
+        const key = createKey(options.key, options.base);
         let stateDevtools = null;
         const push = (value) => {
             if (!stateDevtools) {
@@ -36,7 +35,6 @@ export const Devtools = {
     createSignalHooks(initialValue, options = {}) {
         const stateDevtools = this.createState(initialValue, {
             key: options.key,
-            name: options.name,
             base: options.base,
             isDisabled: options.isDisabled,
             beforeDevtoolsPush: options.beforeDevtoolsPush,
@@ -57,7 +55,6 @@ export const Devtools = {
     },
 };
 function createKey(key, base) {
-    const i = Indexer.getIndex();
     let result = "";
     if (key?.includes("{scope}")) {
         const scopeName = SharedOptions.getScopeName?.() || "#global";
@@ -69,6 +66,5 @@ function createKey(key, base) {
         result += key;
     else if (base && !key)
         result += `${base}/`;
-    result += `#i=${i}`;
     return result;
 }

package/dist/signals/signals/Computed.d.ts

@@ -13,6 +13,7 @@ export declare class Computed<T> {
     peek(): T;
     private _start;
     private _stop;
+    destroy(): void;
     private static _EMPTY;
     static create<T>(computeFn: () => T, options?: SignalOptionsOrKey<T>): ComputeFn<T>;
 }

package/dist/signals/signals/Computed.js

@@ -17,7 +17,6 @@ export class Computed {
         const opts = normalizeSignalOptions(options);
         const stateOptions = {
             key: opts.key,
-            name: opts.name,
             base: opts.base ?? Computed.name,
             isDisabled: opts.isDisabled,
             beforeDevtoolsPush: (value, push) => {
@@ -84,6 +83,10 @@ export class Computed {
         }
         this._state$.set(Computed._EMPTY);
     }
+    destroy() {
+        this._stop();
+        this._computeCache.clear();
+    }
     // === static ===
     static _EMPTY = Symbol("empty");
     static create(computeFn, options) {
@@ -94,6 +97,7 @@ export class Computed {
         computedFn.peek = () => lc.peek();
         computedFn.get = () => lc.get();
         computedFn.obs = lc.obs;
+        computedFn.destroy = () => lc.destroy();
         return computedFn;
     }
 }

package/dist/signals/signals/Effect.d.ts

@@ -13,10 +13,6 @@ export declare class Effect implements SubscriptionLike {
     private _runInTrackedContext;
     unsubscribe(): void;
     _getRang(): number;
-    /**
-     * @deprecated Use `unsubscribe()` method instead.
-     */
-    complete(): void;
     private _callTeardown;
     static create(effectFn: EffectFn): Effect;
 }

package/dist/signals/signals/Effect.js

@@ -72,12 +72,6 @@ export class Effect {
     _getRang() {
         return this._rang;
     }
-    /**
-     * @deprecated Use `unsubscribe()` method instead.
-     */
-    complete() {
-        this.unsubscribe();
-    }
     _callTeardown() {
         if (this._teardown) {
             this._teardown();

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

@@ -1,4 +1,3 @@
-import { Observable } from "rxjs";
 import { ZodType } from "zod/v4";
 import { type SignalOptionsOrKey, type StatefulSignalFn } from "../../signals/types";
 type StorageLike = {
@@ -10,10 +9,6 @@ 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;
@@ -23,7 +18,7 @@ export declare class LocalState<T = string | null | number | undefined> {
     private _state$;
     private _computed;
     private readonly _options;
-    readonly obs: Observable<T>;
+    readonly obs: import("rxjs").Observable<T>;
     private get _driver();
     constructor(options: Options<T>);
     set(value: T): void;
@@ -37,8 +32,4 @@ export declare class LocalState<T = string | null | number | undefined> {
     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/LocalState.js

@@ -1,5 +1,4 @@
 import { z } from "zod/v4";
-import { signalize } from "../operators";
 import { Computed } from "./Computed";
 import { State } from "./State";
 const NONE = Symbol("NONE");
@@ -18,15 +17,8 @@ export class LocalState {
             initialValue = options.defaultValue;
         }
         this._state$ = new State(initialValue, { isDisabled: true });
-        const validatorSignal$ = options.validator$ && signalize(options.validator$);
         this._computed = new Computed(() => {
             const value = this._state$.get();
-            if (validatorSignal$) {
-                const validator = validatorSignal$.get();
-                if (!validator(value)) {
-                    return options.defaultValue;
-                }
-            }
             if (options.checkEffect) {
                 return options.checkEffect(value) ? value : options.defaultValue;
             }
@@ -116,7 +108,3 @@ export class LocalState {
         return signalFn;
     }
 }
-/**
- * @deprecated use LocalState instead
- */
-export const LocalSignal = LocalState;

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

@@ -1,12 +1,6 @@
-import type { SignalOptionsOrKey } from "../../signals/types";
-import { SignalFn } from "../../signals/types";
+import type { SignalFn, SignalOptionsOrKey } 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?: SignalOptionsOrKey<T>);
-    /** @deprecated use `state` instead */
-    static create<T>(initialValue: T, options?: SignalOptionsOrKey<T>): SignalFn<T>;
+export declare class Signal {
     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,16 +1,7 @@
 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);
-    }
-    /** @deprecated use `state` instead */
-    static create(initialValue, options) {
-        return this.state(initialValue, options);
-    }
+export class Signal {
     static state(initialValue, options) {
         return State.create(initialValue, options);
     }

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

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

package/dist/signals/signals/State.js

@@ -48,6 +48,15 @@ export class State {
         });
         return this.bs$.getValue();
     }
+    complete() {
+        this.bs$.complete();
+        if (this._hooks) {
+            for (const hook of this._hooks) {
+                hook.onDispose?.();
+            }
+            this._hooks = null;
+        }
+    }
     // === static ===
     static _finalizationRegistry = new FinalizationRegistry((hooks) => {
         for (const hook of hooks) {

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

@@ -6,8 +6,6 @@ export interface SignalLifecycleHook<T = any> {
 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>;

package/dist/signals/types/normalizeSignalOptions.js

@@ -3,8 +3,5 @@ export function normalizeSignalOptions(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

@@ -17,4 +17,6 @@ export interface StatefulSignalFn<T> extends ReadableSignalFnLike<T>, WriteableS
 }
 export interface SignalFn<T> extends ReadableSignalFnLike<T>, WriteableSignalLike<T> {
 }
-export type ComputeFn<T> = ReadableSignalFnLike<T>;
+export type ComputeFn<T> = ReadableSignalFnLike<T> & {
+    destroy(): void;
+};

package/docs/CHANGELOG.md

@@ -1,5 +1,55 @@
 # CHANGELOG
 
+## [0.6.2] - 2026-05-17
+
+### Fixed
+- Исправлен вывод типов в `links` 
+
+## [0.6.0] - 2026-04-17
+
+[Гайд по миграции с 0.5.x](./migrations/0.6.0.md)
+
+### Added
+- `createApi()` — центральная фабрика для создания ресурсов и команд, заменяет standalone-функции
+- Фабричные методы `Machine.pending()`, `Machine.fromSnapshot()`
+- Система плагинов с HKT-типами для типобезопасного расширения
+- SSR-гидрация кеша через опции `initialSnapshot` и `getSnapshot()`
+- Кросс-табовая синхронизация через опции `syncDriver` и `defaultSync`
+- Новые опции `createApi`: `keyPrefix`, `syncDriver`, `defaultSync`, `snapshotValidTime`, `initialSnapshot`, `resourceRetentionTime`, `commandRetentionTime`
+- Статус `isRefreshError` в агентах ресурсов
+- Статус `idle` в агентах (ресурсов и команд)
+- `reactHooksPlugin()` — фабричная функция (альтернатива `new ReactHooksPlugin()`)
+
+### Changed
+- **Полностью переработанный модуль Query** — иммутабельные состояния машины, реактивные кеш-записи, SWR-поведение
+- `Machine` теперь дискриминированное объединение иммутабельных подтипов: `MachinePending`, `MachineSuccess`, `MachineError`, `MachineRefreshing`, `MachineRefreshError`
+- Ресурсы теперь поддерживают реактивные кеш-записи с методами `getEntry$()`, `createAgent()`, `trigger()`, `refresh()`
+- Агенты ресурсов переработаны — SWR-поведение, методы `start`, `set`, `retry`, `refresh`, новый статус `idle`
+- Агенты команд переработаны — методы `trigger`, `setKey`
+- Команды теперь поддерживают оптимистичные обновления, патчи при успехе и инвалидацию связанных ресурсов
+- `link` (callback) переименован в `links` (массив или callback): `optimisticUpdate(draft, args)`, `update(draft, args, result)`, `invalidate` — вместо обёрточного объекта
+- React хуки переписаны: `useResource(resource, args)`, `useCommand(command, key)`
+- Оптимистичные обновления с Immer-патчами и rebase-логикой
+
+### Removed
+- Удалены deprecated-элементы:
+  - `api.createOperation()` → используйте `api.createCommand()`
+  - `useOperationAgent()` → используйте `useCommand()`
+  - Все Operation-типы (`OperationDefinition`, `OperationInstance`, `OperationCreateOptions`, `OperationCreateFn`, `OperationQueryState`, `OperationAgentInstanse`) → удалены (Query модуль полностью переписан, см. [гайд по миграции](./migrations/0.6.0.md))
+  - `ResourceRefInstanse` — удалён (используйте `resource.getEntry()` для доступа к кеш-записям)
+  - `LocalSignal` → используйте `LocalState`
+  - `Signal.create()` — удалён из публичного API (технически доступен через наследование от `State`, но не рекомендуется) → используйте `Signal.state()` / `State.create()`
+- Удалены standalone-функции (заменены методами `createApi()`):
+  - `createResource()` → `api.createResource()`
+  - `createCommand()` → `api.createCommand()`
+  - `createResourceDuplicator()` → удалён без замены
+  - `resetAllQueriesCache()` → `api.resetAll()`
+- Удалены и заменены React-хуки:
+  - `useCommandAgent()` → используйте `useCommand()`
+  - `useResourceAgent()` → используйте `useResource()`
+  - `useResourceRef()` → удалён (используйте `resource.getEntry()`)
+- Удалён namespace `unstable_queryV2` — экспериментальный API стал основным
+
 ## [0.5.4] - 2026-03-21
 
 ### Fixed
@@ -88,8 +138,10 @@
 - **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.6.2]: https://github.com/fozy-labs/rx-toolkit/compare/v0.6.0...v0.6.2
+[0.6.0]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.4...v0.6.0
+[0.5.4]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.3...v0.5.4
+[0.5.3]: https://github.com/fozy-labs/rx-toolkit/compare/v0.5.2...v0.5.3
 [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

package/docs/contributing/release/README.md

@@ -22,10 +22,7 @@ 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. Пуш тегов в репозиторий
+# 4. Пуш тегов в репозиторий
 git push origin develop --tags
 ```
 
@@ -44,10 +41,7 @@ npm run build
 npm version prerelease --preid=rc
 # пример: 1.2.0 → 1.2.0-rc.0
 
-# 4. Публикация RC (НЕ latest!)
-npm publish --tag rc
-
-# 5. Пуш тегов
+# 4. Пуш тегов
 git push origin develop --tags
 ```