s3db.js 11.0.4 → 11.1.0

package/dist/s3db.es.js

@@ -1,10 +1,10 @@
+import crypto, { createHash } from 'crypto';
 import { customAlphabet, urlAlphabet } from 'nanoid';
 import EventEmitter from 'events';
 import { mkdir, copyFile, unlink, stat, access, readdir, writeFile, readFile, rm } from 'fs/promises';
 import fs, { createReadStream, createWriteStream } from 'fs';
 import { pipeline } from 'stream/promises';
 import path, { join } from 'path';
-import crypto, { createHash } from 'crypto';
 import zlib from 'node:zlib';
 import os from 'os';
 import jsonStableStringify from 'json-stable-stringify';
@@ -524,15 +524,7 @@ function tryFnSync(fn) {
 async function dynamicCrypto() {
   let lib;
   if (typeof process !== "undefined") {
-    const [ok, err, result] = await tryFn(async () => {
-      const { webcrypto } = await import('crypto');
-      return webcrypto;
-    });
-    if (ok) {
-      lib = result;
-    } else {
-      throw new CryptoError("Crypto API not available", { original: err, context: "dynamicCrypto" });
-    }
+    lib = crypto.webcrypto;
   } else if (typeof window !== "undefined") {
     lib = window.crypto;
   }
@@ -586,8 +578,7 @@ async function md5(data) {
     throw new CryptoError("MD5 hashing is only available in Node.js environment", { context: "md5" });
   }
   const [ok, err, result] = await tryFn(async () => {
-    const { createHash } = await import('crypto');
-    return createHash("md5").update(data).digest("base64");
+    return crypto.createHash("md5").update(data).digest("base64");
   });
   if (!ok) {
     throw new CryptoError("MD5 hashing failed", { original: err, data });
@@ -5272,10 +5263,121 @@ function createFieldHandler(resourceName, fieldName) {
     deferredSetup: false
   };
 }
+function validateNestedPath(resource, fieldPath) {
+  const parts = fieldPath.split(".");
+  const rootField = parts[0];
+  if (!resource.attributes || !resource.attributes[rootField]) {
+    return {
+      valid: false,
+      rootField,
+      fullPath: fieldPath,
+      error: `Root field "${rootField}" not found in resource attributes`
+    };
+  }
+  if (parts.length === 1) {
+    return { valid: true, rootField, fullPath: fieldPath };
+  }
+  let current = resource.attributes[rootField];
+  let foundJson = false;
+  let levelsAfterJson = 0;
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    if (foundJson) {
+      levelsAfterJson++;
+      if (levelsAfterJson > 1) {
+        return {
+          valid: false,
+          rootField,
+          fullPath: fieldPath,
+          error: `Path "${fieldPath}" exceeds 1 level after 'json' field. Maximum nesting after 'json' is 1 level.`
+        };
+      }
+      continue;
+    }
+    if (typeof current === "string") {
+      if (current === "json" || current.startsWith("json|")) {
+        foundJson = true;
+        levelsAfterJson++;
+        if (levelsAfterJson > 1) {
+          return {
+            valid: false,
+            rootField,
+            fullPath: fieldPath,
+            error: `Path "${fieldPath}" exceeds 1 level after 'json' field`
+          };
+        }
+        continue;
+      }
+      return {
+        valid: false,
+        rootField,
+        fullPath: fieldPath,
+        error: `Field "${parts.slice(0, i).join(".")}" is type "${current}" and cannot be nested`
+      };
+    }
+    if (typeof current === "object") {
+      if (current.$$type) {
+        const type = current.$$type;
+        if (type === "json" || type.includes("json")) {
+          foundJson = true;
+          levelsAfterJson++;
+          continue;
+        }
+        if (type !== "object" && !type.includes("object")) {
+          return {
+            valid: false,
+            rootField,
+            fullPath: fieldPath,
+            error: `Field "${parts.slice(0, i).join(".")}" is type "${type}" and cannot be nested`
+          };
+        }
+      }
+      if (!current[part]) {
+        return {
+          valid: false,
+          rootField,
+          fullPath: fieldPath,
+          error: `Field "${part}" not found in "${parts.slice(0, i).join(".")}"`
+        };
+      }
+      current = current[part];
+    } else {
+      return {
+        valid: false,
+        rootField,
+        fullPath: fieldPath,
+        error: `Invalid structure at "${parts.slice(0, i).join(".")}"`
+      };
+    }
+  }
+  return { valid: true, rootField, fullPath: fieldPath };
+}
 function resolveFieldAndPlugin(resource, field, value) {
   if (!resource._eventualConsistencyPlugins) {
     throw new Error(`No eventual consistency plugins configured for this resource`);
   }
+  if (field.includes(".")) {
+    const validation = validateNestedPath(resource, field);
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+    const rootField = validation.rootField;
+    const fieldPlugin2 = resource._eventualConsistencyPlugins[rootField];
+    if (!fieldPlugin2) {
+      const availableFields = Object.keys(resource._eventualConsistencyPlugins).join(", ");
+      throw new Error(
+        `No eventual consistency plugin found for root field "${rootField}". Available fields: ${availableFields}`
+      );
+    }
+    return {
+      field: rootField,
+      // Root field for plugin lookup
+      fieldPath: field,
+      // Full path for nested access
+      value,
+      plugin: fieldPlugin2
+    };
+  }
   const fieldPlugin = resource._eventualConsistencyPlugins[field];
   if (!fieldPlugin) {
     const availableFields = Object.keys(resource._eventualConsistencyPlugins).join(", ");
@@ -5283,7 +5385,7 @@ function resolveFieldAndPlugin(resource, field, value) {
       `No eventual consistency plugin found for field "${field}". Available fields: ${availableFields}`
     );
   }
-  return { field, value, plugin: fieldPlugin };
+  return { field, fieldPath: field, value, plugin: fieldPlugin };
 }
 function groupByCohort(transactions, cohortField) {
   const groups = {};
@@ -5528,10 +5630,10 @@ async function consolidateRecord(originalId, transactionResource, targetResource
       })
     );
     if (!ok || !transactions || transactions.length === 0) {
-      const [recordOk, recordErr, record] = await tryFn(
+      const [recordOk2, recordErr2, record2] = await tryFn(
         () => targetResource.get(originalId)
       );
-      const currentValue2 = recordOk && record ? record[config.field] || 0 : 0;
+      const currentValue2 = recordOk2 && record2 ? record2[config.field] || 0 : 0;
       if (config.verbose) {
         console.log(
           `[EventualConsistency] ${config.resource}.${config.field} - No pending transactions for ${originalId}, skipping`
@@ -5566,6 +5668,7 @@ async function consolidateRecord(originalId, transactionResource, targetResource
           );
         }
         currentValue = 0;
+        appliedTransactions.length = 0;
       } else {
         appliedTransactions.sort(
           (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
@@ -5573,42 +5676,46 @@ async function consolidateRecord(originalId, transactionResource, targetResource
         const hasSetInApplied = appliedTransactions.some((t) => t.operation === "set");
         if (!hasSetInApplied) {
           const recordValue = recordExists[config.field] || 0;
-          let appliedDelta = 0;
-          for (const t of appliedTransactions) {
-            if (t.operation === "add") appliedDelta += t.value;
-            else if (t.operation === "sub") appliedDelta -= t.value;
-          }
-          const baseValue = recordValue - appliedDelta;
-          const hasExistingAnchor = appliedTransactions.some((t) => t.source === "anchor");
-          if (baseValue !== 0 && !hasExistingAnchor) {
-            const firstTransactionDate = new Date(appliedTransactions[0].timestamp);
-            const cohortInfo = getCohortInfo(firstTransactionDate, config.cohort.timezone, config.verbose);
-            const anchorTransaction = {
-              id: idGenerator(),
-              originalId,
-              field: config.field,
-              value: baseValue,
-              operation: "set",
-              timestamp: new Date(firstTransactionDate.getTime() - 1).toISOString(),
-              // 1ms before first txn to ensure it's first
-              cohortDate: cohortInfo.date,
-              cohortHour: cohortInfo.hour,
-              cohortMonth: cohortInfo.month,
-              source: "anchor",
-              applied: true
-            };
-            await transactionResource.insert(anchorTransaction);
-            appliedTransactions.unshift(anchorTransaction);
+          if (typeof recordValue === "number") {
+            let appliedDelta = 0;
+            for (const t of appliedTransactions) {
+              if (t.operation === "add") appliedDelta += t.value;
+              else if (t.operation === "sub") appliedDelta -= t.value;
+            }
+            const baseValue = recordValue - appliedDelta;
+            const hasExistingAnchor = appliedTransactions.some((t) => t.source === "anchor");
+            if (baseValue !== 0 && typeof baseValue === "number" && !hasExistingAnchor) {
+              const firstTransactionDate = new Date(appliedTransactions[0].timestamp);
+              const cohortInfo = getCohortInfo(firstTransactionDate, config.cohort.timezone, config.verbose);
+              const anchorTransaction = {
+                id: idGenerator(),
+                originalId,
+                field: config.field,
+                fieldPath: config.field,
+                // Add fieldPath for consistency
+                value: baseValue,
+                operation: "set",
+                timestamp: new Date(firstTransactionDate.getTime() - 1).toISOString(),
+                // 1ms before first txn to ensure it's first
+                cohortDate: cohortInfo.date,
+                cohortHour: cohortInfo.hour,
+                cohortMonth: cohortInfo.month,
+                source: "anchor",
+                applied: true
+              };
+              await transactionResource.insert(anchorTransaction);
+              appliedTransactions.unshift(anchorTransaction);
+            }
           }
         }
         currentValue = config.reducer(appliedTransactions);
       }
     } else {
-      const [recordOk, recordErr, record] = await tryFn(
+      const [recordOk2, recordErr2, record2] = await tryFn(
         () => targetResource.get(originalId)
       );
-      currentValue = recordOk && record ? record[config.field] || 0 : 0;
-      if (currentValue !== 0) {
+      currentValue = recordOk2 && record2 ? record2[config.field] || 0 : 0;
+      if (currentValue !== 0 && typeof currentValue === "number") {
         let anchorTimestamp;
         if (transactions && transactions.length > 0) {
           const firstPendingDate = new Date(transactions[0].timestamp);
@@ -5621,6 +5728,8 @@ async function consolidateRecord(originalId, transactionResource, targetResource
           id: idGenerator(),
           originalId,
           field: config.field,
+          fieldPath: config.field,
+          // Add fieldPath for consistency
           value: currentValue,
           operation: "set",
           timestamp: anchorTimestamp,
@@ -5646,38 +5755,101 @@ async function consolidateRecord(originalId, transactionResource, targetResource
     transactions.sort(
       (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
     );
-    const hasSetOperation = transactions.some((t) => t.operation === "set");
-    if (currentValue !== 0 && !hasSetOperation) {
-      transactions.unshift(createSyntheticSetTransaction(currentValue));
+    const transactionsByPath = {};
+    for (const txn of transactions) {
+      const path = txn.fieldPath || txn.field || config.field;
+      if (!transactionsByPath[path]) {
+        transactionsByPath[path] = [];
+      }
+      transactionsByPath[path].push(txn);
     }
-    const consolidatedValue = config.reducer(transactions);
-    if (config.verbose) {
-      console.log(
-        `[EventualConsistency] ${config.resource}.${config.field} - ${originalId}: ${currentValue} \u2192 ${consolidatedValue} (${consolidatedValue > currentValue ? "+" : ""}${consolidatedValue - currentValue})`
-      );
+    const appliedByPath = {};
+    if (appliedOk && appliedTransactions && appliedTransactions.length > 0) {
+      for (const txn of appliedTransactions) {
+        const path = txn.fieldPath || txn.field || config.field;
+        if (!appliedByPath[path]) {
+          appliedByPath[path] = [];
+        }
+        appliedByPath[path].push(txn);
+      }
+    }
+    const consolidatedValues = {};
+    const lodash = await import('lodash-es');
+    const [currentRecordOk, currentRecordErr, currentRecord] = await tryFn(
+      () => targetResource.get(originalId)
+    );
+    for (const [fieldPath, pathTransactions] of Object.entries(transactionsByPath)) {
+      let pathCurrentValue = 0;
+      if (appliedByPath[fieldPath] && appliedByPath[fieldPath].length > 0) {
+        appliedByPath[fieldPath].sort(
+          (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+        );
+        pathCurrentValue = config.reducer(appliedByPath[fieldPath]);
+      } else {
+        if (currentRecordOk && currentRecord) {
+          const recordValue = lodash.get(currentRecord, fieldPath, 0);
+          if (typeof recordValue === "number") {
+            pathCurrentValue = recordValue;
+          }
+        }
+      }
+      if (pathCurrentValue !== 0) {
+        pathTransactions.unshift(createSyntheticSetTransaction(pathCurrentValue));
+      }
+      const pathConsolidatedValue = config.reducer(pathTransactions);
+      consolidatedValues[fieldPath] = pathConsolidatedValue;
+      if (config.verbose) {
+        console.log(
+          `[EventualConsistency] ${config.resource}.${fieldPath} - ${originalId}: ${pathCurrentValue} \u2192 ${pathConsolidatedValue} (${pathTransactions.length - (pathCurrentValue !== 0 ? 1 : 0)} pending txns)`
+        );
+      }
     }
     if (config.verbose) {
       console.log(
         `\u{1F525} [DEBUG] BEFORE targetResource.update() {
   originalId: '${originalId}',
-  field: '${config.field}',
-  consolidatedValue: ${consolidatedValue},
-  currentValue: ${currentValue}
+  consolidatedValues: ${JSON.stringify(consolidatedValues, null, 2)}
 }`
       );
     }
-    const [updateOk, updateErr, updateResult] = await tryFn(
-      () => targetResource.update(originalId, {
-        [config.field]: consolidatedValue
-      })
+    const [recordOk, recordErr, record] = await tryFn(
+      () => targetResource.get(originalId)
     );
+    let updateOk, updateErr, updateResult;
+    if (!recordOk || !record) {
+      if (config.verbose) {
+        console.log(
+          `[EventualConsistency] ${config.resource}.${config.field} - Record ${originalId} doesn't exist yet. Will attempt update anyway (expected to fail).`
+        );
+      }
+      const minimalRecord = { id: originalId };
+      for (const [fieldPath, value] of Object.entries(consolidatedValues)) {
+        lodash.set(minimalRecord, fieldPath, value);
+      }
+      const result = await tryFn(
+        () => targetResource.update(originalId, minimalRecord)
+      );
+      updateOk = result[0];
+      updateErr = result[1];
+      updateResult = result[2];
+    } else {
+      for (const [fieldPath, value] of Object.entries(consolidatedValues)) {
+        lodash.set(record, fieldPath, value);
+      }
+      const result = await tryFn(
+        () => targetResource.update(originalId, record)
+      );
+      updateOk = result[0];
+      updateErr = result[1];
+      updateResult = result[2];
+    }
+    const consolidatedValue = consolidatedValues[config.field] || (record ? lodash.get(record, config.field, 0) : 0);
     if (config.verbose) {
       console.log(
         `\u{1F525} [DEBUG] AFTER targetResource.update() {
   updateOk: ${updateOk},
   updateErr: ${updateErr?.message || "undefined"},
-  updateResult: ${JSON.stringify(updateResult, null, 2)},
-  hasField: ${updateResult?.[config.field]}
+  consolidatedValue (main field): ${consolidatedValue}
 }`
       );
     }
@@ -5685,24 +5857,27 @@ async function consolidateRecord(originalId, transactionResource, targetResource
       const [verifyOk, verifyErr, verifiedRecord] = await tryFn(
         () => targetResource.get(originalId, { skipCache: true })
       );
-      console.log(
-        `\u{1F525} [DEBUG] VERIFICATION (fresh from S3, no cache) {
-  verifyOk: ${verifyOk},
-  verifiedRecord[${config.field}]: ${verifiedRecord?.[config.field]},
-  expectedValue: ${consolidatedValue},
-  \u2705 MATCH: ${verifiedRecord?.[config.field] === consolidatedValue}
+      for (const [fieldPath, expectedValue] of Object.entries(consolidatedValues)) {
+        const actualValue = lodash.get(verifiedRecord, fieldPath);
+        const match = actualValue === expectedValue;
+        console.log(
+          `\u{1F525} [DEBUG] VERIFICATION ${fieldPath} {
+  expectedValue: ${expectedValue},
+  actualValue: ${actualValue},
+  ${match ? "\u2705 MATCH" : "\u274C MISMATCH"}
 }`
-      );
-      if (verifyOk && verifiedRecord?.[config.field] !== consolidatedValue) {
-        console.error(
-          `\u274C [CRITICAL BUG] Update reported success but value not persisted!
+        );
+        if (!match) {
+          console.error(
+            `\u274C [CRITICAL BUG] Update reported success but value not persisted!
   Resource: ${config.resource}
-  Field: ${config.field}
+  FieldPath: ${fieldPath}
   Record ID: ${originalId}
-  Expected: ${consolidatedValue}
-  Actually got: ${verifiedRecord?.[config.field]}
+  Expected: ${expectedValue}
+  Actually got: ${actualValue}
   This indicates a bug in s3db.js resource.update()`
-        );
+          );
+        }
       }
     }
     if (!updateOk) {
@@ -5887,6 +6062,38 @@ async function recalculateRecord(originalId, transactionResource, targetResource
         `[EventualConsistency] ${config.resource}.${config.field} - Found ${allTransactions.length} total transactions for ${originalId}, marking all as pending...`
       );
     }
+    const hasAnchor = allTransactions.some((txn) => txn.source === "anchor");
+    if (!hasAnchor) {
+      const now = /* @__PURE__ */ new Date();
+      const cohortInfo = getCohortInfo(now, config.cohort.timezone, config.verbose);
+      const oldestTransaction = allTransactions.sort(
+        (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+      )[0];
+      const anchorTimestamp = oldestTransaction ? new Date(new Date(oldestTransaction.timestamp).getTime() - 1).toISOString() : now.toISOString();
+      const anchorCohortInfo = getCohortInfo(new Date(anchorTimestamp), config.cohort.timezone, config.verbose);
+      const anchorTransaction = {
+        id: idGenerator(),
+        originalId,
+        field: config.field,
+        fieldPath: config.field,
+        value: 0,
+        // Always 0 for recalculate - we start from scratch
+        operation: "set",
+        timestamp: anchorTimestamp,
+        cohortDate: anchorCohortInfo.date,
+        cohortHour: anchorCohortInfo.hour,
+        cohortMonth: anchorCohortInfo.month,
+        source: "anchor",
+        applied: true
+        // Anchor is always applied
+      };
+      await transactionResource.insert(anchorTransaction);
+      if (config.verbose) {
+        console.log(
+          `[EventualConsistency] ${config.resource}.${config.field} - Created anchor transaction for ${originalId} with value 0`
+        );
+      }
+    }
     const transactionsToReset = allTransactions.filter((txn) => txn.source !== "anchor");
     const { results, errors } = await PromisePool.for(transactionsToReset).withConcurrency(10).process(async (txn) => {
       const [ok, err] = await tryFn(
@@ -6514,16 +6721,151 @@ async function getTopRecords(resourceName, field, options, fieldHandlers) {
   });
   return records.slice(0, limit);
 }
+async function getYearByDay(resourceName, field, year, options, fieldHandlers) {
+  const startDate = `${year}-01-01`;
+  const endDate = `${year}-12-31`;
+  const data = await getAnalytics(resourceName, field, {
+    period: "day",
+    startDate,
+    endDate
+  }, fieldHandlers);
+  if (options.fillGaps) {
+    return fillGaps(data, "day", startDate, endDate);
+  }
+  return data;
+}
+async function getWeekByDay(resourceName, field, week, options, fieldHandlers) {
+  const year = parseInt(week.substring(0, 4));
+  const weekNum = parseInt(week.substring(6, 8));
+  const jan4 = new Date(Date.UTC(year, 0, 4));
+  const jan4Day = jan4.getUTCDay() || 7;
+  const firstMonday = new Date(Date.UTC(year, 0, 4 - jan4Day + 1));
+  const weekStart = new Date(firstMonday);
+  weekStart.setUTCDate(weekStart.getUTCDate() + (weekNum - 1) * 7);
+  const days = [];
+  for (let i = 0; i < 7; i++) {
+    const day = new Date(weekStart);
+    day.setUTCDate(weekStart.getUTCDate() + i);
+    days.push(day.toISOString().substring(0, 10));
+  }
+  const startDate = days[0];
+  const endDate = days[6];
+  const data = await getAnalytics(resourceName, field, {
+    period: "day",
+    startDate,
+    endDate
+  }, fieldHandlers);
+  if (options.fillGaps) {
+    return fillGaps(data, "day", startDate, endDate);
+  }
+  return data;
+}
+async function getWeekByHour(resourceName, field, week, options, fieldHandlers) {
+  const year = parseInt(week.substring(0, 4));
+  const weekNum = parseInt(week.substring(6, 8));
+  const jan4 = new Date(Date.UTC(year, 0, 4));
+  const jan4Day = jan4.getUTCDay() || 7;
+  const firstMonday = new Date(Date.UTC(year, 0, 4 - jan4Day + 1));
+  const weekStart = new Date(firstMonday);
+  weekStart.setUTCDate(weekStart.getUTCDate() + (weekNum - 1) * 7);
+  const weekEnd = new Date(weekStart);
+  weekEnd.setUTCDate(weekEnd.getUTCDate() + 6);
+  const startDate = weekStart.toISOString().substring(0, 10);
+  const endDate = weekEnd.toISOString().substring(0, 10);
+  const data = await getAnalytics(resourceName, field, {
+    period: "hour",
+    startDate,
+    endDate
+  }, fieldHandlers);
+  if (options.fillGaps) {
+    return fillGaps(data, "hour", startDate, endDate);
+  }
+  return data;
+}
+async function getLastNHours(resourceName, field, hours = 24, options, fieldHandlers) {
+  const now = /* @__PURE__ */ new Date();
+  const hoursAgo = new Date(now);
+  hoursAgo.setHours(hoursAgo.getHours() - hours + 1);
+  const startHour = hoursAgo.toISOString().substring(0, 13);
+  const endHour = now.toISOString().substring(0, 13);
+  const data = await getAnalytics(resourceName, field, {
+    period: "hour",
+    startDate: startHour,
+    endDate: endHour
+  }, fieldHandlers);
+  if (options.fillGaps) {
+    const result = [];
+    const emptyRecord = { count: 0, sum: 0, avg: 0, min: 0, max: 0, recordCount: 0 };
+    const dataMap = new Map(data.map((d) => [d.cohort, d]));
+    const current = new Date(hoursAgo);
+    for (let i = 0; i < hours; i++) {
+      const cohort = current.toISOString().substring(0, 13);
+      result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+      current.setHours(current.getHours() + 1);
+    }
+    return result;
+  }
+  return data;
+}
+async function getLastNWeeks(resourceName, field, weeks = 4, options, fieldHandlers) {
+  const now = /* @__PURE__ */ new Date();
+  const weeksAgo = new Date(now);
+  weeksAgo.setDate(weeksAgo.getDate() - weeks * 7);
+  const weekCohorts = [];
+  const currentDate = new Date(weeksAgo);
+  while (currentDate <= now) {
+    const weekCohort = getCohortWeekFromDate(currentDate);
+    if (!weekCohorts.includes(weekCohort)) {
+      weekCohorts.push(weekCohort);
+    }
+    currentDate.setDate(currentDate.getDate() + 7);
+  }
+  const startWeek = weekCohorts[0];
+  const endWeek = weekCohorts[weekCohorts.length - 1];
+  const data = await getAnalytics(resourceName, field, {
+    period: "week",
+    startDate: startWeek,
+    endDate: endWeek
+  }, fieldHandlers);
+  return data;
+}
+async function getLastNMonths(resourceName, field, months = 12, options, fieldHandlers) {
+  const now = /* @__PURE__ */ new Date();
+  const monthsAgo = new Date(now);
+  monthsAgo.setMonth(monthsAgo.getMonth() - months + 1);
+  const startDate = monthsAgo.toISOString().substring(0, 7);
+  const endDate = now.toISOString().substring(0, 7);
+  const data = await getAnalytics(resourceName, field, {
+    period: "month",
+    startDate,
+    endDate
+  }, fieldHandlers);
+  if (options.fillGaps) {
+    const result = [];
+    const emptyRecord = { count: 0, sum: 0, avg: 0, min: 0, max: 0, recordCount: 0 };
+    const dataMap = new Map(data.map((d) => [d.cohort, d]));
+    const current = new Date(monthsAgo);
+    for (let i = 0; i < months; i++) {
+      const cohort = current.toISOString().substring(0, 7);
+      result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });
+      current.setMonth(current.getMonth() + 1);
+    }
+    return result;
+  }
+  return data;
+}
 
 function addHelperMethods(resource, plugin, config) {
   resource.set = async (id, field, value) => {
-    const { plugin: handler } = resolveFieldAndPlugin(resource, field, value);
+    const { field: rootField, fieldPath, plugin: handler } = resolveFieldAndPlugin(resource, field, value);
     const now = /* @__PURE__ */ new Date();
     const cohortInfo = getCohortInfo(now, config.cohort.timezone, config.verbose);
     const transaction = {
       id: idGenerator(),
       originalId: id,
       field: handler.field,
+      fieldPath,
+      // Store full path for nested access
       value,
       operation: "set",
       timestamp: now.toISOString(),
@@ -6535,18 +6877,20 @@ function addHelperMethods(resource, plugin, config) {
     };
     await handler.transactionResource.insert(transaction);
     if (config.mode === "sync") {
-      return await plugin._syncModeConsolidate(handler, id, field);
+      return await plugin._syncModeConsolidate(handler, id, fieldPath);
     }
     return value;
   };
   resource.add = async (id, field, amount) => {
-    const { plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
+    const { field: rootField, fieldPath, plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
     const now = /* @__PURE__ */ new Date();
     const cohortInfo = getCohortInfo(now, config.cohort.timezone, config.verbose);
     const transaction = {
       id: idGenerator(),
       originalId: id,
       field: handler.field,
+      fieldPath,
+      // Store full path for nested access
       value: amount,
       operation: "add",
       timestamp: now.toISOString(),
@@ -6558,20 +6902,24 @@ function addHelperMethods(resource, plugin, config) {
     };
     await handler.transactionResource.insert(transaction);
     if (config.mode === "sync") {
-      return await plugin._syncModeConsolidate(handler, id, field);
+      return await plugin._syncModeConsolidate(handler, id, fieldPath);
     }
     const [ok, err, record] = await tryFn(() => handler.targetResource.get(id));
-    const currentValue = ok && record ? record[field] || 0 : 0;
+    if (!ok || !record) return amount;
+    const lodash = await import('lodash-es');
+    const currentValue = lodash.get(record, fieldPath, 0);
     return currentValue + amount;
   };
   resource.sub = async (id, field, amount) => {
-    const { plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
+    const { field: rootField, fieldPath, plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
     const now = /* @__PURE__ */ new Date();
     const cohortInfo = getCohortInfo(now, config.cohort.timezone, config.verbose);
     const transaction = {
       id: idGenerator(),
       originalId: id,
       field: handler.field,
+      fieldPath,
+      // Store full path for nested access
       value: amount,
       operation: "sub",
       timestamp: now.toISOString(),
@@ -6583,10 +6931,12 @@ function addHelperMethods(resource, plugin, config) {
     };
     await handler.transactionResource.insert(transaction);
     if (config.mode === "sync") {
-      return await plugin._syncModeConsolidate(handler, id, field);
+      return await plugin._syncModeConsolidate(handler, id, fieldPath);
     }
     const [ok, err, record] = await tryFn(() => handler.targetResource.get(id));
-    const currentValue = ok && record ? record[field] || 0 : 0;
+    if (!ok || !record) return -amount;
+    const lodash = await import('lodash-es');
+    const currentValue = lodash.get(record, fieldPath, 0);
     return currentValue - amount;
   };
   resource.consolidate = async (id, field) => {
@@ -6672,6 +7022,8 @@ async function completeFieldSetup(handler, database, config, plugin) {
         id: "string|required",
         originalId: "string|required",
         field: "string|required",
+        fieldPath: "string|optional",
+        // Support for nested field paths (e.g., 'utmResults.medium')
         value: "number|required",
         operation: "string|required",
         timestamp: "string|required",
@@ -7170,6 +7522,72 @@ class EventualConsistencyPlugin extends Plugin {
   async getTopRecords(resourceName, field, options = {}) {
     return await getTopRecords(resourceName, field, options, this.fieldHandlers);
   }
+  /**
+   * Get analytics for entire year, broken down by days
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} year - Year (e.g., 2025)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Daily analytics for the year (up to 365/366 records)
+   */
+  async getYearByDay(resourceName, field, year, options = {}) {
+    return await getYearByDay(resourceName, field, year, options, this.fieldHandlers);
+  }
+  /**
+   * Get analytics for entire week, broken down by days
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {string} week - Week in YYYY-Www format (e.g., '2025-W42')
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Daily analytics for the week (7 records)
+   */
+  async getWeekByDay(resourceName, field, week, options = {}) {
+    return await getWeekByDay(resourceName, field, week, options, this.fieldHandlers);
+  }
+  /**
+   * Get analytics for entire week, broken down by hours
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {string} week - Week in YYYY-Www format (e.g., '2025-W42')
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Hourly analytics for the week (168 records)
+   */
+  async getWeekByHour(resourceName, field, week, options = {}) {
+    return await getWeekByHour(resourceName, field, week, options, this.fieldHandlers);
+  }
+  /**
+   * Get analytics for last N hours
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} hours - Number of hours to look back (default: 24)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Hourly analytics
+   */
+  async getLastNHours(resourceName, field, hours = 24, options = {}) {
+    return await getLastNHours(resourceName, field, hours, options, this.fieldHandlers);
+  }
+  /**
+   * Get analytics for last N weeks
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} weeks - Number of weeks to look back (default: 4)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Weekly analytics
+   */
+  async getLastNWeeks(resourceName, field, weeks = 4, options = {}) {
+    return await getLastNWeeks(resourceName, field, weeks, options, this.fieldHandlers);
+  }
+  /**
+   * Get analytics for last N months
+   * @param {string} resourceName - Resource name
+   * @param {string} field - Field name
+   * @param {number} months - Number of months to look back (default: 12)
+   * @param {Object} options - Options
+   * @returns {Promise<Array>} Monthly analytics
+   */
+  async getLastNMonths(resourceName, field, months = 12, options = {}) {
+    return await getLastNMonths(resourceName, field, months, options, this.fieldHandlers);
+  }
 }
 
 class FullTextPlugin extends Plugin {
@@ -13188,7 +13606,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.0.4" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.1.0" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};