dspx 0.1.1-alpha.0

package/src/native/utils/TimeSeriesBuffer.h

@@ -0,0 +1,140 @@
+#pragma once
+#include <deque>
+#include <utility>
+#include <vector>
+#include <cstdint>
+#include <stdexcept>
+
+namespace dsp::utils
+{
+    /**
+     * @brief A time-series buffer that stores timestamped samples.
+     *
+     * This buffer replaces CircularBuffer for time-aware processing.
+     * It stores pairs of (timestamp, value) and supports both:
+     * - Sample-based windows (fixed number of samples)
+     * - Time-based windows (fixed duration in milliseconds)
+     *
+     * Uses std::deque for efficient front/back operations.
+     *
+     * @tparam T The numeric type (e.g., float, double).
+     */
+    template <typename T>
+    class TimeSeriesBuffer
+    {
+    public:
+        using TimestampType = uint64_t;
+        using Sample = std::pair<TimestampType, T>;
+
+        /**
+         * @brief Constructs a time-series buffer.
+         * @param max_samples Maximum number of samples (for sample-based mode, 0 = unlimited)
+         * @param window_duration_ms Maximum time window in milliseconds (for time-based mode, 0 = disabled)
+         */
+        explicit TimeSeriesBuffer(size_t max_samples = 0, uint64_t window_duration_ms = 0);
+
+        /**
+         * @brief Adds a new timestamped sample.
+         *
+         * Automatically removes old samples based on window constraints:
+         * - If max_samples > 0: removes oldest samples beyond the limit
+         * - If window_duration_ms > 0: removes samples older than (newest_timestamp - window_duration_ms)
+         *
+         * @param timestamp The timestamp in milliseconds (or sample index)
+         * @param value The sample value
+         */
+        void push(TimestampType timestamp, T value);
+
+        /**
+         * @brief Removes samples older than the specified timestamp.
+         * @param cutoff_timestamp Samples with timestamp < cutoff_timestamp will be removed
+         * @return size_t Number of samples removed
+         */
+        size_t removeOlderThan(TimestampType cutoff_timestamp);
+
+        /**
+         * @brief Gets the oldest sample without removing it.
+         * @return const Sample& Reference to the oldest (front) sample
+         * @throws std::out_of_range if buffer is empty
+         */
+        const Sample &front() const;
+
+        /**
+         * @brief Gets the newest sample without removing it.
+         * @return const Sample& Reference to the newest (back) sample
+         * @throws std::out_of_range if buffer is empty
+         */
+        const Sample &back() const;
+
+        /**
+         * @brief Removes the oldest sample.
+         * @throws std::out_of_range if buffer is empty
+         */
+        void popFront();
+
+        /**
+         * @brief Gets the current number of samples in the buffer.
+         * @return size_t The number of samples
+         */
+        size_t size() const noexcept;
+
+        /**
+         * @brief Checks if the buffer is empty.
+         * @return bool True if empty
+         */
+        bool empty() const noexcept;
+
+        /**
+         * @brief Clears all samples from the buffer.
+         */
+        void clear() noexcept;
+
+        /**
+         * @brief Exports all samples as a vector.
+         * @return std::vector<Sample> All timestamp-value pairs
+         */
+        std::vector<Sample> toVector() const;
+
+        /**
+         * @brief Restores buffer from a vector of samples.
+         * @param samples Vector of timestamp-value pairs to restore
+         */
+        void fromVector(const std::vector<Sample> &samples);
+
+        /**
+         * @brief Gets the time span of the buffer (newest - oldest timestamp).
+         * @return uint64_t Time span in milliseconds (0 if empty or single sample)
+         */
+        uint64_t getTimeSpan() const noexcept;
+
+        /**
+         * @brief Provides iterator access to samples (const).
+         */
+        typename std::deque<Sample>::const_iterator begin() const noexcept;
+        typename std::deque<Sample>::const_iterator end() const noexcept;
+
+        /**
+         * @brief Gets the maximum sample count constraint.
+         * @return size_t Maximum samples (0 = unlimited)
+         */
+        size_t getMaxSamples() const noexcept;
+
+        /**
+         * @brief Gets the time window duration constraint.
+         * @return uint64_t Window duration in milliseconds (0 = disabled)
+         */
+        uint64_t getWindowDuration() const noexcept;
+
+    private:
+        std::deque<Sample> m_samples;
+        size_t m_max_samples;
+        uint64_t m_window_duration_ms;
+
+        /**
+         * @brief Enforces window constraints by removing old samples.
+         * Called automatically after push().
+         */
+        void enforceWindowConstraints();
+    };
+
+} // namespace dsp::utils

