dspx 0.1.1-alpha.0

package/src/ts/__tests__/Tap.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Unit tests for .tap() method
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { createDspPipeline } from "../bindings.js";
+
+describe("Tap Method", () => {
+  it("should execute tap callback after processing", async () => {
+    let tapCalled = false;
+    let tappedSamples: Float32Array | null = null;
+    let tappedStage = "";
+
+    const pipeline = createDspPipeline()
+      .MovingAverage({ mode: "moving", windowSize: 3 })
+      .tap((samples, stage) => {
+        tapCalled = true;
+        tappedSamples = samples;
+        tappedStage = stage;
+      });
+
+    const input = new Float32Array([1, 2, 3, 4, 5]);
+    await pipeline.process(input, { sampleRate: 1000 });
+
+    assert.strictEqual(tapCalled, true);
+    assert.notStrictEqual(tappedSamples, null);
+    assert.strictEqual(tappedStage, "movingAverage:moving");
+  });
+
+  it("should support multiple tap calls in chain", async () => {
+    const tapLog: Array<{ stage: string; firstValue: number }> = [];
+
+    const pipeline = createDspPipeline()
+      .MovingAverage({ mode: "moving", windowSize: 2 })
+      .tap((samples, stage) => {
+        tapLog.push({ stage, firstValue: samples[0] });
+      })
+      .Rectify({ mode: "full" })
+      .tap((samples, stage) => {
+        tapLog.push({ stage, firstValue: samples[0] });
+      })
+      .Rms({ mode: "moving", windowSize: 2 })
+      .tap((samples, stage) => {
+        tapLog.push({ stage, firstValue: samples[0] });
+      });
+
+    const input = new Float32Array([1, -2, 3, -4, 5]);
+    await pipeline.process(input, { sampleRate: 1000 });
+
+    assert.strictEqual(tapLog.length, 3);
+    assert.strictEqual(tapLog[0].stage, "movingAverage:moving");
+    assert.strictEqual(tapLog[1].stage, "movingAverage:moving → rectify:full");
+    assert.strictEqual(
+      tapLog[2].stage,
+      "movingAverage:moving → rectify:full → rms:moving"
+    );
+  });
+
+  it("should not modify the data in tap callback", async () => {
+    const pipeline = createDspPipeline()
+      .MovingAverage({ mode: "moving", windowSize: 2 })
+      .tap((samples) => {
+        // Try to modify (should not affect final result since it's after processing)
+        samples[0] = 999;
+      });
+
+    const input = new Float32Array([1, 2, 3, 4, 5]);
+    const result = await pipeline.process(input, { sampleRate: 1000 });
+
+    // Since tap is called after native processing completes, the modification
+    // will actually persist (samples reference the result buffer)
+    assert.strictEqual(result[0], 999);
+  });
+
+  it("should handle errors in tap callback gracefully", async () => {
+    let processCompleted = false;
+
+    const pipeline = createDspPipeline()
+      .MovingAverage({ mode: "moving", windowSize: 2 })
+      .tap(() => {
+        throw new Error("Tap error!");
+      });
+
+    const input = new Float32Array([1, 2, 3, 4, 5]);
+
+    // Should not throw, error is caught and logged
+    const result = await pipeline.process(input, { sampleRate: 1000 });
+    processCompleted = true;
+
+    assert.strictEqual(processCompleted, true);
+    assert.notStrictEqual(result, null);
+  });
+
+  it("should work with empty pipeline (no stages)", async () => {
+    let tapCalled = false;
+
+    const pipeline = createDspPipeline().tap((samples, stage) => {
+      tapCalled = true;
+      assert.strictEqual(stage, "start");
+    });
+
+    const input = new Float32Array([1, 2, 3]);
+    await pipeline.process(input, { sampleRate: 1000 });
+
+    assert.strictEqual(tapCalled, true);
+  });
+
+  it("should receive a view of the actual result buffer", async () => {
+    let tappedBuffer: Float32Array | null = null;
+
+    const pipeline = createDspPipeline()
+      .MovingAverage({ mode: "moving", windowSize: 2 })
+      .tap((samples) => {
+        tappedBuffer = samples;
+      });
+
+    const input = new Float32Array([1, 2, 3, 4, 5]);
+    const result = await pipeline.process(input, { sampleRate: 1000 });
+
+    // Should be the same reference
+    assert.strictEqual(tappedBuffer, result);
+  });
+
+  it("should support inspection of sample slices", async () => {
+    const inspectedSlices: number[][] = [];
+
+    const pipeline = createDspPipeline()
+      .MovingAverage({ mode: "moving", windowSize: 3 })
+      .tap((samples) => {
+        // Common pattern: inspect first few samples
+        inspectedSlices.push(Array.from(samples.slice(0, 3)));
+      })
+      .Rectify();
+
+    const input = new Float32Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    await pipeline.process(input, { sampleRate: 1000 });
+
+    assert.strictEqual(inspectedSlices.length, 1);
+    assert.strictEqual(inspectedSlices[0].length, 3);
+  });
+
+  it("should work with pipeline callbacks simultaneously", async () => {
+    let tapCalled = false;
+    let onBatchCalled = false;
+
+    const pipeline = createDspPipeline()
+      .pipeline({
+        onBatch: () => {
+          onBatchCalled = true;
+        },
+      })
+      .MovingAverage({ mode: "moving", windowSize: 2 })
+      .tap(() => {
+        tapCalled = true;
+      });
+
+    const input = new Float32Array([1, 2, 3]);
+    await pipeline.process(input, { sampleRate: 1000 });
+
+    assert.strictEqual(tapCalled, true);
+    assert.strictEqual(onBatchCalled, true);
+  });
+});

