masterrecord 0.3.5 → 0.3.6

package/test/queryCache.test.js

@@ -0,0 +1,148 @@
+const assert = require('assert');
+const QueryCache = require('../Cache/QueryCache');
+
+describe('QueryCache', () => {
+    let cache;
+
+    beforeEach(() => {
+        cache = new QueryCache({ ttl: 1000, maxSize: 3 });
+    });
+
+    test('cache miss returns null', () => {
+        const key = cache.generateKey('SELECT * FROM users', [], 'users');
+        assert.strictEqual(cache.get(key), null);
+    });
+
+    test('cache hit returns stored data', () => {
+        const key = cache.generateKey('SELECT * FROM users', [], 'users');
+        const data = [{ id: 1, name: 'John' }];
+
+        cache.set(key, data, 'users');
+        const cached = cache.get(key);
+
+        assert.deepStrictEqual(cached, data);
+    });
+
+    test('TTL expiration removes entries', (done) => {
+        const key = cache.generateKey('SELECT * FROM users', [], 'users');
+        cache.set(key, { id: 1 }, 'users');
+
+        setTimeout(() => {
+            assert.strictEqual(cache.get(key), null);
+            done();
+        }, 1100);  // Wait for TTL expiration
+    });
+
+    test('LRU eviction removes oldest entry', () => {
+        cache.set('key1', 'data1', 'table1');
+        cache.set('key2', 'data2', 'table2');
+        cache.set('key3', 'data3', 'table3');
+
+        // Access key1 to make it recently used
+        cache.get('key1');
+
+        // Add key4 - should evict key2 (least recently used)
+        cache.set('key4', 'data4', 'table4');
+
+        assert.strictEqual(cache.get('key1'), 'data1');  // Still in cache
+        assert.strictEqual(cache.get('key2'), null);     // Evicted
+        assert.strictEqual(cache.get('key3'), 'data3');  // Still in cache
+        assert.strictEqual(cache.get('key4'), 'data4');  // Newly added
+    });
+
+    test('invalidateTable removes all entries for table', () => {
+        cache.set('key1', 'data1', 'users');
+        cache.set('key2', 'data2', 'users');
+        cache.set('key3', 'data3', 'posts');
+
+        cache.invalidateTable('users');
+
+        assert.strictEqual(cache.get('key1'), null);
+        assert.strictEqual(cache.get('key2'), null);
+        assert.strictEqual(cache.get('key3'), 'data3');  // Different table
+    });
+
+    test('getStats returns accurate metrics', () => {
+        const key1 = cache.generateKey('query1', [], 'users');
+        const key2 = cache.generateKey('query2', [], 'posts');
+
+        cache.set(key1, 'data1', 'users');
+        cache.get(key1);  // Hit
+        cache.get(key2);  // Miss
+
+        const stats = cache.getStats();
+        assert.strictEqual(stats.size, 1);
+        assert.strictEqual(stats.hits, 1);
+        assert.strictEqual(stats.misses, 1);
+        assert.strictEqual(stats.hitRate, '50.00%');
+    });
+
+    test('clear removes all cache entries', () => {
+        const key1 = cache.generateKey('query1', [], 'users');
+        const key2 = cache.generateKey('query2', [], 'posts');
+
+        cache.set(key1, 'data1', 'users');
+        cache.set(key2, 'data2', 'posts');
+
+        assert.strictEqual(cache.cache.size, 2);
+
+        cache.clear();
+
+        assert.strictEqual(cache.cache.size, 0);
+        assert.strictEqual(cache.hitCount, 0);
+        assert.strictEqual(cache.missCount, 0);
+    });
+
+    test('disabled cache does not store or retrieve data', () => {
+        cache.enabled = false;
+
+        const key = cache.generateKey('SELECT * FROM users', [], 'users');
+        cache.set(key, 'data', 'users');
+
+        assert.strictEqual(cache.get(key), null);
+        assert.strictEqual(cache.cache.size, 0);
+    });
+
+    test('generateKey creates consistent keys for same query', () => {
+        const key1 = cache.generateKey('SELECT * FROM users WHERE id = ?', [1], 'users');
+        const key2 = cache.generateKey('SELECT * FROM users WHERE id = ?', [1], 'users');
+        const key3 = cache.generateKey('SELECT * FROM users WHERE id = ?', [2], 'users');
+
+        assert.strictEqual(key1, key2);  // Same query + params = same key
+        assert.notStrictEqual(key1, key3);  // Different params = different key
+    });
+
+    test('generateKey normalizes whitespace', () => {
+        const key1 = cache.generateKey('SELECT   *   FROM   users', [], 'users');
+        const key2 = cache.generateKey('SELECT * FROM users', [], 'users');
+
+        assert.strictEqual(key1, key2);  // Whitespace normalized
+    });
+
+    test('cache updates lastAccess on hit', () => {
+        const key = cache.generateKey('query', [], 'users');
+        cache.set(key, 'data', 'users');
+
+        const entry1 = cache.cache.get(key);
+        const originalAccess = entry1.lastAccess;
+
+        // Wait a bit
+        setTimeout(() => {
+            cache.get(key);
+            const entry2 = cache.cache.get(key);
+            assert(entry2.lastAccess > originalAccess);
+        }, 10);
+    });
+
+    test('cache tracks hit count per entry', () => {
+        const key = cache.generateKey('query', [], 'users');
+        cache.set(key, 'data', 'users');
+
+        cache.get(key);
+        cache.get(key);
+        cache.get(key);
+
+        const entry = cache.cache.get(key);
+        assert.strictEqual(entry.hits, 3);
+    });
+});

