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

package/dist/query-v2/core/resource/ResourceV2.d.ts

@@ -0,0 +1,120 @@
+import type { IResourceV2Agent } from "../../../query-v2/types/agent.types";
+import type { ICacheEntry } from "../../../query-v2/types/cache.types";
+import type { TOnCacheEntryAdded, TOnQueryStarted } from "../../../query-v2/types/lifecycle.types";
+import type { TMachine, TPatchFn } from "../../../query-v2/types/machine.types";
+import type { IResourceV2 } from "../../../query-v2/types/resource.types";
+import type { TBeforeDevtoolsPushFn, TCompareArgsFn, TQueryFn, TSerializeArgsFn } from "../../../query-v2/types/shared.types";
+import { CacheEntry } from "../common/CacheEntry";
+import type { TMachineInstance } from "../machines/Machine";
+export interface ResourceV2Config<TArgs, TData, TError = Error> {
+    key?: string;
+    keyPrefix?: string;
+    keyStrategy?: "serialize" | "compare";
+    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;
+}
+/**
+ * Cache-backed resource manager.
+ * Orchestrates queries, caching, lifecycle hooks, GC, and optimistic patches for a single resource type.
+ */
+export declare class ResourceV2<TArgs, TData, TError = Error> implements IResourceV2<TArgs, TData, TError> {
+    private readonly _cache;
+    private readonly _queryFn;
+    private readonly _lifecycleHooks;
+    private readonly _serializeArgs;
+    private readonly _compareArg;
+    private readonly _keyStrategy;
+    private readonly _cacheLifetime;
+    private readonly _beforeDevtoolsPush?;
+    private readonly _key?;
+    private readonly _keyPrefix?;
+    /** In-flight queries keyed by serialized args — for dedup + abort */
+    private readonly _inFlight;
+    /** Cache lifetime timers keyed by serialized args */
+    private readonly _gcTimers;
+    /** Refresh error listeners (used by Agent for refreshError tracking) */
+    private readonly _refreshErrorListeners;
+    constructor(config: ResourceV2Config<TArgs, TData, TError>);
+    /**
+     * Create an agent that tracks a single cache entry with reactive state (SWR).
+     *
+     * @returns A new agent bound to this resource.
+     */
+    createAgent(): IResourceV2Agent<TArgs, TData, TError>;
+    /**
+     * Execute a query for the given args, returning the cache entry.
+     * Deduplicates concurrent calls for the same args unless `doForce` is set.
+     *
+     * @param args - Query arguments (used as cache key).
+     * @param doForce - If true, bypass dedup and re-execute the query.
+     * @returns The cache entry after query initiation.
+     */
+    query(args: TArgs, doForce?: boolean): Promise<ICacheEntry<TData, TError>>;
+    /**
+     * Reactive query — read machine state as a signal dependency.
+     * Initiates the query if not already cached.
+     *
+     * @param args - Query arguments.
+     * @returns Current machine state (registers a reactive subscription).
+     */
+    query$(args: TArgs, doForce?: boolean): TMachine<TData, TError>;
+    /**
+     * Get the cache entry for the given args without initiating a query (unless `doInitiate` is set).
+     *
+     * @param args - Query arguments.
+     * @returns The cache entry, or `null` if not cached.
+     */
+    entry(args: TArgs, doInitiate?: boolean): ICacheEntry<TData, TError> | null;
+    entry$(args: TArgs, doInitiate?: boolean): TMachine<TData, TError>;
+    invalidate(args: TArgs): void;
+    compareArgs(a: TArgs, b: TArgs): boolean;
+    /** Public key getter for API registry */
+    get key(): string | undefined;
+    /** Public keyStrategy getter for snapshot validation */
+    get keyStrategy(): "serialize" | "compare";
+    /** Serialize args to string key */
+    getSerializedKey(args: TArgs): string;
+    /** Iterate cache entries — for snapshot */
+    cacheEntries(): Iterable<[TArgs | string, CacheEntry<TData, TError>]>;
+    /** Hydrate a cache entry from snapshot data */
+    hydrateEntry(args: TArgs, machine: TMachineInstance<TData, TError>): void;
+    /** Check if cache entry exists for given args */
+    hasEntry(args: TArgs): boolean;
+    /** Pre-populate cache with data */
+    populateEntry(args: TArgs, data: TData): void;
+    /** Create an optimistic patch on a cache entry */
+    createEntryPatch(args: TArgs, patchFn: TPatchFn<TData>): {
+        commit: () => void;
+        abort: () => void;
+    } | null;
+    /** Lock a cache entry — prevent GC eviction. Returns unlock function. */
+    lockEntry(args: TArgs): {
+        unlock: () => void;
+    };
+    /** Subscribe to refresh error events (used by Agent) */
+    onRefreshError(listener: (args: TArgs, error: TError) => void): () => void;
+    /** Reset the entire cache — aborts in-flight requests, clears GC timers, completes all entries. */
+    resetCache(): void;
+    /**
+     * Schedule GC for a cache entry after cacheLifetime.
+     * Called when subscriber count drops to 0.
+     */
+    scheduleGc(args: TArgs): void;
+    /**
+     * Cancel pending GC for a cache entry.
+     * Called when a new subscriber appears.
+     */
+    cancelGc(args: TArgs): void;
+    private _cancelGcTimer;
+    private _evictEntry;
+    private _executeQuery;
+    private _executeRefresh;
+    private _buildCacheEntryOptions;
+}

