jw-automator 4.0.0 → 6.0.0

package/docs/MIGRATION.md

@@ -1,3 +1,85 @@
+# Migration Guide
+
+## v5.0.0 - Storage API Simplification & Moratorium-Based Persistence
+
+### Breaking Change: Storage API Simplified
+
+The pluggable storage adapter pattern has been removed in favor of a simpler direct configuration.
+
+**Old API (v4):**
+```javascript
+const automator = new Automator({
+  storage: Automator.storage.file('./tasks.json')
+});
+
+const automator = new Automator({
+  storage: Automator.storage.memory()
+});
+```
+
+**New API (v5):**
+```javascript
+// File storage
+const automator = new Automator({
+  storageFile: './tasks.json'
+});
+
+// Memory-only mode
+const automator = new Automator({
+  // No storageFile option = memory-only
+});
+```
+
+### New: Moratorium-Based Persistence
+
+v5 introduces a moratorium-based persistence state machine that reduces disk wear:
+
+- **CRUD operations** (add/update/remove) save immediately and start a moratorium period
+- **Task execution** (state progression) marks state as dirty and saves if moratorium has expired
+- If moratorium is active, dirty state waits until moratorium ends, then saves automatically
+- **Default `saveInterval`** changed from 5000ms to **15000ms (15 seconds)**
+- `saveInterval` now defines the moratorium period (minimum cooling time between saves)
+- `stop()` always saves immediately if dirty, ignoring any active moratorium
+
+**Why this matters:** Reduces disk writes from task execution (critical for SD cards/flash media) while ensuring CRUD changes are persisted immediately. The moratorium-based approach eliminates wasteful periodic polling.
+
+### Changes Required
+
+1. **File storage:** Replace `storage: Automator.storage.file(path)` with `storageFile: path`
+2. **Memory storage:** Remove `storage: Automator.storage.memory()` entirely (omit `storageFile`)
+3. **Custom storage adapters:** No longer supported via plug-in interface
+4. **`saveInterval` default:** Changed from 5000ms to 15000ms (update if you relied on the old default)
+
+### Custom Storage Migration
+
+If you were using custom storage adapters, use this pattern instead:
+
+```javascript
+const automator = new Automator(); // Memory-only
+
+// Load from custom source on initialization
+automator.seed(async (auto) => {
+  const tasks = await yourCustomLoad();
+  tasks.forEach(task => auto.addTask(task));
+});
+
+// Save on updates
+automator.on('update', async () => {
+  const tasks = automator.getTasks();
+  await yourCustomSave(tasks);
+});
+```
+
+### Removed
+
+- `Automator.storage.file()` static method
+- `Automator.storage.memory()` static method
+- `FileStorage` class (integrated into Automator)
+- `MemoryStorage` class (no longer needed)
+- Custom storage adapter interface (`{ load(), save() }`)
+
+---
+
 # Migration Guide: v3 to v4
 
 This guide helps you migrate from jw-automator v3 to v4.
@@ -6,7 +88,7 @@ This guide helps you migrate from jw-automator v3 to v4.
 
 ## Overview
 
-jw-automator v4 is a significant refinement of v3's architecture, focusing on making the scheduler's behavior even more predictable and robust out-of-the-box. While v3 represented a complete rewrite, v4 introduces breaking changes by refining default behaviors and error handling for action specifications.
+jw-automator v4 is a significant refinement of v3's architecture, focusing on making the scheduler's behavior even more predictable and robust out-of-the-box. While v3 represented a complete rewrite, v4 introduces breaking changes by refining default behaviors and error handling for task specifications.
 
 v3 was the widely-deployed production version. v4 builds upon that foundation with enhanced predictability.
 
@@ -17,18 +99,18 @@ v3 was the widely-deployed production version. v4 builds upon that foundation wi
 ### 1. Default `catchUpWindow` Behavior Changed
 
 **v3:** If `catchUpWindow` was not specified, it defaulted to `"unlimited"` (catch up all missed executions).
-**v4:** If `catchUpWindow` is not specified, it now uses a **smart default** based on the action type:
--   For **recurring actions**, it defaults to the **duration of the recurrence interval** (e.g., an hourly action gets a 1-hour `catchUpWindow`).
--   For **one-time actions**, it defaults to **`0`** (skip all missed executions).
+**v4:** If `catchUpWindow` is not specified, it now uses a **smart default** based on the task type:
+-   For **recurring tasks**, it defaults to the **duration of the recurrence interval** (e.g., an hourly task gets a 1-hour `catchUpWindow`).
+-   For **one-time tasks**, it defaults to **`0`** (skip all missed executions).
 
