waveform-analysis 0.1.48 → 0.1.51

package/src/core/samplingReference.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+
+import type { WaveformPoint } from '../types'
+import {
+  sampleWaveformReference,
+  type ReferenceSamplingStrategy,
+  type SourceIndexSamplingResult,
+} from './samplingReference'
+import {
+  REFERENCE_AGGREGATE_VECTORS,
+  REFERENCE_SAMPLING_POINTS,
+  REFERENCE_SOURCE_INDEX_VECTORS,
+} from './samplingReferenceVectors'
+
+function indexes(strategy: Exclude<ReferenceSamplingStrategy, 'average' | 'sum'>, target: number) {
+  const result = sampleWaveformReference({
+    points: REFERENCE_SAMPLING_POINTS,
+    strategy,
+    targetPointCount: target,
+  })
+  expect(result.kind).toBe('source-indexes')
+  return Array.from((result as SourceIndexSamplingResult).sourceIndexes)
+}
+
+describe('sampleWaveformReference', () => {
+  it('locks the source-index strategy vectors', () => {
+    for (const vector of REFERENCE_SOURCE_INDEX_VECTORS) {
+      expect(indexes(vector.strategy, vector.targetPointCount)).toEqual(
+        vector.expectedSourceIndexes,
+      )
+    }
+  })
+
+  it('locks the aggregate bucket and synthesized-X semantics', () => {
+    for (const vector of REFERENCE_AGGREGATE_VECTORS) {
+      const result = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS,
+        strategy: vector.strategy,
+        targetPointCount: vector.targetPointCount,
+      })
+
+      expect(result).toMatchObject({ kind: 'aggregates', validPointCount: 8 })
+      expect(Array.from(result.kind === 'aggregates' ? result.x : [])).toEqual(vector.expectedX)
+      expect(Array.from(result.kind === 'aggregates' ? result.y : [])).toEqual(vector.expectedY)
+    }
+  })
+
+  it('uses the earliest point for equal extrema and removes duplicate peak entries', () => {
+    const tied = [
+      { x: 0, y: 0 },
+      { x: 1, y: -5 },
+      { x: 2, y: -5 },
+      { x: 3, y: 5 },
+      { x: 4, y: 5 },
+      { x: 5, y: 0 },
+      { x: 6, y: 0 },
+    ]
+
+    const minmax = sampleWaveformReference({
+      points: tied,
+      strategy: 'minmax',
+      targetPointCount: 4,
+    })
+    const peak = sampleWaveformReference({ points: tied, strategy: 'peak', targetPointCount: 6 })
+
+    expect(Array.from(minmax.kind === 'source-indexes' ? minmax.sourceIndexes : [])).toEqual([
+      0, 1, 3, 6,
+    ])
+    expect(Array.from(peak.kind === 'source-indexes' ? peak.sourceIndexes : [])).toEqual([
+      0, 1, 3, 5, 6,
+    ])
+  })
+
+  it('filters invalid points, stably orders X, and returns indexes into the original input', () => {
+    const input: WaveformPoint[] = [
+      { x: 2, y: 20 },
+      { x: Number.NaN, y: 99 },
+      { x: 1, y: 10 },
+      { x: 1, y: 11 },
+      { x: 3, y: Number.POSITIVE_INFINITY },
+    ]
+    const result = sampleWaveformReference({ points: input, strategy: 'none', targetPointCount: 1 })
+
+    expect(result).toMatchObject({ inputPointCount: 5, validPointCount: 3, kind: 'source-indexes' })
+    expect(Array.from(result.kind === 'source-indexes' ? result.sourceIndexes : [])).toEqual([
+      2, 3, 0,
+    ])
+    expect(input).toEqual([
+      { x: 2, y: 20 },
+      { x: Number.NaN, y: 99 },
+      { x: 1, y: 10 },
+      { x: 1, y: 11 },
+      { x: 3, y: Number.POSITIVE_INFINITY },
+    ])
+  })
+
+  it('defines empty, short, and low-target behavior without exceeding the target', () => {
+    const strategies: ReferenceSamplingStrategy[] = [
+      'none',
+      'peak',
+      'lttb',
+      'average',
+      'min',
+      'max',
+      'minmax',
+      'sum',
+    ]
+    for (const strategy of strategies) {
+      const empty = sampleWaveformReference({ points: [], strategy, targetPointCount: 3 })
+      expect(empty.kind === 'aggregates' ? empty.x : empty.sourceIndexes).toHaveLength(0)
+
+      const short = sampleWaveformReference({
+        points: REFERENCE_SAMPLING_POINTS.slice(0, 2),
+        strategy,
+        targetPointCount: 10,
+      })
+      expect(short.kind === 'aggregates' ? short.x : short.sourceIndexes).toHaveLength(2)
+    }
+
+    expect(indexes('lttb', 2)).toEqual([0, 7])
+    expect(indexes('minmax', 3)).toEqual([0, 7])
+    expect(indexes('peak', 6)).toHaveLength(5)
+  })
+})