package/dist/query-v2/core/resource/ResourceV2.js

@@ -0,0 +1,464 @@
+import { shallowEqual } from "../../../common/utils/shallowEqual";
+import { SKIP } from "../../../query-v2/lib/SKIP_TOKEN";
+import { stableStringify } from "../../../query-v2/lib/stableStringify";
+import { Batcher } from "../../../signals";
+import { CacheEntry } from "../common/CacheEntry";
+import { CacheMap } from "../common/CacheMap";
+import { LifecycleHooks } from "../common/LifecycleHooks";
+import { MachineIdle } from "../machines/MachineIdle";
+import { MachineRefreshing } from "../machines/MachineRefreshing";
+import { MachineSuccess } from "../machines/MachineSuccess";
+import { MachineWithData } from "../machines/MachineWithData";
+import { ResourceV2Agent } from "./ResourceV2Agent";
+/**
+ * Cache-backed resource manager.
+ * Orchestrates queries, caching, lifecycle hooks, GC, and optimistic patches for a single resource type.
+ */
+export class ResourceV2 {
+    _cache;
+    _queryFn;
+    _lifecycleHooks;
+    _serializeArgs;
+    _compareArg;
+    _keyStrategy;
+    _cacheLifetime;
+    _beforeDevtoolsPush;
+    _key;
+    _keyPrefix;
+    /** In-flight queries keyed by serialized args — for dedup + abort */
+    _inFlight = new Map();
+    /** Cache lifetime timers keyed by serialized args */
+    _gcTimers = new Map();
+    /** Refresh error listeners (used by Agent for refreshError tracking) */
+    _refreshErrorListeners = new Set();
+    constructor(config) {
+        this._queryFn = config.queryFn;
+        this._serializeArgs = config.serializeArgs ?? stableStringify;
+        this._compareArg = config.compareArg ?? shallowEqual;
+        this._keyStrategy = config.keyStrategy ?? "serialize";
+        this._cacheLifetime = config.cacheLifetime ?? 60_000;
+        this._beforeDevtoolsPush = config.beforeDevtoolsPush;
+        this._key = config.key;
+        this._keyPrefix = config.keyPrefix;
+        this._cache = CacheMap.create({
+            keyStrategy: this._keyStrategy,
+            serializeArgs: this._serializeArgs,
+            compareArg: this._compareArg,
+            doCacheArgs: config.doCacheArgs ?? false,
+        });
+        this._lifecycleHooks = new LifecycleHooks({
+            onCacheEntryAdded: config.onCacheEntryAdded,
+            onQueryStarted: config.onQueryStarted,
+            serializeArgs: this._serializeArgs,
+        });
+    }
+    /**
+     * Create an agent that tracks a single cache entry with reactive state (SWR).
+     *
+     * @returns A new agent bound to this resource.
+     */
+    createAgent() {
+        return new ResourceV2Agent(this);
+    }
+    /**
+     * Execute a query for the given args, returning the cache entry.
+     * Deduplicates concurrent calls for the same args unless `doForce` is set.
+     *
+     * @param args - Query arguments (used as cache key).
+     * @param doForce - If true, bypass dedup and re-execute the query.
+     * @returns The cache entry after query initiation.
+     */
+    async query(args, doForce) {
+        // SKIP check
+        if (args === SKIP) {
+            throw new Error("SKIP_TOKEN is not valid for direct query()");
+        }
+        const key = this._serializeArgs(args);
+        // Cache hit — return existing entry (unless force)
+        const existing = this._cache.get(args);
+        if (existing && !doForce) {
+            const machine = existing.peek();
+            // If already success or pending or refreshing, return the entry
+            if (machine.state.status !== "idle") {
+                return existing;
+            }
+        }
+        // Query dedup — if already in-flight for same args, return same promise
+        if (!doForce) {
+            const flight = this._inFlight.get(key);
+            if (flight) {
+                return flight.promise;
+            }
+        }
+        // Cancel existing in-flight for same args (ADR-4 Layer 1)
+        const existingFlight = this._inFlight.get(key);
+        if (existingFlight) {
+            existingFlight.abortController.abort();
+            this._inFlight.delete(key);
+        }
+        // Cancel any pending GC timer for these args
+        this._cancelGcTimer(key);
+        const abortController = new AbortController();
+        const isNewEntry = !existing;
+        // Create or reuse entry inside Batcher for atomic updates
+        let cacheEntry;
+        // Set up entry and pending state
+        Batcher.run(() => {
+            if (isNewEntry || doForce) {
+                if (existing && doForce) {
+                    cacheEntry = existing;
+                    // Transition to refreshing or pending based on current state
+                    const current = cacheEntry.peek();
+                    if (current instanceof MachineSuccess) {
+                        const refreshing = current.invalidate();
+                        cacheEntry.set(refreshing);
+                    }
+                    else if (current instanceof MachineRefreshing) {
+                        // Already refreshing — it'll be re-queried
+                    }
+                    else {
+                        const idle = MachineIdle.create();
+                        const pending = idle.start(args);
+                        cacheEntry.set(pending);
+                    }
+                }
+                else {
+                    // New entry
+                    const idle = MachineIdle.create();
+                    const pending = idle.start(args);
+                    cacheEntry = new CacheEntry(pending, this._buildCacheEntryOptions(args));
+                    this._cache.set(args, cacheEntry);
+                    // Fire onCacheEntryAdded for new entries
+                    this._lifecycleHooks.fireCacheEntryAdded(args, () => cacheEntry.peek());
+                }
+            }
+            else {
+                cacheEntry = existing;
+                const current = cacheEntry.peek();
+                const pending = current.start(args);
+                cacheEntry.set(pending);
+            }
+            // Fire onQueryStarted
+            this._lifecycleHooks.fireQueryStarted(args, () => cacheEntry);
+        });
+        // Execute queryFn
+        const promise = this._executeQuery(args, key, cacheEntry, abortController);
+        this._inFlight.set(key, { promise: promise, abortController });
+        return promise;
+    }
+    /**
+     * Reactive query — read machine state as a signal dependency.
+     * Initiates the query if not already cached.
+     *
+     * @param args - Query arguments.
+     * @returns Current machine state (registers a reactive subscription).
+     */
+    query$(args, doForce) {
+        if (args === SKIP) {
+            return MachineIdle.create().state;
+        }
+        // Trigger query (fire-and-forget) and read entry signal reactively
+        const entryResult = this._cache.get(args);
+        if (!entryResult) {
+            // Initiate query
+            this.query(args, doForce);
+            // Return idle while it's being initiated
+            const newEntry = this._cache.get(args);
+            if (newEntry) {
+                return newEntry.machine$().state;
+            }
+            return MachineIdle.create().state;
+        }
+        if (doForce) {
+            this.query(args, true);
+        }
+        // Reactive read — registers signal dependency
+        return entryResult.machine$().state;
+    }
+    /**
+     * Get the cache entry for the given args without initiating a query (unless `doInitiate` is set).
+     *
+     * @param args - Query arguments.
+     * @returns The cache entry, or `null` if not cached.
+     */
+    entry(args, doInitiate) {
+        const existing = this._cache.get(args);
+        if (existing) {
+            return existing;
+        }
+        if (doInitiate) {
+            // Fire-and-forget query initiation
+            this.query(args);
+            return this._cache.get(args) ?? null;
+        }
+        return null;
+    }
+    entry$(args, doInitiate) {
+        if (args === SKIP) {
+            return MachineIdle.create().state;
+        }
+        const existing = this._cache.get(args);
+        if (!existing && doInitiate) {
+            this.query(args);
+            const created = this._cache.get(args);
+            if (created) {
+                return created.machine$().state;
+            }
+        }
+        if (existing) {
+            return existing.machine$().state;
+        }
+        return MachineIdle.create().state;
+    }
+    invalidate(args) {
+        const existing = this._cache.get(args);
+        if (!existing)
+            return;
+        const machine = existing.peek();
+        // Only invalidate from success state
+        if (!(machine instanceof MachineSuccess))
+            return;
+        const key = this._serializeArgs(args);
+        // Abort any existing in-flight for these args (ADR-4 Layer 1)
+        const flight = this._inFlight.get(key);
+        if (flight) {
+            flight.abortController.abort();
+            this._inFlight.delete(key);
+        }
+        const abortController = new AbortController();
+        Batcher.run(() => {
+            const refreshing = machine.invalidate();
+            existing.set(refreshing);
+            this._lifecycleHooks.fireQueryStarted(args, () => existing);
+        });
+        const promise = this._executeRefresh(args, key, existing, abortController);
+        this._inFlight.set(key, { promise, abortController });
+    }
+    compareArgs(a, b) {
+        if (this._keyStrategy === "compare") {
+            return this._compareArg(a, b);
+        }
+        return this._serializeArgs(a) === this._serializeArgs(b);
+    }
+    /** Public key getter for API registry */
+    get key() {
+        return this._key;
+    }
+    /** Public keyStrategy getter for snapshot validation */
+    get keyStrategy() {
+        return this._keyStrategy;
+    }
+    /** Serialize args to string key */
+    getSerializedKey(args) {
+        return this._serializeArgs(args);
+    }
+    /** Iterate cache entries — for snapshot */
+    cacheEntries() {
+        return this._cache.entries();
+    }
+    /** Hydrate a cache entry from snapshot data */
+    hydrateEntry(args, machine) {
+        const existing = this._cache.get(args);
+        if (existing)
+            return; // Don't overwrite existing entries
+        const entry = new CacheEntry(machine, this._buildCacheEntryOptions(args));
+        this._cache.set(args, entry);
+        // Fire lifecycle for hydrated entries
+        this._lifecycleHooks.fireCacheEntryAdded(args, () => entry.peek());
+        if (machine.state.status === "success") {
+            this._lifecycleHooks.resolveCacheDataLoaded(args, machine.state.data);
+        }
+    }
+    /** Check if cache entry exists for given args */
+    hasEntry(args) {
+        return this._cache.has(args);
+    }
+    /** Pre-populate cache with data */
+    populateEntry(args, data) {
+        const existing = this._cache.get(args);
+        if (existing) {
+            const success = MachineSuccess.create(data, args);
+            existing.set(success);
+            return;
+        }
+        const success = MachineSuccess.create(data, args);
+        const entry = new CacheEntry(success, this._buildCacheEntryOptions(args));
+        this._cache.set(args, entry);
+    }
+    /** Create an optimistic patch on a cache entry */
+    createEntryPatch(args, patchFn) {
+        const entry = this._cache.get(args);
+        if (!entry)
+            return null;
+        const machine = entry.peek();
+        if (!(machine instanceof MachineWithData))
+            return null;
+        const { machine: patchedMachine, patch } = machine.createPatch(patchFn);
+        entry.set(patchedMachine);
+        return {
+            commit: () => {
+                const current = entry.peek();
+                if (current instanceof MachineWithData) {
+                    const finished = current.finishPatch("commit", patch);
+                    entry.set(finished);
+                }
+            },
+            abort: () => {
+                const current = entry.peek();
+                if (current instanceof MachineWithData) {
+                    const finished = current.finishPatch("abort", patch);
+                    entry.set(finished);
+                }
+            },
+        };
+    }
+    /** Lock a cache entry — prevent GC eviction. Returns unlock function. */
+    lockEntry(args) {
+        this.cancelGc(args);
+        return {
+            unlock: () => {
+                // Re-schedule GC (will be cancelled again if still subscribed)
+                this.scheduleGc(args);
+            },
+        };
+    }
+    /** Subscribe to refresh error events (used by Agent) */
+    onRefreshError(listener) {
+        this._refreshErrorListeners.add(listener);
+        return () => {
+            this._refreshErrorListeners.delete(listener);
+        };
+    }
+    /** Reset the entire cache — aborts in-flight requests, clears GC timers, completes all entries. */
+    resetCache() {
+        // Abort all in-flight requests
+        for (const [, flight] of this._inFlight) {
+            flight.abortController.abort();
+        }
+        this._inFlight.clear();
+        // Clear all GC timers
+        for (const [, timer] of this._gcTimers) {
+            clearTimeout(timer);
+        }
+        this._gcTimers.clear();
+        // Complete all cache entries
+        for (const entry of this._cache.values()) {
+            entry.complete();
+        }
+        // Clear lifecycle hooks
+        this._lifecycleHooks.clearAll();
+        // Clear the cache map
+        this._cache.clear();
+    }
+    /**
+     * Schedule GC for a cache entry after cacheLifetime.
+     * Called when subscriber count drops to 0.
+     */
+    scheduleGc(args) {
+        const key = this._serializeArgs(args);
+        this._cancelGcTimer(key);
+        this._gcTimers.set(key, setTimeout(() => {
+            this._gcTimers.delete(key);
+            this._evictEntry(args, key);
+        }, this._cacheLifetime));
+    }
+    /**
+     * Cancel pending GC for a cache entry.
+     * Called when a new subscriber appears.
+     */
+    cancelGc(args) {
+        const key = this._serializeArgs(args);
+        this._cancelGcTimer(key);
+    }
+    // --- Private helpers ---
+    _cancelGcTimer(key) {
+        const timer = this._gcTimers.get(key);
+        if (timer != null) {
+            clearTimeout(timer);
+            this._gcTimers.delete(key);
+        }
+    }
+    _evictEntry(args, key) {
+        const entry = this._cache.get(args);
+        if (!entry)
+            return;
+        // Abort in-flight if any
+        const flight = this._inFlight.get(key);
+        if (flight) {
+            flight.abortController.abort();
+            this._inFlight.delete(key);
+        }
+        // Fire lifecycle removal
+        this._lifecycleHooks.fireCacheEntryRemoved(args);
+        // Complete the entry (ADR-4 Layer 3)
+        entry.complete();
+        // Remove from cache
+        this._cache.delete(args);
+    }
+    async _executeQuery(args, key, cacheEntry, abortController) {
+        try {
+            const data = await this._queryFn(args, {
+                abortSignal: abortController.signal,
+            });
+            // If aborted after await, don't process result
+            if (abortController.signal.aborted) {
+                return cacheEntry;
+            }
+            Batcher.run(() => {
+                const current = cacheEntry.peek();
+                if (current.state.status === "pending") {
+                    const success = current.successHappened(data);
+                    cacheEntry.set(success);
+                }
+                else if (current.state.status === "refreshing") {
+                    const success = current.successHappened(data);
+                    cacheEntry.set(success);
+                }
+            });
+            this._lifecycleHooks.resolveCacheDataLoaded(args, data);
+            this._lifecycleHooks.resolveQueryFulfilled(data);
+        }
+        catch (error) {
+            if (abortController.signal.aborted) {
+                this._lifecycleHooks.rejectQueryFulfilled(error);
+                return cacheEntry;
+            }
+            Batcher.run(() => {
+                const current = cacheEntry.peek();
+                if (current.state.status === "pending") {
+                    const errorMachine = current.errorHappened(error);
+                    cacheEntry.set(errorMachine);
+                }
+                else if (current.state.status === "refreshing") {
+                    // ADR-2: Preserve stale data
+                    const success = current.errorHappened(error);
+                    cacheEntry.set(success);
+                    // Notify refresh error listeners (used by Agent)
+                    for (const listener of this._refreshErrorListeners) {
+                        listener(args, error);
+                    }
+                }
+            });
+            this._lifecycleHooks.rejectQueryFulfilled(error);
+        }
+        finally {
+            this._inFlight.delete(key);
+        }
+        return cacheEntry;
+    }
+    async _executeRefresh(args, key, cacheEntry, abortController) {
+        return this._executeQuery(args, key, cacheEntry, abortController);
+    }
+    _buildCacheEntryOptions(args) {
+        const parts = [];
+        if (this._keyPrefix)
+            parts.push(this._keyPrefix);
+        if (this._key)
+            parts.push(this._key);
+        parts.push(this._serializeArgs(args));
+        return {
+            keyParts: parts.length > 0 ? parts : undefined,
+            beforeDevtoolsPush: this._beforeDevtoolsPush,
+        };
+    }
+}

