dspx 0.1.1-alpha.0

package/src/ts/examples/callbacks/production-topic-router.ts

@@ -0,0 +1,214 @@
+/**
+ * Production Topic Router Example
+ *
+ * Demonstrates fan-out routing to multiple observability backends:
+ * - Errors → PagerDuty/Alerting
+ * - Performance → Prometheus/Metrics
+ * - Debug → Loki/Centralized Logging
+ */
+
+import { createDspPipeline, createTopicRouter } from "../../index.js";
+import type { LogEntry } from "../../types.js";
+
+console.log("Production Topic Router Example\n");
+
+// Simulate observability backends
+const backends = {
+  pagerDuty: {
+    alert: async (log: LogEntry) => {
+      console.log(`  🚨 [PagerDuty] ALERT: ${log.message}`);
+      console.log(`     Topic: ${log.topic}`);
+      console.log(`     Context:`, log.context);
+    },
+  },
+
+  prometheus: {
+    record: async (topic: string, context?: Record<string, any>) => {
+      console.log(`  [Prometheus] Metric recorded`);
+      console.log(`     Metric: ${topic}`);
+      console.log(`     Labels:`, context);
+    },
+  },
+
+  loki: {
+    send: async (log: LogEntry) => {
+      console.log(`  [Loki] Log ingested`);
+      console.log(`     Level: ${log.level}`);
+      console.log(`     Message: ${log.message}`);
+    },
+  },
+
+  cloudwatch: {
+    send: async (log: LogEntry) => {
+      console.log(`  [CloudWatch] Log sent`);
+      console.log(`     Stream: ${log.topic}`);
+    },
+  },
+};
+
+console.log("1. Builder Pattern (Recommended)\n");
+{
+  const router = createTopicRouter()
+    .errors(backends.pagerDuty.alert)
+    .performance((log) => backends.prometheus.record(log.topic!, log.context))
+    .debug(backends.loki.send)
+    .default(backends.cloudwatch.send) // Catch-all
+    .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();
+}
+
+console.log("2. Manual Route Configuration\n");
+{
+  const router = createTopicRouter()
+    .custom(/^pipeline\.error/, backends.pagerDuty.alert, "error-alerts")
+    .custom(
+      /^pipeline\.stage\.rms/,
+      (log) => backends.prometheus.record(log.topic!, log.context),
+      "rms-metrics"
+    )
+    .custom(
+      /^pipeline\.performance/,
+      (log) => backends.prometheus.record(log.topic!, log.context),
+      "performance-metrics"
+    )
+    .custom(/.*/, backends.loki.send, "default-logs")
+    .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();
+}
+
+console.log("3. Multi-Backend Routing (Fan-Out)\n");
+{
+  // Route errors to BOTH PagerDuty AND CloudWatch
+  const router = createTopicRouter()
+    .errors(async (log) => {
+      await backends.pagerDuty.alert(log);
+      await backends.cloudwatch.send(log);
+    })
+    .performance((log) => backends.prometheus.record(log.topic!, log.context))
+    .default(backends.loki.send)
+    .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();
+}
+
+console.log("4. Stage-Specific Routing\n");
+{
+  const router = createTopicRouter()
+    .stage("rms", async (log) => {
+      console.log(`  [RMS-Specific] ${log.message}`);
+      await backends.prometheus.record(log.topic!, log.context);
+    })
+    .stage("movingAverage", async (log) => {
+      console.log(`  [MA-Specific] ${log.message}`);
+      await backends.loki.send(log);
+    })
+    .default(backends.cloudwatch.send)
+    .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();
+}
+
+console.log("5. Real-World Production Pattern\n");
+{
+  console.log("  Routing Configuration:");
+  console.log("     • Errors        → PagerDuty (critical alerts)");
+  console.log("     • Performance   → Prometheus (metrics)");
+  console.log("     • Debug         → Loki (centralized logs)");
+  console.log("     • Everything    → CloudWatch (backup/audit)\n");
+
+  const router = createTopicRouter()
+    // Critical: Alert on errors
+    .errors(async (log) => {
+      console.log(`  🚨 [CRITICAL] Alerting team via PagerDuty`);
+      await backends.pagerDuty.alert(log);
+      await backends.cloudwatch.send(log); // Backup to CloudWatch
+    })
+
+    // Metrics: Export to Prometheus
+    .performance(async (log) => {
+      await backends.prometheus.record(log.topic!, log.context);
+      await backends.cloudwatch.send(log);
+    })
+
+    // Debug: Send to Loki
+    .debug(async (log) => {
+      await backends.loki.send(log);
+      await backends.cloudwatch.send(log);
+    })
+
+    // Default: CloudWatch only
+    .default(backends.cloudwatch.send)
+    .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(100).map(() => Math.random() * 10 - 5);
+  await pipeline.process(samples, { sampleRate: 48000 });
+
+  console.log("\n  Logs routed to multiple backends in parallel");
+}
+
+console.log("\nKey Benefits:");
+console.log("   - Fan-out: Single log → Multiple backends");
+console.log("   - Non-blocking: All routes processed in parallel");
+console.log("   - Extensible: Add new routes without changing pipeline code");
+console.log("   - Production-safe: Matches Loki, OTEL, FluentBit patterns");
+console.log("   - Type-safe: Full TypeScript support");
+
+console.log("\nProduction Deployment:");
+console.log("   • Add rate limiting (p-queue) for alert storms");
+console.log("   • Add retry logic for failed backend calls");
+console.log("   • Add buffering for network outages");
+console.log("   • Add metrics on router performance");
+console.log("   • Configure topic conventions for your org");

