s3db.js 11.2.2 → 11.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "11.2.2",
+  "version": "11.2.3",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",

package/src/database.class.js

@@ -35,6 +35,7 @@ export class Database extends EventEmitter {
     this.passphrase = options.passphrase || "secret";
     this.versioningEnabled = options.versioningEnabled || false;
     this.persistHooks = options.persistHooks || false; // New configuration for hook persistence
+    this.strictValidation = options.strictValidation !== false; // Enable strict validation by default
 
     // Initialize hooks system
     this._initHooks();
@@ -199,6 +200,7 @@ export class Database extends EventEmitter {
           asyncEvents: versionData.asyncEvents !== undefined ? versionData.asyncEvents : true,
           hooks: this.persistHooks ? this._deserializeHooks(versionData.hooks || {}) : (versionData.hooks || {}),
           versioningEnabled: this.versioningEnabled,
+          strictValidation: this.strictValidation,
           map: versionData.map,
           idGenerator: restoredIdGenerator,
           idSize: restoredIdSize
@@ -999,6 +1001,7 @@ export class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== undefined ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
+      strictValidation: this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,

package/src/errors.js

@@ -1,12 +1,12 @@
 export class BaseError extends Error {
-  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, suggestion, ...rest }) {
+  constructor({ verbose, bucket, key, message, code, statusCode, requestId, awsMessage, original, commandName, commandInput, metadata, suggestion, description, ...rest }) {
     if (verbose) message = message + `\n\nVerbose:\n\n${JSON.stringify(rest, null, 2)}`;
     super(message);
 
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, this.constructor);
-    } else { 
-      this.stack = (new Error(message)).stack; 
+    } else {
+      this.stack = (new Error(message)).stack;
     }
 
     super.name = this.constructor.name;
@@ -23,6 +23,7 @@ export class BaseError extends Error {
     this.commandInput = commandInput;
     this.metadata = metadata;
     this.suggestion = suggestion;
+    this.description = description;
     this.data = { bucket, key, ...rest, verbose, message };
   }
 
@@ -41,6 +42,7 @@ export class BaseError extends Error {
       commandInput: this.commandInput,
       metadata: this.metadata,
       suggestion: this.suggestion,
+      description: this.description,
       data: this.data,
       original: this.original,
       stack: this.stack,
@@ -264,6 +266,115 @@ export class ResourceError extends S3dbError {
 
 export class PartitionError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || 'Check partition definition, fields, and input values.' });
+    // Generate description if not provided
+    let description = details.description;
+    if (!description && details.resourceName && details.partitionName && details.fieldName) {
+      const { resourceName, partitionName, fieldName, availableFields = [] } = details;
+      description = `
+Partition Field Validation Error
+
+Resource: ${resourceName}
+Partition: ${partitionName}
+Missing Field: ${fieldName}
+
+Available fields in schema:
+${availableFields.map(f => `  • ${f}`).join('\n') || '  (no fields defined)'}
+
+Possible causes:
+1. Field was removed from schema but partition still references it
+2. Typo in partition field name
+3. Nested field path is incorrect (use dot notation like 'utm.source')
+
+Solution:
+${details.strictValidation === false
+  ? '  • Update partition definition to use existing fields'
+  : `  • Add missing field to schema, OR
+  • Update partition definition to use existing fields, OR
+  • Use strictValidation: false to skip this check during testing`}
+
+Docs: https://docs.s3db.js.org/resources/partitions#validation
+`.trim();
+    }
+
+    super(message, {
+      ...details,
+      description,
+      suggestion: details.suggestion || 'Check partition definition, fields, and input values.'
+    });
+  }
+}
+
+export class AnalyticsNotEnabledError extends S3dbError {
+  constructor(details = {}) {
+    const {
+      pluginName = 'EventualConsistency',
+      resourceName = 'unknown',
+      field = 'unknown',
+      configuredResources = [],
+      registeredResources = [],
+      pluginInitialized = false,
+      ...rest
+    } = details;
+
+    const message = `Analytics not enabled for ${resourceName}.${field}`;
+
+    // Generate diagnostic description
+    const description = `
+Analytics Not Enabled
+
+Plugin: ${pluginName}
+Resource: ${resourceName}
+Field: ${field}
+
+Diagnostics:
+  • Plugin initialized: ${pluginInitialized ? '✓ Yes' : '✗ No'}
+  • Analytics resources created: ${registeredResources.length}/${configuredResources.length}
+${configuredResources.map(r => {
+  const exists = registeredResources.includes(r);
+  return `    ${exists ? '✓' : '✗'} ${r}${!exists ? ' (missing)' : ''}`;
+}).join('\n')}
+
+Possible causes:
+1. Resource not created yet - Analytics resources are created when db.createResource() is called
+2. Resource created before plugin initialization - Plugin must be initialized before resources
+3. Field not configured in analytics.resources config
+
+Correct initialization order:
+  1. Create database: const db = new Database({ ... })
+  2. Install plugins: await db.connect() (triggers plugin.install())
+  3. Create resources: await db.createResource({ name: '${resourceName}', ... })
+  4. Analytics resources are auto-created by plugin
+
+Example fix:
+  const db = new Database({
+    bucket: 'my-bucket',
+    plugins: [new EventualConsistencyPlugin({
+      resources: {
+        '${resourceName}': {
+          fields: {
+            '${field}': { type: 'counter', analytics: true }
+          }
+        }
+      }
+    })]
+  });
+
+  await db.connect();  // Plugin initialized here
+  await db.createResource({ name: '${resourceName}', ... });  // Analytics resource created here
+
+Docs: https://docs.s3db.js.org/plugins/eventual-consistency#troubleshooting
+`.trim();
+
+    super(message, {
+      ...rest,
+      pluginName,
+      resourceName,
+      field,
+      configuredResources,
+      registeredResources,
+      pluginInitialized,
+      description,
+      suggestion: 'Ensure resources are created after plugin initialization. Check plugin configuration and resource creation order.'
+    });
   }
 }

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

