@neurodevs/node-lsl 18.0.0 → 19.0.0

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

@@ -0,0 +1,109 @@
+import { test, assert } from '@neurodevs/node-tdd'
+
+import UsbDeviceController, {
+    UsbController,
+} from '../../impl/controllers/UsbDeviceController.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+import { FakeLibndx } from '@neurodevs/ndx-native'
+
+export default class UsbDeviceControllerTest extends AbstractPackageTest {
+    private static instance: UsbController
+
+    private static readonly serialNumber = this.generateId()
+    private static readonly valueToWrite = this.generateId()
+
+    private static readonly callsToOnData: {
+        data: Buffer
+        length: number
+        timestampSec: number
+    }[] = []
+
+    private static readonly onData = (
+        data: Buffer,
+        length: number,
+        timestampSec: number
+    ) => {
+        this.callsToOnData.push({ data, length, timestampSec })
+    }
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        this.instance = this.UsbDeviceController()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async connectCallsLibndxCreateUsbBackend() {
+        await this.connect()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToCreateUsbBackend[0],
+            {
+                serialNumber: this.serialNumber,
+            },
+            'Did not call create_usb_backend!'
+        )
+    }
+
+    @test()
+    protected static async connectCallsLibndxStartUsbBackend() {
+        await this.connect()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToStartUsbBackend[0],
+            {
+                serialNumber: this.serialNumber,
+                onData: this.onData,
+            },
+            'Did not call start_usb_backend!'
+        )
+    }
+
+    @test()
+    protected static async disconnectCallsLibndxStopUsbBackend() {
+        await this.connect()
+        await this.disconnect()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToStopUsbBackend[0],
+            {
+                serialNumber: this.serialNumber,
+            },
+            'Did not call stop_usb_backend!'
+        )
+    }
+
+    @test()
+    protected static async writeUsbCallsLibndxWriteUsbBackend() {
+        await this.instance.writeUsb(this.valueToWrite)
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToWriteUsbBackend[0],
+            {
+                serialNumber: this.serialNumber,
+                value: this.valueToWrite,
+            },
+            'Did not call write_usb_backend!'
+        )
+    }
+
+    private static async connect() {
+        await this.instance.connect()
+    }
+
+    private static async disconnect() {
+        await this.instance.disconnect()
+    }
+
+    private static UsbDeviceController() {
+        return UsbDeviceController.Create({
+            onData: this.onData,
+            serialNumber: this.serialNumber,
+        })
+    }
+}

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/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/impl/LslStreamInlet.ts

