@neurodevs/node-lsl 18.1.0 → 20.0.0

package/src/__tests__/impl/WindowedClockRegressor.test.ts

@@ -0,0 +1,262 @@
+import { randomInt } from 'node:crypto'
+
+import { test, assert } from '@neurodevs/node-tdd'
+
+import WindowedClockRegressor, {
+    ClockRegressor,
+} from '../../impl/clocks/WindowedClockRegressor.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+
+export default class WindowedClockRegressorTest extends AbstractPackageTest {
+    private static instance: ClockRegressor
+
+    protected static readonly chunkSize = randomInt(10, 20)
+
+    private static readonly nominalHz = 50 + Math.random() * 50
+    private static readonly deviceTime = Math.random()
+    private static readonly earliestLslTime = Math.random()
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        this.instance = this.WindowedClockRegressor()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async deriveReturnsChunkSizeEntries() {
+        const timestamps = this.deriveTimestamps()
+
+        assert.isEqual(
+            timestamps.length,
+            this.chunkSize,
+            'Should return an array with chunkSize entries!'
+        )
+    }
+
+    @test()
+    protected static async deriveAnchorsLastTimestampOnRegressionLine() {
+        const nominalChunkStep = this.chunkSize / this.nominalHz
+
+        let deviceTime = this.deviceTime
+        let lslTime = this.earliestLslTime
+
+        for (let i = 0; i < 100; i++) {
+            deviceTime += nominalChunkStep
+            lslTime += nominalChunkStep
+            this.deriveTimestamps(deviceTime, lslTime)
+        }
+
+        deviceTime += nominalChunkStep
+        lslTime += nominalChunkStep
+
+        const jitter = nominalChunkStep * Math.random()
+
+        const timestamps = this.deriveTimestamps(deviceTime, lslTime + jitter)
+
+        for (let i = 0; i < timestamps.length; i++) {
+            const stepsFromLast = timestamps.length - 1 - i
+            const expected = lslTime - stepsFromLast / this.nominalHz
+
+            assert.isBetweenInclusive(
+                timestamps[i],
+                expected - jitter * 0.1,
+                expected + jitter * 0.1,
+                `Timestamp at index ${i} should be anchored on the fitted regression line, not the jittery arrival time!`
+            )
+        }
+    }
+
+    @test()
+    protected static async deriveSpacesEntriesByNominalHz() {
+        const timestamps = this.deriveTimestamps()
+
+        const expected = Array(this.chunkSize)
+            .fill(0)
+            .map((_, i) => {
+                return (
+                    this.earliestLslTime -
+                    (this.chunkSize - 1 - i) / this.nominalHz
+                )
+            })
+
+        assert.isEqualDeep(
+            timestamps,
+            expected,
+            'Entries should be spaced 1/nominalHz apart, working backward from earliestLslTime!'
+        )
+    }
+
+    @test()
+    protected static async deriveUsesFittedSlopeOnceHistoryAccumulates() {
+        const trueSlope = 2
+        const nominalStep = this.chunkSize / this.nominalHz
+        const lslStep = nominalStep * trueSlope
+
+        let deviceTime = this.deviceTime
+        let earliestLslTime = this.earliestLslTime
+
+        for (let i = 0; i < 50; i++) {
+            deviceTime += nominalStep
+            earliestLslTime += lslStep
+
+            this.deriveTimestamps(deviceTime, earliestLslTime)
+        }
+
+        deviceTime += nominalStep
+        earliestLslTime += lslStep
+
+        const timestamps = this.deriveTimestamps(deviceTime, earliestLslTime)
+
+        const expectedSpacing = trueSlope / this.nominalHz
+
+        for (let i = 1; i < timestamps.length; i++) {
+            const actualSpacing = timestamps[i] - timestamps[i - 1]
+
+            assert.isBetweenInclusive(
+                actualSpacing,
+                expectedSpacing * 0.99,
+                expectedSpacing * 1.01,
+                `Spacing at index ${i} should reflect the fitted slope once history has accumulated!`
+            )
+        }
+    }
+
+    @test()
+    protected static async deriveThrowsWhenDeviceTimeDoesNotIncreaseMonotonically() {
+        this.deriveTimestamps()
+
+        assert.doesThrow(
+            () =>
+                this.deriveTimestamps(
+                    this.deviceTime,
+                    this.earliestLslTime + Math.random()
+                ),
+            `\nDevice time (${this.deviceTime}) did not increase from the previous device time (${this.deviceTime})! Device time is expected to always increase between calls, so this likely indicates a bug in the calling code.\n`
+        )
+    }
+
+    @test()
+    protected static async deriveForgetsHistoryOutsideWindowLenSec() {
+        const nominalChunkStep = this.chunkSize / this.nominalHz
+
+        // With chunkSize in [10, 20) and nominalHz in [50, 100), nominalChunkStep
+        // stays within [0.1, 0.4). A fixed 700 iterations always spans at least
+        // 70 device-seconds — comfortably more than 2x the 30s windowLenSec.
+        const oldPhaseCount = 700
+        const newPhaseCount = 700
+
+        let deviceTime = this.deviceTime
+        let earliestLslTime = this.earliestLslTime
+
+        const oldSlope = 2
+
+        for (let i = 0; i < oldPhaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * oldSlope
+
+            this.deriveTimestamps(deviceTime, earliestLslTime)
+        }
+
+        const newSlope = 5
+        let timestamps: number[] = []
+
+        for (let i = 0; i < newPhaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * newSlope
+
+            timestamps = this.deriveTimestamps(deviceTime, earliestLslTime)
+        }
+
+        const expectedSpacing = newSlope / this.nominalHz
+
+        for (let i = 1; i < timestamps.length; i++) {
+            const actualSpacing = timestamps[i] - timestamps[i - 1]
+
+            assert.isBetweenInclusive(
+                actualSpacing,
+                expectedSpacing * 0.99,
+                expectedSpacing * 1.01,
+                `Spacing at index ${i} should reflect the new slope once old history falls outside windowLenSec!`
+            )
+        }
+    }
+
+    @test()
+    protected static async deriveAllowsOverridingWindowLenSec() {
+        const nominalChunkStep = this.chunkSize / this.nominalHz
+        const customWindowLenSec = 5
+
+        // With nominalChunkStep in [0.1, 0.4), 150 iterations always spans at
+        // least 15 device-seconds — more than 2x the 5s customWindowLenSec,
+        // but well short of 2x the 30s default, so this only passes if the
+        // override actually takes effect.
+        const phaseCount = 150
+
+        const instance = WindowedClockRegressor.Create(this.nominalHz, {
+            windowLenSec: customWindowLenSec,
+        })
+
+        let deviceTime = this.deviceTime
+        let earliestLslTime = this.earliestLslTime
+
+        const oldSlope = 2
+
+        for (let i = 0; i < phaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * oldSlope
+
+            instance.deriveTimestamps(
+                deviceTime,
+                earliestLslTime,
+                this.chunkSize
+            )
+        }
+
+        const newSlope = 5
+        let timestamps: number[] = []
+
+        for (let i = 0; i < phaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * newSlope
+
+            timestamps = instance.deriveTimestamps(
+                deviceTime,
+                earliestLslTime,
+                this.chunkSize
+            )
+        }
+
+        const expectedSpacing = newSlope / this.nominalHz
+
+        for (let i = 1; i < timestamps.length; i++) {
+            const actualSpacing = timestamps[i] - timestamps[i - 1]
+
+            assert.isBetweenInclusive(
+                actualSpacing,
+                expectedSpacing * 0.99,
+                expectedSpacing * 1.01,
+                `Spacing at index ${i} should reflect the new slope once old history falls outside the custom windowLenSec!`
+            )
+        }
+    }
+
+    private static deriveTimestamps(
+        deviceTime = this.deviceTime,
+        earliestLslTime = this.earliestLslTime
+    ) {
+        return this.instance.deriveTimestamps(
+            deviceTime,
+            earliestLslTime,
+            this.chunkSize
+        )
+    }
+
+    private static WindowedClockRegressor() {
+        return WindowedClockRegressor.Create(this.nominalHz)
+    }
+}

