masterrecord 0.3.7 → 0.3.8

package/QUERY_CACHING_GUIDE.md

@@ -0,0 +1,445 @@
+# Query Caching Guide - Like Active Record
+
+MasterRecord's query caching works like **Active Record** in Rails:
+- **Opt-in** with `.cache()`
+- **Request-scoped** (cleared after each request)
+- **Automatic invalidation** on data changes
+
+---
+
+## Quick Start
+
+### 1. Express Middleware (Recommended)
+
+```javascript
+const express = require('express');
+const AppContext = require('./models/AppContext');
+
+const app = express();
+
+// Middleware: Create context per request, auto-clear cache
+app.use((req, res, next) => {
+    req.db = new AppContext();
+
+    // Clear cache when request ends (like Active Record)
+    res.on('finish', () => {
+        req.db.endRequest();
+    });
+
+    next();
+});
+
+// Routes
+app.get('/api/categories', (req, res) => {
+    // Opt-in caching with .cache()
+    const categories = req.db.Categories.cache().toList();
+    res.json(categories);
+    // Cache auto-cleared after response
+});
+
+app.get('/api/users/:id', (req, res) => {
+    // No .cache() = always fresh (default)
+    const user = req.db.User.findById(req.params.id);
+    res.json(user);
+});
+
+app.listen(3000);
+```
+
+---
+
+## How It Works
+
+### Default Behavior (No Caching)
+
+```javascript
+// Without .cache() - always hits database
+const user1 = db.User.findById(1);  // DB query
+const user2 = db.User.findById(1);  // DB query again (no cache)
+```
+
+### Opt-In Caching
+
+```javascript
+// With .cache() - caches result
+const categories1 = db.Categories.cache().toList();  // DB query, cached
+const categories2 = db.Categories.cache().toList();  // Cache hit!
+```
+
+### Request-Scoped (Auto-Clear)
+
+```javascript
+// Request 1
+app.get('/route1', (req, res) => {
+    const cats = req.db.Categories.cache().toList();  // DB query
+    res.json(cats);
+    // Cache cleared after response
+});
+
+// Request 2 - starts with empty cache
+app.get('/route2', (req, res) => {
+    const cats = req.db.Categories.cache().toList();  // DB query again (fresh)
+    res.json(cats);
+});
+```
+
+---
+
+## When to Use `.cache()`
+
+### ✅ DO use .cache() for:
+
+```javascript
+// Reference data (rarely changes)
+const categories = db.Categories.cache().toList();
+const countries = db.Countries.cache().toList();
+const settings = db.Settings.cache().toList();
+
+// Expensive aggregations (within a request)
+const totalOrders = db.Orders
+    .where(o => o.status == $$, 'completed')
+    .cache()
+    .count();
+
+// Lookup tables
+const roles = db.Roles.cache().toList();
+const permissions = db.Permissions.cache().toList();
+```
+
+### ❌ DON'T use .cache() for:
+
+```javascript
+// User-specific data (default is safe)
+const user = db.User.findById(userId);  // No .cache()
+
+// Real-time data
+const liveOrders = db.Orders
+    .where(o => o.status == $$, 'pending')
+    .toList();  // No .cache()
+
+// Financial/sensitive data
+const transactions = db.Transactions
+    .where(t => t.user_id == $$, userId)
+    .toList();  // No .cache()
+```
+
+---
+
+## Complete Examples
+
+### Example 1: E-Commerce API
+
+```javascript
+const express = require('express');
+const AppContext = require('./models/AppContext');
+
+const app = express();
+
+// Middleware: Request-scoped caching
+app.use((req, res, next) => {
+    req.db = new AppContext();
+    res.on('finish', () => req.db.endRequest());
+    next();
+});
+
+// Categories - cache (rarely changes)
+app.get('/api/categories', (req, res) => {
+    const categories = req.db.Categories
+        .cache()  // Cache for this request
+        .toList();
+    res.json(categories);
+});
+
+// Products - cache (within request)
+app.get('/api/products', (req, res) => {
+    const products = req.db.Products
+        .where(p => p.active == true)
+        .cache()  // Cache for this request
+        .toList();
+    res.json(products);
+});
+
+// User profile - NO cache (user-specific)
+app.get('/api/profile', (req, res) => {
+    const user = req.db.User.findById(req.user.id);  // No .cache()
+    res.json(user);
+});
+
+// Cart - NO cache (real-time)
+app.get('/api/cart', (req, res) => {
+    const cart = req.db.Cart
+        .where(c => c.user_id == $$, req.user.id)
+        .toList();  // No .cache()
+    res.json(cart);
+});
+
+app.listen(3000);
+```
+
+### Example 2: Admin Dashboard
+
+```javascript
+app.get('/admin/dashboard', async (req, res) => {
+    const db = new AppContext();
+
+    // Multiple queries with caching
+    const stats = {
+        // Cache expensive aggregations
+        totalUsers: db.User.cache().count(),
+        totalOrders: db.Orders.cache().count(),
+
+        // Cache reference data
+        categories: db.Categories.cache().toList(),
+
+        // No cache for real-time data
+        recentOrders: db.Orders
+            .orderByDescending(o => o.created_at)
+            .take(10)
+            .toList()  // No .cache() - always fresh
+    };
+
+    res.render('dashboard', stats);
+
+    // Clear cache after response
+    db.endRequest();
+});
+```
+
+### Example 3: Background Job
+
+```javascript
+// Cron job - process orders
+cron.schedule('*/5 * * * *', async () => {
+    const db = new AppContext();
+
+    // Get pending orders (no cache - real-time)
+    const orders = db.Orders
+        .where(o => o.status == $$, 'pending')
+        .toList();  // No .cache()
+
+    for (const order of orders) {
+        await processOrder(order);
+        order.status = 'processed';
+    }
+
+    await db.saveChanges();  // Invalidates cache
+
+    // Clear cache after job
+    db.endRequest();
+});
+```
+
+---
+
+## Cache Invalidation
+
+Cache is automatically invalidated when you modify data:
+
+```javascript
+app.post('/api/categories', (req, res) => {
+    const db = new AppContext();
+
+    // Cache categories
+    const cats = db.Categories.cache().toList();  // DB query, cached
+
+    // Add new category
+    const newCat = db.Categories.new();
+    newCat.name = req.body.name;
+    db.saveChanges();  // Automatically invalidates Categories cache!
+
+    // Next query hits database (fresh)
+    const freshCats = db.Categories.cache().toList();  // DB query (not cached)
+
+    res.json(newCat);
+    db.endRequest();
+});
+```
+
+---
+
+## Comparison with Active Record
+
+### Active Record (Rails)
+
+```ruby
+# Rails controller
+class CategoriesController < ApplicationController
+  def index
+    # Query cache automatically enabled for request
+    @categories = Category.where(active: true).to_a
+    # Cache automatically cleared after request
+  end
+end
+```
+
+### MasterRecord (Node.js)
+
+```javascript
+// Express route
+app.get('/categories', (req, res) => {
+    // Opt-in caching with .cache()
+    const categories = req.db.Categories
+        .where(c => c.active == true)
+        .cache()  // Explicitly opt-in
+        .toList();
+    res.json(categories);
+    // Cache cleared by middleware
+});
+```
+
+**Key differences:**
+- Active Record: Cache **enabled by default** for all queries
+- MasterRecord: Cache **opt-in** with `.cache()` (safer)
+- Both: **Request-scoped** (cleared after each request)
+
+---
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# .env
+QUERY_CACHE_TTL=5000               # 5 seconds (request-scoped)
+QUERY_CACHE_SIZE=1000              # Max 1000 cached queries
+QUERY_CACHE_ENABLED=true           # Enable caching
+```
+
+### Custom TTL per Query
+
+```javascript
+// Use default TTL (5 seconds)
+const cats = db.Categories.cache().toList();
+
+// For longer-lived cache, increase TTL in config:
+// QUERY_CACHE_TTL=60000  // 1 minute
+```
+
+---
+
+## Testing
+
+### Unit Tests
+
+```javascript
+const AppContext = require('../models/AppContext');
+
+describe('Category API', () => {
+    let db;
+
+    beforeEach(() => {
+        db = new AppContext();
+    });
+
+    afterEach(() => {
+        db.endRequest();  // Clear cache after each test
+    });
+
+    it('caches category queries', () => {
+        const cats1 = db.Categories.cache().toList();
+        const cats2 = db.Categories.cache().toList();
+
+        const stats = db.getCacheStats();
+        expect(stats.hits).toBe(1);  // Second query hit cache
+    });
+
+    it('does not cache without .cache()', () => {
+        const cats1 = db.Categories.toList();  // No .cache()
+        const cats2 = db.Categories.toList();  // No .cache()
+
+        const stats = db.getCacheStats();
+        expect(stats.size).toBe(0);  // Nothing cached
+    });
+});
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+- Use middleware to auto-clear cache per request
+- Cache reference data (categories, settings, countries)
+- Cache within a request for duplicate queries
+- Call `db.endRequest()` at end of request
+- Monitor cache stats in development
+
+### ❌ DON'T:
+- Cache user-specific data
+- Cache real-time data
+- Cache financial/sensitive data
+- Forget to call `endRequest()` in long-running processes
+- Use `.cache()` on frequently updated tables
+
+---
+
+## Troubleshooting
+
+### Cache not clearing between requests
+
+```javascript
+// ❌ BAD: No cache clearing
+app.use((req, res, next) => {
+    req.db = new AppContext();
+    next();
+});
+
+// ✅ GOOD: Auto-clear cache
+app.use((req, res, next) => {
+    req.db = new AppContext();
+    res.on('finish', () => req.db.endRequest());  // Clear cache
+    next();
+});
+```
+
+### Stale data across requests
+
+```javascript
+// Check TTL - should be short (5 seconds default)
+console.log(process.env.QUERY_CACHE_TTL);  // Should be 5000
+
+// Make sure endRequest() is called
+db.endRequest();  // Clears cache
+```
+
+### Low cache hit rate
+
+```javascript
+// Check if queries are actually using .cache()
+const stats = db.getCacheStats();
+console.log(stats);
+// {
+//   size: 0,      // No cached queries?
+//   hits: 0,      // No cache hits?
+//   misses: 10    // All misses?
+// }
+
+// Make sure to use .cache()
+const cats = db.Categories.cache().toList();  // Must have .cache()!
+```
+
+---
+
+## Summary
+
+**MasterRecord caching = Active Record style:**
+
+1. **Opt-in** with `.cache()` (safer than default-on)
+2. **Request-scoped** with `endRequest()` (auto-clear)
+3. **Automatic invalidation** on `saveChanges()`
+
+**Use it like this:**
+```javascript
+// Setup (once)
+app.use((req, res, next) => {
+    req.db = new AppContext();
+    res.on('finish', () => req.db.endRequest());
+    next();
+});
+
+// Use (in routes)
+const categories = req.db.Categories.cache().toList();  // Cached
+const user = req.db.User.findById(id);  // Not cached (default)
+```
+
+**It just works!** ✅

