@fozy-labs/rx-toolkit 0.5.4 → 0.6.0

package/dist/query/core/resource/Resource.js

@@ -0,0 +1,340 @@
+import { Signal } from "../../../signals";
+import { toKeyed as toKeyedUtil } from "../../lib/toKeyed";
+import { CacheMap } from "../cache/CacheMap";
+import { QueryCacheEntry } from "../cache/QueryCacheEntry";
+import { CacheEntryRemovedError } from "../errors";
+import { Machine } from "../machine/Machine";
+import { ResourceAgent } from "./ResourceAgent";
+// ==================== Resource ====================
+/**
+ * Data-fetching abstraction with caching and SWR.
+ *
+ * Each unique set of serialized arguments maps to a single {@link QueryCacheEntry}.
+ * Entries are retained for `retentionTime` ms after the last subscriber unsubscribes.
+ *
+ * @template TArgs - Query argument type.
+ * @template TData - Query return data type.
+ */
+export class Resource {
+    _cache = new CacheMap();
+    /**
+     * Хранит последний добавленный кэш-энтер, для возможности реактивной подписки (с помощью getEntry$)
+     */
+    _lastEntry$ = Signal.state(null, { isDisabled: true });
+    /**
+     * Определяет общий статус ресурса
+     * - "idle": ресурса не активен, записей нет, getEntry$ возвращает null
+     * - "running": ресурс активен, есть хотя бы одна запись, getEntry$ может возвращать записи
+     */
+    _status$ = Signal.state("idle", { isDisabled: true });
+    _queryFn;
+    _key;
+    _retentionTime;
+    _serializeArgs;
+    _onCacheEntryAdded;
+    _onQueryStarted;
+    _beforeQuery;
+    constructor(config) {
+        this._queryFn = config.queryFn;
+        this._key = config.key;
+        this._retentionTime = config.retentionTime;
+        this._serializeArgs = config.serializeArgs;
+        this._onCacheEntryAdded = config.onCacheEntryAdded;
+        this._onQueryStarted = config.onQueryStarted;
+        this._beforeQuery = config.beforeQuery;
+        if (config.snapshot) {
+            for (const [key, snap] of Object.entries(config.snapshot.entries)) {
+                this._hydrateEntry(key, {
+                    args: snap.args,
+                    data: snap.data,
+                    updatedAt: snap.updatedAt,
+                    isStale: snap.isStale ?? false,
+                });
+            }
+        }
+    }
+    // ==================== Public API ====================
+    /**
+     * Execute a query with the given arguments.
+     *
+     * @param args - Query arguments.
+     * @param doForce - When `true`, forces a refresh even if data is cached.
+     */
+    trigger(args, doForce = false) {
+        this._getOrCreate(args, doForce);
+    }
+    /**
+     * Mark the entry as stale and trigger a background SWR refresh.
+     *
+     * @param args - Query arguments identifying the cache entry.
+     */
+    refresh(args) {
+        const keyed = this.toKeyed(args);
+        const entry = this._cache.get(keyed.key);
+        if (entry) {
+            entry.refresh();
+        }
+    }
+    /**
+     * Synchronously return the cache entry for the given arguments.
+     *
+     * @param args - Query arguments (or `void` when `TArgs` is `void`).
+     * @param doInitiate - When `true`, creates and starts the entry if absent.
+     * @returns The cache entry, or `null` if not found and `doInitiate` is `false`.
+     */
+    getEntry(args, doInitiate = false) {
+        const keyed = this.toKeyed(args);
+        const entry = this._cache.get(keyed.key);
+        if (entry) {
+            return entry;
+        }
+        if (doInitiate) {
+            return this._getOrCreate(keyed);
+        }
+        return null;
+    }
+    getEntry$(args, doInitiate = false) {
+        return Signal.compute(() => {
+            const keyed = this.toKeyed(args);
+            const status = this._status$();
+            if (status === "idle" && !doInitiate) {
+                return null;
+            }
+            const lastEntry = this._lastEntry$();
+            if (lastEntry?.keyedArgs.key === keyed.key) {
+                return lastEntry;
+            }
+            return this._cache.get(keyed.key) ?? null;
+        }, { isDisabled: true });
+    }
+    /**
+     * Create a reactive {@link ResourceAgent} that observes this resource
+     * and provides SWR-aware state transitions.
+     */
+    createAgent() {
+        return new ResourceAgent(this);
+    }
+    /**
+     * Serialize arguments into a cache key string.
+     *
+     * @param args - Query arguments.
+     * @returns The serialized key used for cache lookup.
+     */
+    serialize(args) {
+        return this.toKeyed(args).key;
+    }
+    /**
+     * Wrap arguments into a `{ value, key }` pair, avoiding repeated serialization.
+     *
+     * @param args - Query arguments.
+     * @returns A {@link Keyed} wrapper containing the original args and their cache key.
+     */
+    toKeyed(args) {
+        return toKeyedUtil(args, this._serializeArgs);
+    }
+    /** Iterate over all cache entries. */
+    getEntries() {
+        return this._cache.values();
+    }
+    /** Clear all cache entries. */
+    reset() {
+        for (const entry of this._cache.values()) {
+            entry.complete();
+        }
+        this._cache.clear();
+        this._status$.set("idle");
+        this._lastEntry$.set(null);
+    }
+    // ==================== Private ====================
+    /**
+     * Get an existing cache entry or create a new one.
+     *
+     * @internal Used by {@link ResourceAgent} and Command links.
+     * @param args - Query arguments.
+     * @param doForce - When `true`, forces a refresh on an existing entry.
+     */
+    _getOrCreate(args, doForce = false) {
+        const keyed = this.toKeyed(args);
+        const existing = this._cache.get(keyed.key);
+        if (existing) {
+            if (doForce)
+                existing.refresh();
+            return existing;
+        }
+        return this._createEntry(keyed);
+    }
+    _createEntry(keyed, initialMachine) {
+        // ── beforeQuery sync intercept ──
+        // If beforeQuery is set AND there's no snapshot (initialMachine), intercept
+        // to ask other tabs for data before executing queryFn.
+        if (!initialMachine && this._beforeQuery && this._key) {
+            return this._createEntryWithBeforeQuery(keyed);
+        }
+        return this._createEntryDirect(keyed, initialMachine);
+    }
+    /** Standard entry creation: queryFn auto-executes in constructor. */
+    _createEntryDirect(keyed, initialMachine) {
+        // Capture initial query promise for onQueryStarted lifecycle hook.
+        // During the QueryCacheEntry constructor, _execute() fires synchronously,
+        // calling wrappedQueryFn before `entry` is assigned. We save the promise
+        // in the `else` branch and fire onQueryStarted after construction.
+        // eslint-disable-next-line prefer-const -- assigned after constructor; closure reads it
+        let entry;
+        let initialQueryPromise = null;
+        const wrappedQueryFn = (keyedArgs, signal) => {
+            const promise = this._queryFn(keyedArgs.value, signal);
+            if (entry) {
+                // Subsequent calls (refresh / retry) — entry is already assigned
+                this._fireOnQueryStarted(entry, keyedArgs.value, promise);
+            }
+            else {
+                // Initial call during constructor — defer
+                initialQueryPromise = promise;
+            }
+            return promise;
+        };
+        entry = new QueryCacheEntry({
+            queryFn: wrappedQueryFn,
+            retentionTime: this._retentionTime,
+            keyedArgs: keyed,
+            resourceKey: this._key,
+            initialMachine,
+            beforeDevtoolsPush: undefined,
+        });
+        // Register in cache
+        this._cache.set(keyed.key, entry);
+        this._status$.set("running");
+        this._lastEntry$.set(entry);
+        // Cleanup: remove entry from cache when it completes (retention expired)
+        entry.completed$.subscribe(() => {
+            this._cache.delete(keyed.key);
+            if (this._cache.size === 0)
+                this._status$.set("idle");
+            if (this._lastEntry$() === entry) {
+                this._lastEntry$.set(null);
+            }
+        });
+        // Fire onCacheEntryAdded lifecycle hook
+        this._fireOnCacheEntryAdded(entry, keyed);
+        // Fire onQueryStarted for the initial query (deferred from constructor)
+        if (initialQueryPromise) {
+            this._fireOnQueryStarted(entry, keyed.value, initialQueryPromise);
+        }
+        return entry;
+    }
+    /** Entry creation with beforeQuery intercept: starts in pending, asks other tabs first. */
+    _createEntryWithBeforeQuery(keyed) {
+        const wrappedQueryFn = (keyedArgs, signal) => {
+            const promise = this._queryFn(keyedArgs.value, signal);
+            this._fireOnQueryStarted(entry, keyedArgs.value, promise);
+            return promise;
+        };
+        // Create entry with an explicit pending Machine to PREVENT auto-execute
+        const entry = new QueryCacheEntry({
+            queryFn: wrappedQueryFn,
+            retentionTime: this._retentionTime,
+            keyedArgs: keyed,
+            resourceKey: this._key,
+            initialMachine: Machine.pending(keyed.value),
+            beforeDevtoolsPush: undefined,
+        });
+        // Register in cache immediately (UI sees pending state)
+        this._cache.set(keyed.key, entry);
+        this._status$.set("running");
+        this._lastEntry$.set(entry);
+        entry.completed$.subscribe(() => {
+            this._cache.delete(keyed.key);
+            if (this._cache.size === 0)
+                this._status$.set("idle");
+            if (this._lastEntry$() === entry) {
+                this._lastEntry$.set(null);
+            }
+        });
+        this._fireOnCacheEntryAdded(entry, keyed);
+        // Ask other tabs for data, fall back to queryFn
+        this._beforeQuery(this._key, keyed.key)
+            .then((result) => {
+            if (result) {
+                const machine = entry.machine$.peek();
+                if (machine.status === "pending") {
+                    entry.set(machine.success(result.data));
+                }
+            }
+            else {
+                entry._execute();
+            }
+        })
+            .catch(() => {
+            entry._execute();
+        });
+        return entry;
+    }
+    _hydrateEntry(key, meta) {
+        const machine = Machine.fromSnapshot(meta, meta.isStale);
+        const keyed = toKeyedUtil(meta.args, this._serializeArgs);
+        // Verify key matches
+        if (keyed.key !== key) {
+            console.warn(`[rx-toolkit] Snapshot hydration skipped: expected key "${key}" but serialized args produced key "${keyed.key}".`);
+            return;
+        }
+        this._createEntry(keyed, machine);
+    }
+    _fireOnCacheEntryAdded(entry, keyed) {
+        if (!this._onCacheEntryAdded)
+            return;
+        // $cacheDataLoaded: resolves with data on first success, rejects if entry removed first
+        // $cacheEntryRemoved: resolves when entry is removed from cache
+        let resolveRemoved;
+        const $cacheEntryRemoved = new Promise((resolve) => {
+            resolveRemoved = resolve;
+        });
+        const $cacheDataLoaded = new Promise((resolve, reject) => {
+            // Watch the entry's state for the first success
+            const sub = entry.state$.obs.subscribe((machine) => {
+                if (machine.state.status === "success" || machine.state.status === "refreshing") {
+                    resolve(machine.state.data);
+                    sub.unsubscribe();
+                }
+            });
+            // If the entry is cleaned up before success, reject
+            entry.completed$.subscribe(() => {
+                sub.unsubscribe();
+                reject(new CacheEntryRemovedError("data loaded"));
+            });
+        });
+        // When entry is cleaned up, resolve $cacheEntryRemoved
+        entry.completed$.subscribe(() => {
+            resolveRemoved();
+        });
+        const ctx = {
+            entry,
+            $cacheDataLoaded,
+            $cacheEntryRemoved,
+        };
+        try {
+            const result = this._onCacheEntryAdded(keyed.value, ctx);
+            // Hook may be async — suppress unhandled rejection
+            void Promise.resolve(result).catch(() => { });
+        }
+        catch {
+            // Lifecycle errors are suppressed (per docs)
+        }
+    }
+    _fireOnQueryStarted(entry, args, queryPromise) {
+        if (!this._onQueryStarted)
+            return;
+        const $queryFulfilled = queryPromise.then((data) => ({ data }));
+        const ctx = {
+            entry,
+            $queryFulfilled,
+        };
+        try {
+            const result = this._onQueryStarted(args, ctx);
+            // Hook may be async — suppress unhandled rejection
+            void Promise.resolve(result).catch(() => { });
+        }
+        catch {
+            // Lifecycle errors are suppressed (per docs)
+        }
+    }
+}

