@signalium/query 0.0.0 → 0.0.2

package/dist/esm/EntityMap.js

@@ -0,0 +1,42 @@
+import { signal } from 'signalium';
+import { createEntityProxy } from './proxy.js';
+export class EntityStore {
+    map = new Map();
+    hasEntity(key) {
+        return this.map.has(key);
+    }
+    getEntity(key) {
+        return this.map.get(key);
+    }
+    hydratePreloadedEntity(key, shape) {
+        const record = this.getEntity(key);
+        if (record === undefined) {
+            throw new Error(`Entity ${key} not found`);
+        }
+        record.proxy = createEntityProxy(key, record, shape);
+        return record;
+    }
+    setPreloadedEntity(key, obj) {
+        const record = {
+            key,
+            signal: signal(obj),
+            cache: new Map(),
+            proxy: undefined,
+        };
+        this.map.set(key, record);
+        return record;
+    }
+    setEntity(key, obj, shape) {
+        let record = this.map.get(key);
+        if (record === undefined) {
+            record = this.setPreloadedEntity(key, obj);
+            record.proxy = createEntityProxy(key, record, shape);
+        }
+        else {
+            record.signal.value = obj;
+            record.cache.clear();
+        }
+        return record;
+    }
+}
+//# sourceMappingURL=EntityMap.js.map

package/dist/esm/EntityMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityMap.js","sourceRoot":"","sources":["../../src/EntityMap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAW/C,MAAM,OAAO,WAAW;IACd,GAAG,GAAG,IAAI,GAAG,EAAgD,CAAC;IAEtE,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,sBAAsB,CAAC,GAAW,EAAE,KAAgB;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,UAAU,GAAG,YAAY,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,CAAC,KAAK,GAAG,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAErD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,kBAAkB,CAAC,GAAW,EAAE,GAA4B;QAC1D,MAAM,MAAM,GAA0B;YACpC,GAAG;YACH,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;YACnB,KAAK,EAAE,IAAI,GAAG,EAAE;YAChB,KAAK,EAAE,SAAS;SACjB,CAAC;QAEF,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAE1B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,SAAS,CAAC,GAAW,EAAE,GAA4B,EAAE,KAAgB;QACnE,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAE/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAE3C,MAAM,CAAC,KAAK,GAAG,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC;YAC1B,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QAED,OAAO,MAAsB,CAAC;IAChC,CAAC;CACF"}

