@fozy-labs/rx-toolkit 0.5.4 → 0.6.0

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

@@ -0,0 +1,9 @@
+export * from "./Machine";
+export * from "./MachineBase";
+export * from "./MachinePending";
+export * from "./MachineSuccess";
+export * from "./MachineError";
+export * from "./MachineRefreshing";
+export * from "./MachineRefreshError";
+export * from "./MachineWithData";
+export * from "./machine-helpers";

package/dist/query/core/machine/machine-helpers.d.ts

@@ -0,0 +1,9 @@
+import type { TMachineState, TPatchEntry, TPatchState, TRefreshErrorState, TRefreshingState, TSuccessState } from "../../../query/types";
+export type TDataState<TArgs, TData> = TSuccessState<TArgs, TData> | TRefreshingState<TArgs, TData> | TRefreshErrorState<TArgs, TData>;
+export declare function hasData<TArgs, TData>(state: TMachineState<TArgs, TData>): state is TDataState<TArgs, TData>;
+export declare function buildDataState<TArgs, TData>(status: "success" | "refreshing" | "refresh-error", base: TMachineState<TArgs, TData>, data: TData, patchState: TPatchState<TData> | null, updatedAt?: number): TDataState<TArgs, TData>;
+export declare function withDataState<TArgs, TData>(currentState: TMachineState<TArgs, TData>, data: TData, patchState: TPatchState<TData> | null): TDataState<TArgs, TData>;
+export declare function consistencyViolation<TArgs, TData>(currentState: TMachineState<TArgs, TData>): TDataState<TArgs, TData>;
+export declare function replayPatches<TArgs, TData>(currentState: TMachineState<TArgs, TData>, targetStatus: "success" | "refreshing" | "refresh-error", baseData: TData, patches: TPatchEntry[], updatedAt?: number): TDataState<TArgs, TData>;
+export declare function processPatches<TArgs, TData>(currentState: TMachineState<TArgs, TData>, patchState: TPatchState<TData>): TDataState<TArgs, TData>;
+export declare function processAllPatches<TArgs, TData>(currentState: TMachineState<TArgs, TData>, patchState: TPatchState<TData>): TDataState<TArgs, TData>;

package/dist/query/core/machine/machine-helpers.js

@@ -0,0 +1,80 @@
+import { processAllSettledPatches, processPatchState, replayPatchEntries } from "../patcher";
+export function hasData(state) {
+    return state.status === "success" || state.status === "refreshing" || state.status === "refresh-error";
+}
+export function buildDataState(status, base, data, patchState, updatedAt) {
+    const resolvedUpdatedAt = updatedAt ?? (hasData(base) ? base.updatedAt : Date.now());
+    switch (status) {
+        case "success": {
+            const state = {
+                status: "success",
+                args: base.args,
+                data,
+                error: null,
+                updatedAt: resolvedUpdatedAt,
+                patchState,
+            };
+            return state;
+        }
+        case "refreshing": {
+            const state = {
+                status: "refreshing",
+                args: base.args,
+                data,
+                error: null,
+                updatedAt: resolvedUpdatedAt,
+                patchState,
+            };
+            return state;
+        }
+        case "refresh-error": {
+            if (!hasData(base)) {
+                throw new Error("Cannot build refresh-error from non-data state");
+            }
+            const state = {
+                status: "refresh-error",
+                args: base.args,
+                data,
+                error: base.error,
+                updatedAt: resolvedUpdatedAt,
+                patchState,
+            };
+            return state;
+        }
+    }
+}
+export function withDataState(currentState, data, patchState) {
+    if (!hasData(currentState)) {
+        throw new Error("withDataState called on non-data state");
+    }
+    return buildDataState(currentState.status, currentState, data, patchState);
+}
+export function consistencyViolation(currentState) {
+    if (!hasData(currentState)) {
+        throw new Error("Consistency violation in non-data state");
+    }
+    const newPatchState = {
+        originalData: currentState.patchState?.originalData ?? currentState.data,
+        patches: [],
+        isConsistencyViolation: true,
+    };
+    return withDataState(currentState, currentState.data, newPatchState);
+}
+export function replayPatches(currentState, targetStatus, baseData, patches, updatedAt) {
+    const result = replayPatchEntries(baseData, patches);
+    if (!result.ok)
+        return consistencyViolation(currentState);
+    return buildDataState(targetStatus, currentState, result.data, result.patchState, updatedAt);
+}
+export function processPatches(currentState, patchState) {
+    const result = processPatchState(patchState);
+    if (!result.ok)
+        return consistencyViolation(currentState);
+    return withDataState(currentState, result.data, result.patchState);
+}
+export function processAllPatches(currentState, patchState) {
+    const result = processAllSettledPatches(patchState);
+    if (!result.ok)
+        return consistencyViolation(currentState);
+    return withDataState(currentState, result.data, result.patchState);
+}

