@neurodevs/node-lsl 17.1.0 → 18.0.0

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

@@ -1,19 +1,23 @@
+import { Worker } from 'node:worker_threads'
+import { ChannelFormat, LslSample, FakeLiblsl } from '@neurodevs/ndx-native'
 import { test, assert } from '@neurodevs/node-tdd'
 
-import { ChannelFormat, LslSample } from 'impl/LiblslAdapter.js'
 import { CHANNEL_FORMATS } from '../../consts.js'
-import { StreamInfo } from '../../impl/LslStreamInfo.js'
 import LslStreamOutlet, {
     StreamOutletOptions,
 } from '../../impl/LslStreamOutlet.js'
+import {
+    setOutletHandleError,
+    setOutletLiblslAdapter,
+} from '../../impl/workers/outlet/LslStreamOutlet.worker.js'
 import {
     TEST_SUPPORTED_CHANNEL_FORMATS,
     TEST_UNSUPPORTED_CHANNEL_FORMATS,
     TestChannelFormat,
 } from '../../testDoubles/consts.js'
 import generateRandomOutletOptions from '../../testDoubles/generateRandomOutletOptions.js'
-import FakeLiblsl from '../../testDoubles/Liblsl/FakeLiblsl.js'
 import FakeStreamInfo from '../../testDoubles/StreamInfo/FakeStreamInfo.js'
+import FakeWorker from '../../testDoubles/WorkerThreads/FakeWorker.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
 export default class LslStreamOutletTest extends AbstractPackageTest {
@@ -28,6 +32,11 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
 
         this.setFakeLiblsl()
         this.setFakeStreamInfo()
+
+        LslStreamOutlet.Worker = FakeWorker as unknown as typeof Worker
+        FakeWorker.resetTestDoubles()
+
+        setOutletLiblslAdapter(this.fakeLiblsl)
     }
 
     @test()
@@ -106,15 +115,15 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         outlet.pushSample(sample)
 
         assert.isEqual(
-            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.outlet,
-            this.fakeLiblsl.outlet
+            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.outletHandle,
+            this.fakeLiblsl.outletHandle
         )
         assert.isEqualDeep(
             this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.sample,
             sample
         )
         assert.isEqualDeep(this.fakeLiblsl.lastCreateOutletOptions, {
-            info: this.fakeLiblsl.streamInfo,
+            infoHandle: this.fakeLiblsl.infoHandle,
             chunkSize: this.randomOutletOptions.chunkSize,
             maxBufferedMs: this.randomOutletOptions.maxBufferedMs,
         })
@@ -131,8 +140,8 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         outlet.pushSample(sample)
 
         assert.isEqual(
-            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.outlet,
-            this.fakeLiblsl.outlet
+            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.outletHandle,
+            this.fakeLiblsl.outletHandle
         )
         assert.isEqualDeep(
             this.fakeLiblsl.lastPushSampleStringTimestampOptions?.sample,
@@ -199,9 +208,9 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         outlet.destroy()
 
         assert.isEqualDeep(
-            this.fakeLiblsl.lastDestroyStreamInfoOptions,
-            { info: this.fakeLiblsl.streamInfo },
-            'Did not call destroyStreamInfo on destroy!'
+            this.fakeLiblsl.lastDestroyOutletOptions,
+            { outletHandle: this.fakeLiblsl.outletHandle },
+            'Did not call destroy on outlet!'
         )
     }
 
@@ -215,6 +224,45 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         assert.isEqual(this.fakeLiblsl.createOutletHitCount, 1)
     }
 
+    @test()
+    protected static async pushSampleAcceptsOptionalPreciseTimestamp() {
+        const outlet = await this.FloatOutlet()
+        const fakeTimestamp = Math.random() * 1000
+
+        outlet.pushSample([1.0], fakeTimestamp)
+
+        assert.isEqual(
+            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.timestamp,
+            fakeTimestamp
+        )
+    }
+
+    @test()
+    protected static async pushSampleHandlesErrorCode() {
+        let passedErrorCode: number | undefined
+
+        setOutletHandleError((errorCode: number) => {
+            passedErrorCode = errorCode
+        })
+
+        FakeLiblsl.fakeErrorCode = [-4, -3, -2, -1, 0][
+            Math.floor(Math.random() * 5)
+        ]
+
+        const outlet =
+            Math.random() > 0.5
+                ? await this.FloatOutlet()
+                : await this.StringOutlet()
+
+        outlet.pushSample([1.0])
+
+        assert.isEqualDeep(
+            passedErrorCode,
+            FakeLiblsl.fakeErrorCode,
+            'Did not pass the expected error code to handleError!'
+        )
+    }
+
     @test()
     protected static async waitsForTenMsAfterConstructionBeforeReturning() {
         const startMs = Date.now()
@@ -252,62 +300,6 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         assert.isEqualDeep(outlet['units'], 'N/A', 'Did not set units as N/A!')
     }
 
