jw-automator 2.0.0 → 3.1.0

package/src/core/CoreEngine.js

@@ -0,0 +1,210 @@
+/**
+ * CoreEngine.js
+ *
+ * Pure state machine for scheduling.
+ * Deterministic step function: step(state, lastTick, now) -> { newState, events }
+ */
+
+const RecurrenceEngine = require('./RecurrenceEngine');
+
+class CoreEngine {
+  /**
+   * Process one scheduling step
+   *
+   * @param {Object} state - Current scheduler state (actions array)
+   * @param {Date} lastTick - Previous tick time
+   * @param {Date} now - Current tick time
+   * @param {number} maxIterations - Safety limit for catch-up loops
+   * @returns {Object} - { newState, events }
+   */
+  static step(state, lastTick, now, maxIterations = 10000) {
+    const events = [];
+    const newState = this._cloneState(state);
+
+    // Process each action
+    for (let i = 0; i < newState.actions.length; i++) {
+      const action = newState.actions[i];
+
+      if (!action.date) {
+        // No scheduled time - run immediately
+        const event = this._executeAction(action, now);
+        events.push(event);
+
+        // Advance to next occurrence
+        this._advanceAction(action);
+
+        // Check if action should be removed
+        if (RecurrenceEngine.shouldStop(action)) {
+          newState.actions.splice(i, 1);
+          i--;
+        }
+        continue;
+      }
+
+      const nextRun = new Date(action.date);
+
+      // Safety: prevent processing actions in the future
+      if (nextRun > now) {
+        continue;
+      }
+
+      // Catch-up loop: process all missed occurrences
+      let iterationCount = 0;
+      let currentNextRun = nextRun;
+
+      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 isInCurrentTick = currentNextRun > lastTick && currentNextRun <= now;
+        const shouldExecute = action.unBuffered ? isInCurrentTick : true;
+
+        if (shouldExecute) {
+          const event = this._executeAction(action, currentNextRun);
+          events.push(event);
+        }
+
+        // Advance to next occurrence
+        const prevTime = currentNextRun.getTime();
+        this._advanceAction(action);
+
+        // Check if action should stop
+        if (RecurrenceEngine.shouldStop(action)) {
+          newState.actions.splice(i, 1);
+          i--;
+          break;
+        }
+
+        // Update currentNextRun for next iteration
+        if (action.date) {
+          currentNextRun = new Date(action.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
+            });
+            // Force advancement
+            currentNextRun = new Date(prevTime + 1000);
+            action.date = currentNextRun;
+          }
+        } else {
+          // No more occurrences
+          break;
+        }
+      }
+
+      // 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
+        });
+      }
+    }
+
+    return { newState, events };
+  }
+
+  /**
+   * Clone state for immutability
+   */
+  static _cloneState(state) {
+    return {
+      actions: state.actions.map(action => ({ ...action }))
+    };
+  }
+
+  /**
+   * 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
+   */
+  static _executeAction(action, scheduledTime) {
+    return {
+      type: 'action',
+      actionId: action.id,
+      name: action.name,
+      cmd: action.cmd,
+      payload: action.payload,
+      scheduledTime: new Date(scheduledTime),
+      actualTime: new Date(),
+      count: action.count || 0
+    };
+  }
+
+  /**
+   * Advance an action to its next occurrence
+   */
+  static _advanceAction(action) {
+    // Increment count
+    action.count = (action.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';
+
+      const nextTime = RecurrenceEngine.getNextOccurrence(
+        currentTime,
+        action.repeat,
+        dstPolicy
+      );
+
+      action.date = nextTime;
+    } else {
+      // One-time action - clear date
+      action.date = null;
+    }
+  }
+
+  /**
+   * Simulate actions 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
+    let currentTime = new Date(startDate);
+
+    // Align to second boundary
+    currentTime.setMilliseconds(0);
+
+    const endTime = new Date(endDate);
+    let lastTick = new Date(currentTime.getTime() - 1000);
+
+    let iterationCount = 0;
+    const maxTotalIterations = maxIterations * 10;
+
+    // Step through time second by second
+    while (currentTime <= endTime && iterationCount < maxTotalIterations) {
+      iterationCount++;
+
+      const { newState, events } = this.step(simulatedState, lastTick, currentTime, maxIterations);
+      simulatedState.actions = newState.actions;
+
+      // Collect action events (filter out errors for cleaner simulation output)
+      const actionEvents = events.filter(e => e.type === 'action');
+      simulatedEvents.push(...actionEvents);
+
+      // Advance time by 1 second
+      lastTick = currentTime;
+      currentTime = new Date(currentTime.getTime() + 1000);
+    }
+
+    return simulatedEvents;
+  }
+}
+
+module.exports = CoreEngine;

package/src/core/RecurrenceEngine.js

@@ -0,0 +1,237 @@
+/**
+ * RecurrenceEngine.js
+ *
+ * Pure recurrence calculation logic.
+ * Handles all DST transitions, local-time semantics, and next-run computations.
+ */
+
+class RecurrenceEngine {
+  /**
+   * Calculate the next occurrence time for an action based on its recurrence rule.
+   *
+   * CRITICAL INVARIANT: nextTime.getTime() > currentTime.getTime()
+   *
+   * @param {Date} currentTime - The current scheduled time (local)
+   * @param {Object} repeat - The repeat configuration
+   * @param {string} dstPolicy - 'once' or 'twice' for fall-back behavior
+   * @returns {Date} - The next scheduled time (always > currentTime in UTC milliseconds)
+   */
+  static getNextOccurrence(currentTime, repeat, dstPolicy = 'once') {
+    if (!repeat || !repeat.type) {
+      return null;
+    }
+
+    const { type, interval = 1 } = repeat;
+    const current = new Date(currentTime);
+    let next = null;
+
+    switch (type) {
+      case 'second':
+        next = this._addSeconds(current, interval);
+        break;
+      case 'minute':
+        next = this._addMinutes(current, interval);
+        break;
+      case 'hour':
+        next = this._addHours(current, interval);
+        break;
+      case 'day':
+        next = this._addDays(current, interval);
+        break;
+      case 'weekday':
+        next = this._addWeekdays(current, interval);
+        break;
+      case 'weekend':
+        next = this._addWeekends(current, interval);
+        break;
+      case 'week':
+        next = this._addWeeks(current, interval);
+        break;
+      case 'month':
+        next = this._addMonths(current, interval);
+        break;
+      case 'year':
+        next = this._addYears(current, interval);
+        break;
+      default:
+        throw new Error(`Unknown recurrence type: ${type}`);
+    }
+
+    // SAFETY: Ensure monotonic progression
+    if (next && next.getTime() <= current.getTime()) {
+      // Force forward by 1 second to prevent infinite loops
+      next = new Date(current.getTime() + 1000);
+    }
+
+    // Handle DST transitions
+    next = this._handleDSTTransition(current, next, dstPolicy);
+
+    return next;
+  }
+
+  /**
+   * Add seconds to a date
+   */
+  static _addSeconds(date, count) {
+    return new Date(date.getTime() + (count * 1000));
+  }
+
+  /**
+   * Add minutes to a date
+   */
+  static _addMinutes(date, count) {
+    return new Date(date.getTime() + (count * 60 * 1000));
+  }
+
+  /**
+   * Add hours to a date
+   */
+  static _addHours(date, count) {
+    return new Date(date.getTime() + (count * 60 * 60 * 1000));
+  }
+
+  /**
+   * Add days to a date (preserving local time across DST)
+   */
+  static _addDays(date, count) {
+    const result = new Date(date);
+    result.setDate(result.getDate() + count);
+    return result;
+  }
+
+  /**
+   * Add weekdays (Mon-Fri) to a date
+   */
+  static _addWeekdays(date, count) {
+    const result = new Date(date);
+    let added = 0;
+
+    while (added < count) {
+      result.setDate(result.getDate() + 1);
+      const day = result.getDay();
+      // 0 = Sunday, 6 = Saturday
+      if (day !== 0 && day !== 6) {
+        added++;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Add weekend days (Sat-Sun) to a date
+   */
+  static _addWeekends(date, count) {
+    const result = new Date(date);
+    let added = 0;
+
+    while (added < count) {
+      result.setDate(result.getDate() + 1);
+      const day = result.getDay();
+      // 0 = Sunday, 6 = Saturday
+      if (day === 0 || day === 6) {
+        added++;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Add weeks to a date
+   */
+  static _addWeeks(date, count) {
+    return this._addDays(date, count * 7);
+  }
+
+  /**
+   * Add months to a date (preserving day-of-month when possible)
+   */
+  static _addMonths(date, count) {
+    const result = new Date(date);
+    const originalDay = result.getDate();
+
+    result.setMonth(result.getMonth() + count);
+
+    // Handle edge case: Jan 31 + 1 month should be Feb 28/29, not Mar 3
+    if (result.getDate() !== originalDay) {
+      result.setDate(0); // Set to last day of previous month
+    }
+
+    return result;
+  }
+
+  /**
+   * Add years to a date
+   */
+  static _addYears(date, count) {
+    const result = new Date(date);
+    result.setFullYear(result.getFullYear() + count);
+    return result;
+  }
+
+  /**
+   * Handle DST transitions between current and next time
+   *
+   * - Spring forward: missing hour handled naturally by Date constructor
+   * - Fall back: prevent duplicate execution based on dstPolicy
+   */
+  static _handleDSTTransition(currentTime, nextTime, dstPolicy) {
+    if (!nextTime) return nextTime;
+
+    const currentOffset = currentTime.getTimezoneOffset();
+    const nextOffset = nextTime.getTimezoneOffset();
+
+    // No DST transition
+    if (currentOffset === nextOffset) {
+      return nextTime;
+    }
+
+    // Spring forward (offset decreased - clock jumped ahead)
+    // The missing hour is handled naturally by Date arithmetic
+    // No special handling needed
+
+    // Fall back (offset increased - clock fell back)
+    if (nextOffset > currentOffset) {
+      // We've crossed into the repeated hour
+      if (dstPolicy === 'once') {
+        // Skip the second occurrence by adding the offset difference
+        const offsetDiff = (nextOffset - currentOffset) * 60 * 1000;
+        return new Date(nextTime.getTime() + offsetDiff);
+      }
+      // dstPolicy === 'twice': allow both occurrences (no adjustment needed)
+    }
+
+    return nextTime;
+  }
+
+  /**
+   * Check if an action should stop based on limit or endDate
+   */
+  static shouldStop(action) {
+    const { repeat } = action;
+
+    if (!repeat) return true;
+
+    // Check count limit
+    if (repeat.limit !== null && repeat.limit !== undefined) {
+      const count = action.count || 0;
+      if (count >= repeat.limit) {
+        return true;
+      }
+    }
+
+    // Check end date
+    if (repeat.endDate) {
+      const endDate = new Date(repeat.endDate);
+      const nextRun = new Date(action.date);
+      if (nextRun > endDate) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+}
+
+module.exports = RecurrenceEngine;

package/src/host/SchedulerHost.js

@@ -0,0 +1,174 @@
+/**
+ * SchedulerHost.js
+ *
+ * Manages real-time ticking with 1-second alignment.
+ * Wraps the core engine and drives it with wall-clock time.
+ */
+
+const EventEmitter = require('events');
+const CoreEngine = require('../core/CoreEngine');
+
+class SchedulerHost extends EventEmitter {
+  constructor() {
+    super();
+    this.state = { actions: [] };
+    this.running = false;
+    this.lastTick = null;
+    this.timer = null;
+    this.functions = new Map();
+  }
+
+  /**
+   * Start the scheduler
+   */
+  start() {
+    if (this.running) {
+      return;
+    }
+
+    this.running = true;
+    this.lastTick = new Date();
+    this.lastTick.setMilliseconds(0);
+
+    this._scheduleTick();
+    this.emit('ready');
+  }
+
+  /**
+   * Stop the scheduler
+   */
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Register a command function
+   */
+  addFunction(name, fn) {
+    if (typeof fn !== 'function') {
+      throw new Error(`Function ${name} must be a function`);
+    }
+    this.functions.set(name, fn);
+  }
+
+  /**
+   * Remove a command function
+   */
+  removeFunction(name) {
+    this.functions.delete(name);
+  }
+
+  /**
+   * Schedule the next tick aligned to whole seconds
+   */
+  _scheduleTick() {
+    if (!this.running) {
+      return;
+    }
+
+    const now = new Date();
+    const milliseconds = now.getMilliseconds();
+
+    // Calculate wait time to next whole second
+    const waitTime = 1000 - milliseconds;
+
+    this.timer = setTimeout(() => {
+      this._tick();
+    }, waitTime);
+  }
+
+  /**
+   * Execute one tick
+   */
+  _tick() {
+    if (!this.running) {
+      return;
+    }
+
+    const now = new Date();
+    now.setMilliseconds(0); // Align to second boundary
+
+    try {
+      // Run the core engine step
+      const { newState, events } = CoreEngine.step(this.state, this.lastTick, now);
+
+      // Update state
+      this.state = newState;
+      this.lastTick = now;
+
+      // Process events
+      for (const event of events) {
+        if (event.type === 'action') {
+          this._executeActionEvent(event);
+        } else if (event.type === 'error') {
+          this.emit('error', event);
+        }
+      }
+    } catch (error) {
+      this.emit('error', {
+        type: 'error',
+        message: `Tick error: ${error.message}`,
+        error
+      });
+    }
+
+    // Schedule next tick
+    this._scheduleTick();
+  }
+
+  /**
+   * Execute an action event by calling its registered function
+   */
+  _executeActionEvent(event) {
+    // Emit the action event
+    this.emit('action', event);
+
+    // Execute the command function if registered
+    const fn = this.functions.get(event.cmd);
+    if (fn) {
+      try {
+        fn(event.payload, event);
+      } catch (error) {
+        this.emit('error', {
+          type: 'error',
+          message: `Error executing command ${event.cmd}: ${error.message}`,
+          actionId: event.actionId,
+          error
+        });
+      }
+    } else {
+      this.emit('debug', {
+        type: 'debug',
+        message: `No function registered for command: ${event.cmd}`,
+        actionId: event.actionId
+      });
+    }
+  }
+
+  /**
+   * Add an action to the state
+   */
+  addAction(action) {
+    this.state.actions.push(action);
+  }
+
+  /**
+   * Get current state
+   */
+  getState() {
+    return this.state;
+  }
+
+  /**
+   * Set state
+   */
+  setState(state) {
+    this.state = state;
+  }
+}
+
+module.exports = SchedulerHost;

package/src/storage/FileStorage.js

@@ -0,0 +1,59 @@
+/**
+ * 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;

package/src/storage/MemoryStorage.js

@@ -0,0 +1,27 @@
+/**
+ * MemoryStorage.js
+ *
+ * In-memory storage adapter (no persistence)
+ */
+
+class MemoryStorage {
+  constructor() {
+    this.state = { actions: [] };
+  }
+
+  /**
+   * Load state from memory
+   */
+  load() {
+    return JSON.parse(JSON.stringify(this.state));
+  }
+
+  /**
+   * Save state to memory
+   */
+  save(state) {
+    this.state = JSON.parse(JSON.stringify(state));
+  }
+}
+
+module.exports = MemoryStorage;

package/.actions.json

@@ -1 +0,0 @@
-[{"name":"sec","date":"2019-07-18T16:05:38.000Z","cmd":"test","payload":"tick","unBuffered":null,"repeat":{"type":"second","interval":1,"count":34,"limit":null,"endDate":null,"executed":25},"id":1563465903653}]