jw-automator 2.0.0 → 3.0.0

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}]

package/.jshintrc

@@ -1,16 +0,0 @@
-{
-    "multistr": true,
-    "undef": true,
-    "unused": false,
-    "validthis": true,
-    "node": true,
-    "loopfunc": true,
-    "globals": {
-        "$": true,
-        "document": true,
-        "jQuery": true,
-        "window": true,
-        "jwf": true,
-        "performance": true
-    }
-}

package/.vscode/settings.json

@@ -1,6 +0,0 @@
-{
-    "cSpell.words": [
-        "Milli",
-        "automator"
-    ]
-}