@fozy-labs/rx-toolkit 0.5.4 → 0.6.0

package/dist/query/core/cache/QueryCacheEntry.js

@@ -0,0 +1,136 @@
+import { Machine } from "../machine/Machine";
+import { CacheEntry } from "./CacheEntry";
+// ==================== QueryCacheEntry ====================
+export class QueryCacheEntry extends CacheEntry {
+    keyedArgs;
+    machine$;
+    _queryFn;
+    _abortController = null;
+    constructor(options) {
+        const machine = options.initialMachine ?? Machine.pending(options.keyedArgs.value);
+        const devtoolsKey = options.resourceKey
+            ? `${options.resourceKey}:${options.keyedArgs.key}`
+            : options.keyedArgs.key;
+        super(machine, {
+            retentionTime: options.retentionTime,
+            devtoolsKey,
+            beforeDevtoolsPush: options.beforeDevtoolsPush,
+        });
+        this.keyedArgs = options.keyedArgs;
+        this._queryFn = options.queryFn;
+        this.machine$ = this.state$;
+        // Auto-execute queryFn when no initial state is provided
+        if (!options.initialMachine) {
+            this._execute();
+        }
+    }
+    /** Transition to refreshing and re-fetch data. Valid from success or refresh-error. */
+    refresh() {
+        const machine = this.machine$.peek();
+        if (machine.status !== "success" && machine.status !== "refresh-error") {
+            console.warn(`[QueryCacheEntry] refresh() called in invalid state: ${machine.status}`);
+            return;
+        }
+        this.set(machine.refresh());
+        this._execute();
+    }
+    /** Re-execute query after error. Valid from error state only. */
+    retry() {
+        const machine = this.machine$.peek();
+        if (machine.status !== "error") {
+            console.warn(`[QueryCacheEntry] retry() called in invalid state: ${machine.status}`);
+            return;
+        }
+        this.set(machine.retry());
+        this._execute();
+    }
+    /** Create an optimistic patch. Returns null if state has no data. */
+    createPatch(patchFn) {
+        const machine = this.machine$.peek();
+        if (machine.status !== "success" && machine.status !== "refreshing" && machine.status !== "refresh-error") {
+            console.warn(`[QueryCacheEntry] createPatch() called in invalid state: ${machine.status}`);
+            return null;
+        }
+        const onSettle = () => {
+            const current = this.machine$.peek();
+            if ((current.status === "success" ||
+                current.status === "refreshing" ||
+                current.status === "refresh-error") &&
+                current.patchState) {
+                const finished = current.finishPatch();
+                this.set(finished);
+                if (finished.patchState?.isConsistencyViolation) {
+                    this.refresh();
+                }
+            }
+        };
+        const { machine: newMachine, handle } = machine.createPatch(patchFn, onSettle);
+        this.set(newMachine);
+        return handle;
+    }
+    /** Abort any in-flight request before completing the entry. */
+    complete() {
+        this._abortController?.abort();
+        super.complete();
+    }
+    // ==================== Private ====================
+    /** @internal Called by Resource when beforeQuery intercept needs to trigger the query. */
+    _execute() {
+        // Abort any in-flight request
+        this._abortController?.abort();
+        const controller = new AbortController();
+        this._abortController = controller;
+        const machine = this.machine$.peek();
+        switch (machine.status) {
+            case "success":
+                this.set(machine.refresh());
+                break;
+            case "refresh-error":
+                this.set(machine.refresh());
+                break;
+            case "pending":
+            case "refreshing":
+                break;
+            case "error":
+                return;
+            default:
+                console.warn(`[QueryCacheEntry] executed in unexpected state: ${machine.status}`);
+        }
+        this._queryFn(this.keyedArgs, controller.signal)
+            .then((data) => {
+            if (controller.signal.aborted)
+                return;
+            const machine = this.machine$.peek();
+            switch (machine.status) {
+                case "pending":
+                    this.set(machine.success(data));
+                    break;
+                case "refreshing": {
+                    const rebased = machine.rebase(data);
+                    this.set(rebased);
+                    if (rebased.patchState?.isConsistencyViolation) {
+                        this.refresh();
+                    }
+                    break;
+                }
+                default:
+                    console.warn(`[QueryCacheEntry] received data in unexpected state: ${machine.status}`);
+            }
+        })
+            .catch((error) => {
+            if (controller.signal.aborted)
+                return;
+            const machine = this.machine$.peek();
+            switch (machine.status) {
+                case "pending":
+                    this.set(machine.fail(error));
+                    break;
+                case "refreshing":
+                    this.set(machine.fail(error));
+                    break;
+                default:
+                    console.warn(`[QueryCacheEntry] received error in unexpected state: ${machine.status}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,3 @@
+export * from "./CacheEntry";
+export * from "./CacheMap";
+export * from "./QueryCacheEntry";

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

@@ -0,0 +1,3 @@
+export * from "./CacheEntry";
+export * from "./CacheMap";
+export * from "./QueryCacheEntry";

package/dist/query/core/command/Command.d.ts

@@ -0,0 +1,67 @@
+import type { Args, ICommand, ICommandAgent, ICommandConfig } from "../../../query/types";
+import { QueryCacheEntry } from "../cache/QueryCacheEntry";
+/**
+ * Abstraction for write operations (mutations).
+ *
+ * Manages cache entries, link-based optimistic/update patches on related resources,
+ * and lifecycle hooks (`onCacheEntryAdded`, `onQueryStarted`).
+ *
+ * @template TArgs - The argument type accepted by the mutation.
+ * @template TData - The data type returned by the mutation.
+ *
+ * @see {@link https://github.com/AcademyCity/rx-toolkit/blob/main/docs/query/api/command.md | Command API docs}
+ */
+export declare class Command<TArgs, TData> implements ICommand<TArgs, TData> {
+    private readonly _cache;
+    private readonly _lastEntry$;
+    private readonly _status$;
+    private readonly _queryFn;
+    readonly _key: string | undefined;
+    private readonly _linkManager;
+    private readonly _retentionTime;
+    private readonly _onCacheEntryAdded;
+    private readonly _onQueryStarted;
+    private _keyCounter;
+    constructor(config: ICommandConfig<TArgs, TData>);
+    /**
+     * Imperatively execute the mutation.
+     *
+     * Applies optimistic patches, runs `queryFn`, then commits/rolls-back
+     * patches and invalidates linked resources on success/failure.
+     *
+     * @param argsOrKeyed - Plain arguments or a {@link Keyed} wrapper.
+     * @param key - Optional cache-entry key. Auto-generated when omitted.
+     * @returns A promise that resolves with the mutation result.
+     */
+    trigger(argsOrKeyed: Args<TArgs>, key?: string): Promise<TData>;
+    /**
+     * Synchronously retrieve a cache entry by key.
+     *
+     * @param key - The cache-entry key.
+     * @returns The matching {@link QueryCacheEntry}, or `null` if none exists.
+     */
+    getEntry(key: string): QueryCacheEntry<TArgs, TData> | null;
+    /**
+     * Reactive variant of {@link getEntry}.
+     *
+     * Reads an internal signal so that callers in a reactive context
+     * (e.g. `computed`, `effect`) re-evaluate when the cache changes.
+     *
+     * @param key - The cache-entry key.
+     * @returns The matching {@link QueryCacheEntry}, or `null` if none exists.
+     */
+    getEntry$(key: string): QueryCacheEntry<TArgs, TData> | null;
+    /**
+     * Create a reactive agent that observes this command's state.
+     *
+     * @param key - Optional key to bind the agent to a specific cache entry.
+     * @returns A new {@link ICommandAgent} instance.
+     */
+    createAgent(key?: string): ICommandAgent<TArgs, TData>;
+    /** Clear all cache entries. Called by createApi.resetAll(). */
+    reset(): void;
+    private _generateKey;
+    private _toKeyed;
+    private _fireOnCacheEntryAdded;
+    private _fireOnQueryStarted;
+}

package/dist/query/core/command/Command.js

@@ -0,0 +1,253 @@
+import { Signal } from "../../../signals";
+import { KEYED_BRAND } from "../../constants";
+import { isKeyed } from "../../lib/toKeyed";
+import { CacheMap } from "../cache/CacheMap";
+import { QueryCacheEntry } from "../cache/QueryCacheEntry";
+import { CacheEntryRemovedError } from "../errors";
+import { CommandAgent } from "./CommandAgent";
+import { LinkManager } from "./LinkManager";
+// ==================== Command ====================
+/**
+ * Abstraction for write operations (mutations).
+ *
+ * Manages cache entries, link-based optimistic/update patches on related resources,
+ * and lifecycle hooks (`onCacheEntryAdded`, `onQueryStarted`).
+ *
+ * @template TArgs - The argument type accepted by the mutation.
+ * @template TData - The data type returned by the mutation.
+ *
+ * @see {@link https://github.com/AcademyCity/rx-toolkit/blob/main/docs/query/api/command.md | Command API docs}
+ */
+export class Command {
+    _cache = new CacheMap();
+    _lastEntry$ = Signal.state(null, { isDisabled: true });
+    _status$ = Signal.state("idle", { isDisabled: true });
+    _queryFn;
+    _key;
+    _linkManager;
+    _retentionTime;
+    _onCacheEntryAdded;
+    _onQueryStarted;
+    _keyCounter = 0;
+    constructor(config) {
+        this._queryFn = config.queryFn;
+        this._key = config.key;
+        this._linkManager = new LinkManager(config.links);
+        this._retentionTime = config.retentionTime;
+        this._onCacheEntryAdded = config.onCacheEntryAdded;
+        this._onQueryStarted = config.onQueryStarted;
+    }
+    // ==================== Public API (ICommand) ====================
+    /**
+     * Imperatively execute the mutation.
+     *
+     * Applies optimistic patches, runs `queryFn`, then commits/rolls-back
+     * patches and invalidates linked resources on success/failure.
+     *
+     * @param argsOrKeyed - Plain arguments or a {@link Keyed} wrapper.
+     * @param key - Optional cache-entry key. Auto-generated when omitted.
+     * @returns A promise that resolves with the mutation result.
+     */
+    trigger(argsOrKeyed, key) {
+        const keyed = this._toKeyed(argsOrKeyed, key);
+        const args = keyed.value;
+        const entryKey = keyed.key;
+        const linkManager = this._linkManager;
+        // 1. Apply optimistic patches (synchronous, before queryFn)
+        const patchHandles = linkManager.applyOptimisticPatches(args);
+        // 2. Set up result promise (resolved/rejected by link handlers after queryFn settles)
+        let resolveResult;
+        let rejectResult;
+        const resultPromise = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        // Clean up existing entry for the same key, if any
+        const existing = this._cache.get(entryKey);
+        if (existing) {
+            existing.complete();
+        }
+        // eslint-disable-next-line prefer-const -- assigned after constructor; closure reads it
+        let entry;
+        let initialQueryPromise = null;
+        let linksSettled = false;
+        const wrappedQueryFn = (keyedArgs, _signal) => {
+            const promise = this._queryFn(keyedArgs.value);
+            // Chain link handlers only on the initial trigger, not on QCE refresh
+            if (!linksSettled) {
+                promise.then((result) => {
+                    linksSettled = true;
+                    linkManager.settle(args, patchHandles, { status: "fulfilled", value: result });
+                    resolveResult(result);
+                }, (error) => {
+                    linksSettled = true;
+                    linkManager.settle(args, patchHandles, { status: "rejected", reason: error });
+                    rejectResult(error);
+                });
+            }
+            // Lifecycle: onQueryStarted
+            if (entry) {
+                this._fireOnQueryStarted(entry, keyedArgs.value, promise);
+            }
+            else {
+                initialQueryPromise = promise;
+            }
+            return promise;
+        };
+        // 4. Create QueryCacheEntry — auto-executes wrappedQueryFn in constructor
+        entry = new QueryCacheEntry({
+            queryFn: wrappedQueryFn,
+            retentionTime: this._retentionTime,
+            keyedArgs: keyed,
+            resourceKey: this._key,
+        });
+        // Register in cache
+        this._cache.set(entryKey, entry);
+        this._status$.set("running");
+        this._lastEntry$.set(entry);
+        // Cleanup: remove entry from cache when it completes
+        entry.completed$.subscribe(() => {
+            // Guard: only remove if THIS entry is still the current one for the key
+            if (this._cache.get(entryKey) === entry) {
+                this._cache.delete(entryKey);
+                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 resultPromise;
+    }
+    /**
+     * Synchronously retrieve a cache entry by key.
+     *
+     * @param key - The cache-entry key.
+     * @returns The matching {@link QueryCacheEntry}, or `null` if none exists.
+     */
+    getEntry(key) {
+        return this._cache.get(key) ?? null;
+    }
+    /**
+     * Reactive variant of {@link getEntry}.
+     *
+     * Reads an internal signal so that callers in a reactive context
+     * (e.g. `computed`, `effect`) re-evaluate when the cache changes.
+     *
+     * @param key - The cache-entry key.
+     * @returns The matching {@link QueryCacheEntry}, or `null` if none exists.
+     */
+    getEntry$(key) {
+        let entry = null;
+        const signal$ = Signal.compute(() => {
+            const status = this._status$();
+            if (status === "idle") {
+                return null;
+            }
+            // Fast path: already found in a previous evaluation
+            if (entry) {
+                return entry;
+            }
+            const lastEntry = this._lastEntry$();
+            if (lastEntry?.keyedArgs.key === key) {
+                entry = lastEntry;
+                return entry;
+            }
+            return this._cache.get(key) ?? null;
+        }, { isDisabled: true });
+        return signal$();
+    }
+    /**
+     * Create a reactive agent that observes this command's state.
+     *
+     * @param key - Optional key to bind the agent to a specific cache entry.
+     * @returns A new {@link ICommandAgent} instance.
+     */
+    createAgent(key) {
+        return new CommandAgent(this, key);
+    }
+    /** Clear all cache entries. Called by createApi.resetAll(). */
+    reset() {
+        const entries = [...this._cache.values()];
+        this._cache.clear();
+        this._status$.set("idle");
+        this._lastEntry$.set(null);
+        for (const entry of entries) {
+            entry.complete();
+        }
+    }
+    // ==================== Private — Key Generation ====================
+    _generateKey() {
+        return `${Date.now()}-${this._keyCounter++}`;
+    }
+    _toKeyed(args, key) {
+        if (isKeyed(args)) {
+            return args;
+        }
+        return {
+            value: args,
+            key: key ?? this._generateKey(),
+            [KEYED_BRAND]: true,
+        };
+    }
+    // ==================== Private — Lifecycle Hooks ====================
+    _fireOnCacheEntryAdded(entry, keyed) {
+        if (!this._onCacheEntryAdded)
+            return;
+        let resolveRemoved;
+        const $cacheEntryRemoved = new Promise((resolve) => {
+            resolveRemoved = resolve;
+        });
+        const $cacheDataLoaded = new Promise((resolve, reject) => {
+            const sub = entry.state$.obs.subscribe((machine) => {
+                if (machine.state.status === "success" || machine.state.status === "refreshing") {
+                    resolve(machine.state.data);
+                    sub.unsubscribe();
+                }
+            });
+            entry.completed$.subscribe(() => {
+                sub.unsubscribe();
+                reject(new CacheEntryRemovedError("data loaded"));
+            });
+        });
+        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/command/CommandAgent.d.ts

@@ -0,0 +1,17 @@
+import type { Args, ICommandAgent, IQueryCacheEntry, TCommandAgentState } from "../../../query/types";
+import type { ComputeFn } from "../../../signals/types";
+export interface ICommandForAgent<TArgs, TData> {
+    trigger(args: Args<TArgs>, key?: string): Promise<TData>;
+    getEntry$(key: string): IQueryCacheEntry<TArgs, TData> | null;
+}
+export declare class CommandAgent<TArgs, TData> implements ICommandAgent<TArgs, TData> {
+    private readonly _command;
+    private readonly _tracking$;
+    readonly state$: ComputeFn<TCommandAgentState<TArgs, TData>>;
+    constructor(command: ICommandForAgent<TArgs, TData>, key?: string);
+    trigger(args: Args<TArgs>, key?: string): Promise<TData>;
+    setKey(key: string): void;
+    private _observeKey;
+    private _deriveState;
+    private _createIdleState;
+}

package/dist/query/core/command/CommandAgent.js

@@ -0,0 +1,67 @@
+import { Signal } from "../../../signals";
+export class CommandAgent {
+    _command;
+    _tracking$;
+    state$;
+    constructor(command, key) {
+        this._command = command;
+        this._tracking$ = Signal.state(null, { isDisabled: true });
+        this.state$ = Signal.compute(() => {
+            const tracking = this._tracking$();
+            if (!tracking)
+                return this._createIdleState();
+            const entry = tracking.current$();
+            if (!entry)
+                return this._createIdleState();
+            const machineState = entry.state$().state;
+            return this._deriveState(entry, machineState);
+        }, { isDisabled: true });
+        if (key != null) {
+            this.setKey(key);
+        }
+    }
+    async trigger(args, key) {
+        const result = this._command.trigger(args, key);
+        if (key != null) {
+            this._observeKey(key);
+        }
+        return result;
+    }
+    setKey(key) {
+        this._observeKey(key);
+    }
+    // ==================== Private ====================
+    _observeKey(key) {
+        const tracking = this._tracking$.peek();
+        if (tracking && tracking.key === key)
+            return;
+        const current$ = Signal.compute(() => this._command.getEntry$(key), { isDisabled: true });
+        this._tracking$.set({ key, current$ });
+    }
+    _deriveState(entry, machineState) {
+        // Command agent uses a simplified status mapping:
+        // refreshing / refresh-error are not applicable to commands → map to pending.
+        const machineStatus = machineState.status;
+        const status = machineStatus === "refreshing" || machineStatus === "refresh-error" ? "pending" : machineStatus;
+        return {
+            status,
+            data: machineState.data,
+            error: machineState.error,
+            args: machineState.args,
+            isLoading: status === "pending",
+            isSuccess: status === "success",
+            isError: status === "error",
+        };
+    }
+    _createIdleState() {
+        return {
+            status: "idle",
+            data: null,
+            error: null,
+            args: null,
+            isLoading: false,
+            isSuccess: false,
+            isError: false,
+        };
+    }
+}

package/dist/query/core/command/LinkManager.d.ts

@@ -0,0 +1,24 @@
+import type { IPatchHandle, TLinkConfig } from "../../../query/types";
+/**
+ * Encapsulates link-based patching and invalidation logic for a {@link Command}.
+ *
+ * Responsible for:
+ * - Applying optimistic patches before the mutation runs.
+ * - Applying update patches after successful mutation.
+ * - Invalidating / refreshing linked resources.
+ *
+ * @template TArgs - The argument type of the owning Command.
+ * @template TData - The data type returned by the owning Command.
+ */
+export declare class LinkManager<TArgs, TData> {
+    private readonly _links;
+    constructor(_links: TLinkConfig<TArgs, TData, any, any>[]);
+    applyOptimisticPatches(args: TArgs): IPatchHandle[];
+    applyUpdatePatches(args: TArgs, result: TData): void;
+    invalidateResources(args: TArgs): void;
+    /**
+     * Handle the settled result of a mutation: commit or rollback optimistic
+     * patches, apply update patches, and invalidate linked resources.
+     */
+    settle(args: TArgs, patchHandles: IPatchHandle[], result: PromiseSettledResult<TData>): void;
+}

package/dist/query/core/command/LinkManager.js

@@ -0,0 +1,71 @@
+// ==================== LinkManager ====================
+/**
+ * Encapsulates link-based patching and invalidation logic for a {@link Command}.
+ *
+ * Responsible for:
+ * - Applying optimistic patches before the mutation runs.
+ * - Applying update patches after successful mutation.
+ * - Invalidating / refreshing linked resources.
+ *
+ * @template TArgs - The argument type of the owning Command.
+ * @template TData - The data type returned by the owning Command.
+ */
+export class LinkManager {
+    _links;
+    constructor(_links) {
+        this._links = _links;
+    }
+    applyOptimisticPatches(args) {
+        const handles = [];
+        for (const link of this._links) {
+            if (!link.optimisticUpdate)
+                continue;
+            const forwardedArgs = link.forwardArgs(args);
+            const entry = link.resource.getEntry(forwardedArgs);
+            const handle = entry?.createPatch((draft) => {
+                link.optimisticUpdate(draft, args);
+            });
+            if (handle)
+                handles.push(handle);
+        }
+        return handles;
+    }
+    applyUpdatePatches(args, result) {
+        for (const link of this._links) {
+            if (!link.update)
+                continue;
+            const forwardedArgs = link.forwardArgs(args);
+            const entry = link.resource.getEntry(forwardedArgs);
+            const handle = entry?.createPatch((draft) => {
+                link.update(draft, args, result);
+            });
+            if (handle)
+                handle.commit();
+        }
+    }
+    invalidateResources(args) {
+        for (const link of this._links) {
+            if (!link.invalidate)
+                continue;
+            const forwardedArgs = link.forwardArgs(args);
+            const resource = link.resource;
+            resource.refresh(forwardedArgs);
+        }
+    }
+    /**
+     * Handle the settled result of a mutation: commit or rollback optimistic
+     * patches, apply update patches, and invalidate linked resources.
+     */
+    settle(args, patchHandles, result) {
+        if (result.status === "fulfilled") {
+            this.applyUpdatePatches(args, result.value);
+            for (const h of patchHandles)
+                h.commit();
+            this.invalidateResources(args);
+        }
+        else {
+            for (const h of patchHandles)
+                h.abort();
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+export * from "./Command";
+export * from "./CommandAgent";

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

@@ -0,0 +1,2 @@
+export * from "./Command";
+export * from "./CommandAgent";

package/dist/query/core/errors/CacheEntryRemovedError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Thrown when a cache entry is removed before an async operation settles.
+ */
+export declare class CacheEntryRemovedError extends Error {
+    readonly name = "CacheEntryRemovedError";
+    constructor(detail: string);
+}

package/dist/query/core/errors/CacheEntryRemovedError.js

@@ -0,0 +1,9 @@
+/**
+ * Thrown when a cache entry is removed before an async operation settles.
+ */
+export class CacheEntryRemovedError extends Error {
+    name = "CacheEntryRemovedError";
+    constructor(detail) {
+        super(`Cache entry removed before ${detail}`);
+    }
+}

package/dist/query/core/errors/MachineStateError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Thrown when a Machine method requires state that doesn't exist
+ * (e.g. createPatch on a state without data, finishPatch without patchState).
+ */
+export declare class MachineStateError extends Error {
+    readonly name = "MachineStateError";
+    constructor(method: string, detail: string);
+}