masterrecord 0.3.6 → 0.3.8

package/readme.md

@@ -785,25 +785,51 @@ MasterRecord includes a **production-grade two-level caching system** similar to
 └─────────────────────────────────────────────────────┘
 ```
 
-#### Basic Usage (Default Behavior)
+#### Basic Usage (Opt-In, Request-Scoped)
 
-Caching is **enabled by default** and requires zero configuration:
+Caching is **opt-in** and **request-scoped** like Active Record. Use `.cache()` to enable caching, and call `endRequest()` to clear:
 
 ```javascript
 const db = new AppContext();
 
-// First query hits database (cache miss)
-const user = db.User.where(u => u.id == $$, 1).single();
+// DEFAULT: No caching (always hits database)
+const user = db.User.findById(1);  // DB query
+const user2 = db.User.findById(1);  // DB query again (no cache)
 
-// Second identical query hits cache (99%+ faster)
-const user2 = db.User.where(u => u.id == $$, 1).single();
+// OPT-IN: Enable caching with .cache()
+const categories = db.Categories.cache().toList();  // DB query, cached
+const categories2 = db.Categories.cache().toList();  // Cache hit! (instant)
 
 // Update invalidates cache automatically
-user2.name = "Updated";
-db.saveChanges();  // Cache for User table cleared
+const cat = db.Categories.findById(1);
+cat.name = "Updated";
+db.saveChanges();  // Cache for Categories table cleared
 
-// Next query hits database again (cache miss)
-const user3 = db.User.where(u => u.id == $$, 1).single();
+// End request (clears cache - like Active Record)
+db.endRequest();  // Cache cleared for next request
+```
+
+**Web Application Pattern (Recommended):**
+```javascript
+// Express middleware - automatic request-scoped caching
+app.use((req, res, next) => {
+    req.db = new AppContext();
+
+    // Clear cache when response finishes (like Active Record)
+    res.on('finish', () => {
+        req.db.endRequest();  // Clears query cache
+    });
+
+    next();
+});
+
+// In your routes
+app.get('/categories', (req, res) => {
+    // Cache is fresh for this request
+    const categories = req.db.Categories.cache().toList();
+    res.json(categories);
+    // Cache auto-cleared after response
+});
 ```
 
 #### Configuration
@@ -812,29 +838,43 @@ Configure caching via environment variables:
 
 ```bash
 # Development (.env)
-QUERY_CACHE_ENABLED=true           # Enable/disable (default: true)
-QUERY_CACHE_TTL=300000             # TTL in milliseconds (default: 5 minutes)
+QUERY_CACHE_TTL=5000               # TTL in milliseconds (default: 5 seconds - request-scoped)
 QUERY_CACHE_SIZE=1000              # Max cache entries (default: 1000)
+QUERY_CACHE_ENABLED=true           # Enable/disable globally (default: true)
 
 # Production (.env)
-QUERY_CACHE_ENABLED=true
-QUERY_CACHE_TTL=300                # Redis uses seconds
+QUERY_CACHE_TTL=5                  # Redis uses seconds (5 seconds default)
 REDIS_URL=redis://localhost:6379  # Use Redis for distributed caching
 ```
 
-#### Disable Caching for Specific Queries
+**Note:**
+- Cache is **opt-in per query** using `.cache()`
+- Default TTL is **5 seconds** (request-scoped like Active Record)
+- Call `db.endRequest()` to clear cache manually (recommended in middleware)
+- Environment variables control the cache system globally
+
+#### Enable Caching for Specific Queries
 
-Use `.noCache()` for real-time data that shouldn't be cached:
+Use `.cache()` for frequently accessed, rarely changed data:
 
 ```javascript
-// Always hit database (never cached)
+// DEFAULT: Always hits database (safe)
 const liveData = db.Analytics
     .where(a => a.date == $$, today)
