jw-automator 3.1.0 → 4.0.0

package/docs/defensive-defaults.md

@@ -0,0 +1,65 @@
+# Automator Defensive Defaults Strategy
+
+The Automator's design philosophy for handling action specifications is **"Fail loudly, run defensively."**
+
+The goal is to maximize system robustness. Rather than rejecting an action with minor errors or missing properties, the Automator will make reasonable, "defensive" assumptions to coerce the action into a valid, runnable state.
+
+However, these corrections are never silent. Whenever a default is applied or a value is coerced due to invalid input, the Automator emits either a `warning` or `debug` event. This ensures that the developer is always aware of any assumptions the system has made on their behalf.
+
+---
+
+### Property Default and Coercion Rules
+
+The following rules are applied when an action is added via `addAction()` or updated via `updateAction...()`.
+
+#### **`cmd`**
+- **Rule:** An action without a command is not runnable.
+- **Behavior:** Throws a hard `Error` if missing. This is the primary exception to the "run defensively" rule, as the action's intent cannot be determined.
+
+#### **`date`** (Start Time)
+- **Rule:** An action needs a starting time.
+- **Default:** If `date` is not provided, it defaults to **5 seconds in the future** from the time it was added.
+- **Event:** `debug`
+
+#### **`catchUpWindow`** (Smart Default)
+- **Philosophy:** The default catch-up behavior should match the user's likely intent for "server busy" vs. "server offline" scenarios. Explicit settings always take priority.
+- **Priority Rules:**
+  1.  **Explicit `catchUpWindow`:** If the property is present, it is used.
+      - `Infinity` is coerced to `"unlimited"`.
+      - Negative numbers are coerced to `0`.
+      - Invalid strings or other types are coerced to `"unlimited"`.
+      - A `warning` event is emitted for any coercion.
+  2.  **Legacy `unBuffered`:** If `catchUpWindow` is absent but the legacy `unBuffered` property is present, it is mapped for backwards compatibility:
+      - `unBuffered: true` maps to `catchUpWindow: 0` (no catch-up).
+      - `unBuffered: false` maps to `catchUpWindow: "unlimited"`.
+  3.  **Smart Default (Recurring):** If the action has a `repeat` property, `catchUpWindow` defaults to the **duration of the repeat interval** (e.g., an hourly action gets a 1-hour catch-up window).
+  4.  **Smart Default (One-Time):** If the action does not have a `repeat` property, `catchUpWindow` defaults to **`0`** (no catch-up).
+
+---
+
+### Recurrence Rules (`repeat.*`)
+
+#### **`repeat.type`**
+- **Rule:** The recurrence `type` is fundamental to the action's behavior and must be a valid string (e.g., 'hour', 'day', 'week').
+- **Behavior:** Throws a hard `Error` if missing or invalid. Unlike other properties, the ambiguity of an invalid type is considered a fatal error, as the user's intent cannot be safely determined.
+
+#### **`repeat.interval`**
+- **Rule:** The interval must be a positive integer.
+- **Default:** If `undefined`, it is `1`. If defined but invalid (e.g., `0`, `-5`, `2.5`), it is coerced to a valid integer via `Math.max(1, Math.floor(value))`.
+- **Event:** `warning` (if a value was changed).
+
+#### **`repeat.limit`**
+- **Rule:** The execution limit must be a number greater than or equal to 1.
+- **Default:** If invalid (e.g., `0`, `-10`, `'foo'`), it is coerced to `null` (unlimited).
+- **Event:** `warning`
+
+#### **`repeat.endDate`**
+- **Rule:** The end date must be a valid date representation.
+-
+- **Default:** If invalid, it is coerced to `null` (no end date).
+- **Event:** `warning`
+
+#### **`repeat.dstPolicy`**
+- **Rule:** The DST "fall back" policy must be either `'once'` or `'twice'`.
+- **Default:** If missing or invalid, it is coerced to `'once'`.
+- **Event:** `warning` (if an invalid value was provided).

package/examples/basic-example.js

@@ -50,51 +50,54 @@ automator.on('error', (event) => {
   console.error('Error:', event.message);
 });
 