@@ -1,12 +1,14 @@
 /**
  * Memory Cache Configuration Documentation
- * 
+ *
  * This cache implementation stores data in memory using a Map-like structure.
  * It provides fast access to frequently used data but is limited by available RAM
  * and data is lost when the process restarts.
- * 
+ *
  * @typedef {Object} MemoryCacheConfig
  * @property {number} [maxSize=1000] - Maximum number of items to store in cache
+ * @property {number} [maxMemoryBytes=0] - Maximum memory usage in bytes (0 = unlimited). When set, cache will evict items to stay under this limit.
+ * @property {number} [maxMemoryPercent=0] - Maximum memory usage as decimal fraction of total system memory (0 = unlimited, 0.1 = 10%, 0.5 = 50%, 1.0 = 100%). Takes precedence over maxMemoryBytes if both are set.
  * @property {number} [ttl=300000] - Time to live in milliseconds (5 minutes default)
  * @property {boolean} [enableStats=false] - Whether to track cache statistics (hits, misses, etc.)
  * @property {string} [evictionPolicy='lru'] - Cache eviction policy: 'lru' (Least Recently Used) or 'fifo' (First In First Out)
@@ -70,9 +72,54 @@
  *   maxSize: 1000,
  *   ttl: 300000 // 5 minutes
  * }
- * 
+ *
+ * @example
+ * // Memory-limited configuration (prevents memory exhaustion)
+ * {
+ *   maxMemoryBytes: 100 * 1024 * 1024, // 100MB hard limit
+ *   ttl: 600000, // 10 minutes
+ *   enableCompression: true, // Reduce memory usage
+ *   compressionThreshold: 1024 // Compress items > 1KB
+ * }
+ *
+ * @example
+ * // Production configuration with memory monitoring (absolute bytes)
+ * {
+ *   maxSize: 5000, // Limit number of items
+ *   maxMemoryBytes: 512 * 1024 * 1024, // 512MB memory limit
+ *   ttl: 1800000, // 30 minutes
+ *   enableCompression: true,
+ *   compressionThreshold: 512
+ * }
+ *
+ * // Check memory usage
+ * const stats = cache.getMemoryStats();
+ * console.log(`Memory: ${stats.memoryUsage.current} / ${stats.memoryUsage.max}`);
+ * console.log(`Usage: ${stats.memoryUsagePercent}%`);
+ * console.log(`Evicted due to memory: ${stats.evictedDueToMemory}`);
+ *
+ * @example
+ * // Production configuration with percentage of system memory
+ * {
+ *   maxMemoryPercent: 0.1, // Use max 10% of system memory (0.1 = 10%)
+ *   ttl: 1800000, // 30 minutes
+ *   enableCompression: true
+ * }
+ *
+ * // On a 16GB system, this sets maxMemoryBytes to ~1.6GB
+ * // On a 32GB system, this sets maxMemoryBytes to ~3.2GB
+ *
+ * // Check system memory stats
+ * const stats = cache.getMemoryStats();
+ * console.log(`System Memory: ${stats.systemMemory.total}`);
+ * console.log(`Cache using: ${stats.systemMemory.cachePercent} of system memory`);
+ * console.log(`Max allowed: ${(stats.maxMemoryPercent * 100).toFixed(1)}%`);
+ *
  * @notes
- * - Memory usage is limited by available RAM and maxSize setting
+ * - Memory usage is limited by available RAM, maxSize setting, and optionally maxMemoryBytes or maxMemoryPercent
+ * - maxMemoryPercent takes precedence over maxMemoryBytes if both are set
+ * - maxMemoryPercent is calculated based on total system memory at cache creation time
+ * - Useful for containerized/cloud environments where system memory varies
  * - TTL is checked on access, not automatically in background
  * - LRU eviction removes least recently accessed items when cache is full
  * - FIFO eviction removes oldest items when cache is full
@@ -83,8 +130,12 @@
  * - Cleanup interval helps prevent memory leaks from expired items
  * - Tags are useful for cache invalidation and monitoring
  * - Case sensitivity affects key matching and storage efficiency
+ * - maxMemoryBytes prevents memory exhaustion by enforcing byte-level limits
+ * - Memory tracking includes serialized data size (compressed or uncompressed)
+ * - getMemoryStats() includes systemMemory info for monitoring
  */
 import zlib from 'node:zlib';
