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

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

@@ -0,0 +1,132 @@
+import { SKIP } from "../../../query-v2/lib/SKIP_TOKEN";
+import { Signal } from "../../../signals";
+/**
+ * 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 class ResourceV2Agent {
+    _resource;
+    _tracking$;
+    _refreshError$;
+    _state$;
+    _unsubRefreshError;
+    _currentArgs = null;
+    constructor(resource) {
+        this._resource = resource;
+        // Agent signals are internal derived state for React hooks — only CacheEntry signals belong in devtools
+        this._tracking$ = Signal.state({ previous: null, current: null }, { isDisabled: true });
+        // Agent signal — excluded from devtools; only CacheEntry signals represent canonical cache state
+        this._refreshError$ = Signal.state(null, { isDisabled: true });
+        // Subscribe to refresh errors from the resource
+        this._unsubRefreshError = this._resource.onRefreshError((args, error) => {
+            if (this._currentArgs !== null && this._resource.compareArgs(this._currentArgs, args)) {
+                this._refreshError$.set(error);
+            }
+        });
+        // Agent signal — excluded from devtools; only CacheEntry signals represent canonical cache state
+        this._state$ = Signal.compute(() => {
+            const { previous, current } = this._tracking$();
+            if (!current) {
+                return {
+                    status: "idle",
+                    data: null,
+                    error: null,
+                    args: null,
+                    isLoading: false,
+                    isInitialLoading: false,
+                    isRefreshing: false,
+                    isSuccess: false,
+                    isError: false,
+                    refreshError: this._refreshError$(),
+                };
+            }
+            // Read machine$ reactively — this is the key reactive subscription
+            const machine = current.machine$();
+            const machineState = machine.state;
+            const status = machineState.status;
+            // Determine previous data for SWR
+            let previousData = null;
+            if (previous) {
+                const prevMachine = previous.machine$();
+                const prevState = prevMachine.state;
+                if (prevState.data != null) {
+                    previousData = prevState.data;
+                }
+            }
+            const currentData = machineState.data;
+            const isLoading = status === "pending" || status === "refreshing";
+            const isRefreshing = status === "refreshing";
+            // SWR: use previous data if current is loading and has no data yet
+            const data = currentData ?? (isLoading ? previousData : null);
+            const hasPreviousData = previousData !== null;
+            const isInitialLoading = isLoading && !hasPreviousData && currentData === null;
+            const isSuccess = data !== null;
+            const isError = status === "error";
+            const error = isError ? machineState.error : null;
+            return {
+                status,
+                data,
+                error,
+                args: machineState.args ?? null,
+                isLoading,
+                isInitialLoading,
+                isRefreshing,
+                isSuccess,
+                isError,
+                refreshError: this._refreshError$(),
+            };
+        }, { isDisabled: true });
+    }
+    /** Computed reactive state signal — projects CacheEntry machine state into a flat agent state object. */
+    get state$() {
+        return this._state$;
+    }
+    /**
+     * Start (or re-start) the agent with new args. Skips if args are unchanged.
+     *
+     * @param args - Query arguments, or `SKIP_TOKEN` to do nothing.
+     */
+    async start(args) {
+        // SKIP: no-op
+        if (args === SKIP) {
+            return;
+        }
+        const typedArgs = args;
+        // Same args check — skip if unchanged
+        if (this._currentArgs !== null && this._resource.compareArgs(this._currentArgs, typedArgs)) {
+            return;
+        }
+        this._currentArgs = typedArgs;
+        // Query the resource — get a cache entry
+        const entryPromise = this._resource.query(typedArgs);
+        // Get the entry synchronously from the resource
+        const entry = this._resource.entry(typedArgs);
+        // Swap previous/current
+        const oldTracking = this._tracking$.peek();
+        this._tracking$.set({
+            previous: oldTracking.current,
+            current: entry,
+        });
+        // Wait for the query to resolve and then clear previous
+        try {
+            await entryPromise;
+            // Clear refreshError on successful query completion
+            this._refreshError$.set(null);
+        }
+        catch {
+            // query() shouldn't reject, but handle gracefully
+        }
+        // Clear previous after current resolves (success or error)
+        // Only if current hasn't changed (latest-wins)
+        const currentTracking = this._tracking$.peek();
+        if (currentTracking.current === entry) {
+            this._tracking$.set({
+                previous: null,
+                current: entry,
+            });
+        }
+    }
+    compareArgs(a, b) {
+        return this._resource.compareArgs(a, b);
+    }
+}

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

