dspx 0.1.1-alpha.0

package/src/ts/examples/callbacks/advanced-router-features.ts

@@ -0,0 +1,326 @@
+/**
+ * Advanced Topic Router Features Example
+ *
+ * Demonstrates:
+ * 1. Concurrency control per route
+ * 2. Metrics tracking and monitoring
+ * 3. Pluggable backend handlers
+ * 4. Production-grade observability
+ */
+
+import {
+  createDspPipeline,
+  createTopicRouter,
+  createConsoleHandler,
+  createMockHandler,
+} from "../../index.js";
+
+console.log("Advanced Topic Router Features\n");
+
+// Example 1: Concurrency Control
+console.log("1. Concurrency Control (Prevent Alert Storms)\n");
+{
+  let alertCount = 0;
+  const slowAlertHandler = async () => {
+    alertCount++;
+    console.log(
+      `   [Alert ${alertCount}] Processing (simulating network call)...`
+    );
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    console.log(`   [Alert ${alertCount}] Complete`);
+  };
+
+  const router = createTopicRouter()
+    .errors(slowAlertHandler, {
+      concurrency: 2, // Max 2 concurrent alerts
+      trackMetrics: true,
+    })
+    .default(createConsoleHandler())
+    .build();
+
+  const pipeline = createDspPipeline();
+  pipeline
+    .pipeline({
+      onLogBatch: (logs) => router.routeBatch(logs),
+    })
+    .MovingAverage({ mode: "moving", windowSize: 3 });
+
+  console.log("   Processing with concurrency limit of 2...\n");
+
+  const samples = new Float32Array([1, 2, 3]);
+  await pipeline.process(samples, { sampleRate: 1000 });
+
+  console.log("\n   Metrics:");
+  const metrics = router.getMetrics();
+  metrics.forEach((m) => {
+    console.log(`   • Route: ${m.name}`);
+    console.log(`     Executions: ${m.executionCount}`);
+    console.log(`     Avg Duration: ${m.averageDuration.toFixed(2)}ms`);
+    console.log(
+      `     Min/Max: ${m.minDuration.toFixed(2)}ms / ${m.maxDuration.toFixed(
+        2
+      )}ms`
+    );
+  });
+
+  console.log();
+}
+
+// Example 2: Metrics Tracking
+console.log("2. Metrics Tracking (Mini-OpenTelemetry)\n");
+{
+  const mock = createMockHandler((log) => {
+    console.log(`   Tracked: [${log.topic}] ${log.message}`);
+  });
+
+  const router = createTopicRouter()
+    .performance(mock.handler, {
+      trackMetrics: true,
+      concurrency: 5,
+    })
+    .debug(mock.handler, {
+      trackMetrics: true,
+    })
+    .default(mock.handler, {
+      trackMetrics: false, // No tracking for default route
+    })
+    .build();
+
+  const pipeline = createDspPipeline();
+  pipeline
+    .pipeline({
+      onLogBatch: (logs) => router.routeBatch(logs),
+    })
+    .MovingAverage({ mode: "moving", windowSize: 3 })
+    .Rms({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array([1, -2, 3, -4, 5]);
+  await pipeline.process(samples, { sampleRate: 1000 });
+
+  console.log("\n   Route Metrics:");
+  const metrics = router.getMetrics();
+  metrics.forEach((m) => {
+    console.log(`\n   Route: ${m.name}`);
+    console.log(`   • Executions: ${m.executionCount}`);
+    console.log(`   • Total Duration: ${m.totalDuration.toFixed(2)}ms`);
+    console.log(`   • Avg Duration: ${m.averageDuration.toFixed(2)}ms`);
+    console.log(
+      `   • Min/Max: ${m.minDuration.toFixed(2)}ms / ${m.maxDuration.toFixed(
+        2
+      )}ms`
+    );
+    console.log(`   • Errors: ${m.errorCount}`);
+    console.log(
+      `   • Last Executed: ${
+        m.lastExecuted ? new Date(m.lastExecuted).toISOString() : "Never"
+      }`
+    );
+  });
+
+  console.log(`\n   Total logs captured: ${mock.getLogs().length}`);
+  console.log();
+}
+
+// Example 3: Pluggable Backends
+console.log("3. Pluggable Backend Handlers\n");
+{
+  console.log("   Using built-in handlers:\n");
+
+  // Simulate backend configurations
+  const mockPagerDuty = createMockHandler((log) => {
+    console.log(`   [PagerDuty] Alert triggered: ${log.message}`);
+  });
+
+  const mockPrometheus = createMockHandler((log) => {
+    console.log(`   [Prometheus] Metric recorded: ${log.topic}`);
+  });
+
+  const mockLoki = createMockHandler((log) => {
+    console.log(`   [Loki] Log stored: [${log.level}] ${log.message}`);
+  });
+
+  const router = createTopicRouter()
+    .errors(mockPagerDuty.handler, { trackMetrics: true })
+    .performance(mockPrometheus.handler, { trackMetrics: true })
+    .debug(mockLoki.handler, { trackMetrics: true })
+    .build();
+
+  const pipeline = createDspPipeline();
+  pipeline
+    .pipeline({
+      onLogBatch: (logs) => router.routeBatch(logs),
+    })
+    .MovingAverage({ mode: "moving", windowSize: 3 });
+
+  const samples = new Float32Array([1, 2, 3]);
+  await pipeline.process(samples, { sampleRate: 1000 });
+
+  console.log("\n   Backend Summary:");
+  console.log(`   • PagerDuty logs: ${mockPagerDuty.getLogs().length}`);
+  console.log(`   • Prometheus logs: ${mockPrometheus.getLogs().length}`);
+  console.log(`   • Loki logs: ${mockLoki.getLogs().length}`);
+  console.log();
+}
+
+// Example 4: Production-Grade Setup
+console.log("4. Production-Grade Configuration\n");
+{
+  console.log("   Multi-tier routing with metrics + concurrency:\n");
+
+  const criticalAlerts = createMockHandler((log) => {
+    console.log(`   [CRITICAL] ${log.message}`);
+  });
+
+  const performanceMetrics = createMockHandler((log) => {
+    console.log(`   [METRICS] ${log.topic}: ${JSON.stringify(log.context)}`);
+  });
+
+  const debugLogs = createMockHandler();
+
+  const router = createTopicRouter()
+    // Critical errors: Limited concurrency to prevent PagerDuty overload
+    .errors(criticalAlerts.handler, {
+      concurrency: 3,
+      trackMetrics: true,
+    })
+    // Performance: Higher concurrency for metrics
+    .performance(performanceMetrics.handler, {
+      concurrency: 10,
+      trackMetrics: true,
+    })
+    // Debug: No concurrency limit, but track metrics
+    .debug(debugLogs.handler, {
+      trackMetrics: true,
+    })
+    // Default: Console with no limits
+    .default(createConsoleHandler(), {
+      trackMetrics: false,
+    })
+    .build();
+
+  const pipeline = createDspPipeline();
+  pipeline
+    .pipeline({
+      onLogBatch: (logs) => router.routeBatch(logs),
+    })
+    .MovingAverage({ mode: "moving", windowSize: 10 })
+    .Rectify()
+    .Rms({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array(50).map(() => Math.random() * 10 - 5);
+  await pipeline.process(samples, { sampleRate: 48000 });
+
+  console.log("\n   Final Metrics Report:");
+  const metrics = router.getMetrics();
+
+  console.log(
+    "\n   ┌─────────────────────┬──────────┬─────────────┬────────────┐"
+  );
+  console.log(
+    "   │ Route               │ Exec     │ Avg (ms)    │ Errors     │"
+  );
+  console.log(
+    "   ├─────────────────────┼──────────┼─────────────┼────────────┤"
+  );
+
+  metrics.forEach((m) => {
+    const route = m.name.padEnd(19);
+    const exec = String(m.executionCount).padEnd(8);
+    const avg = m.averageDuration.toFixed(2).padEnd(11);
+    const errors = String(m.errorCount).padEnd(10);
+    console.log(`   │ ${route} │ ${exec} │ ${avg} │ ${errors} │`);
+  });
+
+  console.log(
+    "   └─────────────────────┴──────────┴─────────────┴────────────┘"
+  );
+
+  console.log("\n   Performance Insights:");
+  const totalExec = metrics.reduce((sum, m) => sum + m.executionCount, 0);
+  const avgLatency =
+    metrics.reduce((sum, m) => sum + m.averageDuration, 0) / metrics.length;
+  const totalErrors = metrics.reduce((sum, m) => sum + m.errorCount, 0);
+
+  console.log(`   • Total Route Executions: ${totalExec}`);
+  console.log(`   • Average Route Latency: ${avgLatency.toFixed(2)}ms`);
+  console.log(`   • Total Errors: ${totalErrors}`);
+  console.log(
+    `   • Success Rate: ${((1 - totalErrors / totalExec) * 100).toFixed(2)}%`
+  );
+}
+
+// Example 5: Priority-Based Routing
+console.log("\n5. Priority-Based Routing (NEW)\n");
+{
+  console.log(
+    "   Route critical errors to PagerDuty, warnings to Prometheus\n"
+  );
+
+  const pagerDuty = createMockHandler((log) => {
+    console.log(
+      `   [PagerDuty] ALERT: ${log.message} (priority: ${log.priority})`
+    );
+  });
+
+  const prometheus = createMockHandler((log) => {
+    console.log(
+      `   [Prometheus] Metric: ${log.message} (priority: ${log.priority})`
+    );
+  });
+
+  const loki = createMockHandler((log) => {
+    console.log(`   [Loki] Log: ${log.message} (priority: ${log.priority})`);
+  });
+
+  const router = createTopicRouter()
+    // Critical errors (9-10) → PagerDuty
+    .errors(pagerDuty.handler, {
+      minPriority: 9,
+      maxPriority: 10,
+      concurrency: 3,
+    })
+    // Warnings (7-8) → Prometheus
+    .custom(/^pipeline\./, prometheus.handler, {
+      minPriority: 7,
+      maxPriority: 8,
+    })
+    // All logs → Loki
+    .default(loki.handler, {
+      minPriority: 1,
+      maxPriority: 10,
+    })
+    .build();
+
+  const pipeline = createDspPipeline();
+  pipeline
+    .pipeline({
+      onLogBatch: (logs) => router.routeBatch(logs),
+    })
+    .MovingAverage({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array([1, 2, 3, 4, 5]);
+  await pipeline.process(samples, { sampleRate: 1000 });
+
+  console.log(`\n   Priority Summary:`);
+  console.log(
+    `   • PagerDuty (critical 9-10): ${pagerDuty.getLogs().length} alerts`
+  );
+  console.log(
+    `   • Prometheus (warn 7-8): ${prometheus.getLogs().length} metrics`
+  );
+  console.log(`   • Loki (all): ${loki.getLogs().length} logs`);
+}
+
+console.log("\nAdvanced Features Summary:");
+console.log("   - Concurrency Control - Prevent backend overload");
+console.log("   - Metrics Tracking - Built-in observability");
+console.log("   - Pluggable Backends - Drop-in integrations");
+console.log("   - Priority Routing - 10-level smart routing (NEW)");
+console.log("   - Production-Ready - Real-world patterns");
+
+console.log("\nUse Cases:");
+console.log("   • Rate-limit PagerDuty alerts (concurrency: 3)");
+console.log("   • Track route performance (trackMetrics: true)");
+console.log("   • Monitor error rates per backend");
+console.log("   • Route by priority (critical → PagerDuty, warn → metrics)");
+console.log("   • Optimize routing strategy with metrics");

package/src/ts/examples/callbacks/benchmark-circular-buffer.ts

@@ -0,0 +1,109 @@
+/**
+ * Benchmark: Circular Buffer vs Array for Log Pooling
+ * Demonstrates memory and performance benefits of circular buffer
+ */
+
+import { CircularLogBuffer } from "../../CircularLogBuffer.js";
+import type { LogEntry } from "../../types.js";
+
+function benchmarkArray(iterations: number, logsPerIteration: number): number {
+  const startTime = performance.now();
+
+  for (let i = 0; i < iterations; i++) {
+    const logPool: LogEntry[] = [];
+
+    // Simulate log accumulation
+    for (let j = 0; j < logsPerIteration; j++) {
+      logPool.push({
+        level: "info",
+        message: `Log entry ${j}`,
+        context: { iteration: i, index: j },
+        timestamp: performance.now(),
+      });
+    }
+
+    // Simulate flush
+    const logs = [...logPool];
+    // In real app: send logs to callback
+    const _sum = logs.length;
+  }
+
+  return performance.now() - startTime;
+}
+
+function benchmarkCircularBuffer(
+  iterations: number,
+  logsPerIteration: number
+): number {
+  const buffer = new CircularLogBuffer(32);
+  const startTime = performance.now();
+
+  for (let i = 0; i < iterations; i++) {
+    // Simulate log accumulation
+    for (let j = 0; j < logsPerIteration; j++) {
+      buffer.push({
+        level: "info",
+        message: `Log entry ${j}`,
+        context: { iteration: i, index: j },
+        timestamp: performance.now(),
+      });
+    }
+
+    // Simulate flush
+    const logs = buffer.flush();
+    // In real app: send logs to callback
+    const _sum = logs.length;
+  }
+
+  return performance.now() - startTime;
+}
+
+console.log("Benchmarking Log Pooling: Array vs Circular Buffer\n");
+
+const testCases = [
+  {
+    iterations: 1000,
+    logsPerIteration: 3,
+    description: "1000 iterations × 3 logs (typical usage)",
+  },
+  {
+    iterations: 10000,
+    logsPerIteration: 5,
+    description: "10000 iterations × 5 logs (high frequency)",
+  },
+  {
+    iterations: 100000,
+    logsPerIteration: 2,
+    description: "100000 iterations × 2 logs (extreme load)",
+  },
+];
+
+for (const testCase of testCases) {
+  console.log(`Test: ${testCase.description}`);
+
+  // Warm-up
+  benchmarkArray(10, testCase.logsPerIteration);
+  benchmarkCircularBuffer(10, testCase.logsPerIteration);
+
+  // Run benchmarks
+  const arrayTime = benchmarkArray(
+    testCase.iterations,
+    testCase.logsPerIteration
+  );
+  const circularTime = benchmarkCircularBuffer(
+    testCase.iterations,
+    testCase.logsPerIteration
+  );
+
+  console.log(`   Array approach:           ${arrayTime.toFixed(3)}ms`);
+  console.log(`   Circular buffer approach: ${circularTime.toFixed(3)}ms`);
+  console.log(`   Speedup: ${(arrayTime / circularTime).toFixed(2)}x faster`);
+  console.log(`   Time saved: ${(arrayTime - circularTime).toFixed(3)}ms\n`);
+}
+
+console.log("Key Benefits of Circular Buffer:");
+console.log("   - Fixed memory footprint (no array reallocations)");
+console.log("   - No garbage collection pressure from temporary arrays");
+console.log("   - Cache-friendly memory access pattern");
+console.log("   - Predictable performance under load");
+console.log("   - Handles burst logging gracefully (overwrites oldest)");

package/src/ts/examples/callbacks/monitoring-example.ts

@@ -0,0 +1,265 @@
+import { createDspPipeline } from "../../bindings.js";
+import type { PipelineCallbacks, LogLevel } from "../../types.js";
+
+/**
+ * Example: Real-time audio monitoring with callbacks
+ * Demonstrates selective callback usage for performance monitoring
+ */
+
+class PerformanceMonitor {
+  private stageTimes = new Map<string, number[]>();
+
+  recordStageTime(stage: string, durationMs: number) {
+    if (!this.stageTimes.has(stage)) {
+      this.stageTimes.set(stage, []);
+    }
+    this.stageTimes.get(stage)!.push(durationMs);
+  }
+
+  getStats(stage: string) {
+    const times = this.stageTimes.get(stage) || [];
+    if (times.length === 0) {
+      return { min: 0, max: 0, avg: 0, count: 0 };
+    }
+
+    return {
+      min: Math.min(...times),
+      max: Math.max(...times),
+      avg: times.reduce((a, b) => a + b, 0) / times.length,
+      count: times.length,
+    };
+  }
+
+  printReport() {
+    console.log("\nPerformance Report:");
+    console.log("─".repeat(70));
+    console.log(
+      "Stage".padEnd(30),
+      "Count".padEnd(10),
+      "Avg (ms)".padEnd(10),
+      "Min (ms)".padEnd(10),
+      "Max (ms)"
+    );
+    console.log("─".repeat(70));
+
+    for (const [stage, _] of this.stageTimes) {
+      const stats = this.getStats(stage);
+      console.log(
+        stage.padEnd(30),
+        stats.count.toString().padEnd(10),
+        stats.avg.toFixed(3).padEnd(10),
+        stats.min.toFixed(3).padEnd(10),
+        stats.max.toFixed(3)
+      );
+    }
+    console.log("─".repeat(70));
+  }
+}
+
+class SignalAnalyzer {
+  private peakCount = 0;
+  private clipCount = 0;
+
+  analyzeSample(value: number, index: number, stage: string) {
+    const absValue = Math.abs(value);
+
+    // Detect clipping (value at maximum)
+    if (absValue >= 0.99) {
+      this.clipCount++;
+      console.log(
+        `⚠️  Clipping detected at sample ${index} in ${stage}: ${value.toFixed(
+          4
+        )}`
+      );
+    }
+    // Detect peaks (high amplitude)
+    else if (absValue > 0.85) {
+      this.peakCount++;
+    }
+  }
+
+  getReport() {
+    return {
+      peaks: this.peakCount,
+      clips: this.clipCount,
+    };
+  }
+}
+
+async function monitoringExample() {
+  console.log("=".repeat(70));
+  console.log("Real-time Audio Monitoring with Callbacks");
+  console.log("=".repeat(70));
+  console.log();
+
+  const monitor = new PerformanceMonitor();
+  const analyzer = new SignalAnalyzer();
+
+  const callbacks: PipelineCallbacks = {
+    // Analyze every sample for clipping/peaks (can be disabled for performance)
+    onSample: (value, index, stage) => {
+      analyzer.analyzeSample(value, index, stage);
+    },
+
+    // Track performance of each processing run
+    onStageComplete: (stage, durationMs) => {
+      monitor.recordStageTime(stage, durationMs);
+    },
+
+    // Handle errors gracefully
+    onError: (stage, error) => {
+      console.error(`❌ Error in ${stage}:`, error.message);
+    },
+
+    // Structured logging
+    onLog: (level, msg, ctx) => {
+      const timestamp = new Date().toISOString();
+      const emoji = {
+        debug: "🔍",
+        info: "ℹ️",
+        warn: "⚠️",
+        error: "❌",
+      }[level];
+
+      if (level !== "debug") {
+        console.log(
+          `${emoji} [${timestamp}] [${level.toUpperCase()}] ${msg}`,
+          ctx ? JSON.stringify(ctx) : ""
+        );
+      }
+    },
+  };
+
+  // Build pipeline with comprehensive processing
+  const pipeline = createDspPipeline()
+    .pipeline(callbacks)
+    .MovingAverage({ mode: "moving", windowSize: 5 })
+    .Rectify({ mode: "full" })
+    .Rms({ mode: "moving", windowSize: 10 });
+
+  console.log("Processing audio batches...\n");
+
+  // Simulate multiple processing batches (like streaming audio)
+  const sampleRate = 44100;
+  const batchSize = 512; // Typical audio buffer size
+  const numBatches = 5;
+
+  for (let batch = 0; batch < numBatches; batch++) {
+    console.log(`\nProcessing batch ${batch + 1}/${numBatches}...`);
+
+    // Generate test signal with varying characteristics
+    const signal = new Float32Array(batchSize);
+    for (let i = 0; i < batchSize; i++) {
+      // Add some variation between batches
+      const amplitude = 0.5 + batch * 0.1;
+      signal[i] = Math.sin((2 * Math.PI * 440 * i) / sampleRate) * amplitude;
+
+      // Add occasional peaks
+      if (i % 100 === 0) {
+        signal[i] = 0.95;
+      }
+
+      // Add occasional clips in later batches
+      if (batch >= 3 && i % 150 === 0) {
+        signal[i] = 1.0; // Clipping!
+      }
+    }
+
+    await pipeline.process(signal, { sampleRate, channels: 1 });
+  }
+
+  // Print reports
+  monitor.printReport();
+
+  const signalStats = analyzer.getReport();
+  console.log("\nSignal Analysis:");
+  console.log("─".repeat(70));
+  console.log(`  Peak samples (> 0.85):       ${signalStats.peaks}`);
+  console.log(`  Clipped samples (>= 0.99):   ${signalStats.clips}`);
+  console.log("─".repeat(70));
+
+  console.log("\nMonitoring complete!\n");
+}
+
+async function selectiveCallbacksExample() {
+  console.log("\n" + "=".repeat(70));
+  console.log("Selective Callbacks Example (Performance-Optimized)");
+  console.log("=".repeat(70));
+  console.log();
+
+  let processCount = 0;
+
+  // Use only the callbacks you need for better performance
+  const lightweightCallbacks: PipelineCallbacks = {
+    // No onSample callback - saves significant overhead for large buffers
+    // onSample: undefined,
+
+    onStageComplete: (stage, durationMs) => {
+      processCount++;
+      console.log(
+        `✓ Batch ${processCount}: ${stage} completed in ${durationMs.toFixed(
+          3
+        )}ms`
+      );
+    },
+
+    // Only log errors and warnings
+    onLog: (level, msg, ctx) => {
+      if (level === "error" || level === "warn") {
+        console.log(`[${level.toUpperCase()}] ${msg}`, ctx || "");
+      }
+    },
+  };
+
+  const pipeline = createDspPipeline()
+    .pipeline(lightweightCallbacks)
+    .MovingAverage({ mode: "moving", windowSize: 3 })
+    .Rms({ mode: "moving", windowSize: 5 });
+
+  console.log("Processing large batches without per-sample callbacks...\n");
+
+  // Process larger buffers more efficiently
+  const largeBuffer = new Float32Array(4096);
+  for (let i = 0; i < largeBuffer.length; i++) {
+    largeBuffer[i] = Math.random() * 0.5;
+  }
+
+  const iterations = 10;
+  const startTime = performance.now();
+
+  for (let i = 0; i < iterations; i++) {
+    await pipeline.process(largeBuffer, { sampleRate: 44100, channels: 1 });
+  }
+
+  const totalTime = performance.now() - startTime;
+  const avgTime = totalTime / iterations;
+
+  console.log("\n" + "─".repeat(70));
+  console.log(
+    `Processed ${iterations} batches of ${largeBuffer.length} samples`
+  );
+  console.log(`Total time: ${totalTime.toFixed(2)}ms`);
+  console.log(`Average per batch: ${avgTime.toFixed(3)}ms`);
+  console.log(
+    `Throughput: ${(
+      (largeBuffer.length * iterations) /
+      (totalTime / 1000)
+    ).toFixed(0)} samples/sec`
+  );
+  console.log("─".repeat(70));
+
+  console.log("\nPerformance test complete!\n");
+}
+
+async function main() {
+  try {
+    // Run both examples
+    await monitoringExample();
+    await selectiveCallbacksExample();
+  } catch (error) {
+    console.error("Example failed:", error);
+    process.exit(1);
+  }
+}
+
+main();