-    @test()
-    protected static async throwsWithUnknownErrorCode() {
-        await this.assertThrowsWithErrorCode(
-            -999,
-            `An unknown liblsl error has occurred!`
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeOne() {
-        await this.assertThrowsWithErrorCode(
-            -1,
-            `The liblsl operation failed due to a timeout!`
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeTwo() {
-        await this.assertThrowsWithErrorCode(
-            -2,
-            `The liblsl stream has been lost!`
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeThree() {
-        await this.assertThrowsWithErrorCode(
-            -3,
-            'A liblsl argument was incorrectly specified!'
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeFour() {
-        await this.assertThrowsWithErrorCode(
-            -4,
-            'An internal liblsl error has occurred!'
-        )
-    }
-
-    private static async assertThrowsWithErrorCode(
-        errorCode: number,
-        message: string
-    ) {
-        FakeLiblsl.fakeErrorCode = errorCode
-
-        const outlet =
-            Math.random() > 0.5
-                ? await this.FloatOutlet()
-                : await this.StringOutlet()
-
-        assert.doesThrow(() => {
-            outlet.pushSample([1.0])
-        }, message)
-    }
-
     private static async assertThrowsWithEmptyChannelNames() {
         await this.createAndAssertThrows(
             'channelNames',
@@ -386,7 +378,7 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
 }
 
 class CheckingOutlet extends LslStreamOutlet {
-    public constructor(info: StreamInfo, options: StreamOutletOptions) {
-        super(info, options)
+    public constructor(options: StreamOutletOptions) {
+        super(options)
     }
 }

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

@@ -1,10 +1,10 @@
 import { randomInt } from 'crypto'
 import { test, assert } from '@neurodevs/node-tdd'
 
+import { StreamInletOptions } from '../../impl/LslStreamInlet.js'
 import LslWebSocketBridge, {
     WebSocketBridgeOptions,
 } from '../../impl/LslWebSocketBridge.js'
-import FakeStreamInfo from '../../testDoubles/StreamInfo/FakeStreamInfo.js'
 import FakeStreamInlet from '../../testDoubles/StreamInlet/FakeStreamInlet.js'
 import SpyLslWebSocketBridge from '../../testDoubles/WebSocketBridge/SpyLslWebSocketBridge.js'
 import FakeWebSocket from '../../testDoubles/WebSockets/FakeWebSocket.js'
@@ -36,12 +36,12 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
     protected static async createsLslStreamInlet() {
         const call = FakeStreamInlet.callsToConstructor[0]
 
-        const info = call?.info
-        const chunkSize = call?.options?.chunkSize
+        const sourceId = call.options!.sourceId
+        const chunkSize = call.options!.chunkSize
 
         assert.isEqualDeep(
             {
-                info,
+                sourceId,
                 chunkSize,
             },
             this.inletOptions
@@ -50,7 +50,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     @test()
     protected static async activateCallsStartPullingOnInlet() {
-        this.activate()
+        await this.activate()
 
         assert.isEqual(
             FakeStreamInlet.numCallsToStartPulling,
@@ -61,7 +61,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     @test()
     protected static async deactivateCallsStopPullingOnInlet() {
-        this.activate()
+        await this.activate()
         this.deactivate()
 
         assert.isEqual(
@@ -93,7 +93,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     @test()
     protected static async activateSendsDataToWebSocketClients() {
-        this.activate()
+        await this.activate()
 
         const { samples, timestamps } = this.simulateOnDataCallback()
 
@@ -119,7 +119,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
             client.readyState = WebSocket.CONNECTING
         }
 
-        this.activate()
+        await this.activate()
         this.simulateOnDataCallback()
 
         const calls = FakeWebSocket.callsToSend.filter((call) =>
@@ -150,8 +150,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
     protected static async throwsIfActivateIsCalledAfterDestroy() {
         this.destroy()
 
-        assert.doesThrow(() => {
-            this.activate()
+        await assert.doesThrowAsync(async () => {
+            await this.activate()
         }, `\n\n Cannot activate bridge after destroying it! \n\n Please create and activate a new instance. \n`)
     }
 
@@ -184,7 +184,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     @test()
     protected static async activateSendsDataToRemoteSockets() {
-        this.activate()
+        await this.activate()
 
         const { samples, timestamps } = this.simulateOnDataCallback()
 
@@ -218,7 +218,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
             socket.readyState = WebSocket.CONNECTING
         }
 
-        this.activate()
+        await this.activate()
         this.simulateOnDataCallback()
 
         const calls = FakeWebSocket.callsToSend.filter((call) =>
@@ -253,8 +253,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         }, `At least one of listenPort or connectUrls must be provided!`)
     }
 
-    private static activate() {
-        this.instance.activate()
+    private static async activate() {
+        await this.instance.activate()
     }
 
     private static deactivate() {
@@ -266,8 +266,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
     }
 
     private static simulateOnDataCallback() {
-        const samples = new Float32Array([1, 2, 3, 4, 5, 6])
-        const timestamps = new Float64Array([7, 8])
+        const samples = [...new Float32Array([1, 2, 3, 4, 5, 6])]
+        const timestamps = [...new Float64Array([7, 8])]
 
         FakeStreamInlet.callsToConstructor[0]?.onData!(samples, timestamps)
         return { samples, timestamps }
@@ -277,8 +277,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     private static readonly connectUrls = [this.generateId(), this.generateId()]
 
-    private static readonly inletOptions = {
-        info: new FakeStreamInfo(),
+    private static readonly inletOptions: StreamInletOptions = {
+        sourceId: this.sourceId,
         chunkSize: randomInt(1, 100),
     }
 

package/src/assertions.ts

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

package/src/impl/LslBackpressureMonitor.ts

@@ -0,0 +1,13 @@
+export default class LslBackpressureMonitor implements BackpressureMonitor {
+    public static Class?: BackpressureMonitorConstructor
+
+    protected constructor() {}
+
+    public static Create() {
+        return new (this.Class ?? this)()
+    }
+}
+
+export interface BackpressureMonitor {}
+
+export type BackpressureMonitorConstructor = new () => BackpressureMonitor

package/src/impl/LslEventMarkerEmitter.ts

@@ -0,0 +1,133 @@
+import { generateShortId } from '@neurodevs/generate-id'
+
+import LslStreamOutlet, {
+    StreamOutletOptions,
+    StreamOutlet,
+} from './LslStreamOutlet.js'
+
+export default class LslEventMarkerEmitter implements EventMarkerEmitter {
+    public static Class?: EventMarkerEmitterConstructor
+
+    protected outlet: StreamOutlet
+    private isRunning = false
+    private waitResolve?: () => void
+    private timeout?: any
+
+    protected constructor(outlet: StreamOutlet) {
+        this.outlet = outlet
+    }
+
+    public static async Create(options?: EventMarkerEmitterOptions) {
+        const outlet = await this.LslStreamOutlet(options)
+        return new (this.Class ?? this)(outlet)
+    }
+
+    public async emit(markerName: string, options?: EventMarkerOptions) {
+        this.throwIfAlreadyRunning('emit')
+        this.isRunning = true
+
+        const { waitAfterMs } = options || {}
+
+        this.pushMarkerToOutlet(markerName)
+
+        if (waitAfterMs) {
+            await this.wait(waitAfterMs)
+        }
+        this.isRunning = false
+    }
+
+    private throwIfAlreadyRunning(methodName: string) {
+        if (this.isRunning) {
+            throw new Error(`Cannot call ${methodName} while already running!`)
+        }
+    }
+
+    public async emitMany(markers: TimedEventMarker[]) {
+        this.throwIfAlreadyRunning('emitMany')
+        this.isRunning = true
+
+        for (const marker of markers) {
+            const { name, waitAfterMs } = marker
+            this.pushMarkerToOutlet(name)
+
+            await this.wait(waitAfterMs)
+
+            if (!this.isRunning) {
+                return
+            }
+        }
+        this.isRunning = false
+    }
+
+    private pushMarkerToOutlet(markerName: string) {
+        this.outlet.pushSample([markerName])
+    }
+
+    protected async wait(forMs: number) {
+        return new Promise((resolve) => this.setTimeout(resolve, forMs))
+    }
+
+    private setTimeout(resolve: (value: unknown) => void, waitAfterMs: number) {
+        this.waitResolve = resolve as any
+        this.timeout = setTimeout(resolve, waitAfterMs)
+    }
+
+    public interrupt() {
+        this.waitResolve?.()
+        clearTimeout(this.timeout)
+        this.isRunning = false
+    }
+
+    public destroy() {
+        if (this.isRunning) {
+            this.interrupt()
+        }
+        this.outlet.destroy()
+    }
+
+    private static generateDefaultOutletOptions() {
+        const uniqueId = generateShortId()
+
+        const name = `Event markers (${uniqueId})`
+        const sourceId = `event-markers-${uniqueId}`
+
+        return {
+            name,
+            type: 'Markers',
+            sourceId,
+            channelNames: ['Markers'],
+            channelFormat: 'string',
+            sampleRateHz: 0,
+            chunkSize: 1,
+        } as StreamOutletOptions
+    }
+
+    private static LslStreamOutlet(options?: Partial<StreamOutletOptions>) {
+        return LslStreamOutlet.Create({
+            ...this.generateDefaultOutletOptions(),
+            ...options,
+        })
+    }
+}
+
+export interface EventMarkerEmitter {
+    emit(markerName: string, options?: EventMarkerOptions): Promise<void>
+    emitMany(markers: TimedEventMarker[]): Promise<void>
+    interrupt(): void
+    destroy(): void
+}
+
+export type EventMarkerEmitterOptions = Partial<StreamOutletOptions>
+
+export type EventMarkerEmitterConstructor = new (
+    outlet: StreamOutlet
+) => EventMarkerEmitter
+
+export interface EventMarkerOptions {
+    waitAfterMs?: number
+}
+
+export interface TimedEventMarker {
+    name: string
+    waitAfterMs: number
+}

package/src/impl/LslStreamInfo.ts

@@ -1,14 +1,14 @@
 import generateId from '@neurodevs/generate-id'
-
-import { CHANNEL_FORMATS_MAP } from '../consts.js'
-import { BoundStreamInfo, ChannelFormat } from './LiblslAdapter.js'
-import LiblslAdapter from './LiblslAdapter.js'
+import {
+    ChannelFormat,
+    InfoHandle,
+    LiblslAdapter,
+    CHANNEL_FORMATS_MAP,
+} from '@neurodevs/ndx-native'
 
 export default class LslStreamInfo implements StreamInfo {
     public static Class?: StreamInfoConstructor
 
-    private static instanceCache = new Map<BoundStreamInfo, StreamInfo>()
-
     public readonly name: string
     public readonly type: string
     public readonly sourceId: string
@@ -17,7 +17,8 @@ export default class LslStreamInfo implements StreamInfo {
     public readonly channelFormat: ChannelFormat
     public readonly sampleRateHz: number
     public readonly units: string
-    public readonly boundInfo: BoundStreamInfo
+
+    public readonly infoHandle: InfoHandle
 
     private lsl = LiblslAdapter.getInstance()
 
@@ -30,7 +31,6 @@ export default class LslStreamInfo implements StreamInfo {
             channelFormat,
             sampleRateHz,
             units = 'N/A',
-            boundInfo,
         } = options
 
         this.name = name
@@ -42,25 +42,12 @@ export default class LslStreamInfo implements StreamInfo {
         this.sampleRateHz = sampleRateHz
         this.units = units
 
-        if (!boundInfo) {
-            this.boundInfo = this.createStreamInfo()
-            this.appendChannelsToStreamInfo()
-        } else {
-            this.boundInfo = boundInfo
-        }
+        this.infoHandle = this.createStreamInfo()
+        this.appendChannelsToStreamInfo()
     }
 
     public static Create(options: StreamInfoOptions) {
-        const instance = new (this.Class ?? this)(options)
-
-        const { boundInfo: handle } = instance
-        this.instanceCache.set(handle, instance)
-
-        return instance
-    }
-
-    public static From(handle: BoundStreamInfo) {
-        return this.instanceCache.get(handle)!
+        return new (this.Class ?? this)(options)
     }
 
     private createStreamInfo() {
@@ -80,7 +67,7 @@ export default class LslStreamInfo implements StreamInfo {
 
     private appendChannelsToStreamInfo() {
         this.lsl.appendChannelsToStreamInfo({
-            info: this.boundInfo,
+            infoHandle: this.infoHandle,
             channels: this.channelNames.map((label: string) => ({
                 label,
                 units: this.units,
@@ -90,7 +77,7 @@ export default class LslStreamInfo implements StreamInfo {
     }
 
     public destroy() {
-        this.lsl.destroyStreamInfo({ info: this.boundInfo })
+        this.lsl.destroyStreamInfo({ infoHandle: this.infoHandle })
     }
 }
 
@@ -104,10 +91,12 @@ export interface StreamInfo {
     readonly channelCount: number
     readonly channelFormat: ChannelFormat
     readonly sampleRateHz: number
-    readonly boundInfo: BoundStreamInfo
+    readonly infoHandle: InfoHandle
 }
 
-type StreamInfoConstructor = new (options: StreamInfoOptions) => StreamInfo
+export type StreamInfoConstructor = new (
+    options: StreamInfoOptions
+) => StreamInfo
 
 export interface StreamInfoOptions {
     channelNames: string[]
@@ -117,5 +106,4 @@ export interface StreamInfoOptions {
     type?: string
     sourceId?: string
     units?: string
-    boundInfo?: BoundStreamInfo
 }