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

package/dist/query-v2/types/cache.types.d.ts

@@ -0,0 +1,37 @@
+import type { IMachineBox } from "./machine.types";
+import type { TCompareArgsFn, TSerializeArgsFn } from "./shared.types";
+/** Single reactive cache unit holding a Machine */
+export interface ICacheEntry<TData, TError = Error> {
+    /** Reactive signal holding current machine state */
+    readonly machine$: () => IMachineBox<TData, TError>;
+    /** Synchronous peek at current machine */
+    peek(): IMachineBox<TData, TError>;
+    /** Update machine state */
+    set(machine: IMachineBox<TData, TError>): void;
+    /** Cleanup — complete and release */
+    complete(): void;
+    /** Observable for cache lifetime management */
+    readonly onClean$: {
+        subscribe(cb: () => void): {
+            unsubscribe(): void;
+        };
+    };
+}
+/** Dual-strategy cache abstraction */
+export interface ICacheMap<TArgs, TData, TError = Error> {
+    get(args: TArgs): ICacheEntry<TData, TError> | undefined;
+    set(args: TArgs, entry: ICacheEntry<TData, TError>): void;
+    delete(args: TArgs): boolean;
+    has(args: TArgs): boolean;
+    values(): Iterable<ICacheEntry<TData, TError>>;
+    entries(): Iterable<[TArgs | string, ICacheEntry<TData, TError>]>;
+    clear(): void;
+    readonly size: number;
+}
+/** Factory options for creating appropriate cache map */
+export interface ICacheMapOptions<_TArgs> {
+    keyStrategy: "serialize" | "compare";
+    serializeArgs: TSerializeArgsFn;
+    compareArg: TCompareArgsFn;
+    doCacheArgs: boolean;
+}

package/dist/query-v2/types/cache.types.js

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

package/dist/query-v2/types/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./shared.types";
+export * from "./machine.types";
+export * from "./cache.types";
+export * from "./resource.types";
+export * from "./agent.types";
+export * from "./api.types";
+export * from "./plugin.types";
+export * from "./snapshot.types";
+export * from "./lifecycle.types";

package/dist/query-v2/types/index.js

@@ -0,0 +1,9 @@
+export * from "./shared.types";
+export * from "./machine.types";
+export * from "./cache.types";
+export * from "./resource.types";
+export * from "./agent.types";
+export * from "./api.types";
+export * from "./plugin.types";
+export * from "./snapshot.types";
+export * from "./lifecycle.types";

package/dist/query-v2/types/lifecycle.types.d.ts

@@ -0,0 +1,25 @@
+import type { ICacheEntry } from "./cache.types";
+import type { TMachine } from "./machine.types";
+/** Tools provided to onCacheEntryAdded */
+export interface TCacheEntryAddedTools<TData> {
+    /** Resolves when first MachineSuccess is set */
+    $cacheDataLoaded: Promise<TData>;
+    /** Resolves when cache entry is removed */
+    $cacheEntryRemoved: Promise<void>;
+    /** Get current machine state */
+    getCacheEntry(): TMachine<TData, any>;
+}
+/** onCacheEntryAdded callback type */
+export type TOnCacheEntryAdded<TArgs, TData> = (args: TArgs, tools: TCacheEntryAddedTools<TData>) => void | Promise<void>;
+/** Tools provided to onQueryStarted */
+export interface TQueryStartedTools<TData> {
+    /** Resolves/rejects when query completes */
+    $queryFulfilled: Promise<{
+        data: TData;
+        isError: false;
+    }>;
+    /** Get current cache entry for patching */
+    getCacheEntry(): ICacheEntry<TData, any>;
+}
+/** onQueryStarted callback type */
+export type TOnQueryStarted<TArgs, TData> = (args: TArgs, tools: TQueryStartedTools<TData>) => void | Promise<void>;

package/dist/query-v2/types/lifecycle.types.js

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

package/dist/query-v2/types/machine.types.d.ts

