s3db.js 10.0.4 → 10.0.6

package/dist/s3db.cjs.js

@@ -4449,8 +4449,24 @@ class EventualConsistencyPlugin extends Plugin {
     this.addHelperMethods();
     if (this.config.autoConsolidate) {
       this.startConsolidationTimer();
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Auto-consolidation ENABLED (interval: ${this.config.consolidationInterval}s, window: ${this.config.consolidationWindow}h, mode: ${this.config.mode})`
+        );
+      }
+    } else {
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Auto-consolidation DISABLED (manual consolidation only)`
+        );
+      }
     }
     this.startGarbageCollectionTimer();
+    if (this.config.verbose) {
+      console.log(
+        `[EventualConsistency] ${this.config.resource}.${this.config.field} - Setup complete. Resources: ${this.config.resource}_transactions_${this.config.field}, ${this.config.resource}_consolidation_locks_${this.config.field}${this.config.enableAnalytics ? `, ${this.config.resource}_analytics_${this.config.field}` : ""}`
+      );
+    }
   }
   async onStart() {
     if (this.deferredSetup) {
@@ -4711,11 +4727,21 @@ class EventualConsistencyPlugin extends Plugin {
     };
     if (this.config.batchTransactions) {
       this.pendingTransactions.set(transaction.id, transaction);
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Transaction batched: ${data.operation} ${data.value} for ${data.originalId} (batch: ${this.pendingTransactions.size}/${this.config.batchSize})`
+        );
+      }
       if (this.pendingTransactions.size >= this.config.batchSize) {
         await this.flushPendingTransactions();
       }
     } else {
       await this.transactionResource.insert(transaction);
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Transaction created: ${data.operation} ${data.value} for ${data.originalId} (cohort: ${cohortInfo.hour}, applied: false)`
+        );
+      }
     }
     return transaction;
   }
@@ -4780,11 +4806,23 @@ class EventualConsistencyPlugin extends Plugin {
   }
   startConsolidationTimer() {
     const intervalMs = this.config.consolidationInterval * 1e3;
+    if (this.config.verbose) {
+      const nextRun = new Date(Date.now() + intervalMs);
+      console.log(
+        `[EventualConsistency] ${this.config.resource}.${this.config.field} - Consolidation timer started. Next run at ${nextRun.toISOString()} (every ${this.config.consolidationInterval}s)`
+      );
+    }
     this.consolidationTimer = setInterval(async () => {
       await this.runConsolidation();
     }, intervalMs);
   }
   async runConsolidation() {
+    const startTime = Date.now();
+    if (this.config.verbose) {
+      console.log(
+        `[EventualConsistency] ${this.config.resource}.${this.config.field} - Starting consolidation run at ${(/* @__PURE__ */ new Date()).toISOString()}`
+      );
+    }
     try {
       const now = /* @__PURE__ */ new Date();
       const hoursToCheck = this.config.consolidationWindow || 24;
@@ -4794,6 +4832,11 @@ class EventualConsistencyPlugin extends Plugin {
         const cohortInfo = this.getCohortInfo(date);
         cohortHours.push(cohortInfo.hour);
       }
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Querying ${hoursToCheck} hour partitions for pending transactions...`
+        );
+      }
       const transactionsByHour = await Promise.all(
         cohortHours.map(async (cohortHour) => {
           const [ok, err, txns] = await tryFn(
@@ -4808,26 +4851,47 @@ class EventualConsistencyPlugin extends Plugin {
       const transactions = transactionsByHour.flat();
       if (transactions.length === 0) {
         if (this.config.verbose) {
-          console.log(`[EventualConsistency] No pending transactions to consolidate`);
+          console.log(
+            `[EventualConsistency] ${this.config.resource}.${this.config.field} - No pending transactions found. Next run in ${this.config.consolidationInterval}s`
+          );
         }
         return;
       }
       const uniqueIds = [...new Set(transactions.map((t) => t.originalId))];
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Found ${transactions.length} pending transactions for ${uniqueIds.length} records. Consolidating with concurrency=${this.config.consolidationConcurrency}...`
+        );
+      }
       const { results, errors } = await promisePool.PromisePool.for(uniqueIds).withConcurrency(this.config.consolidationConcurrency).process(async (id) => {
         return await this.consolidateRecord(id);
       });
