ts-prorm-orm 1.1.0

package/dist/query-optimizers/prepared-statement-cache.js

@@ -0,0 +1,423 @@
+"use strict";
+/**
+ * Prepared Statement Caching
+ * Provides functionality to cache and reuse prepared statements for better performance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryResultCache = exports.PreparedStatementCache = void 0;
+exports.createPreparedStatementCache = createPreparedStatementCache;
+/**
+ * Tracks SQL statement usage (hit/miss counts, execution timings, last-used
+ * time) keyed by normalized SQL + params, with TTL-based expiry.
+ *
+ * IMPORTANT — naming caveat: despite the name, this does **not** cache a real
+ * driver-level prepared-statement handle. None of the `Dialect` implementations
+ * in `src/dialects/**` expose a separate prepare/execute split - `query(sql,
+ * options)` always receives the full SQL text and applies `options.replacements`
+ * / `options.bind` per call (see e.g. `sqlite/index.ts` `query()`, which calls
+ * `connection.prepare(sql)` fresh on every invocation). So there is no reusable
+ * driver object for this class to hold onto; the `compiled` field on each entry
+ * is whatever metadata the caller passes to `set()` (by default just `{}`, or -
+ * see `QueryOptimizer.executeQuery()` - a lightweight `{ sql, paramCount }`
+ * descriptor). In practice this class behaves as a query-usage/hit-count
+ * tracker with an optional metadata slot, not a real statement cache. It is
+ * kept under this name for backwards compatibility with existing callers/tests;
+ * treat `getStats()` / `hitCount` / `topStatements` as the reliable surface,
+ * and don't rely on `compiled` holding an executable handle.
+ *
+ * Invalidation: entries expire via TTL (`options.ttl`, default 1 hour). Since
+ * that alone can serve stale-shaped results after schema changes made via raw
+ * DDL, `invalidateTable()` is provided to drop entries referencing a given
+ * table name on write (e.g. from a caller's insert/update/delete path); it is
+ * not auto-wired to every write in this codebase, but `QueryOptimizer.
+ * invalidateTableCache()` calls it alongside the query-result cache.
+ */
+class PreparedStatementCache {
+    constructor(dialect, options) {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalExecutionTime: 0,
+        };
+        this.dialect = dialect;
+        this.cache = new Map();
+        this.maxSize = options.maxSize || 500;
+        this.ttl = options.ttl || 3600000; // 1 hour default
+        this.normalizeSql = options.normalizeSql !== false;
+        this.onCache = options.onCache;
+        this.onEvict = options.onEvict;
+        this.logging = options.logging || false;
+    }
+    /**
+     * Get a cached prepared statement
+     */
+    get(sql, params) {
+        const key = this.generateKey(sql, params);
+        const entry = this.cache.get(key);
+        if (entry) {
+            // Check if entry has expired
+            if (Date.now() - entry.createdAt > this.ttl) {
+                this.evict(key, entry);
+                this.stats.misses++;
+                return undefined;
+            }
+            // Update statistics
+            entry.hitCount++;
+            entry.lastUsedAt = Date.now();
+            this.stats.hits++;
+            this.log(`Cache hit for: ${key} (hits: ${entry.hitCount})`);
+            return entry;
+        }
+        this.stats.misses++;
+        this.log(`Cache miss for: ${key}`);
+        return undefined;
+    }
+    /**
+     * Store a prepared statement in the cache
+     */
+    set(sql, compiled, params) {
+        const key = this.generateKey(sql, params);
+        // Check if we need to evict entries
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            this.evictOldest();
+        }
+        const entry = {
+            key,
+            sql,
+            compiled,
+            createdAt: Date.now(),
+            hitCount: 0,
+            lastUsedAt: Date.now(),
+            executions: 0,
+            totalExecutionTime: 0,
+        };
+        this.cache.set(key, entry);
+        if (this.onCache) {
+            this.onCache(key, entry);
+        }
+        this.log(`Cached statement: ${key}`);
+        return entry;
+    }
+    /**
+     * Record execution of a prepared statement
+     */
+    recordExecution(key, executionTime) {
+        const entry = this.cache.get(key);
+        if (entry) {
+            entry.executions++;
+            entry.totalExecutionTime += executionTime;
+            this.stats.totalExecutionTime += executionTime;
+        }
+    }
+    /**
+     * Check if a statement is cached
+     */
+    has(sql, params) {
+        const key = this.generateKey(sql, params);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        // Check if entry has expired
+        if (Date.now() - entry.createdAt > this.ttl) {
+            this.evict(key, entry);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Clear all cached statements
+     */
+    clear() {
+        this.cache.clear();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            totalExecutionTime: 0,
+        };
+        this.log('Cache cleared');
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? (this.stats.hits / total) * 100 : 0;
+        // Get most used statements
+        const topStatements = Array.from(this.cache.values())
+            .sort((a, b) => b.hitCount - a.hitCount)
+            .slice(0, 10)
+            .map((s) => ({
+            sql: s.sql,
+            hits: s.hitCount,
+            executions: s.executions,
+            avgExecutionTime: s.executions > 0 ? s.totalExecutionTime / s.executions : 0,
+        }));
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            hitRate: Math.round(hitRate * 100) / 100,
+            totalExecutions: this.stats.totalExecutionTime,
+            evictions: this.stats.evictions,
+            topStatements,
+        };
+    }
+    /**
+     * Get all cached statements
+     */
+    getAll() {
+        return Array.from(this.cache.values());
+    }
+    /**
+     * Generate a cache key from SQL and optional parameters
+     */
+    generateKey(sql, params) {
+        let normalizedSql = sql;
+        if (this.normalizeSql) {
+            // Normalize SQL by replacing values with placeholders
+            normalizedSql = this.normalizeSQL(sql);
+        }
+        if (params && params.length > 0) {
+            // Include params in key if not normalizing SQL
+            return `${normalizedSql}::${JSON.stringify(params)}`;
+        }
+        return normalizedSql;
+    }
+    /**
+     * Normalize SQL for consistent caching
+     */
+    normalizeSQL(sql) {
+        return (sql
+            // Remove extra whitespace
+            .replace(/\s+/g, ' ')
+            // Remove comments
+            .replace(/--.*$/gm, '')
+            .replace(/\/\*[\s\S]*?\*\//g, '')
+            // Uppercase keywords
+            .replace(/\b(SELECT|FROM|WHERE|JOIN|LEFT|RIGHT|INNER|OUTER|ON|AND|OR|ORDER|BY|GROUP|HAVING|LIMIT|OFFSET|INSERT|INTO|VALUES|UPDATE|SET|DELETE)\b/gi, (match) => match.toUpperCase())
+            .trim());
+    }
+    /**
+     * Evict the oldest entry from cache
+     */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastUsedAt < oldestTime) {
+                oldestTime = entry.lastUsedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            const entry = this.cache.get(oldestKey);
+            if (entry) {
+                this.evict(oldestKey, entry);
+            }
+        }
+    }
+    /**
+     * Evict a specific entry from cache
+     */
+    evict(key, entry) {
+        this.cache.delete(key);
+        this.stats.evictions++;
+        if (this.onEvict) {
+            this.onEvict(key, entry);
+        }
+        this.log(`Evicted: ${key}`);
+    }
+    /**
+     * Log a message if logging is enabled
+     */
+    log(message) {
+        if (this.logging) {
+            console.log(`[PreparedStatementCache] ${message}`);
+        }
+    }
+    /**
+     * Invalidate (remove) cache entries whose SQL references the given table.
+     * Intended to be called by write paths (INSERT/UPDATE/DELETE/DDL) so cached
+     * entries can't outlive schema/data changes for that table between TTL
+     * expirations. Not automatically wired into every write in this codebase -
+     * callers that write outside of `QueryOptimizer` should call this explicitly.
+     */
+    invalidateTable(tableName) {
+        let invalidated = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.sql.toLowerCase().includes(tableName.toLowerCase())) {
+                this.evict(key, entry);
+                invalidated++;
+            }
+        }
+        return invalidated;
+    }
+    /**
+     * Remove expired entries
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.createdAt > this.ttl) {
+                this.evict(key, entry);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+    /**
+     * Get cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.PreparedStatementCache = PreparedStatementCache;
+/**
+ * Query result cache for caching query results
+ */
+class QueryResultCache {
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.maxSize = options.maxSize || 100;
+        this.ttl = options.ttl || 60000; // 1 minute default
+        this.logging = options.logging || false;
+    }
+    /**
+     * Get cached query result
+     */
+    get(sql, params) {
+        const key = this.generateKey(sql, params);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        // Check if entry has expired
+        if (Date.now() - entry.createdAt > this.ttl) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        entry.hitCount++;
+        entry.lastUsedAt = Date.now();
+        return entry.result;
+    }
+    /**
+     * Store a query result in cache
+     */
+    set(sql, params, result) {
+        const key = this.generateKey(sql, params);
+        // Check if we need to evict entries
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            this.evictOldest();
+        }
+        this.cache.set(key, {
+            key,
+            sql,
+            params,
+            result,
+            createdAt: Date.now(),
+            lastUsedAt: Date.now(),
+            hitCount: 0,
+        });
+        this.log(`Cached result for: ${key}`);
+    }
+    /**
+     * Check if a query result is cached
+     */
+    has(sql, params) {
+        const key = this.generateKey(sql, params);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() - entry.createdAt > this.ttl) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Invalidate cache for a specific table
+     */
+    invalidateTable(tableName) {
+        let invalidated = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.sql.toLowerCase().includes(tableName.toLowerCase())) {
+                this.cache.delete(key);
+                invalidated++;
+            }
+        }
+        return invalidated;
+    }
+    /**
+     * Clear all cached results
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let hitCount = 0;
+        for (const entry of this.cache.values()) {
+            hitCount += entry.hitCount;
+        }
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hitCount,
+        };
+    }
+    /**
+     * Generate a cache key
+     */
+    generateKey(sql, params) {
+        const normalizedSql = sql.replace(/\s+/g, ' ').trim();
+        if (params && params.length > 0) {
+            return `${normalizedSql}::${JSON.stringify(params)}`;
+        }
+        return normalizedSql;
+    }
+    /**
+     * Evict the oldest entry
+     */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastUsedAt < oldestTime) {
+                oldestTime = entry.lastUsedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+    /**
+     * Log a message
+     */
+    log(message) {
+        if (this.logging) {
+            console.log(`[QueryResultCache] ${message}`);
+        }
+    }
+}
+exports.QueryResultCache = QueryResultCache;
+/**
+ * Create a prepared statement cache
+ */
+function createPreparedStatementCache(dialect, options) {
+    return new PreparedStatementCache(dialect, {
+        maxSize: 500,
+        ...options,
+    });
+}
+exports.default = {
+    PreparedStatementCache,
+    QueryResultCache,
+    createPreparedStatementCache,
+};