drizzle-cube 0.2.24 → 0.2.26

package/dist/server/index.d.ts

@@ -36,6 +36,141 @@ export declare interface BaseQueryDefinition {
     where?: SQL;
 }
 
+/**
+ * Cache configuration options
+ */
+export declare interface CacheConfig {
+    /**
+     * Cache provider implementation
+     * Required if caching is enabled
+     */
+    provider: CacheProvider;
+    /**
+     * Default TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    defaultTtlMs?: number;
+    /**
+     * Prefix for all cache keys
+     * Useful for multi-environment setups (e.g., 'prod:', 'dev:')
+     * @default 'drizzle-cube:'
+     */
+    keyPrefix?: string;
+    /**
+     * Enable/disable caching globally
+     * Allows disabling without removing configuration
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to include security context in cache key
+     * CRITICAL for multi-tenant applications - should almost always be true
+     * @default true
+     */
+    includeSecurityContext?: boolean;
+    /**
+     * Custom function to extract cacheable parts of security context
+     * Use when security context contains non-serializable values
+     * @default Uses JSON.stringify on entire security context
+     */
+    securityContextSerializer?: (ctx: SecurityContext) => string;
+    /**
+     * Callback for cache errors (get/set failures)
+     * Cache errors are non-fatal by default - queries still execute
+     */
+    onError?: (error: Error, operation: 'get' | 'set' | 'delete') => void;
+    /**
+     * Callback for cache events (hits, misses, sets)
+     * Useful for monitoring and debugging
+     */
+    onCacheEvent?: (event: CacheEvent) => void;
+}
+
+/**
+ * Metadata about a cached entry
+ * Used to provide cache information in query responses
+ */
+export declare interface CacheEntryMetadata {
+    /** Unix timestamp (ms) when the entry was cached */
+    cachedAt: number;
+    /** Original TTL in milliseconds */
+    ttlMs: number;
+    /** Remaining TTL in milliseconds */
+    ttlRemainingMs: number;
+}
+
+/**
+ * Cache event for monitoring and debugging
+ */
+export declare interface CacheEvent {
+    /** Type of cache event */
+    type: 'hit' | 'miss' | 'set' | 'error';
+    /** Cache key involved */
+    key: string;
+    /** Duration of the cache operation in milliseconds */
+    durationMs: number;
+}
+
+/**
+ * Return type for cache get operations
+ * Includes value and optional metadata for TTL tracking
+ */
+export declare interface CacheGetResult<T> {
+    value: T;
+    metadata?: CacheEntryMetadata;
+}
+
+/**
+ * Configuration for cache key generation
+ */
+declare interface CacheKeyConfig {
+    /** Prefix for all cache keys */
+    keyPrefix?: string;
+    /** Whether to include security context in cache key */
+    includeSecurityContext?: boolean;
+    /** Custom serializer for security context */
+    securityContextSerializer?: (ctx: SecurityContext) => string;
+}
+
+/**
+ * Cache provider interface that users implement for their preferred backend
+ * All methods use async/Promise to support network-based caches (Redis, etc.)
+ */
+export declare interface CacheProvider {
+    /**
+     * Get a cached value by key
+     * @returns The cached value with metadata, or null/undefined if not found or expired
+     */
+    get<T = unknown>(key: string): Promise<CacheGetResult<T> | null | undefined>;
+    /**
+     * Set a value in the cache
+     * @param key - Cache key
+     * @param value - Value to cache (must be JSON-serializable)
+     * @param ttlMs - Time-to-live in milliseconds (optional, uses default if not provided)
+     */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a specific key from the cache
+     * @returns true if key existed and was deleted, false otherwise
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete all keys matching a pattern (for cache invalidation)
+     * Pattern uses glob-style matching: 'prefix:*' matches all keys starting with 'prefix:'
+     * @returns Number of keys deleted
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Optional: Called when the cache provider is no longer needed
+     * Use for cleanup (e.g., closing Redis connections)
+     */
+    close?(): Promise<void>;
+}
+
 /**
  * Compiled cube with execution function
  */
