Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | /**
* Cache types for Drizzle Cube semantic layer
* Provides pluggable caching for query results
*/
import type { SecurityContext } from './core'
/**
* Return type for cache get operations
* Includes value and optional metadata for TTL tracking
*/
export interface CacheGetResult<T> {
value: T
metadata?: CacheEntryMetadata
}
/**
* Metadata about a cached entry
* Used to provide cache information in query responses
*/
export 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 provider interface that users implement for their preferred backend
* All methods use async/Promise to support network-based caches (Redis, etc.)
*/
export 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>
}
/**
* Cache event for monitoring and debugging
*/
export 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
}
/**
* Cache configuration options
*/
export 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
}
/**
* Cache metadata included in QueryResult when served from cache
*/
export 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
}
|