+      const duration = Date.now() - startTime;
       if (errors && errors.length > 0) {
-        console.error(`Consolidation completed with ${errors.length} errors:`, errors);
+        console.error(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Consolidation completed with ${errors.length} errors in ${duration}ms:`,
+          errors
+        );
+      }
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Consolidation complete: ${results.length} records consolidated in ${duration}ms (${errors.length} errors). Next run in ${this.config.consolidationInterval}s`
+        );
       }
       this.emit("eventual-consistency.consolidated", {
         resource: this.config.resource,
         field: this.config.field,
         recordCount: uniqueIds.length,
         successCount: results.length,
-        errorCount: errors.length
+        errorCount: errors.length,
+        duration
       });
     } catch (error) {
-      console.error("Consolidation error:", error);
+      const duration = Date.now() - startTime;
+      console.error(
+        `[EventualConsistency] ${this.config.resource}.${this.config.field} - Consolidation error after ${duration}ms:`,
+        error
+      );
       this.emit("eventual-consistency.consolidation-error", error);
     }
   }
@@ -4862,8 +4926,18 @@ class EventualConsistencyPlugin extends Plugin {
         })
       );
       if (!ok || !transactions || transactions.length === 0) {
+        if (this.config.verbose) {
+          console.log(
+            `[EventualConsistency] ${this.config.resource}.${this.config.field} - No pending transactions for ${originalId}, skipping`
+          );
+        }
         return currentValue;
       }
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Consolidating ${originalId}: ${transactions.length} pending transactions (current: ${currentValue})`
+        );
+      }
       transactions.sort(
         (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
       );
@@ -4872,6 +4946,11 @@ class EventualConsistencyPlugin extends Plugin {
         transactions.unshift(this._createSyntheticSetTransaction(currentValue));
       }
       const consolidatedValue = this.config.reducer(transactions);
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - ${originalId}: ${currentValue} \u2192 ${consolidatedValue} (${consolidatedValue > currentValue ? "+" : ""}${consolidatedValue - currentValue})`
+        );
+      }
       const [updateOk, updateErr] = await tryFn(
         () => this.targetResource.update(originalId, {
           [this.config.field]: consolidatedValue
@@ -5108,21 +5187,43 @@ class EventualConsistencyPlugin extends Plugin {
    */
   async updateAnalytics(transactions) {
     if (!this.analyticsResource || transactions.length === 0) return;
+    if (this.config.verbose) {
+      console.log(
+        `[EventualConsistency] ${this.config.resource}.${this.config.field} - Updating analytics for ${transactions.length} transactions...`
+      );
+    }
     try {
       const byHour = this._groupByCohort(transactions, "cohortHour");
+      const cohortCount = Object.keys(byHour).length;
+      if (this.config.verbose) {
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Updating ${cohortCount} hourly analytics cohorts...`
+        );
+      }
       for (const [cohort, txns] of Object.entries(byHour)) {
         await this._upsertAnalytics("hour", cohort, txns);
       }
       if (this.config.analyticsConfig.rollupStrategy === "incremental") {
         const uniqueHours = Object.keys(byHour);
+        if (this.config.verbose) {
+          console.log(
+            `[EventualConsistency] ${this.config.resource}.${this.config.field} - Rolling up ${uniqueHours.length} hours to daily/monthly analytics...`
+          );
+        }
         for (const cohortHour of uniqueHours) {
           await this._rollupAnalytics(cohortHour);
         }
       }
-    } catch (error) {
       if (this.config.verbose) {
-        console.warn(`[EventualConsistency] Analytics update error:`, error.message);
+        console.log(
+          `[EventualConsistency] ${this.config.resource}.${this.config.field} - Analytics update complete for ${cohortCount} cohorts`
+        );
       }
+    } catch (error) {
+      console.warn(
+        `[EventualConsistency] ${this.config.resource}.${this.config.field} - Analytics update error:`,
+        error.message
+      );
     }
   }
   /**
@@ -5352,79 +5453,163 @@ class EventualConsistencyPlugin extends Plugin {
       recordCount: a.recordCount
     }));
   }
+  /**
+   * Fill gaps in analytics data with zeros for continuous time series
+   * @private
+   * @param {Array} data - Sparse analytics data
+   * @param {string} period - Period type ('hour', 'day', 'month')
+   * @param {string} startDate - Start date (ISO format)
+   * @param {string} endDate - End date (ISO format)
+   * @returns {Array} Complete time series with gaps filled
+   */
+  _fillGaps(data, period, startDate, endDate) {
+    if (!data || data.length === 0) {
+      data = [];
+    }
+    const dataMap = /* @__PURE__ */ new Map();
+    data.forEach((item) => {
+      dataMap.set(item.cohort, item);
+    });
+    const result = [];
+    const emptyRecord = {
+      count: 0,
+      sum: 0,
+      avg: 0,
+      min: 0,
+      max: 0,
+      recordCount: 0
+    };
+    if (period === "hour") {
+      const start = /* @__PURE__ */ new Date(startDate + "T00:00:00Z");
+      const end = /* @__PURE__ */ new Date(endDate + "T23:59:59Z");
+      for (let dt = new Date(start); dt <= end; dt.setHours(dt.getHours() + 1)) {
+        const cohort = dt.toISOString().substring(0, 13);
+        result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+      }
+    } else if (period === "day") {
+      const start = new Date(startDate);
+      const end = new Date(endDate);
+      for (let dt = new Date(start); dt <= end; dt.setDate(dt.getDate() + 1)) {
+        const cohort = dt.toISOString().substring(0, 10);
+        result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+      }
+    } else if (period === "month") {
+      const startYear = parseInt(startDate.substring(0, 4));
+      const startMonth = parseInt(startDate.substring(5, 7));
+      const endYear = parseInt(endDate.substring(0, 4));
+      const endMonth = parseInt(endDate.substring(5, 7));
+      for (let year = startYear; year <= endYear; year++) {
+        const firstMonth = year === startYear ? startMonth : 1;
+        const lastMonth = year === endYear ? endMonth : 12;
+        for (let month = firstMonth; month <= lastMonth; month++) {
+          const cohort = `${year}-${month.toString().padStart(2, "0")}`;
+          result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+        }
+      }
+    }
+    return result;
+  }
   /**
    * Get analytics for entire month, broken down by days
    * @param {string} resourceName - Resource name
    * @param {string} field - Field name
    * @param {string} month - Month in YYYY-MM format
+   * @param {Object} options - Options
+   * @param {boolean} options.fillGaps - Fill missing days with zeros (default: false)
    * @returns {Promise<Array>} Daily analytics for the month
    */
-  async getMonthByDay(resourceName, field, month) {
+  async getMonthByDay(resourceName, field, month, options = {}) {
     const year = parseInt(month.substring(0, 4));
     const monthNum = parseInt(month.substring(5, 7));
     const firstDay = new Date(year, monthNum - 1, 1);
     const lastDay = new Date(year, monthNum, 0);
     const startDate = firstDay.toISOString().substring(0, 10);
     const endDate = lastDay.toISOString().substring(0, 10);
-    return await this.getAnalytics(resourceName, field, {
+    const data = await this.getAnalytics(resourceName, field, {
       period: "day",
       startDate,
       endDate
     });
+    if (options.fillGaps) {
+      return this._fillGaps(data, "day", startDate, endDate);
+    }
+    return data;
   }
   /**
    * Get analytics for entire day, broken down by hours
    * @param {string} resourceName - Resource name
    * @param {string} field - Field name
    * @param {string} date - Date in YYYY-MM-DD format
+   * @param {Object} options - Options
+   * @param {boolean} options.fillGaps - Fill missing hours with zeros (default: false)
    * @returns {Promise<Array>} Hourly analytics for the day
    */
-  async getDayByHour(resourceName, field, date) {
-    return await this.getAnalytics(resourceName, field, {
+  async getDayByHour(resourceName, field, date, options = {}) {
+    const data = await this.getAnalytics(resourceName, field, {
       period: "hour",
       date
     });
+    if (options.fillGaps) {
+      return this._fillGaps(data, "hour", date, date);
+    }
+    return data;
   }
   /**
    * Get analytics for last N days, broken down by days
    * @param {string} resourceName - Resource name
    * @param {string} field - Field name
    * @param {number} days - Number of days to look back (default: 7)
+   * @param {Object} options - Options
+   * @param {boolean} options.fillGaps - Fill missing days with zeros (default: false)
    * @returns {Promise<Array>} Daily analytics
    */
-  async getLastNDays(resourceName, field, days = 7) {
+  async getLastNDays(resourceName, field, days = 7, options = {}) {
     const dates = Array.from({ length: days }, (_, i) => {
       const date = /* @__PURE__ */ new Date();
       date.setDate(date.getDate() - i);
       return date.toISOString().substring(0, 10);
     }).reverse();
-    return await this.getAnalytics(resourceName, field, {
+    const data = await this.getAnalytics(resourceName, field, {
       period: "day",
       startDate: dates[0],
       endDate: dates[dates.length - 1]
     });
+    if (options.fillGaps) {
+      return this._fillGaps(data, "day", dates[0], dates[dates.length - 1]);
+    }
+    return data;
   }
   /**
    * Get analytics for entire year, broken down by months
    * @param {string} resourceName - Resource name
    * @param {string} field - Field name
    * @param {number} year - Year (e.g., 2025)
+   * @param {Object} options - Options
+   * @param {boolean} options.fillGaps - Fill missing months with zeros (default: false)
    * @returns {Promise<Array>} Monthly analytics for the year
    */
-  async getYearByMonth(resourceName, field, year) {
-    return await this.getAnalytics(resourceName, field, {
+  async getYearByMonth(resourceName, field, year, options = {}) {
+    const data = await this.getAnalytics(resourceName, field, {
       period: "month",
       year
     });
+    if (options.fillGaps) {
+      const startDate = `${year}-01`;
+      const endDate = `${year}-12`;
+      return this._fillGaps(data, "month", startDate, endDate);
+    }
+    return data;
   }
   /**
    * Get analytics for entire month, broken down by hours
    * @param {string} resourceName - Resource name
    * @param {string} field - Field name
    * @param {string} month - Month in YYYY-MM format (or 'last' for previous month)
+   * @param {Object} options - Options
+   * @param {boolean} options.fillGaps - Fill missing hours with zeros (default: false)
    * @returns {Promise<Array>} Hourly analytics for the month (up to 24*31=744 records)
    */
-  async getMonthByHour(resourceName, field, month) {
+  async getMonthByHour(resourceName, field, month, options = {}) {
     let year, monthNum;
     if (month === "last") {
       const now = /* @__PURE__ */ new Date();
@@ -5439,11 +5624,15 @@ class EventualConsistencyPlugin extends Plugin {
     const lastDay = new Date(year, monthNum, 0);
     const startDate = firstDay.toISOString().substring(0, 10);
     const endDate = lastDay.toISOString().substring(0, 10);
-    return await this.getAnalytics(resourceName, field, {
+    const data = await this.getAnalytics(resourceName, field, {
       period: "hour",
       startDate,
       endDate
     });
+    if (options.fillGaps) {
+      return this._fillGaps(data, "hour", startDate, endDate);
+    }
+    return data;
   }
   /**
    * Get top records by volume
@@ -11564,7 +11753,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "10.0.4" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "10.0.6" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};