@fozy-labs/rx-toolkit 0.5.4 → 0.6.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Vladimir Panev
+Copyright (c) 2025-2026 Vladimir Panev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # RxToolkit
 
-> Фреймворк агностик набор инструментов для **реактивного** управления состоянием, построенный поверх RxJS.
+> Фреймворк-агностик набор инструментов для **реактивного** управления состоянием, построенный поверх RxJS.
 
 [![npm version](https://badge.fury.io/js/%40fozy-labs%2Frx-toolkit.svg)](https://badge.fury.io/js/%40fozy-labs%2Frx-toolkit)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
@@ -14,7 +14,7 @@ npm install @fozy-labs/rx-toolkit rxjs
 ## 🎯 Цель
 
 RxJS действительно мощный инструмент реактивного программирования,
-он удобен когда мы работаем с потоком событий, но когда речь заходит о состоянии приложения,
+он удобен, когда мы работаем с потоком событий, но когда речь заходит о состоянии приложения,
 из-за асинхронной природы rx'а, его использование становится сложным и громоздким, не говоря уже о кешировании данных
 (хотя некоторые разработчики "продают" rxjs, как альтернативу Query библиотекам,
 на самом деле реализация подобного функционала выльется в создание отдельной библиотеки).
@@ -27,7 +27,7 @@ RxToolkit решает эти проблемы, предоставляя сво
 - 🔧 **Framework-agnostic** — Стройте систему и описывайте логику в изолированном месте.
 - ⚡ **Built on RxJS** — Наследует всю мощь RxJS.
 - 💾 **Кеш-менеджер** — Предоставляет Query реализацию для работы с данными.
-- 🧪 **Query v2** *(experimental)* — Переработанный кеш-менеджер с machine states, плагинами и SSR snapshots.
+- 🧪 **Query** — Кеш-менеджер с machine states, плагинами и SSR snapshots.
 - 🔷 **TypeScript-first** — Полная типизация.
 - 🔗 **Интеграция с фреймворками** — Как и RxJS напрямую работает в Angular, Svelte и SolidJS.
   Поставляется с React-хуками из коробки.
@@ -35,7 +35,6 @@ RxToolkit решает эти проблемы, предоставляя сво
 ## 📚 Документация
 - [**RxSignals**](./docs/signals/README.md) - реактивные примитивы
 - [**RxQuery**](./docs/query/README.md) - кеш-менеджер для работы с данными
-- [**RxQuery v2**](./docs/query-v2/README.md) - кеш-менеджер v2 *(experimental)*
 - [**React**](./docs/usage/react/README.md) - интеграция с React
 - [**Devtools**](./docs/devtools/README.md) - инструменты разработчика
 - [**DefaultOptions**](./docs/options/README.md) - глобальные настройки
@@ -96,7 +95,7 @@ const on10click$ = doubled$.obs.pipe(
 );
 
 const sub = on10click$.subscribe(() => {
-    console.log('Great! That you first reached 10 clicks!');
+    console.log('Great! You first reached 10 clicks!');
 });
 // Не забываем отписаться
 sub.unsubscribe();
@@ -104,17 +103,27 @@ sub.unsubscribe();
 
 ###### RxQuery (Корзина покупок)
 ```tsx
-const getCart = createResource({
+import {
+    createApi,
+    reactHooksPlugin,
+} from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+    plugins: [reactHooksPlugin()],
+});
+
+const getCart = api.createResource({
+    key: 'cart',
     queryFn: fetchCart,
 });
 
-const toggleCardItem = createCommand({
-    queryFn: fetchToggleCardItem,
-    link(add) {
-        add({
+const toggleCartItem = api.createCommand({
+    queryFn: fetchToggleCartItem,
+    links(link) {
+        link({
             resource: getCart,
             forwardArgs: () => undefined,
-            optimisticUpdate: ({ draft, args }) => {
+            optimisticUpdate: (draft, args) => {
                 const item = draft.items.find(i => i.id === args.id);
                 if (!item) return;
                 item.enabled = args.enabled;
@@ -124,8 +133,8 @@ const toggleCardItem = createCommand({
 });
 
 function ShoppingCart() {
-    const cartQuery = useResourceAgent(getCart);
-    const [toggleItem] = useCommandAgent(toggleCardItem);
+    const cartQuery = getCart.useResource();
+    const [toggleItem] = toggleCartItem.useCommand();
     const cart = cartQuery.data;
 
     return (

package/dist/common/devtools/reduxDevtools.js

@@ -98,7 +98,7 @@ export function reduxDevtools(options = {}) {
     return {
         state(name, initState) {
             const keys = name.split("/");
-            state = applyState(keys, initState, state);
+            state = applyState(keys, initState, state, existConsoleWarning);
             pendingActionType = "create";
             scheduler.schedule(flushToDevtools);
             return (newState) => {
@@ -118,11 +118,26 @@ export function reduxDevtools(options = {}) {
         },
     };
 }
-function applyState(keys, newState, state) {
+function existConsoleWarning(paths) {
+    if (typeof console === "undefined" || typeof console.warn !== "function") {
+        return false;
+    }
+    const path = paths.join("/");
+    console.warn(`
+[RxToolkit Redux Devtools] Warning: ${path} is already defined in the state.
+This may lead to unexpected behavior in Redux Devtools.
+Consider using a unique path for each state or ensure that states are properly clearedwhen completed.
+`);
+    return true;
+}
+function applyState(keys, newState, state, warnFn) {
     const acc = { ...state };
     let current = acc;
     keys.forEach((key, i, arr) => {
         if (i === arr.length - 1) {
+            if (key in current && warnFn) {
+                warnFn(keys);
+            }
             current[key] = newState;
         }
         else {

package/dist/common/react/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./useConstant";
 export * from "./useEventHandler";
+export * from "./useIsomorphicLayoutEffect";

package/dist/common/react/index.js

@@ -1,2 +1,3 @@
 export * from "./useConstant";
 export * from "./useEventHandler";
+export * from "./useIsomorphicLayoutEffect";

package/dist/common/react/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,17 @@
+import React from "react";
+/**
+ * A hook that resolves to `useLayoutEffect` on the client and `useEffect` on the server.
+ *
+ * Used to prevent React hydration warnings when using layout effects with
+ * Server-Side Rendering (SSR).
+ *
+ * @param {React.EffectCallback} effect - Imperative function that can return a cleanup function.
+ * @param {React.DependencyList} [deps] - If present, effect will only activate if the values in the list change.
+ *
+ * @see {@link https://react.dev React Docs: useLayoutEffect}
+ * @example
+ * useIsomorphicLayoutEffect(() => {
+ *   console.log("Synchronous on client, standard on server");
+ * }, [data]);
+ */
+export declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;

package/dist/common/react/useIsomorphicLayoutEffect.js

@@ -0,0 +1,17 @@
+import React from "react";
+/**
+ * A hook that resolves to `useLayoutEffect` on the client and `useEffect` on the server.
+ *
+ * Used to prevent React hydration warnings when using layout effects with
+ * Server-Side Rendering (SSR).
+ *
+ * @param {React.EffectCallback} effect - Imperative function that can return a cleanup function.
+ * @param {React.DependencyList} [deps] - If present, effect will only activate if the values in the list change.
+ *
+ * @see {@link https://react.dev React Docs: useLayoutEffect}
+ * @example
+ * useIsomorphicLayoutEffect(() => {
+ *   console.log("Synchronous on client, standard on server");
+ * }, [data]);
+ */
+export const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;

package/dist/index.d.ts

@@ -3,6 +3,5 @@ export * from "./common/options";
 export * from "./common/react";
 export * from "./common/utils/deepEqual";
 export * from "./common/utils/shallowEqual";
-export * from "./query";
 export * from "./signals";
-export * as unstable_queryV2 from "./query-v2";
+export * from "./query";

package/dist/index.js

@@ -3,6 +3,5 @@ export * from "./common/options";
 export * from "./common/react";
 export * from "./common/utils/deepEqual";
 export * from "./common/utils/shallowEqual";
-export * from "./query";
 export * from "./signals";
-export * as unstable_queryV2 from "./query-v2";
+export * from "./query";

package/dist/query/api/createApi.d.ts

@@ -0,0 +1,4 @@
+import type { IApi, IPlugin, TCreateApiOptions } from "../../query/types";
+export declare function createApi<const TPlugins extends readonly IPlugin[] = readonly IPlugin[]>(options?: TCreateApiOptions<TPlugins>): IApi<TPlugins>;
+/** @internal — re-exported for unit testing only */
+export { mergeHooks } from "../core/api";

package/dist/query/api/createApi.js

@@ -0,0 +1,9 @@
+import { Api } from "../core/api";
+export function createApi(options) {
+    // Safe cast: Api implements IApi (with default plugins). At runtime,
+    // plugin augmentations are applied via Object.assign in Api.createResource/createCommand.
+    // The generic TPlugins only affects the compile-time type of the returned object.
+    return new Api(options);
+}
+/** @internal — re-exported for unit testing only */
+export { mergeHooks } from "../core/api";

package/dist/query/api/index.d.ts

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

package/dist/query/api/index.js

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

package/dist/query/constants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sentinel value passed as resource arguments to indicate that the query
+ * should be skipped (not executed). Useful for conditional fetching.
+ */
+export declare const SKIP: unique symbol;
+/**
+ * Unique brand symbol used to distinguish {@link Keyed} wrappers
+ * from plain argument objects at runtime.
+ */
+export declare const KEYED_BRAND: unique symbol;
+/** Current serialization version used by the snapshot/restore mechanism. */
+export declare const CURRENT_SNAPSHOT_VERSION = 1;

package/dist/query/constants.js

@@ -0,0 +1,15 @@
+// ==================== SKIP Sentinel ==
+/**
+ * Sentinel value passed as resource arguments to indicate that the query
+ * should be skipped (not executed). Useful for conditional fetching.
+ */
+export const SKIP = Symbol("SKIP");
+// ==================== Keyed Brand ====================
+/**
+ * Unique brand symbol used to distinguish {@link Keyed} wrappers
+ * from plain argument objects at runtime.
+ */
+export const KEYED_BRAND = Symbol("KEYED_BRAND");
+// ==================== Snapshot Version ====================
+/** Current serialization version used by the snapshot/restore mechanism. */
+export const CURRENT_SNAPSHOT_VERSION = 1;

package/dist/query/core/api/Api.d.ts

@@ -0,0 +1,20 @@
+import type { IApi, ICommand, IResource, TApiSnapshot, TCommandOptions, TCreateApiOptions, TResourceOptions } from "../../../query/types";
+export declare class Api implements IApi {
+    private readonly resources;
+    private readonly commands;
+    private readonly resourcesByKey;
+    private readonly keyPrefix;
+    private readonly plugins;
+    private readonly apiSerializeArgs;
+    private readonly apiResourceRetentionTime;
+    private readonly apiCommandRetentionTime;
+    private readonly snapshoter;
+    private readonly apiOnCacheEntryAdded;
+    private readonly apiOnQueryStarted;
+    private readonly syncer;
+    constructor(options?: TCreateApiOptions);
+    createResource: <TArgs = void, TData = unknown>(opts: TResourceOptions<TArgs, TData>) => IResource<TArgs, TData>;
+    createCommand: <TArgs = void, TData = unknown>(opts: TCommandOptions<TArgs, TData>) => ICommand<TArgs, TData>;
+    getSnapshot: () => TApiSnapshot;
+    resetAll: () => void;
+}

package/dist/query/core/api/Api.js

@@ -0,0 +1,129 @@
+import { stableStringify } from "../../../query/lib/stableStringify";
+import { Command } from "../command/Command";
+import { Resource } from "../resource/Resource";
+import { Snapshoter } from "../snapshoter";
+import { Syncer } from "../syncer";
+import { DEFAULT_COMMAND_RETENTION_TIME, DEFAULT_RESOURCE_RETENTION_TIME } from "./constants";
+import { mergeHooks } from "./mergeHooks";
+import { normalizeLinks } from "./normalizeLinks";
+export class Api {
+    resources = [];
+    commands = [];
+    resourcesByKey = new Map();
+    keyPrefix;
+    plugins;
+    apiSerializeArgs;
+    apiResourceRetentionTime;
+    apiCommandRetentionTime;
+    snapshoter;
+    apiOnCacheEntryAdded;
+    apiOnQueryStarted;
+    syncer;
+    constructor(options) {
+        this.keyPrefix = options?.keyPrefix ?? null;
+        this.plugins = options?.plugins ?? [];
+        this.apiSerializeArgs = options?.serializeArgs ?? stableStringify;
+        this.apiResourceRetentionTime = options?.resourceRetentionTime ?? DEFAULT_RESOURCE_RETENTION_TIME;
+        this.apiCommandRetentionTime = options?.commandRetentionTime ?? DEFAULT_COMMAND_RETENTION_TIME;
+        this.snapshoter = new Snapshoter({
+            initialSnapshot: options?.initialSnapshot ?? null,
+            snapshotValidTime: options?.snapshotValidTime ?? false,
+            keyPrefix: this.keyPrefix,
+        });
+        this.apiOnCacheEntryAdded = options?.onCacheEntryAdded;
+        this.apiOnQueryStarted = options?.onQueryStarted;
+        const syncDriver = options?.syncDriver;
+        const defaultSync = options?.defaultSync ?? "none";
+        this.syncer = syncDriver
+            ? new Syncer({ syncDriver, keyPrefix: this.keyPrefix, defaultSync, resourcesByKey: this.resourcesByKey })
+            : null;
+        // Install plugins
+        for (const plugin of this.plugins) {
+            plugin.install({ keyPrefix: this.keyPrefix ?? "" });
+        }
+        // Connect sync driver after setup
+        this.syncer?.connect();
+    }
+    createResource = (opts) => {
+        const effectiveRetentionTime = opts.retentionTime !== undefined ? opts.retentionTime : this.apiResourceRetentionTime;
+        const effectiveSerializeArgs = opts.serializeArgs ?? this.apiSerializeArgs;
+        const effectiveKey = this.keyPrefix != null && opts.key != null ? `${this.keyPrefix}/${opts.key}` : opts.key;
+        // Merge lifecycle hooks: API-level + resource-level
+        const mergedOnCacheEntryAdded = mergeHooks(this.apiOnCacheEntryAdded, opts.onCacheEntryAdded);
+        const mergedOnQueryStarted = mergeHooks(this.apiOnQueryStarted, opts.onQueryStarted);
+        // Snapshot hydration: build initialEntries if snapshot has matching resource data
+        const initialEntries = this.snapshoter.hydrateResource(opts.key, opts.snapshotValidTime);
+        const syncEnabled = this.syncer && this.syncer.isResourceSyncEnabled(opts);
+        const config = {
+            queryFn: opts.queryFn,
+            key: effectiveKey,
+            retentionTime: effectiveRetentionTime,
+            serializeArgs: effectiveSerializeArgs,
+            onCacheEntryAdded: mergedOnCacheEntryAdded,
+            onQueryStarted: mergedOnQueryStarted,
+            getDevtoolsKey: opts.getDevtoolsKey,
+            snapshot: initialEntries,
+            beforeQuery: syncEnabled
+                ? this.syncer.beforeQuery
+                : undefined,
+        };
+        const resource = new Resource(config);
+        // Track for resetAll / getSnapshot
+        this.resources.push(resource);
+        if (effectiveKey) {
+            this.resourcesByKey.set(effectiveKey, resource);
+        }
+        // Plugin augmentation
+        let augmented = {};
+        for (const plugin of this.plugins) {
+            if (plugin.augmentResource) {
+                const additions = plugin.augmentResource(resource, opts);
+                augmented = { ...augmented, ...additions };
+            }
+        }
+        // Spread augmented properties onto the resource object
+        Object.assign(resource, augmented);
+        return resource;
+    };
+    createCommand = (opts) => {
+        const effectiveRetentionTime = opts.retentionTime !== undefined ? opts.retentionTime : this.apiCommandRetentionTime;
+        const effectiveKey = this.keyPrefix != null && opts.key != null ? `${this.keyPrefix}/${opts.key}` : opts.key;
+        // Merge lifecycle hooks: API-level + command-level
+        const mergedOnCacheEntryAdded = mergeHooks(this.apiOnCacheEntryAdded, opts.onCacheEntryAdded);
+        const mergedOnQueryStarted = mergeHooks(this.apiOnQueryStarted, opts.onQueryStarted);
+        const config = {
+            queryFn: opts.queryFn,
+            key: effectiveKey,
+            links: normalizeLinks(opts.links),
+            retentionTime: effectiveRetentionTime,
+            onCacheEntryAdded: mergedOnCacheEntryAdded,
+            onQueryStarted: mergedOnQueryStarted,
+        };
+        const command = new Command(config);
+        // Track for resetAll
+        this.commands.push(command);
+        // Plugin augmentation
+        let augmented = {};
+        for (const plugin of this.plugins) {
+            if (plugin.augmentCommand) {
+                const additions = plugin.augmentCommand(command, opts);
+                augmented = { ...augmented, ...additions };
+            }
+        }
+        Object.assign(command, augmented);
+        return command;
+    };
+    getSnapshot = () => {
+        return this.snapshoter.getSnapshot(this.resources);
+    };
+    resetAll = () => {
+        for (const resource of this.resources) {
+            resource.reset();
+        }
+        for (const command of this.commands) {
+            command.reset();
+        }
+        // Clean up sync state and reconnect
+        this.syncer?.cleanup();
+    };
+}

package/dist/query/core/api/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_RESOURCE_RETENTION_TIME = 60000;
+export declare const DEFAULT_COMMAND_RETENTION_TIME = 0;

package/dist/query/core/api/constants.js

@@ -0,0 +1,3 @@
+// Default retention times (in milliseconds)
+export const DEFAULT_RESOURCE_RETENTION_TIME = 60_000;
+export const DEFAULT_COMMAND_RETENTION_TIME = 0;

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

@@ -0,0 +1,3 @@
+export { Api } from "./Api";
+export { mergeHooks } from "./mergeHooks";
+export { DEFAULT_RESOURCE_RETENTION_TIME, DEFAULT_COMMAND_RETENTION_TIME } from "./constants";

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

@@ -0,0 +1,3 @@
+export { Api } from "./Api";
+export { mergeHooks } from "./mergeHooks";
+export { DEFAULT_RESOURCE_RETENTION_TIME, DEFAULT_COMMAND_RETENTION_TIME } from "./constants";

package/dist/query/core/api/mergeHooks.d.ts

@@ -0,0 +1,2 @@
+/** @internal — exported for unit testing only */
+export declare function mergeHooks<TFn extends ((...args: any[]) => any) | undefined>(apiHook: TFn | undefined, localHook: TFn | undefined): TFn | undefined;

package/dist/query/core/api/mergeHooks.js

@@ -0,0 +1,26 @@
+/** @internal — exported for unit testing only */
+export function mergeHooks(apiHook, localHook) {
+    if (!apiHook && !localHook)
+        return undefined;
+    if (!apiHook)
+        return localHook;
+    if (!localHook)
+        return apiHook;
+    // Both hooks may be async. The callers use sync try/catch and suppress
+    // lifecycle errors, so the merged function must never produce an unhandled
+    // rejection — catch each hook independently.
+    return (async (...args) => {
+        try {
+            await apiHook(...args);
+        }
+        catch {
+            /* lifecycle error suppressed */
+        }
+        try {
+            await localHook(...args);
+        }
+        catch {
+            /* lifecycle error suppressed */
+        }
+    });
+}

package/dist/query/core/api/normalizeLinks.d.ts

@@ -0,0 +1,2 @@
+import type { TLinkConfig, TLinksInput } from "../../../query/types";
+export declare function normalizeLinks<TArgs, TData>(input: TLinksInput<TArgs, TData> | undefined): TLinkConfig<TArgs, TData, any, any>[];

package/dist/query/core/api/normalizeLinks.js

@@ -0,0 +1,11 @@
+export function normalizeLinks(input) {
+    if (!input)
+        return [];
+    if (Array.isArray(input))
+        return input;
+    const collected = [];
+    input((config) => {
+        collected.push(config);
+    });
+    return collected;
+}

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

@@ -0,0 +1,21 @@
+import { Observable, Subject } from "rxjs";
+import type { ICacheEntry, ICacheEntryOptions } from "../../../query/types";
+/**
+ * Internal reactive container wrapping a Signal.state<TState>.
+ * Implements ICacheEntry<TState>.
+ */
+export declare class CacheEntry<TState> implements ICacheEntry<TState> {
+    private _state$;
+    private _isCompleted;
+    readonly completed$: Subject<void>;
+    readonly obs: Observable<TState>;
+    readonly state$: import("../../../signals").ReadableSignalFnLike<TState>;
+    constructor(initialState: TState, options: ICacheEntryOptions<TState>);
+    /** Non-reactive read */
+    peek(): TState;
+    /** Update stored state (no-op if completed) */
+    set(state: TState): void;
+    /** Fire onClean$ and mark completed. Subsequent set() calls are no-ops. */
+    complete(): void;
+    private _getResetOnRefCountZero;
+}

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

@@ -0,0 +1,54 @@
+import { finalize, ReplaySubject, share, Subject, timer } from "rxjs";
+import { signalize, State } from "../../../signals";
+/**
+ * Internal reactive container wrapping a Signal.state<TState>.
+ * Implements ICacheEntry<TState>.
+ */
+export class CacheEntry {
+    _state$;
+    _isCompleted = false;
+    completed$ = new Subject();
+    obs;
+    state$;
+    constructor(initialState, options) {
+        this._state$ = new State(initialState, {
+            key: options?.devtoolsKey,
+            beforeDevtoolsPush: options?.beforeDevtoolsPush,
+        });
+        this.obs = this._state$.obs.pipe(finalize(() => {
+            this.complete();
+        }), share({
+            connector: () => new ReplaySubject(1),
+            resetOnRefCountZero: this._getResetOnRefCountZero(options.retentionTime),
+            resetOnComplete: true,
+        }));
+        this.state$ = signalize(this.obs);
+    }
+    /** Non-reactive read */
+    peek() {
+        return this._state$.peek();
+    }
+    /** Update stored state (no-op if completed) */
+    set(state) {
+        if (this._isCompleted)
+            return;
+        this._state$.set(state);
+    }
+    /** Fire onClean$ and mark completed. Subsequent set() calls are no-ops. */
+    complete() {
+        if (this._isCompleted)
+            return;
+        this._isCompleted = true;
+        this.completed$.next();
+        this.completed$.complete();
+        this._state$.complete();
+    }
+    _getResetOnRefCountZero(retentionTime) {
+        if (retentionTime === false)
+            return false;
+        if (retentionTime <= 0)
+            return true;
+        const lifetime = retentionTime;
+        return () => timer(lifetime);
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { ICacheMap } from "../../../query/types";
+/** Simple key→value container mapping string keys to cache entries. */
+export declare class CacheMap<TValue> implements ICacheMap<TValue> {
+    private readonly _map;
+    /** Number of entries currently stored. */
+    get size(): number;
+    /** Return entry by key, or `undefined` if absent. */
+    get(key: string): TValue | undefined;
+    /** Store an entry under the given key. */
+    set(key: string, value: TValue): void;
+    /** Remove an entry. Returns `true` if the entry existed. */
+    delete(key: string): boolean;
+    /** Check whether an entry with the given key exists. */
+    has(key: string): boolean;
+    /** Remove all entries. */
+    clear(): void;
+    /** Iterate over all stored values. */
+    values(): IterableIterator<TValue>;
+}

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

@@ -0,0 +1,32 @@
+/** Simple key→value container mapping string keys to cache entries. */
+export class CacheMap {
+    _map = new Map();
+    /** Number of entries currently stored. */
+    get size() {
+        return this._map.size;
+    }
+    /** Return entry by key, or `undefined` if absent. */
+    get(key) {
+        return this._map.get(key);
+    }
+    /** Store an entry under the given key. */
+    set(key, value) {
+        this._map.set(key, value);
+    }
+    /** Remove an entry. Returns `true` if the entry existed. */
+    delete(key) {
+        return this._map.delete(key);
+    }
+    /** Check whether an entry with the given key exists. */
+    has(key) {
+        return this._map.has(key);
+    }
+    /** Remove all entries. */
+    clear() {
+        this._map.clear();
+    }
+    /** Iterate over all stored values. */
+    values() {
+        return this._map.values();
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { IPatchHandle, IQueryCacheEntry, IQueryCacheEntryOptions, Keyed } from "../../../query/types";
+import type { ReadableSignalFnLike } from "../../../signals/types";
+import { Machine } from "../machine/Machine";
+import { CacheEntry } from "./CacheEntry";
+export declare class QueryCacheEntry<TArgs, TData> extends CacheEntry<Machine<TArgs, TData>> implements IQueryCacheEntry<TArgs, TData> {
+    readonly keyedArgs: Keyed<TArgs>;
+    readonly machine$: ReadableSignalFnLike<Machine<TArgs, TData>>;
+    private _queryFn;
+    private _abortController;
+    constructor(options: IQueryCacheEntryOptions<TArgs, TData>);
+    /** Transition to refreshing and re-fetch data. Valid from success or refresh-error. */
+    refresh(): void;
+    /** Re-execute query after error. Valid from error state only. */
+    retry(): void;
+    /** Create an optimistic patch. Returns null if state has no data. */
+    createPatch(patchFn: (data: TData) => void): IPatchHandle | null;
+    /** Abort any in-flight request before completing the entry. */
+    complete(): void;
+    /** @internal Called by Resource when beforeQuery intercept needs to trigger the query. */
+    _execute(): void;
+}