@@ -0,0 +1,2 @@
+export { ResourceV2, type ResourceV2Config } from "./ResourceV2";
+export { ResourceV2Agent } from "./ResourceV2Agent";

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

@@ -0,0 +1,2 @@
+export { ResourceV2 } from "./ResourceV2";
+export { ResourceV2Agent } from "./ResourceV2Agent";

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

@@ -0,0 +1,11 @@
+export { SKIP, type SKIP_TOKEN } from "./lib/SKIP_TOKEN";
+export { NO_VALUE } from "./lib/NO_VALUE";
+export type { NO_VALUE as NO_VALUE_TYPE } from "./lib/NO_VALUE";
+export { stableStringify } from "./lib/stableStringify";
+export { Machine, type TMachineInstance, MachineIdle, MachinePending, MachineSuccess, MachineError, MachineRefreshing, MachineWithData, Patcher, CacheEntry, type CacheEntryOptions, CacheMap, type TCacheMapInstance, LifecycleHooks, ResourceV2, type ResourceV2Config, ResourceV2Agent, } from "./core";
+export { createApi } from "./api/createApi";
+export { ReactHooksPlugin } from "./plugins/ReactHooksPlugin";
+export type { IReactHooksPluginContributions } from "./plugins/ReactHooksPlugin";
+export { useResourceV2Agent, useResourceV2Ref } from "./react";
+export { getSnapshot, hydrateSnapshot, CURRENT_SNAPSHOT_VERSION } from "./snapshot/Snapshot";
+export * from "./types";

package/dist/query-v2/index.js

@@ -0,0 +1,17 @@
+// Sentinel tokens
+export { SKIP } from "./lib/SKIP_TOKEN";
+export { NO_VALUE } from "./lib/NO_VALUE";
+// Utilities
+export { stableStringify } from "./lib/stableStringify";
+// Core — Machine classes
+export { Machine, MachineIdle, MachinePending, MachineSuccess, MachineError, MachineRefreshing, MachineWithData, Patcher, CacheEntry, CacheMap, LifecycleHooks, ResourceV2, ResourceV2Agent, } from "./core";
+// API factory
+export { createApi } from "./api/createApi";
+// Plugins
+export { ReactHooksPlugin } from "./plugins/ReactHooksPlugin";
+// React hooks (standalone)
+export { useResourceV2Agent, useResourceV2Ref } from "./react";
+// Snapshot
+export { getSnapshot, hydrateSnapshot, CURRENT_SNAPSHOT_VERSION } from "./snapshot/Snapshot";
+// Types
+export * from "./types";

package/dist/query-v2/lib/NO_VALUE.d.ts

@@ -0,0 +1,2 @@
+export declare const NO_VALUE: unique symbol;
+export type NO_VALUE = typeof NO_VALUE;

package/dist/query-v2/lib/NO_VALUE.js

@@ -0,0 +1 @@
+export const NO_VALUE = Symbol("NO_VALUE");

package/dist/query-v2/lib/SKIP_TOKEN.d.ts

@@ -0,0 +1,2 @@
+export declare const SKIP: unique symbol;
+export type SKIP_TOKEN = typeof SKIP;

package/dist/query-v2/lib/SKIP_TOKEN.js

@@ -0,0 +1 @@
+export const SKIP = Symbol("SKIP");

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

