ai-workflows 2.1.3 → 2.4.0

package/examples/04-database-persistence.ts

@@ -0,0 +1,518 @@
+/**
+ * Example: Integration with ai-database for Persistence
+ *
+ * This example demonstrates how to integrate ai-workflows with a database
+ * for durable event storage, state persistence, and audit logging.
+ *
+ * Note: This example uses a mock database implementation. In production,
+ * you would use ai-database or another persistence layer.
+ *
+ * Key concepts demonstrated:
+ * - DatabaseContext integration with workflows
+ * - Durable event storage with $.do
+ * - State checkpointing
+ * - Audit trail with 5W+H events
+ * - Recovery from failures
+ *
+ * @example
+ * ```bash
+ * npx tsx examples/04-database-persistence.ts
+ * ```
+ */
+
+import {
+  Workflow,
+  createCascadeContext,
+  recordStep,
+  type WorkflowContext,
+  type DatabaseContext,
+} from '../dist/index.js'
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+interface StoredEvent {
+  id: string
+  event: string
+  data: unknown
+  timestamp: number
+}
+
+interface StoredAction {
+  id: string
+  actor: string
+  object: string
+  action: string
+  status?: 'pending' | 'active' | 'completed' | 'failed'
+  metadata?: Record<string, unknown>
+  createdAt: number
+  completedAt?: number
+  result?: unknown
+}
+
+interface StoredArtifact {
+  key: string
+  type: string
+  sourceHash: string
+  content: unknown
+  metadata?: Record<string, unknown>
+  storedAt: number
+}
+
+interface WorkflowCheckpoint {
+  workflowId: string
+  state: Record<string, unknown>
+  history: Array<{ timestamp: number; type: string; name: string; data?: unknown }>
+  createdAt: number
+}
+
+// ============================================================================
+// Mock Database Implementation
+// ============================================================================
+
+class MockDatabase {
+  private events: StoredEvent[] = []
+  private actions: Map<string, StoredAction> = new Map()
+  private artifacts: Map<string, StoredArtifact> = new Map()
+  private checkpoints: Map<string, WorkflowCheckpoint> = new Map()
+
+  // Event storage
+  async recordEvent(event: string, data: unknown): Promise<string> {
+    const id = `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    const stored: StoredEvent = {
+      id,
+      event,
+      data,
+      timestamp: Date.now(),
+    }
+    this.events.push(stored)
+    console.log(`  [DB] Recorded event: ${event} (${id})`)
+    return id
+  }
+
+  async getEvents(filter?: { event?: string; since?: number }): Promise<StoredEvent[]> {
+    let result = [...this.events]
+    if (filter?.event) {
+      result = result.filter((e) => e.event === filter.event)
+    }
+    if (filter?.since) {
+      result = result.filter((e) => e.timestamp >= filter.since)
+    }
+    return result
+  }
+
+  // Action storage
+  async createAction(action: Omit<StoredAction, 'id' | 'createdAt'>): Promise<string> {
+    const id = `act_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    const stored: StoredAction = {
+      ...action,
+      id,
+      status: action.status || 'pending',
+      createdAt: Date.now(),
+    }
+    this.actions.set(id, stored)
+    console.log(`  [DB] Created action: ${action.action} on ${action.object} (${id})`)
+    return id
+  }
+
+  async updateAction(
+    id: string,
+    update: Partial<Pick<StoredAction, 'status' | 'result'>>
+  ): Promise<void> {
+    const action = this.actions.get(id)
+    if (action) {
+      Object.assign(action, update)
+      if (update.status === 'completed' || update.status === 'failed') {
+        action.completedAt = Date.now()
+      }
+      console.log(`  [DB] Updated action ${id}: status=${action.status}`)
+    }
+  }
+
+  async getAction(id: string): Promise<StoredAction | null> {
+    return this.actions.get(id) || null
+  }
+
+  async getPendingActions(): Promise<StoredAction[]> {
+    return Array.from(this.actions.values()).filter(
+      (a) => a.status === 'pending' || a.status === 'active'
+    )
+  }
+
+  // Artifact storage
+  async storeArtifact(artifact: Omit<StoredArtifact, 'storedAt'>): Promise<void> {
+    const stored: StoredArtifact = {
+      ...artifact,
+      storedAt: Date.now(),
+    }
+    this.artifacts.set(artifact.key, stored)
+    console.log(`  [DB] Stored artifact: ${artifact.key} (${artifact.type})`)
+  }
+
+  async getArtifact(key: string): Promise<StoredArtifact | null> {
+    return this.artifacts.get(key) || null
+  }
+
+  // Checkpoint storage
+  async saveCheckpoint(checkpoint: WorkflowCheckpoint): Promise<void> {
+    this.checkpoints.set(checkpoint.workflowId, checkpoint)
+    console.log(`  [DB] Saved checkpoint for workflow ${checkpoint.workflowId}`)
+  }
+
+  async getCheckpoint(workflowId: string): Promise<WorkflowCheckpoint | null> {
+    return this.checkpoints.get(workflowId) || null
+  }
+
+  // Stats
+  getStats() {
+    return {
+      events: this.events.length,
+      actions: this.actions.size,
+      artifacts: this.artifacts.size,
+      checkpoints: this.checkpoints.size,
+    }
+  }
+
+  // Dump for inspection
+  dump() {
+    return {
+      events: this.events,
+      actions: Array.from(this.actions.values()),
+      artifacts: Array.from(this.artifacts.values()),
+      checkpoints: Array.from(this.checkpoints.values()),
+    }
+  }
+}
+
+// ============================================================================
+// Database Context Adapter
+// ============================================================================
+
+function createDatabaseContext(db: MockDatabase): DatabaseContext {
+  return {
+    async recordEvent(event: string, data: unknown): Promise<void> {
+      await db.recordEvent(event, data)
+    },
+
+    async createAction(action: {
+      actor: string
+      object: string
+      action: string
+      status?: 'pending' | 'active' | 'completed' | 'failed'
+      metadata?: Record<string, unknown>
+    }): Promise<void> {
+      await db.createAction(action)
+    },
+
+    async completeAction(id: string, result: unknown): Promise<void> {
+      await db.updateAction(id, { status: 'completed', result })
+    },
+
+    async storeArtifact(artifact: {
+      key: string
+      type: string
+      sourceHash: string
+      content: unknown
+      metadata?: Record<string, unknown>
+    }): Promise<void> {
+      await db.storeArtifact(artifact)
+    },
+
+    async getArtifact(key: string): Promise<unknown | null> {
+      const artifact = await db.getArtifact(key)
+      return artifact?.content ?? null
+    },
+  }
+}
+
+// ============================================================================
+// Durable Workflow Example
+// ============================================================================
+
+interface PaymentRequest {
+  orderId: string
+  amount: number
+  customerId: string
+}
+
+interface PaymentResult {
+  transactionId: string
+  status: 'success' | 'failed'
+  processedAt: number
+}
+
+async function createDurablePaymentWorkflow(db: MockDatabase) {
+  const dbContext = createDatabaseContext(db)
+
+  const workflow = Workflow(
+    ($) => {
+      // Payment processing with durable state
+      $.on.Payment.process(async (request: PaymentRequest, $: WorkflowContext) => {
+        $.log(`Processing payment for order ${request.orderId}`)
+
+        // Create cascade context for tracing
+        const cascade = createCascadeContext({ name: 'payment-processing' })
+
+        // Step 1: Validate payment
+        const validateStep = recordStep(cascade, 'validate', {
+          actor: 'payment-service',
+          action: 'validate-payment',
+        })
+
+        try {
+          // Simulate validation
+          await new Promise((resolve) => setTimeout(resolve, 50))
+          if (request.amount <= 0) {
+            throw new Error('Invalid amount')
+          }
+          validateStep.complete()
+          $.log('  Payment validated')
+        } catch (error) {
+          validateStep.fail(error instanceof Error ? error : new Error(String(error)))
+          throw error
+        }
+
+        // Step 2: Process payment (durable)
+        const processStep = recordStep(cascade, 'process', {
+          actor: 'payment-gateway',
+          action: 'charge-card',
+        })
+
+        try {
+          // This would be $.do in real usage for durable execution
+          await new Promise((resolve) => setTimeout(resolve, 100))
+          const transactionId = `txn_${Date.now()}`
+
+          // Store transaction artifact
+          if ($.db) {
+            await $.db.storeArtifact({
+              key: `payment:${request.orderId}`,
+              type: 'transaction',
+              sourceHash: request.orderId,
+              content: {
+                transactionId,
+                amount: request.amount,
+                customerId: request.customerId,
+              },
+            })
+          }
+
+          processStep.complete()
+          $.log(`  Payment processed: ${transactionId}`)
+
+          // Emit success event
+          $.send('Payment.completed', {
+            orderId: request.orderId,
+            transactionId,
+            amount: request.amount,
+          })
+
+          return {
+            transactionId,
+            status: 'success' as const,
+            processedAt: Date.now(),
+          }
+        } catch (error) {
+          processStep.fail(error instanceof Error ? error : new Error(String(error)))
+
+          $.send('Payment.failed', {
+            orderId: request.orderId,
+            error: error instanceof Error ? error.message : String(error),
+          })
+
+          throw error
+        }
+      })
+
+      $.on.Payment.completed(
+        async (data: { orderId: string; transactionId: string }, $: WorkflowContext) => {
+          $.log(`Payment ${data.transactionId} completed for order ${data.orderId}`)
+
+          // Create action to fulfill order
+          if ($.db) {
+            await $.db.createAction({
+              actor: 'fulfillment-service',
+              object: `order:${data.orderId}`,
+              action: 'fulfill',
+              metadata: { transactionId: data.transactionId },
+            })
+          }
+        }
+      )
+
+      $.on.Payment.failed(async (data: { orderId: string; error: string }, $: WorkflowContext) => {
+        $.log(`Payment failed for order ${data.orderId}: ${data.error}`)
+
+        // Create action to notify customer
+        if ($.db) {
+          await $.db.createAction({
+            actor: 'notification-service',
+            object: `customer:order:${data.orderId}`,
+            action: 'notify-payment-failed',
+            metadata: { error: data.error },
+          })
+        }
+      })
+    },
+    { db: dbContext }
+  )
+
+  return workflow
+}
+
+// ============================================================================
+// State Recovery Example
+// ============================================================================
+
+async function demonstrateStateRecovery(db: MockDatabase) {
+  console.log('\n--- State Recovery Demo ---\n')
+
+  // Simulate saving a checkpoint
+  const checkpoint: WorkflowCheckpoint = {
+    workflowId: 'workflow-123',
+    state: {
+      orderId: 'order-456',
+      step: 'payment-processing',
+      attempts: 2,
+    },
+    history: [
+      { timestamp: Date.now() - 10000, type: 'event', name: 'Order.placed' },
+      { timestamp: Date.now() - 5000, type: 'action', name: 'validate' },
+      {
+        timestamp: Date.now() - 1000,
+        type: 'action',
+        name: 'process-payment',
+        data: { attempt: 1 },
+      },
+    ],
+    createdAt: Date.now(),
+  }
+
+  await db.saveCheckpoint(checkpoint)
+
+  // Simulate recovery
+  console.log('Recovering workflow state...')
+  const recovered = await db.getCheckpoint('workflow-123')
+
+  if (recovered) {
+    console.log(`  Recovered workflow: ${recovered.workflowId}`)
+    console.log(`  State: ${JSON.stringify(recovered.state)}`)
+    console.log(`  History entries: ${recovered.history.length}`)
+    console.log(`  Last action: ${recovered.history[recovered.history.length - 1]?.name}`)
+  }
+}
+
+// ============================================================================
+// Audit Trail Example
+// ============================================================================
+
+async function demonstrateAuditTrail(db: MockDatabase) {
+  console.log('\n--- Audit Trail Demo ---\n')
+
+  // Record various events
+  await db.recordEvent('User.login', {
+    userId: 'user-123',
+    ip: '192.168.1.1',
+    userAgent: 'Mozilla/5.0...',
+  })
+
+  await db.recordEvent('Order.placed', {
+    orderId: 'order-789',
+    customerId: 'user-123',
+    total: 99.99,
+  })
+
+  await db.recordEvent('Payment.processed', {
+    orderId: 'order-789',
+    transactionId: 'txn-abc',
+    amount: 99.99,
+  })
+
+  await db.recordEvent('Order.shipped', {
+    orderId: 'order-789',
+    trackingNumber: 'TRK123456',
+    carrier: 'FastShip',
+  })
+
+  // Query events
+  console.log('All recorded events:')
+  const events = await db.getEvents()
+  for (const event of events) {
+    console.log(`  ${new Date(event.timestamp).toISOString()} | ${event.event}`)
+  }
+
+  // Query specific event type
+  console.log('\nOrder-related events:')
+  const orderEvents = await db.getEvents({ event: 'Order.placed' })
+  for (const event of orderEvents) {
+    console.log(`  ${event.id}: ${JSON.stringify(event.data)}`)
+  }
+}
+
+// ============================================================================
+// Demo Execution
+// ============================================================================
+
+async function runDemo() {
+  console.log('='.repeat(60))
+  console.log('Database Persistence Integration Demo')
+  console.log('='.repeat(60))
+  console.log()
+
+  // Create mock database
+  const db = new MockDatabase()
+
+  // Create and start workflow
+  const workflow = await createDurablePaymentWorkflow(db)
+  await workflow.start()
+
+  // Process some payments
+  console.log('--- Processing Payments ---\n')
+
+  await workflow.send('Payment.process', {
+    orderId: 'order-001',
+    amount: 99.99,
+    customerId: 'cust-001',
+  })
+  await new Promise((resolve) => setTimeout(resolve, 200))
+
+  await workflow.send('Payment.process', {
+    orderId: 'order-002',
+    amount: 149.99,
+    customerId: 'cust-002',
+  })
+  await new Promise((resolve) => setTimeout(resolve, 200))
+
+  // Demonstrate state recovery
+  await demonstrateStateRecovery(db)
+
+  // Demonstrate audit trail
+  await demonstrateAuditTrail(db)
+
+  // Show database stats
+  console.log('\n--- Database Stats ---\n')
+  const stats = db.getStats()
+  console.log(`  Events: ${stats.events}`)
+  console.log(`  Actions: ${stats.actions}`)
+  console.log(`  Artifacts: ${stats.artifacts}`)
+  console.log(`  Checkpoints: ${stats.checkpoints}`)
+
+  // Show pending actions
+  console.log('\n--- Pending Actions ---\n')
+  const pending = await db.getPendingActions()
+  for (const action of pending) {
+    console.log(`  ${action.id}: ${action.action} on ${action.object} (${action.status})`)
+  }
+
+  // Full dump for inspection
+  console.log('\n--- Full Database Dump ---\n')
+  const dump = db.dump()
+  console.log(JSON.stringify(dump, null, 2))
+
+  // Clean up
+  await workflow.stop()
+}
+
+// Run if executed directly
+runDemo().catch(console.error)

