waveform-analysis 0.1.48 → 0.1.50

package/src/core/workerSampling/repository.ts

@@ -0,0 +1,400 @@
+import type { WaveformPoint } from '@/types'
+import type { WorkerSamplingDataset } from '../waveformPointSource'
+import { javascriptSamplingBackend } from './javascriptBackend'
+import {
+  datasetLength,
+  datasetVisibleRange,
+  datasetXAt,
+  datasetXRange,
+  createStoredDataset,
+  disposeDatasetIndexes,
+  isWasmDatasetBackend,
+  registerWasmDataset,
+  type StoredDataset,
+} from './repositoryDataset'
+import {
+  type DatasetResponse,
+  type DisposeAllResponse,
+  type FindNearestPointResponse,
+  type SampleViewportResponse,
+  type WorkerSamplingBackend,
+  type WorkerSamplingBackendKind,
+  type WorkerSamplingOutput,
+  type WorkerSamplingRequest,
+  type WorkerSamplingResponse,
+  type WorkerSamplingSeriesRequest,
+  type WorkerSamplingSeriesResponse,
+  type WorkerSamplingStatus,
+} from './protocol'
+import { SamplingOutputCache, type SamplingCacheMetrics } from './samplingCache'
+import {
+  cacheKey,
+  diagnosticsFor,
+  nearestPoint,
+  outputCount,
+  outputWithGlobalIndexes,
+  selectedStrategy,
+  shouldUseRaw,
+  statusFor,
+  targetPointCount,
+} from './repositorySupport'
+
+export interface WorkerSamplingResourceMetrics {
+  datasetCount: number
+  indexBytes: number
+  cache: SamplingCacheMetrics
+}
+
+export interface WorkerSamplingRepositoryOptions {
+  javascriptBackend?: WorkerSamplingBackend
+  wasmBackend?: WorkerSamplingBackend
+  indexMaxBytes?: number
+  cacheMaxEntries?: number
+  cacheMaxBytes?: number
+}
+
+export class WorkerSamplingRepository {
+  private readonly datasets = new Map<string, StoredDataset>()
+  private readonly javascriptBackend: WorkerSamplingBackend
+  private readonly cache: SamplingOutputCache
+  private readonly indexMaxBytes: number | undefined
+  private wasmBackend: WorkerSamplingBackend | undefined
+
+  constructor(options: WorkerSamplingRepositoryOptions = {}) {
+    this.javascriptBackend = options.javascriptBackend ?? javascriptSamplingBackend
+    this.wasmBackend = options.wasmBackend
+    this.indexMaxBytes = options.indexMaxBytes
+    this.cache = new SamplingOutputCache({
+      maxEntries: options.cacheMaxEntries,
+      maxBytes: options.cacheMaxBytes,
+    })
+  }
+
+  get resourceMetrics(): WorkerSamplingResourceMetrics {
+    return {
+      datasetCount: this.datasets.size,
+      indexBytes: [...this.datasets.values()].reduce(
+        (total, dataset) => total + (dataset.wasmIndexBytes ?? dataset.index?.byteLength ?? 0),
+        0,
+      ),
+      cache: this.cache.metrics,
+    }
+  }
+
+  /** Enables the numeric backend after the worker has initialized its WASM module. */
+  setWasmBackend(backend: WorkerSamplingBackend | undefined) {
+    if (
+      this.wasmBackend &&
+      this.wasmBackend !== backend &&
+      isWasmDatasetBackend(this.wasmBackend)
+    ) {
+      this.wasmBackend.disposeAllDatasets()
+      this.datasets.forEach((dataset) => {
+        dataset.wasmDatasetHandle = undefined
+        dataset.wasmIndexBytes = undefined
+      })
+    }
+    this.wasmBackend = backend
+    if (isWasmDatasetBackend(backend))
+      this.datasets.forEach((dataset) => registerWasmDataset(backend, dataset, this.indexMaxBytes))
+  }
+
+  handle(request: WorkerSamplingRequest): WorkerSamplingResponse {
+    switch (request.type) {
+      case 'register-dataset':
+        return this.register(request.datasetId, request.requestId, request.points, request.dataset)
+      case 'replace-dataset':
+        return this.replace(
+          request.datasetId,
+          request.requestId,
+          request.revision,
+          request.points,
+          request.dataset,
+        )
+      case 'sample-viewport':
+        return this.sample(request)
+      case 'find-nearest-point':
+        return this.findNearest(request.datasetId, request.requestId, request.revision, request.x)
+      case 'get-dataset-metrics':
+        return this.metrics(request.datasetId, request.requestId, request.revision)
+      case 'dispose-dataset':
+        return this.dispose(request.datasetId, request.requestId, request.revision)
+      case 'dispose-all':
+        return this.disposeAll(request.requestId)
+    }
+  }
+
+  private register(
+    datasetId: string,
+    requestId: number,
+    points: readonly WaveformPoint[] | undefined,
+    dataset?: WorkerSamplingDataset,
+  ): DatasetResponse {
+    const existing = this.datasets.get(datasetId)
+    if (existing) return this.datasetResponse(requestId, datasetId, existing, 'stale-revision')
+    const stored = createStoredDataset(points, dataset, 1, this.indexMaxBytes)
+    registerWasmDataset(this.wasmBackend, stored, this.indexMaxBytes)
+    this.datasets.set(datasetId, stored)
+    return this.datasetResponse(requestId, datasetId, stored, 'ok')
+  }
+
+  private replace(
+    datasetId: string,
+    requestId: number,
+    revision: number,
+    points: readonly WaveformPoint[] | undefined,
+    numeric?: WorkerSamplingDataset,
+  ): DatasetResponse {
+    const existing = this.datasets.get(datasetId)
+    const status = statusFor(existing, revision)
+    if (status !== 'ok' || !existing)
+      return this.datasetResponse(requestId, datasetId, existing, status)
+    disposeDatasetIndexes(this.wasmBackend, existing)
+    this.cache.deleteDataset(datasetId)
+    const dataset = createStoredDataset(points, numeric, existing.revision + 1, this.indexMaxBytes)
+    registerWasmDataset(this.wasmBackend, dataset, this.indexMaxBytes)
+    this.datasets.set(datasetId, dataset)
+    return this.datasetResponse(requestId, datasetId, dataset, 'ok')
+  }
+
+  private sample(
+    request: Extract<WorkerSamplingRequest, { type: 'sample-viewport' }>,
+  ): SampleViewportResponse {
+    return {
+      type: 'sample-viewport-response',
+      requestId: request.requestId,
+      results: request.series.map((series) => this.sampleSeries(request.requestId, series)),
+    }
+  }
+
+  private sampleSeries(
+    requestId: number,
+    request: WorkerSamplingSeriesRequest,
+  ): WorkerSamplingSeriesResponse {
+    const startedAt = performance.now()
+    const dataset = this.datasets.get(request.datasetId)
+    const status = statusFor(dataset, request.revision)
+    if (status !== 'ok' || !dataset) {
+      return this.sampleResponse(
+        requestId,
+        request,
+        status,
+        undefined,
+        'unavailable',
+        'sampled',
+        0,
+        startedAt,
+        false,
+      )
+    }
+    const range = datasetVisibleRange(dataset, request.xDomain)
+    const visiblePointCount = range.end - range.start
+    if (shouldUseRaw(request, visiblePointCount)) {
+      return this.sampleResponse(
+        requestId,
+        request,
+        'ok',
+        {
+          kind: 'source-indexes',
+          sourceIndexes: Uint32Array.from(
+            { length: visiblePointCount },
+            (_, index) => range.start + index,
+          ),
+        },
+        'raw',
+        'raw',
+        visiblePointCount,
+        startedAt,
+        false,
+      )
+    }
+    const preferredBackend =
+      request.mode === 'wasm' || (request.mode === 'auto' && this.wasmBackend)
+        ? this.wasmBackend
+        : this.javascriptBackend
+    const fallbackToJavascript = !preferredBackend && request.wasmFailureFallback === 'javascript'
+    const backend = preferredBackend ?? (fallbackToJavascript ? this.javascriptBackend : undefined)
+    if (!backend) {
+      return this.sampleResponse(
+        requestId,
+        request,
+        'wasm-unavailable',
+        undefined,
+        'unavailable',
+        'sampled',
+        visiblePointCount,
+        startedAt,
+        false,
+      )
+    }
+    const strategy = selectedStrategy(request.strategy)
+    const target = targetPointCount(request)
+    const key = cacheKey(request, range, strategy, target, backend.kind)
+    const cached = this.cache.get(key)
+    if (cached) {
+      return this.sampleResponse(
+        requestId,
+        request,
+        fallbackToJavascript ? 'wasm-unavailable' : 'ok',
+        cached,
+        backend.kind,
+        'sampled',
+        visiblePointCount,
+        startedAt,
+        true,
+      )
+    }
+    const indexed =
+      backend.kind === 'wasm'
+        ? dataset.wasmDatasetHandle !== undefined && isWasmDatasetBackend(backend)
+          ? backend.sampleDataset(
+              dataset.wasmDatasetHandle,
+              range.start,
+              range.end,
+              strategy,
+              target,
+            )
+          : undefined
+        : dataset.index?.sample(range.start, range.end, strategy, target)
+    const output =
+      indexed ??
+      outputWithGlobalIndexes(
+        backend.sample({
+          x: datasetXRange(dataset, range.start, range.end),
+          y: dataset.y.subarray(range.start, range.end),
+          points: dataset.points?.slice(range.start, range.end) ?? [],
+          strategy,
+          targetPointCount: target,
+        }),
+        range.start,
+      )
+    this.cache.set(key, output)
+    if (dataset.wasmDatasetHandle !== undefined && isWasmDatasetBackend(backend)) {
+      dataset.wasmIndexBytes = backend.datasetIndexBytes(dataset.wasmDatasetHandle)
+    }
+    return this.sampleResponse(
+      requestId,
+      request,
+      fallbackToJavascript ? 'wasm-unavailable' : 'ok',
+      output,
+      backend.kind,
+      'sampled',
+      visiblePointCount,
+      startedAt,
+      false,
+    )
+  }
+
+  private sampleResponse(
+    requestId: number,
+    request: WorkerSamplingSeriesRequest,
+    status: WorkerSamplingStatus,
+    output: WorkerSamplingOutput | undefined,
+    backend: WorkerSamplingBackendKind,
+    selectedMode: 'raw' | 'sampled',
+    visiblePointCount: number,
+    startedAt: number,
+    cacheHit: boolean,
+  ): WorkerSamplingSeriesResponse {
+    const diagnostics = diagnosticsFor(
+      request,
+      datasetLength(this.datasets.get(request.datasetId)),
+      visiblePointCount,
+      backend,
+      selectedMode,
+      performance.now() - startedAt,
+      outputCount(output),
+      cacheHit,
+    )
+    diagnostics.requestId = requestId
+    return {
+      seriesId: request.seriesId,
+      datasetId: request.datasetId,
+      revision: request.revision,
+      status,
+      output,
+      diagnostics,
+    }
+  }
+
+  private findNearest(
+    datasetId: string,
+    requestId: number,
+    revision: number,
+    x: number,
+  ): FindNearestPointResponse {
+    const dataset = this.datasets.get(datasetId)
+    const status = statusFor(dataset, revision)
+    if (status !== 'ok' || !dataset) {
+      return { type: 'find-nearest-point-response', requestId, datasetId, revision, status }
+    }
+    const point = dataset.points
+      ? nearestPoint(dataset.points, x)
+      : (() => {
+          const range = datasetVisibleRange(dataset, [x, x])
+          if (
+            !datasetLength(dataset) ||
+            x < datasetXAt(dataset, 0) ||
+            x > datasetXAt(dataset, datasetLength(dataset) - 1)
+          ) {
+            return undefined
+          }
+          const right = Math.min(datasetLength(dataset) - 1, range.start)
+          const left = Math.max(0, right - 1)
+          const index =
+            Math.abs(x - datasetXAt(dataset, left)) < Math.abs(datasetXAt(dataset, right) - x)
+              ? left
+              : right
+          return Number.isFinite(x) && datasetLength(dataset)
+            ? { x: datasetXAt(dataset, index), y: dataset.y[index]! }
+            : undefined
+        })()
+    return { type: 'find-nearest-point-response', requestId, datasetId, revision, status, point }
+  }
+
+  private metrics(datasetId: string, requestId: number, revision: number): DatasetResponse {
+    const dataset = this.datasets.get(datasetId)
+    return this.datasetResponse(requestId, datasetId, dataset, statusFor(dataset, revision))
+  }
+
+  private dispose(datasetId: string, requestId: number, revision: number): DatasetResponse {
+    const dataset = this.datasets.get(datasetId)
+    const status = statusFor(dataset, revision)
+    if (status === 'ok' && dataset) {
+      disposeDatasetIndexes(this.wasmBackend, dataset)
+      this.cache.deleteDataset(datasetId)
+      this.datasets.delete(datasetId)
+    }
+    return this.datasetResponse(requestId, datasetId, dataset, status)
+  }
+
+  private disposeAll(requestId: number): DisposeAllResponse {
+    const disposedDatasetIds = [...this.datasets.keys()]
+    this.datasets.forEach((dataset) => disposeDatasetIndexes(this.wasmBackend, dataset))
+    if (isWasmDatasetBackend(this.wasmBackend)) this.wasmBackend.disposeAllDatasets()
+    this.datasets.clear()
+    this.cache.clear()
+    return { type: 'dispose-all-response', requestId, disposedDatasetIds }
+  }
+
+  private datasetResponse(
+    requestId: number,
+    datasetId: string,
+    dataset: StoredDataset | undefined,
+    status: WorkerSamplingStatus,
+  ): DatasetResponse {
+    return {
+      type: 'dataset-response',
+      requestId,
+      datasetId,
+      revision: dataset?.revision ?? 0,
+      status,
+      metrics: dataset
+        ? {
+            ...dataset.metrics,
+            indexBytes: dataset.wasmIndexBytes ?? dataset.index?.byteLength ?? 0,
+          }
+        : undefined,
+    }
+  }
+}

