jw-automator 4.0.1 → 6.0.0

package/src/core/CoreEngine.js

@@ -11,7 +11,7 @@ class CoreEngine {
   /**
    * Process one scheduling step
    *
-   * @param {Object} state - Current scheduler state (actions array)
+   * @param {Object} state - Current scheduler state (tasks array)
    * @param {Date} lastTick - Previous tick time
    * @param {Date} now - Current tick time
    * @param {number} maxIterations - Safety limit for catch-up loops
@@ -21,29 +21,29 @@ class CoreEngine {
     const events = [];
     const newState = this._cloneState(state);
 
-    // Process each action
-    for (let i = 0; i < newState.actions.length; i++) {
-      const action = newState.actions[i];
+    // Process each task
+    for (let i = 0; i < newState.tasks.length; i++) {
+      const task = newState.tasks[i];
 
-      if (!action.date) {
+      if (!task.date) {
         // No scheduled time - run immediately
-        const event = this._executeAction(action, now);
+        const event = this._executeTask(task, now);
         events.push(event);
 
         // Advance to next occurrence
-        this._advanceAction(action);
+        this._advanceTask(task);
 
-        // Check if action should be removed
-        if (RecurrenceEngine.shouldStop(action)) {
-          newState.actions.splice(i, 1);
+        // Check if task should be removed
+        if (RecurrenceEngine.shouldStop(task)) {
+          newState.tasks.splice(i, 1);
           i--;
         }
         continue;
       }
 
-      const nextRun = new Date(action.date);
+      const nextRun = new Date(task.date);
 
-      // Safety: prevent processing actions in the future
+      // Safety: prevent processing tasks in the future
       if (nextRun > now) {
         continue;
       }
@@ -52,78 +52,81 @@ 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;
-              }
-            }
+      // Get catchUpWindow and catchUpLimit (defaults to 0 - real-time mode, no catch-up)
+      const catchUpWindow = task.catchUpWindow !== undefined ? task.catchUpWindow : 0;
+      const catchUpLimit = task.catchUpLimit !== undefined ? task.catchUpLimit : 0;
+
+      // JUMP: Fast-forward to the beginning of the catch-up window.
+      // This avoids iterating through a large number of occurrences outside the window.
+      if (catchUpWindow !== "unlimited" && catchUpWindow > 0 && task.repeat) {
+        const windowStart = new Date(now.getTime() - catchUpWindow);
+        if (currentNextRun < windowStart) {
+          const ffResult = RecurrenceEngine.fastForward(currentNextRun, task.repeat, windowStart);
+          if (ffResult && ffResult.skippedOccurrences > 0) {
+            task.date = ffResult.nextRun;
+            task.count = (task.count || 0) + ffResult.skippedOccurrences;
+            currentNextRun = ffResult.nextRun;
           }
         }
       }
 
-      while (currentNextRun <= now && iterationCount < maxIterations) {
+      // Buffer for collecting eligible slots when catchUpLimit is set
+      // This allows us to keep only the most recent N slots
+      const eligibleBuffer = [];
+      const needsBuffering = catchUpLimit !== "all" && catchUpLimit > 0;
+
+      while (currentNextRun && currentNextRun <= now && iterationCount < maxIterations) {
         iterationCount++;
 
         const lag = now.getTime() - currentNextRun.getTime();
 
-        // Determine if we should execute this occurrence based on catchUpWindow
-        const isInCurrentTick = currentNextRun > lastTick && currentNextRun <= now;
+        // Determine if this occurrence is eligible based on catchUpWindow
         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);
-          events.push(event);
+        if (isWithinWindow) {
+          if (needsBuffering) {
+            // Buffer this eligible slot
+            eligibleBuffer.push({
+              scheduledTime: new Date(currentNextRun),
+              count: task.count || 0
+            });
+            // Keep only the last N slots
+            if (eligibleBuffer.length > catchUpLimit) {
+              eligibleBuffer.shift();
+            }
+          } else if (catchUpLimit === "all") {
+            // Execute immediately - no limit
+            const event = this._executeTask(task, currentNextRun);
+            events.push(event);
+          }
+          // If catchUpLimit is 0, don't execute (real-time mode)
         }
 
         // Advance to next occurrence
         const prevTime = currentNextRun.getTime();
-        this._advanceAction(action);
+        this._advanceTask(task);
 
-        // Check if action should stop
-        if (RecurrenceEngine.shouldStop(action)) {
-          newState.actions.splice(i, 1);
+        // Check if task should stop
+        if (RecurrenceEngine.shouldStop(task)) {
+          newState.tasks.splice(i, 1);
           i--;
           break;
         }
 
         // Update currentNextRun for next iteration
-        if (action.date) {
-          currentNextRun = new Date(action.date);
+        if (task.date) {
+          currentNextRun = new Date(task.date);
 
           // SAFETY: Ensure monotonic progression
           if (currentNextRun.getTime() <= prevTime) {
             events.push({
               type: 'error',
-              message: `Action ${action.id} failed to advance time monotonically`,
-              actionId: action.id
+              message: `Task ${task.id} failed to advance time monotonically`,
+              taskId: task.id
             });
             // Force advancement
             currentNextRun = new Date(prevTime + 1000);
-            action.date = currentNextRun;
+            task.date = currentNextRun;
           }
         } else {
           // No more occurrences
@@ -131,12 +134,29 @@ class CoreEngine {
         }
       }
 
+      // Execute buffered slots (if we were buffering)
+      if (needsBuffering && eligibleBuffer.length > 0) {
+        for (const slot of eligibleBuffer) {
+          const event = {
+            type: 'task',
+            taskId: task.id,
+            name: task.name,
+            cmd: task.cmd,
+            payload: task.payload,
+            scheduledTime: slot.scheduledTime,
+            actualTime: new Date(),
+            count: slot.count
+          };
+          events.push(event);
+        }
+      }
+
       // Safety check: iteration limit reached
       if (iterationCount >= maxIterations) {
         events.push({
           type: 'error',
-          message: `Action ${action.id} exceeded max iterations (${maxIterations}) - possible infinite loop`,
-          actionId: action.id
+          message: `Task ${task.id} exceeded max iterations (${maxIterations}) - possible infinite loop`,
+          taskId: task.id
         });
       }
     }
@@ -149,137 +169,61 @@ class CoreEngine {
    */
   static _cloneState(state) {
     return {
-      actions: state.actions.map(action => ({ ...action }))
+      tasks: state.tasks.map(task => ({ ...task }))
     };
   }
 
   /**
-   * Check if a time falls within the current tick window
-   */
-  static _isCurrentTick(time, lastTick, now) {
-    return time > lastTick && time <= now;
-  }
-
-  /**
-   * Create an action execution event
+   * Create a task execution event
    */
-  static _executeAction(action, scheduledTime) {
+  static _executeTask(task, scheduledTime) {
     return {
-      type: 'action',
-      actionId: action.id,
-      name: action.name,
-      cmd: action.cmd,
-      payload: action.payload,
+      type: 'task',
+      taskId: task.id,
+      name: task.name,
+      cmd: task.cmd,
+      payload: task.payload,
       scheduledTime: new Date(scheduledTime),
       actualTime: new Date(),
-      count: action.count || 0
+      count: task.count || 0
     };
   }
 
   /**
-   * Advance an action to its next occurrence
+   * Advance a task to its next occurrence
    */
-  static _advanceAction(action) {
+  static _advanceTask(task) {
     // Increment count
-    action.count = (action.count || 0) + 1;
+    task.count = (task.count || 0) + 1;
 
     // Calculate next run time
-    if (action.repeat) {
-      const currentTime = action.date ? new Date(action.date) : new Date();
-      const dstPolicy = action.repeat.dstPolicy || 'once';
+    if (task.repeat) {
+      const currentTime = task.date ? new Date(task.date) : new Date();
+      const dstPolicy = task.repeat.dstPolicy || 'once';
 
       const nextTime = RecurrenceEngine.getNextOccurrence(
         currentTime,
-        action.repeat,
+        task.repeat,
         dstPolicy
       );
 
-      action.date = nextTime;
+      task.date = nextTime;
     } else {
-      // One-time action - clear date
-      action.date = null;
+      // One-time task - clear date
+      task.date = null;
     }
   }
 
-  /**
-   * 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
+   * Simulate tasks in a time range without mutating state
    */
   static simulate(state, startDate, endDate, maxIterations = 100000) {
     const simulatedEvents = [];
     const simulatedState = this._cloneState(state);
 
-    // Start simulation from the earliest action time or startDate
+    // Start simulation from the earliest task time or startDate
     let currentTime = new Date(startDate);
 
     // Align to second boundary
@@ -296,11 +240,11 @@ class CoreEngine {
       iterationCount++;
 
       const { newState, events } = this.step(simulatedState, lastTick, currentTime, maxIterations);
-      simulatedState.actions = newState.actions;
+      simulatedState.tasks = newState.tasks;
 
-      // Collect action events (filter out errors for cleaner simulation output)
-      const actionEvents = events.filter(e => e.type === 'action');
-      simulatedEvents.push(...actionEvents);
+      // Collect task events (filter out errors for cleaner simulation output)
+      const taskEvents = events.filter(e => e.type === 'task');
+      simulatedEvents.push(...taskEvents);
 
       // Advance time by 1 second
       lastTick = currentTime;

package/src/core/RecurrenceEngine.js

@@ -7,7 +7,7 @@
 
 class RecurrenceEngine {
   /**
-   * Calculate the next occurrence time for an action based on its recurrence rule.
+   * Calculate the next occurrence time for a task based on its recurrence rule.
    *
    * CRITICAL INVARIANT: nextTime.getTime() > currentTime.getTime()
    *
@@ -69,6 +69,67 @@ class RecurrenceEngine {
     return next;
   }
 
+  /**
+   * Fast-forward a task to a target time using mathematical projection.
+   * This is only applicable for simple, fixed-duration recurrence types.
+   *
+   * @param {Date} currentTime - The current scheduled time.
+   * @param {Object} repeat - The repeat configuration.
+   * @param {Date} targetTime - The time to project towards.
+   * @returns {Object|null} - { nextRun, skippedOccurrences } or null if not applicable.
+   */
+  static fastForward(currentTime, repeat, targetTime) {
+    if (!repeat || !repeat.type) {
+      return null;
+    }
+
+    const { type, interval = 1 } = repeat;
+    const timeToSkip = targetTime.getTime() - currentTime.getTime();
+
+    if (timeToSkip <= 0) {
+      return { nextRun: currentTime, skippedOccurrences: 0 };
+    }
+
+    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 types (weekday, weekend, month, year) cannot be fast-forwarded.
+        return null;
+    }
+
+    if (stepMilliseconds === 0) {
+      return null;
+    }
+
+    const stepsToSkip = Math.floor(timeToSkip / stepMilliseconds);
+
+    if (stepsToSkip <= 0) {
+      return { nextRun: currentTime, skippedOccurrences: 0 };
+    }
+
+    const newTime = new Date(currentTime.getTime() + (stepsToSkip * stepMilliseconds));
+
+    return {
+      nextRun: newTime,
+      skippedOccurrences: stepsToSkip,
+    };
+  }
+
   /**
    * Add seconds to a date
    */
@@ -206,16 +267,16 @@ class RecurrenceEngine {
   }
 
   /**
-   * Check if an action should stop based on limit or endDate
+   * Check if a task should stop based on limit or endDate
    */
-  static shouldStop(action) {
-    const { repeat } = action;
+  static shouldStop(task) {
+    const { repeat } = task;
 
     if (!repeat) return true;
 
     // Check count limit
     if (repeat.limit !== null && repeat.limit !== undefined) {
-      const count = action.count || 0;
+      const count = task.count || 0;
       if (count >= repeat.limit) {
         return true;
       }
@@ -224,7 +285,7 @@ class RecurrenceEngine {
     // Check end date
     if (repeat.endDate) {
       const endDate = new Date(repeat.endDate);
-      const nextRun = new Date(action.date);
+      const nextRun = new Date(task.date);
       if (nextRun > endDate) {
         return true;
       }

package/src/host/SchedulerHost.js

@@ -11,11 +11,12 @@ const CoreEngine = require('../core/CoreEngine');
 class SchedulerHost extends EventEmitter {
   constructor() {
     super();
-    this.state = { actions: [] };
+    this.state = { tasks: [] };
     this.running = false;
     this.lastTick = null;
     this.timer = null;
     this.functions = new Map();
+    this.bootMode = true;
   }
 
   /**
@@ -27,8 +28,48 @@ class SchedulerHost extends EventEmitter {
     }
 
     this.running = true;
-    this.lastTick = new Date();
-    this.lastTick.setMilliseconds(0);
+    const now = new Date();
+    now.setMilliseconds(0);
+
+    // Boot sweep - advance state to current time without executing tasks
+    if (this.bootMode) {
+      try {
+        // Boot sweep: advance state from lastTick to now without executing tasks
+        // If lastTick is null (first start), use now (no catch-up needed)
+        const { newState, events } = CoreEngine.step(this.state, this.lastTick || now, now);
+
+        // Update state (tasks are now advanced to current time)
+        this.state = newState;
+
+        // Process events to ensure state consistency, but don't execute callbacks
+        // The bootMode flag will prevent _executeTaskEvent from calling functions
+        for (const event of events) {
+          if (event.type === 'task') {
+            this._executeTaskEvent(event);
+          } else if (event.type === 'error') {
+            this.emit('error', event);
+          }
+        }
+
+        // Exit boot mode
+        this.bootMode = false;
+
+        // Signal to Automator that state should be saved
+        this.emit('boot-complete');
+
+      } catch (error) {
+        this.emit('error', {
+          type: 'error',
+          message: `Boot sweep error: ${error.message}`,
+          error
+        });
+        // Exit boot mode even on error to allow normal operation
+        this.bootMode = false;
+      }
+    }
+
+    // Set lastTick after boot sweep completes
+    this.lastTick = now;
 
     this._scheduleTick();
     this.emit('ready');
@@ -102,8 +143,8 @@ class SchedulerHost extends EventEmitter {
 
       // Process events
       for (const event of events) {
-        if (event.type === 'action') {
-          this._executeActionEvent(event);
+        if (event.type === 'task') {
+          this._executeTaskEvent(event);
         } else if (event.type === 'error') {
           this.emit('error', event);
         }
@@ -121,11 +162,16 @@ class SchedulerHost extends EventEmitter {
   }
 
   /**
-   * Execute an action event by calling its registered function
+   * Execute a task event by calling its registered function
    */
-  _executeActionEvent(event) {
-    // Emit the action event
-    this.emit('action', event);
+  _executeTaskEvent(event) {
+    // Skip execution during boot mode
+    if (this.bootMode) {
+      return;
+    }
+
+    // Emit the task event
+    this.emit('task', event);
 
     // Execute the command function if registered
     const fn = this.functions.get(event.cmd);
@@ -136,7 +182,7 @@ class SchedulerHost extends EventEmitter {
         this.emit('error', {
           type: 'error',
           message: `Error executing command ${event.cmd}: ${error.message}`,
-          actionId: event.actionId,
+          taskId: event.taskId,
           error
         });
       }
@@ -144,16 +190,16 @@ class SchedulerHost extends EventEmitter {
       this.emit('debug', {
         type: 'debug',
         message: `No function registered for command: ${event.cmd}`,
-        actionId: event.actionId
+        taskId: event.taskId
       });
     }
   }
 
   /**
-   * Add an action to the state
+   * Add a task to the state
    */
-  addAction(action) {
-    this.state.actions.push(action);
+  addTask(task) {
+    this.state.tasks.push(task);
   }
 
   /**

package/src/storage/FileStorage.js

@@ -1,59 +0,0 @@
-/**
- * FileStorage.js
- *
- * Pluggable file-based storage adapter
- */
-
-const fs = require('fs');
-const path = require('path');
-
-class FileStorage {
-  constructor(filePath) {
-    this.filePath = path.resolve(filePath);
-  }
-
-  /**
-   * Load state from file
-   */
-  load() {
-    try {
-      if (fs.existsSync(this.filePath)) {
-        const data = fs.readFileSync(this.filePath, 'utf8');
-        const state = JSON.parse(data);
-
-        // Convert date strings back to Date objects
-        if (state.actions) {
-          state.actions = state.actions.map(action => {
-            if (action.date) {
-              action.date = new Date(action.date);
-            }
-            if (action.repeat && action.repeat.endDate) {
-              action.repeat.endDate = new Date(action.repeat.endDate);
-            }
-            return action;
-          });
-        }
-
-        return state;
-      }
-    } catch (error) {
-      throw new Error(`Failed to load from ${this.filePath}: ${error.message}`);
-    }
-
-    return { actions: [] };
-  }
-
-  /**
-   * Save state to file
-   */
-  save(state) {
-    try {
-      const data = JSON.stringify(state, null, 2);
-      fs.writeFileSync(this.filePath, data, 'utf8');
-    } catch (error) {
-      throw new Error(`Failed to save to ${this.filePath}: ${error.message}`);
-    }
-  }
-}
-
-module.exports = FileStorage;