s3db.js 9.1.0 → 9.2.1

package/PLUGINS.md

@@ -18,6 +18,9 @@
   - [📊 Metrics Plugin](#-metrics-plugin)
   - [🔄 Replicator Plugin](#-replicator-plugin)
   - [📬 Queue Consumer Plugin](#-queue-consumer-plugin)
+  - [🤖 State Machine Plugin](#-state-machine-plugin)
+  - [💾 Backup Plugin](#-backup-plugin)
+  - [⏰ Scheduler Plugin](#-scheduler-plugin)
 - [🔧 Plugin Development](#-plugin-development)
 - [💡 Plugin Combinations](#-plugin-combinations)
 - [🎯 Best Practices](#-best-practices)
@@ -26,22 +29,68 @@
 
 ## 🚀 Getting Started with Plugins
 
-Plugins extend s3db.js with additional functionality. They can be used individually or combined for powerful workflows.
+Plugins extend s3db.js with additional functionality using a **driver-based architecture**. They can be used individually or combined for powerful workflows.
+
+### Plugin Architecture
+
+Most s3db.js plugins follow a **driver pattern** where you specify:
+- **`driver`**: The storage/connection type (`filesystem`, `s3`, `multi`, etc.)
+- **`config`**: Driver-specific configuration options
+- **Plugin options**: Global settings that apply across drivers
 
 ### Basic Plugin Usage
 
 ```javascript
-import { S3db, CachePlugin, CostsPlugin } from 's3db.js';
+import { S3db, CachePlugin, BackupPlugin, CostsPlugin } from 's3db.js';
 
 const s3db = new S3db({
-  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
-  plugins: [
-    new CachePlugin(),
-    CostsPlugin // Some plugins are static objects
-  ]
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp"
 });
 
 await s3db.connect();
+
+// Driver-based plugins (most common)
+await s3db.usePlugin(new CachePlugin({
+  driver: 'memory',
+  config: { maxSize: 1000 }
+}));
+
+await s3db.usePlugin(new BackupPlugin({
+  driver: 'filesystem',
+  config: { path: './backups/{date}/' }
+}));
+
+// Static utility plugins
+await s3db.usePlugin(CostsPlugin);
+```
+
+### Driver-Based Configuration Pattern
+
+```javascript
+// Single driver example
+new SomePlugin({
+  driver: 'driverType',
+  config: {
+    // Driver-specific options
+    option1: 'value1',
+    option2: 'value2'
+  },
+  // Global plugin options
+  verbose: true,
+  timeout: 30000
+});
+
+// Multi-driver example  
+new SomePlugin({
+  driver: 'multi',
+  config: {
+    strategy: 'all',
+    destinations: [
+      { driver: 'driver1', config: {...} },
+      { driver: 'driver2', config: {...} }
+    ]
+  }
+});
 ```
 
 ### Plugin Types
@@ -57,24 +106,72 @@ await s3db.connect();
 
 ## 💾 Cache Plugin
 
-Intelligent caching system that reduces S3 API calls and improves performance by storing frequently accessed data in memory or S3.
+**Driver-Based Caching System** - Intelligent caching that reduces S3 API calls and improves performance using configurable storage drivers.
 
-### ⚡ Quick Start
+> 🏎️ **Performance**: Dramatically reduces S3 costs and latency by caching frequently accessed data.
+
+### 🚀 Quick Start
 
+#### Memory Driver (Fast & Temporary)
 ```javascript
 import { S3db, CachePlugin } from 's3db.js';
 
 const s3db = new S3db({
   connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
-  plugins: [new CachePlugin()]
+  plugins: [
+    new CachePlugin({
+      driver: 'memory',
+      ttl: 300000,        // 5 minutes
+      maxSize: 1000,      // Max 1000 items
+      config: {
+        evictionPolicy: 'lru',
+        enableStats: true
+      }
+    })
+  ]
 });
 
 await s3db.connect();
 
-// Cache is automatically used for read operations
+// Cache automatically intercepts read operations
 const users = s3db.resource('users');
-await users.count(); // Cached for default TTL
-await users.list();  // Cached result
+await users.count(); // ⚡ Cached for 5 minutes
+await users.list();  // ⚡ Cached result
+```
+
+#### S3 Driver (Persistent & Shared)
+```javascript
+const s3db = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [
+    new CachePlugin({
+      driver: 's3',
+      ttl: 1800000,       // 30 minutes
+      config: {
+        bucket: 'my-cache-bucket',    // Optional: separate bucket
+        keyPrefix: 'cache/',          // Cache key prefix
+        storageClass: 'STANDARD'      // S3 storage class
+      }
+    })
+  ]
+});
+```
+
+#### Filesystem Driver (Local & Fast)
+```javascript
+const s3db = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [
+    new CachePlugin({
+      driver: 'filesystem',
+      config: {
+        path: './cache',
+        partitionAware: true,
+        partitionStrategy: 'hierarchical'
+      }
+    })
+  ]
+});
 ```
 
 ### ⚙️ Configuration Parameters
@@ -4143,6 +4240,758 @@ const s3db = new S3db({
 
 ---
 
+## 🤖 State Machine Plugin
+
+Finite state machine capabilities for managing complex workflows and business processes with well-defined states and transitions.
+
+### ⚡ Quick Start
+
+```javascript
+import { S3db, StateMachinePlugin } from 's3db.js';
+
+const s3db = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [
+    new StateMachinePlugin({
+      stateMachines: {
+        order_processing: {
+          initialState: 'pending',
+          states: {
+            pending: {
+              on: { CONFIRM: 'confirmed', CANCEL: 'cancelled' }
+            },
+            confirmed: {
+              on: { PREPARE: 'preparing', CANCEL: 'cancelled' },
+              entry: 'onConfirmed'
+            },
+            preparing: {
+              on: { SHIP: 'shipped', CANCEL: 'cancelled' },
+              guards: { SHIP: 'canShip' }
+            },
+            shipped: {
+              on: { DELIVER: 'delivered', RETURN: 'returned' }
+            },
+            delivered: { type: 'final' },
+            cancelled: { type: 'final' },
+            returned: { type: 'final' }
+          }
+        }
+      },
+      actions: {
+        onConfirmed: async (context, event, machine) => {
+          console.log(`Order ${context.id} confirmed!`);
+          return { action: 'confirmed', timestamp: new Date() };
+        }
+      },
+      guards: {
+        canShip: async (context, event, machine) => {
+          const inventory = await machine.database.resource('inventory').get(context.productId);
+          return inventory && inventory.quantity >= context.quantity;
+        }
+      }
+    })
+  ]
+});
+
+await s3db.connect();
+
+// Initialize entity with state machine
+await s3db.plugins.stateMachine.initializeEntity('order_processing', 'order123');
+
+// Send events to trigger transitions
+await s3db.plugins.stateMachine.send('order_processing', 'order123', 'CONFIRM', {
+  id: 'order123',
+  productId: 'prod1',
+  quantity: 2
+});
+
+// Get current state
+const state = await s3db.plugins.stateMachine.getState('order_processing', 'order123');
+console.log('Current state:', state); // 'confirmed'
+```
+
+### ⚙️ Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `stateMachines` | object | `{}` | State machine definitions |
+| `actions` | object | `{}` | Action functions for state entry/exit |
+| `guards` | object | `{}` | Guard functions for transition validation |
+| `persistTransitions` | boolean | `true` | Store transition history in database |
+| `transitionLogResource` | string | `'transitions'` | Resource name for transition log |
+| `stateResource` | string | `'entity_states'` | Resource name for current states |
+| `verbose` | boolean | `false` | Enable detailed logging |
+
+### State Machine Definition Structure
+
+```javascript
+stateMachines: {
+  machine_name: {
+    initialState: 'start_state',
+    states: {
+      state_name: {
+        on: { EVENT_NAME: 'target_state' },     // Transitions
+        entry: 'action_name',                   // Action on state entry
+        exit: 'action_name',                    // Action on state exit
+        guards: { EVENT_NAME: 'guard_name' },   // Transition guards
+        meta: { custom: 'metadata' },          // Additional metadata
+        type: 'final'                          // Mark as final state
+      }
+    }
+  }
+}
+```
+
+### API Methods
+
+```javascript
+// Entity management
+await stateMachine.initializeEntity(machineId, entityId, context);
+const state = await stateMachine.getState(machineId, entityId);
+const result = await stateMachine.send(machineId, entityId, event, context);
+
+// State information
+const events = stateMachine.getValidEvents(machineId, entityId);
+const definition = stateMachine.getMachineDefinition(machineId);
+const machines = stateMachine.getMachines();
+
+// History and visualization
+const history = await stateMachine.getTransitionHistory(machineId, entityId);
+const dot = stateMachine.visualize(machineId); // Graphviz DOT format
+```
+
+### Events
+
+```javascript
+stateMachine.on('initialized', ({ machines }) => {
+  console.log('Initialized machines:', machines);
+});
+
+stateMachine.on('transition', ({ machineId, entityId, from, to, event, context }) => {
+  console.log(`${entityId}: ${from} → ${to} via ${event}`);
+});
+
+stateMachine.on('action_error', ({ actionName, error, machineId, entityId }) => {
+  console.error(`Action ${actionName} failed:`, error);
+});
+```
+
+---
+
+## 💾 Backup Plugin
+
+**Driver-Based Backup System** - Comprehensive database backup and restore capabilities with configurable drivers, compression, encryption, and retention policies.
+
+> ⚡ **NEW**: Driver-based architecture supports filesystem, S3, and multi-destination backups with flexible strategies.
+
+### 🚀 Quick Start
+
+#### Single Driver (Filesystem)
+```javascript
+import { S3db, BackupPlugin } from 's3db.js';
+
+const s3db = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp"
+});
+
+await s3db.connect();
+
+// Install backup plugin with filesystem driver
+const backupPlugin = new BackupPlugin({
+  driver: 'filesystem',
+  config: {
+    path: './backups/{date}/',
+    compression: 'gzip'
+  },
+  retention: {
+    daily: 7,
+    weekly: 4,
+    monthly: 12
+  }
+});
+
+await s3db.usePlugin(backupPlugin);
+
+// Create backups
+const fullBackup = await backupPlugin.backup('full');
+console.log('Backup ID:', fullBackup.id);
+
+// List and restore
+const backups = await backupPlugin.listBackups();
+await backupPlugin.restore(fullBackup.id);
+```
+
+#### Single Driver (S3)
+```javascript
+const backupPlugin = new BackupPlugin({
+  driver: 's3',
+  config: {
+    bucket: 'my-backup-bucket',
+    path: 'database/{date}/',
+    storageClass: 'STANDARD_IA',
+    serverSideEncryption: 'AES256'
+  },
+  compression: 'gzip',
+  verification: true
+});
+```
+
+#### Multi-Driver (Multiple Destinations)
+```javascript
+const backupPlugin = new BackupPlugin({
+  driver: 'multi',
+  config: {
+    strategy: 'all', // 'all', 'any', 'priority'
+    destinations: [
+      { 
+        driver: 'filesystem', 
+        config: { path: '/local/backups/{date}/' } 
+      },
+      { 
+        driver: 's3', 
+        config: { 
+          bucket: 'remote-backups',
+          storageClass: 'GLACIER'
+        } 
+      }
+    ]
+  }
+});
+```
+
+### 🎯 Driver Types
+
+#### 📁 Filesystem Driver
+**Perfect for**: Local backups, network storage, development
+
+```javascript
+{
+  driver: 'filesystem',
+  config: {
+    path: '/backups/{date}/',           // Template path with variables
+    permissions: 0o644,                 // File permissions  
+    directoryPermissions: 0o755         // Directory permissions
+  }
+}
+```
+
+**Path Templates:**
+- `{date}` → `2024-03-15`
+- `{time}` → `14-30-45`
+- `{year}` → `2024`
+- `{month}` → `03`
+- `{day}` → `15`
+- `{backupId}` → `full-2024-03-15T14-30-45-abc123`
+- `{type}` → `full` | `incremental`
+
+#### ☁️ S3 Driver
+**Perfect for**: Cloud backups, long-term storage, disaster recovery
+
+```javascript
+{
+  driver: 's3',
+  config: {
+    bucket: 'my-backup-bucket',         // S3 bucket (optional, uses database bucket)
+    path: 'backups/{date}/',            // S3 key prefix with templates
+    storageClass: 'STANDARD_IA',        // S3 storage class
+    serverSideEncryption: 'AES256',     // Server-side encryption
+    client: customS3Client              // Custom S3 client (optional)
+  }
+}
+```
+
+**Storage Classes:** `STANDARD`, `STANDARD_IA`, `ONEZONE_IA`, `REDUCED_REDUNDANCY`, `GLACIER`, `DEEP_ARCHIVE`
+
+#### 🔄 Multi Driver
+**Perfect for**: Redundancy, hybrid storage, complex backup strategies
+
+```javascript
+{
+  driver: 'multi',
+  config: {
+    strategy: 'all',                    // Backup strategy
+    concurrency: 3,                     // Max concurrent uploads
+    destinations: [
+      { driver: 'filesystem', config: {...} },
+      { driver: 's3', config: {...} }
+    ]
+  }
+}
+```
+
+**Strategies:**
+- **`all`**: Upload to all destinations (fail if any fails)
+- **`any`**: Upload to all, succeed if at least one succeeds  
+- **`priority`**: Try destinations in order, stop on first success
+
+### 🔧 Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| **`driver`** | `string` | `'filesystem'` | Driver type: `filesystem`, `s3`, `multi` |
+| **`config`** | `object` | `{}` | Driver-specific configuration |
+| `retention` | `object` | `{}` | Retention policy (GFS rotation) |
+| `include` | `array` | `null` | Resources to include (null = all) |
+| `exclude` | `array` | `[]` | Resources to exclude |
+| `compression` | `string` | `'gzip'` | `'none'`, `'gzip'`, `'brotli'`, `'deflate'` |
+| `encryption` | `object` | `null` | Encryption configuration |
+| `verification` | `boolean` | `true` | Verify backup integrity |
+| `tempDir` | `string` | `'./tmp/backups'` | Temporary working directory |
+| `verbose` | `boolean` | `false` | Enable detailed logging |
+
+### 🎛️ Backup Types & Operations
+
+```javascript
+// Full backup - complete database snapshot
+const fullBackup = await backupPlugin.backup('full');
+console.log(`✓ Full backup: ${fullBackup.id} (${fullBackup.size} bytes)`);
+
+// Incremental backup - changes since last backup  
+const incrementalBackup = await backupPlugin.backup('incremental');
+
+// Selective backup - specific resources only
+const selectiveBackup = await backupPlugin.backup('full', {
+  resources: ['users', 'posts']
+});
+
+// Custom backup type
+const customBackup = await backupPlugin.backup('weekly-snapshot');
+```
+
+### 📋 Backup Management
+
+```javascript
+// List all backups
+const allBackups = await backupPlugin.listBackups();
+
+// List with filters
+const recentBackups = await backupPlugin.listBackups({
+  limit: 10,
+  prefix: 'full-2024'
+});
+
+// Get backup status
+const status = await backupPlugin.getBackupStatus(backupId);
+console.log(`Status: ${status.status}, Size: ${status.size}`);
+
+// Restore operations
+await backupPlugin.restore(backupId);                    // Full restore
+await backupPlugin.restore(backupId, { overwrite: true }); // Overwrite existing
+await backupPlugin.restore(backupId, { 
+  resources: ['users'] 
+}); // Selective restore
+```
+
+### 🔄 Legacy Format Support
+
+The plugin automatically converts legacy `destinations` format:
+
+```javascript
+// ❌ Old format (still works)
+new BackupPlugin({
+  destinations: [
+    { type: 'filesystem', path: '/backups/' }
+  ]
+});
+
+// ✅ Automatically converted to:
+// driver: 'multi'
+// config: { destinations: [{ driver: 'filesystem', config: { path: '/backups/' } }] }
+```
+
+### 📊 Retention Policies (GFS)
+
+Grandfather-Father-Son rotation keeps backups efficiently:
+
+```javascript
+retention: {
+  daily: 7,      // Keep 7 daily backups
+  weekly: 4,     // Keep 4 weekly backups  
+  monthly: 12,   // Keep 12 monthly backups
+  yearly: 3      // Keep 3 yearly backups
+}
+```
+
+### 🎣 Hooks & Events
+
+```javascript
+const backupPlugin = new BackupPlugin({
+  driver: 'filesystem',
+  config: { path: './backups/' },
+  
+  // Lifecycle hooks
+  onBackupStart: async (type, { backupId }) => {
+    console.log(`🚀 Starting ${type} backup: ${backupId}`);
+    await notifySlack(`Backup ${backupId} started`);
+  },
+  
+  onBackupComplete: async (type, stats) => {
+    console.log(`✅ ${type} backup completed:`, {
+      id: stats.backupId,
+      size: `${Math.round(stats.size / 1024)}KB`,
+      duration: `${stats.duration}ms`,
+      destinations: stats.driverInfo
+    });
+  },
+  
+  onBackupError: async (type, { backupId, error }) => {
+    console.error(`❌ Backup ${backupId} failed:`, error.message);
+    await alertOps(error);
+  }
+});
+
+// Event listeners
+backupPlugin.on('backup_start', ({ id, type }) => {
+  updateDashboard(`Backup ${id} started`);
+});
+
+backupPlugin.on('backup_complete', ({ id, type, size, duration }) => {
+  metrics.record('backup.completed', { type, size, duration });
+});
+
+backupPlugin.on('restore_complete', ({ id, restored }) => {
+  console.log(`Restored ${restored.length} resources from ${id}`);
+});
+```
+
+### 🔒 Advanced Security
+
+```javascript
+const secureBackupPlugin = new BackupPlugin({
+  driver: 's3',
+  config: {
+    bucket: 'secure-backups',
+    storageClass: 'STANDARD_IA',
+    serverSideEncryption: 'aws:kms',
+    kmsKeyId: 'arn:aws:kms:region:account:key/key-id'
+  },
+  
+  // Client-side encryption (before upload)
+  encryption: {
+    algorithm: 'AES-256-GCM',
+    key: process.env.BACKUP_ENCRYPTION_KEY,
+    keyDerivation: {
+      algorithm: 'PBKDF2',
+      iterations: 100000,
+      salt: 'backup-salt-2024'
+    }
+  },
+  
+  // Integrity verification
+  verification: true,
+  
+  // Compression for efficiency
+  compression: 'gzip'
+});
+```
+
+### 🚀 Production Examples
+
+#### Enterprise Multi-Region Setup
+```javascript
+const enterpriseBackup = new BackupPlugin({
+  driver: 'multi',
+  config: {
+    strategy: 'all',
+    destinations: [
+      {
+        driver: 's3',
+        config: {
+          bucket: 'backups-us-east-1',
+          path: 'production/{date}/',
+          storageClass: 'STANDARD_IA'
+        }
+      },
+      {
+        driver: 's3', 
+        config: {
+          bucket: 'backups-eu-west-1',
+          path: 'production/{date}/',
+          storageClass: 'STANDARD_IA'
+        }
+      },
+      {
+        driver: 'filesystem',
+        config: {
+          path: '/mnt/backup-nas/s3db/{date}/'
+        }
+      }
+    ]
+  },
+  retention: {
+    daily: 30,
+    weekly: 12, 
+    monthly: 24,
+    yearly: 7
+  },
+  verification: true,
+  compression: 'gzip'
+});
+```
+
+#### Development Quick Backup
+```javascript
+const devBackup = new BackupPlugin({
+  driver: 'filesystem',
+  config: {
+    path: './dev-backups/{date}/'
+  },
+  compression: 'none',
+  verification: false,
+  verbose: true,
+  retention: { daily: 3 }
+});
+```
+
+### 🎯 CLI Integration
+
+The BackupPlugin works with s3db CLI commands:
+
+```bash
+# Create backups
+s3db backup full --connection "s3://key:secret@bucket"
+s3db backup incremental --connection "s3://key:secret@bucket"
+
+# List and status
+s3db backup --list --connection "s3://key:secret@bucket"
+s3db backup --status backup-id --connection "s3://key:secret@bucket"
+
+# Restore operations  
+s3db restore backup-id --connection "s3://key:secret@bucket"
+s3db restore backup-id --overwrite --connection "s3://key:secret@bucket"
+```
+
+> **Note**: CLI requires the BackupPlugin to be installed in the database instance.
+
+### 🔍 Driver Information
+
+```javascript
+// Get driver details
+const driverInfo = backupPlugin.driver.getStorageInfo();
+console.log('Driver type:', driverInfo.type);
+console.log('Configuration:', driverInfo.config);
+
+// Multi-driver details
+if (driverInfo.type === 'multi') {
+  console.log('Strategy:', driverInfo.strategy);
+  driverInfo.destinations.forEach((dest, i) => {
+    console.log(`Destination ${i}:`, dest.driver, dest.info);
+  });
+}
+```
+
+---
+
+## ⏰ Scheduler Plugin
+
+Robust job scheduling capabilities with cron expressions, retry logic, and comprehensive monitoring for automated tasks.
+
+### ⚡ Quick Start
+
+```javascript
+import { S3db, SchedulerPlugin } from 's3db.js';
+
+const s3db = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [
+    new SchedulerPlugin({
+      timezone: 'America/Sao_Paulo',
+      jobs: {
+        daily_cleanup: {
+          schedule: '0 3 * * *', // 3 AM daily
+          description: 'Clean up expired sessions',
+          action: async (database, context) => {
+            const expired = await database.resource('sessions').list({
+              where: { expiresAt: { $lt: new Date() } }
+            });
+            
+            for (const session of expired) {
+              await database.resource('sessions').delete(session.id);
+            }
+            
+            return { deleted: expired.length };
+          },
+          enabled: true,
+          retries: 2,
+          timeout: 30000
+        },
+        
+        hourly_metrics: {
+          schedule: '@hourly',
+          description: 'Collect system metrics',
+          action: async (database) => {
+            const metrics = {
+              timestamp: new Date().toISOString(),
+              memory: process.memoryUsage(),
+              uptime: process.uptime()
+            };
+            
+            await database.resource('metrics').insert({
+              id: `metrics_${Date.now()}`,
+              ...metrics
+            });
+            
+            return metrics;
+          }
+        }
+      },
+      onJobComplete: (jobName, result, duration) => {
+        console.log(`Job ${jobName} completed in ${duration}ms`);
+      }
+    })
+  ]
+});
+
+await s3db.connect();
+
+// Jobs run automatically based on schedule
+// Manual execution
+await s3db.plugins.scheduler.runJob('daily_cleanup');
+
+// Get job status
+const allJobs = s3db.plugins.scheduler.getAllJobsStatus();
+console.log('Scheduled jobs:', allJobs.length);
+```
+
+### ⚙️ Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `timezone` | string | `'UTC'` | IANA timezone identifier |
+| `jobs` | object | `{}` | Job definitions |
+| `defaultTimeout` | number | `60000` | Default job timeout (ms) |
+| `defaultRetries` | number | `1` | Default retry attempts |
+| `persistJobs` | boolean | `true` | Store job execution history |
+| `jobHistoryResource` | string | `'job_history'` | Resource for job history |
+| `onJobStart` | function | `null` | Callback when job starts |
+| `onJobComplete` | function | `null` | Callback when job completes |
+| `onJobError` | function | `null` | Callback when job fails |
+| `verbose` | boolean | `false` | Enable detailed logging |
+
+### Job Configuration
+
+```javascript
+jobs: {
+  job_name: {
+    schedule: '0 0 * * *',           // Cron expression (required)
+    description: 'Job description',   // Human-readable description
+    action: async (database, context, schedulerPlugin) => {
+      // Job implementation (required)
+      return { success: true };
+    },
+    enabled: true,                   // Enable/disable job
+    retries: 2,                     // Retry attempts on failure
+    timeout: 30000,                 // Timeout in milliseconds
+    meta: { priority: 'high' }      // Custom metadata
+  }
+}
+```
+
+### Cron Expressions
+
+#### Standard Format
+```
+* * * * *
+│ │ │ │ │
+│ │ │ │ └─── Day of week (0-7, Sunday = 0 or 7)
+│ │ │ └───── Month (1-12)
+│ │ └─────── Day of month (1-31)
+│ └───────── Hour (0-23)
+└─────────── Minute (0-59)
+```
+
+#### Examples
+```javascript
+'0 0 * * *'      // Daily at midnight
+'0 9 * * MON'    // Every Monday at 9 AM
+'*/15 * * * *'   // Every 15 minutes
+'0 2 1 * *'      // First day of month at 2 AM
+```
+
+#### Shorthand Expressions
+```javascript
+'@yearly'   // Once a year at midnight on January 1st
+'@monthly'  // Once a month at midnight on the 1st
+'@weekly'   // Once a week at midnight on Sunday
+'@daily'    // Once a day at midnight
+'@hourly'   // Once an hour at the beginning of the hour
+```
+
+### API Methods
+
+```javascript
+// Job execution
+const result = await scheduler.runJob(jobName, context);
+const stats = scheduler.getJobStatus(jobName);
+const allJobs = scheduler.getAllJobsStatus();
+
+// Job management
+scheduler.enableJob(jobName);
+scheduler.disableJob(jobName);
+scheduler.addJob(jobName, jobConfig);
+scheduler.removeJob(jobName);
+
+// History and monitoring
+const history = await scheduler.getJobHistory(jobName, { status: 'success', limit: 10 });
+const stats = scheduler.getJobStatistics(jobName);
+```
+
+### Events
+
+```javascript
+scheduler.on('job_start', ({ jobName, context }) => {
+  console.log(`Job ${jobName} started`);
+});
+
+scheduler.on('job_complete', ({ jobName, result, duration }) => {
+  console.log(`Job ${jobName} completed in ${duration}ms`);
+});
+
+scheduler.on('job_error', ({ jobName, error, retryCount }) => {
+  console.error(`Job ${jobName} failed (attempt ${retryCount}):`, error);
+});
+
+scheduler.on('job_enabled', ({ jobName }) => {
+  console.log(`Job ${jobName} enabled`);
+});
+```
+
+### Integration with Other Plugins
+
+```javascript
+// Scheduled backups
+jobs: {
+  daily_backup: {
+    schedule: '0 1 * * *',
+    action: async (database) => {
+      const backup = database.getPlugin('BackupPlugin');
+      return await backup.backup('full');
+    }
+  }
+}
+
+// Process state machine entities
+jobs: {
+  process_pending_orders: {
+    schedule: '*/10 * * * *',
+    action: async (database) => {
+      const stateMachine = database.getPlugin('StateMachinePlugin');
+      const orders = await database.resource('orders').list({
+        where: { status: 'pending' }
+      });
+      
+      for (const order of orders) {
+        await stateMachine.send('order_processing', order.id, 'AUTO_PROCESS');
+      }
+      
+      return { processed: orders.length };
+    }
+  }
+}
+```
+
+---
+
 ## 🎯 Best Practices
 
 ### Plugin Performance
@@ -4152,6 +5001,9 @@ const s3db = new S3db({
 3. **Use appropriate sampling** for metrics collection
 4. **Configure retention policies** for audit logs
 5. **Test replicator connections** before deployment
+6. **Design efficient state machines** with minimal guards and actions
+7. **Schedule backups during low-traffic periods** to minimize impact
+8. **Use appropriate job timeouts** to prevent resource exhaustion
 
 ### Plugin Security
 
@@ -4160,6 +5012,9 @@ const s3db = new S3db({
 3. **Use IAM roles** instead of access keys when possible
 4. **Encrypt replication data** in transit and at rest
 5. **Validate message sources** in queue consumers
+6. **Secure state machine actions** to prevent unauthorized transitions
+7. **Encrypt backup data** for sensitive databases
+8. **Restrict job execution permissions** to necessary resources only
 
 ### Plugin Monitoring
 
@@ -4168,6 +5023,9 @@ const s3db = new S3db({
 3. **Track error rates** across all plugins
 4. **Use structured logging** for debugging
 5. **Implement circuit breakers** for external services
+6. **Monitor state machine transition rates** and error patterns
+7. **Track backup success rates** and storage usage
+8. **Alert on job failures** and execution delays
 
 ---