jw-automator 3.1.0 → 4.0.0

package/src/Automator.js

@@ -35,6 +35,33 @@ class Automator {
     this._loadState();
   }
 
+  /**
+   * Seed the automator with initial actions (runs only on first use)
+   *
+   * @param {Function} callback - Function to execute when database is empty
+   * @returns {boolean} - True if seeding ran, false if skipped
+   */
+  seed(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('seed() requires a callback function');
+    }
+
+    const state = this.host.getState();
+
+    // Check if already populated
+    if (state.actions && state.actions.length > 0) {
+      return false;
+    }
+
+    // Execute seeding callback
+    callback(this);
+
+    // Immediately save the seeded state
+    this._saveState();
+
+    return true;
+  }
+
   /**
    * Start the automator
    */
@@ -83,17 +110,33 @@ class Automator {
    * Add an action
    */
   addAction(actionSpec) {
-    // Validate action
+    // Validate action (includes defensive coercion)
     this._validateAction(actionSpec);
 
+    // Normalize catchUpWindow (handles backwards compatibility with unBuffered)
+    const catchUpWindow = this._normalizeCatchUpWindow(actionSpec);
+
+    // Defensive: Default missing date to 5 seconds from now
+    let startDate;
+    if (!actionSpec.date) {
+      startDate = new Date(Date.now() + 5000);
+      this._emit('debug', {
+        type: 'debug',
+        message: 'No date provided - defaulting to 5 seconds from now'
+      });
+    } else {
+      startDate = new Date(actionSpec.date);
+    }
+
     // Create action with state
     const action = {
       id: this.nextId++,
       name: actionSpec.name || null,
       cmd: actionSpec.cmd,
       payload: actionSpec.payload !== undefined ? actionSpec.payload : null,
-      date: actionSpec.date ? new Date(actionSpec.date) : new Date(),
-      unBuffered: actionSpec.unBuffered || false,
+      date: startDate,
+      unBuffered: actionSpec.unBuffered !== undefined ? actionSpec.unBuffered : false,
+      catchUpWindow: catchUpWindow,
       repeat: actionSpec.repeat ? { ...actionSpec.repeat } : null,
       count: 0
     };
@@ -130,7 +173,7 @@ class Automator {
     }
 
     // Update allowed fields
-    const allowedUpdates = ['name', 'cmd', 'payload', 'date', 'unBuffered', 'repeat', 'count'];
+    const allowedUpdates = ['name', 'cmd', 'payload', 'date', 'unBuffered', 'catchUpWindow', 'repeat', 'count'];
 
     for (const key of allowedUpdates) {
       if (key in updates) {
@@ -147,6 +190,11 @@ class Automator {
       }
     }
 
+    // Re-normalize catchUpWindow if unBuffered or catchUpWindow was updated
+    if ('unBuffered' in updates || 'catchUpWindow' in updates) {
+      action.catchUpWindow = this._normalizeCatchUpWindow(action);
+    }
+
     this._emit('update', {
       type: 'update',
       operation: 'update',
@@ -173,7 +221,7 @@ class Automator {
       return 0;
     }
 
-    const allowedUpdates = ['cmd', 'payload', 'date', 'unBuffered', 'repeat', 'count'];
+    const allowedUpdates = ['cmd', 'payload', 'date', 'unBuffered', 'catchUpWindow', 'repeat', 'count'];
 
     for (const action of toUpdate) {
       for (const key of allowedUpdates) {
@@ -191,6 +239,11 @@ class Automator {
         }
       }
 
+      // Re-normalize catchUpWindow if unBuffered or catchUpWindow was updated
+      if ('unBuffered' in updates || 'catchUpWindow' in updates) {
+        action.catchUpWindow = this._normalizeCatchUpWindow(action);
+      }
+
       this._emit('update', {
         type: 'update',
         operation: 'update',
@@ -263,12 +316,31 @@ class Automator {
     return toRemove.length;
   }
 
+  /**
+   * Deep clone an action
+   */
+  _cloneAction(action) {
+    const cloned = { ...action };
+
+    // Deep copy nested objects
+    if (action.repeat) {
+      cloned.repeat = { ...action.repeat };
+    }
+
+    // Clone Date objects properly
+    if (action.date) {
+      cloned.date = new Date(action.date);
+    }
+
+    return cloned;
+  }
+
   /**
    * Get all actions (deep copy)
    */
   getActions() {
     const state = this.host.getState();
-    return JSON.parse(JSON.stringify(state.actions));
+    return state.actions.map(a => this._cloneAction(a));
   }
 
   /**
@@ -278,7 +350,7 @@ class Automator {
     const state = this.host.getState();
     return state.actions
       .filter(a => a.name === name)
-      .map(a => JSON.parse(JSON.stringify(a)));
+      .map(a => this._cloneAction(a));
   }
 
   /**
@@ -287,7 +359,7 @@ class Automator {
   getActionByID(id) {
     const state = this.host.getState();
     const action = state.actions.find(a => a.id === id);
-    return action ? JSON.parse(JSON.stringify(action)) : null;
+    return action ? this._cloneAction(action) : null;
   }
 
   /**
@@ -393,13 +465,21 @@ class Automator {
   _loadState() {
     try {
       const state = this.options.storage.load();
-      this.host.setState(state);
 
-      // Update nextId to be higher than any existing ID
+      // Normalize catchUpWindow for existing actions (for backwards compatibility)
       if (state.actions && state.actions.length > 0) {
+        state.actions = state.actions.map(action => ({
+          ...action,
+          catchUpWindow: action.catchUpWindow !== undefined
+            ? action.catchUpWindow
+            : this._normalizeCatchUpWindow(action)
+        }));
+
         const maxId = Math.max(...state.actions.map(a => a.id || 0));
         this.nextId = maxId + 1;
       }
+
+      this.host.setState(state);
     } catch (error) {
       this._emit('error', {
         type: 'error',
@@ -438,8 +518,88 @@ class Automator {
     }, this.options.saveInterval);
   }
 
+
+  /**
+   * Calculate interval in milliseconds from a repeat spec.
+   * Note: Uses approximations for month/year, as this is for a default
+   * catch-up window, not for precise scheduling.
+   *
+   * @param {object} repeat
+   * @returns {number}
+   * @private
+   */
+  _getIntervalMilliseconds(repeat) {
+    const interval = repeat.interval || 1;
+    switch (repeat.type) {
+      case 'second':
+        return interval * 1000;
+      case 'minute':
+        return interval * 60 * 1000;
+      case 'hour':
+        return interval * 60 * 60 * 1000;
+      case 'day':
+      case 'weekday': // Approximated as 1 day for catch-up purposes
+      case 'weekend': // Approximated as 1 day for catch-up purposes
+        return interval * 24 * 60 * 60 * 1000;
+      case 'week':
+        return interval * 7 * 24 * 60 * 60 * 1000;
+      case 'month':
+        // A reasonable approximation for a default is 30 days
+        return interval * 30 * 24 * 60 * 60 * 1000;
+      case 'year':
+        // A reasonable approximation for a default is 365 days
+        return interval * 365 * 24 * 60 * 60 * 1000;
+      default:
+        // Fallback for an invalid type that slipped past validation
+        return 60000; // 1 minute
+    }
+  }
+
+  /**
+   * Normalize catchUpWindow property (handles backwards compatibility with unBuffered)
+   *
+   * Priority:
+   * 1. catchUpWindow specified → normalize it (coerce Infinity to "unlimited" if needed)
+   * 2. unBuffered specified → convert to catchUpWindow equivalent
+   * 3. Neither specified → default to "unlimited" (catch up everything)
+   *
+   * @param {Object} spec - Action specification
+   * @returns {string|number} - Normalized catchUpWindow value ("unlimited" or milliseconds)
+   */
+  _normalizeCatchUpWindow(spec) {
+    // 1. New property takes precedence
+    if (spec.catchUpWindow !== undefined) {
+      // Coerce Infinity to "unlimited" (backwards compatibility)
+      if (spec.catchUpWindow === Infinity) {
+        this._emit('debug', {
+          type: 'debug',
+          message: 'Coercing catchUpWindow: Infinity → "unlimited"'
+        });
+        return "unlimited";
+      }
+      return spec.catchUpWindow;
+    }
+
+    // 2. Backwards compatibility mapping for legacy 'unBuffered'
+    if (spec.unBuffered !== undefined) {
+      return spec.unBuffered ? 0 : "unlimited";
+    }
+
+    // 3. For recurring actions, default to the interval duration
+    if (spec.repeat) {
+      return this._getIntervalMilliseconds(spec.repeat);
+    }
+
+    // 4. For one-time actions, default to 0 (no catch-up)
+    return 0;
+  }
+
   /**
-   * Validate action specification
+   * Validate and normalize action specification
+   * Philosophy: "Fail loudly, run defensively"
+   * - Emit ERROR events for serious issues but coerce to reasonable defaults
+   * - Emit DEBUG events for auto-corrections
+   * - Never silently fail
    */
   _validateAction(action) {
     if (!action.cmd) {
@@ -448,16 +608,86 @@ class Automator {
 
     if (action.repeat) {
       const validTypes = ['second', 'minute', 'hour', 'day', 'weekday', 'weekend', 'week', 'month', 'year'];
-      if (!validTypes.includes(action.repeat.type)) {
-        throw new Error(`Invalid repeat type: ${action.repeat.type}`);
+
+      // CRITICAL: An invalid repeat.type is a fatal error, as intent is lost.
+      if (!action.repeat.type || !validTypes.includes(action.repeat.type)) {
+        throw new Error(`Invalid repeat.type "${action.repeat.type}". Must be one of: ${validTypes.join(', ')}`);
       }
 
-      if (action.repeat.interval !== undefined && action.repeat.interval < 1) {
-        throw new Error('Repeat interval must be >= 1');
+      // Defensive: Coerce invalid interval to Math.max(1, Math.floor(value))
+      if (action.repeat.interval !== undefined) {
+        const original = action.repeat.interval;
+        const coerced = Math.max(1, Math.floor(original));
+        if (original !== coerced) {
+          this._emit('warning', {
+            type: 'warning',
+            message: `Invalid repeat.interval ${original} - coerced to ${coerced}`,
+            actionSpec: action
+          });
+          action.repeat.interval = coerced;
+        }
       }
 
+      // Defensive: Validate dstPolicy
       if (action.repeat.dstPolicy && !['once', 'twice'].includes(action.repeat.dstPolicy)) {
-        throw new Error('DST policy must be "once" or "twice"');
+        this._emit('warning', {
+          type: 'warning',
+          message: `Invalid dstPolicy "${action.repeat.dstPolicy}" - defaulting to "once"`,
+          actionSpec: action
+        });
+        action.repeat.dstPolicy = 'once';
+      }
+
+      // Defensive: Coerce invalid repeat.limit to null (unlimited) with WARNING event
+      if (action.repeat.limit !== undefined && action.repeat.limit !== null) {
+        if (typeof action.repeat.limit !== 'number' || action.repeat.limit < 1) {
+          this._emit('warning', {
+            type: 'warning',
+            message: `Invalid repeat.limit ${action.repeat.limit} - defaulting to null (unlimited)`,
+            actionSpec: action
+          });
+          action.repeat.limit = null;
+        }
+      }
+
+      // Defensive: Validate repeat.endDate
+      if (action.repeat.endDate !== undefined && action.repeat.endDate !== null) {
+        try {
+          new Date(action.repeat.endDate);
+        } catch (e) {
+          this._emit('warning', {
+            type: 'warning',
+            message: `Invalid repeat.endDate - ignoring`,
+            actionSpec: action
+          });
+          action.repeat.endDate = null;
+        }
+      }
+    }
+
+    // Defensive: Validate catchUpWindow if provided
+    if (action.catchUpWindow !== undefined) {
+      const isValidString = action.catchUpWindow === "unlimited";
+      const isNumber = typeof action.catchUpWindow === 'number';
+      const isInfinity = action.catchUpWindow === Infinity; // Allow for backwards compatibility
+
+      // Coerce negative numbers to 0 FIRST
+      if (isNumber && action.catchUpWindow < 0) {
+        this._emit('warning', {
+          type: 'warning',
+          message: `Negative catchUpWindow ${action.catchUpWindow} - coerced to 0`,
+          actionSpec: action
+        });
+        action.catchUpWindow = 0;
+      }
+      // Then validate it's a valid value
+      else if (!isValidString && !isNumber && !isInfinity) {
+        this._emit('warning', {
+          type: 'warning',
+          message: `Invalid catchUpWindow "${action.catchUpWindow}" - defaulting to "unlimited"`,
+          actionSpec: action
+        });
+        action.catchUpWindow = "unlimited";
       }
     }
   }

package/src/core/CoreEngine.js

@@ -52,14 +52,47 @@ class CoreEngine {
       let iterationCount = 0;
       let currentNextRun = nextRun;
 
+      // Get catchUpWindow (defaults to "unlimited" for backwards compatibility)
+      const catchUpWindow = action.catchUpWindow !== undefined ? action.catchUpWindow : "unlimited";
+
+      // Fast-forward optimization: if we're far outside the catch-up window,
+      // jump directly to near the current time using mathematical projection
+      if (catchUpWindow !== "unlimited" && action.repeat) {
+        const lag = now.getTime() - currentNextRun.getTime();
+
+        if (lag > catchUpWindow * 2) {
+          // We're deep in the "Dead Zone" - use fast-forward
+          const fastForwardResult = this._fastForwardAction(action, now, catchUpWindow);
+
+          if (fastForwardResult) {
+            currentNextRun = fastForwardResult.nextRun;
+            action.date = currentNextRun;
+            action.count = fastForwardResult.count;
+
+            // After fast-forward, if still outside window, just advance without executing
+            if (currentNextRun <= now) {
+              const finalLag = now.getTime() - currentNextRun.getTime();
+              if (finalLag > catchUpWindow) {
+                // Still outside window after fast-forward, skip to next viable occurrence
+                this._advanceAction(action);
+                currentNextRun = action.date ? new Date(action.date) : null;
+              }
+            }
+          }
+        }
+      }
+
       while (currentNextRun <= now && iterationCount < maxIterations) {
         iterationCount++;
 
-        // Determine if we should execute this occurrence
-        // UnBuffered: only execute if this is the actual current tick (not catching up)
-        // Buffered: execute all missed occurrences
+        const lag = now.getTime() - currentNextRun.getTime();
+
+        // Determine if we should execute this occurrence based on catchUpWindow
         const isInCurrentTick = currentNextRun > lastTick && currentNextRun <= now;
-        const shouldExecute = action.unBuffered ? isInCurrentTick : true;
+        const isWithinWindow = catchUpWindow === "unlimited" || lag <= catchUpWindow;
+
+        // Legacy unBuffered behavior (maps to catchUpWindow: 0 or Infinity)
+        const shouldExecute = isWithinWindow;
 
         if (shouldExecute) {
           const event = this._executeAction(action, currentNextRun);
@@ -168,6 +201,77 @@ class CoreEngine {
     }
   }
 
+  /**
+   * Fast-forward an action to near the current time using mathematical projection
+   * This avoids iterating through thousands/millions of occurrences for high-frequency tasks
+   *
+   * @param {Object} action - The action to fast-forward
+   * @param {Date} now - Current time
+   * @param {number} catchUpWindow - The catch-up window in milliseconds
+   * @returns {Object|null} - { nextRun, count } or null if not applicable
+   */
+  static _fastForwardAction(action, now, catchUpWindow) {
+    if (!action.repeat || !action.date) {
+      return null;
+    }
+
+    const { type, interval = 1 } = action.repeat;
+    const currentTime = new Date(action.date);
+    const lag = now.getTime() - currentTime.getTime();
+
+    // Only applicable for simple time-based recurrence (not weekday/weekend)
+    let stepMilliseconds = 0;
+
+    switch (type) {
+      case 'second':
+        stepMilliseconds = interval * 1000;
+        break;
+      case 'minute':
+        stepMilliseconds = interval * 60 * 1000;
+        break;
+      case 'hour':
+        stepMilliseconds = interval * 60 * 60 * 1000;
+        break;
+      case 'day':
+        stepMilliseconds = interval * 24 * 60 * 60 * 1000;
+        break;
+      case 'week':
+        stepMilliseconds = interval * 7 * 24 * 60 * 60 * 1000;
+        break;
+      default:
+        // Complex recurrence (weekday, weekend, month, year) - can't fast-forward easily
+        return null;
+    }
+
+    if (stepMilliseconds === 0) {
+      return null;
+    }
+
+    // Calculate how many steps we can skip
+    // We want to jump to just before the catch-up window starts
+    const targetLag = catchUpWindow;
+    const timeToSkip = lag - targetLag;
+
+    if (timeToSkip <= 0) {
+      return null;
+    }
+
+    const stepsToSkip = Math.floor(timeToSkip / stepMilliseconds);
+
+    if (stepsToSkip <= 0) {
+      return null;
+    }
+
+    // Project forward
+    const newTime = new Date(currentTime.getTime() + (stepsToSkip * stepMilliseconds));
+    const newCount = (action.count || 0) + stepsToSkip;
+
+    return {
+      nextRun: newTime,
+      count: newCount
+    };
+  }
+
   /**
    * Simulate actions in a time range without mutating state
    */