yaml-flow 3.1.0 → 4.0.0

package/examples/npm-libs/batch/batch-step-machine.ts

@@ -0,0 +1,121 @@
+/**
+ * Batch Example: Process tickets through a Step Machine flow
+ *
+ * Demonstrates:
+ *  - batch() with step-machine processor
+ *  - Concurrency control (3 slots)
+ *  - Progress tracking
+ *  - Mixed success/failure handling
+ *
+ * Run with: npx tsx examples/npm-libs/batch/batch-step-machine.ts
+ */
+
+import { batch } from '../../src/batch/index.js';
+import { createStepMachine } from '../../src/step-machine/index.js';
+import type { StepFlowConfig, StepHandler } from '../../src/step-machine/types.js';
+
+// ============================================================================
+// 1. Define a simple flow
+// ============================================================================
+
+const ticketFlow: StepFlowConfig = {
+  id: 'support-ticket',
+  settings: { start_step: 'classify', max_total_steps: 10 },
+  steps: {
+    classify: {
+      produces_data: ['category'],
+      transitions: { billing: 'handle', technical: 'handle', unknown: 'escalate' },
+    },
+    handle: {
+      expects_data: ['category'],
+      produces_data: ['resolution'],
+      transitions: { resolved: 'done', failed: 'escalate' },
+    },
+    escalate: {
+      expects_data: ['category'],
+      produces_data: ['escalation_id'],
+      transitions: { done: 'done' },
+    },
+  },
+  terminal_states: {
+    done: { return_intent: 'resolved', return_artifacts: ['resolution', 'escalation_id'] },
+  },
+};
+
+const handlers: Record<string, StepHandler> = {
+  classify: async (input) => {
+    const msg = (input.message as string) || '';
+    if (msg.includes('bill') || msg.includes('charge')) return { result: 'billing', data: { category: 'billing' } };
+    if (msg.includes('crash') || msg.includes('error')) return { result: 'technical', data: { category: 'technical' } };
+    return { result: 'unknown', data: { category: 'unknown' } };
+  },
+  handle: async (input) => {
+    // Simulate occasional failure
+    if (Math.random() < 0.2) return { result: 'failed' };
+    return { result: 'resolved', data: { resolution: `Resolved ${input.category} issue` } };
+  },
+  escalate: async (input) => {
+    return { result: 'done', data: { escalation_id: `ESC-${Date.now()}` } };
+  },
+};
+
+// ============================================================================
+// 2. Batch of tickets
+// ============================================================================
+
+const tickets = [
+  { id: 'T-001', message: 'I was double-charged on my bill' },
+  { id: 'T-002', message: 'App crashes on startup' },
+  { id: 'T-003', message: 'How do I change my password?' },
+  { id: 'T-004', message: 'Billing error on invoice #1234' },
+  { id: 'T-005', message: 'Error 500 on checkout page' },
+  { id: 'T-006', message: 'Cannot access my account' },
+  { id: 'T-007', message: 'Refund not processed on my bill' },
+  { id: 'T-008', message: 'App throws error on login' },
+];
+
+// ============================================================================
+// 3. Run batch
+// ============================================================================
+
+async function main() {
+  console.log(`Processing ${tickets.length} tickets with 3 concurrent slots\n`);
+
+  const result = await batch(tickets, {
+    concurrency: 3,
+
+    processor: async (ticket) => {
+      const machine = createStepMachine(ticketFlow, handlers);
+      return machine.run({ message: ticket.message });
+    },
+
+    onItemComplete: (ticket, flowResult) => {
+      console.log(`  ✓ ${ticket.id}: ${flowResult.intent} — ${flowResult.stepHistory.join(' → ')}`);
+    },
+
+    onItemError: (ticket, error) => {
+      console.log(`  ✗ ${ticket.id}: ${error.message}`);
+    },
+
+    onProgress: (p) => {
+      if (p.percent % 25 === 0) {
+        console.log(`  [${p.percent}%] ${p.completed + p.failed}/${p.total} done, ${p.active} active`);
+      }
+    },
+  });
+
+  console.log(`\n${'='.repeat(50)}`);
+  console.log(`Results: ${result.completed} completed, ${result.failed} failed (${result.durationMs}ms)`);
+
+  // Show per-item breakdown
+  for (const item of result.items) {
+    const ticket = item.item;
+    if (item.status === 'completed') {
+      console.log(`  ${ticket.id}: ${item.result?.intent} (${item.durationMs}ms)`);
+    } else {
+      console.log(`  ${ticket.id}: FAILED — ${item.error?.message}`);
+    }
+  }
+}
+
+main().catch(console.error);