package/examples/README.md

@@ -0,0 +1,173 @@
+# ai-workflows Examples
+
+This directory contains runnable examples demonstrating the key features of ai-workflows.
+
+## Prerequisites
+
+```bash
+# From the package root (or monorepo root)
+npm install
+npm run build  # Must build first since examples import from dist/
+```
+
+## Running Examples
+
+Each example can be run directly with `tsx`:
+
+```bash
+# From the ai-workflows package directory
+npx tsx examples/01-ecommerce-order-pipeline.ts
+npx tsx examples/02-content-moderation-cascade.ts
+npx tsx examples/03-scheduled-reporting-dependencies.ts
+npx tsx examples/04-database-persistence.ts
+```
+
+**Note:** Examples import from `../dist/index.js` to use the built package. Ensure you run `npm run build` first.
+
+## Examples Overview
+
+### 01 - E-commerce Order Processing Pipeline
+
+Demonstrates a complete order processing workflow using event-driven architecture.
+
+**Key Concepts:**
+- Event handlers with `$.on.Noun.event()`
+- Event chaining (one event triggers another)
+- State management with `$.state`
+- Error handling and compensation patterns
+- Customer notification flow
+
+**Flow:**
+```
+Order.placed -> Payment.requested -> Payment.completed -> Order.confirmed
+                                  -> Shipping.requested -> Order.shipped
+```
+
+### 02 - AI Content Moderation with Human Escalation
+
+Demonstrates the CascadeExecutor pattern for tiered processing with escalation.
+
+**Key Concepts:**
+- `CascadeExecutor` for code -> AI -> agent -> human escalation
+- Per-tier timeouts and retry configuration
+- Skip conditions for tier bypassing
+- 5W+H audit trail for compliance
+- Workflow integration with cascade results
+
+**Tiers:**
+1. **Code**: Fast keyword/pattern matching (100ms timeout)
+2. **Generative**: LLM-based analysis (5s timeout)
+3. **Agentic**: Multi-step reasoning with tools (30s timeout)
+4. **Human**: Expert review queue (1 hour timeout)
+
+### 03 - Scheduled Reporting with Dependency Chains
+
+Demonstrates complex workflows with dependencies and parallel execution.
+
+**Key Concepts:**
+- `DependencyGraph` for step ordering
+- `topologicalSort()` for execution planning
+- `getExecutionLevels()` for parallel grouping
+- `waitForAll()` and `Barrier` for synchronization
+- `withConcurrencyLimit()` for controlled parallelism
+
+**Pipeline:**
+```
+Level 0: [fetch-sales, fetch-crm, fetch-inventory, fetch-analytics]  (parallel)
+Level 1: [aggregate-data]                                             (sequential)
+Level 2: [generate-daily-report, generate-summary]                    (parallel)
+Level 3: [distribute-email, distribute-slack, archive-s3]             (parallel)
+```
+
+### 04 - Database Persistence Integration
+
+Demonstrates durable event storage and state persistence.
+
+**Key Concepts:**
+- `DatabaseContext` integration with workflows
+- Durable event storage with `$.db.recordEvent()`
+- Action tracking with `$.db.createAction()`
+- Artifact storage with `$.db.storeArtifact()`
+- State checkpointing and recovery
+- Audit trail with 5W+H events
+
+**Note:** Uses a mock database implementation. In production, integrate with `ai-database` or your persistence layer.
+
+## Code Patterns
+
+### Basic Workflow Setup
+
+```typescript
+import { Workflow } from 'ai-workflows'
+
+const workflow = Workflow($ => {
+  $.on.Entity.event(async (data, $) => {
+    $.log('Processing event')
+    $.send('Another.event', { result: 'done' })
+  })
+})
+
+await workflow.start()
+await workflow.send('Entity.event', { input: 'data' })
+await workflow.stop()
+```
+
+### Cascade Executor
+
+```typescript
+import { CascadeExecutor } from 'ai-workflows'
+
+const cascade = new CascadeExecutor({
+  tiers: {
+    code: { name: 'rules', execute: async (input) => { /* fast rules */ } },
+    generative: { name: 'ai', execute: async (input) => { /* AI analysis */ } },
+    human: { name: 'review', execute: async (input) => { /* human queue */ } },
+  },
+  useDefaultTimeouts: true,
+})
+
+const result = await cascade.execute(input)
+console.log(`Resolved by ${result.tier} tier`)
+```
+
+### Dependency Graph
+
+```typescript
+import { DependencyGraph, getExecutionLevels } from 'ai-workflows'
+
+const graph = new DependencyGraph()
+graph.addNode('step-a')
+graph.addNode('step-b')
+graph.addNode('step-c', { dependsOn: ['step-a', 'step-b'] })
+
+const levels = getExecutionLevels(graph.getNodes())
+// Level 0: [step-a, step-b]
+// Level 1: [step-c]
+```
+
+### Barrier Synchronization
+
+```typescript
+import { Barrier, waitForAll } from 'ai-workflows'
+
+// Simple parallel wait
+const results = await waitForAll([
+  fetchA(),
+  fetchB(),
+  fetchC(),
+], { timeout: 5000 })
+
+// Manual barrier with progress
+const barrier = new Barrier(3, {
+  onProgress: (p) => console.log(`${p.percentage}% complete`)
+})
+// ... barrier.arrive(result) from parallel workers
+const all = await barrier.wait()
+```
+
+## Related Documentation
+
+- [ai-workflows README](../README.md) - Full API documentation
+- [CascadeExecutor](../src/cascade-executor.ts) - Tiered execution pattern
+- [DependencyGraph](../src/dependency-graph.ts) - Step dependency management
+- [Barrier](../src/barrier.ts) - Parallel coordination primitives