package/dist/query/core/resource/ResourceAgent.d.ts

@@ -0,0 +1,37 @@
+import type { ArgsOrVoidOrSkip, IResourceAgent, TResourceAgentState } from "../../../query/types";
+import type { Resource } from "./Resource";
+/**
+ * Reactive observer for a {@link Resource} with SWR behaviour.
+ *
+ * The agent tracks a single cache entry at a time, deriving a flat
+ * {@link TResourceAgentState} signal. When arguments change via {@link start},
+ * the previous entry's data is preserved as stale fallback (SWR).
+ *
+ * @template TArgs - Query argument type.
+ * @template TData - Query return data type.
+ */
+export declare class ResourceAgent<TArgs, TData> implements IResourceAgent<TArgs, TData> {
+    private readonly _resource;
+    private readonly _tracking$;
+    readonly state$: import("../../../signals").ComputeFn<TResourceAgentState<TArgs, TData>>;
+    private _previous$;
+    private _isStarted;
+    private _isMarked;
+    constructor(resource: Resource<TArgs, TData>);
+    get args(): TArgs | null;
+    /**
+     */
+    start(): void;
+    /**
+     */
+    set(args: ArgsOrVoidOrSkip<TArgs>, mark: boolean): void;
+    /** Retry the last failed query. Only meaningful after an error state. */
+    retry: () => void;
+    /** Force a background refresh of the current entry (SWR). */
+    refresh: () => void;
+    private _deriveState;
+    private _promoteToPrevious;
+    private _deriveNotIdleState;
+    private _createPendingState;
+    private _idleState;
+}