package/src/ts/CircularLogBuffer.ts

@@ -0,0 +1,87 @@
+/**
+ * Circular buffer for efficient log pooling
+ * Avoids array reallocations and maintains fixed memory footprint
+ */
+
+import type { LogEntry } from "./types.js";
+
+export class CircularLogBuffer {
+  private buffer: LogEntry[];
+  private writeIndex = 0;
+  private count = 0;
+  private readonly capacity: number;
+
+  /**
+   * Create a circular log buffer
+   * @param capacity - Maximum number of log entries to store (default: 32)
+   */
+  constructor(capacity: number = 32) {
+    this.capacity = capacity;
+    this.buffer = new Array(capacity);
+  }
+
+  /**
+   * Add a log entry to the buffer
+   * If buffer is full, oldest entry is overwritten
+   */
+  push(entry: LogEntry): void {
+    this.buffer[this.writeIndex] = entry;
+    this.writeIndex = (this.writeIndex + 1) % this.capacity;
+    if (this.count < this.capacity) {
+      this.count++;
+    }
+  }
+
+  /**
+   * Get all log entries in chronological order and clear the buffer
+   * @returns Array of log entries (oldest to newest)
+   */
+  flush(): LogEntry[] {
+    if (this.count === 0) {
+      return [];
+    }
+
+    const result: LogEntry[] = new Array(this.count);
+
+    if (this.count < this.capacity) {
+      // Buffer not full - entries are at start
+      for (let i = 0; i < this.count; i++) {
+        result[i] = this.buffer[i];
+      }
+    } else {
+      // Buffer full - need to unwrap circular order
+      const oldestIndex = this.writeIndex; // Points to oldest (next to be overwritten)
+      for (let i = 0; i < this.capacity; i++) {
+        result[i] = this.buffer[(oldestIndex + i) % this.capacity];
+      }
+    }
+
+    // Reset buffer state (reuse memory)
+    this.count = 0;
+    this.writeIndex = 0;
+
+    return result;
+  }
+
+  /**
+   * Check if buffer has any entries
+   */
+  hasEntries(): boolean {
+    return this.count > 0;
+  }
+
+  /**
+   * Get current number of entries in buffer
+   */
+  size(): number {
+    return this.count;
+  }
+
+  /**
+   * Clear all entries without allocating new memory
+   */
+  clear(): void {
+    this.count = 0;
+    this.writeIndex = 0;
+  }
+}

package/src/ts/DriftDetector.ts

