yaml-flow 7.1.0 → 8.0.0

package/examples/npm-libs/continuous-event-graph/portfolio-tracker.ts

@@ -1,287 +0,0 @@
-/**
- * Portfolio Tracker — Correct Model
- *
- * Demonstrates externally-driven tasks, engine-stored data, data-changed
- * cascade, and retrigger via task-restart.
- *
- * Graph topology:
- *   portfolio-form  →  price-fetch  →  holdings-table  →  portfolio-value
- *     (external)       (handler)        (handler)          (handler)
- *
- * Key concepts:
- *   • portfolio-form has NO handler — it's user-editable.
- *     The caller pushes `task-completed` with data externally.
- *   • Engine persists `data` on GraphEngineStore (per-task state).
- *   • Downstream handlers read upstream data from engine state:
- *       ctx.live.state.tasks['portfolio-form'].data
- *   • data-changed refresh: reactive layer auto-hashes the data payload
- *     on external push. When the hash differs from previous, downstream
- *     tasks become re-eligible.
- *   • retrigger('price-fetch') sends a task-restart event through the
- *     engine, which resets the task and re-triggers the cascade.
- *
- * Timeline:
- *   T0: Empty board — graph wired, standing by
- *   T1: User submits 2 holdings → push task-completed for portfolio-form
- *       data-changed cascade: price-fetch → holdings-table → portfolio-value
- *   T2: User adds 3rd holding → push task-completed with new data
- *       new hash → identical cascade, fresh prices
- *   T3: Force price refresh without form change → retrigger('price-fetch')
- *   T4: Quiescent
- *
- * Run with: npx tsx examples/npm-libs/continuous-event-graph/portfolio-tracker.ts
- */
-
-import type { GraphConfig } from '../../src/event-graph/types.js';
-import { createReactiveGraph } from '../../src/continuous-event-graph/reactive.js';
-import { validateReactiveGraph } from '../../src/continuous-event-graph/validate.js';
-import { createCallbackHandler } from '../../src/continuous-event-graph/handlers.js';
-import type { TaskHandlerFn, ReactiveGraph } from '../../src/continuous-event-graph/reactive.js';
-import type { ResolveCallbackFn } from '../../src/continuous-event-graph/handlers.js';
-
-// ============================================================================
-// Simulated market data
-// ============================================================================
-
-const marketPrices: Record<string, number> = {
-  AAPL: 198.50,
-  MSFT: 425.30,
-  GOOG: 178.90,
-  AMZN: 192.40,
-  TSLA: 168.75,
-};
-
-function fetchPrices(symbols: string[]): Record<string, number> {
-  const prices: Record<string, number> = {};
-  for (const sym of symbols) {
-    prices[sym] = marketPrices[sym] ?? 0;
-  }
-  return prices;
-}
-
-// ============================================================================
-// 1. Define the graph config
-// ============================================================================
-
-const config: GraphConfig = {
-  id: 'portfolio-tracker',
-  settings: {
-    completion: 'manual',
-    execution_mode: 'eligibility-mode',
-    refreshStrategy: 'data-changed',
-  },
-  tasks: {
-    'portfolio-form': {
-      // No requires — root node, externally driven
-      provides: ['portfolio-form'],
-      description: 'Editable portfolio holdings (no handler — external push)',
-    },
-    'price-fetch': {
-      requires: ['portfolio-form'],
-      provides: ['price-fetch'],
-      taskHandlers: ['price-fetch'],
-      description: 'Fetch market prices for portfolio symbols',
-    },
-    'holdings-table': {
-      requires: ['portfolio-form', 'price-fetch'],
-      provides: ['holdings-table'],
-      taskHandlers: ['holdings-table'],
-      description: 'Join holdings × prices → table rows',
-    },
-    'portfolio-value': {
-      requires: ['holdings-table'],
-      provides: ['portfolio-value'],
-      taskHandlers: ['portfolio-value'],
-      description: 'Sum all holding values → total portfolio value',
-    },
-  },
-};
-
-// ============================================================================
-// 2. Define handlers (portfolio-form has NONE — it's externally driven)
-// ============================================================================
-
-// Lazy resolver — graph doesn't exist at handler-creation time
-let graphRef: ReactiveGraph;
-const getResolve = (): ResolveCallbackFn => graphRef.resolveCallback.bind(graphRef);
-
-const handlers: Record<string, TaskHandlerFn> = {
-  // price-fetch: reads holdings from upstream state, fetches market prices
-  'price-fetch': createCallbackHandler(async ({ state }) => {
-    const formData = state['portfolio-form'] as
-      { holdings?: Array<{ symbol: string; qty: number }> } | undefined;
-    const symbols = (formData?.holdings ?? []).map(h => h.symbol);
-    console.log(`  [price-fetch] Fetching prices for: ${symbols.join(', ') || '(none)'}`);
-    const prices = fetchPrices(symbols);
-    return { prices };
-  }, getResolve),
-
-  // holdings-table: reads form data + prices from upstream state, computes rows
-  'holdings-table': createCallbackHandler(async ({ state }) => {
-    const formData = state['portfolio-form'] as
-      { holdings?: Array<{ symbol: string; qty: number }> } | undefined;
-    const priceData = state['price-fetch'] as
-      { prices?: Record<string, number> } | undefined;
-
-    const holdings = formData?.holdings ?? [];
-    const prices = priceData?.prices ?? {};
-
-    const rows = holdings.map(h => ({
-      symbol: h.symbol,
-      qty: h.qty,
-      price: prices[h.symbol] ?? 0,
-      value: h.qty * (prices[h.symbol] ?? 0),
-    }));
-    console.log(`  [holdings-table] ${rows.length} rows computed`);
-    rows.forEach(r =>
-      console.log(`    ${r.symbol}: ${r.qty} × $${r.price.toFixed(2)} = $${r.value.toFixed(2)}`),
-    );
-    return { rows };
-  }, getResolve),
-
-  // portfolio-value: reads table rows from upstream state, sums values
-  'portfolio-value': createCallbackHandler(async ({ state }) => {
-    const tableData = state['holdings-table'] as
-      { rows?: Array<{ value: number }> } | undefined;
-    const rows = tableData?.rows ?? [];
-    const totalValue = rows.reduce((sum, r) => sum + r.value, 0);
-    console.log(`  [portfolio-value] Total: $${totalValue.toFixed(2)}`);
-    return { totalValue };
-  }, getResolve),
-};
-
-// ============================================================================
-// 3. Create the reactive graph
-// ============================================================================
-
-const graph = createReactiveGraph(config, {
-  handlers,
-  onDrain: (events, live, result) => {
-    const done = Object.values(live.state.tasks).filter(t => t.status === 'completed').length;
-    const total = Object.keys(live.config.tasks).length;
-    if (events.length > 0) {
-      console.log(`  [drain] ${events.length} events, ${done}/${total} done, eligible: [${result.eligible.join(', ')}]`);
-    }
-  },
-});
-graphRef = graph;
-
-// ============================================================================
-// 4. T0: Empty board
-// ============================================================================
-
-console.log('=== Portfolio Tracker ===');
-console.log(`Tasks: ${Object.keys(config.tasks).join(' → ')}`);
-console.log(`portfolio-form has NO handler — externally driven\n`);
-
-console.log('--- T0: Empty board ---');
-console.log('  No holdings yet. Standing by.\n');
-
-// ============================================================================
-// 5. T1: User submits 2 holdings → external push for portfolio-form
-// ============================================================================
-
-console.log('--- T1: User adds AAPL (50 shares) and MSFT (30 shares) ---\n');
-
-// External push — portfolio-form completes with data.
-// The reactive layer auto-hashes the data payload.
-// data-changed cascade triggers: price-fetch → holdings-table → portfolio-value
-graph.push({
-  type: 'task-completed',
-  taskName: 'portfolio-form',
-  data: {
-    holdings: [
-      { symbol: 'AAPL', qty: 50 },
-      { symbol: 'MSFT', qty: 30 },
-    ],
-  },
-  timestamp: new Date().toISOString(),
-});
-
-await sleep(2000);
-printState('T1');
-
-// ============================================================================
-// 6. T2: User adds a 3rd holding → new data, new hash → cascade
-// ============================================================================
-
-console.log('\n--- T2: User adds GOOG (100 shares) ---\n');
-
-// Same task, new data. Auto-hash differs → data-changed re-triggers downstream.
-graph.push({
-  type: 'task-completed',
-  taskName: 'portfolio-form',
-  data: {
-    holdings: [
-      { symbol: 'AAPL', qty: 50 },
-      { symbol: 'MSFT', qty: 30 },
-      { symbol: 'GOOG', qty: 100 },
-    ],
-  },
-  timestamp: new Date().toISOString(),
-});
-
-await sleep(2000);
-printState('T2');
-
-// ============================================================================
-// 7. T3: Force price refresh — retrigger without form change
-// ============================================================================
-
-console.log('\n--- T3: Force price refresh via retrigger ---\n');
-
-// Simulate a price change
-marketPrices.AAPL = 205.00;
-console.log('  [simulated] AAPL price changed to $205.00');
-
-// retrigger pushes a task-restart event through the engine
-graph.retrigger('price-fetch');
-
-await sleep(2000);
-printState('T3');
-
-// ============================================================================
-// 8. T4: Quiescent
-// ============================================================================
-
-console.log('\n--- T4: No changes — board quiescent ---');
-const sched = graph.getSchedule();
-console.log(`  Eligible tasks: ${sched.eligible.length === 0 ? 'none' : sched.eligible.join(', ')}`);
-
-// ============================================================================
-// 9. Validate
-// ============================================================================
-
-console.log('\n--- Validation ---');
-const validation = validateReactiveGraph({ graph, handlers });
-console.log(`  Valid: ${validation.valid} (${validation.issues.length} issues)`);
-for (const issue of validation.issues) {
-  console.log(`    [${issue.severity}] ${issue.code}: ${issue.message}`);
-}
-
-graph.dispose();
-console.log('\nDone.');
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-function printState(label: string): void {
-  console.log(`\n--- ${label} Result ---`);
-  const state = graph.getState();
-  for (const [name, task] of Object.entries(state.state.tasks)) {
-    const hash = task.lastDataHash ? ` (hash: ${task.lastDataHash.slice(0, 8)}…)` : '';
-    console.log(`  ${name}: ${task.status} (${task.executionCount}x)${hash}`);
-  }
-
-  // Read portfolio value directly from engine state — no sharedState needed
-  const valueData = state.state.tasks['portfolio-value']?.data as
-    { totalValue?: number } | undefined;
-  if (valueData?.totalValue != null) {
-    console.log(`\n  Portfolio Value: $${valueData.totalValue.toFixed(2)}`);
-  }
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}