package/src/ts/__tests__/TimeBasedExpiration.test.ts

@@ -0,0 +1,124 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import { createDspPipeline } from "../index.js";
+
+describe("True Time-Based Expiration", () => {
+  test("should expire samples based on age, not count", async () => {
+    const pipeline = createDspPipeline();
+    // 1 second window with timestamps
+    pipeline.MovingAverage({ mode: "moving", windowDuration: 1000 });
+
+    // Add 3 samples within 500ms
+    const batch1 = new Float32Array([10, 20, 30]);
+    const timestamps1 = new Float32Array([0, 100, 200]);
+
+    const result1 = await pipeline.process(batch1, timestamps1, {
+      channels: 1,
+    });
+
+    // Average of [10, 20, 30] = 20
+    assert.ok(Math.abs(result1[2] - 20) < 0.01, "Expected average of ~20");
+
+    // Add a sample 2 seconds later - should expire all previous samples
+    const batch2 = new Float32Array([100]);
+    const timestamps2 = new Float32Array([2200]); // 2.2 seconds from start
+
+    const result2 = await pipeline.process(batch2, timestamps2, {
+      channels: 1,
+    });
+
+    // Should only have the new sample (100), since all previous ones are > 1 second old
+    assert.ok(
+      Math.abs(result2[0] - 100) < 0.01,
+      `Expected only new sample (100), got ${result2[0]}`
+    );
+  });
+
+  test("should work with irregular sampling", async () => {
+    const pipeline = createDspPipeline();
+    // 500ms window
+    pipeline.MovingAverage({ mode: "moving", windowDuration: 500 });
+
+    // Irregular timestamps: 0ms, 50ms, 600ms, 650ms
+    const samples = new Float32Array([10, 20, 30, 40]);
+    const timestamps = new Float32Array([0, 50, 600, 650]);
+
+    const result = await pipeline.process(samples, timestamps, {
+      channels: 1,
+    });
+
+    // At timestamp 0: avg([10]) = 10
+    assert.ok(Math.abs(result[0] - 10) < 0.01, "First sample should be 10");
+
+    // At timestamp 50: avg([10, 20]) = 15
+    assert.ok(
+      Math.abs(result[1] - 15) < 0.01,
+      "Second should be avg(10,20)=15"
+    );
+
+    // At timestamp 600: samples at 0 and 50 are expired (>500ms old)
+    // Only sample at 600ms, so avg([30]) = 30
+    assert.ok(
+      Math.abs(result[2] - 30) < 0.01,
+      `Third should be 30 (old samples expired), got ${result[2]}`
+    );
+
+    // At timestamp 650: samples at 600 and 650 are within 500ms
+    // avg([30, 40]) = 35
+    assert.ok(
+      Math.abs(result[3] - 35) < 0.01,
+      "Fourth should be avg(30,40)=35"
+    );
+  });
+
+  test("should handle streaming with time-based windows", async () => {
+    const pipeline = createDspPipeline();
+    // 300ms window
+    pipeline.MovingAverage({ mode: "moving", windowDuration: 300 });
+
+    // First chunk: samples at 0, 100, 200ms
+    const chunk1 = new Float32Array([10, 20, 30]);
+    const ts1 = new Float32Array([0, 100, 200]);
+    const result1 = await pipeline.process(chunk1, ts1, { channels: 1 });
+
+    // At 200ms: avg([10, 20, 30]) = 20
+    assert.ok(Math.abs(result1[2] - 20) < 0.01, "First chunk avg should be 20");
+
+    // Second chunk: samples at 250, 600ms
+    // At 250ms: all previous samples still valid (within 300ms)
+    // At 600ms: samples at 0, 100, 200, 250 all expired (>300ms old)
+    const chunk2 = new Float32Array([40, 100]);
+    const ts2 = new Float32Array([250, 600]);
+    const result2 = await pipeline.process(chunk2, ts2, { channels: 1 });
+
+    // At 250ms: avg([10, 20, 30, 40]) = 25
+    assert.ok(
+      Math.abs(result2[0] - 25) < 0.01,
+      `At 250ms expected avg(10,20,30,40)=25, got ${result2[0]}`
+    );
+
+    // At 600ms: only sample at 600ms remains, avg([100]) = 100
+    assert.ok(
+      Math.abs(result2[1] - 100) < 0.01,
+      `At 600ms expected 100 (all previous expired), got ${result2[1]}`
+    );
+  });
+
+  test("should only use time-based expiration when timestamps provided", async () => {
+    const pipeline = createDspPipeline();
+    // Both windowSize and windowDuration specified
+    pipeline.MovingAverage({ mode: "moving", windowDuration: 1000 });
+
+    // Process without timestamps - should use sample-count mode
+    const samples1 = new Float32Array([1, 2, 3, 4, 5]);
+
+    // This should work without timestamps (falls back to sample-count mode)
+    const result1 = await pipeline.process(samples1, {
+      channels: 1,
+      sampleRate: 1000, // Required when no timestamps
+    });
+
+    assert.ok(result1 instanceof Float32Array);
+    assert.strictEqual(result1.length, 5);
+  });
+});