@@ -515,6 +650,47 @@ export declare interface FilterCondition {
  */
 export declare type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'notStartsWith' | 'endsWith' | 'notEndsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'set' | 'notSet' | 'inDateRange' | 'beforeDate' | 'afterDate' | 'between' | 'notBetween' | 'in' | 'notIn' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex' | 'isEmpty' | 'isNotEmpty' | 'arrayContains' | 'arrayOverlaps' | 'arrayContained';
 
+/**
+ * FNV-1a hash - fast, non-cryptographic hash function
+ * Returns hex string for cache key readability
+ *
+ * Properties:
+ * - O(n) time complexity
+ * - Low collision rate for similar strings
+ * - Deterministic across runs
+ *
+ * @param str - String to hash
+ * @returns 8-character hex string
+ */
+export declare function fnv1aHash(str: string): string;
+
+/**
+ * Generate a deterministic cache key from query and security context
+ *
+ * Key structure: {prefix}query:{queryHash}:ctx:{securityHash}
+ *
+ * Uses FNV-1a hash for:
+ * - Speed: ~3x faster than SHA-256
+ * - Simplicity: No dependencies required
+ * - Sufficient collision resistance for cache keys
+ *
+ * @param query - The semantic query to cache
+ * @param securityContext - Security context for tenant isolation
+ * @param config - Cache key configuration
+ * @returns Deterministic cache key string
+ */
+export declare function generateCacheKey(query: SemanticQuery, securityContext: SecurityContext, config?: CacheKeyConfig): string;
+
+/**
+ * Generate invalidation pattern for a cube
+ * Used when cube data changes and all related cache entries need clearing
+ *
+ * @param cubeName - Name of the cube to invalidate
+ * @param keyPrefix - Cache key prefix
+ * @returns Glob pattern for cache invalidation
+ */
+export declare function getCubeInvalidationPattern(cubeName: string, keyPrefix?: string): string;
+
 /**
  * Derive SQL join type from semantic relationship
  */
@@ -735,6 +911,112 @@ export declare interface MeasureMetadata {
  */
 export declare type MeasureType = 'count' | 'countDistinct' | 'countDistinctApprox' | 'sum' | 'avg' | 'min' | 'max' | 'runningTotal' | 'number' | 'calculated' | 'stddev' | 'stddevSamp' | 'variance' | 'varianceSamp' | 'percentile' | 'median' | 'p95' | 'p99' | 'lag' | 'lead' | 'rank' | 'denseRank' | 'rowNumber' | 'ntile' | 'firstValue' | 'lastValue' | 'movingAvg' | 'movingSum';
 
+/**
+ * Simple in-memory cache provider implementing the CacheProvider interface
+ *
+ * Features:
+ * - TTL support with automatic expiration on read
+ * - Optional automatic cleanup of expired entries
+ * - Optional max entries limit with LRU eviction
+ * - Full metadata support for TTL tracking
+ *
+ * Limitations:
+ * - Not shared across processes/instances
+ * - Data lost on process restart
+ * - Not suitable for distributed deployments
+ */
+export declare class MemoryCacheProvider implements CacheProvider {
+    private cache;
+    private defaultTtlMs;
+    private maxEntries?;
+    private cleanupIntervalId?;
+    private accessOrder;
+    constructor(options?: MemoryCacheProviderOptions);
+    /**
+     * Get a cached value by key
+     * Returns null if not found or expired
+     * Automatically removes expired entries on access
+     */
+    get<T>(key: string): Promise<CacheGetResult<T> | null>;
+    /**
+     * Set a value in the cache
+     * Respects maxEntries limit with LRU eviction
+     */
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a specific key from the cache
+     * Returns true if key existed and was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Delete all keys matching a pattern
+     * Supports glob-style patterns with trailing '*'
+     * Returns number of keys deleted
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Check if a key exists in the cache
+     * Returns false for expired entries
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Stop automatic cleanup and clear the cache
+     * Call this when the cache provider is no longer needed
+     */
+    close(): Promise<void>;
+    /**
+     * Remove all expired entries from the cache
+     * Called automatically by cleanup interval
+     * Can also be called manually
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Get current cache size (number of entries)
+     * Note: May include expired entries that haven't been cleaned up yet
+     */
+    size(): number;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    stats(): {
+        size: number;
+        maxEntries?: number;
+        defaultTtlMs: number;
+    };
+    private touchAccessOrder;
+    private removeFromAccessOrder;
+    private evictOldest;
+}
+
+/**
+ * Options for MemoryCacheProvider
+ */
+declare interface MemoryCacheProviderOptions {
+    /**
+     * Default TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    defaultTtlMs?: number;
+    /**
+     * Maximum number of entries in the cache
+     * When exceeded, oldest entries are evicted (LRU)
+     * @default undefined (unlimited)
+     */
+    maxEntries?: number;
+    /**
+     * Interval in milliseconds to run automatic cleanup
+     * Set to 0 to disable automatic cleanup
+     * @default 60000 (1 minute)
+     */
+    cleanupIntervalMs?: number;
+}
+
 /**
  * Multi-cube query context for cross-cube operations
  */
@@ -760,6 +1042,15 @@ export declare class MySQLExecutor extends BaseDatabaseExecutor {
     getEngineType(): 'mysql' | 'singlestore';
 }
 
+/**
+ * Normalize query for consistent hashing
+ * Sorts arrays and object keys to ensure same query = same hash
+ *
+ * @param query - The semantic query to normalize
+ * @returns Normalized query with sorted arrays and keys
+ */
+export declare function normalizeQuery(query: SemanticQuery): SemanticQuery;
+
 /**
  * Period comparison metadata for compareDateRange queries
  * Provides information about the periods being compared
@@ -1033,6 +1324,20 @@ export declare class QueryBuilder {
     buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
 }
 
+/**
+ * Cache metadata included in QueryResult when served from cache
+ */
+export declare interface QueryCacheMetadata {
+    /** Always true when this object is present */
+    hit: true;
+    /** ISO timestamp when the result was cached */
+    cachedAt: string;
+    /** Original TTL in milliseconds */
+    ttlMs: number;
+    /** Remaining TTL in milliseconds */
+    ttlRemainingMs: number;
+}
+
 /**
  * Query context passed to cube SQL functions
  * Provides access to database, schema, and security context
@@ -1064,7 +1369,8 @@ export declare class QueryExecutor {
     private cteBuilder;
     private databaseAdapter;
     private comparisonQueryBuilder;
-    constructor(dbExecutor: DatabaseExecutor);
+    private cacheConfig?;
+    constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig);
     /**
      * Unified query execution method that handles both single and multi-cube queries
      */
@@ -1073,6 +1379,11 @@ export declare class QueryExecutor {
      * Legacy interface for single cube queries
      */
     executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * Execute a comparison query with caching support
+     * Wraps executeComparisonQuery with cache set logic
+     */
+    private executeComparisonQueryWithCache;
     /**
      * Execute a comparison query with multiple date periods
      * Expands compareDateRange into multiple sub-queries and merges results
@@ -1310,6 +1621,17 @@ export declare interface QueryResult {
         /** Period comparison metadata (present when compareDateRange is used) */
         periods?: PeriodComparisonMetadata;
     };
+    /** Cache metadata (present when result served from cache) */
+    cache?: {
+        /** Always true when this object is present */
+        hit: true;
+        /** ISO timestamp when the result was cached */
+        cachedAt: string;
+        /** Original TTL in milliseconds */
+        ttlMs: number;
+        /** Remaining TTL in milliseconds */
+        ttlRemainingMs: number;
+    };
 }
 
 /**
@@ -1368,11 +1690,14 @@ export declare class SemanticLayerCompiler {
     private cubes;
     private dbExecutor?;
     private metadataCache?;
+    private cacheConfig?;
     constructor(options?: {
         drizzle?: DatabaseExecutor['db'];
         schema?: any;
         databaseExecutor?: DatabaseExecutor;
         engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore';
+        /** Cache configuration for query result caching */
+        cache?: CacheConfig;
     });
     /**
      * Set or update the database executor