waveform-analysis 0.1.48 → 0.1.51

package/src/core/wasmSampling.test.ts

@@ -0,0 +1,205 @@
+/// <reference types="node" />
+
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+import { beforeAll, describe, expect, it } from 'vitest'
+
+import { sampleWaveformReference } from './samplingReference'
+import {
+  REFERENCE_AGGREGATE_VECTORS,
+  REFERENCE_SAMPLING_POINTS,
+  REFERENCE_SOURCE_INDEX_VECTORS,
+} from './samplingReferenceVectors'
+import {
+  calculateWasmRange,
+  createInitializedWasmSamplingBackend,
+  findWasmVisibleRange,
+  initializeWasmSampling,
+  sampleWaveformWasm,
+} from './wasmSampling'
+
+const x = Float64Array.from(REFERENCE_SAMPLING_POINTS, (point) => point.x)
+const y = Float64Array.from(REFERENCE_SAMPLING_POINTS, (point) => point.y)
+
+describe('sampleWaveformWasm', () => {
+  beforeAll(async () => {
+    await initializeWasmSampling(
+      await readFile(resolve(process.cwd(), 'wasm/pkg/waveform_sampling_wasm_bg.wasm')),
+    )
+  })
+
+  it('matches the shared source-index vectors and TypeScript reference', async () => {
+    for (const vector of REFERENCE_SOURCE_INDEX_VECTORS) {
+      const wasm = await sampleWaveformWasm({ x, y, ...vector })
+      const reference = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS,
+        strategy: vector.strategy,
+        targetPointCount: vector.targetPointCount,
+      })
+
+      expect(wasm.kind).toBe('source-indexes')
+      expect(reference.kind).toBe('source-indexes')
+      if (wasm.kind === 'source-indexes' && reference.kind === 'source-indexes') {
+        expect(Array.from(wasm.sourceIndexes)).toEqual(vector.expectedSourceIndexes)
+        expect(Array.from(wasm.sourceIndexes)).toEqual(Array.from(reference.sourceIndexes))
+      }
+    }
+  })
+
+  it('matches the shared aggregate vectors and TypeScript reference', async () => {
+    for (const vector of REFERENCE_AGGREGATE_VECTORS) {
+      const wasm = await sampleWaveformWasm({ x, y, ...vector })
+      const reference = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS,
+        strategy: vector.strategy,
+        targetPointCount: vector.targetPointCount,
+      })
+
+      expect(wasm.kind).toBe('aggregates')
+      expect(reference.kind).toBe('aggregates')
+      if (wasm.kind === 'aggregates' && reference.kind === 'aggregates') {
+        expect(Array.from(wasm.x)).toEqual(vector.expectedX)
+        expect(Array.from(wasm.y)).toEqual(vector.expectedY)
+        expect(Array.from(wasm.x)).toEqual(Array.from(reference.x))
+        expect(Array.from(wasm.y)).toEqual(Array.from(reference.y))
+      }
+    }
+  })
+
+  it('preserves reference filtering, stable sorting, and original source indexes', async () => {
+    const wasm = await sampleWaveformWasm({
+      x: Float64Array.from([2, Number.NaN, 1, 1, 3]),
+      y: Float64Array.from([20, 99, 10, 11, Number.POSITIVE_INFINITY]),
+      strategy: 'none',
+      targetPointCount: 1,
+    })
+
+    expect(wasm).toEqual({ kind: 'source-indexes', sourceIndexes: Uint32Array.from([2, 3, 0]) })
+  })
+
+  it('calculates full domains and normalized visible ranges', async () => {
+    const range = await calculateWasmRange(
+      Float64Array.from([2, Number.NaN, 1, 1, 3]),
+      Float64Array.from([20, 99, 10, 11, Number.POSITIVE_INFINITY]),
+    )
+    const visible = await findWasmVisibleRange(
+      Float64Array.from([2, Number.NaN, 1, 1, 3]),
+      Float64Array.from([20, 99, 10, 11, Number.POSITIVE_INFINITY]),
+      [1, 1],
+    )
+
+    expect(range).toEqual({ x: [1, 2], y: [10, 20] })
+    expect(visible).toEqual([0, 2])
+    await expect(calculateWasmRange(Float64Array.of(0), new Float64Array())).rejects.toThrow(
+      'x and y must have the same length',
+    )
+  })
+
+  it('matches the reference across strategy and target boundary cases', async () => {
+    const points = [
+      { x: 3, y: 3 },
+      { x: 1, y: -2 },
+      { x: 1, y: 4 },
+      { x: Number.NaN, y: 6 },
+      { x: 2, y: -1 },
+      { x: 4, y: Number.POSITIVE_INFINITY },
+      { x: 5, y: 0 },
+    ]
+    const caseX = Float64Array.from(points, (point) => point.x)
+    const caseY = Float64Array.from(points, (point) => point.y)
+    const strategies = ['none', 'peak', 'lttb', 'average', 'min', 'max', 'minmax', 'sum'] as const
+    const targets = [0, 1, 2, 3, 6, 20, Number.POSITIVE_INFINITY]
+
+    for (const strategy of strategies) {
+      for (const targetPointCount of targets) {
+        const wasm = await sampleWaveformWasm({
+          x: caseX,
+          y: caseY,
+          strategy,
+          targetPointCount,
+        })
+        const reference = sampleWaveformReference({ points, strategy, targetPointCount })
+
+        expect(wasm.kind).toBe(reference.kind)
+        if (wasm.kind === 'source-indexes' && reference.kind === 'source-indexes') {
+          expect(Array.from(wasm.sourceIndexes)).toEqual(Array.from(reference.sourceIndexes))
+        }
+        if (wasm.kind === 'aggregates' && reference.kind === 'aggregates') {
+          expect(Array.from(wasm.x)).toEqual(Array.from(reference.x))
+          expect(Array.from(wasm.y)).toEqual(Array.from(reference.y))
+        }
+      }
+    }
+  })
+
+  it('rejects coordinate arrays with unequal lengths', async () => {
+    await expect(
+      sampleWaveformWasm({
+        x: Float64Array.of(0),
+        y: new Float64Array(),
+        strategy: 'none',
+        targetPointCount: 1,
+      }),
+    ).rejects.toThrow('x and y must have the same length')
+  })
+
+  it('keeps a bounded dataset index in WASM for unaligned viewport queries and releases it', () => {
+    const backend = createInitializedWasmSamplingBackend()
+    const handle = backend.registerDataset(x, y, 1024 * 1024)
+    const visible = REFERENCE_SAMPLING_POINTS.slice(2, 9)
+
+    for (const strategy of ['peak', 'min', 'max', 'minmax'] as const) {
+      const actual = backend.sampleDataset(handle, 2, 9, strategy, 6)
+      const expected = sampleWaveformReference({
+        points: visible,
+        strategy,
+        targetPointCount: 6,
+      })
+      expect(actual.kind).toBe('source-indexes')
+      expect(expected.kind).toBe('source-indexes')
+      if (actual.kind === 'source-indexes' && expected.kind === 'source-indexes') {
+        expect(Array.from(actual.sourceIndexes)).toEqual(
+          Array.from(expected.sourceIndexes, (index) => index + 2),
+        )
+      }
+    }
+
+    const aggregates = backend.sampleDataset(handle, 2, 9, 'average', 4)
+    const expectedAggregates = sampleWaveformReference({
+      points: visible,
+      strategy: 'average',
+      targetPointCount: 4,
+    })
+    expect(aggregates.kind).toBe('aggregates')
+    expect(expectedAggregates.kind).toBe('aggregates')
+    if (aggregates.kind === 'aggregates' && expectedAggregates.kind === 'aggregates') {
+      aggregates.x.forEach((value, index) =>
+        expect(value).toBeCloseTo(expectedAggregates.x[index]!, 12),
+      )
+      aggregates.y.forEach((value, index) =>
+        expect(value).toBeCloseTo(expectedAggregates.y[index]!, 12),
+      )
+    }
+    expect(backend.datasetIndexBytes(handle)).toBeGreaterThan(0)
+    backend.disposeDataset(handle)
+    expect(backend.datasetIndexBytes(handle)).toBe(0)
+  })
+
+  it('registers evenly sampled values without an explicit X column', () => {
+    const backend = createInitializedWasmSamplingBackend()
+    const handle = backend.registerSamples(
+      new Float64Array([1, 9, 2]),
+      new Uint32Array([0, 2, 3]),
+      10,
+      2,
+      1024 * 1024,
+    )
+
+    expect(backend.sampleDataset(handle, 0, 3, 'max', 3)).toMatchObject({
+      kind: 'source-indexes',
+      sourceIndexes: Uint32Array.from([0, 1, 2]),
+    })
+    backend.disposeDataset(handle)
+  })
+})

