s3db.js 11.0.5 → 11.2.0

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

@@ -18,8 +18,9 @@ import { getCohortInfo, resolveFieldAndPlugin } from "./utils.js";
 export function addHelperMethods(resource, plugin, config) {
   // Add method to set value (replaces current value)
   // Signature: set(id, field, value)
+  // Supports dot notation: set(id, 'utmResults.medium', 10)
   resource.set = async (id, field, value) => {
-    const { plugin: handler } = resolveFieldAndPlugin(resource, field, value);
+    const { field: rootField, fieldPath, plugin: handler } = resolveFieldAndPlugin(resource, field, value);
 
     // Create transaction inline
     const now = new Date();
@@ -29,6 +30,7 @@ export function addHelperMethods(resource, plugin, config) {
       id: idGenerator(),
       originalId: id,
       field: handler.field,
+      fieldPath: fieldPath,  // Store full path for nested access
       value: value,
       operation: 'set',
       timestamp: now.toISOString(),
@@ -43,7 +45,7 @@ export function addHelperMethods(resource, plugin, config) {
 
     // In sync mode, immediately consolidate
     if (config.mode === 'sync') {
-      return await plugin._syncModeConsolidate(handler, id, field);
+      return await plugin._syncModeConsolidate(handler, id, fieldPath);
     }
 
     return value;
@@ -51,8 +53,9 @@ export function addHelperMethods(resource, plugin, config) {
 
   // Add method to increment value
   // Signature: add(id, field, amount)
+  // Supports dot notation: add(id, 'utmResults.medium', 5)
   resource.add = async (id, field, amount) => {
-    const { plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
+    const { field: rootField, fieldPath, plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
 
     // Create transaction inline
     const now = new Date();
@@ -62,6 +65,7 @@ export function addHelperMethods(resource, plugin, config) {
       id: idGenerator(),
       originalId: id,
       field: handler.field,
+      fieldPath: fieldPath,  // Store full path for nested access
       value: amount,
       operation: 'add',
       timestamp: now.toISOString(),
@@ -76,19 +80,25 @@ export function addHelperMethods(resource, plugin, config) {
 
     // In sync mode, immediately consolidate
     if (config.mode === 'sync') {
-      return await plugin._syncModeConsolidate(handler, id, field);
+      return await plugin._syncModeConsolidate(handler, id, fieldPath);
     }
 
     // Async mode - return current value (optimistic)
+    // Note: For nested paths, we need to use lodash get
     const [ok, err, record] = await tryFn(() => handler.targetResource.get(id));
-    const currentValue = (ok && record) ? (record[field] || 0) : 0;
+    if (!ok || !record) return amount;
+
+    // Get current value from nested path
+    const lodash = await import('lodash-es');
+    const currentValue = lodash.get(record, fieldPath, 0);
     return currentValue + amount;
   };
 
   // Add method to decrement value
   // Signature: sub(id, field, amount)
+  // Supports dot notation: sub(id, 'utmResults.medium', 3)
   resource.sub = async (id, field, amount) => {
-    const { plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
+    const { field: rootField, fieldPath, plugin: handler } = resolveFieldAndPlugin(resource, field, amount);
 
     // Create transaction inline
     const now = new Date();
@@ -98,6 +108,7 @@ export function addHelperMethods(resource, plugin, config) {
       id: idGenerator(),
       originalId: id,
       field: handler.field,
+      fieldPath: fieldPath,  // Store full path for nested access
       value: amount,
       operation: 'sub',
       timestamp: now.toISOString(),
@@ -112,12 +123,17 @@ export function addHelperMethods(resource, plugin, config) {
 
     // In sync mode, immediately consolidate
     if (config.mode === 'sync') {
-      return await plugin._syncModeConsolidate(handler, id, field);
+      return await plugin._syncModeConsolidate(handler, id, fieldPath);
     }
 
     // Async mode - return current value (optimistic)
+    // Note: For nested paths, we need to use lodash get
     const [ok, err, record] = await tryFn(() => handler.targetResource.get(id));
-    const currentValue = (ok && record) ? (record[field] || 0) : 0;
+    if (!ok || !record) return -amount;
+
+    // Get current value from nested path
+    const lodash = await import('lodash-es');
+    const currentValue = lodash.get(record, fieldPath, 0);
     return currentValue - amount;
   };
 

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

@@ -95,11 +95,12 @@ export 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',
         cohortDate: 'string|required',
-        cohortHour: 'string|required',
+        cohortHour: 'string|optional',  // ✅ FIX BUG #2: Changed from required to optional for migration compatibility
         cohortWeek: 'string|optional',
         cohortMonth: 'string|optional',
         source: 'string|optional',

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

@@ -160,19 +160,169 @@ export function createFieldHandler(resourceName, fieldName) {
   };
 }
 
+/**
+ * Validate nested path in resource schema
+ * Allows 1 level of nesting after 'json' type fields
+ *
+ * @param {Object} resource - Resource object
+ * @param {string} fieldPath - Dot-notation path (e.g., 'utmResults.medium.google')
+ * @returns {Object} { valid: boolean, rootField: string, fullPath: string, error?: string }
+ */
+export function validateNestedPath(resource, fieldPath) {
+  const parts = fieldPath.split('.');
+  const rootField = parts[0];
+
+  // Root field must exist in resource attributes
+  if (!resource.attributes || !resource.attributes[rootField]) {
+    return {
+      valid: false,
+      rootField,
+      fullPath: fieldPath,
+      error: `Root field "${rootField}" not found in resource attributes`
+    };
+  }
+
+  // If no nesting, just return valid
+  if (parts.length === 1) {
+    return { valid: true, rootField, fullPath: fieldPath };
+  }
+
+  // Validate nested path
+  let current = resource.attributes[rootField];
+  let foundJson = false;
+  let levelsAfterJson = 0;
+
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+
+    // If we found 'json' before, count levels
+    if (foundJson) {
+      levelsAfterJson++;
+      // Only allow 1 level after 'json'
+      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.`
+        };
+      }
+      // After 'json', we can't validate further, but we allow 1 level
+      continue;
+    }
+
+    // Check if current level is 'json' type
+    if (typeof current === 'string') {
+      if (current === 'json' || current.startsWith('json|')) {
+        foundJson = true;
+        levelsAfterJson++;
+        // Allow 1 level after json
+        if (levelsAfterJson > 1) {
+          return {
+            valid: false,
+            rootField,
+            fullPath: fieldPath,
+            error: `Path "${fieldPath}" exceeds 1 level after 'json' field`
+          };
+        }
+        continue;
+      }
+      // Other string types can't be nested
+      return {
+        valid: false,
+        rootField,
+        fullPath: fieldPath,
+        error: `Field "${parts.slice(0, i).join('.')}" is type "${current}" and cannot be nested`
+      };
+    }
+
+    // Check if current is an object with nested structure
+    if (typeof current === 'object') {
+      // Check for $$type
+      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`
+          };
+        }
+      }
+
+      // Navigate to next level
+      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 };
+}
+
 /**
  * Resolve field and plugin from arguments
+ * Supports dot notation for nested fields (e.g., 'utmResults.medium.google')
+ *
  * @param {Object} resource - Resource object
- * @param {string} field - Field name
+ * @param {string} field - Field name or path (supports dot notation)
  * @param {*} value - Value (for error reporting)
- * @returns {Object} Resolved field and plugin handler
- * @throws {Error} If field or plugin not found
+ * @returns {Object} Resolved field, path, and plugin handler
+ * @throws {Error} If field or plugin not found, or path is invalid
  */
 export function resolveFieldAndPlugin(resource, field, value) {
   if (!resource._eventualConsistencyPlugins) {
     throw new Error(`No eventual consistency plugins configured for this resource`);
   }
 
+  // Check if field contains dot notation (nested path)
+  if (field.includes('.')) {
+    const validation = validateNestedPath(resource, field);
+
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+
+    // Get plugin for root field
+    const rootField = validation.rootField;
+    const fieldPlugin = resource._eventualConsistencyPlugins[rootField];
+
+    if (!fieldPlugin) {
+      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: fieldPlugin
+    };
+  }
+
+  // Simple field (no nesting)
   const fieldPlugin = resource._eventualConsistencyPlugins[field];
 
   if (!fieldPlugin) {
@@ -183,7 +333,7 @@ export function resolveFieldAndPlugin(resource, field, value) {
     );
   }
 
-  return { field, value, plugin: fieldPlugin };
+  return { field, fieldPath: field, value, plugin: fieldPlugin };
 }
 
 /**
@@ -205,3 +355,67 @@ export function groupByCohort(transactions, cohortField) {
   }
   return groups;
 }
+
+/**
+ * Ensure transaction has cohortHour field
+ * ✅ FIX BUG #2: Calculate cohortHour from timestamp if missing
+ *
+ * @param {Object} transaction - Transaction to check/fix
+ * @param {string} timezone - Timezone to use for cohort calculation
+ * @param {boolean} verbose - Whether to log warnings
+ * @returns {Object} Transaction with cohortHour populated
+ */
+export function ensureCohortHour(transaction, timezone = 'UTC', verbose = false) {
+  // If cohortHour already exists, return as-is
+  if (transaction.cohortHour) {
+    return transaction;
+  }
+
+  // Calculate cohortHour from timestamp
+  if (transaction.timestamp) {
+    const date = new Date(transaction.timestamp);
+    const cohortInfo = getCohortInfo(date, timezone, verbose);
+
+    if (verbose) {
+      console.log(
+        `[EventualConsistency] Transaction ${transaction.id} missing cohortHour, ` +
+        `calculated from timestamp: ${cohortInfo.hour}`
+      );
+    }
+
+    // Add cohortHour (and other cohort fields if missing)
+    transaction.cohortHour = cohortInfo.hour;
+
+    if (!transaction.cohortWeek) {
+      transaction.cohortWeek = cohortInfo.week;
+    }
+
+    if (!transaction.cohortMonth) {
+      transaction.cohortMonth = cohortInfo.month;
+    }
+  } else if (verbose) {
+    console.warn(
+      `[EventualConsistency] Transaction ${transaction.id} missing both cohortHour and timestamp, ` +
+      `cannot calculate cohort`
+    );
+  }
+
+  return transaction;
+}
+
+/**
+ * Ensure all transactions in array have cohortHour
+ * ✅ FIX BUG #2: Batch version of ensureCohortHour
+ *
+ * @param {Array} transactions - Transactions to check/fix
+ * @param {string} timezone - Timezone to use for cohort calculation
+ * @param {boolean} verbose - Whether to log warnings
+ * @returns {Array} Transactions with cohortHour populated
+ */
+export function ensureCohortHours(transactions, timezone = 'UTC', verbose = false) {
+  if (!transactions || !Array.isArray(transactions)) {
+    return transactions;
+  }
+
+  return transactions.map(txn => ensureCohortHour(txn, timezone, verbose));
+}