jw-automator 2.0.0 → 3.1.0

package/docs/QUICKSTART.md

@@ -0,0 +1,356 @@
+# Quick Start Guide
+
+Get up and running with jw-automator v3 in 5 minutes.
+
+---
+
+## Installation
+
+```bash
+npm install jw-automator
+```
+
+---
+
+## Basic Example
+
+Create a file `app.js`:
+
+```javascript
+const Automator = require('jw-automator');
+
+// Create automator with file-based storage
+const automator = new Automator({
+  storage: Automator.storage.file('./my-actions.json')
+});
+
+// Register a function
+automator.addFunction('sayHello', function(payload) {
+  console.log(`Hello, ${payload.name}!`);
+});
+
+// Add a repeating action
+automator.addAction({
+  name: 'Greeting',
+  cmd: 'sayHello',
+  date: new Date(Date.now() + 2000), // Start in 2 seconds
+  payload: { name: 'World' },
+  repeat: {
+    type: 'second',
+    interval: 5,
+    limit: 3 // Run 3 times then stop
+  }
+});
+
+// Listen to events
+automator.on('action', (event) => {
+  console.log(`Action executed: ${event.name}`);
+});
+
+// Start the scheduler
+automator.start();
+
+console.log('Automator started! Greeting will run 3 times.');
+```
+
+Run it:
+
+```bash
+node app.js
+```
+
+---
+
+## Common Patterns
+
+### Daily Task at Specific Time
+
+```javascript
+automator.addAction({
+  name: 'Daily Backup',
+  cmd: 'runBackup',
+  date: new Date('2025-05-01T02:00:00'), // 2:00 AM
+  repeat: {
+    type: 'day',
+    interval: 1
+  }
+});
+```
+
+### Weekday Task
+
+```javascript
+automator.addAction({
+  name: 'Weekday Reminder',
+  cmd: 'sendReminder',
+  date: new Date('2025-05-01T09:00:00'), // 9:00 AM
+  repeat: {
+    type: 'weekday',
+    interval: 1 // Every weekday
+  }
+});
+```
+
+### Every N Minutes
+
+```javascript
+automator.addAction({
+  name: 'Health Check',
+  cmd: 'checkHealth',
+  date: new Date(),
+  repeat: {
+    type: 'minute',
+    interval: 15 // Every 15 minutes
+  }
+});
+```
+
+### Limited Run Count
+
+```javascript
+automator.addAction({
+  name: 'Startup Sequence',
+  cmd: 'initSystem',
+  date: new Date(),
+  repeat: {
+    type: 'second',
+    interval: 1,
+    limit: 10 // Run exactly 10 times
+  }
+});
+```
+
+### End Date
+
+```javascript
+automator.addAction({
+  name: 'Summer Sprinklers',
+  cmd: 'waterLawn',
+  date: new Date('2025-06-01T06:00:00'),
+  repeat: {
+    type: 'day',
+    interval: 1,
+    endDate: new Date('2025-09-01T00:00:00') // Stop after summer
+  }
+});
+```
+
+---
+
+## Buffered vs UnBuffered
+
+### Buffered (Default) - Catch Up Missed Events
+
+```javascript
+automator.addAction({
+  name: 'Critical Task',
+  cmd: 'criticalTask',
+  date: new Date('2025-05-01T10:00:00'),
+  unBuffered: false, // Execute even if delayed
+  repeat: { type: 'hour', interval: 1 }
+});
+```
+
+If the system is offline from 10:00 to 13:00, it will execute the 10:00, 11:00, and 12:00 occurrences when it comes back online.
+
+### UnBuffered - Skip Missed Events
+
+```javascript
+automator.addAction({
+  name: 'Animation Frame',
+  cmd: 'updateAnimation',
+  date: new Date(),
+  unBuffered: true, // Only run if on time
+  repeat: { type: 'second', interval: 1 }
+});
+```
+
+If the system is delayed, it won't execute missed animation frames.
+
+---
+
+## Simulation
+
+Preview what will happen in the future:
+
+```javascript
+const tomorrow = new Date();
+tomorrow.setDate(tomorrow.getDate() + 1);
+
+const events = automator.getActionsInRange(new Date(), tomorrow);
+
+console.log(`${events.length} events scheduled in next 24 hours`);
+
+events.slice(0, 5).forEach(event => {
+  console.log(`${event.name} at ${event.scheduledTime.toLocaleString()}`);
+});
+```
+
+---
+
+## Storage Options
+
+### File Storage
+
+```javascript
+const automator = new Automator({
+  storage: Automator.storage.file('./actions.json')
+});
+```
+
+### Memory Storage (No Persistence)
+
+```javascript
+const automator = new Automator({
+  storage: Automator.storage.memory()
+});
+```
+
+### Custom Storage
+
+```javascript
+const automator = new Automator({
+  storage: {
+    load: function() {
+      // Load from database, cloud, etc.
+      return { actions: [...] };
+    },
+    save: function(state) {
+      // Save to database, cloud, etc.
+    }
+  }
+});
+```
+
+---
+
+## Event Handling
+
+```javascript
+// Scheduler ready
+automator.on('ready', () => {
+  console.log('Scheduler started');
+});
+
+// Action executed
+automator.on('action', (event) => {
+  console.log('Action:', event.name);
+  console.log('Scheduled:', event.scheduledTime);
+  console.log('Actual:', event.actualTime);
+  console.log('Count:', event.count);
+});
+
+// Action added/updated/removed
+automator.on('update', (event) => {
+  console.log('Update:', event.operation, event.actionId);
+});
+
+// Errors
+automator.on('error', (event) => {
+  console.error('Error:', event.message);
+});
+```
+
+---
+
+## Managing Actions
+
+### Add
+
+```javascript
+const id = automator.addAction({
+  name: 'My Task',
+  cmd: 'myCommand',
+  date: new Date(),
+  repeat: { type: 'hour', interval: 1 }
+});
+```
+
+### Update
+
+```javascript
+// By ID
+automator.updateActionByID(id, {
+  name: 'Updated Task',
+  repeat: { type: 'hour', interval: 2 }
+});
+
+// By name
+automator.updateActionByName('My Task', {
+  payload: { updated: true }
+});
+```
+
+### Remove
+
+```javascript
+// By ID
+automator.removeActionByID(id);
+
+// By name
+automator.removeActionByName('My Task');
+```
+
+### Query
+
+```javascript
+// All actions
+const all = automator.getActions();
+
+// By name
+const tasks = automator.getActionsByName('My Task');
+
+// By ID
+const task = automator.getActionByID(id);
+
+// Description
+const desc = automator.describeAction(id);
+console.log(desc);
+```
+
+---
+
+## DST Handling
+
+For actions that run during daylight saving time transitions:
+
+### Fall Back (Repeated Hour)
+
+```javascript
+automator.addAction({
+  name: 'DST Aware',
+  cmd: 'task',
+  date: new Date('2025-11-02T01:30:00'), // Falls in repeated hour
+  repeat: {
+    type: 'day',
+    interval: 1,
+    dstPolicy: 'once' // Only run the first 1:30 AM
+    // or dstPolicy: 'twice' to run both
+  }
+});
+```
+
+---
+
+## Graceful Shutdown
+
+```javascript
+process.on('SIGINT', () => {
+  console.log('Shutting down...');
+  automator.stop(); // Saves state
+  process.exit(0);
+});
+```
+
+---
+
+## Next Steps
+
+- Read the full [README](../README.md)
+- Check out [examples](../examples/)
+- Review [Architecture](./ARCHITECTURE.md)
+- See [Migration Guide](./MIGRATION.md) if upgrading from v1
+
+---
+
+Happy Automating!