package/dist/query/core/patcher/Patcher.d.ts

@@ -0,0 +1,30 @@
+import { type Patch } from "immer";
+import type { TPatchEntry, TPatchState } from "../../../query/types";
+export type TPatchResult<TData> = {
+    ok: true;
+    data: TData;
+    patchState: TPatchState<TData> | null;
+} | {
+    ok: false;
+};
+export declare function createPatches<T>(base: T, recipe: (draft: T) => void): [T, Patch[], Patch[]];
+export declare function applyForwardPatches<T>(base: T, patches: Patch[]): T;
+export declare function rebasePatches<T>(base: T, forwardPatches: Patch[]): [T, Patch[], Patch[]];
+/**
+ * Replay a list of patch entries onto new base data.
+ * Pure data operation — no machine-state knowledge.
+ */
+export declare function replayPatchEntries<TData>(baseData: TData, patches: TPatchEntry[]): TPatchResult<TData>;
+/**
+ * Process a patch state: fold settled independent patches, then replay remaining.
+ * Stops at the first pending patch — patches after it are left as-is.
+ * Pure data operation — no machine-state knowledge.
+ */
+export declare function processPatchState<TData>(patchState: TPatchState<TData>): TPatchResult<TData>;
+/**
+ * Process ALL settled patches in a patch state, continuing past pending ones.
+ * Committed patches are rebased and folded into originalData;
+ * aborted patches are dropped; pending patches are kept and rebased.
+ * Pure data operation — no machine-state knowledge.
+ */
+export declare function processAllSettledPatches<TData>(patchState: TPatchState<TData>): TPatchResult<TData>;

package/dist/query/core/patcher/Patcher.js