@@ -0,0 +1,4 @@
+export { SKIP, type SKIP_TOKEN } from "./SKIP_TOKEN";
+export { NO_VALUE } from "./NO_VALUE";
+export type { NO_VALUE as NO_VALUE_TYPE } from "./NO_VALUE";
+export { stableStringify } from "./stableStringify";

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

@@ -0,0 +1,3 @@
+export { SKIP } from "./SKIP_TOKEN";
+export { NO_VALUE } from "./NO_VALUE";
+export { stableStringify } from "./stableStringify";

package/dist/query-v2/lib/stableStringify.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deterministic JSON.stringify with sorted object keys.
+ * Used as the default serializeArgs for the 'serialize' key strategy.
+ *
+ * Handles: plain objects, arrays, primitives, null, undefined, nested structures.
+ * Does NOT handle: Date, Map, Set, RegExp (documented limitation).
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/query-v2/lib/stableStringify.js

@@ -0,0 +1,23 @@
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Deterministic JSON.stringify with sorted object keys.
+ * Used as the default serializeArgs for the 'serialize' key strategy.
+ *
+ * Handles: plain objects, arrays, primitives, null, undefined, nested structures.
+ * Does NOT handle: Date, Map, Set, RegExp (documented limitation).
+ */
+export function stableStringify(value) {
+    return JSON.stringify(value, (_, val) => {
+        if (isPlainObject(val)) {
+            return Object.keys(val)
+                .sort()
+                .reduce((acc, key) => {
+                acc[key] = val[key];
+                return acc;
+            }, {});
+        }
+        return val;
+    });
+}

package/dist/query-v2/plugins/ReactHooksPlugin.d.ts

@@ -0,0 +1,25 @@
+import type { ResourceV2 } from "../../query-v2/core/resource/ResourceV2";
+import type { SKIP_TOKEN } from "../../query-v2/lib/SKIP_TOKEN";
+import type { IResourceV2AgentState, IResourceV2Ref } from "../../query-v2/types/agent.types";
+import type { IPlugin, IPluginContext } from "../../query-v2/types/plugin.types";
+import type { IResourceV2Options } from "../../query-v2/types/resource.types";
+/** Contributions added by ReactHooksPlugin to resources */
+export interface IReactHooksPluginContributions<TArgs, TData, TError = Error> {
+    useResourceV2Agent(args: TArgs | SKIP_TOKEN): IResourceV2AgentState<TArgs, TData, TError>;
+    useResourceV2Ref(args: TArgs | SKIP_TOKEN): IResourceV2Ref<TArgs, TData, TError>;
+}
+declare module "../../query-v2/types/plugin.types" {
+    interface PluginContributionMap<TArgs, TData, TError> {
+        ReactHooksPlugin: IReactHooksPluginContributions<TArgs, TData, TError>;
+    }
+}
+/**
+ * Plugin that attaches `useResourceV2Agent` and `useResourceV2Ref` as methods on resources via `augmentResource`.
+ * Standalone imports from `@/query-v2/react/` are available as an alternative without requiring this plugin.
+ */
+export declare class ReactHooksPlugin implements IPlugin {
+    readonly name: "ReactHooksPlugin";
+    private _context;
+    install(context: IPluginContext): void;
+    augmentResource<TArgs, TData, TError>(res: ResourceV2<TArgs, TData, TError>, _options: IResourceV2Options<TArgs, TData, TError>): Record<string, unknown>;
+}

package/dist/query-v2/plugins/ReactHooksPlugin.js

@@ -0,0 +1,19 @@
+import { useResourceV2Agent } from "../../query-v2/react/useResourceV2Agent";
+import { useResourceV2Ref } from "../../query-v2/react/useResourceV2Ref";
+/**
+ * Plugin that attaches `useResourceV2Agent` and `useResourceV2Ref` as methods on resources via `augmentResource`.
+ * Standalone imports from `@/query-v2/react/` are available as an alternative without requiring this plugin.
+ */
+export class ReactHooksPlugin {
+    name = "ReactHooksPlugin";
+    _context = null;
+    install(context) {
+        this._context = context;
+    }
+    augmentResource(res, _options) {
+        return {
+            useResourceV2Agent: (args) => useResourceV2Agent(res, args),
+            useResourceV2Ref: (args) => useResourceV2Ref(res, args),
+        };
+    }
+}

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