@@ -0,0 +1,331 @@
+/**
+ * Drift Detection for Time-Series Processing
+ *
+ * Monitors sample timing and detects drift/irregularities in real-time data streams.
+ * Useful for debugging hardware issues, network problems, and ensuring data quality.
+ */
+
+export interface DriftStatistics {
+  /** Current time delta between samples (ms) */
+  deltaMs: number;
+  /** Expected time delta based on sample rate (ms) */
+  expectedMs: number;
+  /** Absolute drift from expected (ms) */
+  absoluteDrift: number;
+  /** Relative drift as percentage (%) */
+  relativeDrift: number;
+  /** Sample index where drift was detected */
+  sampleIndex: number;
+  /** Timestamp of current sample */
+  currentTimestamp: number;
+  /** Timestamp of previous sample */
+  previousTimestamp: number;
+}
+
+export interface DriftDetectorOptions {
+  /** Expected sample rate in Hz (e.g., 1000 for 1kHz) */
+  expectedSampleRate?: number;
+  /** Drift threshold percentage (0-100, default: 10%) */
+  driftThreshold?: number;
+  /** Callback when drift is detected */
+  onDriftDetected?: (stats: DriftStatistics) => void;
+  /** Callback for all timing measurements (high volume!) */
+  onTimingMeasured?: (stats: DriftStatistics) => void;
+}
+
+export interface TimingMetrics {
+  /** Total samples processed */
+  samplesProcessed: number;
+  /** Number of drift events detected */
+  driftEventsCount: number;
+  /** Minimum delta observed (ms) */
+  minDelta: number;
+  /** Maximum delta observed (ms) */
+  maxDelta: number;
+  /** Average delta (ms) */
+  averageDelta: number;
+  /** Standard deviation of deltas (ms) */
+  stdDevDelta: number;
+  /** Largest drift detected (ms) */
+  maxDriftObserved: number;
+}
+
+/**
+ * DriftDetector monitors timing between samples and detects anomalies
+ */
+export class DriftDetector {
+  private options: Required<DriftDetectorOptions>;
+  private previousTimestamp: number | null = null;
+  private sampleIndex: number = 0;
+
+  // Metrics tracking
+  private samplesProcessed: number = 0;
+  private driftEventsCount: number = 0;
+  private minDelta: number = Infinity;
+  private maxDelta: number = -Infinity;
+  private deltasSum: number = 0;
+  private deltasSumSquared: number = 0;
+  private maxDriftObserved: number = 0;
+
+  constructor(options: DriftDetectorOptions = {}) {
+    this.options = {
+      expectedSampleRate: options.expectedSampleRate ?? 1000,
+      driftThreshold: options.driftThreshold ?? 10,
+      onDriftDetected: options.onDriftDetected ?? (() => {}),
+      onTimingMeasured: options.onTimingMeasured ?? (() => {}),
+    };
+  }
+
+  /**
+   * Process a single timestamp and detect drift
+   */
+  processSample(timestamp: number): void {
+    if (this.previousTimestamp !== null) {
+      const deltaMs = timestamp - this.previousTimestamp;
+      const expectedMs = 1000 / this.options.expectedSampleRate;
+      const absoluteDrift = Math.abs(deltaMs - expectedMs);
+      const relativeDrift = (absoluteDrift / expectedMs) * 100;
+
+      const stats: DriftStatistics = {
+        deltaMs,
+        expectedMs,
+        absoluteDrift,
+        relativeDrift,
+        sampleIndex: this.sampleIndex,
+        currentTimestamp: timestamp,
+        previousTimestamp: this.previousTimestamp,
+      };
+
+      // Update metrics
+      this.updateMetrics(deltaMs, absoluteDrift);
+
+      // Call timing callback (every sample)
+      this.options.onTimingMeasured(stats);
+
+      // Detect drift
+      if (relativeDrift > this.options.driftThreshold) {
+        this.driftEventsCount++;
+        this.options.onDriftDetected(stats);
+      }
+    }
+
+    this.previousTimestamp = timestamp;
+    this.sampleIndex++;
+    this.samplesProcessed++;
+  }
+
+  /**
+   * Process a batch of timestamps
+   */
+  processBatch(timestamps: Float32Array): void {
+    for (let i = 0; i < timestamps.length; i++) {
+      this.processSample(timestamps[i]);
+    }
+  }
+
+  /**
+   * Get current timing metrics
+   */
+  getMetrics(): TimingMetrics {
+    const avgDelta =
+      this.samplesProcessed > 1
+        ? this.deltasSum / (this.samplesProcessed - 1)
+        : 0;
+
+    const variance =
+      this.samplesProcessed > 1
+        ? this.deltasSumSquared / (this.samplesProcessed - 1) -
+          avgDelta * avgDelta
+        : 0;
+
+    const stdDev = Math.sqrt(Math.max(0, variance));
+
+    return {
+      samplesProcessed: this.samplesProcessed,
+      driftEventsCount: this.driftEventsCount,
+      minDelta: this.minDelta === Infinity ? 0 : this.minDelta,
+      maxDelta: this.maxDelta === -Infinity ? 0 : this.maxDelta,
+      averageDelta: avgDelta,
+      stdDevDelta: stdDev,
+      maxDriftObserved: this.maxDriftObserved,
+    };
+  }
+
+  /**
+   * Reset all metrics and state
+   */
+  reset(): void {
+    this.previousTimestamp = null;
+    this.sampleIndex = 0;
+    this.samplesProcessed = 0;
+    this.driftEventsCount = 0;
+    this.minDelta = Infinity;
+    this.maxDelta = -Infinity;
+    this.deltasSum = 0;
+    this.deltasSumSquared = 0;
+    this.maxDriftObserved = 0;
+  }
+
+  /**
+   * Get the expected sample rate configured for this detector
+   */
+  getExpectedSampleRate(): number {
+    return this.options.expectedSampleRate;
+  }
+
+  /**
+   * Update internal metrics
+   */
+  private updateMetrics(deltaMs: number, absoluteDrift: number): void {
+    this.minDelta = Math.min(this.minDelta, deltaMs);
+    this.maxDelta = Math.max(this.maxDelta, deltaMs);
+    this.deltasSum += deltaMs;
+    this.deltasSumSquared += deltaMs * deltaMs;
+    this.maxDriftObserved = Math.max(this.maxDriftObserved, absoluteDrift);
+  }
+}
+
+/**
+ * Utility: Detect gaps in timestamps (missing samples)
+ */
+export interface GapDetection {
+  /** Index where gap starts */
+  startIndex: number;
+  /** Index where gap ends */
+  endIndex: number;
+  /** Gap duration in ms */
+  durationMs: number;
+  /** Expected number of samples in gap */
+  expectedSamples: number;
+  /** Timestamp before gap */
+  timestampBefore: number;
+  /** Timestamp after gap */
+  timestampAfter: number;
+}
+
+export function detectGaps(
+  timestamps: Float32Array,
+  expectedSampleRate: number,
+  gapThreshold: number = 2.0 // Multiplier of expected interval
+): GapDetection[] {
+  const gaps: GapDetection[] = [];
+  const expectedInterval = 1000 / expectedSampleRate;
+  const gapMinDuration = expectedInterval * gapThreshold;
+
+  for (let i = 1; i < timestamps.length; i++) {
+    const delta = timestamps[i] - timestamps[i - 1];
+    if (delta > gapMinDuration) {
+      const expectedSamples = Math.floor(delta / expectedInterval) - 1;
+      gaps.push({
+        startIndex: i - 1,
+        endIndex: i,
+        durationMs: delta,
+        expectedSamples,
+        timestampBefore: timestamps[i - 1],
+        timestampAfter: timestamps[i],
+      });
+    }
+  }
+
+  return gaps;
+}
+
+/**
+ * Utility: Validate timestamp monotonicity
+ */
+export interface MonotonicityViolation {
+  index: number;
+  currentTimestamp: number;
+  previousTimestamp: number;
+  violation: "backwards" | "duplicate";
+}
+
+export function validateMonotonicity(
+  timestamps: Float32Array
+): MonotonicityViolation[] {
+  const violations: MonotonicityViolation[] = [];
+
+  for (let i = 1; i < timestamps.length; i++) {
+    const current = timestamps[i];
+    const previous = timestamps[i - 1];
+
+    if (current < previous) {
+      violations.push({
+        index: i,
+        currentTimestamp: current,
+        previousTimestamp: previous,
+        violation: "backwards",
+      });
+    } else if (current === previous) {
+      violations.push({
+        index: i,
+        currentTimestamp: current,
+        previousTimestamp: previous,
+        violation: "duplicate",
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Utility: Calculate sample rate from timestamps
+ */
+export interface SampleRateEstimate {
+  /** Estimated sample rate in Hz */
+  estimatedRate: number;
+  /** Average interval in ms */
+  averageInterval: number;
+  /** Standard deviation of intervals */
+  stdDevInterval: number;
+  /** Coefficient of variation (stdDev / mean) */
+  coefficientOfVariation: number;
+  /** Regularity assessment */
+  regularity: "excellent" | "good" | "fair" | "poor" | "irregular";
+}
+
+export function estimateSampleRate(
+  timestamps: Float32Array
+): SampleRateEstimate {
+  if (timestamps.length < 2) {
+    return {
+      estimatedRate: 0,
+      averageInterval: 0,
+      stdDevInterval: 0,
+      coefficientOfVariation: 0,
+      regularity: "irregular",
+    };
+  }
+
+  // Calculate intervals
+  let sumIntervals = 0;
+  let sumSquaredIntervals = 0;
+  for (let i = 1; i < timestamps.length; i++) {
+    const interval = timestamps[i] - timestamps[i - 1];
+    sumIntervals += interval;
+    sumSquaredIntervals += interval * interval;
+  }
+
+  const n = timestamps.length - 1;
+  const avgInterval = sumIntervals / n;
+  const variance = sumSquaredIntervals / n - avgInterval * avgInterval;
+  const stdDev = Math.sqrt(Math.max(0, variance));
+  const cv = avgInterval > 0 ? stdDev / avgInterval : Infinity;
+
+  // Assess regularity
+  let regularity: "excellent" | "good" | "fair" | "poor" | "irregular";
+  if (cv < 0.01) regularity = "excellent"; // <1% variation
+  else if (cv < 0.05) regularity = "good"; // <5% variation
+  else if (cv < 0.15) regularity = "fair"; // <15% variation
+  else if (cv < 0.3) regularity = "poor"; // <30% variation
+  else regularity = "irregular"; // >30% variation
+
+  return {
+    estimatedRate: 1000 / avgInterval,
+    averageInterval: avgInterval,
+    stdDevInterval: stdDev,
+    coefficientOfVariation: cv,
+    regularity,
+  };
+}