-    .noCache()  // Skip cache
-    .toList();
-
-// Reference data (highly cacheable)
-const categories = db.Categories.toList();  // Cached for 5 minutes
+    .toList();  // No caching (default)
+
+// OPT-IN: Cache reference data
+const categories = db.Categories.cache().toList();  // Cached for 5 minutes
+const settings = db.Settings.cache().toList();  // Cached
+const countries = db.Countries.cache().toList();  // Cached
+
+// When to use .cache():
+// ✅ Reference data (categories, settings, countries)
+// ✅ Rarely changing data (roles, permissions)
+// ✅ Expensive aggregations with stable results
+// ❌ User-specific data
+// ❌ Real-time data
+// ❌ Financial/critical data
 ```
 
 #### Manual Cache Control
@@ -901,19 +941,22 @@ class AppContext extends context {
 MasterRecord automatically invalidates cache entries when data changes:
 
 ```javascript
-// Query is cached
-const users = db.User.where(u => u.active == true).toList();
+// Query with caching enabled
+const categories = db.Categories.cache().toList();  // DB query, cached
+
+// Any modification to Categories table invalidates ALL cached Category queries
+const cat = db.Categories.findById(1);
+cat.name = "Updated";
+db.saveChanges();  // Invalidates all cached Categories queries
 
-// Any modification to User table invalidates ALL User queries
-const user = db.User.findById(1);
-user.name = "Updated";
-db.saveChanges();  // Invalidates all cached User queries
+// Next cached query hits database (fresh data)
+const categoriesAgain = db.Categories.cache().toList();  // DB query (cache cleared)
 
-// Next query hits database (fresh data)
-const usersAgain = db.User.where(u => u.active == true).toList();
+// Non-cached queries are unaffected (always fresh)
+const users = db.User.toList();  // No .cache() = always DB query
 
-// Queries for OTHER tables are unaffected
-const posts = db.Post.toList();  // Still cached
+// Queries for OTHER tables' caches are unaffected
+const settings = db.Settings.cache().toList();  // Still cached (different table)
 ```
 
 **Invalidation rules:**
@@ -937,40 +980,39 @@ Expected performance improvements:
 
 #### Best Practices
 
-**DO cache:**
+**DO use .cache():**
 ```javascript
 // Reference data (rarely changes)
-const categories = db.Categories.toList();
-const settings = db.Settings.toList();
-
-// Read-heavy data (user profiles)
-const user = db.User.findById(userId);
-
-// Expensive aggregations
-const stats = db.Orders
-    .where(o => o.status == $$, 'completed')
+const categories = db.Categories.cache().toList();
+const settings = db.Settings.cache().toList();
+const countries = db.Countries.cache().toList();
+
+// Expensive aggregations (stable results)
+const totalRevenue = db.Orders
+    .where(o => o.year == $$, 2024)
+    .cache()
     .count();
 ```
 
-**DON'T cache:**
+**DON'T use .cache():**
 ```javascript
-// Real-time data (always needs fresh results)
+// User-specific data (default is safe - no caching)
+const user = db.User.findById(userId);  // Always fresh
+
+// Real-time data (default is safe)
 const liveOrders = db.Orders
     .where(o => o.status == $$, 'pending')
-    .noCache()
-    .toList();
+    .toList();  // Always fresh
 
-// Financial transactions (critical accuracy)
+// Financial transactions (default is safe)
 const balance = db.Transactions
     .where(t => t.user_id == $$, userId)
-    .noCache()
-    .toList();
+    .toList();  // Always fresh
 
-// User-specific sensitive data (security concern)
+// User-specific sensitive data (default is safe)
 const permissions = db.UserPermissions
     .where(p => p.user_id == $$, userId)
-    .noCache()
-    .toList();
+    .toList();  // Always fresh
 ```
 
 #### Monitoring Cache Performance
@@ -988,6 +1030,74 @@ if (parseFloat(stats.hitRate) < 50) {
 }
 ```
 
