@jay-js/system/dist/query/cache.d.ts

A powerful and flexible TypeScript library for UI, state management, lazy loading, routing and managing draggable elements in modern web applications.

import type { TCacheEntry } from "./types.js";
/**
 * Global query cache singleton
 * Manages cached data across all queries with automatic garbage collection
 */
declare class QueryCache {
    private cache;
    private gcTimers;
    private listeners;
    /**
     * Get cached data for a key
     *
     * @param key Query key
     * @returns Cache entry or undefined if not found
     */
    get<TData>(key: string): TCacheEntry<TData> | undefined;
    /**
     * Set cached data for a key
     *
     * @param key Query key
     * @param data Data to cache
     * @param cacheTime Time in ms before garbage collection
     */
    set<TData>(key: string, data: TData, cacheTime: number): void;
    /**
     * Check if data is stale
     *
     * @param key Query key
     * @param staleTime Time in ms before data is considered stale
     * @returns True if data is stale or not found
     */
    isStale(key: string, staleTime: number): boolean;
    /**
     * Delete cache entry
     *
     * @param key Query key
     */
    delete(key: string): void;
    /**
     * Increment subscriber count
     *
     * @param key Query key
     */
    subscribe(key: string): void;
    /**
     * Decrement subscriber count
     *
     * @param key Query key
     */
    unsubscribe(key: string): void;
    /**
     * Register a listener for cache changes on a specific key
     *
     * @param key Query key to watch
     * @param callback Function to call when cache is updated
     * @returns Cleanup function to remove the listener
     */
    onChange(key: string, callback: (data: any) => void): () => void;
    /**
     * Remove a listener for a specific key
     *
     * @param key Query key
     * @param callback Callback to remove
     */
    offChange(key: string, callback: (data: any) => void): void;
    /**
     * Schedule garbage collection for inactive query
     *
     * @param key Query key
     * @param cacheTime Time in ms before garbage collection
     */
    private scheduleGC;
    /**
     * Clear all cache
     */
    clear(): void;
    /**
     * Invalidate queries matching a pattern
     * Supports glob patterns (* and ?) and RegExp
     *
     * @param pattern Glob pattern string or RegExp to match keys
     * @returns Array of invalidated keys
     *
     * @example
     * ```typescript
     * // Invalidate all user queries
     * queryCache.invalidatePattern('user-*');
     *
     * // Invalidate with regex
     * queryCache.invalidatePattern(/^user-\d+$/);
     * ```
     */
    invalidatePattern(pattern: string | RegExp): string[];
    /**
     * Invalidate queries matching a predicate function
     *
     * @param predicate Function that returns true for keys to invalidate
     * @returns Array of invalidated keys
     *
     * @example
     * ```typescript
     * // Invalidate all stale queries
     * queryCache.invalidateQueries((key, entry) => {
     *   const age = Date.now() - entry.timestamp;
     *   return age > 60000; // 1 minute
     * });
     * ```
     */
    invalidateQueries(predicate: (key: string, entry: TCacheEntry<any>) => boolean): string[];
    /**
     * Get all cache keys
     *
     * @returns Array of all cached query keys
     */
    getKeys(): string[];
    /**
     * Match key against pattern
     *
     * @param key Query key
     * @param pattern String glob pattern or RegExp
     * @returns True if key matches pattern
     */
    private matchesPattern;
    /**
     * Get cache size
     */
    get size(): number;
}
/**
 * Global cache singleton instance
 */
export declare const queryCache: QueryCache;
export {};