package/QueryLanguage/queryMethods.js

@@ -10,7 +10,7 @@ class queryMethods{
         this.__entity = entity;
         this.__context = context;
         this.__queryObject = new queryScript();
-        this.__useCache = true;  // Enable caching by default
+        this.__useCache = false;  // Disable caching by default (opt-in with .cache())
     }
 
     // build a single entity
@@ -89,11 +89,19 @@ class queryMethods{
     }
 
     /**
-     * Disable query caching for this query
-     * Use for queries that should always hit database
+     * Enable query result caching for this query
+     * Use for frequently accessed, rarely changed data (categories, settings, etc.)
+     * Cache is shared across all context instances and invalidated on saveChanges()
+     *
+     * @example
+     * // Cache this query result
+     * const categories = db.Categories.cache().toList();
+     *
+     * // Without .cache(), always hits database (default)
+     * const user = db.User.findById(1);
      */
-    noCache() {
-        this.__useCache = false;
+    cache() {
+        this.__useCache = true;
         return this;
     }
 

package/context.js

@@ -45,7 +45,7 @@ class context {
         // 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
+                ttl: process.env.QUERY_CACHE_TTL || 5000,  // 5 seconds default (request-scoped)
                 maxSize: process.env.QUERY_CACHE_SIZE || 1000,
                 enabled: process.env.QUERY_CACHE_ENABLED !== 'false'
             });
