@revealui/core 0.0.1-pre.4 → 0.2.0

package/dist/cache/query-cache.js

@@ -0,0 +1,260 @@
+/**
+ * Query Result Caching with Redis
+ *
+ * Implements multi-layer caching for database queries
+ */
+import { logger } from '../observability/logger.js';
+// Mock Redis for now - replace with actual Redis connection
+class RedisCache {
+    cache = new Map();
+    stats = {
+        hits: 0,
+        misses: 0,
+        sets: 0,
+        deletes: 0,
+        hitRate: 0,
+    };
+    async get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            this.updateHitRate();
+            return null;
+        }
+        if (Date.now() > entry.expires) {
+            this.cache.delete(key);
+            this.stats.misses++;
+            this.updateHitRate();
+            return null;
+        }
+        this.stats.hits++;
+        this.updateHitRate();
+        return entry.value;
+    }
+    async set(key, value, ttl) {
+        this.cache.set(key, {
+            value,
+            expires: Date.now() + ttl * 1000,
+        });
+        this.stats.sets++;
+    }
+    async setex(key, ttl, value) {
+        await this.set(key, value, ttl);
+    }
+    async del(...keys) {
+        let deleted = 0;
+        for (const key of keys) {
+            if (this.cache.delete(key)) {
+                deleted++;
+                this.stats.deletes++;
+            }
+        }
+        return deleted;
+    }
+    async keys(pattern) {
+        const regex = new RegExp(pattern.replace('*', '.*'));
+        return Array.from(this.cache.keys()).filter((key) => regex.test(key));
+    }
+    async flushall() {
+        this.cache.clear();
+    }
+    getStats() {
+        return { ...this.stats };
+    }
+    updateHitRate() {
+        const total = this.stats.hits + this.stats.misses;
+        this.stats.hitRate = total > 0 ? (this.stats.hits / total) * 100 : 0;
+    }
+}
+const redis = new RedisCache();
+/**
+ * Cache a query result
+ */
+export async function cacheQuery(key, queryFn, options = {}) {
+    const { ttl = 300, // 5 minutes default
+    prefix = 'query', } = options;
+    const cacheKey = `${prefix}:${key}`;
+    // Try cache first
+    const cached = await redis.get(cacheKey);
+    if (cached) {
+        try {
+            return JSON.parse(cached);
+        }
+        catch (error) {
+            logger.error('Cache parse error', error instanceof Error ? error : new Error(String(error)));
+            // Continue to execute query
+        }
+    }
+    // Execute query
+    const result = await queryFn();
+    // Cache result
+    try {
+        await redis.setex(cacheKey, ttl, JSON.stringify(result));
+    }
+    catch (error) {
+        logger.error('Cache set error', error instanceof Error ? error : new Error(String(error)));
+        // Continue even if caching fails
+    }
+    return result;
+}
+/**
+ * Invalidate cache by key
+ */
+export async function invalidateCache(key) {
+    await redis.del(key);
+}
+/**
+ * Invalidate cache by pattern
+ */
+export async function invalidateCachePattern(pattern) {
+    const keys = await redis.keys(pattern);
+    if (keys.length > 0) {
+        await redis.del(...keys);
+    }
+}
+/**
+ * Invalidate cache by tags
+ */
+export async function invalidateCacheTags(tags) {
+    for (const tag of tags) {
+        await invalidateCachePattern(`*:tag:${tag}:*`);
+    }
+}
+/**
+ * Clear all cache
+ */
+export async function clearCache() {
+    await redis.flushall();
+}
+/**
+ * Get cache statistics
+ */
+export function getCacheStats() {
+    return redis.getStats();
+}
+/**
+ * Cache for list queries
+ */
+export async function cacheList(resource, filters, queryFn, ttl = 300) {
+    const filterKey = Object.entries(filters)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const cacheKey = `list:${resource}:${filterKey}`;
+    return cacheQuery(cacheKey, queryFn, { ttl, prefix: 'list' });
+}
+/**
+ * Cache for single item queries
+ */
+export async function cacheItem(resource, id, queryFn, ttl = 300) {
+    const cacheKey = `item:${resource}:${id}`;
+    return cacheQuery(cacheKey, queryFn, { ttl, prefix: 'item' });
+}
+/**
+ * Cache for count queries
+ */
+export async function cacheCount(resource, filters, queryFn, ttl = 300) {
+    const filterKey = Object.entries(filters)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const cacheKey = `count:${resource}:${filterKey}`;
+    return cacheQuery(cacheKey, queryFn, { ttl, prefix: 'count' });
+}
+/**
+ * Invalidate resource cache
+ */
+export async function invalidateResource(resource) {
+    await invalidateCachePattern(`*:${resource}:*`);
+}
+/**
+ * Warm cache with data
+ */
+export async function warmCache(key, data, ttl = 300) {
+    await redis.setex(`query:${key}`, ttl, JSON.stringify(data));
+}
+/**
+ * Get cached value without executing query
+ */
+export async function getCached(key) {
+    const cached = await redis.get(`query:${key}`);
+    if (!cached)
+        return null;
+    try {
+        return JSON.parse(cached);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if key exists in cache
+ */
+export async function cacheExists(key) {
+    const cached = await redis.get(`query:${key}`);
+    return cached !== null;
+}
+/**
+ * Memoize function with cache
+ */
+export function memoize(fn, options = {}) {
+    return (async (...args) => {
+        const key = `memoize:${fn.name}:${JSON.stringify(args)}`;
+        return cacheQuery(key, () => fn(...args), options);
+    });
+}
+/**
+ * Create cache wrapper for query function
+ */
+export function withCache(queryFn, options) {
+    return (async (...args) => {
+        const key = options.keyFn(...args);
+        return cacheQuery(key, () => queryFn(...args), {
+            ttl: options.ttl,
+            prefix: options.prefix,
+        });
+    });
+}
+/**
+ * Batch cache operations
+ */
+export async function batchCache(operations) {
+    return Promise.all(operations.map(({ key, queryFn, ttl }) => cacheQuery(key, queryFn, { ttl })));
+}
+/**
+ * Cache with stale-while-revalidate pattern
+ */
+export async function cacheSWR(key, queryFn, options = {}) {
+    const { ttl = 300, staleTime = 60 } = options;
+    const cacheKey = `query:${key}`;
+    const staleKey = `${cacheKey}:stale`;
+    // Try fresh cache
+    const cached = await redis.get(cacheKey);
+    if (cached) {
+        return JSON.parse(cached);
+    }
+    // Try stale cache while revalidating
+    const stale = await redis.get(staleKey);
+    if (stale) {
+        // Return stale data immediately
+        const staleData = JSON.parse(stale);
+        // Revalidate in background
+        queryFn()
+            .then((fresh) => {
+            redis.setex(cacheKey, ttl, JSON.stringify(fresh));
+            redis.setex(staleKey, staleTime, JSON.stringify(fresh));
+        })
+            .catch((error) => {
+            logger.error('SWR revalidation error', error instanceof Error ? error : new Error(String(error)));
+        });
+        return staleData;
+    }
+    // No cache, execute query
+    const result = await queryFn();
+    // Cache both fresh and stale
+    await Promise.all([
+        redis.setex(cacheKey, ttl, JSON.stringify(result)),
+        redis.setex(staleKey, staleTime, JSON.stringify(result)),
+    ]);
+    return result;
+}

package/dist/caching/app-cache.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Application-Level Caching
+ *
+ * Utilities for React Query, SWR, and application-level cache management
+ */
+/**
+ * React Query Configuration
+ */
+export interface ReactQueryConfig {
+    defaultOptions?: {
+        queries?: {
+            staleTime?: number;
+            cacheTime?: number;
+            refetchOnWindowFocus?: boolean;
+            refetchOnReconnect?: boolean;
+            refetchOnMount?: boolean;
+            retry?: number | boolean;
+            retryDelay?: number | ((attemptIndex: number) => number);
+        };
+        mutations?: {
+            retry?: number | boolean;
+            retryDelay?: number | ((attemptIndex: number) => number);
+        };
+    };
+}
+export declare const DEFAULT_REACT_QUERY_CONFIG: ReactQueryConfig;
+/**
+ * SWR Configuration
+ */
+export interface SWRConfig {
+    revalidateOnFocus?: boolean;
+    revalidateOnReconnect?: boolean;
+    refreshInterval?: number;
+    dedupingInterval?: number;
+    loadingTimeout?: number;
+    errorRetryInterval?: number;
+    errorRetryCount?: number;
+    focusThrottleInterval?: number;
+    shouldRetryOnError?: boolean;
+    keepPreviousData?: boolean;
+}
+export declare const DEFAULT_SWR_CONFIG: SWRConfig;
+/**
+ * Cache Key Generator
+ */
+export declare class CacheKeyGenerator {
+    private prefix;
+    constructor(prefix?: string);
+    /**
+     * Generate key for list queries
+     */
+    list(resource: string, filters?: Record<string, unknown>): string[];
+    /**
+     * Generate key for detail queries
+     */
+    detail(resource: string, id: string | number): string[];
+    /**
+     * Generate key for custom queries
+     */
+    custom(...parts: (string | number | Record<string, unknown>)[]): string[];
+    /**
+     * Generate key for infinite queries
+     */
+    infinite(resource: string, filters?: Record<string, unknown>): string[];
+}
+/**
+ * Cache Invalidation Strategies
+ */
+export declare class CacheInvalidator {
+    /**
+     * Invalidate by resource
+     */
+    static byResource(resource: string): string[];
+    /**
+     * Invalidate by ID
+     */
+    static byId(resource: string, id: string | number): string[];
+    /**
+     * Invalidate lists
+     */
+    static lists(resource: string): string[];
+    /**
+     * Invalidate infinite queries
+     */
+    static infinite(resource: string): string[];
+    /**
+     * Invalidate all
+     */
+    static all(): string[];
+}
+/**
+ * Optimistic Update Helper
+ */
+export declare class OptimisticUpdater<_T> {
+    /**
+     * Update list (add item)
+     */
+    static addToList<T>(oldData: T[] | undefined, newItem: T): T[];
+    /**
+     * Update list (remove item)
+     */
+    static removeFromList<T extends {
+        id: string | number;
+    }>(oldData: T[] | undefined, id: string | number): T[];
+    /**
+     * Update list (update item)
+     */
+    static updateInList<T extends {
+        id: string | number;
+    }>(oldData: T[] | undefined, id: string | number, updates: Partial<T>): T[];
+    /**
+     * Update detail
+     */
+    static updateDetail<T>(oldData: T | undefined, updates: Partial<T>): T | undefined;
+    /**
+     * Update paginated list
+     */
+    static updatePaginatedList<T extends {
+        id: string | number;
+    }>(oldData: {
+        pages: Array<{
+            data: T[];
+        }>;
+        pageParams: unknown[];
+    } | undefined, id: string | number, updates: Partial<T>): {
+        pages: {
+            data: T[];
+        }[];
+        pageParams: unknown[];
+    } | undefined;
+}
+/**
+ * Cache Prefetch Helper
+ */
+export interface PrefetchConfig {
+    staleTime?: number;
+    cacheTime?: number;
+}
+export declare class CachePrefetcher {
+    /**
+     * Prefetch on hover
+     */
+    static onHover(prefetchFn: () => Promise<unknown>, delay?: number): {
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+    /**
+     * Prefetch on visibility
+     */
+    static onVisible(element: HTMLElement | null, prefetchFn: () => Promise<unknown>, options?: IntersectionObserverInit): () => void;
+    /**
+     * Prefetch on idle
+     */
+    static onIdle(prefetchFn: () => Promise<unknown>): void;
+}
+/**
+ * Cache Persistence
+ */
+export interface CachePersistenceConfig {
+    key: string;
+    storage?: 'localStorage' | 'sessionStorage' | 'indexedDB';
+    version?: number;
+    maxAge?: number;
+}
+export declare class CachePersistence {
+    private config;
+    constructor(config: CachePersistenceConfig);
+    /**
+     * Save to storage
+     */
+    save(data: unknown): Promise<void>;
+    /**
+     * Load from storage
+     */
+    load(): Promise<unknown | null>;
+    /**
+     * Remove from storage
+     */
+    remove(): Promise<void>;
+    /**
+     * Save to IndexedDB
+     */
+    private saveToIndexedDB;
+    /**
+     * Load from IndexedDB
+     */
+    private loadFromIndexedDB;
+    /**
+     * Remove from IndexedDB
+     */
+    private removeFromIndexedDB;
+}
+/**
+ * Cache Statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    totalQueries: number;
+    cacheSize: number;
+}
+export declare class CacheStatsTracker {
+    private hits;
+    private misses;
+    /**
+     * Record cache hit
+     */
+    recordHit(): void;
+    /**
+     * Record cache miss
+     */
+    recordMiss(): void;
+    /**
+     * Get statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics
+     */
+    reset(): void;
+}
+/**
+ * Query dedupe helper
+ */
+export declare class QueryDeduplicator {
+    private pending;
+    /**
+     * Deduplicate query
+     */
+    dedupe<T>(key: string, queryFn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear pending queries
+     */
+    clear(): void;
+}
+//# sourceMappingURL=app-cache.d.ts.map

package/dist/caching/app-cache.d.ts.map

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