groundswell 0.0.2 → 1.0.0

package/examples/examples/03-parent-child.ts

@@ -1,241 +0,0 @@
-/**
- * Example 3: Parent-Child Workflows
- *
- * Demonstrates:
- * - Creating hierarchical workflow structures
- * - Automatic parent-child attachment
- * - Using @Task decorator to spawn child workflows
- * - Event propagation from children to root
- * - Tree visualization of nested workflows
- */
-
-import {
-  Workflow,
-  Step,
-  Task,
-  ObservedState,
-  WorkflowTreeDebugger,
-} from 'groundswell';
-import { printHeader, printSection, sleep } from '../utils/helpers.js';
-
-/**
- * Leaf workflow - performs actual work
- */
-class ProcessItemWorkflow extends Workflow {
-  @ObservedState()
-  itemId: string;
-
-  @ObservedState()
-  processed: boolean = false;
-
-  constructor(itemId: string, parent?: Workflow) {
-    super(`ProcessItem-${itemId}`, parent);
-    this.itemId = itemId;
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async validate(): Promise<void> {
-    this.logger.info(`Validating item ${this.itemId}`);
-    await sleep(50);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async transform(): Promise<void> {
-    this.logger.info(`Transforming item ${this.itemId}`);
-    await sleep(100);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async save(): Promise<void> {
-    this.logger.info(`Saving item ${this.itemId}`);
-    this.processed = true;
-    await sleep(50);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info(`Starting item processing for ${this.itemId}`);
-
-    await this.validate();
-    await this.transform();
-    await this.save();
-
-    this.setStatus('completed');
-    this.logger.info(`Completed processing ${this.itemId}`);
-  }
-}
-
-/**
- * Middle-tier workflow - manages a batch of items
- */
-class BatchProcessorWorkflow extends Workflow {
-  @ObservedState()
-  batchId: string;
-
-  @ObservedState()
-  itemCount: number = 0;
-
-  @ObservedState()
-  processedCount: number = 0;
-
-  private items: string[];
-
-  constructor(batchId: string, items: string[], parent?: Workflow) {
-    super(`Batch-${batchId}`, parent);
-    this.batchId = batchId;
-    this.items = items;
-    this.itemCount = items.length;
-  }
-
-  @Step({ logStart: true })
-  async prepareBatch(): Promise<void> {
-    this.logger.info(`Preparing batch ${this.batchId} with ${this.itemCount} items`);
-    await sleep(50);
-  }
-
-  @Task()
-  async processItem(itemId: string): Promise<ProcessItemWorkflow> {
-    this.logger.info(`Spawning workflow for item ${itemId}`);
-    return new ProcessItemWorkflow(itemId, this);
-  }
-
-  @Step({ logFinish: true, snapshotState: true })
-  async finalizeBatch(): Promise<void> {
-    this.processedCount = this.itemCount;
-    this.logger.info(`Batch ${this.batchId} finalized: ${this.processedCount} items processed`);
-    await sleep(30);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info(`Starting batch ${this.batchId}`);
-
-    await this.prepareBatch();
-
-    // Process each item sequentially
-    for (const itemId of this.items) {
-      const itemWorkflow = await this.processItem(itemId);
-      await itemWorkflow.run();
-      this.processedCount++;
-    }
-
-    await this.finalizeBatch();
-
-    this.setStatus('completed');
-  }
-}
-
-/**
- * Top-level orchestrator workflow
- */
-class DataPipelineWorkflow extends Workflow {
-  @ObservedState()
-  pipelineName: string;
-
-  @ObservedState()
-  totalBatches: number = 0;
-
-  @ObservedState()
-  completedBatches: number = 0;
-
-  private batches: { id: string; items: string[] }[];
-
-  constructor(name: string, batches: { id: string; items: string[] }[]) {
-    super(name);
-    this.pipelineName = name;
-    this.batches = batches;
-    this.totalBatches = batches.length;
-  }
-
-  @Step({ logStart: true, logFinish: true })
-  async initialize(): Promise<void> {
-    this.logger.info(`Initializing pipeline: ${this.pipelineName}`);
-    this.logger.info(`Total batches to process: ${this.totalBatches}`);
-    await sleep(50);
-  }
-
-  @Task()
-  async processBatch(batch: { id: string; items: string[] }): Promise<BatchProcessorWorkflow> {
-    this.logger.info(`Creating batch processor for ${batch.id}`);
-    return new BatchProcessorWorkflow(batch.id, batch.items, this);
-  }
-
-  @Step({ logStart: true, logFinish: true, snapshotState: true })
-  async cleanup(): Promise<void> {
-    this.logger.info('Running cleanup tasks');
-    await sleep(50);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('=== Pipeline Started ===');
-
-    await this.initialize();
-
-    // Process each batch
-    for (const batch of this.batches) {
-      const batchWorkflow = await this.processBatch(batch);
-      await batchWorkflow.run();
-      this.completedBatches++;
-      this.logger.info(`Completed ${this.completedBatches}/${this.totalBatches} batches`);
-    }
-
-    await this.cleanup();
-
-    this.setStatus('completed');
-    this.logger.info('=== Pipeline Completed ===');
-  }
-}
-
-/**
- * Run the parent-child workflow example
- */
-export async function runParentChildExample(): Promise<void> {
-  printHeader('Example 3: Parent-Child Workflows');
-
-  // Create sample data
-  const batches = [
-    { id: 'batch-A', items: ['A1', 'A2'] },
-    { id: 'batch-B', items: ['B1', 'B2', 'B3'] },
-  ];
-
-  // Create the pipeline
-  const pipeline = new DataPipelineWorkflow('MyDataPipeline', batches);
-  const debugger_ = new WorkflowTreeDebugger(pipeline);
-
-  printSection('Initial Tree Structure');
-  console.log(debugger_.toTreeString());
-
-  printSection('Executing Pipeline');
-  await pipeline.run();
-
-  printSection('Final Tree Structure');
-  console.log(debugger_.toTreeString());
-
-  printSection('Tree Statistics');
-  const stats = debugger_.getStats();
-  console.log(`Total nodes: ${stats.totalNodes}`);
-  console.log(`By status:`, stats.byStatus);
-  console.log(`Total logs: ${stats.totalLogs}`);
-  console.log(`Total events: ${stats.totalEvents}`);
-
-  printSection('Workflow Hierarchy');
-  console.log('Pipeline:', pipeline.id);
-  console.log('  Children (batches):', pipeline.children.length);
-  for (const batch of pipeline.children) {
-    console.log(`    ${batch.getNode().name} - ${batch.children.length} items`);
-    for (const item of batch.children) {
-      console.log(`      ${item.getNode().name} [${item.getNode().status}]`);
-    }
-  }
-
-  printSection('Sample Logs (first 15)');
-  const logLines = debugger_.toLogString().split('\n').slice(0, 15);
-  console.log(logLines.join('\n'));
-  console.log('...');
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runParentChildExample().catch(console.error);
-}

package/examples/examples/04-observers-debugger.ts

@@ -1,340 +0,0 @@
-/**
- * Example 4: Observers and Debugger
- *
- * Demonstrates:
- * - Implementing custom WorkflowObserver
- * - Real-time event streaming
- * - Log collection and filtering
- * - Using WorkflowTreeDebugger API
- * - Observable subscription patterns
- */
-
-import {
-  Workflow,
-  Step,
-  Task,
-  ObservedState,
-  WorkflowTreeDebugger,
-  WorkflowObserver,
-  WorkflowEvent,
-  LogEntry,
-  WorkflowNode,
-  Observable,
-} from 'groundswell';
-import { printHeader, printSection, sleep } from '../utils/helpers.js';
-
-/**
- * Custom observer that collects detailed metrics
- */
-class MetricsObserver implements WorkflowObserver {
-  public logCount = 0;
-  public eventCount = 0;
-  public stateUpdates = 0;
-  public treeChanges = 0;
-
-  public logsByLevel: Record<string, number> = {
-    debug: 0,
-    info: 0,
-    warn: 0,
-    error: 0,
-  };
-
-  public eventsByType: Record<string, number> = {};
-  public stepDurations: { step: string; duration: number }[] = [];
-  public errors: WorkflowEvent[] = [];
-
-  onLog(entry: LogEntry): void {
-    this.logCount++;
-    this.logsByLevel[entry.level] = (this.logsByLevel[entry.level] || 0) + 1;
-  }
-
-  onEvent(event: WorkflowEvent): void {
-    this.eventCount++;
-    this.eventsByType[event.type] = (this.eventsByType[event.type] || 0) + 1;
-
-    if (event.type === 'stepEnd') {
-      this.stepDurations.push({
-        step: event.step,
-        duration: event.duration,
-      });
-    }
-
-    if (event.type === 'error') {
-      this.errors.push(event);
-    }
-  }
-
-  onStateUpdated(_node: WorkflowNode): void {
-    this.stateUpdates++;
-  }
-
-  onTreeChanged(_root: WorkflowNode): void {
-    this.treeChanges++;
-  }
-
-  getReport(): string {
-    const lines = [
-      `=== Metrics Report ===`,
-      `Logs: ${this.logCount} total`,
-      `  - debug: ${this.logsByLevel.debug}`,
-      `  - info: ${this.logsByLevel.info}`,
-      `  - warn: ${this.logsByLevel.warn}`,
-      `  - error: ${this.logsByLevel.error}`,
-      ``,
-      `Events: ${this.eventCount} total`,
-      ...Object.entries(this.eventsByType).map(([type, count]) => `  - ${type}: ${count}`),
-      ``,
-      `State updates: ${this.stateUpdates}`,
-      `Tree changes: ${this.treeChanges}`,
-      ``,
-      `Step durations:`,
-      ...this.stepDurations.map((s) => `  - ${s.step}: ${s.duration}ms`),
-    ];
-
-    if (this.errors.length > 0) {
-      lines.push(``, `Errors: ${this.errors.length}`);
-    }
-
-    return lines.join('\n');
-  }
-}
-
-/**
- * Custom observer that logs in real-time
- */
-class ConsoleObserver implements WorkflowObserver {
-  private prefix: string;
-
-  constructor(prefix: string = 'OBSERVER') {
-    this.prefix = prefix;
-  }
-
-  onLog(entry: LogEntry): void {
-    const level = entry.level.toUpperCase().padEnd(5);
-    console.log(`[${this.prefix}] ${level} | ${entry.message}`);
-  }
-
-  onEvent(event: WorkflowEvent): void {
-    if (event.type === 'stepStart') {
-      console.log(`[${this.prefix}] >> Step started: ${event.step}`);
-    } else if (event.type === 'stepEnd') {
-      console.log(`[${this.prefix}] << Step ended: ${event.step} (${event.duration}ms)`);
-    } else if (event.type === 'childAttached') {
-      console.log(`[${this.prefix}] ++ Child attached: ${event.child.name}`);
-    } else if (event.type === 'error') {
-      console.log(`[${this.prefix}] !! ERROR: ${event.error.message}`);
-    }
-  }
-
-  onStateUpdated(node: WorkflowNode): void {
-    console.log(`[${this.prefix}] State updated: ${node.name}`);
-  }
-
-  onTreeChanged(_root: WorkflowNode): void {
-    console.log(`[${this.prefix}] Tree structure changed`);
-  }
-}
-
-/**
- * Sample workflow for observation
- */
-class ObservableWorkflow extends Workflow {
-  @ObservedState()
-  phase: string = 'init';
-
-  @ObservedState()
-  progress: number = 0;
-
-  @Step({ trackTiming: true, snapshotState: true, logStart: true })
-  async phase1(): Promise<void> {
-    this.phase = 'phase1';
-    this.progress = 25;
-    await sleep(100);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async phase2(): Promise<void> {
-    this.phase = 'phase2';
-    this.progress = 50;
-    await sleep(150);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true })
-  async phase3(): Promise<void> {
-    this.phase = 'phase3';
-    this.progress = 75;
-    await sleep(80);
-  }
-
-  @Step({ trackTiming: true, snapshotState: true, logFinish: true })
-  async phase4(): Promise<void> {
-    this.phase = 'phase4';
-    this.progress = 100;
-    await sleep(120);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('Observable workflow starting');
-
-    await this.phase1();
-    await this.phase2();
-    await this.phase3();
-    await this.phase4();
-
-    this.setStatus('completed');
-    this.logger.info('Observable workflow completed');
-  }
-}
-
-/**
- * Child workflow for tree demonstration
- */
-class ChildWorkflow extends Workflow {
-  @Step({ trackTiming: true })
-  async doWork(): Promise<void> {
-    this.logger.info('Child doing work');
-    await sleep(50);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    await this.doWork();
-    this.setStatus('completed');
-  }
-}
-
-/**
- * Parent workflow that spawns children
- */
-class ParentWithChildrenWorkflow extends Workflow {
-  @Task()
-  async spawnChild(name: string): Promise<ChildWorkflow> {
-    return new ChildWorkflow(name, this);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('Parent starting');
-
-    const child1 = await this.spawnChild('Child-1');
-    await child1.run();
-
-    const child2 = await this.spawnChild('Child-2');
-    await child2.run();
-
-    this.setStatus('completed');
-    this.logger.info('Parent completed');
-  }
-}
-
-/**
- * Run the observers and debugger example
- */
-export async function runObserversDebuggerExample(): Promise<void> {
-  printHeader('Example 4: Observers and Debugger');
-
-  // Part 1: Custom MetricsObserver
-  printSection('Part 1: MetricsObserver');
-  {
-    const workflow = new ObservableWorkflow('MetricsDemo');
-    const metricsObserver = new MetricsObserver();
-    workflow.addObserver(metricsObserver);
-
-    await workflow.run();
-
-    console.log(metricsObserver.getReport());
-  }
-
-  // Part 2: Real-time ConsoleObserver
-  printSection('Part 2: Real-time ConsoleObserver');
-  {
-    const workflow = new ObservableWorkflow('ConsoleDemo');
-    const consoleObserver = new ConsoleObserver('LIVE');
-    workflow.addObserver(consoleObserver);
-
-    await workflow.run();
-  }
-
-  // Part 3: Using Observable for event streaming
-  printSection('Part 3: Observable Event Stream');
-  {
-    const workflow = new ParentWithChildrenWorkflow('StreamDemo');
-    const debugger_ = new WorkflowTreeDebugger(workflow);
-
-    const eventLog: string[] = [];
-
-    // Subscribe to the event stream
-    const subscription = debugger_.events.subscribe({
-      next: (event) => {
-        eventLog.push(`${event.type}: ${'node' in event ? event.node.name : 'N/A'}`);
-      },
-    });
-
-    await workflow.run();
-
-    console.log('Events received via Observable:');
-    eventLog.forEach((e) => console.log(`  ${e}`));
-
-    // Cleanup subscription
-    subscription.unsubscribe();
-  }
-
-  // Part 4: WorkflowTreeDebugger API
-  printSection('Part 4: WorkflowTreeDebugger API');
-  {
-    const workflow = new ParentWithChildrenWorkflow('DebuggerDemo');
-    const debugger_ = new WorkflowTreeDebugger(workflow);
-
-    await workflow.run();
-
-    console.log('1. Tree visualization:');
-    console.log(debugger_.toTreeString());
-
-    console.log('2. Get tree root:');
-    const root = debugger_.getTree();
-    console.log(`   Root: ${root.name} (${root.id})`);
-    console.log(`   Children: ${root.children.length}`);
-
-    console.log('\n3. Find node by ID:');
-    const firstChild = workflow.children[0];
-    const foundNode = debugger_.getNode(firstChild.id);
-    console.log(`   Found: ${foundNode?.name}`);
-
-    console.log('\n4. Statistics:');
-    const stats = debugger_.getStats();
-    console.log(`   ${JSON.stringify(stats, null, 2)}`);
-
-    console.log('\n5. Formatted logs:');
-    const logs = debugger_.toLogString().split('\n').slice(0, 5);
-    logs.forEach((log) => console.log(`   ${log}`));
-    console.log('   ...');
-  }
-
-  // Part 5: Multiple observers
-  printSection('Part 5: Multiple Observers');
-  {
-    const workflow = new ObservableWorkflow('MultiObserver');
-
-    const metrics = new MetricsObserver();
-    const console1 = new ConsoleObserver('OBS-1');
-    const console2 = new ConsoleObserver('OBS-2');
-
-    workflow.addObserver(metrics);
-    workflow.addObserver(console1);
-    workflow.addObserver(console2);
-
-    // Note: both console observers will print
-    console.log('Running with 3 observers attached...');
-    await workflow.run();
-
-    console.log('\nMetrics summary:');
-    console.log(`  Events received: ${metrics.eventCount}`);
-    console.log(`  Logs received: ${metrics.logCount}`);
-  }
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runObserversDebuggerExample().catch(console.error);
-}