package/examples/basic-example.js

@@ -0,0 +1,135 @@
+/**
+ * Basic Example - jw-automator v3
+ *
+ * This example demonstrates the core features of jw-automator.
+ */
+
+const Automator = require('../index');
+
+// Create automator with file-based persistence
+const automator = new Automator({
+  storage: Automator.storage.file('./example-actions.json'),
+  autoSave: true,
+  saveInterval: 5000
+});
+
+// Register command functions
+automator.addFunction('logMessage', function(payload, event) {
+  console.log(`[${new Date().toLocaleTimeString()}] ${payload.message}`);
+  console.log(`  Scheduled: ${event.scheduledTime.toLocaleTimeString()}`);
+  console.log(`  Execution count: ${event.count + 1}`);
+});
+
+automator.addFunction('morningRoutine', function(payload) {
+  console.log('Good morning! Starting daily routine...');
+  console.log('- Check weather');
+  console.log('- Turn on coffee maker');
+  console.log('- Adjust thermostat');
+});
+
+automator.addFunction('weeklyBackup', function(payload) {
+  console.log('Running weekly backup...');
+  // Simulate backup process
+  console.log('Backup complete!');
+});
+
+// Listen to events
+automator.on('ready', () => {
+  console.log('Automator started!');
+  console.log('Current actions:', automator.getActions().length);
+});
+
+automator.on('action', (event) => {
+  console.log(`\n=== Action Executed ===`);
+  console.log(`Name: ${event.name || 'Unnamed'}`);
+  console.log(`Command: ${event.cmd}`);
+  console.log(`======================\n`);
+});
+
+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'
+  }
+});
+
+// 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);
+console.log(`${futureEvents.length} events scheduled in the next 24 hours\n`);
+
+futureEvents.slice(0, 10).forEach((event, i) => {
+  console.log(`${i + 1}. ${event.name} at ${event.scheduledTime.toLocaleString()}`);
+});
+
+if (futureEvents.length > 10) {
+  console.log(`... and ${futureEvents.length - 10} more events`);
+}
+
+console.log('\n=== Current Actions ===');
+automator.getActions().forEach((action) => {
+  console.log(automator.describeAction(action.id));
+  console.log('---');
+});
+
+// Start the automator
+console.log('\n=== Starting Automator ===\n');
+automator.start();
+
+// Graceful shutdown on Ctrl+C
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down automator...');
+  automator.stop();
+  console.log('Goodbye!');
+  process.exit(0);
+});
+
+// Keep the process running
+console.log('Press Ctrl+C to stop\n');

