masterrecord 0.3.5 → 0.3.7

package/Cache/QueryCache.js

@@ -0,0 +1,175 @@
+/**
+ * Production-Grade Query Result Cache
+ * Similar to EF Core's EFCoreSecondLevelCacheInterceptor
+ */
+class QueryCache {
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.ttl = options.ttl || 5 * 60 * 1000;  // 5 minutes default
+        this.maxSize = options.maxSize || 1000;    // LRU eviction
+        this.enabled = options.enabled !== false;
+        this.hitCount = 0;
+        this.missCount = 0;
+
+        // Start cleanup timer
+        this._startCleanupTimer();
+    }
+
+    /**
+     * Generate deterministic cache key from query + params
+     * Like Hibernate's query cache regions
+     */
+    generateKey(query, params, tableName) {
+        const crypto = require('crypto');
+        const normalizedQuery = query.trim().toLowerCase().replace(/\s+/g, ' ');
+        const keyData = {
+            query: normalizedQuery,
+            params: params || [],
+            table: tableName
+        };
+        return crypto.createHash('sha256')
+            .update(JSON.stringify(keyData))
+            .digest('hex');
+    }
+
+    /**
+     * Get cached query result
+     */
+    get(cacheKey) {
+        if (!this.enabled) return null;
+
+        const entry = this.cache.get(cacheKey);
+        if (!entry) {
+            this.missCount++;
+            return null;
+        }
+
+        // Check TTL expiration
+        if (Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(cacheKey);
+            this.missCount++;
+            return null;
+        }
+
+        // Update LRU metadata
+        entry.hits++;
+        entry.lastAccess = Date.now();
+        this.hitCount++;
+
+        // Log cache hit in dev
+        if (process.env.NODE_ENV !== 'production') {
+            console.debug(`[QueryCache HIT] Key: ${cacheKey.substring(0, 8)}... (${entry.hits} hits)`);
+        }
+
+        return entry.data;
+    }
+
+    /**
+     * Store query result in cache
+     */
+    set(cacheKey, data, tableName) {
+        if (!this.enabled) return;
+
+        // LRU eviction if at capacity
+        if (this.cache.size >= this.maxSize) {
+            this._evictLRU();
+        }
+
+        this.cache.set(cacheKey, {
+            data: data,
+            timestamp: Date.now(),
+            lastAccess: Date.now(),
+            hits: 0,
+            tableName: tableName
+        });
+
+        // Log cache set in dev
+        if (process.env.NODE_ENV !== 'production') {
+            console.debug(`[QueryCache SET] Key: ${cacheKey.substring(0, 8)}... Table: ${tableName}`);
+        }
+    }
+
+    /**
+     * Invalidate all cache entries for a table
+     * Called automatically on INSERT/UPDATE/DELETE
+     */
+    invalidateTable(tableName) {
+        let invalidated = 0;
+        for (const [key, entry] of this.cache) {
+            if (entry.tableName === tableName) {
+                this.cache.delete(key);
+                invalidated++;
+            }
+        }
+
+        if (process.env.NODE_ENV !== 'production') {
+            console.debug(`[QueryCache INVALIDATE] Table: ${tableName} (${invalidated} entries)`);
+        }
+    }
+
+    /**
+     * Clear all cache entries
+     */
+    clear() {
+        this.cache.clear();
+        this.hitCount = 0;
+        this.missCount = 0;
+    }
+
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.hitCount + this.missCount;
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hits: this.hitCount,
+            misses: this.missCount,
+            hitRate: total > 0 ? (this.hitCount / total * 100).toFixed(2) + '%' : '0%',
+            enabled: this.enabled
+        };
+    }
+
+    /**
+     * LRU eviction - remove least recently used entry
+     */
+    _evictLRU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+
+        for (const [key, entry] of this.cache) {
+            if (entry.lastAccess < oldestTime) {
+                oldestTime = entry.lastAccess;
+                oldestKey = key;
+            }
+        }
+
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+
+    /**
+     * Background cleanup of expired entries
+     */
+    _startCleanupTimer() {
+        setInterval(() => {
+            const now = Date.now();
+            let cleaned = 0;
+
+            for (const [key, entry] of this.cache) {
+                if (now - entry.timestamp > this.ttl) {
+                    this.cache.delete(key);
+                    cleaned++;
+                }
+            }
+
+            if (cleaned > 0 && process.env.NODE_ENV !== 'production') {
+                console.debug(`[QueryCache CLEANUP] Removed ${cleaned} expired entries`);
+            }
+        }, 60000); // Run every minute
+    }
+}
+
+module.exports = QueryCache;

