s3db.js 11.2.2 → 11.2.4

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.errors.js

@@ -0,0 +1,47 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * CacheError - Errors related to cache operations
+ *
+ * Used for cache operations including:
+ * - Cache driver initialization and setup
+ * - Cache get/set/delete operations
+ * - Cache invalidation and warming
+ * - Driver-specific operations (memory, filesystem, S3)
+ * - Resource-level caching
+ *
+ * @extends S3dbError
+ */
+export class CacheError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = 'unknown', operation = 'unknown', resourceName, key, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Cache Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ''}
+${key ? `Key: ${key}` : ''}
+
+Common causes:
+1. Invalid cache key format
+2. Cache driver not properly initialized
+3. Resource not found or not cached
+4. Memory limits exceeded
+5. Filesystem permissions issues
+
+Solution:
+Check cache configuration and ensure the cache driver is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/cache.md
+`.trim();
+    }
+
+    super(message, { ...rest, driver, operation, resourceName, key, description });
+  }
+}
+
+export default CacheError;

package/src/plugins/cache.plugin.js

@@ -8,7 +8,90 @@ import MemoryCache from "./cache/memory-cache.class.js";
 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";
-
+import { CacheError } from "./cache.errors.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 +103,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
@@ -471,7 +556,13 @@ export class CachePlugin extends Plugin {
   async warmCache(resourceName, options = {}) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new CacheError('Resource not found for cache warming', {
+        operation: 'warmCache',
+        driver: this.driver?.constructor.name,
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: 'Check resource name spelling or ensure resource has been created'
+      });
     }
 
     const { includePartitions = true, sampleSize = 100 } = options;

package/src/plugins/eventual-consistency/analytics.js

@@ -1209,3 +1209,148 @@ export async function getLastNMonths(resourceName, field, months = 12, options,
 
   return data;
 }
+
+/**
+ * Get raw transaction events for custom aggregation
+ *
+ * This method provides direct access to the underlying transaction events,
+ * allowing developers to perform custom aggregations beyond the pre-built analytics.
+ * Useful for complex queries, custom metrics, or when you need the raw event data.
+ *
+ * @param {string} resourceName - Resource name
+ * @param {string} field - Field name
+ * @param {Object} options - Query options
+ * @param {string} options.recordId - Filter by specific record ID
+ * @param {string} options.startDate - Start date filter (YYYY-MM-DD or YYYY-MM-DDTHH)
+ * @param {string} options.endDate - End date filter (YYYY-MM-DD or YYYY-MM-DDTHH)
+ * @param {string} options.cohortDate - Filter by cohort date (YYYY-MM-DD)
+ * @param {string} options.cohortHour - Filter by cohort hour (YYYY-MM-DDTHH)
+ * @param {string} options.cohortMonth - Filter by cohort month (YYYY-MM)
+ * @param {boolean} options.applied - Filter by applied status (true/false/undefined for both)
+ * @param {string} options.operation - Filter by operation type ('add', 'sub', 'set')
+ * @param {number} options.limit - Maximum number of events to return
+ * @param {Object} fieldHandlers - Field handlers map
+ * @returns {Promise<Array>} Raw transaction events
+ *
+ * @example
+ * // Get all events for a specific record
+ * const events = await plugin.getRawEvents('wallets', 'balance', {
+ *   recordId: 'wallet1'
+ * });
+ *
+ * @example
+ * // Get events for a specific time range
+ * const events = await plugin.getRawEvents('wallets', 'balance', {
+ *   startDate: '2025-10-01',
+ *   endDate: '2025-10-31'
+ * });
+ *
+ * @example
+ * // Get only pending (unapplied) transactions
+ * const pending = await plugin.getRawEvents('wallets', 'balance', {
+ *   applied: false
+ * });
+ */
+export async function getRawEvents(resourceName, field, options, fieldHandlers) {
+  // Get handler for this resource/field combination
+  const resourceHandlers = fieldHandlers.get(resourceName);
+  if (!resourceHandlers) {
+    throw new Error(`No eventual consistency configured for resource: ${resourceName}`);
+  }
+
+  const handler = resourceHandlers.get(field);
+  if (!handler) {
+    throw new Error(`No eventual consistency configured for field: ${resourceName}.${field}`);
+  }
+
+  if (!handler.transactionResource) {
+    throw new Error('Transaction resource not initialized');
+  }
+
+  const {
+    recordId,
+    startDate,
+    endDate,
+    cohortDate,
+    cohortHour,
+    cohortMonth,
+    applied,
+    operation,
+    limit
+  } = options;
+
+  // Build query object for partition-based filtering
+  const query = {};
+
+  // Filter by recordId (uses partition if available)
+  if (recordId !== undefined) {
+    query.originalId = recordId;
+  }
+
+  // Filter by applied status (uses partition)
+  if (applied !== undefined) {
+    query.applied = applied;
+  }
+
+  // Fetch transactions using partition-aware query
+  const [ok, err, allTransactions] = await tryFn(() =>
+    handler.transactionResource.query(query)
+  );
+
+  if (!ok || !allTransactions) {
+    return [];
+  }
+
+  // Ensure all transactions have cohort fields
+  let filtered = allTransactions;
+
+  // Filter by operation type
+  if (operation !== undefined) {
+    filtered = filtered.filter(t => t.operation === operation);
+  }
+
+  // Filter by temporal fields (these are in-memory filters after partition query)
+  if (cohortDate) {
+    filtered = filtered.filter(t => t.cohortDate === cohortDate);
+  }
+
+  if (cohortHour) {
+    filtered = filtered.filter(t => t.cohortHour === cohortHour);
+  }
+
+  if (cohortMonth) {
+    filtered = filtered.filter(t => t.cohortMonth === cohortMonth);
+  }
+
+  if (startDate && endDate) {
+    // Determine which cohort field to use based on format
+    const isHourly = startDate.length > 10; // YYYY-MM-DDTHH vs YYYY-MM-DD
+    const cohortField = isHourly ? 'cohortHour' : 'cohortDate';
+
+    filtered = filtered.filter(t =>
+      t[cohortField] && t[cohortField] >= startDate && t[cohortField] <= endDate
+    );
+  } else if (startDate) {
+    const isHourly = startDate.length > 10;
+    const cohortField = isHourly ? 'cohortHour' : 'cohortDate';
+    filtered = filtered.filter(t => t[cohortField] && t[cohortField] >= startDate);
+  } else if (endDate) {
+    const isHourly = endDate.length > 10;
+    const cohortField = isHourly ? 'cohortHour' : 'cohortDate';
+    filtered = filtered.filter(t => t[cohortField] && t[cohortField] <= endDate);
+  }
+
+  // Sort by timestamp (newest first by default)
+  filtered.sort((a, b) => {
+    const aTime = new Date(a.timestamp || a.createdAt).getTime();
+    const bTime = new Date(b.timestamp || b.createdAt).getTime();
+    return bTime - aTime;
+  });
+
+  // Apply limit
+  if (limit && limit > 0) {
+    filtered = filtered.slice(0, limit);
+  }
+
+  return filtered;
+}