@@ -4,6 +4,7 @@ export default class LslStreamInlet implements StreamInlet {
     public static Class?: StreamInletConstructor
     public static Worker = Worker
     public static waitAfterOpenStreamMs = 100
+    public static setTimeout = setTimeout
 
     private sourceId: string
     private chunkSize: number
@@ -91,7 +92,9 @@ export default class LslStreamInlet implements StreamInlet {
             this.postCreate()
 
             while (!this.workerReady) {
-                await new Promise((resolve) => setTimeout(resolve, 10))
+                await new Promise((resolve) =>
+                    LslStreamInlet.setTimeout(resolve, 10)
+                )
             }
 
             this.postStartPulling()

package/src/impl/LslStreamOutlet.ts

@@ -13,6 +13,7 @@ import {
 export default class LslStreamOutlet implements StreamOutlet {
     public static Class?: StreamOutletConstructor
     public static Worker = Worker
+    public static setTimeout = setTimeout
 
     public readonly name: string
     public readonly type: string
@@ -131,12 +132,12 @@ export default class LslStreamOutlet implements StreamOutlet {
         string: 'pushSampleStringTimestamp',
     }
 
-    public pushSample(sample: LslSample, timestamp?: number) {
+    public pushSample(sample: LslSample, timestampSec?: number) {
         this.worker.postMessage({
             type: 'pushSample',
             payload: {
                 sample,
-                timestamp,
+                timestampSec,
             },
         })
     }
@@ -153,13 +154,13 @@ export default class LslStreamOutlet implements StreamOutlet {
 
     private static async waitForSetup(waitAfterConstructionMs: number) {
         await new Promise((resolve) =>
-            setTimeout(resolve, waitAfterConstructionMs)
+            LslStreamOutlet.setTimeout(resolve, waitAfterConstructionMs)
         )
     }
 }
 
 export interface StreamOutlet {
-    pushSample(sample: LslSample, timestamp?: number): void
+    pushSample(sample: LslSample, timestampSec?: number): void
     destroy(): void
     readonly name: string
     readonly type: string

package/src/impl/LslWebSocketBridge.ts

@@ -66,7 +66,7 @@ export default class LslWebSocketBridge implements WebSocketBridge {
         }
     }
 
-    private readonly cannotActivateMessage = `\n\n Cannot activate bridge after destroying it! \n\n Please create and activate a new instance. \n`
+    private readonly cannotActivateMessage = `\n\nCannot activate bridge after destroying it! \n\nPlease create and activate a new instance. \n`
 
     private async startPullingData() {
         await this.inlet.startPulling()
@@ -77,7 +77,7 @@ export default class LslWebSocketBridge implements WebSocketBridge {
         this.stopPullingData()
     }
 
-    private readonly cannotDeactivateMessage = `\n\n Cannot deactivate bridge after destroying it! \n\n Please create and activate a new instance. \n`
+    private readonly cannotDeactivateMessage = `\n\nCannot deactivate bridge after destroying it! \n\nPlease create and activate a new instance. \n`
 
     private stopPullingData() {
         this.inlet.stopPulling()

package/src/impl/WindowedClockRegressor.ts

@@ -0,0 +1,136 @@
+export default class WindowedClockRegressor implements ClockRegressor {
+    public static Class?: ClockRegressorConstructor
+
+    private readonly nominalHz: number
+    private readonly windowLenSec: number
+    private readonly defaultWindowLenSec = 30
+    private readonly history: {
+        deviceTime: number
+        earliestLslTime: number
+    }[] = []
+
+    private slope = 1 // lsl-host-seconds per device-second
+
+    protected constructor(
+        nominalHz: number,
+        options?: WindowedClockRegressorOptions
+    ) {
+        const { windowLenSec = this.defaultWindowLenSec } = options ?? {}
+
+        this.nominalHz = nominalHz
+        this.windowLenSec = windowLenSec
+    }
+
+    public static Create(
+        nominalHz: number,
+        options?: WindowedClockRegressorOptions
+    ) {
+        return new (this.Class ?? this)(nominalHz, options)
+    }
+
+    public deriveTimestamps(
+        deviceTime: number,
+        earliestLslTime: number,
+        chunkSize: number
+    ) {
+        this.throwIfDeviceTimeDoesNotIncrease(deviceTime)
+
+        this.history.push({ deviceTime, earliestLslTime })
+        this.pruneHistoryOutsideWindow()
+        this.refitSlope()
+
+        const anchor = this.anchorTimeFor(deviceTime)
+
+        const timestamps = Array(chunkSize).fill(0)
+
+        for (let i = 0; i <= chunkSize - 1; i++) {
+            const stepsFromLast = chunkSize - 1 - i
+            const deviceTimeOffset = -stepsFromLast / this.nominalHz
+            const lslTimeOffset = deviceTimeOffset * this.slope
+
+            timestamps[i] = anchor + lslTimeOffset
+        }
+
+        return timestamps
+    }
+
+    private anchorTimeFor(deviceTime: number) {
+        const xMean = this.currentMeanDeviceTime
+        const yMean = this.currentMeanLslTime
+
+        return yMean + this.slope * (deviceTime - xMean)
+    }
+
+    private throwIfDeviceTimeDoesNotIncrease(deviceTime: number) {
+        const last = this.history[this.history.length - 1]
+
+        if (last && deviceTime <= last.deviceTime) {
+            throw new Error(
+                `\nDevice time (${deviceTime}) did not increase from the previous device time (${last.deviceTime})! Device time is expected to always increase between calls, so this likely indicates a bug in the calling code.\n`
+            )
+        }
+    }
+
+    private pruneHistoryOutsideWindow() {
+        const { deviceTime: latest } = this.history[this.history.length - 1]
+        const cutoff = latest - this.windowLenSec
+
+        while (this.history.length > 0 && this.history[0].deviceTime < cutoff) {
+            this.history.shift()
+        }
+    }
+
+    private refitSlope() {
+        if (this.history.length < 2) {
+            return
+        }
+
+        const xMean = this.currentMeanDeviceTime
+        const yMean = this.currentMeanLslTime
+
+        let numerator = 0
+        let denominator = 0
+
+        for (const { deviceTime, earliestLslTime } of this.history) {
+            const xCentered = deviceTime - xMean
+
+            numerator += xCentered * (earliestLslTime - yMean)
+            denominator += xCentered * xCentered
+        }
+
+        this.slope = numerator / denominator
+    }
+
+    private get currentMeanDeviceTime() {
+        const totalDeviceTime = this.history.reduce(
+            (sum, { deviceTime }) => sum + deviceTime,
+            0
+        )
+        return totalDeviceTime / this.history.length
+    }
+
+    private get currentMeanLslTime() {
+        const totalLslTime = this.history.reduce(
+            (sum, { earliestLslTime }) => sum + earliestLslTime,
+            0
+        )
+        return totalLslTime / this.history.length
+    }
+}
+
+export interface ClockRegressor {
+    deriveTimestamps(
+        deviceTime: number,
+        earliestLslTime: number,
+        chunkSize: number
+    ): number[]
+}
+
+export type ClockRegressorConstructor = new (
+    nominalHz: number,
+    options?: WindowedClockRegressorOptions
+) => ClockRegressor
+
+export interface WindowedClockRegressorOptions {
+    windowLenSec?: number
+}