+import os from 'node:os';
 import { Cache } from "./cache.class.js"
 
 export class MemoryCache extends Cache {
@@ -93,12 +144,39 @@ export class MemoryCache extends Cache {
     this.cache = {};
     this.meta = {};
     this.maxSize = config.maxSize !== undefined ? config.maxSize : 1000;
+
+    // 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).'
+      );
+    }
+
+    // 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}`
+        );
+      }
+
+      const totalMemory = os.totalmem();
+      this.maxMemoryBytes = Math.floor(totalMemory * config.maxMemoryPercent);
+      this.maxMemoryPercent = config.maxMemoryPercent;
+    } else {
+      this.maxMemoryBytes = config.maxMemoryBytes !== undefined ? config.maxMemoryBytes : 0; // 0 = unlimited
+      this.maxMemoryPercent = 0;
+    }
+
     this.ttl = config.ttl !== undefined ? config.ttl : 300000;
-    
+
     // Compression configuration
     this.enableCompression = config.enableCompression !== undefined ? config.enableCompression : false;
     this.compressionThreshold = config.compressionThreshold !== undefined ? config.compressionThreshold : 1024;
-    
+
     // Stats for compression
     this.compressionStats = {
       totalCompressed: 0,
@@ -106,33 +184,26 @@ export class MemoryCache extends Cache {
       totalCompressedSize: 0,
       compressionRatio: 0
     };
+
+    // Memory tracking
+    this.currentMemoryBytes = 0;
+    this.evictedDueToMemory = 0;
   }
 
   async _set(key, data) {
-    // Limpar se exceder maxSize
-    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) {
-        delete this.cache[oldestKey];
-        delete this.meta[oldestKey];
-      }
-    }
-    
     // Prepare data for storage
     let finalData = data;
     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);