package/Cache/RedisQueryCache.js

@@ -0,0 +1,155 @@
+/**
+ * Distributed Query Cache using Redis
+ * For multi-process/clustered deployments
+ */
+class RedisQueryCache {
+    constructor(redisClient, options = {}) {
+        this.redis = redisClient;
+        this.localCache = new Map();  // L1 cache (in-memory)
+        this.ttl = options.ttl || 5 * 60;  // Redis uses seconds
+        this.enabled = options.enabled !== false;
+        this.prefix = options.prefix || 'qcache:';
+
+        // Subscribe to invalidation events
+        this._setupInvalidationSubscription();
+    }
+
+    generateKey(query, params, tableName) {
+        const crypto = require('crypto');
+        const hash = crypto.createHash('sha256')
+            .update(JSON.stringify({query, params}))
+            .digest('hex');
+        return `${this.prefix}${tableName}:${hash}`;
+    }
+
+    async get(cacheKey) {
+        if (!this.enabled) return null;
+
+        // L1: Check local cache first (fast)
+        if (this.localCache.has(cacheKey)) {
+            const entry = this.localCache.get(cacheKey);
+            if (Date.now() - entry.timestamp < 30000) {  // 30s local TTL
+                return entry.data;
+            }
+            this.localCache.delete(cacheKey);
+        }
+
+        // L2: Check Redis (distributed)
+        try {
+            const cached = await this.redis.get(cacheKey);
+            if (cached) {
+                const data = JSON.parse(cached);
+
+                // Populate L1
+                this.localCache.set(cacheKey, {
+                    data: data,
+                    timestamp: Date.now()
+                });
+
+                return data;
+            }
+        } catch (error) {
+            console.error('[RedisQueryCache] Get error:', error);
+        }
+
+        return null;
+    }
+
+    async set(cacheKey, data, tableName) {
+        if (!this.enabled) return;
+
+        try {
+            // Store in Redis with TTL
+            await this.redis.setex(cacheKey, this.ttl, JSON.stringify(data));
+
+            // Store in L1
+            this.localCache.set(cacheKey, {
+                data: data,
+                timestamp: Date.now()
+            });
+        } catch (error) {
+            console.error('[RedisQueryCache] Set error:', error);
+        }
+    }
+
+    async invalidateTable(tableName) {
+        try {
+            // Find all keys for this table
+            const pattern = `${this.prefix}${tableName}:*`;
+            const keys = await this.redis.keys(pattern);
+
+            if (keys.length > 0) {
+                await this.redis.del(...keys);
+            }
+
+            // Clear L1
+            for (const [key] of this.localCache) {
+                if (key.includes(tableName)) {
+                    this.localCache.delete(key);
+                }
+            }
+
+            // Publish invalidation to other processes
+            await this.redis.publish('cache-invalidate', JSON.stringify({
+                table: tableName,
+                timestamp: Date.now()
+            }));
+
+        } catch (error) {
+            console.error('[RedisQueryCache] Invalidate error:', error);
+        }
+    }
+
+    _setupInvalidationSubscription() {
+        // Subscribe to invalidation messages from other processes
+        const subscriber = this.redis.duplicate();
+        subscriber.subscribe('cache-invalidate', (message) => {
+            try {
+                const event = JSON.parse(message);
+
+                // Clear local cache for this table
+                for (const [key] of this.localCache) {
+                    if (key.includes(event.table)) {
+                        this.localCache.delete(key);
+                    }
+                }
+            } catch (error) {
+                console.error('[RedisQueryCache] Subscription error:', error);
+            }
+        });
+    }
+
+    async clear() {
+        try {
+            const keys = await this.redis.keys(`${this.prefix}*`);
+            if (keys.length > 0) {
+                await this.redis.del(...keys);
+            }
+            this.localCache.clear();
+        } catch (error) {
+            console.error('[RedisQueryCache] Clear error:', error);
+        }
+    }
+
+    async getStats() {
+        try {
+            const keys = await this.redis.keys(`${this.prefix}*`);
+            return {
+                size: keys.length,
+                localSize: this.localCache.size,
+                enabled: this.enabled,
+                ttl: this.ttl
+            };
+        } catch (error) {
+            console.error('[RedisQueryCache] GetStats error:', error);
+            return {
+                size: 0,
+                localSize: this.localCache.size,
+                enabled: this.enabled,
+                ttl: this.ttl
+            };
+        }
+    }
+}
+
+module.exports = RedisQueryCache;

