s3db.js 13.6.0 → 14.0.2

package/src/plugins/cache/memory-cache.class.js

@@ -137,10 +137,31 @@
 import zlib from 'node:zlib';
 import os from 'node:os';
 import { Cache } from "./cache.class.js"
+import { CacheError } from '../cache.errors.js';
 
 export class MemoryCache extends Cache {
   constructor(config = {}) {
     super(config);
+    this.caseSensitive = config.caseSensitive !== undefined ? config.caseSensitive : true;
+    this.serializer = typeof config.serializer === 'function' ? config.serializer : JSON.stringify;
+
+    // Default deserializer with Date reconstruction
+    const defaultDeserializer = (str) => {
+      return JSON.parse(str, (key, value) => {
+        // Reconstruct Date objects from ISO strings
+        if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/.test(value)) {
+          return new Date(value);
+        }
+        return value;
+      });
+    };
+
+    this.deserializer = typeof config.deserializer === 'function' ? config.deserializer : defaultDeserializer;
+    this.enableStats = config.enableStats === true;
+    this.evictionPolicy = (config.evictionPolicy || 'fifo').toLowerCase();
+    if (!['lru', 'fifo'].includes(this.evictionPolicy)) {
+      this.evictionPolicy = 'fifo';
+    }
     this.cache = {};
     this.meta = {};
     this.maxSize = config.maxSize !== undefined ? config.maxSize : 1000;
@@ -148,19 +169,26 @@ export class MemoryCache extends Cache {
     // Validate that only one memory limit option is used
     if (config.maxMemoryBytes && config.maxMemoryBytes > 0 &&
         config.maxMemoryPercent && config.maxMemoryPercent > 0) {
-      throw new Error(
-        '[MemoryCache] Cannot use both maxMemoryBytes and maxMemoryPercent. ' +
-        'Choose one: maxMemoryBytes (absolute) or maxMemoryPercent (0...1 fraction).'
-      );
+      throw new CacheError('[MemoryCache] Cannot use both maxMemoryBytes and maxMemoryPercent', {
+        driver: 'memory',
+        operation: 'constructor',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Choose either maxMemoryBytes or maxMemoryPercent to limit memory usage.'
+      });
     }
 
     // Calculate maxMemoryBytes from percentage if provided
     if (config.maxMemoryPercent && config.maxMemoryPercent > 0) {
       if (config.maxMemoryPercent > 1) {
-        throw new Error(
-          '[MemoryCache] maxMemoryPercent must be between 0 and 1 (e.g., 0.1 for 10%). ' +
-          `Received: ${config.maxMemoryPercent}`
-        );
+        throw new CacheError('[MemoryCache] maxMemoryPercent must be between 0 and 1', {
+          driver: 'memory',
+          operation: 'constructor',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Provide a fraction between 0 and 1 (e.g., 0.1 for 10%).',
+          maxMemoryPercent: config.maxMemoryPercent
+        });
       }
 
       const totalMemory = os.totalmem();
@@ -188,17 +216,82 @@ export class MemoryCache extends Cache {
     // Memory tracking
     this.currentMemoryBytes = 0;
     this.evictedDueToMemory = 0;
+
+    // Monotonic counter for LRU ordering (prevents timestamp collisions)
+    this._accessCounter = 0;
+
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      deletes: 0,
+      evictions: 0
+    };
+  }
+
+  _normalizeKey(key) {
+    return this.caseSensitive ? key : key.toLowerCase();
+  }
+
+  _recordStat(type) {
+    if (!this.enableStats) return;
+    if (Object.prototype.hasOwnProperty.call(this.stats, type)) {
+      this.stats[type] += 1;
+    }
+  }
+
+  _selectEvictionCandidate() {
+    const entries = Object.entries(this.meta);
+    if (entries.length === 0) {
+      return null;
+    }
+
+    if (this.evictionPolicy === 'lru') {
+      // Use accessOrder (monotonic counter) for stable LRU ordering
+      entries.sort((a, b) => (a[1].accessOrder ?? a[1].insertOrder ?? 0) - (b[1].accessOrder ?? b[1].insertOrder ?? 0));
+    } else {
+      // Default to FIFO (order of insertion)
+      entries.sort((a, b) => (a[1].insertOrder ?? a[1].createdAt ?? a[1].ts) - (b[1].insertOrder ?? b[1].createdAt ?? b[1].ts));
+    }
+
+    return entries[0]?.[0] || null;
   }
 
   async _set(key, data) {
+    const normalizedKey = this._normalizeKey(key);
+
+    // Serialize first (needed for both compression and memory limit checks)
+    let serialized;
+    try {
+      serialized = this.serializer(data);
+    } catch (error) {
+      throw new CacheError(`Failed to serialize data for key '${key}'`, {
+        driver: 'memory',
+        operation: 'set',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Ensure the custom serializer handles the provided data type.',
+        key,
+        original: error
+      });
+    }
+
     // Prepare data for storage
-    let finalData = data;
+    let finalData = serialized;
     let compressed = false;
     let originalSize = 0;
     let compressedSize = 0;
 
-    // Calculate size first (needed for both compression and memory limit checks)
-    const serialized = JSON.stringify(data);
+    if (typeof serialized !== 'string') {
+      throw new CacheError('MemoryCache serializer must return a string', {
+        driver: 'memory',
+        operation: 'set',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Update the custom serializer to return a string output.'
+      });
+    }
+
     originalSize = Buffer.byteLength(serialized, 'utf8');
 
     // Apply compression if enabled
@@ -232,105 +325,144 @@ export class MemoryCache extends Cache {
     const itemSize = compressed ? compressedSize : originalSize;
 
     // If replacing existing key, subtract its old size from current memory
-    if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
-      const oldSize = this.meta[key]?.compressedSize || 0;
+    if (Object.prototype.hasOwnProperty.call(this.cache, normalizedKey)) {
+      const oldSize = this.meta[normalizedKey]?.compressedSize || 0;
       this.currentMemoryBytes -= oldSize;
     }
 
     // Memory-aware eviction: Remove items until we have space
     if (this.maxMemoryBytes > 0) {
+      // If item is too large to fit even in empty cache, don't cache it
+      if (itemSize > this.maxMemoryBytes) {
+        this.evictedDueToMemory++;
+        return data;
+      }
+
       while (this.currentMemoryBytes + itemSize > this.maxMemoryBytes && Object.keys(this.cache).length > 0) {
-        // Remove the oldest item
-        const oldestKey = Object.entries(this.meta)
-          .sort((a, b) => a[1].ts - b[1].ts)[0]?.[0];
-        if (oldestKey) {
-          const evictedSize = this.meta[oldestKey]?.compressedSize || 0;
-          delete this.cache[oldestKey];
-          delete this.meta[oldestKey];
-          this.currentMemoryBytes -= evictedSize;
-          this.evictedDueToMemory++;
-        } else {
-          break; // No more items to evict
-        }
+        const candidate = this._selectEvictionCandidate();
+        if (!candidate) break;
+        const evictedSize = this.meta[candidate]?.compressedSize || 0;
+        delete this.cache[candidate];
+        delete this.meta[candidate];
+        this.currentMemoryBytes -= evictedSize;
+        this.evictedDueToMemory++;
+        this._recordStat('evictions');
       }
     }
 
-    // Item count eviction (original logic)
-    if (this.maxSize > 0 && Object.keys(this.cache).length >= this.maxSize) {
-      // Remove o item mais antigo
-      const oldestKey = Object.entries(this.meta)
-        .sort((a, b) => a[1].ts - b[1].ts)[0]?.[0];
-      if (oldestKey) {
-        const evictedSize = this.meta[oldestKey]?.compressedSize || 0;
-        delete this.cache[oldestKey];
-        delete this.meta[oldestKey];
+    // Item count eviction: only evict if we're about to exceed maxSize
+    // Check length before adding the new item (so maxSize=2 allows 2 items, not 1)
+    if (this.maxSize > 0 && !Object.prototype.hasOwnProperty.call(this.cache, normalizedKey) && Object.keys(this.cache).length >= this.maxSize) {
+      const candidate = this._selectEvictionCandidate();
+      if (candidate) {
+        const evictedSize = this.meta[candidate]?.compressedSize || 0;
+        delete this.cache[candidate];
+        delete this.meta[candidate];
         this.currentMemoryBytes -= evictedSize;
+        this._recordStat('evictions');
       }
     }
 
     // Store the item
-    this.cache[key] = finalData;
-    this.meta[key] = {
-      ts: Date.now(),
+    this.cache[normalizedKey] = finalData;
+    const timestamp = Date.now();
+    const insertOrder = ++this._accessCounter;
+    this.meta[normalizedKey] = {
+      ts: timestamp,
+      createdAt: timestamp,
+      lastAccess: timestamp,
+      insertOrder,
+      accessOrder: insertOrder,
       compressed,
       originalSize,
-      compressedSize: itemSize
+      compressedSize: itemSize,
+      originalKey: key
     };
 
     // Update current memory usage
     this.currentMemoryBytes += itemSize;
 
+    this._recordStat('sets');
+
     return data;
   }
 
   async _get(key) {
-    if (!Object.prototype.hasOwnProperty.call(this.cache, key)) return null;
+    const normalizedKey = this._normalizeKey(key);
+
+    if (!Object.prototype.hasOwnProperty.call(this.cache, normalizedKey)) {
+      this._recordStat('misses');
+      return null;
+    }
 
     // Check TTL expiration
     if (this.ttl > 0) {
       const now = Date.now();
-      const meta = this.meta[key];
-      if (meta && now - meta.ts > this.ttl) {
+      const meta = this.meta[normalizedKey];
+      if (meta && now - (meta.createdAt ?? meta.ts) > this.ttl) {
         // Expired - decrement memory before deleting
         const itemSize = meta.compressedSize || 0;
         this.currentMemoryBytes -= itemSize;
-        delete this.cache[key];
-        delete this.meta[key];
+        delete this.cache[normalizedKey];
+        delete this.meta[normalizedKey];
+        this._recordStat('misses');
         return null;
       }
     }
 
-    const rawData = this.cache[key];
-    
+    const rawData = this.cache[normalizedKey];
+
     // Check if data is compressed
     if (rawData && typeof rawData === 'object' && rawData.__compressed) {
       try {
         // Decompress data
         const compressedBuffer = Buffer.from(rawData.__data, 'base64');
         const decompressed = zlib.gunzipSync(compressedBuffer).toString('utf8');
-        return JSON.parse(decompressed);
+        const value = this.deserializer(decompressed);
+        this._recordStat('hits');
+        if (this.evictionPolicy === 'lru' && this.meta[normalizedKey]) {
+          this.meta[normalizedKey].lastAccess = Date.now();
+          this.meta[normalizedKey].accessOrder = ++this._accessCounter;
+        }
+        return value;
       } catch (error) {
         console.warn(`[MemoryCache] Decompression failed for key '${key}':`, error.message);
         // If decompression fails, remove corrupted entry
-        delete this.cache[key];
-        delete this.meta[key];
+        delete this.cache[normalizedKey];
+        delete this.meta[normalizedKey];
+        this._recordStat('misses');
         return null;
       }
     }
     
-    // Return uncompressed data
-    return rawData;
+    try {
+      const value = typeof rawData === 'string' ? this.deserializer(rawData) : rawData;
+      this._recordStat('hits');
+      if (this.evictionPolicy === 'lru' && this.meta[normalizedKey]) {
+        this.meta[normalizedKey].lastAccess = Date.now();
+        this.meta[normalizedKey].accessOrder = ++this._accessCounter;
+      }
+      return value;
+    } catch (error) {
+      console.warn(`[MemoryCache] Deserialization failed for key '${key}':`, error.message);
+      delete this.cache[normalizedKey];
+      delete this.meta[normalizedKey];
+      this._recordStat('misses');
+      return null;
+    }
   }
 
   async _del(key) {
-    // Decrement memory usage
-    if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
-      const itemSize = this.meta[key]?.compressedSize || 0;
+    const normalizedKey = this._normalizeKey(key);
+
+    if (Object.prototype.hasOwnProperty.call(this.cache, normalizedKey)) {
+      const itemSize = this.meta[normalizedKey]?.compressedSize || 0;
       this.currentMemoryBytes -= itemSize;
     }
 
-    delete this.cache[key];
-    delete this.meta[key];
+    delete this.cache[normalizedKey];
+    delete this.meta[normalizedKey];
+    this._recordStat('deletes');
     return true;
   }
 
@@ -339,12 +471,17 @@ export class MemoryCache extends Cache {
       this.cache = {};
       this.meta = {};
       this.currentMemoryBytes = 0; // Reset memory counter
+      this.evictedDueToMemory = 0;
+      if (this.enableStats) {
+        this.stats = { hits: 0, misses: 0, sets: 0, deletes: 0, evictions: 0 };
+      }
       return true;
     }
     // Remove only keys that start with the prefix
     const removed = [];
+    const normalizedPrefix = this._normalizeKey(prefix);
     for (const key of Object.keys(this.cache)) {
-      if (key.startsWith(prefix)) {
+      if (key.startsWith(normalizedPrefix)) {
         removed.push(key);
         // Decrement memory usage
         const itemSize = this.meta[key]?.compressedSize || 0;
@@ -363,7 +500,24 @@ export class MemoryCache extends Cache {
   }
 
   async keys() {
-    return Object.keys(this.cache);
+    return Object.keys(this.cache).map(key => this.meta[key]?.originalKey || key);
+  }
+
+  getStats() {
+    if (!this.enableStats) {
+      return { enabled: false };
+    }
+
+    const total = this.stats.hits + this.stats.misses;
+    const hitRate = total > 0 ? this.stats.hits / total : 0;
+
+    return {
+      ...this.stats,
+      memoryUsageBytes: this.currentMemoryBytes,
+      maxMemoryBytes: this.maxMemoryBytes,
+      evictedDueToMemory: this.evictedDueToMemory,
+      hitRate
+    };
   }
 
   /**