package/dist/esm/QueryClient.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Query Client with Entity Caching and Deduplication
+ *
+ * Features:
+ * - Global entity map for deduplication
+ * - Entity definitions with cached sub-entity paths
+ * - Eager entity discovery and caching
+ * - Permanent proxy cache for entities
+ * - Response caching for offline access
+ * - Signalium-based reactivity for entity updates
+ * - Self-contained validator (no external dependencies except Signalium)
+ */
+import { type Context, Signal } from 'signalium';
+import { DiscriminatedQueryResult, EntityDef, QueryResult, ObjectFieldTypeDef, RefetchInterval } from './types.js';
+import { EntityRecord } from './EntityMap.js';
+import { QueryStore } from './QueryStore.js';
+export interface QueryContext {
+    fetch: typeof fetch;
+    evictionMultiplier?: number;
+    refetchMultiplier?: number;
+}
+export interface QueryCacheOptions {
+    maxCount?: number;
+    gcTime?: number;
+    staleTime?: number;
+    refetchInterval?: RefetchInterval;
+}
+export interface QueryDefinition<Params, Result> {
+    id: string;
+    shape: ObjectFieldTypeDef;
+    fetchFn: (context: QueryContext, params: Params) => Promise<Result>;
+    cache?: QueryCacheOptions;
+}
+declare class RefetchManager {
+    private multiplier;
+    private intervalId;
+    private clock;
+    private buckets;
+    constructor(multiplier?: number);
+    addQuery(instance: QueryResultImpl<any>): void;
+    removeQuery(query: QueryResultImpl<any>): void;
+    private tick;
+    destroy(): void;
+}
+declare class MemoryEvictionManager {
+    private queryClient;
+    private multiplier;
+    private intervalId;
+    private currentFlush;
+    private nextFlush;
+    constructor(queryClient: QueryClient, multiplier?: number);
+    scheduleEviction(queryKey: number): void;
+    cancelEviction(queryKey: number): void;
+    private tick;
+    destroy(): void;
+}
+/**
+ * QueryResult wraps a DiscriminatedReactivePromise and adds additional functionality
+ * like refetch, while forwarding all the base relay properties.
+ * This class combines the old QueryInstance and QueryResultImpl into a single entity.
+ */
+export declare class QueryResultImpl<T> implements QueryResult<T> {
+    def: QueryDefinition<any, any>;
+    initialized: boolean;
+    isRefetchingSignal: Signal<boolean>;
+    updatedAt: number | undefined;
+    private queryClient;
+    queryKey: number;
+    private params;
+    private relay;
+    private relayState;
+    constructor(def: QueryDefinition<any, any>, queryClient: QueryClient, queryKey: number, params: any);
+    get value(): T | undefined;
+    get error(): unknown;
+    get isPending(): boolean;
+    get isRejected(): boolean;
+    get isResolved(): boolean;
+    get isSettled(): boolean;
+    get isReady(): boolean;
+    get isRefetching(): boolean;
+    get isFetching(): boolean;
+    private get _version();
+    private get _signal();
+    private get _flags();
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    refetch(): Promise<T>;
+    /**
+     * Fetches fresh data, updates the cache, and updates updatedAt timestamp
+     */
+    runQuery(): Promise<T>;
+    isStale(): boolean;
+    /**
+     * Initialize the query by loading from cache and fetching if stale
+     */
+    private initialize;
+    get [Symbol.toStringTag](): string;
+}
+export declare class QueryClient {
+    private store;
+    private context;
+    private entityMap;
+    queryInstances: Map<number, QueryResultImpl<unknown>>;
+    memoryEvictionManager: MemoryEvictionManager;
+    refetchManager: RefetchManager;
+    constructor(store: QueryStore, context?: QueryContext);
+    getContext(): QueryContext;
+    saveQueryData(queryDef: QueryDefinition<any, any>, queryKey: number, data: unknown, entityRefs: Set<number>): void;
+    activateQuery(queryInstance: QueryResultImpl<unknown>): void;
+    loadCachedQuery(queryDef: QueryDefinition<any, any>, queryKey: number): import("./QueryStore.js").MaybePromise<import("./QueryStore.js").CachedQuery | undefined>;
+    /**
+     * Loads a query from the document store and returns a QueryResult
+     * that triggers fetches and prepopulates with cached data
+     */
+    getQuery<Params, Result>(queryDef: QueryDefinition<Params, Result>, params: Params): DiscriminatedQueryResult<Result>;
+    hydrateEntity(key: number, shape: EntityDef): EntityRecord;
+    saveEntity(key: number, obj: Record<string, unknown>, shape: EntityDef, entityRefs?: Set<number>): EntityRecord;
+    destroy(): void;
+}
+export declare const QueryClientContext: Context<QueryClient | undefined>;
+export {};
+//# sourceMappingURL=QueryClient.d.ts.map

package/dist/esm/QueryClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryClient.d.ts","sourceRoot":"","sources":["../../src/QueryClient.ts"],"names":[],"mappings":"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"}

package/dist/esm/QueryClient.js

