@quarry-systems/drift-timer 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,308 @@
+# MCG Timer Plugin
+
+A comprehensive timer and scheduling plugin for Managed Cyclic Graph (MCG) that enables nodes to delay execution, wait for specific times, and schedule based on cron-like patterns.
+
+## Features
+
+- ✅ **Simple Delays**: Sleep for a specified duration
+- ✅ **Scheduled Waits**: Wait until a specific date/time
+- ✅ **Cron Patterns**: Daily, weekly, monthly scheduling
+- ✅ **Business Days**: Skip weekends automatically
+- ✅ **Flexible Storage**: Custom paths for timer metadata
+- ✅ **Callbacks**: onStart and onComplete hooks
+- ✅ **Two Usage Modes**: Plugin-based or action-based
+
+## Installation
+
+```bash
+npm install @quarry-systems/drift-timer
+```
+
+## Quick Start
+
+### Plugin-Based Approach
+
+```typescript
+import { ManagedCyclicGraph } from '@quarry-systems/managed-cyclic-graph';
+import { mcgTimerPlugin, sleep, dailyAt } from '@quarry-systems/drift-timer';
+
+const graph = new ManagedCyclicGraph()
+  .use(mcgTimerPlugin)
+  
+  .node('wait5sec', {
+    type: 'timernode',
+    meta: {
+      timer: sleep(5000)  // Wait 5 seconds
+    }
+  })
+  
+  .node('dailyReport', {
+    type: 'timernode',
+    meta: {
+      timer: dailyAt(9, 0)  // Wait until 9:00 AM
+    }
+  })
+  
+  .build();
+```
+
+### Action-Based Approach
+
+```typescript
+import { ManagedCyclicGraph } from '@quarry-systems/managed-cyclic-graph';
+import { createTimerAction, sleep, nextBusinessDay } from '@quarry-systems/drift-timer';
+
+const graph = new ManagedCyclicGraph()
+  .node('processOrder', {
+    execute: [
+      // ... process order logic
+    ]
+  })
+  
+  .node('waitForBusinessDay', {
+    execute: [
+      createTimerAction('waitForBusinessDay', nextBusinessDay(9, 0))
+    ]
+  })
+  
+  .node('sendReport', {
+    execute: [
+      // ... send report logic
+    ]
+  })
+  
+  .build();
+```
+
+## API Reference
+
+### Helper Functions
+
+#### `sleep(ms: number)`
+Sleep for a specified duration in milliseconds.
+
+```typescript
+sleep(5000)  // Sleep for 5 seconds
+sleep(60000) // Sleep for 1 minute
+```
+
+#### `waitUntil(date: Date | string | number)`
+Wait until a specific date/time.
+
+```typescript
+waitUntil(new Date('2024-12-25T00:00:00'))
+waitUntil('2024-12-25T00:00:00')
+waitUntil(Date.now() + 3600000)  // 1 hour from now
+```
+
+#### `dailyAt(hour: number, minute?: number)`
+Wait until the next occurrence of a specific time each day.
+
+```typescript
+dailyAt(9, 0)   // Wait until 9:00 AM
+dailyAt(17, 30) // Wait until 5:30 PM
+```
+
+#### `weeklyAt(dayOfWeek: number, hour: number, minute?: number)`
+Wait until the next occurrence of a specific day and time each week.
+
+```typescript
+weeklyAt(1, 9, 0)  // Monday at 9:00 AM (0=Sunday, 1=Monday, ...)
+weeklyAt(5, 17, 0) // Friday at 5:00 PM
+```
+
+#### `nextBusinessDay(hour?: number, minute?: number)`
+Wait until the next business day (skips weekends) at the specified time.
+
+```typescript
+nextBusinessDay()       // Next business day at midnight
+nextBusinessDay(9, 0)   // Next business day at 9:00 AM
+nextBusinessDay(8, 30)  // Next business day at 8:30 AM
+```
+
+### Configuration Options
+
+```typescript
+interface TimerConfig {
+  sleepMs?: number;              // Sleep duration in milliseconds
+  waitUntil?: Date | string | number;  // Target date/time
+  cronPattern?: CronPattern;     // Cron-like scheduling
+  storePath?: string;            // Custom storage path
+  onStart?: (ctx) => void;       // Callback when timer starts
+  onComplete?: (ctx) => void;    // Callback when timer completes
+}
+```
+
+### Cron Pattern Options
+
+```typescript
+interface CronPattern {
+  type: 'daily' | 'weekly' | 'monthly' | 'custom';
+  hour?: number;          // Hour (0-23)
+  minute?: number;        // Minute (0-59)
+  dayOfWeek?: number;     // Day of week (0-6, Sunday=0)
+  dayOfMonth?: number;    // Day of month (1-31)
+  skipWeekends?: boolean; // Skip Saturday/Sunday
+  expression?: string;    // Custom cron expression (future)
+}
+```
+
+## Examples
+
+### Retry with Exponential Backoff
+
+```typescript
+const graph = new ManagedCyclicGraph()
+  .use(mcgTimerPlugin)
+  
+  .node('attempt1', {
+    execute: [/* try operation */]
+  })
+  
+  .node('wait1', {
+    type: 'timernode',
+    meta: { timer: sleep(1000) }  // Wait 1 second
+  })
+  
+  .node('attempt2', {
+    execute: [/* retry operation */]
+  })
+  
+  .node('wait2', {
+    type: 'timernode',
+    meta: { timer: sleep(2000) }  // Wait 2 seconds
+  })
+  
+  .node('attempt3', {
+    execute: [/* final retry */]
+  })
+  
+  .build();
+```
+
+### Daily Report Generation
+
+```typescript
+const graph = new ManagedCyclicGraph()
+  .use(mcgTimerPlugin)
+  
+  .node('waitForMorning', {
+    type: 'timernode',
+    meta: {
+      timer: dailyAt(8, 0)  // Every day at 8:00 AM
+    }
+  })
+  
+  .node('generateReport', {
+    execute: [/* generate report */]
+  })
+  
+  .node('sendReport', {
+    execute: [/* send report */]
+  })
+  
+  // Loop back to wait for next day
+  .edge('sendReport', 'waitForMorning', 'any')
+  
+  .build();
+```
+
+### Weekend-Aware Processing
+
+```typescript
+const graph = new ManagedCyclicGraph()
+  .use(mcgTimerPlugin)
+  
+  .node('checkData', {
+    execute: [/* check for new data */]
+  })
+  
+  .node('waitForBusinessDay', {
+    type: 'timernode',
+    meta: {
+      timer: nextBusinessDay(9, 0)
+    }
+  })
+  
+  .node('processData', {
+    execute: [/* process during business hours */]
+  })
+  
+  .build();
+```
+
+### With Callbacks
+
+```typescript
+const graph = new ManagedCyclicGraph()
+  .use(mcgTimerPlugin)
+  
+  .node('scheduledTask', {
+    type: 'timernode',
+    meta: {
+      timer: {
+        ...dailyAt(10, 0),
+        onStart: (ctx) => {
+          console.log('Timer started, waiting until 10:00 AM');
+        },
+        onComplete: (ctx) => {
+          console.log('Timer completed, executing task now');
+        }
+      }
+    }
+  })
+  
+  .build();
+```
+
+## Metadata Storage
+
+Timer metadata is stored in the context at `data.timer.{nodeId}` by default:
+
+```typescript
+{
+  data: {
+    timer: {
+      wait5sec: {
+        startTime: 1701234567890,
+        targetTime: 1701234572890,
+        duration: 5000,
+        completed: true
+      }
+    }
+  }
+}
+```
+
+You can customize the storage path:
+
+```typescript
+{
+  timer: {
+    ...sleep(5000),
+    storePath: 'data.customPath.myTimer'
+  }
+}
+```
+
+## Use Cases
+
+- **Rate Limiting**: Add delays between API calls
+- **Retry Logic**: Wait before retrying failed operations
+- **Scheduled Tasks**: Run tasks at specific times
+- **Business Hours**: Ensure operations run during business days
+- **Cooldown Periods**: Enforce waiting periods between actions
+- **Batch Processing**: Wait for batch windows
+- **Compliance**: Respect time-based regulations
+
+## Best Practices
+
+1. **Use Business Day Scheduling** for operations that should only run during work hours
+2. **Add Callbacks** for logging and monitoring timer events
+3. **Store Metadata** in custom paths when you need to track multiple timers
+4. **Combine with Guards** to create conditional timing logic
+5. **Use Action-Based** approach when mixing timers with other actions
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@quarry-systems/drift-timer",
+  "version": "0.1.0-alpha.1",
+  "description": "Timer and scheduling plugin for Drift",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "rimraf dist || rm -rf dist",
+    "dev": "tsc -p . --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "drift",
+    "plugin",
+    "timer",
+    "delay",
+    "schedule",
+    "cron"
+  ],
+  "author": "Brett Nye",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "CHANGELOG.md"
+  ],
+  "type": "commonjs"
+}