+#### Request-Scoped Caching (Like Active Record)
+
+MasterRecord's caching is designed to work like Active Record - **cache within a request, clear after**:
+
+```javascript
+// Express middleware pattern (recommended)
+app.use((req, res, next) => {
+    req.db = new AppContext();
+
+    // Automatically clear cache when request ends
+    res.on('finish', () => {
+        req.db.endRequest();  // Like Active Record's cache clearing
+    });
+
+    next();
+});
+
+// In routes - cache is fresh per request
+app.get('/api/categories', (req, res) => {
+    // First call in this request - DB query
+    const categories = req.db.Categories.cache().toList();
+
+    // Second call in same request - cache hit
+    const categoriesAgain = req.db.Categories.cache().toList();
+
+    res.json(categories);
+    // After response, cache is automatically cleared
+});
+
+// Next request starts with empty cache (fresh)
+```
+
+**Why request-scoped?**
+- ✅ Like Active Record - familiar pattern
+- ✅ No stale data across requests
+- ✅ Cache only lives during request processing
+- ✅ Automatic cleanup
+
+#### Important: Shared Cache Behavior
+
+**The cache is shared across all context instances of the same class.** This ensures consistency within a request:
+
+```javascript
+const db1 = new AppContext();
+const db2 = new AppContext();
+
+// Context 1: Cache data with .cache()
+const categories1 = db1.Categories.cache().toList();  // DB query, cached
+
+// Context 2: Sees cached data
+const categories2 = db2.Categories.cache().toList();  // Cache hit!
+
+// Context 2: Updates invalidate cache for BOTH contexts
+const cat = db2.Categories.findById(1);
+cat.name = "Updated";
+db2.saveChanges();  // Invalidates shared cache
+
+// Context 1: Sees fresh data
+const categories3 = db1.Categories.cache().toList();  // Cache miss, fresh data
+console.log(categories3[0].name);  // "Updated"
+```
+
+**Why shared cache?**
+- ✅ Prevents stale data across multiple context instances
+- ✅ Ensures all parts of your application see consistent data
+- ✅ Reduces memory usage (one cache instead of many)
+- ✅ Correct behavior for single-database applications (most use cases)
+
 ### Multi-Context Applications
 
 Manage multiple databases in one application:
@@ -1065,6 +1175,7 @@ context.remove(entity)
 // Cache management
 context.getCacheStats()              // Get cache statistics
 context.clearQueryCache()            // Clear all cached queries
+context.endRequest()                 // End request and clear cache (like Active Record)
 context.setQueryCacheEnabled(bool)   // Enable/disable caching
 ```
 
@@ -1079,7 +1190,7 @@ context.setQueryCacheEnabled(bool)   // Enable/disable caching
 .skip(number)                    // Skip N records
 .take(number)                    // Limit to N records
 .include(relationship)           // Eager load
-.noCache()                       // Disable caching for this query
+.cache()                         // Enable caching for this query (opt-in)
 
 // Terminal methods (execute query)
 .toList()                        // Return array
@@ -1249,18 +1360,22 @@ console.log(`${author.name} has ${posts.length} posts`);
 
 ## Performance Tips
 
-### 1. Leverage Query Caching
+### 1. Use Query Caching Selectively
 
 ```javascript
-// ✅ GOOD: Cache reference data
-const categories = db.Categories.toList();  // Cached automatically
-
-// ✅ GOOD: Reuse queries (cache hits)
-const user1 = db.User.findById(123);  // DB query
-const user2 = db.User.findById(123);  // Cache hit (instant)
-
-// ✅ GOOD: Disable cache for real-time data
-const liveOrders = db.Orders.where(o => o.status == 'pending').noCache().toList();
+// ✅ GOOD: Cache reference data that rarely changes
+const categories = db.Categories.cache().toList();  // Opt-in caching
+const settings = db.Settings.cache().toList();
+
+// ✅ GOOD: Queries without .cache() are always fresh (safe default)
+const user1 = db.User.findById(123);  // Always DB query (no cache)
+const user2 = db.User.findById(123);  // Always DB query (no cache)
+
+// ✅ GOOD: Cache expensive queries with stable results
+const revenue2024 = db.Orders
+    .where(o => o.year == $$, 2024)
+    .cache()  // Historical data doesn't change
+    .count();
 
 // Monitor cache performance
 const stats = db.getCacheStats();