package/src/core/samplingReference.ts

@@ -0,0 +1,243 @@
+import type { WaveformPoint } from '../types'
+
+/** Sampling algorithms that can be implemented equivalently by the future WASM core. */
+export type ReferenceSamplingStrategy =
+  'none' | 'peak' | 'lttb' | 'average' | 'min' | 'max' | 'minmax' | 'sum'
+
+/**
+ * A pure TypeScript reference request. Source indexes in the result address the original
+ * `points` array, after filtering non-finite points and applying a stable ascending-X order.
+ */
+export interface ReferenceSamplingRequest {
+  points: readonly WaveformPoint[]
+  strategy: ReferenceSamplingStrategy
+  targetPointCount: number
+}
+
+interface ReferenceSamplingResultBase {
+  strategy: ReferenceSamplingStrategy
+  inputPointCount: number
+  validPointCount: number
+}
+
+/** A result made of real points from the input sequence. */
+export interface SourceIndexSamplingResult extends ReferenceSamplingResultBase {
+  kind: 'source-indexes'
+  sourceIndexes: Uint32Array
+}
+
+/** A result whose points are synthesized from a contiguous source bucket. */
+export interface AggregateSamplingResult extends ReferenceSamplingResultBase {
+  kind: 'aggregates'
+  x: Float64Array
+  y: Float64Array
+}
+
+export type ReferenceSamplingResult = SourceIndexSamplingResult | AggregateSamplingResult
+
+interface IndexedPoint {
+  sourceIndex: number
+  x: number
+  y: number
+}
+
+function normalizedPoints(points: readonly WaveformPoint[]): IndexedPoint[] {
+  const result: IndexedPoint[] = []
+  let ordered = true
+  let previousX = Number.NEGATIVE_INFINITY
+
+  for (let sourceIndex = 0; sourceIndex < points.length; sourceIndex += 1) {
+    const point = points[sourceIndex]
+    if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) continue
+    if (point.x < previousX) ordered = false
+    previousX = point.x
+    result.push({ sourceIndex, x: point.x, y: point.y })
+  }
+
+  // ES2019 guarantees stable Array#sort, preserving duplicate-X source order.
+  if (!ordered) result.sort((left, right) => left.x - right.x)
+  return result
+}
+
+function targetCount(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 bucketBounds(bucket: number, bucketCount: number, start: number, end: number) {
+  const span = end - start
+  return {
+    start: start + Math.floor((bucket * span) / bucketCount),
+    end: start + Math.floor(((bucket + 1) * span) / bucketCount),
+  }
+}
+
+function addUniqueIndex(indexes: number[], index: number) {
+  if (indexes[indexes.length - 1] !== index) indexes.push(index)
+}
+
+function withEndpoints(points: IndexedPoint[], target: number, selectInterior: () => number[]) {
+  if (points.length <= target) return points.map((_, index) => index)
+  if (target === 1) return [0]
+  if (target === 2) return [0, points.length - 1]
+
+  const indexes = [0]
+  for (const index of selectInterior()) addUniqueIndex(indexes, index)
+  addUniqueIndex(indexes, points.length - 1)
+  return indexes
+}
+
+function selectExtrema(points: IndexedPoint[], target: number, kind: 'min' | 'max' | 'minmax') {
+  const bucketCount = kind === 'minmax' ? Math.floor((target - 2) / 2) : Math.max(0, target - 2)
+
+  return withEndpoints(points, target, () => {
+    if (bucketCount === 0) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, points.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (points[index]!.y < points[minimum]!.y) minimum = index
+        if (points[index]!.y > points[maximum]!.y) maximum = index
+      }
+      if (kind === 'min') {
+        addUniqueIndex(result, minimum)
+      } else if (kind === 'max') {
+        addUniqueIndex(result, maximum)
+      } else if (minimum <= maximum) {
+        addUniqueIndex(result, minimum)
+        addUniqueIndex(result, maximum)
+      } else {
+        addUniqueIndex(result, maximum)
+        addUniqueIndex(result, minimum)
+      }
+    }
+    return result
+  })
+}
+
+function selectPeak(points: IndexedPoint[], target: number) {
+  const bucketCount = Math.floor((target - 2) / 4)
+  return withEndpoints(points, target, () => {
+    if (bucketCount === 0) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, points.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (points[index]!.y < points[minimum]!.y) minimum = index
+        if (points[index]!.y > points[maximum]!.y) maximum = index
+      }
+      for (const index of [bounds.start, minimum, maximum, bounds.end - 1].sort((a, b) => a - b)) {
+        addUniqueIndex(result, index)
+      }
+    }
+    return result
+  })
+}
+
+function selectLttb(points: IndexedPoint[], target: number) {
+  return withEndpoints(points, target, () => {
+    const bucketSize = (points.length - 2) / (target - 2)
+    const result: number[] = []
+    let previous = 0
+
+    for (let bucket = 0; bucket < target - 2; bucket += 1) {
+      const averageStart = Math.min(points.length, Math.floor((bucket + 1) * bucketSize) + 1)
+      const averageEnd = Math.min(points.length, Math.floor((bucket + 2) * bucketSize) + 1)
+      let averageX = 0
+      let averageY = 0
+      for (let index = averageStart; index < averageEnd; index += 1) {
+        averageX += points[index]!.x
+        averageY += points[index]!.y
+      }
+      const averageCount = averageEnd - averageStart
+      if (averageCount > 0) {
+        averageX /= averageCount
+        averageY /= averageCount
+      } else {
+        averageX = points[points.length - 1]!.x
+        averageY = points[points.length - 1]!.y
+      }
+
+      const bounds = bucketBounds(bucket, target - 2, 1, points.length - 1)
+      let selected = bounds.start
+      let maximumArea = -1
+      for (let index = bounds.start; index < bounds.end; index += 1) {
+        const area = Math.abs(
+          (points[previous]!.x - averageX) * (points[index]!.y - points[previous]!.y) -
+            (points[previous]!.x - points[index]!.x) * (averageY - points[previous]!.y),
+        )
+        if (area > maximumArea) {
+          maximumArea = area
+          selected = index
+        }
+      }
+      result.push(selected)
+      previous = selected
+    }
+    return result
+  })
+}
+
+function aggregate(points: IndexedPoint[], target: number, strategy: 'average' | 'sum') {
+  const count = targetCount(target, points.length)
+  const x = new Float64Array(count)
+  const y = new Float64Array(count)
+  for (let bucket = 0; bucket < count; bucket += 1) {
+    const bounds = bucketBounds(bucket, count, 0, points.length)
+    for (let index = bounds.start; index < bounds.end; index += 1) {
+      x[bucket] += points[index]!.x
+      y[bucket] += points[index]!.y
+    }
+    const bucketSize = bounds.end - bounds.start
+    x[bucket] /= bucketSize
+    if (strategy === 'average') y[bucket] /= bucketSize
+  }
+  return { x, y }
+}
+
+/**
+ * Samples an immutable point sequence without changing its objects or order. Aggregate X values
+ * are the arithmetic mean of each contiguous bucket's X values; extrema ties select the earliest
+ * source point. Source-point strategies preserve first and last points whenever the target is 2+.
+ */
+export function sampleWaveformReference(
+  request: ReferenceSamplingRequest,
+): ReferenceSamplingResult {
+  const points = normalizedPoints(request.points)
+  const base = {
+    strategy: request.strategy,
+    inputPointCount: request.points.length,
+    validPointCount: points.length,
+  }
+
+  if (request.strategy === 'average' || request.strategy === 'sum') {
+    return {
+      ...base,
+      kind: 'aggregates',
+      ...aggregate(points, request.targetPointCount, request.strategy),
+    }
+  }
+
+  const target = targetCount(request.targetPointCount, points.length)
+  let indexes: number[]
+  if (request.strategy === 'none' || points.length <= target) {
+    indexes = points.map((_, index) => index)
+  } else if (request.strategy === 'peak') {
+    indexes = selectPeak(points, target)
+  } else if (request.strategy === 'lttb') {
+    indexes = selectLttb(points, target)
+  } else {
+    indexes = selectExtrema(points, target, request.strategy)
+  }
+
+  return {
+    ...base,
+    kind: 'source-indexes',
+    sourceIndexes: Uint32Array.from(indexes, (index) => points[index]!.sourceIndex),
+  }
+}