package/examples/npm-libs/continuous-event-graph/live-cards-board.ts

@@ -0,0 +1,215 @@
+/**
+ * Live Cards → Reactive Graph Example: Board Dashboard
+ *
+ * Demonstrates `liveCardsToReactiveGraph` — the bridge that converts
+ * live card / source JSON definitions into a fully wired ReactiveGraph.
+ *
+ * This example shows both overloads:
+ *   1. Flat array of cards  → reactive graph
+ *   2. LiveBoard object     → reactive graph (with board-level id/settings)
+ *
+ * Features exercised:
+ *  - Source nodes with pre-populated state (static data feeds)
+ *  - Custom sourceHandlers (simulated API fetch)
+ *  - Card nodes with compute expressions (sum, avg, count, template)
+ *  - Cross-card data flow via data.requires / data.provides
+ *  - LiveBoard overload — board.id, board.settings forwarded to GraphConfig
+ *  - validateReactiveGraph on the resulting graph
+ *
+ * Run with: npx tsx examples/npm-libs/continuous-event-graph/live-cards-board.ts
+ */
+
+import {
+  liveCardsToReactiveGraph,
+  validateReactiveGraph,
+} from '../../src/continuous-event-graph/index.js';
+import type { LiveCard, LiveBoard } from '../../src/continuous-event-graph/index.js';
+
+// ============================================================================
+// 1. Flat cards array → Reactive Graph
+// ============================================================================
+
+console.log('=== Part 1: Flat cards array ===\n');
+
+const cards: LiveCard[] = [
+  {
+    id: 'market-feed',
+    type: 'source',
+    meta: { title: 'Live Market Prices' },
+    state: { prices: [142.5, 305.8, 89.2, 211.0, 178.3] },
+    source: { kind: 'static', bindTo: 'state.prices' },
+  },
+  {
+    id: 'stats',
+    type: 'card',
+    meta: { title: 'Price Statistics' },
+    state: {},
+    data: { requires: ['market-feed'] },
+    compute: {
+      total: { fn: 'sum', input: 'state.market-feed.prices' },
+      avg: { fn: 'avg', input: 'state.market-feed.prices' },
+      count: { fn: 'count', input: 'state.market-feed.prices' },
+    },
+  },
+  {
+    id: 'summary',
+    type: 'card',
+    meta: { title: 'Summary Label' },
+    state: {},
+    data: { requires: ['stats'] },
+    compute: {
+      label: {
+        fn: 'template',
+        input: 'state.stats',
+        format: '{{count}} stocks — total ${{total}}, avg ${{avg}}',
+      },
+    },
+  },
+];
+
+const flatResult = liveCardsToReactiveGraph(cards, {
+});
+
+console.log('Graph ID:', flatResult.config.id);
+console.log('Tasks:', Object.keys(flatResult.config.tasks).join(', '));
+console.log('Pushing trigger event...\n');
+
+flatResult.graph.push({
+  type: 'inject-tokens',
+  tokens: [],
+  timestamp: new Date().toISOString(),
+});
+
+await sleep(1000);
+
+const flatState = flatResult.graph.getState();
+for (const [name, task] of Object.entries(flatState.state.tasks)) {
+  const hash = task.lastDataHash ? ` (hash: ${task.lastDataHash.slice(0, 8)}…)` : '';
+  console.log(`  ${name}: ${task.status}${hash}`);
+}
+console.log(`  Outputs: [${flatState.state.availableOutputs.join(', ')}]`);
+
+flatResult.graph.dispose();
+
+// ============================================================================
+// 2. LiveBoard → Reactive Graph
+// ============================================================================
+
+console.log('\n=== Part 2: LiveBoard overload ===\n');
+
+const board: LiveBoard = {
+  id: 'portfolio-board',
+  title: 'Portfolio Analytics Dashboard',
+  mode: 'board',
+  positions: {
+    'equity-feed':   { x: 0, y: 0, w: 300, h: 200 },
+    'bond-feed':     { x: 320, y: 0, w: 300, h: 200 },
+    'portfolio-mix': { x: 160, y: 240, w: 300, h: 200 },
+    'risk-summary':  { x: 160, y: 480, w: 300, h: 200 },
+  },
+  settings: {
+    completion: 'manual',
+  },
+  nodes: [
+    {
+      id: 'equity-feed',
+      type: 'source',
+      meta: { title: 'Equity Prices' },
+      state: {},
+      source: { kind: 'api', bindTo: 'state.raw', url_template: 'https://api.example.com/equity' },
+    },
+    {
+      id: 'bond-feed',
+      type: 'source',
+      meta: { title: 'Bond Yields' },
+      state: { yields: [3.2, 4.1, 2.8, 5.0] },
+      source: { kind: 'static', bindTo: 'state.yields' },
+    },
+    {
+      id: 'portfolio-mix',
+      type: 'card',
+      meta: { title: 'Portfolio Mix Calculator' },
+      state: {},
+      data: { requires: ['equity-feed', 'bond-feed'] },
+      compute: {
+        equity_total: { fn: 'sum', input: 'state.equity-feed.prices' },
+        bond_total: { fn: 'sum', input: 'state.bond-feed.yields' },
+      },
+    },
+    {
+      id: 'risk-summary',
+      type: 'card',
+      meta: { title: 'Risk Summary' },
+      state: {},
+      data: { requires: ['portfolio-mix'] },
+      compute: {
+        label: {
+          fn: 'template',
+          input: 'state.portfolio-mix',
+          format: 'Equities: ${{equity_total}} | Bonds: {{bond_total}}%',
+        },
+      },
+    },
+  ],
+};
+
+const boardResult = liveCardsToReactiveGraph(board, {
+  // Custom handler for the API-based source — simulates a fetch
+  sourceHandlers: {
+    'equity-feed': async ({ callbackToken }) => {
+      console.log('  [equity-feed] Simulating API fetch...');
+      await sleep(100);
+      // Use the graph to resolve — bridge wires this up automatically
+      boardResult.graph.resolveCallback(callbackToken, { prices: [155.2, 310.4, 92.1, 220.5] });
+      return 'task-initiated' as const;
+    },
+  },
+});
+
+console.log('Board ID:',     boardResult.config.id);
+console.log('Completion:',   boardResult.config.settings.completion);
+console.log('Tasks:',        Object.keys(boardResult.config.tasks).join(', '));
+console.log('Cards in map:', boardResult.cards.size);
+console.log();
+
+// Push and run
+boardResult.graph.push({
+  type: 'inject-tokens',
+  tokens: [],
+  timestamp: new Date().toISOString(),
+});
+
+await sleep(1500);
+
+const boardState = boardResult.graph.getState();
+console.log('Final task states:');
+for (const [name, task] of Object.entries(boardState.state.tasks)) {
+  const hash = task.lastDataHash ? ` (hash: ${task.lastDataHash.slice(0, 8)}…)` : '';
+  console.log(`  ${name}: ${task.status} (executed ${task.executionCount}x)${hash}`);
+}
+console.log(`  Outputs: [${boardState.state.availableOutputs.join(', ')}]`);
+
+// ============================================================================
+// 3. Validate the reactive graph
+// ============================================================================
+
+console.log('\n=== Validation ===');
+const validation = validateReactiveGraph({
+  graph: boardResult.graph,
+  handlers: boardResult.handlers,
+});
+console.log(`  Valid: ${validation.valid} (${validation.issues.length} issues)`);
+for (const issue of validation.issues) {
+  console.log(`    [${issue.severity}] ${issue.code}: ${issue.message}`);
+}
+
+boardResult.graph.dispose();
+console.log('\nDone.');
+
+// ============================================================================
+// Util
+// ============================================================================
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}