+    originalSize = Buffer.byteLength(serialized, 'utf8');
+
     // Apply compression if enabled
     if (this.enableCompression) {
       try {
-        // Serialize data to measure size
-        const serialized = JSON.stringify(data);
-        originalSize = Buffer.byteLength(serialized, 'utf8');
-        
         // Compress only if over threshold
         if (originalSize >= this.compressionThreshold) {
           const compressedBuffer = zlib.gzipSync(Buffer.from(serialized, 'utf8'));
@@ -143,12 +214,12 @@ export class MemoryCache extends Cache {
           };
           compressedSize = Buffer.byteLength(finalData.__data, 'utf8');
           compressed = true;
-          
+
           // Update compression stats
           this.compressionStats.totalCompressed++;
           this.compressionStats.totalOriginalSize += originalSize;
           this.compressionStats.totalCompressedSize += compressedSize;
-          this.compressionStats.compressionRatio = 
+          this.compressionStats.compressionRatio =
             (this.compressionStats.totalCompressedSize / this.compressionStats.totalOriginalSize).toFixed(2);
         }
       } catch (error) {
@@ -156,33 +227,79 @@ export class MemoryCache extends Cache {
         console.warn(`[MemoryCache] Compression failed for key '${key}':`, error.message);
       }
     }
-    
+
+    // Calculate actual storage size (compressed or original)
+    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;
+      this.currentMemoryBytes -= oldSize;
+    }
+
+    // Memory-aware eviction: Remove items until we have space
+    if (this.maxMemoryBytes > 0) {
+      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
+        }
+      }
+    }
+
+    // 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];
+        this.currentMemoryBytes -= evictedSize;
+      }
+    }
+
+    // Store the item
     this.cache[key] = finalData;
-    this.meta[key] = { 
+    this.meta[key] = {
       ts: Date.now(),
       compressed,
       originalSize,
-      compressedSize: compressed ? compressedSize : originalSize
+      compressedSize: itemSize
     };
-    
+
+    // Update current memory usage
+    this.currentMemoryBytes += itemSize;
+
     return data;
   }
 
   async _get(key) {
     if (!Object.prototype.hasOwnProperty.call(this.cache, key)) 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 * 1000) {
-        // Expirado
+      if (meta && now - 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];
         return null;
       }
     }
-    
+
     const rawData = this.cache[key];
     
     // Check if data is compressed
@@ -206,6 +323,12 @@ export class MemoryCache extends Cache {
   }
 
   async _del(key) {
+    // Decrement memory usage
+    if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
+      const itemSize = this.meta[key]?.compressedSize || 0;
+      this.currentMemoryBytes -= itemSize;
+    }
+
     delete this.cache[key];
     delete this.meta[key];
     return true;