package/examples/npm-libs/continuous-event-graph/reactive-monitoring.ts

@@ -1,265 +0,0 @@
-/**
- * Reactive Graph Example: Live Monitoring Dashboard
- *
- * Demonstrates the reactive graph's advanced features:
- *  - Self-sustaining execution (no loops, no daemon)
- *  - createCallbackHandler + createFireAndForgetHandler
- *  - Adding nodes at runtime with handlers
- *  - Conditional routing (on)
- *  - Handler failure → core engine on_failure tokens
- *  - Auto dataHash (no explicit hash in handlers)
- *  - validateReactiveGraph for handler/dispatch checks
- *  - Observability via onDrain
- *  - Journal-based event batching
- *
- * Scenario: A monitoring system that collects metrics, evaluates alerts,
- * and dynamically adds notification channels at runtime.
- *
- * Run with: npx tsx examples/npm-libs/continuous-event-graph/reactive-monitoring.ts
- */
-
-import {
-  createReactiveGraph,
-  MemoryJournal,
-  createCallbackHandler,
-  createFireAndForgetHandler,
-  validateReactiveGraph,
-} from '../../src/continuous-event-graph/index.js';
-import type { GraphConfig, TaskConfig } from '../../src/continuous-event-graph/types.js';
-import type { TaskHandlerFn, ReactiveGraph } from '../../src/continuous-event-graph/reactive.js';
-import type { ResolveCallbackFn } from '../../src/continuous-event-graph/handlers.js';
-
-// ============================================================================
-// 1. Define the initial graph
-// ============================================================================
-
-const config: GraphConfig = {
-  id: 'monitoring-dashboard',
-  settings: {
-    completion: 'manual', // continuous — never auto-completes
-    execution_mode: 'eligibility-mode',
-  },
-  tasks: {
-    collect_cpu: {
-      provides: ['cpu-metrics'],
-      taskHandlers: ['collect_cpu'],
-      description: 'Collect CPU utilization metrics',
-    },
-    collect_memory: {
-      provides: ['memory-metrics'],
-      taskHandlers: ['collect_memory'],
-      description: 'Collect memory usage metrics',
-    },
-    evaluate_health: {
-      requires: ['cpu-metrics', 'memory-metrics'],
-      provides: ['health-status'],
-      taskHandlers: ['evaluate_health'],
-      on: {
-        healthy: ['system-ok'],
-        degraded: ['system-degraded'],
-        critical: ['system-critical'],
-      },
-      description: 'Evaluate system health from all metrics',
-    },
-    alert_oncall: {
-      requires: ['system-critical'],
-      provides: ['oncall-notified'],
-      taskHandlers: ['alert_oncall'],
-      description: 'Page the on-call engineer',
-    },
-    log_status: {
-      requires: ['system-ok'],
-      provides: ['status-logged'],
-      taskHandlers: ['log_status'],
-      description: 'Log healthy status for audit',
-    },
-    scale_up: {
-      requires: ['system-degraded'],
-      provides: ['scaled-up'],
-      taskHandlers: ['scale_up'],
-      on_failure: ['scale-failed'],
-      description: 'Auto-scale infrastructure',
-    },
-    escalate: {
-      requires: ['scale-failed'],
-      provides: ['escalated'],
-      taskHandlers: ['escalate'],
-      description: 'Escalate to platform team when auto-scale fails',
-    },
-  },
-};
-
-// ============================================================================
-// 2. Simulated metrics
-// ============================================================================
-
-let cpuLoad = 45; // start normal
-let memoryUsage = 60;
-
-function simulateMetrics(): { cpu: number; memory: number } {
-  // Gradually increase load to trigger different paths
-  cpuLoad = Math.min(99, cpuLoad + Math.floor(Math.random() * 15));
-  memoryUsage = Math.min(95, memoryUsage + Math.floor(Math.random() * 10));
-  return { cpu: cpuLoad, memory: memoryUsage };
-}
-
-// ============================================================================
-// 3. Create reactive graph
-// ============================================================================
-
-console.log('=== Reactive Monitoring Dashboard ===\n');
-
-// Lazy resolver — graph doesn't exist at handler-creation time
-let graphRef: ReactiveGraph;
-const getResolve = (): ResolveCallbackFn => graphRef.resolveCallback.bind(graphRef);
-
-// Handlers use createCallbackHandler for data-producing tasks and
-// createFireAndForgetHandler for side-effect-only tasks.
-// No explicit dataHash — the reactive layer auto-computes from data.
-
-const handlers: Record<string, TaskHandlerFn> = {
-  // Data-producing handlers — return data and let auto-hash do the rest
-  collect_cpu: createCallbackHandler(async ({ nodeId }) => {
-    const { cpu } = simulateMetrics();
-    console.log(`  [${nodeId}] CPU: ${cpu}%`);
-    return { cpu };
-  }, getResolve),
-
-  collect_memory: createCallbackHandler(async ({ nodeId }) => {
-    const { memory } = simulateMetrics();
-    console.log(`  [${nodeId}] Memory: ${memory}%`);
-    return { memory };
-  }, getResolve),
-
-  // evaluate_health uses conditional routing (on: { healthy, degraded, critical })
-  // resolveCallback doesn't support `result`, so we push directly to the graph
-  evaluate_health: async ({ nodeId, callbackToken }) => {
-    setTimeout(() => {
-      let status: string;
-      if (cpuLoad > 90 || memoryUsage > 90) {
-        status = 'critical';
-      } else if (cpuLoad > 70 || memoryUsage > 75) {
-        status = 'degraded';
-      } else {
-        status = 'healthy';
-      }
-      console.log(`  [${nodeId}] Health: ${status.toUpperCase()} (CPU=${cpuLoad}%, Mem=${memoryUsage}%)`);
-      // Use graph.push directly for conditional routing (result field)
-      graphRef.push({
-        type: 'task-completed',
-        taskName: nodeId,
-        result: status,
-        data: { status, cpu: cpuLoad, memory: memoryUsage },
-        timestamp: new Date().toISOString(),
-      });
-    }, 50);
-    return 'task-initiated';
-  },
-
-  // Side-effect-only handlers — fire and forget (logging, alerting)
-  alert_oncall: createFireAndForgetHandler(async ({ nodeId }) => {
-    console.log(`  [${nodeId}] 🚨 PAGING ON-CALL: System critical!`);
-    await sleep(100);
-  }, getResolve),
-
-  log_status: createFireAndForgetHandler(({ nodeId }) => {
-    console.log(`  [${nodeId}] ✅ System healthy — logged.`);
-  }, getResolve),
-
-  scale_up: createCallbackHandler(async ({ nodeId }) => {
-    console.log(`  [${nodeId}] ⚡ Scaling up infrastructure...`);
-    await sleep(100);
-    // Simulate scale failure 50% of the time
-    if (Math.random() > 0.5) {
-      throw new Error('Auto-scale service unavailable');
-    }
-    console.log(`  [${nodeId}] Scaled up successfully.`);
-    return {};
-  }, getResolve),
-
-  escalate: createFireAndForgetHandler(({ nodeId }) => {
-    console.log(`  [${nodeId}] 📢 Escalating to platform team — auto-scale failed.`);
-  }, getResolve),
-};
-
-const rg = createReactiveGraph(config, {
-  handlers,
-
-  onDrain: (events, live, result) => {
-    const statuses = Object.entries(live.state.tasks)
-      .map(([n, s]) => `${n}=${s.status}`)
-      .join(', ');
-    console.log(`  [drain] ${events.length} events | eligible: [${result.eligible.join(', ')}]`);
-  },
-});
-graphRef = rg;
-
-// ============================================================================
-// 4. Kick it off — one push, the graph drives itself
-// ============================================================================
-
-console.log('Phase 1: Initial metrics collection\n');
-rg.push({ type: 'inject-tokens', tokens: [], timestamp: new Date().toISOString() });
-
-await sleep(1000);
-
-// ============================================================================
-// 5. Add a Slack notification node at runtime
-// ============================================================================
-
-console.log('\n--- Adding Slack notification node at runtime ---\n');
-
-const slackConfig: TaskConfig = {
-  requires: ['system-degraded'],
-  provides: ['slack-notified'],
-  taskHandlers: ['notify_slack'],
-  description: 'Send alert to #incidents Slack channel',
-};
-
-// Use createFireAndForgetHandler — Slack notification is a side-effect
-const slackHandler: TaskHandlerFn = createFireAndForgetHandler(({ nodeId }) => {
-  console.log(`  [${nodeId}] 💬 Slack → #incidents: System degraded, auto-scaling...`);
-}, getResolve);
-
-rg.registerHandler('notify_slack', slackHandler);
-rg.addNode('notify_slack', slackConfig);
-
-await sleep(500);
-
-// ============================================================================
-// 6. Show final state
-// ============================================================================
-
-console.log('\n=== Final State ===\n');
-
-const state = rg.getState();
-for (const [name, task] of Object.entries(state.state.tasks)) {
-  const hash = task.lastDataHash ? ` (hash: ${task.lastDataHash})` : '';
-  console.log(`  ${name}: ${task.status} [${task.executionCount}x]${hash}`);
-}
-
-console.log(`\n  Outputs: [${state.state.availableOutputs.join(', ')}]`);
-
-// ============================================================================
-// 7. Validate reactive graph consistency
-// ============================================================================
-
-console.log('\n=== Validation ===');
-const validation = validateReactiveGraph({
-  graph: rg,
-  handlers: { ...handlers, notify_slack: slackHandler },
-});
-console.log(`  Valid: ${validation.valid} (${validation.issues.length} issues)`);
-for (const issue of validation.issues) {
-  console.log(`    [${issue.severity}] ${issue.code}: ${issue.message}`);
-}
-
-rg.dispose();
-
-// ============================================================================
-// Util
-// ============================================================================
-
-function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}