package/src/core/samplingReferenceValues.ts

@@ -0,0 +1,169 @@
+import type { ReferenceSamplingStrategy } from './samplingReference'
+import type { WorkerSamplingOutput } from './workerSampling/protocol'
+
+interface Bounds {
+  start: number
+  end: number
+}
+
+function targetCount(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 bucketBounds(bucket: number, bucketCount: number, start: number, end: number): Bounds {
+  const span = end - start
+  return {
+    start: start + Math.floor((bucket * span) / bucketCount),
+    end: start + Math.floor(((bucket + 1) * span) / bucketCount),
+  }
+}
+
+function addUnique(indexes: number[], index: number) {
+  if (indexes[indexes.length - 1] !== index) indexes.push(index)
+}
+
+function withEndpoints(length: number, target: number, selectInterior: () => number[]) {
+  if (length <= target) return Array.from({ length }, (_, index) => index)
+  if (target === 1) return [0]
+  if (target === 2) return [0, length - 1]
+  const indexes = [0]
+  selectInterior().forEach((index) => addUnique(indexes, index))
+  addUnique(indexes, length - 1)
+  return indexes
+}
+
+function extremaIndexes(y: Float64Array, target: number, strategy: 'min' | 'max' | 'minmax') {
+  const bucketCount = strategy === 'minmax' ? Math.floor((target - 2) / 2) : Math.max(0, target - 2)
+  return withEndpoints(y.length, target, () => {
+    if (!bucketCount) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, y.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (y[index]! < y[minimum]!) minimum = index
+        if (y[index]! > y[maximum]!) maximum = index
+      }
+      if (strategy === 'min') addUnique(result, minimum)
+      else if (strategy === 'max') addUnique(result, maximum)
+      else if (minimum <= maximum) {
+        addUnique(result, minimum)
+        addUnique(result, maximum)
+      } else {
+        addUnique(result, maximum)
+        addUnique(result, minimum)
+      }
+    }
+    return result
+  })
+}
+
+function peakIndexes(y: Float64Array, target: number) {
+  const bucketCount = Math.floor((target - 2) / 4)
+  return withEndpoints(y.length, target, () => {
+    if (!bucketCount) return []
+    const result: number[] = []
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const bounds = bucketBounds(bucket, bucketCount, 1, y.length - 1)
+      let minimum = bounds.start
+      let maximum = bounds.start
+      for (let index = bounds.start + 1; index < bounds.end; index += 1) {
+        if (y[index]! < y[minimum]!) minimum = index
+        if (y[index]! > y[maximum]!) maximum = index
+      }
+      ;[bounds.start, minimum, maximum, bounds.end - 1]
+        .sort((left, right) => left - right)
+        .forEach((index) => addUnique(result, index))
+    }
+    return result
+  })
+}
+
+function lttbIndexes(x: Float64Array, y: Float64Array, target: number) {
+  return withEndpoints(x.length, target, () => {
+    const bucketSize = (x.length - 2) / (target - 2)
+    const result: number[] = []
+    let previous = 0
+    for (let bucket = 0; bucket < target - 2; bucket += 1) {
+      const averageStart = Math.min(x.length, Math.floor((bucket + 1) * bucketSize) + 1)
+      const averageEnd = Math.min(x.length, Math.floor((bucket + 2) * bucketSize) + 1)
+      let averageX = 0
+      let averageY = 0
+      for (let index = averageStart; index < averageEnd; index += 1) {
+        averageX += x[index]!
+        averageY += y[index]!
+      }
+      const averageCount = averageEnd - averageStart
+      if (averageCount) {
+        averageX /= averageCount
+        averageY /= averageCount
+      } else {
+        averageX = x[x.length - 1]!
+        averageY = y[y.length - 1]!
+      }
+      const bounds = bucketBounds(bucket, target - 2, 1, x.length - 1)
+      let selected = bounds.start
+      let maximumArea = -1
+      for (let index = bounds.start; index < bounds.end; index += 1) {
+        const area = Math.abs(
+          (x[previous]! - averageX) * (y[index]! - y[previous]!) -
+            (x[previous]! - x[index]!) * (averageY - y[previous]!),
+        )
+        if (area > maximumArea) {
+          maximumArea = area
+          selected = index
+        }
+      }
+      result.push(selected)
+      previous = selected
+    }
+    return result
+  })
+}
+
+function aggregates(
+  x: Float64Array,
+  y: Float64Array,
+  target: number,
+  strategy: 'average' | 'sum',
+): WorkerSamplingOutput {
+  const count = targetCount(target, x.length)
+  const outputX = new Float64Array(count)
+  const outputY = new Float64Array(count)
+  for (let bucket = 0; bucket < count; bucket += 1) {
+    const bounds = bucketBounds(bucket, count, 0, x.length)
+    for (let index = bounds.start; index < bounds.end; index += 1) {
+      outputX[bucket] += x[index]!
+      outputY[bucket] += y[index]!
+    }
+    const size = bounds.end - bounds.start
+    outputX[bucket] /= size
+    if (strategy === 'average') outputY[bucket] /= size
+  }
+  return { kind: 'aggregates', x: outputX, y: outputY }
+}
+
+/** Numeric JavaScript fallback matching the WASM source-index and aggregate contracts. */
+export function sampleWaveformReferenceValues(
+  x: Float64Array,
+  y: Float64Array,
+  strategy: ReferenceSamplingStrategy,
+  targetPointCount: number,
+): WorkerSamplingOutput {
+  if (x.length !== y.length) throw new Error('x and y must have the same length')
+  if (strategy === 'average' || strategy === 'sum')
+    return aggregates(x, y, targetPointCount, strategy)
+  const target = targetCount(targetPointCount, x.length)
+  const indexes =
+    strategy === 'none' || x.length <= target
+      ? Array.from({ length: x.length }, (_, index) => index)
+      : strategy === 'peak'
+        ? peakIndexes(y, target)
+        : strategy === 'lttb'
+          ? lttbIndexes(x, y, target)
+          : extremaIndexes(y, target, strategy)
+  return { kind: 'source-indexes', sourceIndexes: Uint32Array.from(indexes) }
+}