-// Add actions
-
-// 1. Every 10 seconds - demo message
-automator.addAction({
-  name: 'Demo Message',
-  cmd: 'logMessage',
-  date: new Date(Date.now() + 5000), // Start in 5 seconds
-  payload: { message: 'This is a recurring message every 10 seconds' },
-  unBuffered: false,
-  repeat: {
-    type: 'second',
-    interval: 10,
-    limit: 6, // Run 6 times then stop
-    dstPolicy: 'once'
-  }
-});
-
-// 2. Daily morning routine at 7:00 AM
-automator.addAction({
-  name: 'Morning Routine',
-  cmd: 'morningRoutine',
-  date: new Date(new Date().setHours(7, 0, 0, 0)),
-  unBuffered: false,
-  repeat: {
-    type: 'day',
-    interval: 1,
-    dstPolicy: 'once'
-  }
-});
-
-// 3. Weekly backup every Sunday at 2:00 AM
-const nextSunday = new Date();
-nextSunday.setDate(nextSunday.getDate() + (7 - nextSunday.getDay()) % 7);
-nextSunday.setHours(2, 0, 0, 0);
-
-automator.addAction({
-  name: 'Weekly Backup',
-  cmd: 'weeklyBackup',
-  date: nextSunday,
-  unBuffered: false,
-  repeat: {
-    type: 'week',
-    interval: 1,
-    dstPolicy: 'once'
-  }
+// Seed initial actions (runs only on first use)
+automator.seed((auto) => {
+  console.log('Seeding initial actions...\n');
+
+  // 1. Every 10 seconds - demo message
+  auto.addAction({
+    name: 'Demo Message',
+    cmd: 'logMessage',
+    date: new Date(Date.now() + 5000), // Start in 5 seconds
+    payload: { message: 'This is a recurring message every 10 seconds' },
+    catchUpWindow: 30000, // Tolerate 30 seconds of lag
+    repeat: {
+      type: 'second',
+      interval: 10,
+      limit: 6, // Run 6 times then stop
+      dstPolicy: 'once'
+    }
+  });
+
+  // 2. Daily morning routine at 7:00 AM
+  auto.addAction({
+    name: 'Morning Routine',
+    cmd: 'morningRoutine',
+    date: new Date(new Date().setHours(7, 0, 0, 0)),
+    catchUpWindow: "unlimited", // Never miss a morning routine
+    repeat: {
+      type: 'day',
+      interval: 1,
+      dstPolicy: 'once'
+    }
+  });
+
+  // 3. Weekly backup every Sunday at 2:00 AM
+  const nextSunday = new Date();
+  nextSunday.setDate(nextSunday.getDate() + (7 - nextSunday.getDay()) % 7);
+  nextSunday.setHours(2, 0, 0, 0);
+
+  auto.addAction({
+    name: 'Weekly Backup',
+    cmd: 'weeklyBackup',
+    date: nextSunday,
+    catchUpWindow: "unlimited", // Always run backups, even if delayed
+    repeat: {
+      type: 'week',
+      interval: 1,
+      dstPolicy: 'once'
+    }
+  });
 });
 
 // Demonstrate simulation - what will happen in the next 24 hours?

package/examples/seed-example.js

@@ -0,0 +1,147 @@
+/**
+ * Seed Example - jw-automator v3
+ *
+ * Demonstrates the seed() method and catchUpWindow property.
+ * This example shows how to bootstrap a persistent scheduler that:
+ * - Initializes actions only on first run
+ * - Preserves user-modified schedules on subsequent runs
+ * - Uses catchUpWindow for smart catch-up behavior
+ */
+
+const Automator = require('../index');
+const fs = require('fs');
+
+// Storage file path
+const STORAGE_FILE = './seed-example-actions.json';
+
+// Clean up old storage file for demo purposes
+if (fs.existsSync(STORAGE_FILE)) {
+  console.log('Note: Removing existing storage file for clean demo');
+  fs.unlinkSync(STORAGE_FILE);
+}
+
+// Create automator with file-based persistence
+const automator = new Automator({
+  storage: Automator.storage.file(STORAGE_FILE),
+  autoSave: true,
+  saveInterval: 3000
+});
+
+// Register command functions
+automator.addFunction('criticalTask', function(payload, event) {
+  console.log(`[CRITICAL] ${payload.message}`);
+  console.log(`  Scheduled: ${event.scheduledTime.toLocaleTimeString()}`);
+  console.log(`  Executed: ${event.actualTime.toLocaleTimeString()}`);
+  console.log(`  Execution #${event.count + 1}`);
+});
+
+automator.addFunction('realtimeAlert', function(payload, event) {
+  console.log(`[REALTIME] ${payload.message}`);
+  console.log(`  Only executes if "now" - skips if missed`);
+});
+
+automator.addFunction('flexibleTask', function(payload, event) {
+  const lag = event.actualTime - event.scheduledTime;
+  console.log(`[FLEXIBLE] ${payload.message}`);
+  console.log(`  Lag: ${lag}ms (tolerates up to 5 seconds)`);
+});
+
+// Listen to events
+automator.on('ready', () => {
+  console.log('\n=== Automator Ready ===');
+  console.log(`Actions loaded: ${automator.getActions().length}`);
+});
+
+// SEED: Initialize actions (runs only on first use)
+const didSeed = automator.seed((auto) => {
+  console.log('\n=== SEEDING: First Run Detected ===');
+  console.log('Creating initial system tasks...\n');
+
+  // Task 1: Critical billing task - NEVER miss an execution
+  auto.addAction({
+    name: 'Billing Task',
+    cmd: 'criticalTask',
+    date: new Date(Date.now() + 2000),
+    payload: { message: 'Process billing (catchUpWindow: "unlimited")' },
+    catchUpWindow: "unlimited", // Catch up ALL missed executions
+    repeat: {
+      type: 'second',
+      interval: 10,
+      limit: 3
+    }
+  });
+
+  // Task 2: Real-time alert - only relevant "now"
+  auto.addAction({
+    name: 'Realtime Alert',
+    cmd: 'realtimeAlert',
+    date: new Date(Date.now() + 5000),
+    payload: { message: 'Temperature spike detected!' },
+    catchUpWindow: 0, // Skip ALL missed executions
+    repeat: {
+      type: 'second',
+      interval: 15,
+      limit: 3
+    }
+  });
+
+  // Task 3: Flexible sensor reading - tolerate brief lag
+  auto.addAction({
+    name: 'Sensor Reading',
+    cmd: 'flexibleTask',
+    date: new Date(Date.now() + 8000),
+    payload: { message: 'Read temperature sensor' },
+    catchUpWindow: 5000, // Tolerate up to 5 seconds of lag
+    repeat: {
+      type: 'second',
+      interval: 12,
+      limit: 3
+    }
+  });
+
+  console.log('✅ Initial tasks created!\n');
+});
+
+if (didSeed) {
+  console.log('✨ Seeding completed - tasks initialized for the first time');
+} else {
+  console.log('⏭️  Seeding skipped - existing schedule preserved');
+}
+
+console.log('\n=== Current Schedule ===');
+automator.getActions().forEach((action) => {
+  console.log(`\n${action.name}:`);
+  console.log(`  catchUpWindow: ${action.catchUpWindow === "unlimited" ? '"unlimited"' : action.catchUpWindow + 'ms'}`);
+  console.log(`  Next run: ${action.date.toLocaleTimeString()}`);
+  console.log(`  Executions so far: ${action.count}`);
+});
+
+console.log('\n=== Starting Scheduler ===\n');
+automator.start();
+
+// Simulate a brief delay after 15 seconds to demonstrate catch-up behavior
+setTimeout(() => {
+  console.log('\n⏸️  Simulating 3-second system pause...\n');
+  const start = Date.now();
+  while (Date.now() - start < 3000) {
+    // Block the event loop
+  }
+  console.log('▶️  Resumed! Watch how different catchUpWindow values behave:\n');
+}, 15000);
+
+// Auto-stop after 40 seconds
+setTimeout(() => {
+  console.log('\n=== Shutting Down ===');
+  automator.stop();
+  console.log('\n💡 Tip: Run this example again to see seeding skipped!');
+  console.log(`Storage file: ${STORAGE_FILE}`);
+  console.log('Goodbye!\n');
+  process.exit(0);
+}, 40000);
+
+// Graceful shutdown on Ctrl+C
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down...');
+  automator.stop();
+  process.exit(0);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jw-automator",
-  "version": "3.1.0",
-  "description": "A resilient, local-time, 1-second precision automation scheduler for Node.js",
+  "version": "4.0.0",
+  "description": "A resilient, local-time, 1-second precision automation scheduler for Node.js with smart defensive defaults and clear error handling",
   "main": "index.js",
   "files": [
     "src/",