package/src/assertions.ts

@@ -1,6 +1,5 @@
-import { ChannelFormat } from '@neurodevs/ndx-native'
+import { CHANNEL_FORMATS, ChannelFormat } from '@neurodevs/ndx-native'
 
-import { CHANNEL_FORMATS } from './consts.js'
 import {
     isGreaterThanOrEqualToZero,
     isPositiveInteger,

package/src/impl/LslEventMarkerEmitter.ts

@@ -1,28 +1,28 @@
 import { generateShortId } from '@neurodevs/generate-id'
 
 import LslStreamOutlet, {
-    StreamOutletOptions,
-    StreamOutlet,
+    LslOutletOptions,
+    LslOutlet,
 } from './LslStreamOutlet.js'
 
-export default class LslEventMarkerEmitter implements EventMarkerEmitter {
-    public static Class?: EventMarkerEmitterConstructor
+export default class LslEventMarkerEmitter implements LslEmitter {
+    public static Class?: LslEmitterConstructor
 
-    protected outlet: StreamOutlet
+    protected outlet: LslOutlet
     private isRunning = false
     private waitResolve?: () => void
     private timeout?: any
 
-    protected constructor(outlet: StreamOutlet) {
+    protected constructor(outlet: LslOutlet) {
         this.outlet = outlet
     }
 
-    public static async Create(options?: EventMarkerEmitterOptions) {
+    public static async Create(options?: LslEmitterOptions) {
         const outlet = await this.LslStreamOutlet(options)
         return new (this.Class ?? this)(outlet)
     }
 
-    public async emit(markerName: string, options?: EventMarkerOptions) {
+    public async emit(markerName: string, options?: EmitOptions) {
         this.throwIfAlreadyRunning('emit')
         this.isRunning = true
 
@@ -99,10 +99,10 @@ export default class LslEventMarkerEmitter implements EventMarkerEmitter {
             channelFormat: 'string',
             sampleRateHz: 0,
             chunkSize: 1,
-        } as StreamOutletOptions
+        } as LslOutletOptions
     }
 
-    private static LslStreamOutlet(options?: Partial<StreamOutletOptions>) {
+    private static LslStreamOutlet(options?: Partial<LslOutletOptions>) {
         return LslStreamOutlet.Create({
             ...this.generateDefaultOutletOptions(),
             ...options,
@@ -110,20 +110,18 @@ export default class LslEventMarkerEmitter implements EventMarkerEmitter {
     }
 }
 
-export interface EventMarkerEmitter {
-    emit(markerName: string, options?: EventMarkerOptions): Promise<void>
+export interface LslEmitter {
+    emit(markerName: string, options?: EmitOptions): Promise<void>
     emitMany(markers: TimedEventMarker[]): Promise<void>
     interrupt(): void
     destroy(): void
 }
 
-export type EventMarkerEmitterOptions = Partial<StreamOutletOptions>
+export type LslEmitterOptions = Partial<LslOutletOptions>
 
-export type EventMarkerEmitterConstructor = new (
-    outlet: StreamOutlet
-) => EventMarkerEmitter
+export type LslEmitterConstructor = new (outlet: LslOutlet) => LslEmitter
 
-export interface EventMarkerOptions {
+export interface EmitOptions {
     waitAfterMs?: number
 }
 

package/src/impl/LslStreamInfo.ts

@@ -6,8 +6,8 @@ import {
     CHANNEL_FORMATS_MAP,
 } from '@neurodevs/ndx-native'
 
-export default class LslStreamInfo implements StreamInfo {
-    public static Class?: StreamInfoConstructor
+export default class LslStreamInfo implements LslInfo {
+    public static Class?: LslInfoConstructor
 
     public readonly name: string
     public readonly type: string
@@ -22,7 +22,7 @@ export default class LslStreamInfo implements StreamInfo {
 
     private lsl = LiblslAdapter.getInstance()
 
-    protected constructor(options: StreamInfoOptions) {
+    protected constructor(options: LslInfoOptions) {
         const {
             name = `lsl-stream-info-${generateId()}`,
             type = generateId(),
@@ -46,7 +46,7 @@ export default class LslStreamInfo implements StreamInfo {
         this.appendChannelsToStreamInfo()
     }
 
-    public static Create(options: StreamInfoOptions) {
+    public static Create(options: LslInfoOptions) {
         return new (this.Class ?? this)(options)
     }
 
@@ -81,7 +81,7 @@ export default class LslStreamInfo implements StreamInfo {
     }
 }
 
-export interface StreamInfo {
+export interface LslInfo {
     destroy(): void
     readonly name: string
     readonly type: string
@@ -94,11 +94,9 @@ export interface StreamInfo {
     readonly infoHandle: InfoHandle
 }
 
-export type StreamInfoConstructor = new (
-    options: StreamInfoOptions
-) => StreamInfo
+export type LslInfoConstructor = new (options: LslInfoOptions) => LslInfo
 
-export interface StreamInfoOptions {
+export interface LslInfoOptions {
     channelNames: string[]
     channelFormat: ChannelFormat
     sampleRateHz: number