package/src/ts/examples/callbacks/topic-based-logging.ts

@@ -0,0 +1,161 @@
+/**
+ * Topic-Based Logging Example
+ *
+ * Demonstrates Kafka-style topic-based log filtering and routing.
+ * Topics follow hierarchical structure: pipeline.stage.<name>.<category>
+ */
+
+import { createDspPipeline } from "../../bindings.js";
+import type { LogEntry } from "../../types.js";
+
+console.log("Topic-Based Logging Example\n");
+
+// Example 1: Subscribe to all logs (no filter)
+console.log("1. All Logs (no filter):");
+{
+  const processor = createDspPipeline();
+  processor.pipeline({
+    onLogBatch: (logs: LogEntry[]) => {
+      logs.forEach((log: LogEntry) => {
+        console.log(
+          `   [${log.topic}] ${log.level.toUpperCase()}: ${log.message}`
+        );
+      });
+    },
+  });
+
+  processor.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array([1, -2, 3, -4, 5]);
+  await processor.process(samples, { sampleRate: 1000 });
+}
+
+console.log("\n2. Filter by Stage (pipeline.stage.rms.*):");
+{
+  const processor = createDspPipeline();
+  processor.pipeline({
+    onLogBatch: (logs: LogEntry[]) => {
+      console.log(`   Received ${logs.length} logs from RMS stage:`);
+      logs.forEach((log: LogEntry) => {
+        console.log(`   [${log.topic}] ${log.message}`);
+      });
+    },
+    topicFilter: "pipeline.stage.rms.*", // Only RMS logs
+  });
+
+  processor.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array([1, -2, 3, -4, 5]);
+  await processor.process(samples, { sampleRate: 1000 });
+}
+
+console.log("\n3. Filter by Category (Errors Only - *.error):");
+{
+  const processor = createDspPipeline();
+  processor.pipeline({
+    onLogBatch: (logs: LogEntry[]) => {
+      if (logs.length > 0) {
+        console.log(`   🚨 Received ${logs.length} error logs:`);
+        logs.forEach((log: LogEntry) => {
+          console.log(`   [${log.topic}] ${log.message}`);
+        });
+      } else {
+        console.log("   No errors detected");
+      }
+    },
+    topicFilter: "pipeline.*.error", // Only errors from any stage
+  });
+
+  processor.MovingAverage({ mode: "moving", windowSize: 3 });
+  const samples = new Float32Array([1, 2, 3, 4, 5]);
+  await processor.process(samples, { sampleRate: 1000 });
+}
+
+console.log("\n4. Multiple Topic Filters (Errors + Performance):");
+{
+  const processor = createDspPipeline();
+  processor.pipeline({
+    onLogBatch: (logs: LogEntry[]) => {
+      console.log(`   Received ${logs.length} logs:`);
+      logs.forEach((log: LogEntry) => {
+        const icon = log.topic?.includes("error") ? "🚨" : "⏱️";
+        console.log(`   ${icon} [${log.topic}] ${log.message}`);
+      });
+    },
+    topicFilter: [
+      "pipeline.*.error", // All errors
+      "pipeline.*.performance", // All performance metrics
+    ],
+  });
+
+  processor.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array([1, -2, 3, -4, 5]);
+  await processor.process(samples, { sampleRate: 1000 });
+}
+
+console.log("\n5. Topic-Based Routing (Production Pattern):");
+{
+  // Simulate different backends for different topics
+  const errorAlerts: any[] = [];
+  const metrics: any[] = [];
+  const debugLogs: any[] = [];
+
+  const processor = createDspPipeline();
+  processor.pipeline({
+    onLogBatch: (logs: LogEntry[]) => {
+      // Route logs to different backends based on topic
+      logs.forEach((log: LogEntry) => {
+        if (log.topic?.includes("error")) {
+          errorAlerts.push(log);
+        } else if (
+          log.topic?.includes("performance") ||
+          log.topic?.includes("samples")
+        ) {
+          metrics.push(log);
+        } else {
+          debugLogs.push(log);
+        }
+      });
+
+      console.log(`   Routed logs:`);
+      console.log(`      → Error alerts: ${errorAlerts.length}`);
+      console.log(`      → Metrics: ${metrics.length}`);
+      console.log(`      → Debug logs: ${debugLogs.length}`);
+    },
+  });
+
+  processor.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 5 });
+
+  const samples = new Float32Array([1, -2, 3, -4, 5]);
+  await processor.process(samples, { sampleRate: 1000 });
+}
+
+console.log("\n6. Topic Structure Examples:");
+console.log("   Topic Hierarchy:");
+console.log("   ├── pipeline.debug               (General debug logs)");
+console.log("   ├── pipeline.info                (General info logs)");
+console.log("   ├── pipeline.warn                (General warnings)");
+console.log("   ├── pipeline.error               (General errors)");
+console.log("   └── pipeline.stage.<name>.*      (Stage-specific logs)");
+console.log("       ├── samples                  (Sample-level data)");
+console.log("       ├── performance              (Timing/metrics)");
+console.log("       └── error                    (Stage errors)");
+
+console.log("\n   Topic Filter Patterns:");
+console.log("   • 'pipeline.stage.*'             → All stage logs");
+console.log("   • 'pipeline.stage.rms.*'         → Only RMS stage logs");
+console.log("   • 'pipeline.*.error'             → All errors (any stage)");
+console.log("   • 'pipeline.*.performance'       → All performance metrics");
+console.log(
+  "   • ['pipeline.error', 'pipeline.stage.*.error'] → Multiple patterns"
+);
+
+console.log("\nTopic-based logging complete!");
+console.log("\nProduction Benefits:");
+console.log("   • Selective subscription reduces processing overhead");
+console.log(
+  "   • Route different topics to different backends (Kafka, Loki, etc.)"
+);
+console.log("   • Filter at source instead of post-processing");
+console.log("   • Aligns with industry telemetry standards");