package/QueryLanguage/queryMethods.js

@@ -10,6 +10,7 @@ class queryMethods{
         this.__entity = entity;
         this.__context = context;
         this.__queryObject = new queryScript();
+        this.__useCache = true;  // Enable caching by default
     }
 
     // build a single entity
@@ -87,6 +88,15 @@ class queryMethods{
         return this;
     }
 
+    /**
+     * Disable query caching for this query
+     * Use for queries that should always hit database
+     */
+    noCache() {
+        this.__useCache = false;
+        return this;
+    }
+
     raw(query){
         this.__queryObject.raw(query);
         return this;
@@ -321,47 +331,84 @@ class queryMethods{
             this.__queryObject.script.take = 1;
         }
 
+        // Generate cache key
+        const tableName = this.__entity.__name;
+        const queryString = JSON.stringify(this.__queryObject.script);
+        const params = this.__queryObject.script.parameters ? this.__queryObject.script.parameters.getParams() : [];
+        const cacheKey = this.__context._queryCache.generateKey(queryString, params, tableName);
+
+        // Check cache first (if enabled for this query)
+        if (this.__useCache) {
+            const cached = this.__context._queryCache.get(cacheKey);
+            if (cached) {
+                this.__reset();
+                return cached;
+            }
+        }
+
+        // Cache miss - execute query
+        var result = null;
         if(this.__context.isSQLite){
             var entityValue = this.__context._SQLEngine.get(this.__queryObject.script, this.__entity, this.__context);
-            var sing = this.__singleEntityBuilder(entityValue);
-            this.__reset();
-            return sing;
+            result = this.__singleEntityBuilder(entityValue);
         }
-        
+
         if(this.__context.isMySQL){
             var entityValue = this.__context._SQLEngine.get(this.__queryObject.script, this.__entity, this.__context);
-            var sing = this.__singleEntityBuilder(entityValue[0]);
-            this.__reset();
-            return sing;
+            result = this.__singleEntityBuilder(entityValue[0]);
         }
+
+        // Store in cache
+        if (this.__useCache && result) {
+            this.__context._queryCache.set(cacheKey, result, tableName);
+        }
+
+        this.__reset();
+        return result;
     }
 
     toList(){
-        if(this.__context.isSQLite){
-            if(this.__queryObject.script.entityMap.length === 0){
-                this.__queryObject.skipClause( this.__entity.__name);
-                if(!this.__queryObject.script.take || this.__queryObject.script.take === 0){
-                    this.__queryObject.script.take = 1000;
-                }
+        if(this.__queryObject.script.entityMap.length === 0){
+            this.__queryObject.skipClause( this.__entity.__name);
+            if(!this.__queryObject.script.take || this.__queryObject.script.take === 0){
+                this.__queryObject.script.take = 1000;
+            }
+        }
+
+        // Generate cache key
+        const tableName = this.__entity.__name;
+        const queryString = JSON.stringify(this.__queryObject.script);
+        const params = this.__queryObject.script.parameters ? this.__queryObject.script.parameters.getParams() : [];
+        const cacheKey = this.__context._queryCache.generateKey(queryString, params, tableName);
+
+        // Check cache first (if enabled for this query)
+        if (this.__useCache) {
+            const cached = this.__context._queryCache.get(cacheKey);
+            if (cached) {
+                this.__reset();
+                return cached;
             }
+        }
+
+        // Cache miss - execute query
+        var result = [];
+        if(this.__context.isSQLite){
             var entityValue = this.__context._SQLEngine.all(this.__queryObject.script, this.__entity, this.__context);
-            var toLi = this.__multipleEntityBuilder(entityValue);
-            this.__reset();
-            return toLi;
+            result = this.__multipleEntityBuilder(entityValue);
         }
 
         if(this.__context.isMySQL){
-            if(this.__queryObject.script.entityMap.length === 0){
-                this.__queryObject.skipClause( this.__entity.__name);
-                if(!this.__queryObject.script.take || this.__queryObject.script.take === 0){
-                    this.__queryObject.script.take = 1000;
-                }
-            }
             var entityValue = this.__context._SQLEngine.all(this.__queryObject.script, this.__entity, this.__context);
-            var toLi = this.__multipleEntityBuilder(entityValue);
-            this.__reset();
-            return toLi;
+            result = this.__multipleEntityBuilder(entityValue);
         }
+
+        // Store in cache
+        if (this.__useCache && result) {
+            this.__context._queryCache.set(cacheKey, result, tableName);
+        }
+
+        this.__reset();
+        return result;
     }
 
       // ------------------------------- FUNCTIONS THAT UPDATE SQL START FROM HERE  -----------------------------------------------------

package/context.js

@@ -14,6 +14,7 @@ var path = require('path');
 const appRoot = require('app-root-path');
 const MySQLClient = require('masterrecord/mySQLSyncConnect');
 const PostgresClient = require('masterrecord/postgresSyncConnect');
+const QueryCache = require('./Cache/QueryCache');
 
 class context {
     _isModelValid = {
@@ -32,11 +33,26 @@ class context {
     isMySQL = false;
     isPostgres = false;
 
+    // Static shared cache - all context instances share the same cache
+    static _sharedQueryCache = null;
+
     constructor(){
         this. __environment = process.env.master;
         this.__name = this.constructor.name;
         this._SQLEngine = "";
         this.__trackedEntitiesMap = new Map();  // Initialize Map for O(1) lookups
+
+        // Initialize shared query cache (only once across all instances)
+        if (!context._sharedQueryCache) {
+            context._sharedQueryCache = new QueryCache({
+                ttl: process.env.QUERY_CACHE_TTL || 5 * 60 * 1000,  // 5 min default
+                maxSize: process.env.QUERY_CACHE_SIZE || 1000,
+                enabled: process.env.QUERY_CACHE_ENABLED !== 'false'
+            });
+        }
+
+        // Reference the shared cache
+        this._queryCache = context._sharedQueryCache;
     }
 
         /* 
@@ -549,6 +565,15 @@ class context {
             const tracked = this.__trackedEntities;
 
             if(tracked.length > 0){
+                // Collect affected tables for cache invalidation
+                const affectedTables = new Set();
+                for (let i = 0; i < tracked.length; i++) {
+                    const entity = tracked[i];
+                    if (entity.__entity && entity.__entity.__name) {
+                        affectedTables.add(entity.__entity.__name);
+                    }
+                }
+
                 // Handle transactions based on database type
                 if(this.isSQLite){
                     this._SQLEngine.startTransaction();
@@ -568,6 +593,11 @@ class context {
                     this._processTrackedEntities(tracked);
                     this.__clearErrorHandler();
                 }
+
+                // Invalidate query cache for affected tables
+                for (const tableName of affectedTables) {
+                    this._queryCache.invalidateTable(tableName);
+                }
             }
             else{
                 console.log("save changes has no tracked entities");
@@ -593,6 +623,27 @@ class context {
         this._SQLEngine._execute(query);
     }
 
+    /**
+     * Get query cache statistics
+     */
+    getCacheStats() {
+        return this._queryCache.getStats();
+    }
+
+    /**
+     * Clear query cache manually
+     */
+    clearQueryCache() {
+        this._queryCache.clear();
+    }
+
+    /**
+     * Enable/disable query caching
+     */
+    setQueryCacheEnabled(enabled) {
+        this._queryCache.enabled = enabled;
+    }
+
     // __track(model){
     //     this.__trackedEntities.push(model);
     //     return model;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "An Object-relational mapping for the Master framework. Master Record connects classes to relational database tables to establish a database with almost zero-configuration ",
   "main": "MasterRecord.js",
   "bin": {