package/src/ts/__tests__/TimeBasedRmsAndMav.test.ts

@@ -0,0 +1,231 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { createDspPipeline } from "../index.js";
+
+test("Time-Based RMS", async (t) => {
+  await t.test("should expire samples based on age for RMS", async () => {
+    const pipeline = createDspPipeline();
+    // 1 second window
+    pipeline.Rms({ mode: "moving", windowDuration: 1000 });
+
+    // First 3 samples at 0, 100, 200ms - values 1, 2, 3
+    const chunk1 = new Float32Array([1, 2, 3]);
+    const ts1 = new Float32Array([0, 100, 200]);
+    const result1 = await pipeline.process(chunk1, ts1, { channels: 1 });
+
+    // At 200ms: RMS([1, 2, 3]) = sqrt((1 + 4 + 9) / 3) = sqrt(14/3) ≈ 2.16
+    assert.ok(
+      Math.abs(result1[2] - Math.sqrt(14 / 3)) < 0.01,
+      `Expected RMS ≈ 2.16, got ${result1[2]}`
+    );
+
+    // Sample at 2200ms - 2.2 seconds later (>1s window)
+    // Samples at 0, 100, 200ms should be EXPIRED
+    const chunk2 = new Float32Array([4]);
+    const ts2 = new Float32Array([2200]);
+    const result2 = await pipeline.process(chunk2, ts2, { channels: 1 });
+
+    // At 2200ms: only sample at 2200ms remains, RMS([4]) = 4
+    assert.ok(
+      Math.abs(result2[0] - 4.0) < 0.01,
+      `Expected RMS = 4.0, got ${result2[0]}`
+    );
+  });
+
+  await t.test("should work with irregular sampling for RMS", async () => {
+    const pipeline = createDspPipeline();
+    // 500ms window
+    pipeline.Rms({ mode: "moving", windowDuration: 500 });
+
+    const samples = new Float32Array([2, 4, 6, 8]);
+    const timestamps = new Float32Array([
+      0, // Sample at 0ms
+      50, // Sample at 50ms
+      600, // Sample at 600ms (550ms gap!)
+      650, // Sample at 650ms
+    ]);
+
+    const result = await pipeline.process(samples, timestamps, { channels: 1 });
+
+    // At 650ms with 500ms window:
+    // - Sample at 0ms EXPIRED (650 - 0 = 650ms > 500ms)
+    // - Sample at 50ms EXPIRED (650 - 50 = 600ms > 500ms)
+    // - Sample at 600ms KEPT (650 - 600 = 50ms < 500ms)
+    // - Sample at 650ms KEPT (current)
+    // RMS([6, 8]) = sqrt((36 + 64) / 2) = sqrt(50) ≈ 7.07
+    assert.ok(
+      Math.abs(result[3] - Math.sqrt(50)) < 0.01,
+      `Expected RMS ≈ 7.07, got ${result[3]}`
+    );
+  });
+
+  await t.test(
+    "should handle streaming with time-based windows for RMS",
+    async () => {
+      const pipeline = createDspPipeline();
+      // 300ms window
+      pipeline.Rms({ mode: "moving", windowDuration: 300 });
+
+      // First chunk: samples at 0, 100, 200ms
+      const chunk1 = new Float32Array([1, 2, 3]);
+      const ts1 = new Float32Array([0, 100, 200]);
+      const result1 = await pipeline.process(chunk1, ts1, { channels: 1 });
+
+      // At 200ms: RMS([1, 2, 3]) = sqrt(14/3) ≈ 2.16
+      assert.ok(
+        Math.abs(result1[2] - Math.sqrt(14 / 3)) < 0.01,
+        "First chunk RMS should be sqrt(14/3)"
+      );
+
+      // Second chunk: samples at 250, 600ms
+      const chunk2 = new Float32Array([4, 10]);
+      const ts2 = new Float32Array([250, 600]);
+      const result2 = await pipeline.process(chunk2, ts2, { channels: 1 });
+
+      // At 250ms: all previous samples still valid (within 300ms)
+      // RMS([1, 2, 3, 4]) = sqrt((1 + 4 + 9 + 16) / 4) = sqrt(7.5) ≈ 2.74
+      assert.ok(
+        Math.abs(result2[0] - Math.sqrt(7.5)) < 0.01,
+        `At 250ms expected RMS ≈ 2.74, got ${result2[0]}`
+      );
+
+      // At 600ms: samples at 0, 100, 200, 250 all expired (>300ms old)
+      // RMS([10]) = 10
+      assert.ok(
+        Math.abs(result2[1] - 10.0) < 0.01,
+        `At 600ms expected RMS = 10, got ${result2[1]}`
+      );
+    }
+  );
+});
+
+test("Time-Based Mean Absolute Value", async (t) => {
+  await t.test("should expire samples based on age for MAV", async () => {
+    const pipeline = createDspPipeline();
+    // 1 second window
+    pipeline.MeanAbsoluteValue({ mode: "moving", windowDuration: 1000 });
+
+    // First 3 samples at 0, 100, 200ms - values -1, 2, -3
+    const chunk1 = new Float32Array([-1, 2, -3]);
+    const ts1 = new Float32Array([0, 100, 200]);
+    const result1 = await pipeline.process(chunk1, ts1, { channels: 1 });
+
+    // At 200ms: MAV([-1, 2, -3]) = (1 + 2 + 3) / 3 = 2
+    assert.ok(
+      Math.abs(result1[2] - 2.0) < 0.01,
+      `Expected MAV = 2.0, got ${result1[2]}`
+    );
+
+    // Sample at 2200ms - 2.2 seconds later (>1s window)
+    // Samples at 0, 100, 200ms should be EXPIRED
+    const chunk2 = new Float32Array([-5]);
+    const ts2 = new Float32Array([2200]);
+    const result2 = await pipeline.process(chunk2, ts2, { channels: 1 });
+
+    // At 2200ms: only sample at 2200ms remains, MAV([-5]) = 5
+    assert.ok(
+      Math.abs(result2[0] - 5.0) < 0.01,
+      `Expected MAV = 5.0, got ${result2[0]}`
+    );
+  });
+
+  await t.test("should work with irregular sampling for MAV", async () => {
+    const pipeline = createDspPipeline();
+    // 500ms window
+    pipeline.MeanAbsoluteValue({ mode: "moving", windowDuration: 500 });
+
+    const samples = new Float32Array([-2, 4, -6, 8]);
+    const timestamps = new Float32Array([
+      0, // Sample at 0ms
+      50, // Sample at 50ms
+      600, // Sample at 600ms (550ms gap!)
+      650, // Sample at 650ms
+    ]);
+
+    const result = await pipeline.process(samples, timestamps, { channels: 1 });
+
+    // At 650ms with 500ms window:
+    // - Sample at 0ms EXPIRED (650 - 0 = 650ms > 500ms)
+    // - Sample at 50ms EXPIRED (650 - 50 = 600ms > 500ms)
+    // - Sample at 600ms KEPT (650 - 600 = 50ms < 500ms)
+    // - Sample at 650ms KEPT (current)
+    // MAV([-6, 8]) = (6 + 8) / 2 = 7
+    assert.ok(
+      Math.abs(result[3] - 7.0) < 0.01,
+      `Expected MAV = 7.0, got ${result[3]}`
+    );
+  });
+
+  await t.test(
+    "should handle streaming with time-based windows for MAV",
+    async () => {
+      const pipeline = createDspPipeline();
+      // 300ms window
+      pipeline.MeanAbsoluteValue({ mode: "moving", windowDuration: 300 });
+
+      // First chunk: samples at 0, 100, 200ms
+      const chunk1 = new Float32Array([-1, -2, 3]);
+      const ts1 = new Float32Array([0, 100, 200]);
+      const result1 = await pipeline.process(chunk1, ts1, { channels: 1 });
+
+      // At 200ms: MAV([-1, -2, 3]) = (1 + 2 + 3) / 3 = 2
+      assert.ok(
+        Math.abs(result1[2] - 2.0) < 0.01,
+        "First chunk MAV should be 2.0"
+      );
+
+      // Second chunk: samples at 250, 600ms
+      const chunk2 = new Float32Array([-4, 10]);
+      const ts2 = new Float32Array([250, 600]);
+      const result2 = await pipeline.process(chunk2, ts2, { channels: 1 });
+
+      // At 250ms: all previous samples still valid (within 300ms)
+      // MAV([-1, -2, 3, -4]) = (1 + 2 + 3 + 4) / 4 = 2.5
+      assert.ok(
+        Math.abs(result2[0] - 2.5) < 0.01,
+        `At 250ms expected MAV = 2.5, got ${result2[0]}`
+      );
+
+      // At 600ms: samples at 0, 100, 200, 250 all expired (>300ms old)
+      // MAV([10]) = 10
+      assert.ok(
+        Math.abs(result2[1] - 10.0) < 0.01,
+        `At 600ms expected MAV = 10, got ${result2[1]}`
+      );
+    }
+  );
+});
+
+test("Backward Compatibility", async (t) => {
+  await t.test("RMS should work without timestamps", async () => {
+    const pipeline = createDspPipeline();
+    pipeline.Rms({ mode: "moving", windowSize: 3 });
+
+    const samples = new Float32Array([1, 2, 3, 4]);
+    const result = await pipeline.process(samples, { channels: 1 });
+
+    // Should use sample-count mode (last 3 samples)
+    // At sample 4: RMS([2, 3, 4]) = sqrt((4 + 9 + 16) / 3) = sqrt(29/3) ≈ 3.11
+    assert.ok(
+      Math.abs(result[3] - Math.sqrt(29 / 3)) < 0.01,
+      "RMS should work in sample-count mode"
+    );
+  });
+
+  await t.test("MAV should work without timestamps", async () => {
+    const pipeline = createDspPipeline();
+    pipeline.MeanAbsoluteValue({ mode: "moving", windowSize: 3 });
+
+    const samples = new Float32Array([-1, -2, 3, -4]);
+    const result = await pipeline.process(samples, { channels: 1 });
+
+    // Should use sample-count mode (last 3 samples)
+    // At sample 4: MAV([3, -4]) = (3 + 4) / 2 = 3.5
+    // Wait, with windowSize=3, at index 3 we have [2, 3, 4] in the window
+    // MAV([-2, 3, -4]) = (2 + 3 + 4) / 3 = 3
+    assert.ok(
+      Math.abs(result[3] - 3.0) < 0.01,
+      "MAV should work in sample-count mode"
+    );
+  });
+});