package/dist/query/core/resource/ResourceAgent.js

@@ -0,0 +1,179 @@
+import { Batcher, Signal } from "../../../signals";
+import { SKIP } from "../../constants";
+/**
+ * Reactive observer for a {@link Resource} with SWR behaviour.
+ *
+ * The agent tracks a single cache entry at a time, deriving a flat
+ * {@link TResourceAgentState} signal. When arguments change via {@link start},
+ * the previous entry's data is preserved as stale fallback (SWR).
+ *
+ * @template TArgs - Query argument type.
+ * @template TData - Query return data type.
+ */
+export class ResourceAgent {
+    _resource;
+    _tracking$ = Signal.state(null, { isDisabled: true });
+    state$ = Signal.compute(() => this._deriveState(), {
+        isDisabled: true,
+    });
+    _previous$ = null;
+    _isStarted = false;
+    _isMarked = false;
+    constructor(resource) {
+        this._resource = resource;
+    }
+    get args() {
+        return this._tracking$.peek()?.keyed.value ?? null;
+    }
+    // ==================== Public API (IResourceAgent) ====================
+    /**
+     */
+    start() {
+        this._isStarted = true;
+        const tracking = this._tracking$.peek();
+        if (!tracking) {
+            return;
+        }
+        this._resource.trigger(tracking.keyed);
+    }
+    /**
+     */
+    set(args, mark) {
+        this._isMarked = mark ?? false;
+        const tracking = this._tracking$.peek();
+        if (args === SKIP) {
+            if (!tracking)
+                return;
+            this._previous$ = null;
+            this._tracking$.set(null);
+            return;
+        }
+        const keyed = this._resource.toKeyed(args);
+        // Early return if same args
+        if (tracking && tracking.keyed.key === keyed.key) {
+            return;
+        }
+        if (tracking) {
+            this._promoteToPrevious(tracking);
+        }
+        const newEntry = this._resource.getEntry$(keyed);
+        Batcher.run(() => {
+            if (this._isStarted) {
+                this._resource.trigger(keyed);
+            }
+            this._tracking$.set({
+                keyed,
+                current$: newEntry,
+            });
+        });
+    }
+    /** Retry the last failed query. Only meaningful after an error state. */
+    retry = () => {
+        this._tracking$.peek()?.current$.peek()?.retry();
+    };
+    /** Force a background refresh of the current entry (SWR). */
+    refresh = () => {
+        this._tracking$.peek()?.current$.peek()?.refresh();
+    };
+    // ==================== Private ====================
+    _deriveState() {
+        const tracking = this._tracking$();
+        if (!tracking)
+            return this._idleState;
+        const entry = tracking.current$();
+        if (!entry) {
+            if (this._isStarted) {
+                queueMicrotask(() => this._resource.trigger(tracking.keyed));
+                return this._createPendingState(tracking.keyed.value);
+            }
+            if (this._isMarked) {
+                return this._createPendingState(tracking.keyed.value);
+            }
+            return this._idleState;
+        }
+        const machine = entry.machine$();
+        return this._deriveNotIdleState(machine.state);
+    }
+    _promoteToPrevious(tracking) {
+        if (!tracking)
+            return;
+        const current$ = tracking.current$;
+        if (current$) {
+            const status = current$.peek()?.machine$.peek().state.status;
+            if (status === "success" || status === "refreshing" || status === "refresh-error") {
+                this._previous$ = current$;
+            }
+            else {
+                this._previous$ = null;
+            }
+        }
+    }
+    _deriveNotIdleState(machineState) {
+        let agentStatus = machineState.status;
+        let data = machineState.data;
+        const previousEntry = this._previous$?.();
+        // SWR: pending + previous data → refreshing
+        if (machineState.status === "pending" && previousEntry) {
+            const prevMachine = previousEntry.machine$();
+            if (prevMachine.state.data != null) {
+                agentStatus = "refreshing";
+                data = prevMachine.state.data;
+            }
+        }
+        // SWR: error + previous data → keep stale data
+        if (machineState.status === "error" && previousEntry) {
+            const prevMachine = previousEntry.machine$();
+            if (prevMachine.state.data != null) {
+                data = prevMachine.state.data;
+            }
+        }
+        // Clear previous once success
+        if (machineState.status === "success") {
+            this._previous$ = null;
+        }
+        return {
+            status: agentStatus,
+            data,
+            error: machineState.error,
+            args: machineState.args,
+            isLoading: agentStatus === "pending" || agentStatus === "refreshing",
+            isInitialLoading: agentStatus === "pending",
+            isRefreshing: agentStatus === "refreshing",
+            isRefreshError: agentStatus === "refresh-error",
+            isSuccess: agentStatus === "success",
+            isError: agentStatus === "error" || agentStatus === "refresh-error",
+            retry: this.retry,
+            refresh: this.refresh,
+        };
+    }
+    _createPendingState(args) {
+        return {
+            status: "pending",
+            data: null,
+            error: null,
+            args,
+            isLoading: true,
+            isInitialLoading: true,
+            isRefreshing: false,
+            isRefreshError: false,
+            isSuccess: false,
+            isError: false,
+            retry: this.retry,
+            refresh: this.refresh,
+        };
+    }
+    _idleState = {
+        status: "idle",
+        data: null,
+        error: null,
+        args: null,
+        isLoading: false,
+        isInitialLoading: false,
+        isRefreshing: false,
+        isRefreshError: false,
+        isSuccess: false,
+        isError: false,
+        retry: this.retry,
+        refresh: this.refresh,
+    };
+}