package/examples/hello-world.js

@@ -0,0 +1,40 @@
+/**
+ * Hello World - jw-automator v3
+ *
+ * The simplest possible example.
+ */
+
+const Automator = require('../index');
+
+// Create automator (in-memory, no persistence)
+const automator = new Automator({
+  storage: Automator.storage.memory()
+});
+
+// Register a function
+automator.addFunction('sayHello', function() {
+  console.log('Hello, World!');
+});
+
+// Add an action that runs every 3 seconds, 5 times
+automator.addAction({
+  cmd: 'sayHello',
+  date: new Date(Date.now() + 1000), // Start in 1 second
+  repeat: {
+    type: 'second',
+    interval: 3,
+    limit: 5
+  }
+});
+
+// Start the scheduler
+automator.start();
+
+console.log('Automator started! Will say hello 5 times, every 3 seconds.');
+
+// Auto-stop after 20 seconds
+setTimeout(() => {
+  automator.stop();
+  console.log('Goodbye!');
+  process.exit(0);
+}, 20000);

package/examples/iot-sensor-example.js

@@ -0,0 +1,149 @@
+/**
+ * IoT Sensor Example - jw-automator v3
+ *
+ * Demonstrates using jw-automator for sensor reading and data collection
+ * typical in IoT and home automation scenarios.
+ */
+
+const Automator = require('../index');
+
+// Create automator
+const automator = new Automator({
+  storage: Automator.storage.memory() // Use memory storage for this example
+});
+
+// Simulated sensor data
+const sensorData = {
+  temperature: 22.5,
+  humidity: 45,
+  pressure: 1013.25
+};
+
+// Simulate sensor reading
+function readSensor() {
+  sensorData.temperature += (Math.random() - 0.5) * 2;
+  sensorData.humidity += (Math.random() - 0.5) * 5;
+  sensorData.pressure += (Math.random() - 0.5) * 2;
+
+  return {
+    temperature: sensorData.temperature.toFixed(2),
+    humidity: sensorData.humidity.toFixed(1),
+    pressure: sensorData.pressure.toFixed(2),
+    timestamp: new Date()
+  };
+}
+
+// Register sensor functions
+automator.addFunction('readTemperature', function() {
+  const reading = readSensor();
+  console.log(`[TEMP] ${reading.temperature}°C at ${reading.timestamp.toLocaleTimeString()}`);
+});
+
+automator.addFunction('readHumidity', function() {
+  const reading = readSensor();
+  console.log(`[HUMID] ${reading.humidity}% at ${reading.timestamp.toLocaleTimeString()}`);
+});
+
+automator.addFunction('fullSensorSweep', function() {
+  const reading = readSensor();
+  console.log('\n=== Full Sensor Sweep ===');
+  console.log(`Time: ${reading.timestamp.toLocaleString()}`);
+  console.log(`Temperature: ${reading.temperature}°C`);
+  console.log(`Humidity: ${reading.humidity}%`);
+  console.log(`Pressure: ${reading.pressure} hPa`);
+  console.log('========================\n');
+});
+
+automator.addFunction('dailyReport', function() {
+  console.log('\n*** DAILY SENSOR REPORT ***');
+  console.log('Generated at:', new Date().toLocaleString());
+  console.log('Current readings:', readSensor());
+  console.log('Report complete.');
+  console.log('***************************\n');
+});
+
+// Add sensor reading actions
+
+// 1. Temperature reading every 5 seconds (for 1 minute demo)
+automator.addAction({
+  name: 'Temperature Reading',
+  cmd: 'readTemperature',
+  date: new Date(Date.now() + 2000),
+  unBuffered: false, // Catch up if delayed
+  repeat: {
+    type: 'second',
+    interval: 5,
+    limit: 12 // Stop after 12 readings (1 minute)
+  }
+});
+
+// 2. Humidity reading every 10 seconds
+automator.addAction({
+  name: 'Humidity Reading',
+  cmd: 'readHumidity',
+  date: new Date(Date.now() + 3000),
+  unBuffered: false,
+  repeat: {
+    type: 'second',
+    interval: 10,
+    limit: 6 // Stop after 6 readings
+  }
+});
+
+// 3. Full sensor sweep every 30 seconds
+automator.addAction({
+  name: 'Full Sensor Sweep',
+  cmd: 'fullSensorSweep',
+  date: new Date(Date.now() + 5000),
+  unBuffered: false,
+  repeat: {
+    type: 'second',
+    interval: 30,
+    limit: 3 // Stop after 3 sweeps
+  }
+});
+
+// 4. Daily report at 6:00 AM (won't run in this demo, but shows the pattern)
+const tomorrow6AM = new Date();
+tomorrow6AM.setDate(tomorrow6AM.getDate() + 1);
+tomorrow6AM.setHours(6, 0, 0, 0);
+
+automator.addAction({
+  name: 'Daily Report',
+  cmd: 'dailyReport',
+  date: tomorrow6AM,
+  unBuffered: false,
+  repeat: {
+    type: 'day',
+    interval: 1
+  }
+});
+
+// Events
+automator.on('ready', () => {
+  console.log('IoT Sensor Monitor Started');
+  console.log('================================\n');
+});
+
+automator.on('action', (event) => {
+  // Actions already log themselves
+});
+
+// Start
+automator.start();
+
+console.log('Sensor readings starting in 2 seconds...');
+console.log('This demo will run for about 90 seconds.\n');
+
+// Auto-stop after 90 seconds
+setTimeout(() => {
+  console.log('\n\nDemo complete. Stopping automator...');
+  automator.stop();
+
+  console.log('\nFinal action summary:');
+  automator.getActions().forEach(action => {
+    console.log(`- ${action.name}: ${action.count} executions`);
+  });
+
+  process.exit(0);
+}, 90000);

package/index.js

@@ -0,0 +1,7 @@
+/**
+ * jw-automator v3
+ *
+ * A resilient, local-time, 1-second precision automation scheduler for Node.js
+ */
+
+module.exports = require('./src/Automator');