package/src/core/wasmSampling.ts

@@ -0,0 +1,230 @@
+import initWasm, {
+  calculate_range,
+  dataset_index_bytes,
+  dispose_all_datasets,
+  dispose_dataset,
+  find_visible_range,
+  register_dataset,
+  register_sample_dataset,
+  sample_aggregates,
+  sample_dataset_aggregates,
+  sample_dataset_indexes,
+  sample_indexes,
+} from '../../wasm/pkg/waveform_sampling_wasm'
+import type { InitInput } from '../../wasm/pkg/waveform_sampling_wasm'
+
+import type { ReferenceSamplingStrategy } from './samplingReference'
+import type { WorkerSamplingBackend, WorkerSamplingOutput } from './workerSampling/protocol'
+
+export type WasmSamplingStrategy = ReferenceSamplingStrategy
+
+export interface WasmSamplingRequest {
+  x: Float64Array
+  y: Float64Array
+  strategy: WasmSamplingStrategy
+  targetPointCount: number
+}
+
+export interface WasmSourceIndexSamplingResult {
+  kind: 'source-indexes'
+  sourceIndexes: Uint32Array
+}
+
+export interface WasmAggregateSamplingResult {
+  kind: 'aggregates'
+  x: Float64Array
+  y: Float64Array
+}
+
+export type WasmSamplingResult = WasmSourceIndexSamplingResult | WasmAggregateSamplingResult
+
+export interface WasmDatasetSamplingBackend extends WorkerSamplingBackend {
+  registerDataset(x: Float64Array, y: Float64Array, indexMaxBytes?: number): number
+  registerSamples(
+    y: Float64Array,
+    sourceIndexes: Uint32Array | undefined,
+    startTime: number,
+    sampleRate: number,
+    indexMaxBytes?: number,
+  ): number
+  disposeDataset(handle: number): void
+  disposeAllDatasets(): void
+  datasetIndexBytes(handle: number): number
+  sampleDataset(
+    handle: number,
+    start: number,
+    end: number,
+    strategy: WasmSamplingStrategy,
+    targetPointCount: number,
+  ): WorkerSamplingOutput
+}
+
+export interface WasmRangeMetrics {
+  x: [number, number]
+  y: [number, number]
+}
+
+const strategyCodes: Record<WasmSamplingStrategy, number> = {
+  none: 0,
+  peak: 1,
+  lttb: 2,
+  average: 3,
+  min: 4,
+  max: 5,
+  minmax: 6,
+  sum: 7,
+}
+
+let initialization: Promise<void> | undefined
+
+function targetPointCountForWasm(value: number, pointCount: number) {
+  if (pointCount === 0) return 0
+  if (!Number.isFinite(value)) return pointCount
+  return Math.min(pointCount, Math.max(1, Math.floor(value)))
+}
+
+function validateRequest(request: WasmSamplingRequest) {
+  if (request.x.length !== request.y.length) {
+    throw new Error('x and y must have the same length')
+  }
+}
+
+/** Initializes the bundled WebAssembly module once for the current JavaScript realm. */
+export function initializeWasmSampling(input?: InitInput | Promise<InitInput>): Promise<void> {
+  initialization ??= Promise.resolve(initWasm(input)).then(() => undefined)
+  return initialization
+}
+
+/**
+ * Runs the pure numeric sampler on flat Float64Array coordinates. The caller owns source-data
+ * normalization and receives either original input indexes or newly allocated aggregate arrays.
+ */
+export async function sampleWaveformWasm(
+  request: WasmSamplingRequest,
+): Promise<WasmSamplingResult> {
+  validateRequest(request)
+  await initializeWasmSampling()
+  const target = targetPointCountForWasm(request.targetPointCount, request.x.length)
+  const strategy = strategyCodes[request.strategy]
+  if (request.strategy !== 'average' && request.strategy !== 'sum') {
+    return {
+      kind: 'source-indexes',
+      sourceIndexes: sample_indexes(request.x, request.y, strategy, target),
+    }
+  }
+
+  const values = sample_aggregates(request.x, request.y, strategy, target)
+  const x = new Float64Array(values.length / 2)
+  const y = new Float64Array(values.length / 2)
+  for (let index = 0; index < x.length; index += 1) {
+    x[index] = values[index * 2]!
+    y[index] = values[index * 2 + 1]!
+  }
+  return { kind: 'aggregates', x, y }
+}
+
+/**
+ * Creates the synchronous backend used only after this realm has finished WASM initialization.
+ * Worker code calls `initializeWasmSampling` before exposing this backend to its repository.
+ */
+export function createInitializedWasmSamplingBackend(): WasmDatasetSamplingBackend {
+  const aggregateOutput = (values: Float64Array): WasmAggregateSamplingResult => {
+    const x = new Float64Array(values.length / 2)
+    const y = new Float64Array(values.length / 2)
+    for (let index = 0; index < x.length; index += 1) {
+      x[index] = values[index * 2]!
+      y[index] = values[index * 2 + 1]!
+    }
+    return { kind: 'aggregates', x, y }
+  }
+  const backend: WasmDatasetSamplingBackend = {
+    kind: 'wasm',
+    sample({ x, y, strategy, targetPointCount }) {
+      const request = { x, y, strategy, targetPointCount }
+      validateRequest(request)
+      const target = targetPointCountForWasm(request.targetPointCount, request.x.length)
+      if (request.strategy !== 'average' && request.strategy !== 'sum') {
+        return {
+          kind: 'source-indexes' as const,
+          sourceIndexes: sample_indexes(
+            request.x,
+            request.y,
+            strategyCodes[request.strategy],
+            target,
+          ),
+        }
+      }
+      const values = sample_aggregates(
+        request.x,
+        request.y,
+        strategyCodes[request.strategy],
+        target,
+      )
+      return aggregateOutput(values)
+    },
+    registerDataset(x, y, indexMaxBytes) {
+      validateRequest({ x, y, strategy: 'peak', targetPointCount: x.length })
+      return register_dataset(
+        x,
+        y,
+        Math.max(0, Math.min(0xffffffff, Math.floor(indexMaxBytes ?? 8 * 1024 * 1024))),
+      )
+    },
+    registerSamples(y, sourceIndexes, startTime, sampleRate, indexMaxBytes) {
+      return register_sample_dataset(
+        y,
+        sourceIndexes ?? new Uint32Array(),
+        startTime,
+        sampleRate,
+        Math.max(0, Math.min(0xffffffff, Math.floor(indexMaxBytes ?? 8 * 1024 * 1024))),
+      )
+    },
+    disposeDataset(handle) {
+      dispose_dataset(handle)
+    },
+    disposeAllDatasets() {
+      dispose_all_datasets()
+    },
+    datasetIndexBytes(handle) {
+      return dataset_index_bytes(handle)
+    },
+    sampleDataset(handle, start, end, strategy, targetPointCount) {
+      const target = Math.max(0, Math.floor(targetPointCount))
+      if (strategy === 'average' || strategy === 'sum') {
+        return aggregateOutput(
+          sample_dataset_aggregates(handle, start, end, strategyCodes[strategy], target),
+        )
+      }
+      return {
+        kind: 'source-indexes',
+        sourceIndexes: sample_dataset_indexes(handle, start, end, strategyCodes[strategy], target),
+      }
+    },
+  }
+  return backend
+}
+
+/** Calculates domains from valid points without changing the input arrays. */
+export async function calculateWasmRange(
+  x: Float64Array,
+  y: Float64Array,
+): Promise<WasmRangeMetrics | undefined> {
+  if (x.length !== y.length) throw new Error('x and y must have the same length')
+  await initializeWasmSampling()
+  const result = calculate_range(x, y)
+  return result.length === 4
+    ? { x: [result[0]!, result[1]!], y: [result[2]!, result[3]!] }
+    : undefined
+}
+
+/** Locates a half-open visible range in the filtered, stable ascending-X point sequence. */
+export async function findWasmVisibleRange(
+  x: Float64Array,
+  y: Float64Array,
+  domain: [number, number],
+): Promise<[number, number]> {
+  if (x.length !== y.length) throw new Error('x and y must have the same length')
+  await initializeWasmSampling()
+  const result = find_visible_range(x, y, domain[0], domain[1])
+  return [result[0]!, result[1]!]
+}