jw-automator 2.0.0 → 3.0.0

package/package.json

@@ -1,19 +1,53 @@
-{
-  "name": "jw-automator",
-  "version": "2.0.0",
-  "description": "Run various functions at proscribed intervals",
-  "main": "automator.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jonwyett/jw-automator.git"
-  },
-  "author": "Jonathan Wyett",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/jonwyett/jw-automator/issues"
-  },
-  "homepage": "https://github.com/jonwyett/jw-automator#readme"
-}
+{
+  "name": "jw-automator",
+  "version": "3.0.0",
+  "description": "A resilient, local-time, 1-second precision automation scheduler for Node.js",
+  "main": "index.js",
+  "files": [
+    "src/",
+    "examples/",
+    "docs/",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "scheduler",
+    "automation",
+    "cron",
+    "task",
+    "timer",
+    "schedule",
+    "local-time",
+    "dst",
+    "recurrence",
+    "iot",
+    "raspberry-pi",
+    "home-automation"
+  ],
+  "author": "Jon Wyett",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jonwyett/jw-automator.git"
+  },
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "coverageDirectory": "coverage",
+    "collectCoverageFrom": [
+      "src/**/*.js",
+      "!src/**/*.test.js"
+    ]
+  }
+}

package/src/Automator.js

@@ -0,0 +1,429 @@
+/**
+ * Automator.js
+ *
+ * Main API class for jw-automator v3
+ */
+
+const SchedulerHost = require('./host/SchedulerHost');
+const CoreEngine = require('./core/CoreEngine');
+const FileStorage = require('./storage/FileStorage');
+const MemoryStorage = require('./storage/MemoryStorage');
+
+class Automator {
+  constructor(options = {}) {
+    this.options = {
+      storage: options.storage || new MemoryStorage(),
+      autoSave: options.autoSave !== false, // default true
+      saveInterval: options.saveInterval || 5000, // 5 seconds
+      ...options
+    };
+
+    this.host = new SchedulerHost();
+    this.nextId = 1;
+    this.saveTimer = null;
+
+    // Forward events from host
+    this.host.on('ready', (...args) => this._emit('ready', ...args));
+    this.host.on('action', (...args) => this._emit('action', ...args));
+    this.host.on('error', (...args) => this._emit('error', ...args));
+    this.host.on('debug', (...args) => this._emit('debug', ...args));
+
+    // Event listeners
+    this.listeners = new Map();
+
+    // Load initial state
+    this._loadState();
+  }
+
+  /**
+   * Start the automator
+   */
+  start() {
+    this.host.start();
+
+    // Start auto-save if enabled
+    if (this.options.autoSave) {
+      this._startAutoSave();
+    }
+  }
+
+  /**
+   * Stop the automator
+   */
+  stop() {
+    this.host.stop();
+
+    // Stop auto-save
+    if (this.saveTimer) {
+      clearInterval(this.saveTimer);
+      this.saveTimer = null;
+    }
+
+    // Final save
+    if (this.options.autoSave) {
+      this._saveState();
+    }
+  }
+
+  /**
+   * Register a command function
+   */
+  addFunction(name, fn) {
+    this.host.addFunction(name, fn);
+  }
+
+  /**
+   * Remove a command function
+   */
+  removeFunction(name) {
+    this.host.removeFunction(name);
+  }
+
+  /**
+   * Add an action
+   */
+  addAction(actionSpec) {
+    // Validate action
+    this._validateAction(actionSpec);
+
+    // 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,
+      repeat: actionSpec.repeat ? { ...actionSpec.repeat } : null,
+      count: 0
+    };
+
+    // Set default dstPolicy if not specified
+    if (action.repeat && !action.repeat.dstPolicy) {
+      action.repeat.dstPolicy = 'once';
+    }
+
+    this.host.addAction(action);
+
+    this._emit('update', {
+      type: 'update',
+      operation: 'add',
+      action: { ...action }
+    });
+
+    if (this.options.autoSave) {
+      this._saveState();
+    }
+
+    return action.id;
+  }
+
+  /**
+   * Update an action by ID
+   */
+  updateActionByID(id, updates) {
+    const state = this.host.getState();
+    const action = state.actions.find(a => a.id === id);
+
+    if (!action) {
+      throw new Error(`Action with id ${id} not found`);
+    }
+
+    // Update allowed fields
+    const allowedUpdates = ['name', 'cmd', 'payload', 'date', 'unBuffered', 'repeat', 'count'];
+
+    for (const key of allowedUpdates) {
+      if (key in updates) {
+        if (key === 'date' && updates[key]) {
+          action[key] = new Date(updates[key]);
+        } else if (key === 'repeat' && updates[key]) {
+          action[key] = { ...updates[key] };
+          if (!action[key].dstPolicy) {
+            action[key].dstPolicy = 'once';
+          }
+        } else {
+          action[key] = updates[key];
+        }
+      }
+    }
+
+    this._emit('update', {
+      type: 'update',
+      operation: 'update',
+      actionId: id,
+      action: { ...action }
+    });
+
+    if (this.options.autoSave) {
+      this._saveState();
+    }
+  }
+
+  /**
+   * Remove action by ID
+   */
+  removeActionByID(id) {
+    const state = this.host.getState();
+    const index = state.actions.findIndex(a => a.id === id);
+
+    if (index === -1) {
+      throw new Error(`Action with id ${id} not found`);
+    }
+
+    const removed = state.actions.splice(index, 1)[0];
+
+    this._emit('update', {
+      type: 'update',
+      operation: 'remove',
+      actionId: id,
+      action: removed
+    });
+
+    if (this.options.autoSave) {
+      this._saveState();
+    }
+  }
+
+  /**
+   * Remove actions by name
+   */
+  removeActionByName(name) {
+    const state = this.host.getState();
+    const toRemove = state.actions.filter(a => a.name === name);
+
+    if (toRemove.length === 0) {
+      throw new Error(`No actions found with name: ${name}`);
+    }
+
+    for (const action of toRemove) {
+      const index = state.actions.indexOf(action);
+      if (index !== -1) {
+        state.actions.splice(index, 1);
+
+        this._emit('update', {
+          type: 'update',
+          operation: 'remove',
+          actionId: action.id,
+          action
+        });
+      }
+    }
+
+    if (this.options.autoSave) {
+      this._saveState();
+    }
+
+    return toRemove.length;
+  }
+
+  /**
+   * Get all actions (deep copy)
+   */
+  getActions() {
+    const state = this.host.getState();
+    return JSON.parse(JSON.stringify(state.actions));
+  }
+
+  /**
+   * Get actions by name
+   */
+  getActionsByName(name) {
+    const state = this.host.getState();
+    return state.actions
+      .filter(a => a.name === name)
+      .map(a => JSON.parse(JSON.stringify(a)));
+  }
+
+  /**
+   * Get action by ID
+   */
+  getActionByID(id) {
+    const state = this.host.getState();
+    const action = state.actions.find(a => a.id === id);
+    return action ? JSON.parse(JSON.stringify(action)) : null;
+  }
+
+  /**
+   * Get actions scheduled in a time range
+   */
+  getActionsInRange(startDate, endDate, callback) {
+    const start = new Date(startDate);
+    const end = new Date(endDate);
+
+    const state = this.host.getState();
+    const events = CoreEngine.simulate(state, start, end);
+
+    if (callback && typeof callback === 'function') {
+      callback(events);
+    }
+
+    return events;
+  }
+
+  /**
+   * Simulate range (alias for getActionsInRange)
+   */
+  simulateRange(startDate, endDate) {
+    return this.getActionsInRange(startDate, endDate);
+  }
+
+  /**
+   * Describe an action in human-readable format
+   */
+  describeAction(id) {
+    const action = this.getActionByID(id);
+    if (!action) {
+      return null;
+    }
+
+    let description = `Action #${action.id}`;
+    if (action.name) {
+      description += ` - ${action.name}`;
+    }
+
+    description += `\n  Command: ${action.cmd}`;
+    description += `\n  Next run: ${action.date ? action.date.toLocaleString() : 'None'}`;
+    description += `\n  Executions: ${action.count}`;
+    description += `\n  Buffered: ${!action.unBuffered}`;
+
+    if (action.repeat) {
+      description += `\n  Recurrence: ${action.repeat.type}`;
+      if (action.repeat.interval > 1) {
+        description += ` (every ${action.repeat.interval})`;
+      }
+      if (action.repeat.limit) {
+        description += `\n  Limit: ${action.repeat.limit}`;
+      }
+      if (action.repeat.endDate) {
+        description += `\n  End date: ${new Date(action.repeat.endDate).toLocaleString()}`;
+      }
+      description += `\n  DST policy: ${action.repeat.dstPolicy}`;
+    } else {
+      description += `\n  Recurrence: One-time`;
+    }
+
+    return description;
+  }
+
+  /**
+   * Event listener management
+   */
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event).push(listener);
+  }
+
+  off(event, listener) {
+    if (!this.listeners.has(event)) {
+      return;
+    }
+    const list = this.listeners.get(event);
+    const index = list.indexOf(listener);
+    if (index !== -1) {
+      list.splice(index, 1);
+    }
+  }
+
+  _emit(event, ...args) {
+    if (!this.listeners.has(event)) {
+      return;
+    }
+    const list = this.listeners.get(event);
+    for (const listener of list) {
+      try {
+        listener(...args);
+      } catch (error) {
+        console.error(`Error in ${event} listener:`, error);
+      }
+    }
+  }
+
+  /**
+   * Load state from storage
+   */
+  _loadState() {
+    try {
+      const state = this.options.storage.load();
+      this.host.setState(state);
+
+      // Update nextId to be higher than any existing ID
+      if (state.actions && state.actions.length > 0) {
+        const maxId = Math.max(...state.actions.map(a => a.id || 0));
+        this.nextId = maxId + 1;
+      }
+    } catch (error) {
+      this._emit('error', {
+        type: 'error',
+        message: `Failed to load state: ${error.message}`,
+        error
+      });
+    }
+  }
+
+  /**
+   * Save state to storage
+   */
+  _saveState() {
+    try {
+      const state = this.host.getState();
+      this.options.storage.save(state);
+    } catch (error) {
+      this._emit('error', {
+        type: 'error',
+        message: `Failed to save state: ${error.message}`,
+        error
+      });
+    }
+  }
+
+  /**
+   * Start auto-save timer
+   */
+  _startAutoSave() {
+    if (this.saveTimer) {
+      return;
+    }
+
+    this.saveTimer = setInterval(() => {
+      this._saveState();
+    }, this.options.saveInterval);
+  }
+
+  /**
+   * Validate action specification
+   */
+  _validateAction(action) {
+    if (!action.cmd) {
+      throw new Error('Action must have a cmd property');
+    }
+
+    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}`);
+      }
+
+      if (action.repeat.interval !== undefined && action.repeat.interval < 1) {
+        throw new Error('Repeat interval must be >= 1');
+      }
+
+      if (action.repeat.dstPolicy && !['once', 'twice'].includes(action.repeat.dstPolicy)) {
+        throw new Error('DST policy must be "once" or "twice"');
+      }
+    }
+  }
+
+  /**
+   * Static storage factory methods
+   */
+  static get storage() {
+    return {
+      file: (filePath) => new FileStorage(filePath),
+      memory: () => new MemoryStorage()
+    };
+  }
+}
+
+module.exports = Automator;

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;