s3db.js 11.2.0 → 11.2.3

package/dist/s3db.es.js

@@ -11,6 +11,7 @@ import jsonStableStringify from 'json-stable-stringify';
 import { Transform, Writable } from 'stream';
 import { PromisePool } from '@supercharge/promise-pool';
 import { ReadableStream } from 'node:stream/web';
+import os$1 from 'node:os';
 import { chunk, merge, isString, isEmpty, invert, uniq, cloneDeep, get, set, isObject, isFunction } from 'lodash-es';
 import { Agent } from 'http';
 import { Agent as Agent$1 } from 'https';
@@ -217,7 +218,7 @@ function calculateEffectiveLimit(config = {}) {
 }
 
 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 + `
 
 Verbose:
@@ -243,6 +244,7 @@ ${JSON.stringify(rest, null, 2)}`;
     this.commandInput = commandInput;
     this.metadata = metadata;
     this.suggestion = suggestion;
+    this.description = description;
     this.data = { bucket, key, ...rest, verbose, message };
   }
   toJson() {
@@ -260,6 +262,7 @@ ${JSON.stringify(rest, null, 2)}`;
       commandInput: this.commandInput,
       metadata: this.metadata,
       suggestion: this.suggestion,
+      description: this.description,
       data: this.data,
       original: this.original,
       stack: this.stack
@@ -452,7 +455,107 @@ class ResourceError extends S3dbError {
 }
 class PartitionError extends S3dbError {
   constructor(message, details = {}) {
-    super(message, { ...details, suggestion: details.suggestion || "Check partition definition, fields, and input values." });
+    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) => `  \u2022 ${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 ? "  \u2022 Update partition definition to use existing fields" : `  \u2022 Add missing field to schema, OR
+  \u2022 Update partition definition to use existing fields, OR
+  \u2022 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."
+    });
+  }
+}
+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}`;
+    const description = `
+Analytics Not Enabled
+
+Plugin: ${pluginName}
+Resource: ${resourceName}
+Field: ${field}
+
+Diagnostics:
+  \u2022 Plugin initialized: ${pluginInitialized ? "\u2713 Yes" : "\u2717 No"}
+  \u2022 Analytics resources created: ${registeredResources.length}/${configuredResources.length}
+${configuredResources.map((r) => {
+      const exists = registeredResources.includes(r);
+      return `    ${exists ? "\u2713" : "\u2717"} ${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."
+    });
   }
 }
 
@@ -3601,6 +3704,24 @@ class MemoryCache extends Cache {
     this.cache = {};
     this.meta = {};
     this.maxSize = config.maxSize !== void 0 ? config.maxSize : 1e3;
+    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)."
+      );
+    }
+    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$1.totalmem();
+      this.maxMemoryBytes = Math.floor(totalMemory * config.maxMemoryPercent);
+      this.maxMemoryPercent = config.maxMemoryPercent;
+    } else {
+      this.maxMemoryBytes = config.maxMemoryBytes !== void 0 ? config.maxMemoryBytes : 0;
+      this.maxMemoryPercent = 0;
+    }
     this.ttl = config.ttl !== void 0 ? config.ttl : 3e5;
     this.enableCompression = config.enableCompression !== void 0 ? config.enableCompression : false;
     this.compressionThreshold = config.compressionThreshold !== void 0 ? config.compressionThreshold : 1024;
@@ -3610,23 +3731,18 @@ class MemoryCache extends Cache {
       totalCompressedSize: 0,
       compressionRatio: 0
     };
+    this.currentMemoryBytes = 0;
+    this.evictedDueToMemory = 0;
   }
   async _set(key, data) {
-    if (this.maxSize > 0 && Object.keys(this.cache).length >= this.maxSize) {
-      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];
-      }
-    }
     let finalData = data;
     let compressed = false;
     let originalSize = 0;
     let compressedSize = 0;