@@ -215,6 +338,7 @@ export class MemoryCache extends Cache {
     if (!prefix) {
       this.cache = {};
       this.meta = {};
+      this.currentMemoryBytes = 0; // Reset memory counter
       return true;
     }
     // Remove only keys that start with the prefix
@@ -222,6 +346,9 @@ export class MemoryCache extends Cache {
     for (const key of Object.keys(this.cache)) {
       if (key.startsWith(prefix)) {
         removed.push(key);
+        // Decrement memory usage
+        const itemSize = this.meta[key]?.compressedSize || 0;
+        this.currentMemoryBytes -= itemSize;
         delete this.cache[key];
         delete this.meta[key];
       }
@@ -248,7 +375,7 @@ export class MemoryCache extends Cache {
       return { enabled: false, message: 'Compression is disabled' };
     }
 
-    const spaceSavings = this.compressionStats.totalOriginalSize > 0 
+    const spaceSavings = this.compressionStats.totalOriginalSize > 0
       ? ((this.compressionStats.totalOriginalSize - this.compressionStats.totalCompressedSize) / this.compressionStats.totalOriginalSize * 100).toFixed(2)
       : 0;
 
@@ -268,6 +395,62 @@ export class MemoryCache extends Cache {
       }
     };
   }
+
+  /**
+   * Get memory usage statistics
+   * @returns {Object} Memory stats including current usage, limits, and eviction counts
+   */
+  getMemoryStats() {
+    const totalItems = Object.keys(this.cache).length;
+    const memoryUsagePercent = this.maxMemoryBytes > 0
+      ? ((this.currentMemoryBytes / this.maxMemoryBytes) * 100).toFixed(2)
+      : 0;
+
+    const systemMemory = {
+      total: os.totalmem(),
+      free: os.freemem(),
+      used: os.totalmem() - os.freemem()
+    };
+
+    const cachePercentOfTotal = systemMemory.total > 0
+      ? ((this.currentMemoryBytes / systemMemory.total) * 100).toFixed(2)
+      : 0;
+
+    return {
+      currentMemoryBytes: this.currentMemoryBytes,
+      maxMemoryBytes: this.maxMemoryBytes,
+      maxMemoryPercent: this.maxMemoryPercent,
+      memoryUsagePercent: parseFloat(memoryUsagePercent),
+      cachePercentOfSystemMemory: parseFloat(cachePercentOfTotal),
+      totalItems,
+      maxSize: this.maxSize,
+      evictedDueToMemory: this.evictedDueToMemory,
+      averageItemSize: totalItems > 0 ? Math.round(this.currentMemoryBytes / totalItems) : 0,
+      memoryUsage: {
+        current: this._formatBytes(this.currentMemoryBytes),
+        max: this.maxMemoryBytes > 0 ? this._formatBytes(this.maxMemoryBytes) : 'unlimited',
+        available: this.maxMemoryBytes > 0 ? this._formatBytes(this.maxMemoryBytes - this.currentMemoryBytes) : 'unlimited'
+      },
+      systemMemory: {
+        total: this._formatBytes(systemMemory.total),
+        free: this._formatBytes(systemMemory.free),
+        used: this._formatBytes(systemMemory.used),
+        cachePercent: `${cachePercentOfTotal}%`
+      }
+    };
+  }
+
+  /**
+   * Format bytes to human-readable format
+   * @private
+   */
+  _formatBytes(bytes) {
+    if (bytes === 0) return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+  }
 }
 
 export default MemoryCache

package/src/plugins/cache.plugin.js

@@ -9,6 +9,88 @@ import { FilesystemCache } from "./cache/filesystem-cache.class.js";
 import { PartitionAwareFilesystemCache } from "./cache/partition-aware-filesystem-cache.class.js";
 import tryFn from "../concerns/try-fn.js";
 