@@ -0,0 +1,67 @@
+import type { NO_VALUE } from "./shared.types";
+/** Discriminated union of all machine statuses */
+export type TMachineStatus = "idle" | "pending" | "success" | "error" | "refreshing";
+/** Idle state — initial, no data */
+export interface TResourceV2IdleState {
+    status: "idle";
+    args: null;
+    data: null;
+    error: null;
+    updatedAt: null;
+}
+/** Pending state — query in progress, no data yet */
+export interface TResourceV2PendingState<TData = unknown> {
+    status: "pending";
+    args: unknown;
+    data: null;
+    error: null;
+    updatedAt: null;
+    originalData: TData | NO_VALUE;
+}
+/** Success state — data loaded successfully */
+export interface TResourceV2SuccessState<TData = unknown> {
+    status: "success";
+    args: unknown;
+    data: TData;
+    error: null;
+    updatedAt: number;
+    originalData: TData | NO_VALUE;
+    patches: TResourceV2Patch[] | null;
+}
+/** Error state — query failed */
+export interface TResourceV2ErrorState<TError = Error> {
+    status: "error";
+    args: unknown;
+    data: null;
+    error: TError;
+    updatedAt: null;
+}
+/** Refreshing state — re-fetching while holding stale data */
+export interface TResourceV2RefreshingState<TData = unknown> {
+    status: "refreshing";
+    args: unknown;
+    data: TData;
+    error: null;
+    updatedAt: number;
+    originalData: TData | NO_VALUE;
+    patches: TResourceV2Patch[] | null;
+}
+/** Patch record in the queue (Immer-based) */
+export interface TResourceV2Patch {
+    patches: unknown[];
+    inversePatches: unknown[];
+    status: "pending" | "committed" | "aborted";
+}
+/** Patch function (Immer recipe) */
+export type TPatchFn<TData> = (draft: TData) => void;
+/**
+ * Discriminated union of all machine states (flat state shapes).
+ */
+export type TMachine<TData, TError = Error> = TResourceV2IdleState | TResourceV2PendingState<TData> | TResourceV2SuccessState<TData> | TResourceV2ErrorState<TError> | TResourceV2RefreshingState<TData>;
+/**
+ * Boxed machine — structural type matching runtime machine class instances.
+ * Each machine class wraps its flat state in a `readonly state` property.
+ */
+export interface IMachineBox<TData = unknown, TError = Error> {
+    readonly state: TMachine<TData, TError>;
+}

package/dist/query-v2/types/machine.types.js

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

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

@@ -0,0 +1,38 @@
+import type { ResourceV2 } from "../../query-v2";
+import type { IApi } from "./api.types";
+import type { IResourceV2Options } from "./resource.types";
+import type { Prettify } from "./shared.types";
+/** Plugin interface — all plugins must implement this */
+export interface IPlugin {
+    /** Unique plugin name */
+    readonly name: string;
+    /** Called once when createApi installs the plugin */
+    install(context: IPluginContext): void;
+    /** Called for each createResource — returns augmented resource */
+    augmentResource<TArgs, TData, TError>(resource: ResourceV2<TArgs, TData, TError>, options: IResourceV2Options<TArgs, TData, TError>): Record<string, unknown>;
+}
+/** Context provided to plugins during install */
+export interface IPluginContext {
+    /** The API instance */
+    readonly api: IApi<any>;
+    /** Key strategy for this API */
+    readonly keyStrategy: "serialize" | "compare";
+}
+/** Helper: converts a union to an intersection */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Extract plugin contributions from a single plugin.
+ * Each plugin extends PluginContributionMap via declaration merging.
+ * The name property is used as the key lookup.
+ */
+export interface PluginContributionMap<TArgs, TData, TError> {
+}
+export type ExtractPluginContributions<P extends IPlugin, TArgs, TData, TError> = P extends {
+    name: infer N;
+} ? N extends keyof PluginContributionMap<TArgs, TData, TError> ? PluginContributionMap<TArgs, TData, TError>[N] : object : object;
+/**
+ * Type-level utility: extracts and merges augmentations from a plugin tuple.
+ * Uses UnionToIntersection + Prettify as per ADR-1.
+ */
+export type PluginAugmentations<TPlugins extends IPlugin[], TArgs, TData, TError> = TPlugins extends [] ? object : Prettify<UnionToIntersection<TPlugins[number] extends infer P ? P extends IPlugin ? ExtractPluginContributions<P, TArgs, TData, TError> : never : never>>;
+export {};

package/dist/query-v2/types/plugin.types.js

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

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