+    const serialized = JSON.stringify(data);
+    originalSize = Buffer.byteLength(serialized, "utf8");
     if (this.enableCompression) {
       try {
-        const serialized = JSON.stringify(data);
-        originalSize = Buffer.byteLength(serialized, "utf8");
         if (originalSize >= this.compressionThreshold) {
           const compressedBuffer = zlib.gzipSync(Buffer.from(serialized, "utf8"));
           finalData = {
@@ -3645,13 +3761,42 @@ class MemoryCache extends Cache {
         console.warn(`[MemoryCache] Compression failed for key '${key}':`, error.message);
       }
     }
+    const itemSize = compressed ? compressedSize : originalSize;
+    if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
+      const oldSize = this.meta[key]?.compressedSize || 0;
+      this.currentMemoryBytes -= oldSize;
+    }
+    if (this.maxMemoryBytes > 0) {
+      while (this.currentMemoryBytes + itemSize > this.maxMemoryBytes && Object.keys(this.cache).length > 0) {
+        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;
+        }
+      }
+    }
+    if (this.maxSize > 0 && Object.keys(this.cache).length >= this.maxSize) {
+      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.cache[key] = finalData;
     this.meta[key] = {
       ts: Date.now(),
       compressed,
       originalSize,
-      compressedSize: compressed ? compressedSize : originalSize
+      compressedSize: itemSize
     };
+    this.currentMemoryBytes += itemSize;
     return data;
   }
   async _get(key) {
@@ -3659,7 +3804,9 @@ class MemoryCache extends Cache {
     if (this.ttl > 0) {
       const now = Date.now();
       const meta = this.meta[key];
-      if (meta && now - meta.ts > this.ttl * 1e3) {
+      if (meta && now - meta.ts > this.ttl) {
+        const itemSize = meta.compressedSize || 0;
+        this.currentMemoryBytes -= itemSize;
         delete this.cache[key];
         delete this.meta[key];
         return null;
@@ -3681,6 +3828,10 @@ class MemoryCache extends Cache {
     return rawData;
   }
   async _del(key) {
+    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;
@@ -3689,10 +3840,13 @@ class MemoryCache extends Cache {
     if (!prefix) {
       this.cache = {};
       this.meta = {};
+      this.currentMemoryBytes = 0;
       return true;
     }
     for (const key of Object.keys(this.cache)) {
       if (key.startsWith(prefix)) {
+        const itemSize = this.meta[key]?.compressedSize || 0;
+        this.currentMemoryBytes -= itemSize;
         delete this.cache[key];
         delete this.meta[key];
       }
@@ -3730,6 +3884,53 @@ 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$1.totalmem(),
+      free: os$1.freemem(),
+      used: os$1.totalmem() - os$1.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]}`;
+  }
 }
 
 class FilesystemCache extends Cache {
@@ -4559,8 +4760,10 @@ class CachePlugin extends Plugin {
       config: {
         ttl: options.ttl,
         maxSize: options.maxSize,
+        maxMemoryBytes: options.maxMemoryBytes,
+        maxMemoryPercent: options.maxMemoryPercent,
         ...options.config
-        // Driver-specific config (can override ttl/maxSize)
+        // Driver-specific config (can override ttl/maxSize/maxMemoryBytes/maxMemoryPercent)
       },
       // Resource filtering
       include: options.include || null,
@@ -5101,8 +5304,10 @@ function createConfig(options, detectedTimezone) {
     consolidationWindow: consolidation.window ?? 24,
     autoConsolidate: consolidation.auto !== false,
     mode: consolidation.mode || "async",
-    // ✅ NOVO: Performance tuning - Mark applied concurrency (default 50, antes era 10 hardcoded)
+    // ✅ Performance tuning - Mark applied concurrency (default 50, up from 10)
     markAppliedConcurrency: consolidation.markAppliedConcurrency ?? 50,
+    // ✅ Performance tuning - Recalculate concurrency (default 50, up from 10)
+    recalculateConcurrency: consolidation.recalculateConcurrency ?? 50,
     // Late arrivals
     lateArrivalStrategy: lateArrivals.strategy || "warn",
     // Batch transactions
@@ -5931,11 +6136,33 @@ async function consolidateRecord(originalId, transactionResource, targetResource
       const transactionsToUpdate = transactions.filter((txn) => txn.id !== "__synthetic__");
       const markAppliedConcurrency = config.markAppliedConcurrency || 50;
       const { results, errors } = await PromisePool.for(transactionsToUpdate).withConcurrency(markAppliedConcurrency).process(async (txn) => {
+        const txnWithCohorts = ensureCohortHour(txn, config.cohort.timezone, false);
+        const updateData = { applied: true };
+        if (txnWithCohorts.cohortHour && !txn.cohortHour) {
+          updateData.cohortHour = txnWithCohorts.cohortHour;
+        }
+        if (txnWithCohorts.cohortDate && !txn.cohortDate) {
+          updateData.cohortDate = txnWithCohorts.cohortDate;
+        }
+        if (txnWithCohorts.cohortWeek && !txn.cohortWeek) {
+          updateData.cohortWeek = txnWithCohorts.cohortWeek;
+        }
+        if (txnWithCohorts.cohortMonth && !txn.cohortMonth) {
+          updateData.cohortMonth = txnWithCohorts.cohortMonth;
+        }
+        if (txn.value === null || txn.value === void 0) {
+          updateData.value = 1;
+        }
         const [ok2, err2] = await tryFn(
-          () => transactionResource.update(txn.id, { applied: true })
+          () => transactionResource.update(txn.id, updateData)
         );
         if (!ok2 && config.verbose) {
-          console.warn(`[EventualConsistency] Failed to mark transaction ${txn.id} as applied:`, err2?.message);
+          console.warn(
+            `[EventualConsistency] Failed to mark transaction ${txn.id} as applied:`,
+            err2?.message,
+            "Update data:",
+            updateData
+          );
         }
         return ok2;
       });
@@ -6127,7 +6354,8 @@ async function recalculateRecord(originalId, transactionResource, targetResource
       }
     }
     const transactionsToReset = allTransactions.filter((txn) => txn.source !== "anchor");
-    const { results, errors } = await PromisePool.for(transactionsToReset).withConcurrency(10).process(async (txn) => {
+    const recalculateConcurrency = config.recalculateConcurrency || 50;
+    const { results, errors } = await PromisePool.for(transactionsToReset).withConcurrency(recalculateConcurrency).process(async (txn) => {
       const [ok, err] = await tryFn(
         () => transactionResource.update(txn.id, { applied: false })
       );
@@ -6994,6 +7222,80 @@ async function getLastNMonths(resourceName, field, months = 12, options, fieldHa
   }
   return data;
 }
+async function getRawEvents(resourceName, field, options, fieldHandlers) {
+  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;
+  const query = {};
+  if (recordId !== void 0) {
+    query.originalId = recordId;
+  }
+  if (applied !== void 0) {
+    query.applied = applied;
+  }
+  const [ok, err, allTransactions] = await tryFn(
+    () => handler.transactionResource.query(query)
+  );
+  if (!ok || !allTransactions) {
+    return [];
+  }
+  let filtered = allTransactions;
+  if (operation !== void 0) {
+    filtered = filtered.filter((t) => t.operation === operation);
+  }
+  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) {
+    const isHourly = startDate.length > 10;
+    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);
+  }
+  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;
+  });
+  if (limit && limit > 0) {
+    filtered = filtered.slice(0, limit);
+  }
+  return filtered;
+}
 
 function addHelperMethods(resource, plugin, config) {
   resource.set = async (id, field, value) => {
@@ -7218,6 +7520,28 @@ async function createAnalyticsResource(handler, database, resourceName, fieldNam
       },
       behavior: "body-overflow",
       timestamps: false,
+      asyncPartitions: true,
+      // ✅ Multi-attribute partitions for optimal analytics query performance
+      partitions: {
+        // Query by period (hour/day/week/month)
+        byPeriod: {
+          fields: { period: "string" }
+        },
+        // Query by period + cohort (e.g., all hour records for specific hours)
+        byPeriodCohort: {
+          fields: {
+            period: "string",
+            cohort: "string"
+          }
+        },
+        // Query by field + period (e.g., all daily analytics for clicks field)
+        byFieldPeriod: {
+          fields: {
+            field: "string",
+            period: "string"
+          }
+        }
+      },
       createdBy: "EventualConsistencyPlugin"
     })
   );
@@ -7729,6 +8053,185 @@ class EventualConsistencyPlugin extends Plugin {
   async getLastNMonths(resourceName, field, months = 12, options = {}) {
     return await getLastNMonths(resourceName, field, months, options, this.fieldHandlers);
   }
+  /**
+   * 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
+   * @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
+   * });
+   */
+  async getRawEvents(resourceName, field, options = {}) {
+    return await getRawEvents(resourceName, field, options, this.fieldHandlers);
+  }
+  /**
+   * Get diagnostics information about the plugin state
+   *
+   * This method provides comprehensive diagnostic information about the EventualConsistencyPlugin,
+   * including configured resources, field handlers, timers, and overall health status.
+   * Useful for debugging initialization issues, configuration problems, or runtime errors.
+   *
+   * @param {Object} options - Diagnostic options
+   * @param {string} options.resourceName - Optional: limit diagnostics to specific resource
+   * @param {string} options.field - Optional: limit diagnostics to specific field
+   * @param {boolean} options.includeStats - Include transaction statistics (default: false)
+   * @returns {Promise<Object>} Diagnostic information
+   *
+   * @example
+   * // Get overall plugin diagnostics
+   * const diagnostics = await plugin.getDiagnostics();
+   * console.log(diagnostics);
+   *
+   * @example
+   * // Get diagnostics for specific resource/field with stats
+   * const diagnostics = await plugin.getDiagnostics({
+   *   resourceName: 'wallets',
+   *   field: 'balance',
+   *   includeStats: true
+   * });
+   */
+  async getDiagnostics(options = {}) {
+    const { resourceName, field, includeStats = false } = options;
+    const diagnostics = {
+      plugin: {
+        name: "EventualConsistencyPlugin",
+        initialized: this.database !== null && this.database !== void 0,
+        verbose: this.config.verbose || false,
+        timezone: this.config.cohort?.timezone || "UTC",
+        consolidation: {
+          mode: this.config.consolidation?.mode || "timer",
+          interval: this.config.consolidation?.interval || 6e4,
+          batchSize: this.config.consolidation?.batchSize || 100
+        },
+        garbageCollection: {
+          enabled: this.config.garbageCollection?.enabled !== false,
+          retentionDays: this.config.garbageCollection?.retentionDays || 30,
+          interval: this.config.garbageCollection?.interval || 36e5
+        }
+      },
+      resources: [],
+      errors: [],
+      warnings: []
+    };
+    for (const [resName, resourceHandlers] of this.fieldHandlers.entries()) {
+      if (resourceName && resName !== resourceName) {
+        continue;
+      }
+      const resourceDiag = {
+        name: resName,
+        fields: []
+      };
+      for (const [fieldName, handler] of resourceHandlers.entries()) {
+        if (field && fieldName !== field) {
+          continue;
+        }
+        const fieldDiag = {
+          name: fieldName,
+          type: handler.type || "counter",
+          analyticsEnabled: handler.analyticsResource !== null && handler.analyticsResource !== void 0,
+          resources: {
+            transaction: handler.transactionResource?.name || null,
+            target: handler.targetResource?.name || null,
+            analytics: handler.analyticsResource?.name || null
+          },
+          timers: {
+            consolidation: handler.consolidationTimer !== null && handler.consolidationTimer !== void 0,
+            garbageCollection: handler.garbageCollectionTimer !== null && handler.garbageCollectionTimer !== void 0
+          }
+        };
+        if (!handler.transactionResource) {
+          diagnostics.errors.push({
+            resource: resName,
+            field: fieldName,
+            issue: "Missing transaction resource",
+            suggestion: "Ensure plugin is installed and resources are created after plugin installation"
+          });
+        }
+        if (!handler.targetResource) {
+          diagnostics.warnings.push({
+            resource: resName,
+            field: fieldName,
+            issue: "Missing target resource",
+            suggestion: "Target resource may not have been created yet"
+          });
+        }
+        if (handler.analyticsResource && !handler.analyticsResource.name) {
+          diagnostics.errors.push({
+            resource: resName,
+            field: fieldName,
+            issue: "Invalid analytics resource",
+            suggestion: "Analytics resource exists but has no name - possible initialization failure"
+          });
+        }
+        if (includeStats && handler.transactionResource) {
+          try {
+            const [okPending, errPending, pendingTxns] = await handler.transactionResource.query({ applied: false }).catch(() => [false, null, []]);
+            const [okApplied, errApplied, appliedTxns] = await handler.transactionResource.query({ applied: true }).catch(() => [false, null, []]);
+            fieldDiag.stats = {
+              pendingTransactions: okPending ? pendingTxns?.length || 0 : "error",
+              appliedTransactions: okApplied ? appliedTxns?.length || 0 : "error",
+              totalTransactions: okPending && okApplied ? (pendingTxns?.length || 0) + (appliedTxns?.length || 0) : "error"
+            };
+            if (handler.analyticsResource) {
+              const [okAnalytics, errAnalytics, analyticsRecords] = await handler.analyticsResource.list().catch(() => [false, null, []]);
+              fieldDiag.stats.analyticsRecords = okAnalytics ? analyticsRecords?.length || 0 : "error";
+            }
+          } catch (error) {
+            diagnostics.warnings.push({
+              resource: resName,
+              field: fieldName,
+              issue: "Failed to fetch statistics",
+              error: error.message
+            });
+          }
+        }
+        resourceDiag.fields.push(fieldDiag);
+      }
+      if (resourceDiag.fields.length > 0) {
+        diagnostics.resources.push(resourceDiag);
+      }
+    }
+    diagnostics.health = {
+      status: diagnostics.errors.length === 0 ? diagnostics.warnings.length === 0 ? "healthy" : "warning" : "error",
+      totalResources: diagnostics.resources.length,
+      totalFields: diagnostics.resources.reduce((sum, r) => sum + r.fields.length, 0),
+      errorCount: diagnostics.errors.length,
+      warningCount: diagnostics.warnings.length
+    };
+    return diagnostics;
+  }
 }
 
 class FullTextPlugin extends Plugin {
@@ -11350,6 +11853,7 @@ ${errorDetails}`,
       idGenerator: customIdGenerator,
       idSize = 22,
       versioningEnabled = false,
+      strictValidation = true,
       events = {},
       asyncEvents = true,
       asyncPartitions = true,
@@ -11363,6 +11867,7 @@ ${errorDetails}`,
     this.parallelism = parallelism;
     this.passphrase = passphrase ?? "secret";
     this.versioningEnabled = versioningEnabled;
+    this.strictValidation = strictValidation;
     this.setAsyncMode(asyncEvents);
     this.idGenerator = this.configureIdGenerator(customIdGenerator, idSize);
     if (typeof customIdGenerator === "number" && customIdGenerator > 0) {
@@ -11610,9 +12115,12 @@ ${errorDetails}`,
   }
   /**
    * Validate that all partition fields exist in current resource attributes
-   * @throws {Error} If partition fields don't exist in current schema
+   * @throws {Error} If partition fields don't exist in current schema (only when strictValidation is true)
    */
   validatePartitions() {
+    if (!this.strictValidation) {
+      return;
+    }
     if (!this.config.partitions) {
       return;
     }
@@ -13747,7 +14255,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.0" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.2.3" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -13762,6 +14270,7 @@ class Database extends EventEmitter {
     this.passphrase = options.passphrase || "secret";
     this.versioningEnabled = options.versioningEnabled || false;
     this.persistHooks = options.persistHooks || false;
+    this.strictValidation = options.strictValidation !== false;
     this._initHooks();
     let connectionString = options.connectionString;
     if (!connectionString && (options.bucket || options.accessKeyId || options.secretAccessKey)) {
@@ -13883,6 +14392,7 @@ class Database extends EventEmitter {
           asyncEvents: versionData.asyncEvents !== void 0 ? 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
@@ -14544,6 +15054,7 @@ class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== void 0 ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
+      strictValidation: this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,
@@ -17378,5 +17889,5 @@ class StateMachinePlugin extends Plugin {
   }
 }
 
-export { AVAILABLE_BEHAVIORS, AuditPlugin, AuthenticationError, BackupPlugin, BaseError, CachePlugin, Client, ConnectionString, ConnectionStringError, CostsPlugin, CryptoError, DEFAULT_BEHAVIOR, Database, DatabaseError, EncryptionError, ErrorMap, EventualConsistencyPlugin, FullTextPlugin, InvalidResourceItem, MetricsPlugin, MissingMetadata, NoSuchBucket, NoSuchKey, NotFound, PartitionError, PermissionError, Plugin, PluginObject, QueueConsumerPlugin, ReplicatorPlugin, Resource, ResourceError, ResourceIdsPageReader, ResourceIdsReader, ResourceNotFound, ResourceReader, ResourceWriter, S3QueuePlugin, Database as S3db, S3dbError, SchedulerPlugin, Schema, SchemaError, StateMachinePlugin, UnknownError, ValidationError, Validator, behaviors, calculateAttributeNamesSize, calculateAttributeSizes, calculateEffectiveLimit, calculateSystemOverhead, calculateTotalSize, calculateUTF8Bytes, clearUTF8Cache, clearUTF8Memo, clearUTF8Memory, decode, decodeDecimal, decrypt, S3db as default, encode, encodeDecimal, encrypt, getBehavior, getSizeBreakdown, idGenerator, mapAwsError, md5, passwordGenerator, sha256, streamToString, transformValue, tryFn, tryFnSync };
+export { AVAILABLE_BEHAVIORS, AnalyticsNotEnabledError, AuditPlugin, AuthenticationError, BackupPlugin, BaseError, CachePlugin, Client, ConnectionString, ConnectionStringError, CostsPlugin, CryptoError, DEFAULT_BEHAVIOR, Database, DatabaseError, EncryptionError, ErrorMap, EventualConsistencyPlugin, FullTextPlugin, InvalidResourceItem, MetricsPlugin, MissingMetadata, NoSuchBucket, NoSuchKey, NotFound, PartitionError, PermissionError, Plugin, PluginObject, QueueConsumerPlugin, ReplicatorPlugin, Resource, ResourceError, ResourceIdsPageReader, ResourceIdsReader, ResourceNotFound, ResourceReader, ResourceWriter, S3QueuePlugin, Database as S3db, S3dbError, SchedulerPlugin, Schema, SchemaError, StateMachinePlugin, UnknownError, ValidationError, Validator, behaviors, calculateAttributeNamesSize, calculateAttributeSizes, calculateEffectiveLimit, calculateSystemOverhead, calculateTotalSize, calculateUTF8Bytes, clearUTF8Cache, clearUTF8Memo, clearUTF8Memory, decode, decodeDecimal, decrypt, S3db as default, encode, encodeDecimal, encrypt, getBehavior, getSizeBreakdown, idGenerator, mapAwsError, md5, passwordGenerator, sha256, streamToString, transformValue, tryFn, tryFnSync };
 //# sourceMappingURL=s3db.es.js.map