@@ -644,6 +644,24 @@ class context {
         this._queryCache.enabled = enabled;
     }
 
+    /**
+     * End request and clear query cache
+     * Call this at the end of each request (like Active Record)
+     *
+     * @example
+     * // In Express middleware
+     * app.use((req, res, next) => {
+     *     req.db = new AppContext();
+     *     res.on('finish', () => {
+     *         req.db.endRequest();  // Clears cache
+     *     });
+     *     next();
+     * });
+     */
+    endRequest() {
+        this.clearQueryCache();
+    }
+
     // __track(model){
     //     this.__trackedEntities.push(model);
     //     return model;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "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": {

package/readme.md

@@ -785,29 +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. The cache is **shared across all context instances** to ensure consistency:
+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
+```
 
-// Cache is shared across all context instances
-const db2 = new AppContext();
-const user4 = db2.User.findById(1);  // Also uses shared cache
+**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
@@ -816,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();
+    .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
 
-// Reference data (highly cacheable)
-const categories = db.Categories.toList();  // Cached for 5 minutes
+// 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
@@ -905,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:**
@@ -941,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
@@ -992,27 +1030,66 @@ 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:
+**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
-const user1 = db1.User.findById(1);  // DB query, cached
+// Context 1: Cache data with .cache()
+const categories1 = db1.Categories.cache().toList();  // DB query, cached
 
 // Context 2: Sees cached data
-const user2 = db2.User.findById(1);  // Cache hit!
+const categories2 = db2.Categories.cache().toList();  // Cache hit!
 
 // Context 2: Updates invalidate cache for BOTH contexts
-user2.name = "Updated";
+const cat = db2.Categories.findById(1);
+cat.name = "Updated";
 db2.saveChanges();  // Invalidates shared cache
 
 // Context 1: Sees fresh data
-const user3 = db1.User.findById(1);  // Cache miss, fresh data
-console.log(user3.name);  // "Updated"
+const categories3 = db1.Categories.cache().toList();  // Cache miss, fresh data
+console.log(categories3[0].name);  // "Updated"
 ```
 
 **Why shared cache?**