package/src/core/samplingReferenceVectors.ts

@@ -0,0 +1,46 @@
+import type { WaveformPoint } from '../types'
+import type { ReferenceSamplingStrategy } from './samplingReference'
+
+/** Stable source data shared by the TypeScript reference and future WASM conformance suites. */
+export const REFERENCE_SAMPLING_POINTS: readonly WaveformPoint[] = [
+  { x: 0, y: 4 },
+  { x: 1, y: 1 },
+  { x: 2, y: 8 },
+  { x: 3, y: 2 },
+  { x: 4, y: 7 },
+  { x: 5, y: 0 },
+  { x: 6, y: 9 },
+  { x: 7, y: 3 },
+]
+
+export interface SourceIndexSamplingVector {
+  strategy: Exclude<ReferenceSamplingStrategy, 'average' | 'sum'>
+  targetPointCount: number
+  expectedSourceIndexes: readonly number[]
+}
+
+export const REFERENCE_SOURCE_INDEX_VECTORS: readonly SourceIndexSamplingVector[] = [
+  { strategy: 'none', targetPointCount: 3, expectedSourceIndexes: [0, 1, 2, 3, 4, 5, 6, 7] },
+  { strategy: 'peak', targetPointCount: 6, expectedSourceIndexes: [0, 1, 5, 6, 7] },
+  { strategy: 'min', targetPointCount: 6, expectedSourceIndexes: [0, 1, 3, 4, 5, 7] },
+  { strategy: 'max', targetPointCount: 6, expectedSourceIndexes: [0, 1, 2, 4, 6, 7] },
+  { strategy: 'minmax', targetPointCount: 6, expectedSourceIndexes: [0, 1, 2, 5, 6, 7] },
+  { strategy: 'lttb', targetPointCount: 5, expectedSourceIndexes: [0, 2, 3, 6, 7] },
+]
+
+export interface AggregateSamplingVector {
+  strategy: Extract<ReferenceSamplingStrategy, 'average' | 'sum'>
+  targetPointCount: number
+  expectedX: readonly number[]
+  expectedY: readonly number[]
+}
+
+export const REFERENCE_AGGREGATE_VECTORS: readonly AggregateSamplingVector[] = [
+  {
+    strategy: 'average',
+    targetPointCount: 3,
+    expectedX: [0.5, 3, 6],
+    expectedY: [2.5, 17 / 3, 4],
+  },
+  { strategy: 'sum', targetPointCount: 3, expectedX: [0.5, 3, 6], expectedY: [5, 17, 12] },
+]