@@ -0,0 +1,35 @@
+import type { IResourceV2Agent } from "./agent.types";
+import type { ICacheEntry } from "./cache.types";
+import type { TOnCacheEntryAdded, TOnQueryStarted } from "./lifecycle.types";
+import type { TMachine } from "./machine.types";
+import type { TBeforeDevtoolsPushFn, TCompareArgsFn, TQueryFn, TSerializeArgsFn } from "./shared.types";
+/** Options for api.createResource */
+export interface IResourceV2Options<TArgs, TData, TError = Error> {
+    key?: string;
+    queryFn: TQueryFn<TArgs, TData>;
+    onCacheEntryAdded?: TOnCacheEntryAdded<TArgs, TData>;
+    onQueryStarted?: TOnQueryStarted<TArgs, TData>;
+    serializeArgs?: TSerializeArgsFn;
+    compareArg?: TCompareArgsFn;
+    cacheLifetime?: number;
+    beforeDevtoolsPush?: TBeforeDevtoolsPushFn<TMachine<TData, TError>>;
+    maxSnapshotDataAge?: number;
+    doCacheArgs?: boolean;
+}
+/** ResourceV2 instance (public API) */
+export interface IResourceV2<TArgs, TData, TError = Error> {
+    /** Create an agent (observer with SWR) */
+    createAgent(): IResourceV2Agent<TArgs, TData, TError>;
+    /** Execute query, returns promise of cache entry */
+    query(args: TArgs, doForce?: boolean): Promise<ICacheEntry<TData, TError>>;
+    /** Reactive query — returns current machine state as signal read */
+    query$(args: TArgs, doForce?: boolean): TMachine<TData, TError>;
+    /** Get raw cache entry (non-reactive) */
+    entry(args: TArgs, doInitiate?: boolean): ICacheEntry<TData, TError> | null;
+    /** Get cache entry signal (reactive) */
+    entry$(args: TArgs, doInitiate?: boolean): TMachine<TData, TError>;
+    /** Force re-fetch for given args */
+    invalidate(args: TArgs): void;
+    /** Compare two args values */
+    compareArgs(a: TArgs, b: TArgs): boolean;
+}

package/dist/query-v2/types/resource.types.js

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

package/dist/query-v2/types/shared.types.d.ts

@@ -0,0 +1,20 @@
+export type Prettify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
+/** Serialize args to string cache key */
+export type TSerializeArgsFn = (args: unknown) => string;
+/** Compare two args for equality (used in 'compare' strategy) */
+export type TCompareArgsFn = (a: unknown, b: unknown) => boolean;
+/**
+ * Intercepts machine state before pushing to Redux DevTools.
+ * Default behavior: push machine.state (plain object).
+ * User can transform or filter.
+ */
+export type TBeforeDevtoolsPushFn<TMachineState> = (newValue: TMachineState, push: (value: TMachineState) => void) => void;
+/** Query function signature */
+export type TQueryFn<TArgs, TData> = (args: TArgs, tools: TQueryFnTools) => Promise<TData>;
+export interface TQueryFnTools {
+    abortSignal: AbortSignal;
+}
+/** NO_VALUE type alias — the runtime value lives in lib/NO_VALUE.ts */
+export type NO_VALUE = typeof import("../lib/NO_VALUE").NO_VALUE;

package/dist/query-v2/types/shared.types.js

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

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

@@ -0,0 +1,21 @@
+/** Full API snapshot for SSR */
+export interface TApiSnapshot {
+    /** Format version (integer counter) */
+    version: number;
+    /** keyPrefix of the API instance */
+    keyPrefix: string | null;
+    /** Resource snapshots keyed by resource key */
+    resources: Record<string, TResourceSnapshot>;
+}
+/** Single resource snapshot */
+export interface TResourceSnapshot {
+    /** Cache entries keyed by serialized args */
+    entries: Record<string, TResourceV2SnapshotSlice>;
+}
+/** Single cache entry snapshot */
+export interface TResourceV2SnapshotSlice<TData = unknown> {
+    status: "success";
+    args: unknown;
+    data: TData;
+    updatedAt: number;
+}

package/dist/query-v2/types/snapshot.types.js

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

package/dist/signals/base/Batcher.js

@@ -40,16 +40,20 @@ export const Batcher = {
                 if (!Scheduled.isLocked)
                     return fn();
                 Scheduled.set(rang, fn);
-            }
+            },
         };
     },
     run(fn) {
         if (Scheduled.isLocked)
             return fn();
         Scheduled.isLocked = true;
-        const v = fn();
-        Scheduled.run();
-        Scheduled.isLocked = false;
-        return v;
+        try {
+            const v = fn();
+            Scheduled.run();
+            return v;
+        }
+        finally {
+            Scheduled.isLocked = false;
+        }
     },
 };

package/dist/signals/base/ComputeCache.js