@@ -0,0 +1,363 @@
+/**
+ * Query Client with Entity Caching and Deduplication
+ *
+ * Features:
+ * - Global entity map for deduplication
+ * - Entity definitions with cached sub-entity paths
+ * - Eager entity discovery and caching
+ * - Permanent proxy cache for entities
+ * - Response caching for offline access
+ * - Signalium-based reactivity for entity updates
+ * - Self-contained validator (no external dependencies except Signalium)
+ */
+import { relay, context, signal } from 'signalium';
+import { hashValue, setReactivePromise } from 'signalium/utils';
+import { parseValue } from './proxy.js';
+import { parseEntities } from './parseEntities.js';
+import { EntityStore } from './EntityMap.js';
+import { ValidatorDef } from './typeDefs.js';
+// QueryInstance is now merged into QueryResultImpl below
+const queryKeyFor = (queryDef, params) => {
+    return hashValue([queryDef.id, params]);
+};
+const BASE_TICK_INTERVAL = 1000; // 1 second
+// Refetch interval manager - uses a fixed 1-second tick
+class RefetchManager {
+    multiplier;
+    intervalId;
+    clock = 0; // Increments by 1000ms on each tick
+    // Buckets: Map of actual interval -> Set of query instances
+    buckets = new Map();
+    constructor(multiplier = 1) {
+        this.multiplier = multiplier;
+        // Start the timer immediately and keep it running
+        const tickInterval = BASE_TICK_INTERVAL * this.multiplier;
+        this.intervalId = setTimeout(() => this.tick(), tickInterval);
+    }
+    addQuery(instance) {
+        const interval = instance.def.cache?.refetchInterval;
+        if (!interval) {
+            return;
+        }
+        const actualInterval = interval * this.multiplier;
+        // Add to bucket by actual interval
+        let bucket = this.buckets.get(actualInterval);
+        if (!bucket) {
+            bucket = new Set();
+            this.buckets.set(actualInterval, bucket);
+        }
+        bucket.add(instance);
+    }
+    removeQuery(query) {
+        const interval = query.def.cache?.refetchInterval;
+        if (!interval) {
+            return;
+        }
+        const actualInterval = interval * this.multiplier;
+        // Remove from bucket
+        const bucket = this.buckets.get(actualInterval);
+        if (bucket) {
+            bucket.delete(query);
+            if (bucket.size === 0) {
+                this.buckets.delete(actualInterval);
+            }
+        }
+    }
+    tick() {
+        this.clock += BASE_TICK_INTERVAL * this.multiplier;
+        // Only process buckets where clock is aligned with the interval
+        for (const [interval, bucket] of this.buckets.entries()) {
+            if (this.clock % interval === 0) {
+                // Process all queries in this bucket
+                for (const query of bucket) {
+                    // Skip if already fetching - let the current fetch complete
+                    if (query && !query.isFetching) {
+                        query.refetch();
+                    }
+                }
+            }
+        }
+        const tickInterval = BASE_TICK_INTERVAL * this.multiplier;
+        this.intervalId = setTimeout(() => this.tick(), tickInterval);
+    }
+    destroy() {
+        clearTimeout(this.intervalId);
+    }
+}
+const EVICTION_INTERVAL = 60 * 1000; // 1 minute
+// Memory eviction manager - uses a single interval with rotating sets to avoid timeout overhead
+class MemoryEvictionManager {
+    queryClient;
+    multiplier;
+    intervalId;
+    currentFlush = new Set(); // Queries to evict on next tick
+    nextFlush = new Set(); // Queries to evict on tick after next
+    constructor(queryClient, multiplier = 1) {
+        this.queryClient = queryClient;
+        this.multiplier = multiplier;
+        this.intervalId = setInterval(this.tick, EVICTION_INTERVAL * this.multiplier);
+    }
+    scheduleEviction(queryKey) {
+        // Add to nextFlush so it waits at least one full interval
+        // This prevents immediate eviction if scheduled right before a tick
+        this.nextFlush.add(queryKey);
+    }
+    cancelEviction(queryKey) {
+        // Remove from both sets to handle reactivation
+        this.currentFlush.delete(queryKey);
+        this.nextFlush.delete(queryKey);
+    }
+    tick = () => {
+        if (!this.queryClient)
+            return;
+        // Evict all queries in currentFlush
+        for (const queryKey of this.currentFlush) {
+            this.queryClient.queryInstances.delete(queryKey);
+        }
+        // Rotate: currentFlush becomes nextFlush, nextFlush becomes empty
+        this.currentFlush = this.nextFlush;
+        this.nextFlush = new Set();
+    };
+    destroy() {
+        clearInterval(this.intervalId);
+    }
+}
+/**
+ * QueryResult wraps a DiscriminatedReactivePromise and adds additional functionality
+ * like refetch, while forwarding all the base relay properties.
+ * This class combines the old QueryInstance and QueryResultImpl into a single entity.
+ */
+export class QueryResultImpl {
+    // Fields from old QueryInstance
+    def;
+    initialized = false;
+    isRefetchingSignal;
+    updatedAt = undefined;
+    // References for refetch functionality
+    queryClient;
+    queryKey;
+    params;
+    relay;
+    relayState = undefined;
+    constructor(def, queryClient, queryKey, params) {
+        setReactivePromise(this);
+        this.def = def;
+        this.queryClient = queryClient;
+        this.queryKey = queryKey;
+        this.params = params;
+        this.isRefetchingSignal = signal(false);
+        // Create the relay and handle activation/deactivation
+        this.relay = relay(state => {
+            this.relayState = state;
+            // Load from cache first, then fetch fresh data
+            this.queryClient.activateQuery(this);
+            if (this.initialized) {
+                if (this.isStale()) {
+                    this.refetch();
+                }
+            }
+            else {
+                this.initialize(state);
+            }
+            // Return deactivation callback
+            return {
+                update: () => {
+                    state.setPromise(this.runQuery());
+                },
+                deactivate: () => {
+                    // Last subscriber left, deactivate refetch and schedule memory eviction
+                    if (this.def.cache?.refetchInterval) {
+                        this.queryClient.refetchManager.removeQuery(this);
+                    }
+                    // Schedule removal from memory using the global eviction manager
+                    // This allows quick reactivation from memory if needed again soon
+                    // Disk cache (if configured) will still be available after eviction
+                    this.queryClient.memoryEvictionManager.scheduleEviction(this.queryKey);
+                },
+            };
+        });
+    }
+    get value() {
+        return this.relay.value;
+    }
+    get error() {
+        return this.relay.error;
+    }
+    get isPending() {
+        return this.relay.isPending;
+    }
+    get isRejected() {
+        return this.relay.isRejected;
+    }
+    get isResolved() {
+        return this.relay.isResolved;
+    }
+    get isSettled() {
+        return this.relay.isSettled;
+    }
+    get isReady() {
+        return this.relay.isReady;
+    }
+    get isRefetching() {
+        return this.isRefetchingSignal.value;
+    }
+    get isFetching() {
+        return this.relay.isPending || this.isRefetching;
+    }
+    // TODO: Intimate APIs needed for `useReactive`, this is a code smell and
+    // we should find a better way to entangle these more generically
+    get _version() {
+        return this.relay._version;
+    }
+    get _signal() {
+        return this.relay._signal;
+    }
+    get _flags() {
+        return this.relay._flags;
+    }
+    // Forward Promise methods
+    then(onfulfilled, onrejected) {
+        return this.relay.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.relay.catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.relay.finally(onfinally);
+    }
+    // Additional methods
+    async refetch() {
+        this.isRefetchingSignal.value = true;
+        try {
+            const result = await this.runQuery();
+            if (this.relayState) {
+                this.relayState.value = result;
+                // Update the version to trigger a re-render for direct React consumers
+                // e.g. `useReactive(query, params)`
+                this._version.update(v => v + 1);
+            }
+            return result;
+        }
+        finally {
+            this.isRefetchingSignal.value = false;
+        }
+    }
+    /**
+     * Fetches fresh data, updates the cache, and updates updatedAt timestamp
+     */
+    async runQuery() {
+        const freshData = await this.def.fetchFn(this.queryClient.getContext(), this.params);
+        // Parse and cache the fresh data
+        const entityRefs = new Set();
+        const shape = this.def.shape;
+        const parsedData = shape instanceof ValidatorDef
+            ? parseEntities(freshData, shape, this.queryClient, entityRefs)
+            : parseValue(freshData, shape, this.def.id);
+        // Cache the data (synchronous, fire-and-forget)
+        this.queryClient.saveQueryData(this.def, this.queryKey, freshData, entityRefs);
+        // Update the timestamp
+        this.updatedAt = Date.now();
+        return parsedData;
+    }
+    isStale() {
+        if (this.updatedAt === undefined) {
+            return true; // No data yet, needs fetch
+        }
+        const staleTime = this.def.cache?.staleTime ?? 0;
+        return Date.now() - this.updatedAt >= staleTime;
+    }
+    /**
+     * Initialize the query by loading from cache and fetching if stale
+     */
+    async initialize(state) {
+        try {
+            this.initialized = true;
+            // Load from cache first
+            const cached = await this.queryClient.loadCachedQuery(this.def, this.queryKey);
+            if (cached !== undefined) {
+                const shape = this.def.shape;
+                state.value =
+                    shape instanceof ValidatorDef
+                        ? parseEntities(cached.value, shape, this.queryClient, new Set())
+                        : parseValue(cached.value, shape, this.def.id);
+                // Set the cached timestamp
+                this.updatedAt = cached.updatedAt;
+                // Check if data is stale
+                if (this.isStale()) {
+                    // Data is stale, trigger background refetch
+                    this.refetch();
+                }
+            }
+            else {
+                // No cached data, fetch fresh
+                state.setPromise(this.runQuery());
+            }
+        }
+        catch (error) {
+            // Relay will handle the error state automatically
+            state.setError(error);
+        }
+    }
+    // Make it work with Symbol.toStringTag for Promise detection
+    get [Symbol.toStringTag]() {
+        return 'QueryResult';
+    }
+}
+export class QueryClient {
+    store;
+    context;
+    entityMap = new EntityStore();
+    queryInstances = new Map();
+    memoryEvictionManager;
+    refetchManager;
+    constructor(store, context = { fetch }) {
+        this.store = store;
+        this.context = context;
+        this.memoryEvictionManager = new MemoryEvictionManager(this, this.context.evictionMultiplier);
+        this.refetchManager = new RefetchManager(this.context.refetchMultiplier);
+    }
+    getContext() {
+        return this.context;
+    }
+    saveQueryData(queryDef, queryKey, data, entityRefs) {
+        this.store.saveQuery(queryDef, queryKey, data, entityRefs);
+    }
+    activateQuery(queryInstance) {
+        const { def, queryKey } = queryInstance;
+        this.store.activateQuery(def, queryKey);
+        this.refetchManager.addQuery(queryInstance);
+        this.memoryEvictionManager.cancelEviction(queryKey);
+    }
+    loadCachedQuery(queryDef, queryKey) {
+        return this.store.loadQuery(queryDef, queryKey, this.entityMap);
+    }
+    /**
+     * Loads a query from the document store and returns a QueryResult
+     * that triggers fetches and prepopulates with cached data
+     */
+    getQuery(queryDef, params) {
+        const queryKey = queryKeyFor(queryDef, params);
+        let queryInstance = this.queryInstances.get(queryKey);
+        // Create a new instance if it doesn't exist
+        if (queryInstance === undefined) {
+            queryInstance = new QueryResultImpl(queryDef, this, queryKey, params);
+            // Store for future use
+            this.queryInstances.set(queryKey, queryInstance);
+        }
+        return queryInstance;
+    }
+    hydrateEntity(key, shape) {
+        return this.entityMap.hydratePreloadedEntity(key, shape);
+    }
+    saveEntity(key, obj, shape, entityRefs) {
+        const record = this.entityMap.setEntity(key, obj, shape);
+        this.store.saveEntity(key, obj, entityRefs);
+        return record;
+    }
+    destroy() {
+        this.refetchManager.destroy();
+        this.memoryEvictionManager.destroy();
+    }
+}
+export const QueryClientContext = context(undefined);
+//# sourceMappingURL=QueryClient.js.map