package/dist/query-v2/core/resource/ResourceV2Agent.d.ts

@@ -0,0 +1,26 @@
+import { type SKIP_TOKEN } from "../../../query-v2/lib/SKIP_TOKEN";
+import type { IResourceV2Agent, IResourceV2AgentState } from "../../../query-v2/types/agent.types";
+import type { ComputeFn } from "../../../signals";
+import type { ResourceV2 } from "./ResourceV2";
+/**
+ * Agent that tracks a single cache entry with reactive state, designed for React hook consumption.
+ * Provides SWR (stale-while-revalidate) semantics by keeping previous data while new data loads.
+ */
+export declare class ResourceV2Agent<TArgs, TData, TError = Error> implements IResourceV2Agent<TArgs, TData, TError> {
+    private readonly _resource;
+    private readonly _tracking$;
+    private readonly _refreshError$;
+    private readonly _state$;
+    private readonly _unsubRefreshError;
+    private _currentArgs;
+    constructor(resource: ResourceV2<TArgs, TData, TError>);
+    /** Computed reactive state signal — projects CacheEntry machine state into a flat agent state object. */
+    get state$(): ComputeFn<IResourceV2AgentState<TArgs, TData, TError>>;
+    /**
+     * Start (or re-start) the agent with new args. Skips if args are unchanged.
+     *
+     * @param args - Query arguments, or `SKIP_TOKEN` to do nothing.
+     */
+    start(args: TArgs | SKIP_TOKEN): Promise<void>;
+    compareArgs(a: TArgs, b: TArgs): boolean;
+}