@@ -0,0 +1 @@
+export type { IPlugin, IPluginContext, ExtractPluginContributions, PluginAugmentations, } from "../../query-v2/types/plugin.types";

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

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

package/dist/query-v2/react/__tests__/helpers.d.ts

@@ -0,0 +1,12 @@
+import { ResourceV2, type ResourceV2Config } from "../../../query-v2/core/resource/ResourceV2";
+export declare function controllableQueryFn<TArgs = unknown, TData = unknown>(): {
+    fn: import("vitest").Mock<(args: TArgs, { abortSignal }: {
+        abortSignal: AbortSignal;
+    }) => Promise<TData>>;
+    calls: {
+        args: TArgs;
+        resolve: (data: TData) => void;
+        reject: (error: Error) => void;
+    }[];
+};
+export declare function createTestResource<TArgs = unknown, TData = unknown, TError = Error>(config: Partial<ResourceV2Config<TArgs, TData, TError>> & Pick<ResourceV2Config<TArgs, TData, TError>, "queryFn">): ResourceV2<TArgs, TData, TError>;

package/dist/query-v2/react/__tests__/helpers.js

@@ -0,0 +1,33 @@
+import { vi } from "vitest";
+import { ResourceV2 } from "../../../query-v2/core/resource/ResourceV2";
+export function controllableQueryFn() {
+    const calls = [];
+    const fn = vi.fn((args, { abortSignal }) => {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const wrappedResolve = (data) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(data);
+                }
+            };
+            const wrappedReject = (error) => {
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+            };
+            calls.push({ args, resolve: wrappedResolve, reject: wrappedReject });
+            abortSignal.addEventListener("abort", () => {
+                wrappedReject(new DOMException("Aborted", "AbortError"));
+            });
+        });
+    });
+    return { fn, calls };
+}
+export function createTestResource(config) {
+    return new ResourceV2({
+        key: "test-resource",
+        ...config,
+    });
+}

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

@@ -0,0 +1,2 @@
+export { useResourceV2Agent } from "./useResourceV2Agent";
+export { useResourceV2Ref } from "./useResourceV2Ref";

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

@@ -0,0 +1,2 @@
+export { useResourceV2Agent } from "./useResourceV2Agent";
+export { useResourceV2Ref } from "./useResourceV2Ref";

package/dist/query-v2/react/useResourceV2Agent.d.ts

@@ -0,0 +1,12 @@
+import type { ResourceV2 } from "../../query-v2/core/resource/ResourceV2";
+import { type SKIP_TOKEN } from "../../query-v2/lib/SKIP_TOKEN";
+import type { IResourceV2AgentState } from "../../query-v2/types/agent.types";
+/**
+ * React hook that creates a ResourceV2Agent and returns its reactive state (SWR).
+ *
+ * @param resource - The resource to observe.
+ * @param args - Query arguments, or `SKIP_TOKEN` to skip the query.
+ * @returns Reactive agent state with `data`, `error`, status flags, etc.
+ * @see docs/query-v2/README.md
+ */
+export declare function useResourceV2Agent<TArgs, TData, TError>(resource: ResourceV2<TArgs, TData, TError>, args: TArgs | SKIP_TOKEN): IResourceV2AgentState<TArgs, TData, TError>;

package/dist/query-v2/react/useResourceV2Agent.js