+/**
+ * Cache Plugin Configuration
+ *
+ * Provides caching layer for S3DB resources with multiple backend options.
+ * Automatically caches read operations and invalidates on writes.
+ *
+ * @typedef {Object} CachePluginOptions
+ * @property {string} [driver='s3'] - Cache driver: 'memory', 'filesystem', 's3', or custom driver instance
+ * @property {number} [ttl] - Time to live in milliseconds for cached items (shortcut for config.ttl)
+ * @property {number} [maxSize] - Maximum number of items to cache (shortcut for config.maxSize)
+ * @property {number} [maxMemoryBytes] - (MemoryCache only) Maximum memory in bytes (shortcut for config.maxMemoryBytes). Cannot be used with maxMemoryPercent.
+ * @property {number} [maxMemoryPercent] - (MemoryCache only) Maximum memory as fraction 0...1 (shortcut for config.maxMemoryPercent). Cannot be used with maxMemoryBytes.
+ *
+ * @property {Array<string>} [include] - Only cache these resource names (null = cache all)
+ * @property {Array<string>} [exclude=[]] - Never cache these resource names
+ *
+ * @property {boolean} [includePartitions=true] - Whether to cache partition queries
+ * @property {string} [partitionStrategy='hierarchical'] - Partition caching strategy
+ * @property {boolean} [partitionAware=true] - Use partition-aware filesystem cache
+ * @property {boolean} [trackUsage=true] - Track cache usage statistics
+ * @property {boolean} [preloadRelated=true] - Preload related partitions
+ *
+ * @property {number} [retryAttempts=3] - Number of retry attempts for cache operations
+ * @property {number} [retryDelay=100] - Delay between retries in milliseconds
+ * @property {boolean} [verbose=false] - Enable verbose logging
+ *
+ * @property {Object} [config] - Driver-specific configuration (can override top-level ttl, maxSize, maxMemoryBytes, maxMemoryPercent)
+ * @property {number} [config.ttl] - Override TTL for this driver
+ * @property {number} [config.maxSize] - Override max number of items
+ * @property {number} [config.maxMemoryBytes] - (MemoryCache only) Maximum memory in bytes. Cannot be used with config.maxMemoryPercent.
+ * @property {number} [config.maxMemoryPercent] - (MemoryCache only) Maximum memory as fraction 0...1 (e.g., 0.1 = 10%). Cannot be used with config.maxMemoryBytes.
+ * @property {boolean} [config.enableCompression] - (MemoryCache only) Enable gzip compression
+ * @property {number} [config.compressionThreshold=1024] - (MemoryCache only) Minimum size in bytes to trigger compression
+ *
+ * @example
+ * // Memory cache with absolute byte limit
+ * new CachePlugin({
+ *   driver: 'memory',
+ *   maxMemoryBytes: 512 * 1024 * 1024, // 512MB
+ *   ttl: 600000 // 10 minutes
+ * })
+ *
+ * @example
+ * // Memory cache with percentage limit (cloud-native)
+ * new CachePlugin({
+ *   driver: 'memory',
+ *   maxMemoryPercent: 0.1, // 10% of system memory
+ *   ttl: 1800000 // 30 minutes
+ * })
+ *
+ * @example
+ * // Filesystem cache with partition awareness
+ * new CachePlugin({
+ *   driver: 'filesystem',
+ *   partitionAware: true,
+ *   includePartitions: true,
+ *   ttl: 3600000 // 1 hour
+ * })
+ *
+ * @example
+ * // S3 cache (default)
+ * new CachePlugin({
+ *   driver: 's3',
+ *   ttl: 7200000 // 2 hours
+ * })
+ *
+ * @example
+ * // Selective caching
+ * new CachePlugin({
+ *   driver: 'memory',
+ *   include: ['users', 'products'], // Only cache these
+ *   exclude: ['audit_logs'], // Never cache these
+ *   maxMemoryPercent: 0.15
+ * })
+ *
+ * @notes
+ * - maxMemoryBytes and maxMemoryPercent are mutually exclusive (throws error if both set)
+ * - maxMemoryPercent is recommended for containerized/cloud environments
+ * - Plugin-created resources (createdBy !== 'user') are skipped by default
+ * - Cache is automatically invalidated on insert/update/delete operations
+ * - Use skipCache: true option on queries to bypass cache for specific calls
+ */
 export class CachePlugin extends Plugin {
   constructor(options = {}) {
     super(options);
@@ -20,7 +102,9 @@ export class CachePlugin extends Plugin {
       config: {
         ttl: options.ttl,
         maxSize: options.maxSize,
-        ...options.config // Driver-specific config (can override ttl/maxSize)
+        maxMemoryBytes: options.maxMemoryBytes,
+        maxMemoryPercent: options.maxMemoryPercent,
+        ...options.config // Driver-specific config (can override ttl/maxSize/maxMemoryBytes/maxMemoryPercent)
       },
 
       // Resource filtering