@@ -0,0 +1,122 @@
+import { applyPatches, enablePatches, produceWithPatches } from "immer";
+enablePatches();
+// ==================== Low-level Immer Operations ====================
+export function createPatches(base, recipe) {
+    return produceWithPatches(base, recipe);
+}
+export function applyForwardPatches(base, patches) {
+    return applyPatches(base, patches);
+}
+export function rebasePatches(base, forwardPatches) {
+    return produceWithPatches(base, (draft) => {
+        applyPatches(draft, forwardPatches);
+    });
+}
+// ==================== High-level Patch Operations ====================
+/**
+ * Replay a list of patch entries onto new base data.
+ * Pure data operation — no machine-state knowledge.
+ */
+export function replayPatchEntries(baseData, patches) {
+    let currentData = baseData;
+    const replayedPatches = [];
+    for (const p of patches) {
+        if (p.status === "aborted") {
+            replayedPatches.push(p);
+            continue;
+        }
+        try {
+            const [nextData, forward, inverse] = rebasePatches(currentData, p.forward);
+            currentData = nextData;
+            p.forward = forward;
+            p.inverse = inverse;
+            replayedPatches.push(p);
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    const hasPending = replayedPatches.some((p) => p.status === "pending");
+    if (!hasPending) {
+        let finalData = baseData;
+        for (const p of replayedPatches) {
+            if (p.status === "committed") {
+                try {
+                    finalData = applyForwardPatches(finalData, p.forward);
+                }
+                catch {
+                    return { ok: false };
+                }
+            }
+        }
+        return { ok: true, data: finalData, patchState: null };
+    }
+    return {
+        ok: true,
+        data: currentData,
+        patchState: {
+            originalData: baseData,
+            patches: replayedPatches,
+            isConsistencyViolation: false,
+        },
+    };
+}
+/**
+ * Process a patch state: fold settled independent patches, then replay remaining.
+ * Stops at the first pending patch — patches after it are left as-is.
+ * Pure data operation — no machine-state knowledge.
+ */
+export function processPatchState(patchState) {
+    const patches = [...patchState.patches];
+    let originalData = patchState.originalData;
+    const firstPendingIdx = patches.findIndex((p) => p.status === "pending");
+    const independentEnd = firstPendingIdx === -1 ? patches.length : firstPendingIdx;
+    if (independentEnd > 0) {
+        const independentPatches = patches.slice(0, independentEnd);
+        for (const p of independentPatches) {
+            if (p.status === "committed") {
+                try {
+                    originalData = applyForwardPatches(originalData, p.forward);
+                }
+                catch {
+                    return { ok: false };
+                }
+            }
+        }
+        patches.splice(0, independentEnd);
+    }
+    if (patches.length === 0) {
+        return { ok: true, data: originalData, patchState: null };
+    }
+    return replayPatchEntries(originalData, patches);
+}
+/**
+ * Process ALL settled patches in a patch state, continuing past pending ones.
+ * Committed patches are rebased and folded into originalData;
+ * aborted patches are dropped; pending patches are kept and rebased.
+ * Pure data operation — no machine-state knowledge.
+ */
+export function processAllSettledPatches(patchState) {
+    let committedData = patchState.originalData;
+    const pendingEntries = [];
+    for (const p of patchState.patches) {
+        if (p.status === "aborted")
+            continue;
+        if (p.status === "committed") {
+            try {
+                const [nextData] = rebasePatches(committedData, p.forward);
+                committedData = nextData;
+            }
+            catch {
+                return { ok: false };
+            }
+            continue;
+        }
+        // pending
+        pendingEntries.push(p);
+    }
+    if (pendingEntries.length === 0) {
+        return { ok: true, data: committedData, patchState: null };
+    }
+    return replayPatchEntries(committedData, pendingEntries);
+}

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

@@ -0,0 +1 @@
+export * from "./Patcher";

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

@@ -0,0 +1 @@
+export * from "./Patcher";

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

@@ -0,0 +1,105 @@
+import type { Args, ArgsOrVoid, IResource, IResourceAgent, IResourceConfig, Keyed } from "../../../query/types";
+import { type ReadableSignalFnLike } from "../../../signals";
+import { QueryCacheEntry } from "../cache/QueryCacheEntry";
+/**
+ * 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 declare class Resource<TArgs, TData> implements IResource<TArgs, TData> {
+    private readonly _cache;
+    /**
+     * Хранит последний добавленный кэш-энтер, для возможности реактивной подписки (с помощью getEntry$)
+     */
+    private readonly _lastEntry$;
+    /**
+     * Определяет общий статус ресурса
+     * - "idle": ресурса не активен, записей нет, getEntry$ возвращает null
+     * - "running": ресурс активен, есть хотя бы одна запись, getEntry$ может возвращать записи
+     */
+    private readonly _status$;
+    private readonly _queryFn;
+    readonly _key: string | undefined;
+    private readonly _retentionTime;
+    private readonly _serializeArgs;
+    private readonly _onCacheEntryAdded;
+    private readonly _onQueryStarted;
+    private readonly _beforeQuery?;
+    constructor(config: IResourceConfig<TArgs, TData>);
+    /**
+     * 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: Args<TArgs>, doForce?: boolean): void;
+    /**
+     * Mark the entry as stale and trigger a background SWR refresh.
+     *
+     * @param args - Query arguments identifying the cache entry.
+     */
+    refresh(args: Args<TArgs>): void;
+    /**
+     * 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: ArgsOrVoid<TArgs>, doInitiate?: boolean): QueryCacheEntry<TArgs, TData> | null;
+    /**
+     * Reactive variant of {@link getEntry} — establishes a signal dependency
+     * so that `Signal.compute` / `Signal.effect` callers re-evaluate when the
+     * cache map changes (entry added or removed).
+     *
+     * @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: ArgsOrVoid<TArgs>, doInitiate: true): ReadableSignalFnLike<QueryCacheEntry<TArgs, TData>>;
+    getEntry$(args: ArgsOrVoid<TArgs>, doInitiate?: boolean): ReadableSignalFnLike<QueryCacheEntry<TArgs, TData> | null>;
+    getEntry$(args: Keyed<TArgs>, doInitiate?: boolean): ReadableSignalFnLike<QueryCacheEntry<TArgs, TData> | null>;
+    /**
+     * Create a reactive {@link ResourceAgent} that observes this resource
+     * and provides SWR-aware state transitions.
+     */
+    createAgent(): IResourceAgent<TArgs, TData>;
+    /**
+     * Serialize arguments into a cache key string.
+     *
+     * @param args - Query arguments.
+     * @returns The serialized key used for cache lookup.
+     */
+    serialize(args: Args<TArgs>): string;
+    /**
+     * 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: Args<TArgs>): Keyed<TArgs>;
+    /** Iterate over all cache entries. */
+    getEntries(): IterableIterator<QueryCacheEntry<TArgs, TData>>;
+    /** Clear all cache entries. */
+    reset(): void;
+    /**
+     * 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.
+     */
+    private _getOrCreate;
+    private _createEntry;
+    /** Standard entry creation: queryFn auto-executes in constructor. */
+    private _createEntryDirect;
+    /** Entry creation with beforeQuery intercept: starts in pending, asks other tabs first. */
+    private _createEntryWithBeforeQuery;
+    private _hydrateEntry;
+    private _fireOnCacheEntryAdded;
+    private _fireOnQueryStarted;
+}