package/dist/query/core/resource/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Resource";
+export * from "./ResourceAgent";

package/dist/query/core/resource/index.js

@@ -0,0 +1,2 @@
+export * from "./Resource";
+export * from "./ResourceAgent";

package/dist/query/core/snapshoter/Snapshoter.d.ts

@@ -0,0 +1,22 @@
+import type { TApiSnapshot, TResourceSnapshot } from "../../../query/types";
+import type { Resource } from "../resource/Resource";
+export interface TSnapshoterOptions {
+    initialSnapshot: TApiSnapshot | null;
+    snapshotValidTime: number | false;
+    keyPrefix: string | null;
+}
+export declare class Snapshoter {
+    private readonly _initialSnapshot;
+    private readonly _snapshotValidTime;
+    private readonly _keyPrefix;
+    constructor(options: TSnapshoterOptions);
+    /**
+     * Build hydration entries for a resource from the initial snapshot.
+     * Returns `undefined` when no matching snapshot data exists.
+     */
+    hydrateResource(snapshotKey: string | undefined, resourceSnapshotValidTime?: number | false): TResourceSnapshot | undefined;
+    /**
+     * Collects a serializable snapshot of all registered resources.
+     */
+    getSnapshot(resources: Resource<any, any>[]): TApiSnapshot;
+}