@@ -1098,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
 ```
 
@@ -1112,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
@@ -1282,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/optInCache.test.js

@@ -0,0 +1,221 @@
+/**
+ * Test: Opt-In Caching Behavior
+ *
+ * Verifies that caching is disabled by default and only enabled with .cache()
+ */
+
+const QueryCache = require('../Cache/QueryCache');
+
+console.log("╔════════════════════════════════════════════════════════════════╗");
+console.log("║              Opt-In Caching Test                               ║");
+console.log("╚════════════════════════════════════════════════════════════════╝\n");
+
+let passed = 0;
+let failed = 0;
+
+// Simulate queryMethods with opt-in caching
+class SimulatedQuery {
+    constructor(context) {
+        this._context = context;
+        this.__useCache = false;  // Default: caching disabled
+        this._queryString = 'SELECT * FROM test';
+        this._tableName = 'Test';
+    }
+
+    // Enable caching for this query
+    cache() {
+        this.__useCache = true;
+        return this;
+    }
+
+    // Execute query
+    toList() {
+        const cacheKey = this._context.cache.generateKey(this._queryString, [], this._tableName);
+
+        // Check cache if enabled
+        if (this.__useCache) {
+            const cached = this._context.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+
+        // Simulate DB query
+        const result = [{ id: 1, name: 'Test' }];
+
+        // Store in cache if enabled
+        if (this.__useCache) {
+            this._context.cache.set(cacheKey, result, this._tableName);
+        }
+
+        return result;
+    }
+}
+
+class SimulatedContext {
+    constructor() {
+        this.cache = new QueryCache({ ttl: 60000, maxSize: 100 });
+    }
+
+    createQuery() {
+        return new SimulatedQuery(this);
+    }
+}
+
+// Test 1: Default behavior - no caching
+console.log("📝 Test 1: Queries without .cache() are NOT cached");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    const ctx = new SimulatedContext();
+    ctx.cache.clear();
+
+    // Execute same query twice WITHOUT .cache()
+    const result1 = ctx.createQuery().toList();
+    const result2 = ctx.createQuery().toList();
+
+    const stats = ctx.cache.getStats();
+
+    if(stats.size === 0 && stats.hits === 0) {
+        console.log("   ✓ Queries without .cache() do not store results");
+        console.log("   ✓ No cache hits recorded");
+        console.log("   ✓ Cache size remains 0");
+        passed++;
+    } else {
+        console.log(`   ✗ Queries were cached without .cache() call`);
+        console.log(`   ✗ Cache size: ${stats.size}, hits: ${stats.hits}`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 2: Opt-in with .cache() enables caching
+console.log("\n📝 Test 2: Queries with .cache() ARE cached");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    const ctx = new SimulatedContext();
+    ctx.cache.clear();
+
+    // Execute same query twice WITH .cache()
+    const result1 = ctx.createQuery().cache().toList();
+    const result2 = ctx.createQuery().cache().toList();
+
+    const stats = ctx.cache.getStats();
+
+    if(stats.size === 1 && stats.hits === 1 && stats.misses === 1) {
+        console.log("   ✓ First query with .cache() stored result (miss)");
+        console.log("   ✓ Second query with .cache() hit cache (hit)");
+        console.log(`   ✓ Cache stats: ${stats.hits} hit, ${stats.misses} miss`);
+        passed++;
+    } else {
+        console.log(`   ✗ Caching with .cache() didn't work properly`);
+        console.log(`   ✗ Expected: 1 hit, 1 miss. Got: ${stats.hits} hits, ${stats.misses} misses`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 3: Mixed queries - cached and non-cached
+console.log("\n📝 Test 3: Mixed cached and non-cached queries");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    const ctx = new SimulatedContext();
+    ctx.cache.clear();
+
+    // Non-cached query (no .cache())
+    ctx.createQuery().toList();
+    ctx.createQuery().toList();
+
+    // Cached query (with .cache())
+    ctx.createQuery().cache().toList();
+    ctx.createQuery().cache().toList();
+
+    const stats = ctx.cache.getStats();
+
+    if(stats.size === 1 && stats.hits === 1 && stats.misses === 1) {
+        console.log("   ✓ Non-cached queries didn't affect cache");
+        console.log("   ✓ Cached queries stored and retrieved correctly");
+        console.log(`   ✓ Cache contains only .cache() queries: ${stats.size} entry`);
+        passed++;
+    } else {
+        console.log(`   ✗ Mixed query handling incorrect`);
+        console.log(`   ✗ Cache size: ${stats.size}, expected: 1`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 4: Default __useCache flag is false
+console.log("\n📝 Test 4: Default __useCache flag is false");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    const ctx = new SimulatedContext();
+    const query = ctx.createQuery();
+
+    if(query.__useCache === false) {
+        console.log("   ✓ Default __useCache is false");
+        console.log("   ✓ Caching is opt-in by default");
+        passed++;
+    } else {
+        console.log(`   ✗ Default __useCache is ${query.__useCache}, expected false`);
+        failed++;
+    }
+} catch(err) {
+    console.log(`   ✗ Error: ${err.message}`);
+    failed++;
+}
+
+// Test 5: .cache() sets __useCache to true
+console.log("\n📝 Test 5: .cache() enables caching flag");
+console.log("──────────────────────────────────────────────────");
+
+try {
+    const ctx = new SimulatedContext();
+    const query = ctx.createQuery();
+
+    const beforeCache = query.__useCache;
+    query.cache();
+    const afterCache = query.__useCache;
+
+    if(beforeCache === false && afterCache === true) {
+        console.log("   ✓ __useCache starts as false");
+        console.log("   ✓ .cache() sets __useCache to true");
+        console.log("   ✓ Caching is explicitly enabled");
+        passed++;
+    } else {
+        console.log(`   ✗ Flag transition incorrect`);
+        console.log(`   ✗ Before: ${beforeCache}, After: ${afterCache}`);
+        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("   ✅ Opt-in caching behavior verified");
+    console.log("   ✅ Default is safe (no caching)");
+    console.log("   ✅ .cache() explicitly enables caching\n");
+    process.exit(0);
+} else {
+    console.log("   ❌ Some tests failed\n");
+    process.exit(1);
+}