-**Impact:** User applications that relied on the implicit "unlimited" catch-up for all actions in v3 might now see actions being skipped or fast-forwarded more aggressively. If you desire the old "unlimited" catch-up, you must explicitly set `catchUpWindow: "unlimited"`.
+**Impact:** User applications that relied on the implicit "unlimited" catch-up for all tasks in v3 might now see tasks being skipped or fast-forwarded more aggressively. If you desire the old "unlimited" catch-up, you must explicitly set `catchUpWindow: "unlimited"`.
 
 ### 2. Invalid `repeat.type` Throws a Fatal Error
 
 **v3:** If `repeat.type` was missing or invalid (e.g., a typo like `'horu'`), Automator would defensively coerce it to `'day'` and emit an `error` event.
 **v4:** An invalid or missing `repeat.type` now throws a hard `Error` immediately.
 
-**Impact:** Code that previously succeeded by silently allowing `repeat.type` coercions will now fail fast, forcing explicit correction. This ensures that the action's intent is never misinterpreted.
+**Impact:** Code that previously succeeded by silently allowing `repeat.type` coercions will now fail fast, forcing explicit correction. This ensures that the task's intent is never misinterpreted.
 
 ### 3. Coercion Events Changed from `error` to `warning`
 
@@ -37,36 +119,64 @@ v3 was the widely-deployed production version. v4 builds upon that foundation wi
 
 **Impact:** If your application was listening for `automator.on('error', ...)` to catch these coercion notifications, you must now update your event listener to `automator.on('warning', ...)` to continue receiving them.
 
+### 4. API Method Names Changed (action → task)
+
+**v3:** Methods used "action" terminology: `addAction`, `updateActionByID`, `getActions`, etc.
+**v4:** All methods now use "task" terminology: `addTask`, `updateTaskByID`, `getTasks`, etc.
+
+**Impact:** All API calls need to be updated to use the new method names.
+
+### 5. Event Name Changed
+
+**v3:** Task execution emitted an `'action'` event.
+**v4:** Task execution now emits a `'task'` event.
+
+**Impact:** Update event listeners from `automator.on('action', ...)` to `automator.on('task', ...)`.
+
+### 6. Event Object Properties Changed
+
+**v3:** Event objects contained `actionId` and `action` properties.
+**v4:** Event objects now contain `taskId` and `task` properties.
+
+**Impact:** Update code that accesses these properties in event handlers.
+
+### 7. State Structure Changed
+
+**v3:** State contained an `actions` array.
+**v4:** State now contains a `tasks` array.
+
+**Impact:** Custom storage adapters need to return `{ tasks: [...] }` instead of `{ actions: [...] }`. Existing stored state files need migration.
+
 ---
 
-## Breaking Changes from v3 to v4
+## Breaking Changes from v2 to v3
 
 ### 1. Constructor and Initialization
 
 **v2:**
 ```javascript
 const automator = require('jw-automator');
-automator.init({ file: './actions.json' });
+automator.init({ file: './tasks.json' });
 ```
 
 **v3:**
 ```javascript
 const Automator = require('jw-automator');
 const automator = new Automator({
-  storage: Automator.storage.file('./actions.json')
+  storage: Automator.storage.file('./tasks.json')
 });
 ```
 
-### 2. Action Structure
+### 2. Task Structure
 
 **v2:**
-Action structure was less formalized.
+Task structure was less formalized.
 
 **v3:**
 ```javascript
 {
   id: 1,              // Auto-generated
-  name: 'My Action',  // Optional
+  name: 'My Task',    // Optional
   cmd: 'commandName', // Required
   payload: {},        // Optional
   date: Date,         // Required (or null for immediate)
@@ -105,84 +215,86 @@ Various event names.
 **v3:**
 Standardized events:
 - `ready` - Scheduler started
-- `action` - Action executed
-- `update` - Action added/updated/removed
+- `task` - Task executed
+- `update` - Task added/updated/removed
 - `error` - Error occurred
 - `debug` - Debug information
 
 ### 5. API Methods
 
-#### Adding Actions
+#### Adding Tasks
 
 **v2:**
 ```javascript
-automator.addAction(actionObject);
+automator.addTask(taskObject);
 ```
 
 **v3:**
 ```javascript
