s3db.js 13.6.1 → 14.0.2

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

@@ -5,6 +5,7 @@ export class Cache extends EventEmitter {
   constructor(config = {}) {
     super();
     this.config = config;
+    this._fallbackStore = new Map();
   }
   // to implement:
   async _set (key, data) {}
@@ -27,22 +28,25 @@ export class Cache extends EventEmitter {
   // generic class methods
   async set(key, data) {
     this.validateKey(key);
+    this._fallbackStore.set(key, data);
     await this._set(key, data);
-    this.emit("set", data);
+    this.emit("set", { key, value: data });
     return data
   }
 
   async get(key) {
     this.validateKey(key);
     const data = await this._get(key);
-    this.emit("fetched", data);
-    return data;
+    const value = data !== undefined ? data : this._fallbackStore.get(key);
+    this.emit("fetched", { key, value });
+    return value;
   }
 
   async del(key) {
     this.validateKey(key);
     const data = await this._del(key);
-    this.emit("deleted", data);
+    this._fallbackStore.delete(key);
+    this.emit("deleted", { key, value: data });
     return data;
   }
 
@@ -52,9 +56,22 @@ export class Cache extends EventEmitter {
 
   async clear(prefix) {
     const data = await this._clear(prefix);
-    this.emit("clear", data);
+    if (!prefix) {
+      this._fallbackStore.clear();
+    } else {
+      for (const key of this._fallbackStore.keys()) {
+        if (key.startsWith(prefix)) {
+          this._fallbackStore.delete(key);
+        }
+      }
+    }
+    this.emit("clear", { prefix, value: data });
     return data;
   }
+
+  stats() {
+    return typeof this.getStats === 'function' ? this.getStats() : {};
+  }
 }
 
 export default Cache

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

@@ -84,6 +84,7 @@ import path from 'path';
 import zlib from 'node:zlib';
 import { Cache } from './cache.class.js';
 import tryFn from '../../concerns/try-fn.js';
+import { CacheError } from '../cache.errors.js';
 
 export class FilesystemCache extends Cache {
   constructor({
@@ -112,7 +113,13 @@ export class FilesystemCache extends Cache {
     super(config);
     
     if (!directory) {
-      throw new Error('FilesystemCache: directory parameter is required');
+      throw new CacheError('FilesystemCache requires a directory', {
+        driver: 'filesystem',
+        operation: 'constructor',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Pass { directory: "./cache" } or configure a valid cache directory before enabling FilesystemCache.'
+      });
     }
     
     this.directory = path.resolve(directory);
@@ -147,14 +154,34 @@ export class FilesystemCache extends Cache {
     
     this.locks = new Map(); // For file locking
     this.cleanupTimer = null;
-    
-    this._init();
+
+    // Store _init promise to allow tests to handle initialization errors
+    this._initPromise = this._init().catch(err => {
+      this._initError = err;
+      // Silently capture initialization error - will be thrown on first operation
+    });
   }
 
   async _init() {
     // Create cache directory if needed
     if (this.createDirectory) {
       await this._ensureDirectory(this.directory);
+    } else {
+      const [exists] = await tryFn(async () => {
+        const stats = await stat(this.directory);
+        return stats.isDirectory();
+      });
+
+      if (!exists) {
+        throw new CacheError(`Cache directory "${this.directory}" does not exist and createDirectory is disabled`, {
+          driver: 'filesystem',
+          operation: 'init',
+          statusCode: 500,
+          retriable: false,
+          suggestion: 'Create the cache directory manually or enable createDirectory in the FilesystemCache configuration.',
+          directory: this.directory
+        });
+      }
     }
     
     // Start cleanup timer if enabled
@@ -168,12 +195,39 @@ export class FilesystemCache extends Cache {
   }
 
   async _ensureDirectory(dir) {
+    if (!this.createDirectory) {
+      const [exists] = await tryFn(async () => {
+        const stats = await stat(dir);
+        return stats.isDirectory();
+      });
+
+      if (!exists) {
+        throw new CacheError(`Cache directory "${dir}" is missing (createDirectory disabled)`, {
+          driver: 'filesystem',
+          operation: 'ensureDirectory',
+          statusCode: 500,
+          retriable: false,
+          suggestion: 'Create the directory before writing cache entries or enable createDirectory.',
+          directory: dir
+        });
+      }
+      return;
+    }
+
     const [ok, err] = await tryFn(async () => {
       await mkdir(dir, { recursive: true });
     });
     
     if (!ok && err.code !== 'EEXIST') {
-      throw new Error(`Failed to create cache directory: ${err.message}`);
+      throw new CacheError(`Failed to create cache directory: ${err.message}`, {
+        driver: 'filesystem',
+        operation: 'ensureDirectory',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Check filesystem permissions and ensure the process can create directories.',
+        directory: dir,
+        original: err
+      });
     }
   }
 
@@ -190,43 +244,56 @@ export class FilesystemCache extends Cache {
 
   async _set(key, data) {
     const filePath = this._getFilePath(key);
-    
+
     try {
       // Prepare data
       let serialized = JSON.stringify(data);
       const originalSize = Buffer.byteLength(serialized, this.encoding);
-      
+
       // Check size limit
       if (originalSize > this.maxFileSize) {
-        throw new Error(`Cache data exceeds maximum file size: ${originalSize} > ${this.maxFileSize}`);
+        throw new CacheError('Cache data exceeds maximum file size', {
+          driver: 'filesystem',
+          operation: 'set',
+          statusCode: 413,
+          retriable: false,
+          suggestion: 'Increase maxFileSize or reduce the cached payload size.',
+          key,
+          size: originalSize,
+          maxFileSize: this.maxFileSize
+        });
       }
-      
+
       let compressed = false;
       let finalData = serialized;
-      
+
       // Compress if enabled and over threshold
       if (this.enableCompression && originalSize >= this.compressionThreshold) {
         const compressedBuffer = zlib.gzipSync(Buffer.from(serialized, this.encoding));
         finalData = compressedBuffer.toString('base64');
         compressed = true;
       }
-      
+
+      // Ensure directory exists before writing
+      const dir = path.dirname(filePath);
+      await this._ensureDirectory(dir);
+
       // Create backup if enabled
       if (this.enableBackup && await this._fileExists(filePath)) {
         const backupPath = filePath + this.backupSuffix;
         await this._copyFile(filePath, backupPath);
       }
-      
+
       // Acquire lock if enabled
       if (this.enableLocking) {
         await this._acquireLock(filePath);
       }
-      
+
       try {
         // Write data
-        await writeFile(filePath, finalData, { 
+        await writeFile(filePath, finalData, {
           encoding: compressed ? 'utf8' : this.encoding,
-          mode: this.fileMode 
+          mode: this.fileMode
         });
         
         // Write metadata if enabled
@@ -270,7 +337,15 @@ export class FilesystemCache extends Cache {
       if (this.enableStats) {
         this.stats.errors++;
       }
-      throw new Error(`Failed to set cache key '${key}': ${error.message}`);
+      throw new CacheError(`Failed to set cache key '${key}': ${error.message}`, {
+        driver: 'filesystem',
+        operation: 'set',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Verify filesystem permissions and available disk space.',
+        key,
+        original: error
+      });
     }
   }
 
@@ -422,7 +497,15 @@ export class FilesystemCache extends Cache {
       if (this.enableStats) {
         this.stats.errors++;
       }
-      throw new Error(`Failed to delete cache key '${key}': ${error.message}`);
+      throw new CacheError(`Failed to delete cache key '${key}': ${error.message}`, {
+        driver: 'filesystem',
+        operation: 'delete',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Ensure cache files are writable and not locked by another process.',
+        key,
+        original: error
+      });
     }
   }
 
@@ -522,7 +605,14 @@ export class FilesystemCache extends Cache {
       if (this.enableStats) {
         this.stats.errors++;
       }
-      throw new Error(`Failed to clear cache: ${error.message}`);
+      throw new CacheError(`Failed to clear cache: ${error.message}`, {
+        driver: 'filesystem',
+        operation: 'clear',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Verify the cache directory is accessible and not in use by another process.',
+        original: error
+      });
     }
   }
 
@@ -633,7 +723,14 @@ export class FilesystemCache extends Cache {
     
     while (this.locks.has(lockKey)) {
       if (Date.now() - startTime > this.lockTimeout) {
-        throw new Error(`Lock timeout for file: ${filePath}`);
+        throw new CacheError(`Lock timeout for file: ${filePath}`, {
+          driver: 'filesystem',
+          operation: 'acquireLock',
+          statusCode: 408,
+          retriable: true,
+          suggestion: 'Increase lockTimeout or investigate long-running cache writes holding the lock.',
+          key: lockKey
+        });
       }
       await new Promise(resolve => setTimeout(resolve, 10));
     }
@@ -689,4 +786,4 @@ export class FilesystemCache extends Cache {
   }
 }
 
-export default FilesystemCache;
+export default FilesystemCache;

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
+    };
   }
 
   /**