package/src/ts/examples/chaining/test-chaining-redis.ts

@@ -0,0 +1,113 @@
+/**
+ * Chained DSP Pipeline (MovingAverage → RMS → Rectify)
+ * with Redis state persistence.
+ *
+ * This verifies:
+ *  - Multi-stage serialization to Redis
+ *  - Restoration from Redis into a fresh pipeline
+ *  - Stateless Rectify doesn’t corrupt persisted filters
+ *  - Outputs match expected chaining results
+ */
+
+import { createClient } from "redis";
+import { createDspPipeline } from "../../bindings";
+
+async function testChainingWithRedis(startFresh = false) {
+  console.log("=== DSP Chaining + Redis State Persistence Test ===\n");
+
+  // 1. Connect to Redis
+  const redis = await createClient({ url: "redis://localhost:6379" }).connect();
+  const stateKey = "dsp:pipeline:chained";
+
+  if (startFresh) {
+    console.log("Clearing previous Redis state...");
+    await redis.del(stateKey);
+    console.log("Redis state cleared.\n");
+  }
+
+  // 2. Create a chained pipeline
+  const pipeline = createDspPipeline({
+    redisHost: "localhost",
+    redisPort: 6379,
+    stateKey,
+  });
+
+  pipeline.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 3 }).Rectify();
+
+  console.log("Pipeline: MovingAverage → RMS → Rectify\n");
+
+  // 3️. Attempt to restore previous state
+  const previousState = await redis.get(stateKey);
+  if (previousState) {
+    console.log("Found existing state in Redis. Restoring...\n");
+    await pipeline.loadState(previousState);
+    console.log("State restored successfully!\n");
+  } else {
+    console.log("No previous state found — starting fresh.\n");
+  }
+
+  // 4. Process first batch
+  const batch1 = new Float32Array([1, -2, 3, -4, 5, -6]);
+  console.log("Input batch 1:", Array.from(batch1));
+
+  const output1 = await pipeline.processCopy(batch1, {
+    sampleRate: 1000,
+  });
+  console.log(
+    "Output batch 1:",
+    Array.from(output1).map((v) => v.toFixed(4))
+  );
+
+  // 5. Save state to Redis
+  const state1 = await pipeline.saveState();
+  await redis.set(stateKey, state1);
+  console.log("\nState saved to Redis:");
+  console.log(JSON.stringify(JSON.parse(state1), null, 2));
+
+  // 6. Simulate process restart
+  console.log("\n--- Simulating Restart ---\n");
+  const pipeline2 = createDspPipeline({
+    redisHost: "localhost",
+    redisPort: 6379,
+    stateKey,
+  });
+
+  pipeline2.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 3 }).Rectify();
+
+  const restoredState = await redis.get(stateKey);
+  if (restoredState) {
+    console.log("Restoring pipeline from Redis...");
+    await pipeline2.loadState(restoredState);
+    console.log("Pipeline state fully restored.\n");
+  }
+
+  // 7. Process second batch (continuation test)
+  const batch2 = new Float32Array([7, -8, 9]);
+  console.log("Input batch 2:", Array.from(batch2));
+
+  const output2 = await pipeline2.processCopy(batch2, {
+    sampleRate: 1000,
+  });
+  console.log(
+    "Output batch 2:",
+    Array.from(output2).map((v) => v.toFixed(4))
+  );
+
+  // 8. Inspect rectifier behavior (stateless)
+  const savedState2 = await pipeline2.saveState();
+  const parsed = JSON.parse(savedState2);
+  const rectifyState = parsed.stages.find((s: any) => s.type === "rectify");
+
+  console.log("\nRectify stage state:");
+  console.log(rectifyState || "Rectify stage not found in saved state!");
+
+  console.log("\nChaining + Redis test complete!");
+
+  // 9. Disconnect from Redis
+  await redis.disconnect();
+}
+
+// Toggle this to reset Redis between runs
+const START_FRESH = false;
+
+testChainingWithRedis(START_FRESH).catch(console.error);