-const id = automator.addAction(actionSpec);
-// Returns the action ID
+const id = automator.addTask(taskSpec);
+// Returns the task ID
 ```
 
-#### Getting Actions
+#### Getting Tasks
 
 **v2:**
 ```javascript
-const actions = automator.getActions();
+const tasks = automator.getTasks();
 ```
 
 **v3:**
 ```javascript
-const actions = automator.getActions(); // Deep copy
-const action = automator.getActionByID(id);
-const actions = automator.getActionsByName('name');
+const tasks = automator.getTasks(); // Deep copy
+const task = automator.getTaskByID(id);
+const tasks = automator.getTasksByName('name');
 ```
 
-#### Removing Actions
+#### Removing Tasks
 
 **v2:**
 ```javascript
-automator.removeAction(id);
+automator.removeTask(id);
 ```
 
 **v3:**
 ```javascript
-automator.removeActionByID(id);
-automator.removeActionByName('name'); // Returns count removed
+automator.removeTaskByID(id);
+automator.removeTaskByName('name'); // Returns count removed
 ```
 
-#### Updating Actions
+#### Updating Tasks
 
 **v2:**
 Limited update capability.
 
 **v3:**
 ```javascript
-automator.updateActionByID(id, {
+automator.updateTaskByID(id, {
   name: 'New Name',
   repeat: { type: 'hour', interval: 2 }
 });
 
-automator.updateActionByName('Old Name', {
+automator.updateTaskByName('Old Name', {
   name: 'New Name'
 });
 ```
 
 ---
 
-## New Features in v3
-
 ## New Features in v4
 
 ### 1. Smart `catchUpWindow` Defaults
 
-The new intelligent default system for `catchUpWindow` means that for most actions, you no longer need to explicitly define this property to get predictable, sensible behavior. It automatically adapts based on whether your action is one-time or recurring.
+The new intelligent default system for `catchUpWindow` means that for most tasks, you no longer need to explicitly define this property to get predictable, sensible behavior. It automatically adapts based on whether your task is one-time or recurring.
 
 ### 2. Dedicated `warning` Event
 
 A new `warning` event (`automator.on('warning', ...)`) provides a clearer channel for non-fatal feedback about defensive coercions. This allows developers to distinguish between critical runtime errors and minor data corrections.
 
+### 3. Cleaner "Task" Terminology
+
+The rename from "action" to "task" provides clearer, more intuitive naming throughout the API.
+
 ---
 
 ## New Features in v3
@@ -192,7 +304,7 @@ A new `warning` event (`automator.on('warning', ...)`) provides a clearer channe
 Preview future schedules without running them:
 
 ```javascript
-const events = automator.getActionsInRange(
+const events = automator.getTasksInRange(
   new Date('2025-05-01'),
   new Date('2025-05-07')
 );
@@ -212,7 +324,7 @@ const automator = new Automator({
 
 // File storage
 const automator = new Automator({
-  storage: Automator.storage.file('./actions.json')
+  storage: Automator.storage.file('./tasks.json')
 });
 
 // Custom storage
@@ -224,13 +336,13 @@ const automator = new Automator({
 });
 ```
 
-### 3. Action Description
+### 3. Task Description
 
-Human-readable action summaries:
+Human-readable task summaries:
 
 ```javascript
-console.log(automator.describeAction(1));
-// Action #1 - Morning Lights
+console.log(automator.describeTask(1));
+// Task #1 - Morning Lights
 //   Command: turnLightOn
 //   Next run: 5/1/2025, 7:00:00 AM
 //   Executions: 15
@@ -241,15 +353,15 @@ console.log(automator.describeAction(1));
 
 ### 4. Better Event Payloads
 
-Action events include rich metadata:
+Task events include rich metadata:
 
 ```javascript
-automator.on('action', (event) => {
+automator.on('task', (event) => {
   console.log(event);
   // {
-  //   type: 'action',
-  //   actionId: 1,
-  //   name: 'My Action',
+  //   type: 'task',
+  //   taskId: 1,
+  //   name: 'My Task',
   //   cmd: 'myCmd',
   //   payload: {},
   //   scheduledTime: Date,
@@ -265,7 +377,7 @@ Fine-tune persistence:
 
 ```javascript
 const automator = new Automator({
-  storage: Automator.storage.file('./actions.json'),
+  storage: Automator.storage.file('./tasks.json'),
   autoSave: true,
   saveInterval: 10000 // Save every 10 seconds
 });
@@ -279,20 +391,69 @@ const automator = new Automator({
 
 Thoroughly review the "Breaking Changes from v3 to v4" section above. Identify which changes affect your application.
 
-### Step 2: Review `catchUpWindow` Usage
+### Step 2: Update API Method Names
 
-If your v3 application relied on the implicit "unlimited" catch-up for actions where `catchUpWindow` was not explicitly set, you will need to:
-
--   **Explicitly set `catchUpWindow: "unlimited"`** for those actions if you wish to maintain the old behavior.
--   Otherwise, understand that these actions will now use the new smart defaults (recurrence interval for recurring, `0` for one-time actions).
+Replace all "action" method calls with "task" equivalents:
+- `addAction()` → `addTask()`
+- `updateActionByID()` → `updateTaskByID()`
+- `updateActionByName()` → `updateTaskByName()`
+- `removeActionByID()` → `removeTaskByID()`
+- `removeActionByName()` → `removeTaskByName()`
+- `getActions()` → `getTasks()`
+- `getActionsByName()` → `getTasksByName()`
+- `getActionByID()` → `getTaskByID()`
+- `getActionsInRange()` → `getTasksInRange()`
+- `describeAction()` → `describeTask()`
 
 ### Step 3: Update Event Listeners
 
+Change event listeners from `'action'` to `'task'`:
+```javascript
+// v3
+automator.on('action', (event) => { ... });
+
+// v4
+automator.on('task', (event) => { ... });
+```
+
+### Step 4: Update Event Property Access
+
+Update code that accesses event properties:
+```javascript
+// v3
+event.actionId
+event.action
+
+// v4
+event.taskId
+event.task
+```
+
+### Step 5: Migrate Stored State
+
+If using file storage, update existing state files:
+```javascript
+// v3 format
+{ "actions": [...] }
+
+// v4 format
+{ "tasks": [...] }
+```
+
+### Step 6: Review `catchUpWindow` Usage
+
+If your v3 application relied on the implicit "unlimited" catch-up for tasks where `catchUpWindow` was not explicitly set, you will need to:
+
+-   **Explicitly set `catchUpWindow: "unlimited"`** for those tasks if you wish to maintain the old behavior.
+-   Otherwise, understand that these tasks will now use the new smart defaults (recurrence interval for recurring, `0` for one-time tasks).
+
+### Step 7: Update Warning Event Listeners
+
 If your application was listening for `automator.on('error', ...)` to catch notifications about defensive coercions (e.g., invalid `repeat.interval`), you must now update your code to listen for `automator.on('warning', ...)` to receive these non-fatal messages.
 
-### Step 4: Correct Invalid `repeat.type` Definitions
+### Step 8: Correct Invalid `repeat.type` Definitions
 
-If your application previously used actions with invalid or missing `repeat.type` values that were silently corrected in v3, you must now explicitly fix these `repeat.type` values. Failure to do so will result in a hard `Error` when the action is added or updated in v4.
+If your application previously used tasks with invalid or missing `repeat.type` values that were silently corrected in v3, you must now explicitly fix these `repeat.type` values. Failure to do so will result in a hard `Error` when the task is added or updated in v4.
 
 ---
 
@@ -300,15 +461,18 @@ If your application previously used actions with invalid or missing `repeat.type
 
 ### What's the Same (v3 to v4)
 
--   **Core concepts**: Schedule actions with recurrence
+-   **Core concepts**: Schedule tasks with recurrence
 -   **Recurrence types**: `second`, `minute`, `hour`, `day`, `week`, `month`, `year`
 -   **Local time**: Still operates in local time
--   **API methods**: Names and signatures of `addAction()`, `updateActionByID()`, etc., remain the same.
 -   **Function registration**: Still use `addFunction()`
 -   **Legacy `unBuffered`**: Still supported as an alias, mapping to `catchUpWindow`.
 
 ### What's Different (v3 to v4)
 
+-   **API terminology**: "action" → "task" throughout
+-   **Event name**: `'action'` → `'task'`
+-   **Event properties**: `actionId` → `taskId`, `action` → `task`
+-   **State structure**: `actions` → `tasks`
 -   **`catchUpWindow` Default Behavior**: Now smart and context-aware, instead of always `"unlimited"`.
 -   **`repeat.type` Validation**: Invalid types now throw a fatal `Error`.
 -   **Event Handling**: Coercions now emit `warning` events instead of `error` events.