jw-automator 4.0.1 → 6.0.0

package/docs/QUICKSTART.md

@@ -21,7 +21,7 @@ const Automator = require('jw-automator');
 
 // Create automator with file-based storage
 const automator = new Automator({
-  storage: Automator.storage.file('./my-actions.json')
+  storage: Automator.storage.file('./my-tasks.json')
 });
 
 // Register a function
@@ -29,8 +29,8 @@ automator.addFunction('sayHello', function(payload) {
   console.log(`Hello, ${payload.name}!`);
 });
 
-// Add a repeating action
-automator.addAction({
+// Add a repeating task
+automator.addTask({
   name: 'Greeting',
   cmd: 'sayHello',
   date: new Date(Date.now() + 2000), // Start in 2 seconds
@@ -43,8 +43,8 @@ automator.addAction({
 });
 
 // Listen to events
-automator.on('action', (event) => {
-  console.log(`Action executed: ${event.name}`);
+automator.on('task', (event) => {
+  console.log(`Task executed: ${event.name}`);
 });
 
 // Start the scheduler
@@ -66,7 +66,7 @@ node app.js
 ### Daily Task at Specific Time
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Daily Backup',
   cmd: 'runBackup',
   date: new Date('2025-05-01T02:00:00'), // 2:00 AM
@@ -80,7 +80,7 @@ automator.addAction({
 ### Weekday Task
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Weekday Reminder',
   cmd: 'sendReminder',
   date: new Date('2025-05-01T09:00:00'), // 9:00 AM
@@ -94,7 +94,7 @@ automator.addAction({
 ### Every N Minutes
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Health Check',
   cmd: 'checkHealth',
   date: new Date(),
@@ -108,7 +108,7 @@ automator.addAction({
 ### Limited Run Count
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Startup Sequence',
   cmd: 'initSystem',
   date: new Date(),
@@ -123,7 +123,7 @@ automator.addAction({
 ### End Date
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Summer Sprinklers',
   cmd: 'waterLawn',
   date: new Date('2025-06-01T06:00:00'),
@@ -143,8 +143,8 @@ Automator v4 manages offline catch-up using the `catchUpWindow` property, which
 
 ### Smart Defaults for `catchUpWindow`
 
--   **Recurring Actions:** If `catchUpWindow` is not specified, it defaults to the **duration of the action's recurrence interval**. This ensures short delays are recovered, but long outages don't cause a "thundering herd."
--   **One-Time Actions:** If `catchUpWindow` is not specified and the action has no `repeat` property, it defaults to **`0`** (skip if missed).
+-   **Recurring Tasks:** If `catchUpWindow` is not specified, it defaults to the **duration of the task's recurrence interval**. This ensures short delays are recovered, but long outages don't cause a "thundering herd."
+-   **One-Time Tasks:** If `catchUpWindow` is not specified and the task has no `repeat` property, it defaults to **`0`** (skip if missed).
 
 ### Explicit Control
 
@@ -157,7 +157,7 @@ You can explicitly set `catchUpWindow`:
 #### Example: Critical Task (unlimited catch-up)
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Critical Task',
   cmd: 'criticalTask',
   date: new Date('2025-05-01T10:00:00'),
@@ -171,7 +171,7 @@ If the system is offline from 10:00 to 13:00, it will execute the 10:00, 11:00,
 #### Example: Animation Frame (skip missed)
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'Animation Frame',
   cmd: 'updateAnimation',
   date: new Date(),
@@ -194,7 +194,7 @@ Preview what will happen in the future:
 const tomorrow = new Date();
 tomorrow.setDate(tomorrow.getDate() + 1);
 
-const events = automator.getActionsInRange(new Date(), tomorrow);
+const events = automator.getTasksInRange(new Date(), tomorrow);
 
 console.log(`${events.length} events scheduled in next 24 hours`);
 
@@ -207,35 +207,50 @@ events.slice(0, 5).forEach(event => {
 
 ## Storage Options
 
-### File Storage
+### File-Based Persistence
 
 ```javascript
 const automator = new Automator({
-  storage: Automator.storage.file('./actions.json')
+  storageFile: './tasks.json',
+  autoSave: true,        // default: true
+  saveInterval: 15000    // default: 15000ms (15 seconds)
 });
 ```
 
-### Memory Storage (No Persistence)
+**Moratorium-Based Persistence:**
+- CRUD operations (add/update/remove) save immediately and start a moratorium period
+- Task execution marks state as dirty and saves if moratorium has expired
+- `saveInterval` sets the moratorium period (minimum cooling time between saves)
+- Reduces disk wear from task execution while ensuring CRUD changes persist immediately
+- `stop()` always saves immediately if dirty, ignoring any active moratorium
+
+### Memory-Only Mode (No Persistence)
 
 ```javascript
 const automator = new Automator({
-  storage: Automator.storage.memory()
+  // No storageFile = memory-only mode
 });
 ```
 
-### Custom Storage
+State is lost when the process ends.
+
+### Custom Storage (Database, Cloud, etc.)
+
+For custom persistence, use `getTasks()` and event listeners:
 
 ```javascript
-const automator = new Automator({
-  storage: {
-    load: function() {
-      // Load from database, cloud, etc.
-      return { actions: [...] };
-    },
-    save: function(state) {
-      // Save to database, cloud, etc.
-    }
-  }
+const automator = new Automator(); // Memory-only
+
+// Load from custom source
+automator.seed(async (auto) => {
+  const tasks = await loadFromDatabase();
+  tasks.forEach(task => auto.addTask(task));
+});
+
+// Save on updates
+automator.on('update', async () => {
+  const tasks = automator.getTasks();
+  await saveToDatabase(tasks);
 });
 ```
 
@@ -249,17 +264,17 @@ automator.on('ready', () => {
   console.log('Scheduler started');
 });
 
-// Action executed
-automator.on('action', (event) => {
-  console.log('Action:', event.name);
+// Task executed
+automator.on('task', (event) => {
+  console.log('Task:', event.name);
   console.log('Scheduled:', event.scheduledTime);
   console.log('Actual:', event.actualTime);
   console.log('Count:', event.count);
 });
 
-// Action added/updated/removed
+// Task added/updated/removed
 automator.on('update', (event) => {
-  console.log('Update:', event.operation, event.actionId);
+  console.log('Update:', event.operation, event.taskId);
 });
 
 // Errors
@@ -275,12 +290,12 @@ automator.on('warning', (event) => {
 
 ---
 
-## Managing Actions
+## Managing Tasks
 
 ### Add
 
 ```javascript
-const id = automator.addAction({
+const id = automator.addTask({
   name: 'My Task',
   cmd: 'myCommand',
   date: new Date(),
@@ -292,13 +307,13 @@ const id = automator.addAction({
 
 ```javascript
 // By ID
-automator.updateActionByID(id, {
+automator.updateTaskByID(id, {
   name: 'Updated Task',
   repeat: { type: 'hour', interval: 2 }
 });
 
 // By name
-automator.updateActionByName('My Task', {
+automator.updateTaskByName('My Task', {
   payload: { updated: true }
 });
 ```
@@ -307,26 +322,26 @@ automator.updateActionByName('My Task', {
 
 ```javascript
 // By ID
-automator.removeActionByID(id);
+automator.removeTaskByID(id);
 
 // By name
-automator.removeActionByName('My Task');
+automator.removeTaskByName('My Task');
 ```
 
 ### Query
 
 ```javascript
-// All actions
-const all = automator.getActions();
+// All tasks
+const all = automator.getTasks();
 
 // By name
-const tasks = automator.getActionsByName('My Task');
+const tasks = automator.getTasksByName('My Task');
 
 // By ID
-const task = automator.getActionByID(id);
+const task = automator.getTaskByID(id);
 
 // Description
-const desc = automator.describeAction(id);
+const desc = automator.describeTask(id);
 console.log(desc);
 ```
 
@@ -334,12 +349,12 @@ console.log(desc);
 
 ## DST Handling
 
-For actions that run during daylight saving time transitions:
+For tasks that run during daylight saving time transitions:
 
 ### Fall Back (Repeated Hour)
 
 ```javascript
-automator.addAction({
+automator.addTask({
   name: 'DST Aware',
   cmd: 'task',
   date: new Date('2025-11-02T01:30:00'), // Falls in repeated hour

package/docs/defensive-defaults.md

@@ -1,8 +1,8 @@
 # Automator Defensive Defaults Strategy
 
-The Automator's design philosophy for handling action specifications is **"Fail loudly, run defensively."**
+The Automator's design philosophy for handling task 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.
+The goal is to maximize system robustness. Rather than rejecting a task with minor errors or missing properties, the Automator will make reasonable, "defensive" assumptions to coerce the task 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.
 
@@ -10,14 +10,14 @@ However, these corrections are never silent. Whenever a default is applied or a
 
 ### Property Default and Coercion Rules
 
-The following rules are applied when an action is added via `addAction()` or updated via `updateAction...()`.
+The following rules are applied when a task is added via `addTask()` or updated via `updateTask...()`.
 
 #### **`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.
+- **Rule:** A task 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 task's intent cannot be determined.
 
 #### **`date`** (Start Time)
-- **Rule:** An action needs a starting time.
+- **Rule:** A task 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`
 
@@ -32,15 +32,15 @@ The following rules are applied when an action is added via `addAction()` or upd
   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).
+  3.  **Smart Default (Recurring):** If the task has a `repeat` property, `catchUpWindow` defaults to the **duration of the repeat interval** (e.g., an hourly task gets a 1-hour catch-up window).
+  4.  **Smart Default (One-Time):** If the task 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').
+- **Rule:** The recurrence `type` is fundamental to the task'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`**

package/examples/basic-example.js

@@ -8,7 +8,7 @@ const Automator = require('../index');
 
 // Create automator with file-based persistence
 const automator = new Automator({
-  storage: Automator.storage.file('./example-actions.json'),
+  storageFile: './example-actions.json',
   autoSave: true,
   saveInterval: 5000
 });
@@ -36,7 +36,7 @@ automator.addFunction('weeklyBackup', function(payload) {
 // Listen to events
 automator.on('ready', () => {
   console.log('Automator started!');
-  console.log('Current actions:', automator.getActions().length);
+  console.log('Current actions:', automator.getTasks().length);
 });
 
 automator.on('action', (event) => {
@@ -51,11 +51,11 @@ automator.on('error', (event) => {
 });
 
 // Seed initial actions (runs only on first use)
-automator.seed((auto) => {
+const seedResult = automator.seed((auto) => {
   console.log('Seeding initial actions...\n');
 
   // 1. Every 10 seconds - demo message
-  auto.addAction({
+  const result1 = auto.addTask({
     name: 'Demo Message',
     cmd: 'logMessage',
     date: new Date(Date.now() + 5000), // Start in 5 seconds
@@ -68,9 +68,12 @@ automator.seed((auto) => {
       dstPolicy: 'once'
     }
   });
+  if (!result1.success) {
+    console.error('Failed to add demo task:', result1.error);
+  }
 
   // 2. Daily morning routine at 7:00 AM
-  auto.addAction({
+  const result2 = auto.addTask({
     name: 'Morning Routine',
     cmd: 'morningRoutine',
     date: new Date(new Date().setHours(7, 0, 0, 0)),
@@ -81,13 +84,16 @@ automator.seed((auto) => {
       dstPolicy: 'once'
     }
   });
+  if (!result2.success) {
+    console.error('Failed to add morning routine:', result2.error);
+  }
 
   // 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({
+  const result3 = auto.addTask({
     name: 'Weekly Backup',
     cmd: 'weeklyBackup',
     date: nextSunday,
@@ -98,14 +104,23 @@ automator.seed((auto) => {
       dstPolicy: 'once'
     }
   });
+  if (!result3.success) {
+    console.error('Failed to add weekly backup:', result3.error);
+  }
 });
 
+if (seedResult.seeded) {
+  console.log('✅ Database seeded successfully\n');
+} else {
+  console.log('ℹ️  Database already populated - seeding skipped\n');
+}
+
 // Demonstrate simulation - what will happen in the next 24 hours?
 console.log('\n=== Simulation: Next 24 hours ===');
 const now = new Date();
 const tomorrow = new Date(now.getTime() + 24 * 60 * 60 * 1000);
 
-const futureEvents = automator.getActionsInRange(now, tomorrow);
+const futureEvents = automator.getTasksInRange(now, tomorrow);
 console.log(`${futureEvents.length} events scheduled in the next 24 hours\n`);
 
 futureEvents.slice(0, 10).forEach((event, i) => {
@@ -117,8 +132,8 @@ if (futureEvents.length > 10) {
 }
 
 console.log('\n=== Current Actions ===');
-automator.getActions().forEach((action) => {
-  console.log(automator.describeAction(action.id));
+automator.getTasks().forEach((action) => {
+  console.log(automator.describeTask(action.id));
   console.log('---');
 });
 

package/examples/hello-world.js

@@ -8,7 +8,7 @@ const Automator = require('../index');
 
 // Create automator (in-memory, no persistence)
 const automator = new Automator({
-  storage: Automator.storage.memory()
+  // No storageFile = memory-only mode
 });
 
 // Register a function
@@ -17,7 +17,7 @@ automator.addFunction('sayHello', function() {
 });
 
 // Add an action that runs every 3 seconds, 5 times
-automator.addAction({
+automator.addTask({
   cmd: 'sayHello',
   date: new Date(Date.now() + 1000), // Start in 1 second
   repeat: {

package/examples/iot-sensor-example.js

@@ -9,7 +9,7 @@ const Automator = require('../index');
 
 // Create automator
 const automator = new Automator({
-  storage: Automator.storage.memory() // Use memory storage for this example
+  // Memory-only mode (no persistence)
 });
 
 // Simulated sensor data
@@ -65,7 +65,7 @@ automator.addFunction('dailyReport', function() {
 // Add sensor reading actions
 
 // 1. Temperature reading every 5 seconds (for 1 minute demo)
-automator.addAction({
+automator.addTask({
   name: 'Temperature Reading',
   cmd: 'readTemperature',
   date: new Date(Date.now() + 2000),
@@ -78,7 +78,7 @@ automator.addAction({
 });
 
 // 2. Humidity reading every 10 seconds
-automator.addAction({
+automator.addTask({
   name: 'Humidity Reading',
   cmd: 'readHumidity',
   date: new Date(Date.now() + 3000),
@@ -91,7 +91,7 @@ automator.addAction({
 });
 
 // 3. Full sensor sweep every 30 seconds
-automator.addAction({
+automator.addTask({
   name: 'Full Sensor Sweep',
   cmd: 'fullSensorSweep',
   date: new Date(Date.now() + 5000),
@@ -108,7 +108,7 @@ const tomorrow6AM = new Date();
 tomorrow6AM.setDate(tomorrow6AM.getDate() + 1);
 tomorrow6AM.setHours(6, 0, 0, 0);
 
-automator.addAction({
+automator.addTask({
   name: 'Daily Report',
   cmd: 'dailyReport',
   date: tomorrow6AM,
@@ -141,7 +141,7 @@ setTimeout(() => {
   automator.stop();
 
   console.log('\nFinal action summary:');
-  automator.getActions().forEach(action => {
+  automator.getTasks().forEach(action => {
     console.log(`- ${action.name}: ${action.count} executions`);
   });
 

package/examples/seed-example.js

@@ -22,7 +22,7 @@ if (fs.existsSync(STORAGE_FILE)) {
 
 // Create automator with file-based persistence
 const automator = new Automator({
-  storage: Automator.storage.file(STORAGE_FILE),
+  storageFile: STORAGE_FILE,
   autoSave: true,
   saveInterval: 3000
 });
@@ -49,7 +49,7 @@ automator.addFunction('flexibleTask', function(payload, event) {
 // Listen to events
 automator.on('ready', () => {
   console.log('\n=== Automator Ready ===');
-  console.log(`Actions loaded: ${automator.getActions().length}`);
+  console.log(`Actions loaded: ${automator.getTasks().length}`);
 });
 
 // SEED: Initialize actions (runs only on first use)
@@ -58,7 +58,7 @@ const didSeed = automator.seed((auto) => {
   console.log('Creating initial system tasks...\n');
 
   // Task 1: Critical billing task - NEVER miss an execution
-  auto.addAction({
+  auto.addTask({
     name: 'Billing Task',
     cmd: 'criticalTask',
     date: new Date(Date.now() + 2000),
@@ -72,7 +72,7 @@ const didSeed = automator.seed((auto) => {
   });
 
   // Task 2: Real-time alert - only relevant "now"
-  auto.addAction({
+  auto.addTask({
     name: 'Realtime Alert',
     cmd: 'realtimeAlert',
     date: new Date(Date.now() + 5000),
@@ -86,7 +86,7 @@ const didSeed = automator.seed((auto) => {
   });
 
   // Task 3: Flexible sensor reading - tolerate brief lag
-  auto.addAction({
+  auto.addTask({
     name: 'Sensor Reading',
     cmd: 'flexibleTask',
     date: new Date(Date.now() + 8000),
@@ -109,7 +109,7 @@ if (didSeed) {
 }
 
 console.log('\n=== Current Schedule ===');
-automator.getActions().forEach((action) => {
+automator.getTasks().forEach((action) => {
   console.log(`\n${action.name}:`);
   console.log(`  catchUpWindow: ${action.catchUpWindow === "unlimited" ? '"unlimited"' : action.catchUpWindow + 'ms'}`);
   console.log(`  Next run: ${action.date.toLocaleTimeString()}`);

package/package.json

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