package/dist/query/core/snapshoter/Snapshoter.js

@@ -0,0 +1,78 @@
+import { CURRENT_SNAPSHOT_VERSION } from "../../constants";
+export class Snapshoter {
+    _initialSnapshot;
+    _snapshotValidTime;
+    _keyPrefix;
+    constructor(options) {
+        this._initialSnapshot = options.initialSnapshot;
+        this._snapshotValidTime = options.snapshotValidTime;
+        this._keyPrefix = options.keyPrefix;
+    }
+    /**
+     * Build hydration entries for a resource from the initial snapshot.
+     * Returns `undefined` when no matching snapshot data exists.
+     */
+    hydrateResource(snapshotKey, resourceSnapshotValidTime) {
+        if (!this._initialSnapshot || !snapshotKey || !this._initialSnapshot.resources[snapshotKey]) {
+            return undefined;
+        }
+        const resSnapshot = this._initialSnapshot.resources[snapshotKey];
+        const entries = {};
+        const now = Date.now();
+        const effectiveSnapshotValidTime = resourceSnapshotValidTime !== undefined ? resourceSnapshotValidTime : this._snapshotValidTime;
+        for (const [entryKey, snapEntry] of Object.entries(resSnapshot.entries)) {
+            if (snapEntry.status !== "success")
+                continue;
+            let isStale = false;
+            if (effectiveSnapshotValidTime !== false && typeof snapEntry.updatedAt === "number") {
+                isStale = snapEntry.updatedAt + effectiveSnapshotValidTime < now;
+            }
+            entries[entryKey] = {
+                status: snapEntry.status,
+                args: snapEntry.args,
+                data: snapEntry.data,
+                updatedAt: snapEntry.updatedAt,
+                isStale,
+            };
+        }
+        return Object.keys(entries).length > 0 ? { entries } : undefined;
+    }
+    /**
+     * Collects a serializable snapshot of all registered resources.
+     */
+    getSnapshot(resources) {
+        const resourcesMap = {};
+        for (const resource of resources) {
+            const resourceKey = resource._key;
+            if (!resourceKey)
+                continue;
+            const entries = {};
+            let hasEntries = false;
+            for (const entry of resource.getEntries()) {
+                const { state } = entry.peek();
+                if (state.status !== "success" && state.status !== "refresh-error")
+                    continue;
+                entries[entry.keyedArgs.key] = {
+                    status: state.status,
+                    args: state.args,
+                    data: state.data,
+                    updatedAt: state.updatedAt,
+                };
+                hasEntries = true;
+            }
+            let snapshotResourceKey = resourceKey;
+            if (this._keyPrefix != null && snapshotResourceKey.startsWith(`${this._keyPrefix}/`)) {
+                snapshotResourceKey = snapshotResourceKey.slice(this._keyPrefix.length + 1);
+            }
+            if (hasEntries) {
+                resourcesMap[snapshotResourceKey] = { entries };
+            }
+        }
+        return {
+            version: CURRENT_SNAPSHOT_VERSION,
+            keyPrefix: this._keyPrefix,
+            timestamp: Date.now(),
+            resources: resourcesMap,
+        };
+    }
+}

package/dist/query/core/snapshoter/index.d.ts

@@ -0,0 +1,2 @@
+export { Snapshoter } from "./Snapshoter";
+export type { TSnapshoterOptions } from "./Snapshoter";

package/dist/query/core/snapshoter/index.js

@@ -0,0 +1 @@
+export { Snapshoter } from "./Snapshoter";