package/dist/esm/QueryClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryClient.js","sourceRoot":"","sources":["../../src/QueryClient.ts"],"names":[],"mappings":"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"}

package/dist/esm/QueryStore.d.ts

@@ -0,0 +1,77 @@
+/**
+ * QueryStore - Minimal interface for query persistence
+ *
+ * Provides a clean abstraction over document storage, reference counting,
+ * and LRU cache management. Supports both synchronous (in-memory) and
+ * asynchronous (writer-backed) implementations.
+ */
+import { EntityStore } from './EntityMap.js';
+import { QueryDefinition } from './QueryClient.js';
+export interface CachedQuery {
+    value: unknown;
+    updatedAt: number;
+}
+export interface QueryStore {
+    /**
+     * Asynchronously retrieves a document by key.
+     * May return undefined if the document is not in the store.
+     */
+    loadQuery(queryDef: QueryDefinition<any, any>, queryKey: number, entityMap: EntityStore): MaybePromise<CachedQuery | undefined>;
+    /**
+     * Synchronously stores a document with optional reference IDs.
+     * This is fire-and-forget for async implementations.
+     */
+    saveQuery(queryDef: QueryDefinition<any, any>, queryKey: number, value: unknown, refIds?: Set<number>): void;
+    /**
+     * Synchronously stores an entity with optional reference IDs.
+     * This is fire-and-forget for async implementations.
+     */
+    saveEntity(entityKey: number, value: unknown, refIds?: Set<number>): void;
+    /**
+     * Marks a query as accessed, updating the LRU queue.
+     * Handles eviction internally when the cache is full.
+     */
+    activateQuery(queryDef: QueryDefinition<any, any>, queryKey: number): void;
+}
+export type MaybePromise<T> = T | Promise<T>;
+export interface SyncPersistentStore {
+    has(key: string): boolean;
+    getString(key: string): string | undefined;
+    setString(key: string, value: string): void;
+    getNumber(key: string): number | undefined;
+    setNumber(key: string, value: number): void;
+    getBuffer(key: string): Uint32Array | undefined;
+    setBuffer(key: string, value: Uint32Array): void;
+    delete(key: string): void;
+}
+export declare class MemoryPersistentStore implements SyncPersistentStore {
+    private readonly kv;
+    has(key: string): boolean;
+    getString(key: string): string | undefined;
+    setString(key: string, value: string): void;
+    getNumber(key: string): number | undefined;
+    setNumber(key: string, value: number): void;
+    getBuffer(key: string): Uint32Array | undefined;
+    setBuffer(key: string, value: Uint32Array): void;
+    delete(key: string): void;
+}
+export declare const valueKeyFor: (id: number) => string;
+export declare const refCountKeyFor: (id: number) => string;
+export declare const refIdsKeyFor: (id: number) => string;
+export declare const updatedAtKeyFor: (id: number) => string;
+export declare const queueKeyFor: (queryDefId: string) => string;
+export declare class SyncQueryStore implements QueryStore {
+    private readonly kv;
+    queues: Map<string, Uint32Array>;
+    constructor(kv: SyncPersistentStore);
+    loadQuery(queryDef: QueryDefinition<any, any>, queryKey: number, entityMap: EntityStore): CachedQuery | undefined;
+    private preloadEntities;
+    saveQuery(queryDef: QueryDefinition<any, any>, queryKey: number, value: unknown, refIds?: Set<number>): void;
+    saveEntity(entityKey: number, value: unknown, refIds?: Set<number>): void;
+    activateQuery(queryDef: QueryDefinition<any, any>, queryKey: number): void;
+    private setValue;
+    private deleteValue;
+    private incrementRefCount;
+    private decrementRefCount;
+}
+//# sourceMappingURL=QueryStore.d.ts.map

package/dist/esm/QueryStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryStore.d.ts","sourceRoot":"","sources":["../../src/QueryStore.ts"],"names":[],"mappings":"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"}