package/examples/jsonArrayTransformer.js

@@ -1,215 +0,0 @@
-/**
- * Real-World Example: Storing JavaScript Arrays as JSON Strings
- *
- * This example demonstrates how to use field transformers to store
- * JavaScript arrays in database string columns, solving the common
- * problem of "Type validation blocking array-to-JSON transformation"
- *
- * BEFORE (using raw SQL - not ideal):
- *   - Some fields saved through ORM
- *   - Array fields saved via raw SQL to bypass validation
- *   - Inconsistent, error-prone, loses ORM benefits
- *
- * AFTER (using transformers - production-ready):
- *   - All fields saved through ORM consistently
- *   - Arrays automatically transformed to/from JSON
- *   - Type-safe, maintainable, elegant
- */
-
-const masterrecord = require('masterrecord');
-
-// ============================================================================
-// 1. Define Entity with Transformers
-// ============================================================================
-
-class User {
-    constructor() {
-        // Regular fields - no transformation needed
-        this.id = { type: "integer", primary: true, auto: true };
-        this.name = { type: "string" };
-        this.email = { type: "string" };
-        this.role = { type: "string" };
-
-        // 🔥 ARRAY FIELDS WITH TRANSFORMERS
-        // These fields store arrays as JSON strings in the database
-        this.certified_models = {
-            type: "string",  // Database column type
-            nullable: true,
-            transform: {
-                // Transform JavaScript array → JSON string for database
-                toDatabase: (value) => {
-                    if (value === null || value === undefined) return null;
-                    if (Array.isArray(value)) return JSON.stringify(value);
-                    // Already a string (maybe from edit scenario)
-                    return value;
-                },
-
-                // Transform JSON string → JavaScript array from database
-                fromDatabase: (value) => {
-                    if (!value) return [];
-                    if (Array.isArray(value)) return value;  // Already parsed
-                    try {
-                        return JSON.parse(value);
-                    } catch {
-                        console.warn(`Failed to parse certified_models: ${value}`);
-                        return [];
-                    }
-                }
-            }
-        };
-
-        this.certified_agent_types = {
-            type: "string",
-            nullable: true,
-            transform: {
-                toDatabase: (value) => {
-                    if (value === null || value === undefined) return null;
-                    if (Array.isArray(value)) return JSON.stringify(value);
-                    return value;
-                },
-                fromDatabase: (value) => {
-                    if (!value) return [];
-                    if (Array.isArray(value)) return value;
-                    try {
-                        return JSON.parse(value);
-                    } catch {
-                        console.warn(`Failed to parse certified_agent_types: ${value}`);
-                        return [];
-                    }
-                }
-            }
-        };
-
-        // Regular numeric field
-        this.calibration_score = { type: "integer", nullable: true };
-    }
-}
-
-// ============================================================================
-// 2. Create Context
-// ============================================================================
-
-class AppContext extends masterrecord.context {
-    constructor(config) {
-        super(config);
-    }
-
-    onConfig(db) {
-        this.User = this.dbset(User, "User");
-    }
-}
-
-// ============================================================================
-// 3. Usage Example - Creating a User with Arrays
-// ============================================================================
-
-console.log("╔════════════════════════════════════════════════════════════════╗");
-console.log("║         JSON Array Transformer - Real-World Example           ║");
-console.log("╚════════════════════════════════════════════════════════════════╝\n");
-
-console.log("📝 Scenario: User certification management system");
-console.log("   - Users can be certified for multiple AI models");
-console.log("   - Users can handle multiple agent types");
-console.log("   - Arrays stored as JSON strings in database\n");
-
-// Simulated context (in real app, this would connect to actual database)
-console.log("1️⃣  Creating new user with array fields");
-console.log("──────────────────────────────────────────────────");
-
-const user = new User();
-user.name = "Alex Rich";
-user.email = "alex@example.com";
-user.role = "calibrator";
-
-// ✨ Arrays assigned naturally - NO raw SQL needed!
-user.certified_models = [1, 2, 5, 8];  // Array of model IDs
-user.certified_agent_types = [10, 20, 30];  // Array of agent type IDs
-user.calibration_score = 95;
-
-console.log(`   Name: ${user.name}`);
-console.log(`   Certified Models (array): [${user.certified_models.join(', ')}]`);
-console.log(`   Certified Agent Types (array): [${user.certified_agent_types.join(', ')}]`);
-console.log(`   Calibration Score: ${user.calibration_score}\n`);
-
-// When saved, transformers automatically convert:
-//   [1, 2, 5, 8] → "[1,2,5,8]" (stored in DB)
-console.log("2️⃣  What happens when saving");
-console.log("──────────────────────────────────────────────────");
-console.log("   User provides: [1, 2, 5, 8]");
-console.log("   ↓");
-console.log("   Transformer (toDatabase): [1, 2, 5, 8] → '[1,2,5,8]'");
-console.log("   ↓");
-console.log("   Type Validation: string '[1,2,5,8]' ✓ matches type: 'string'");
-console.log("   ↓");
-console.log("   Database Stores: '[1,2,5,8]' (as string column)\n");
-
-// Standard save - no raw SQL required!
-// context.User.add(user);
-// context.saveChanges();
-
-console.log("3️⃣  What happens when loading");
-console.log("──────────────────────────────────────────────────");
-console.log("   Database Returns: '[1,2,5,8]' (string)");
-console.log("   ↓");
-console.log("   Transformer (fromDatabase): '[1,2,5,8]' → [1, 2, 5, 8]");
-console.log("   ↓");
-console.log("   Application Receives: [1, 2, 5, 8] (JavaScript array)");
-console.log("   ↓");
-console.log("   Code: user.certified_models.includes(2) → true ✓\n");
-
-// When loaded from DB, transformers automatically convert back:
-//   "[1,2,5,8]" → [1, 2, 5, 8] (JavaScript array)
-// const users = context.User.where(u => u.id == $$, userId).toList();
-// console.log(users[0].certified_models);  // [1, 2, 5, 8]
-
-console.log("4️⃣  Updating existing user");
-console.log("──────────────────────────────────────────────────");
-console.log("   const user = context.User.where(u => u.id == $$, 14).single();");
-console.log("   user.certified_models = [1, 2, 5, 8, 12];  // Add model 12");
-console.log("   context.saveChanges();  // ✓ Works perfectly!\n");
-
-console.log("5️⃣  Benefits over raw SQL approach");
-console.log("──────────────────────────────────────────────────");
-console.log("   ✅ Consistent ORM usage (no raw SQL needed)");
-console.log("   ✅ Automatic transformation (transparent to application code)");
-console.log("   ✅ Type-safe (validation happens after transformation)");
-console.log("   ✅ Maintainable (transformation logic in one place)");
-console.log("   ✅ Testable (transformers are pure functions)");
-console.log("   ✅ Works with all ORM features (tracking, relationships, etc.)\n");
-
-console.log("6️⃣  Common Patterns");
-console.log("──────────────────────────────────────────────────");
-
-console.log("\n   Pattern A: Simple Arrays");
-console.log("   ─────────────────────────");
-console.log("   certified_models: [1, 2, 3] → '[1,2,3]'");
-
-console.log("\n   Pattern B: String Arrays");
-console.log("   ─────────────────────────");
-console.log("   tags: ['urgent', 'review'] → '[\"urgent\",\"review\"]'");
-
-console.log("\n   Pattern C: Complex Objects");
-console.log("   ─────────────────────────");
-console.log("   metadata: {key: 'value'} → '{\"key\":\"value\"}'");
-console.log("   transform: { toDatabase: JSON.stringify, fromDatabase: JSON.parse }");
-
-console.log("\n   Pattern D: Defaults for Null");
-console.log("   ─────────────────────────");
-console.log("   fromDatabase: (v) => v ? JSON.parse(v) : []");
-
-console.log("\n\n╔════════════════════════════════════════════════════════════════╗");
-console.log("║                      Summary                                   ║");
-console.log("╚════════════════════════════════════════════════════════════════╝\n");
-
-console.log("✨ PROBLEM SOLVED!");
-console.log("\nBefore: Had to use raw SQL to bypass type validation");
-console.log("        const sql = `UPDATE User SET certified_models = ? WHERE id = ?`;");
-console.log("        context.User.raw(sql, [jsonString, userId]);");
-console.log("\nAfter:  Use ORM naturally with automatic transformation");
-console.log("        user.certified_models = [1, 2, 3];");
-console.log("        context.saveChanges();");
-
-console.log("\n🎯 Use Case: This example solves the exact problem from the");
-console.log("   BookBag calibration system where arrays needed to bypass ORM.\n");
-
-console.log("📖 See readme.md 'Field Transformers' section for full documentation.\n");