package/src/ts/examples/chaining/test-chaining.ts

@@ -0,0 +1,52 @@
+// src/ts/examples/test-chaining.ts
+import { createDspPipeline } from "../../bindings";
+
+async function testChaining() {
+  console.log("=== Testing DSP Stage Chaining ===\n");
+
+  const pipeline = createDspPipeline();
+  pipeline.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 3 }).Rectify();
+
+  console.log("Pipeline: MovingAverage → RMS → Rectify");
+
+  const input = new Float32Array([1, -2, 3, -4, 5, -6]);
+  console.log("Input:", Array.from(input));
+
+  // sampleRate REQUIRED, channels optional
+  const output = await pipeline.processCopy(input, {
+    sampleRate: 1000, // required
+    // channels: 1      // optional; defaults to 1
+  });
+
+  console.log(
+    "Output:",
+    Array.from(output).map((v) => v.toFixed(4))
+  );
+
+  const state = await pipeline.saveState();
+  console.log("\n--- Saved State ---");
+  console.log(JSON.stringify(JSON.parse(state), null, 2));
+
+  // Simulate restart
+  const pipeline2 = createDspPipeline();
+  pipeline2.MovingAverage({ mode: "moving", windowSize: 3 }).Rms({ mode: "moving", windowSize: 3 }).Rectify();
+
+  await pipeline2.loadState(state);
+  console.log("\nState restored.");
+
+  const nextInput = new Float32Array([7, -8, 9]);
+  const nextOutput = await pipeline2.processCopy(nextInput, {
+    sampleRate: 1000, // required
+    // channels: 1
+  });
+
+  console.log("Next input:", Array.from(nextInput));
+  console.log(
+    "Next output:",
+    Array.from(nextOutput).map((v) => v.toFixed(4))
+  );
+
+  console.log("\nChaining test complete!");
+}
+
+testChaining().catch(console.error);