@@ -0,0 +1,36 @@
+import React from "react";
+import { useConstant } from "../../common/react/useConstant";
+import { SKIP } from "../../query-v2/lib/SKIP_TOKEN";
+import { useSignal } from "../../signals/react/useSignal";
+/**
+ * React hook that creates a ResourceV2Agent and returns its reactive state (SWR).
+ *
+ * @param resource - The resource to observe.
+ * @param args - Query arguments, or `SKIP_TOKEN` to skip the query.
+ * @returns Reactive agent state with `data`, `error`, status flags, etc.
+ * @see docs/query-v2/README.md
+ */
+export function useResourceV2Agent(resource, args) {
+    const prevArgsRef = React.useRef(SKIP);
+    const agent = useConstant(() => {
+        const agent = resource.createAgent();
+        if (args !== SKIP) {
+            agent.start(args);
+        }
+        return agent;
+    });
+    if (!compareArgs(args, prevArgsRef.current, resource)) {
+        prevArgsRef.current = args;
+        if (args !== SKIP) {
+            agent.start(args);
+        }
+    }
+    return useSignal(agent.state$);
+}
+function compareArgs(args, prevArgs, resource) {
+    if (args === SKIP && prevArgs === SKIP)
+        return true;
+    if (args === SKIP || prevArgs === SKIP)
+        return false;
+    return resource.compareArgs(args, prevArgs);
+}

package/dist/query-v2/react/useResourceV2Ref.d.ts

@@ -0,0 +1,12 @@
+import type { ResourceV2 } from "../../query-v2/core/resource/ResourceV2";
+import { type SKIP_TOKEN } from "../../query-v2/lib/SKIP_TOKEN";
+import type { IResourceV2Ref } from "../../query-v2/types/agent.types";
+/**
+ * React hook that provides an imperative ref handle for a cache entry (lock, invalidate, patch, create).
+ *
+ * @param resource - The resource to access.
+ * @param args - Query arguments, or `SKIP_TOKEN` to return a no-op ref.
+ * @returns Imperative ref with `has`, `lock`, `invalidate`, `createPatch`, `create`.
+ * @see docs/query-v2/optimistic-updates.md
+ */
+export declare function useResourceV2Ref<TArgs, TData, TError>(resource: ResourceV2<TArgs, TData, TError>, args: TArgs | SKIP_TOKEN): IResourceV2Ref<TArgs, TData, TError>;

package/dist/query-v2/react/useResourceV2Ref.js