package/src/core/workerSampling/repositoryCache.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest'
+
+import type { WaveformPoint } from '@/types'
+import type { WorkerSamplingBackend, WorkerSamplingSeriesRequest } from './protocol'
+import { WorkerSamplingRepository } from './repository'
+
+const points: WaveformPoint[] = Array.from({ length: 32 }, (_, index) => ({
+  x: index,
+  y: index === 7 ? 90 : index,
+}))
+
+function register(repository: WorkerSamplingRepository, datasetId: string, source = points) {
+  return repository.handle({
+    type: 'register-dataset',
+    requestId: 1,
+    datasetId,
+    revision: 0,
+    points: source,
+  })
+}
+
+function request(datasetId: string, revision = 1): WorkerSamplingSeriesRequest {
+  return {
+    seriesId: `${datasetId}-series`,
+    datasetId,
+    revision,
+    xDomain: [0, 31],
+    plotWidth: 3,
+    mode: 'auto',
+    autoThreshold: 2,
+    strategy: 'peak',
+    maxPointsPerPixel: 2,
+    rawPointLimit: 5,
+  }
+}
+
+describe('WorkerSamplingRepository cache lifecycle', () => {
+  it('reports a real cache hit for a repeated viewport and misses after a rendering-key change', () => {
+    const repository = new WorkerSamplingRepository()
+    register(repository, 'alpha')
+    const series = { ...request('alpha'), lineType: 'linear' as const }
+    const first = repository.handle({ type: 'sample-viewport', requestId: 20, series: [series] })
+    const repeated = repository.handle({ type: 'sample-viewport', requestId: 21, series: [series] })
+    const changed = repository.handle({
+      type: 'sample-viewport',
+      requestId: 22,
+      series: [{ ...series, lineType: 'step-end' }],
+    })
+
+    expect(first).toMatchObject({ results: [{ diagnostics: { cacheHit: false } }] })
+    expect(repeated).toMatchObject({ results: [{ diagnostics: { cacheHit: true } }] })
+    expect(changed).toMatchObject({ results: [{ diagnostics: { cacheHit: false } }] })
+    expect(repository.resourceMetrics.cache.entries).toBe(2)
+  })
+
+  it('invalidates cached outputs and releases indexes on revision replacement and disposal', () => {
+    const repository = new WorkerSamplingRepository()
+    register(repository, 'alpha')
+    const series = request('alpha')
+    repository.handle({ type: 'sample-viewport', requestId: 23, series: [series] })
+    expect(repository.resourceMetrics.indexBytes).toBeGreaterThan(0)
+    expect(repository.resourceMetrics.cache.entries).toBe(1)
+
+    repository.handle({
+      type: 'replace-dataset',
+      requestId: 24,
+      datasetId: 'alpha',
+      revision: 1,
+      points: points.map((point) => ({ ...point, y: point.y + 1 })),
+    })
+    expect(repository.resourceMetrics).toMatchObject({ indexBytes: 0, cache: { entries: 0 } })
+    const replacement = repository.handle({
+      type: 'sample-viewport',
+      requestId: 25,
+      series: [{ ...series, revision: 2 }],
+    })
+    expect(replacement).toMatchObject({
+      results: [{ diagnostics: { cacheHit: false, revision: 2 } }],
+    })
+    repository.handle({ type: 'dispose-dataset', requestId: 26, datasetId: 'alpha', revision: 2 })
+    expect(repository.resourceMetrics).toMatchObject({ datasetCount: 0, indexBytes: 0 })
+  })
+
+  it('uses distinct cached outputs for each series in a shared viewport request', () => {
+    const repository = new WorkerSamplingRepository()
+    register(repository, 'alpha')
+    register(
+      repository,
+      'beta',
+      points.map((point) => ({ ...point, y: -point.y })),
+    )
+    const series = [request('alpha'), request('beta')]
+
+    repository.handle({ type: 'sample-viewport', requestId: 27, series })
+    const repeated = repository.handle({ type: 'sample-viewport', requestId: 28, series })
+
+    expect(repeated).toMatchObject({
+      results: [{ diagnostics: { cacheHit: true } }, { diagnostics: { cacheHit: true } }],
+    })
+    repository.handle({ type: 'dispose-all', requestId: 29 })
+    expect(repository.resourceMetrics).toMatchObject({
+      datasetCount: 0,
+      indexBytes: 0,
+      cache: { entries: 0 },
+    })
+  })
+
+  it('computes LTTB per viewport once, then reuses only the matching viewport result', () => {
+    let calls = 0
+    const javascriptBackend: WorkerSamplingBackend = {
+      kind: 'javascript',
+      sample: ({ points }) => {
+        calls += 1
+        return { kind: 'source-indexes', sourceIndexes: Uint32Array.from([0, points.length - 1]) }
+      },
+    }
+    const repository = new WorkerSamplingRepository({ javascriptBackend })
+    register(repository, 'alpha')
+    const full = { ...request('alpha'), strategy: 'lttb' as const }
+    const zoomed = { ...full, xDomain: [4, 19] as [number, number] }
+
+    repository.handle({ type: 'sample-viewport', requestId: 30, series: [full] })
+    const repeated = repository.handle({ type: 'sample-viewport', requestId: 31, series: [full] })
+    repository.handle({ type: 'sample-viewport', requestId: 32, series: [zoomed] })
+
+    expect(calls).toBe(2)
+    expect(repeated).toMatchObject({ results: [{ diagnostics: { cacheHit: true } }] })
+  })
+
+  it('evicts least-recently-used sampled outputs at the configured entry bound', () => {
+    const repository = new WorkerSamplingRepository({ cacheMaxEntries: 1 })
+    register(repository, 'alpha')
+    const full = request('alpha')
+    const zoomed = { ...full, xDomain: [4, 19] as [number, number] }
+
+    repository.handle({ type: 'sample-viewport', requestId: 33, series: [full] })
+    repository.handle({ type: 'sample-viewport', requestId: 34, series: [zoomed] })
+    const fullAgain = repository.handle({ type: 'sample-viewport', requestId: 35, series: [full] })
+
+    expect(repository.resourceMetrics.cache).toMatchObject({ entries: 1, maxEntries: 1 })
+    expect(fullAgain).toMatchObject({ results: [{ diagnostics: { cacheHit: false } }] })
+  })
+
+  it('bounds cache memory and reports lazily allocated index bytes through dataset metrics', () => {
+    const repository = new WorkerSamplingRepository({ cacheMaxBytes: 8 })
+    register(repository, 'alpha')
+    const series = request('alpha')
+
+    repository.handle({ type: 'sample-viewport', requestId: 36, series: [series] })
+    const repeated = repository.handle({ type: 'sample-viewport', requestId: 37, series: [series] })
+    const metrics = repository.handle({
+      type: 'get-dataset-metrics',
+      requestId: 38,
+      datasetId: 'alpha',
+      revision: 1,
+    })
+
+    expect(repeated).toMatchObject({ results: [{ diagnostics: { cacheHit: false } }] })
+    expect(repository.resourceMetrics.cache).toMatchObject({ entries: 0, maxBytes: 8 })
+    expect(metrics).toMatchObject({ status: 'ok', metrics: { indexBytes: expect.any(Number) } })
+    if (metrics.type === 'dataset-response') expect(metrics.metrics?.indexBytes).toBeGreaterThan(0)
+  })
+})