package/test/multiContextCache.test.js

@@ -0,0 +1,230 @@
+/**
+ * Test: Multi-Context Cache Sharing
+ *
+ * Verifies that cache is shared across context instances
+ * so invalidation in one context affects all contexts
+ */
+
+const context = require('../context');
+const QueryCache = require('../Cache/QueryCache');
+
+console.log("╔════════════════════════════════════════════════════════════════╗");
+console.log("║         Multi-Context Cache Sharing Test                      ║");
+console.log("╚════════════════════════════════════════════════════════════════╝\n");
+
+let passed = 0;
+let failed = 0;
+
+// Test 1: Multiple context instances share the same cache
+console.log("📝 Test 1: Multiple contexts share same cache instance");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    class TestContext extends context {
+        constructor() {
+            super();
+        }
+    }
+
+    const db1 = new TestContext();
+    const db2 = new TestContext();
+
+    const areSameInstance = db1._queryCache === db2._queryCache;
+    const isSharedCache = db1._queryCache === context._sharedQueryCache;
+
+    if(areSameInstance && isSharedCache) {
+        console.log("   ✓ Both context instances share the same cache");
+        console.log("   ✓ Cache is stored in static property");
+        passed++;
+    } else {
+        console.log(`   ✗ Contexts have separate caches (BUG!)`);
+        console.log(`   ✗ db1._queryCache === db2._queryCache: ${areSameInstance}`);
+        console.log(`   ✗ Shared cache exists: ${isSharedCache}`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 2: Cache operations in one context affect another context
+console.log("\n📝 Test 2: Cache operations are shared");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    class TestContext extends context {
+        constructor() {
+            super();
+        }
+    }
+
+    const db1 = new TestContext();
+    const db2 = new TestContext();
+
+    // Context 1: Add to cache
+    const key = db1._queryCache.generateKey('SELECT * FROM users', [], 'users');
+    db1._queryCache.set(key, [{ id: 1, name: 'John' }], 'users');
+
+    // Context 2: Should see the same cached data
+    const cached = db2._queryCache.get(key);
+
+    if(cached && cached[0].name === 'John') {
+        console.log("   ✓ Cache data visible across contexts");
+        passed++;
+    } else {
+        console.log(`   ✗ Cache data not shared across contexts`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 3: Cache invalidation in one context affects another
+console.log("\n📝 Test 3: Cache invalidation is shared");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    class TestContext extends context {
+        constructor() {
+            super();
+        }
+    }
+
+    const db1 = new TestContext();
+    const db2 = new TestContext();
+
+    // Context 1: Add multiple entries to cache
+    const key1 = db1._queryCache.generateKey('SELECT * FROM users WHERE id=1', [], 'users');
+    const key2 = db1._queryCache.generateKey('SELECT * FROM users WHERE id=2', [], 'users');
+    db1._queryCache.set(key1, { id: 1, name: 'John' }, 'users');
+    db1._queryCache.set(key2, { id: 2, name: 'Jane' }, 'users');
+
+    // Verify both are cached
+    const beforeCached1 = db1._queryCache.get(key1);
+    const beforeCached2 = db1._queryCache.get(key2);
+
+    // Context 2: Invalidate User table
+    db2._queryCache.invalidateTable('users');
+
+    // Context 1: Should see invalidation
+    const afterCached1 = db1._queryCache.get(key1);
+    const afterCached2 = db1._queryCache.get(key2);
+
+    if(beforeCached1 !== null && beforeCached2 !== null && afterCached1 === null && afterCached2 === null) {
+        console.log("   ✓ Data was cached in context 1");
+        console.log("   ✓ Invalidation in context 2 affected context 1");
+        console.log("   ✓ Cache properly shared across contexts");
+        passed++;
+    } else {
+        console.log(`   ✗ Invalidation not shared properly`);
+        console.log(`   ✗ Before: cached1=${beforeCached1 !== null}, cached2=${beforeCached2 !== null}`);
+        console.log(`   ✗ After:  cached1=${afterCached1 !== null}, cached2=${afterCached2 !== null}`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 4: Cache statistics are shared
+console.log("\n📝 Test 4: Cache statistics are shared");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    // Clear existing cache for clean test
+    context._sharedQueryCache.clear();
+
+    class TestContext extends context {
+        constructor() {
+            super();
+        }
+    }
+
+    const db1 = new TestContext();
+    const db2 = new TestContext();
+
+    // Context 1: Generate hits/misses
+    const key = db1._queryCache.generateKey('query', [], 'users');
+    db1._queryCache.set(key, 'data', 'users');
+    db1._queryCache.get(key);  // Hit
+    db1._queryCache.get('nonexistent');  // Miss
+
+    // Context 2: Should see same stats
+    const stats1 = db1.getCacheStats();
+    const stats2 = db2.getCacheStats();
+
+    if(stats1.hits === 1 && stats2.hits === 1 && stats1.misses === 1 && stats2.misses === 1) {
+        console.log("   ✓ Cache statistics shared across contexts");
+        console.log(`   ✓ Both contexts see: ${stats1.hits} hit, ${stats1.misses} miss`);
+        passed++;
+    } else {
+        console.log(`   ✗ Statistics not shared`);
+        console.log(`   ✗ db1 stats: ${JSON.stringify(stats1)}`);
+        console.log(`   ✗ db2 stats: ${JSON.stringify(stats2)}`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 5: Clear cache from one context affects all
+console.log("\n📝 Test 5: Clear cache affects all contexts");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    class TestContext extends context {
+        constructor() {
+            super();
+        }
+    }
+
+    const db1 = new TestContext();
+    const db2 = new TestContext();
+
+    // Context 1: Add data
+    const key = db1._queryCache.generateKey('query', [], 'users');
+    db1._queryCache.set(key, 'data', 'users');
+
+    // Verify cached in both
+    const before1 = db1._queryCache.get(key);
+    const before2 = db2._queryCache.get(key);
+
+    // Context 2: Clear cache
+    db2.clearQueryCache();
+
+    // Both contexts should see empty cache
+    const after1 = db1._queryCache.get(key);
+    const after2 = db2._queryCache.get(key);
+
+    if(before1 !== null && before2 !== null && after1 === null && after2 === null) {
+        console.log("   ✓ Data cached in both contexts initially");
+        console.log("   ✓ Clear from context 2 affected context 1");
+        passed++;
+    } else {
+        console.log(`   ✗ Clear not shared across contexts`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Summary
+console.log("\n╔════════════════════════════════════════════════════════════════╗");
+console.log("║                        Test Summary                            ║");
+console.log("╚════════════════════════════════════════════════════════════════╝");
+console.log(`\n   ✓ Passed: ${passed}`);
+console.log(`   ✗ Failed: ${failed}`);
+console.log(`   📊 Total:  ${passed + failed}\n`);
+
+if(failed === 0) {
+    console.log("   🎉 All tests passed!\n");
+    console.log("   ✅ Cache is properly shared across context instances");
+    console.log("   ✅ Bug fix verified: Multi-context cache invalidation works\n");
+    process.exit(0);
+} else {
+    console.log("   ❌ Some tests failed\n");
+    process.exit(1);
+}