@@ -0,0 +1,57 @@
+import React from "react";
+import { shallowEqual } from "../../common/utils/shallowEqual";
+import { SKIP } from "../../query-v2/lib/SKIP_TOKEN";
+/**
+ * React hook that provides an imperative ref handle for a cache entry (lock, invalidate, patch, create).
+ *
+ * @param resource - The resource to access.
+ * @param args - Query arguments, or `SKIP_TOKEN` to return a no-op ref.
+ * @returns Imperative ref with `has`, `lock`, `invalidate`, `createPatch`, `create`.
+ * @see docs/query-v2/optimistic-updates.md
+ */
+export function useResourceV2Ref(resource, args) {
+    const stableArgsRef = React.useRef(args);
+    if (!shallowEqual(stableArgsRef.current, args)) {
+        stableArgsRef.current = args;
+    }
+    return React.useMemo(() => {
+        if (stableArgsRef.current === SKIP) {
+            return createSkippedRef();
+        }
+        return createRefHandle(resource, stableArgsRef.current);
+    }, [stableArgsRef.current]);
+}
+function createRefHandle(resource, args) {
+    return {
+        get has() {
+            return resource.hasEntry(args);
+        },
+        lock() {
+            return resource.lockEntry(args);
+        },
+        invalidate() {
+            resource.invalidate(args);
+        },
+        createPatch(patchFn) {
+            return resource.createEntryPatch(args, patchFn);
+        },
+        create(data) {
+            resource.populateEntry(args, data);
+        },
+    };
+}
+function createSkippedRef() {
+    return {
+        get has() {
+            return false;
+        },
+        lock() {
+            return { unlock: () => { } };
+        },
+        invalidate() { },
+        createPatch() {
+            return null;
+        },
+        create() { },
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { ResourceV2 } from "../../query-v2/core/resource/ResourceV2";
+import type { TApiSnapshot } from "../../query-v2/types/snapshot.types";
+export declare const CURRENT_SNAPSHOT_VERSION = 1;
+/**
+ * Capture snapshot from all registered resources.
+ * Only `MachineSuccess` entries are included (per design §5).
+ */
+export declare function getSnapshot(resources: Map<string, ResourceV2<any, any, any>>, keyPrefix: string | null, keyStrategy: "serialize" | "compare"): TApiSnapshot;
+/**
+ * Hydrate resources from a snapshot.
+ * Validates version and keyPrefix before applying.
+ */
+export declare function hydrateSnapshot(snapshot: TApiSnapshot, resources: Map<string, ResourceV2<any, any, any>>, apiKeyPrefix: string | null, maxSnapshotDataAge: number): void;

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

@@ -0,0 +1,76 @@
+import { Machine } from "../../query-v2/core/machines/Machine";
+import { MachineSuccess } from "../../query-v2/core/machines/MachineSuccess";
+export const CURRENT_SNAPSHOT_VERSION = 1;
+/**
+ * Capture snapshot from all registered resources.
+ * Only `MachineSuccess` entries are included (per design §5).
+ */
+export function getSnapshot(resources, keyPrefix, keyStrategy) {
+    if (keyStrategy === "compare") {
+        throw new Error('getSnapshot() is not supported with keyStrategy "compare". ' +
+            'SSR snapshots require keyStrategy "serialize" so that cache keys are serializable strings.');
+    }
+    const resourceSnapshots = {};
+    for (const [resourceKey, resource] of resources) {
+        const entries = {};
+        let hasEntries = false;
+        for (const [key, cacheEntry] of resource.cacheEntries()) {
+            const machine = cacheEntry.peek();
+            if (!(machine instanceof MachineSuccess))
+                continue;
+            const state = machine.state;
+            entries[key] = {
+                status: "success",
+                args: state.args,
+                data: state.data,
+                updatedAt: state.updatedAt,
+            };
+            hasEntries = true;
+        }
+        if (hasEntries) {
+            resourceSnapshots[resourceKey] = { entries };
+        }
+    }
+    return {
+        version: CURRENT_SNAPSHOT_VERSION,
+        keyPrefix,
+        resources: resourceSnapshots,
+    };
+}
+/**
+ * Hydrate resources from a snapshot.
+ * Validates version and keyPrefix before applying.
+ */
+export function hydrateSnapshot(snapshot, resources, apiKeyPrefix, maxSnapshotDataAge) {
+    // Fatal: snapshot format incompatibility — the serialization schema has changed between versions.
+    // This cannot be recovered from; the snapshot must be regenerated.
+    if (snapshot.version !== CURRENT_SNAPSHOT_VERSION) {
+        throw new Error(`Snapshot version mismatch: expected ${CURRENT_SNAPSHOT_VERSION}, got ${snapshot.version}. ` +
+            `The snapshot format is incompatible with the current version of query-v2.`);
+    }
+    // Fatal: wrong API instance — the snapshot was created by a different keyPrefix configuration.
+    // Applying it would pollute the cache with data from an unrelated API.
+    if (snapshot.keyPrefix !== apiKeyPrefix) {
+        throw new Error(`Snapshot keyPrefix mismatch: expected "${apiKeyPrefix}", got "${snapshot.keyPrefix}". ` +
+            `Ensure the snapshot was created by the same API instance configuration.`);
+    }
+    const now = Date.now();
+    for (const [resourceKey, resourceSnapshot] of Object.entries(snapshot.resources)) {
+        const resource = resources.get(resourceKey);
+        if (!resource) {
+            // Non-fatal: a resource may have been removed between versions — skip gracefully.
+            console.warn(`[rx-toolkit] hydrateSnapshot: unknown resource key "${resourceKey}", skipping.`);
+            continue;
+        }
+        for (const [, slice] of Object.entries(resourceSnapshot.entries)) {
+            const machine = Machine.fromSnapshot(slice);
+            // Reconstruct args from the slice
+            const args = slice.args;
+            resource.hydrateEntry(args, machine);
+            // S3: stale entries trigger invalidation
+            if (now - slice.updatedAt > maxSnapshotDataAge) {
+                resource.invalidate(args);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,54 @@
+import type { TMachineStatus, TPatchFn } from "./machine.types";
+/** SKIP_TOKEN type alias for agent args */
+type SKIP_TOKEN = typeof import("../lib/SKIP_TOKEN").SKIP;
+/** Agent — observer with stale-while-revalidate */
+export interface IResourceV2Agent<TArgs, TData, TError = Error> {
+    /** Reactive state (computed signal) */
+    readonly state$: () => IResourceV2AgentState<TArgs, TData, TError>;
+    /** Start query with new args (returns promise) */
+    start(args: TArgs | SKIP_TOKEN): Promise<void>;
+    /** Compare previous and new args */
+    compareArgs(a: TArgs, b: TArgs): boolean;
+}
+/** Agent's computed state shape */
+export interface IResourceV2AgentState<TArgs, TData, TError = Error> {
+    /** Current machine status */
+    status: TMachineStatus;
+    /** Current data (may be stale during loading) */
+    data: TData | null;
+    /** Current error */
+    error: TError | null;
+    /** Current args (fresh) */
+    args: TArgs | null;
+    /** Loading indicator */
+    isLoading: boolean;
+    /** True only on first load (no previous data) */
+    isInitialLoading: boolean;
+    /** True when refreshing existing data */
+    isRefreshing: boolean;
+    /** True when data is available */
+    isSuccess: boolean;
+    /** True when in error state */
+    isError: boolean;
+    /** Error from a failed background refresh (stale data preserved) */
+    refreshError: TError | null;
+}
+/** Ref — imperative access to a specific cache entry by args */
+export interface IResourceV2Ref<_TArgs, TData, _TError = Error> {
+    /** Check if cache entry exists */
+    readonly has: boolean;
+    /** Lock cache entry (prevent eviction) */
+    lock(): {
+        unlock: () => void;
+    };
+    /** Invalidate (force re-fetch) */
+    invalidate(): void;
+    /** Create optimistic patch */
+    createPatch(patchFn: TPatchFn<TData>): {
+        commit: () => void;
+        abort: () => void;
+    } | null;
+    /** Pre-populate cache with data */
+    create(data: TData): void;
+}
+export {};

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

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

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

@@ -0,0 +1,22 @@
+import type { IPlugin, PluginAugmentations } from "./plugin.types";
+import type { IResourceV2, IResourceV2Options } from "./resource.types";
+import type { TCompareArgsFn, TSerializeArgsFn } from "./shared.types";
+import type { TApiSnapshot } from "./snapshot.types";
+/** Options for createApi factory */
+export interface ICreateApiOptions<TPlugins extends IPlugin[] = []> {
+    keyPrefix?: string | null;
+    keyStrategy?: "serialize" | "compare";
+    serializeArgs?: TSerializeArgsFn;
+    compareArg?: TCompareArgsFn;
+    initialSnapshot?: TApiSnapshot | null;
+    cacheLifetime?: number;
+    plugins?: TPlugins;
+    maxSnapshotDataAge?: number;
+    doCacheArgs?: boolean;
+}
+/** API instance returned by createApi */
+export interface IApi<TPlugins extends IPlugin[] = []> {
+    createResource<TArgs, TData, TError = Error>(options: IResourceV2Options<TArgs, TData, TError>): IResourceV2<TArgs, TData, TError> & PluginAugmentations<TPlugins, TArgs, TData, TError>;
+    resetAll(): void;
+    getSnapshot(): TApiSnapshot;
+}

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

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