@@ -3,7 +3,7 @@ import { DependencyTracker } from "../../signals";
  * Кеш для хранения вычисленного значения и его зависимостей
  */
 export class ComputeCache {
-    static _NO_VALUE = Symbol('no-value');
+    static _NO_VALUE = Symbol("no-value");
     _cachedValue = ComputeCache._NO_VALUE;
     _dependencies = [];
     /**
@@ -14,7 +14,7 @@ export class ComputeCache {
             return false;
         }
         // Проверяем, что все зависимости имеют те же значения
-        return this._dependencies.every(dep => {
+        return this._dependencies.every((dep) => {
             try {
                 const currentValue = dep.peek();
                 return Object.is(currentValue, dep.lastValue);
@@ -45,7 +45,7 @@ export class ComputeCache {
             // Вычисляем значение
             const result = computeFn();
             // Получаем текущие значения зависимостей
-            dependencies.forEach(dep => {
+            dependencies.forEach((dep) => {
                 dep.lastValue = dep.peek();
             });
             // Сохраняем результат и зависимости

package/dist/signals/base/DependencyTracker.js

@@ -4,7 +4,7 @@ export class DependencyTracker {
         this._currentHandler?.(dep);
     }
     static start(handler) {
-        let prevHandler = this._currentHandler;
+        const prevHandler = this._currentHandler;
         this._currentHandler = handler;
         return () => {
             this._currentHandler = prevHandler;

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

@@ -1,5 +1,6 @@
-import { StateDevtoolsOptions } from "../../common/devtools";
+import type { SignalLifecycleHook, SignalOptions } from "../../signals/types";
 export declare const Devtools: {
-    createState<T>(initialValue: T, optionsDry?: StateDevtoolsOptions): ((newState: T) => void) | null;
+    createState<T>(initialValue: T, optionsDry?: SignalOptions<T> | string): ((newState: T) => void) | null;
+    createSignalHooks<T>(initialValue: T, options?: SignalOptions<T>): SignalLifecycleHook<T> | null;
     readonly hasDevtools: boolean;
 };

package/dist/signals/base/Devtools.js

@@ -2,46 +2,73 @@ 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" ? { name: optionsDry } : optionsDry;
         if (options.isDisabled)
             return null;
-        let createStateDevtools = SharedOptions.DEVTOOLS?.state;
+        const createStateDevtools = SharedOptions.DEVTOOLS?.state;
         if (!createStateDevtools)
             return null;
-        const key = createKey(options.name, options.base);
-        let stateDevtools = options._skipValues?.includes(initialValue)
-            ? null
-            : createStateDevtools(key, initialValue);
-        return (newState) => {
-            if (options._skipValues?.includes(newState)) {
-                return;
-            }
+        const key = createKey(options.key ?? options.name, options.base);
+        let stateDevtools = null;
+        const push = (value) => {
             if (!stateDevtools) {
-                stateDevtools = createStateDevtools(key, newState);
+                stateDevtools = createStateDevtools(key, value);
                 return;
             }
-            stateDevtools(newState);
+            stateDevtools(value);
+        };
+        // Init
+        if (options.beforeDevtoolsPush) {
+            options.beforeDevtoolsPush(initialValue, push);
+        }
+        else {
+            push(initialValue);
+        }
+        return (newState) => {
+            if (options.beforeDevtoolsPush) {
+                options.beforeDevtoolsPush(newState, push);
+            }
+            else {
+                push(newState);
+            }
+        };
+    },
+    createSignalHooks(initialValue, options = {}) {
+        const stateDevtools = this.createState(initialValue, {
+            key: options.key,
+            name: options.name,
+            base: options.base,
+            isDisabled: options.isDisabled,
+            beforeDevtoolsPush: options.beforeDevtoolsPush,
+        });
+        if (!stateDevtools)
+            return null;
+        return {
+            onChange(newValue) {
+                stateDevtools(newValue);
+            },
+            onDispose() {
+                stateDevtools("$COMPLETED");
+            },
         };
     },
     get hasDevtools() {
         return !!SharedOptions.DEVTOOLS?.state;
     },
 };
-function createKey(name, base) {
+function createKey(key, base) {
     const i = Indexer.getIndex();
-    let key = '';
-    if (name?.includes('{scope}')) {
-        const scopeName = SharedOptions.getScopeName?.() || '#global';
-        name = name.replace('{scope}', scopeName);
+    let result = "";
+    if (key?.includes("{scope}")) {
+        const scopeName = SharedOptions.getScopeName?.() || "#global";
+        key = key.replace("{scope}", scopeName);
     }
-    if (base && name)
-        key += name.replace('{base}', base);
-    else if (!base && name)
-        key += name;
-    else if (base && !name)
-        key += `${base}/`;
-    key += `#i=${i}`;
-    return key;
+    if (base && key)
+        result += key.replace("{base}", base);
+    else if (!base && key)
+        result += key;
+    else if (base && !key)
+        result += `${base}/`;
+    result += `#i=${i}`;
+    return result;
 }

package/dist/signals/base/Indexer.js

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

package/dist/signals/base/ReadonlySignal.js

@@ -1,5 +1,5 @@
-import { SyncObservable } from "./SyncObservable";
 import { DependencyTracker } from "./DependencyTracker";
+import { SyncObservable } from "./SyncObservable";
 export class ReadonlySignal {
     rang = 0;
     obs;

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

@@ -1,5 +1,4 @@
-import { Observable, Subscriber, TeardownLogic } from "rxjs";
+import { Observable } from "rxjs";
 export declare class SyncObservable<T> extends Observable<T> {
-    constructor(subscribe?: (subscriber: Subscriber<T>) => TeardownLogic);
     get value(): T;
 }

package/dist/signals/base/SyncObservable.js

@@ -1,9 +1,6 @@
 import { Observable } from "rxjs";
-const empty = Symbol('EMPTY');
+const empty = Symbol("EMPTY");
 export class SyncObservable extends Observable {
-    constructor(subscribe) {
-        super(subscribe);
-    }
     get value() {
         let value = empty;
         const sub = this.subscribe((v) => {
@@ -11,7 +8,7 @@ export class SyncObservable extends Observable {
         });
         sub.unsubscribe();
         if (value === empty) {
-            throw new Error('No value emitted');
+            throw new Error("No value emitted");
         }
         return value;
     }

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

@@ -1,6 +1,6 @@
-export * from './Batcher';
-export * from './ComputeCache';
-export * from './DependencyTracker';
-export * from './Devtools';
-export * from './ReadonlySignal';
-export * from './SyncObservable';
+export * from "./Batcher";
+export * from "./DependencyTracker";
+export * from "./ComputeCache";
+export * from "./Devtools";
+export * from "./ReadonlySignal";
+export * from "./SyncObservable";

package/dist/signals/base/index.js

@@ -1,6 +1,6 @@
-export * from './Batcher';
-export * from './ComputeCache';
-export * from './DependencyTracker';
-export * from './Devtools';
-export * from './ReadonlySignal';
-export * from './SyncObservable';
+export * from "./Batcher";
+export * from "./DependencyTracker";
+export * from "./ComputeCache";
+export * from "./Devtools";
+export * from "./ReadonlySignal";
+export * from "./SyncObservable";

package/dist/signals/index.d.ts

@@ -1,4 +1,5 @@
-export * from './base';
-export * from './operators';
-export * from './react';
-export * from './signals';
+export * from "./base";
+export * from "./operators";
+export * from "./react";
+export * from "./signals";
+export * from "./types";

package/dist/signals/index.js

@@ -1,4 +1,5 @@
-export * from './base';
-export * from './operators';
-export * from './react';
-export * from './signals';
+export * from "./base";
+export * from "./operators";
+export * from "./react";
+export * from "./signals";
+export * from "./types";

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

@@ -1 +1 @@
-export * from './signalize';
+export * from "./signalize";

package/dist/signals/operators/index.js

@@ -1 +1 @@
-export * from './signalize';
+export * from "./signalize";

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

@@ -1 +1 @@
-export * from './useSignal';
+export * from "./useSignal";

package/dist/signals/react/index.js

@@ -1 +1 @@
-export * from './useSignal';
+export * from "./useSignal";

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

@@ -1,5 +1,4 @@
-import { StateDevtoolsOptions } from "../../common/devtools";
-import { ComputeFn } from "../../signals/types";
+import { ComputeFn, SignalOptionsOrKey } from "../../signals/types";
 export declare class Computed<T> {
     private _computeFn;
     private _state$;
@@ -9,11 +8,11 @@ export declare class Computed<T> {
      * Кеш для хранения вычисленного значения (без подписки) и его зависимостей
      */
     private _computeCache;
-    constructor(_computeFn: () => T, options?: StateDevtoolsOptions);
+    constructor(_computeFn: () => T, options?: SignalOptionsOrKey<T>);
     get(): T;
     peek(): T;
     private _start;
     private _stop;
     private static _EMPTY;
-    static create<T>(computeFn: () => T, options?: StateDevtoolsOptions): ComputeFn<T>;
+    static create<T>(computeFn: () => T, options?: SignalOptionsOrKey<T>): ComputeFn<T>;
 }