@neurodevs/node-lsl 12.0.6 → 13.0.0

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

@@ -1,7 +1,5 @@
 import { test, assert } from '@neurodevs/node-tdd'
-import LslStreamInlet, {
-    StreamInletOptions,
-} from '../../impl/LslStreamInlet.js'
+import { StreamInletOptions } from '../../impl/LslStreamInlet.js'
 import FakeStreamInfo from '../../testDoubles/StreamInfo/FakeStreamInfo.js'
 import { SpyStreamInlet } from '../../testDoubles/StreamInlet/SpyStreamInlet.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
@@ -9,12 +7,19 @@ import AbstractPackageTest from '../AbstractPackageTest.js'
 export default class LslStreamInletTest extends AbstractPackageTest {
     private static instance: SpyStreamInlet
 
+    private static callsToOnData: {
+        samples: Float32Array
+        timestamps: Float64Array
+    }[]
+
     protected static async beforeEach() {
         await super.beforeEach()
 
         this.setSpyStreamInlet()
         this.setFakeStreamInfo()
 
+        this.callsToOnData = []
+
         this.instance = this.LslStreamInlet()
     }
 
@@ -30,7 +35,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
             {
                 channelNames: this.channelNames,
                 channelFormat: 'float32',
-                sampleRate: 0,
+                sampleRateHz: 0,
                 name: this.name_,
                 type: this.type,
                 sourceId: this.sourceId,
@@ -61,35 +66,263 @@ export default class LslStreamInletTest extends AbstractPackageTest {
             {
                 info: fakeInfo.boundStreamInfo,
                 chunkSize: this.chunkSize,
-                maxBuffered: this.maxBuffered,
+                maxBufferedMs: this.maxBufferedMs / 1000,
             },
             'Should have called createInlet!'
         )
     }
 
     @test()
-    protected static async flushSamplesCallsLslBinding() {
-        this.instance.flushSamples()
+    protected static async flushQueueCallsLslBinding() {
+        this.instance.flushQueue()
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastFlushInletOptions,
-            { inlet: this.instance.getBoundInlet() },
+            { inlet: this.boundInlet },
             'Should have called flushInlet!'
         )
     }
 
-    private static LslStreamInlet(options?: Partial<StreamInletOptions>) {
-        const defaultOptions = {
-            channelNames: this.channelNames,
-            channelFormat: 'float32',
-            sampleRate: 0,
-            name: this.name_,
-            type: this.type,
-            sourceId: this.sourceId,
+    @test()
+    protected static async destroyCallsLslBinding() {
+        this.instance.destroy()
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastDestroyInletOptions,
+            { inlet: this.boundInlet },
+            'Should have called destroyInlet!'
+        )
+    }
+
+    @test()
+    protected static async exposesIsRunningFieldThatIsFalseAtFirst() {
+        assert.isFalse(this.isRunning, 'isRunning should be false at first!')
+    }
+
+    @test()
+    protected static async startPullingSetsIsRunningToTrue() {
+        this.startPulling()
+        await this.wait(10)
+
+        assert.isTrue(this.isRunning, 'isRunning should be true!')
+
+        this.stopPulling()
+    }
+
+    @test()
+    protected static async stopPullingSetsIsRunningToFalse() {
+        await this.startThenStop()
+
+        assert.isFalse(this.isRunning, 'isRunning should be false!')
+    }
+
+    @test()
+    protected static async callsOnDataForChunkSizeNotOne() {
+        await this.startThenStop()
+
+        assert.isEqual(
+            this.callsToOnData.length,
+            2,
+            'Did not call onData as expected!'
+        )
+    }
+
+    @test()
+    protected static async callsOnDataForChunkSizeOne() {
+        await this.runChunkSizeOne()
+
+        assert.isEqual(
+            this.callsToOnData.length,
+            2,
+            'Did not call onData as expected!'
+        )
+    }
+
+    @test()
+    protected static async callsPullSampleIfChunkSizeIsOne() {
+        const inlet = await this.runChunkSizeOne()
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastPullSampleOptions,
+            {
+                inlet: this.boundInlet,
+                dataBufferPtr: inlet['dataBufferPtr'],
+                dataBufferElements: this.channelCount,
+                timeout: 0,
+                errcodePtr: inlet['errorCodeBufferPtr'],
+            },
+            'Should have called pullSample!'
+        )
+    }
+
+    @test()
+    protected static async callsPullChunkIfChunkSizeIsNotOne() {
+        await this.startThenStop()
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastPullChunkOptions,
+            {
+                inlet: this.boundInlet,
+                dataBufferPtr: this.instance['dataBufferPtr'],
+                timestampBufferPtr: this.instance['timestampBufferPtr'],
+                dataBufferElements: this.chunkSize * this.channelCount,
+                timestampBufferElements: this.chunkSize,
+                timeout: 0,
+                errcodePtr: this.instance['errorCodeBufferPtr'],
+            },
+            'Should have called pullChunk!'
+        )
+    }
+
+    @test()
+    protected static async passesTimeoutMsOptionToPullSample() {
+        const timeoutMs = 1000 * Math.random()
+
+        await this.runInletWithOptions({
+            chunkSize: 1,
+            timeoutMs,
+        })
+
+        assert.isEqual(
+            this.fakeLiblsl.lastPullSampleOptions?.timeout,
+            timeoutMs / 1000,
+            'Did not pass timeoutMs to pullSample!'
+        )
+    }
+
+    @test()
+    protected static async passesTimeoutMsOptionToPullChunk() {
+        const timeoutMs = 1000 * Math.random()
+
+        await this.runInletWithOptions({
             chunkSize: this.chunkSize,
-            maxBuffered: this.maxBuffered,
-            ...options,
-        } as StreamInletOptions
-        return LslStreamInlet.Create(defaultOptions) as SpyStreamInlet
+            timeoutMs,
+        })
+
+        assert.isEqual(
+            this.fakeLiblsl.lastPullChunkOptions?.timeout,
+            timeoutMs / 1000,
+            'Did not pass timeoutMs to pullChunk!'
+        )
+    }
+
+    @test()
+    protected static async defaultsMaxBufferedMsToSixMinutesInSeconds() {
+        await this.runInletWithOptions({
+            maxBufferedMs: undefined,
+        })
+
+        const sixMinutesInSeconds = 360
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastCreateInletOptions?.maxBufferedMs,
+            sixMinutesInSeconds
+        )
+    }
+
+    @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
+    ) {
+        await this.startThenStop()
+
+        this.instance['errorCodeBuffer'].writeInt32LE(errorCode)
+
+        assert.doesThrow(() => {
+            this.instance['handleErrorCodeIfPresent']()
+        }, message)
+    }
+
+    private static async runChunkSizeOne() {
+        return await this.runInletWithOptions({
+            chunkSize: 1,
+        })
+    }
+
+    private static async runInletWithOptions(
+        options?: Partial<StreamInletOptions>
+    ) {
+        const inlet = this.LslStreamInlet(options)
+        await this.startThenStop(inlet)
+        return inlet
+    }
+
+    private static async startThenStop(inlet?: SpyStreamInlet) {
+        const instance = inlet || this.instance
+        instance.startPulling()
+        await this.wait(10)
+        instance.stopPulling()
+    }
+
+    private static startPulling() {
+        this.instance.startPulling()
+    }
+
+    private static stopPulling() {
+        this.instance.stopPulling()
+    }
+
+    private static get isRunning() {
+        return this.instance.isRunning
+    }
+
+    private static get boundInlet() {
+        return this.instance.getBoundInlet()
+    }
+
+    private static onData = (
+        samples: Float32Array,
+        timestamps: Float64Array
+    ) => {
+        this.callsToOnData.push({ samples, timestamps })
+    }
+
+    protected static LslStreamInlet(options?: Partial<StreamInletOptions>) {
+        return AbstractPackageTest.LslStreamInlet(
+            {
+                ...options,
+            },
+            this.onData
+        ) as SpyStreamInlet
     }
 }

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

@@ -1,5 +1,6 @@
 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, {
@@ -11,8 +12,8 @@ import {
     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 { ChannelFormat, LslSample } from '../../types.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
 export default class LslStreamOutletTest extends AbstractPackageTest {
@@ -35,14 +36,14 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
     }
 
     @test()
-    protected static async allowsZeroSampleRate() {
-        await this.LslStreamOutlet({ sampleRate: 0 })
+    protected static async allowsZeroSampleRateHz() {
+        await this.LslStreamOutlet({ sampleRateHz: 0 })
     }
 
     @test()
-    protected static async throwsWithInvalidSampleRate() {
-        await this.assertThrowsInvalidSampleRate(-1)
-        await this.assertThrowsInvalidSampleRate(-1.5)
+    protected static async throwsWithInvalidSampleRateHz() {
+        await this.assertThrowsInvalidSampleRateHz(-1)
+        await this.assertThrowsInvalidSampleRateHz(-1.5)
     }
 
     @test()
@@ -65,15 +66,15 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
     }
 
     @test()
-    protected static async allowsZeroMaxBuffered() {
-        await this.LslStreamOutlet({ maxBuffered: 0 })
+    protected static async allowsZeroMaxBufferedMs() {
+        await this.LslStreamOutlet({ maxBufferedMs: 0 })
     }
 
     @test()
-    protected static async throwsWithInvalidMaxBuffered() {
-        await this.assertThrowsInvalidMaxBuffered(-1)
-        await this.assertThrowsInvalidMaxBuffered(-1.5)
-        await this.assertThrowsInvalidMaxBuffered(1.5)
+    protected static async throwsWithInvalidMaxBufferedMs() {
+        await this.assertThrowsInvalidMaxBufferedMs(-1)
+        await this.assertThrowsInvalidMaxBufferedMs(-1.5)
+        await this.assertThrowsInvalidMaxBufferedMs(1.5)
     }
 
     @test()
@@ -115,7 +116,7 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         assert.isEqualDeep(this.fakeLiblsl.lastCreateOutletOptions, {
             info: this.fakeLiblsl.streamInfo,
             chunkSize: this.randomOutletOptions.chunkSize,
-            maxBuffered: this.randomOutletOptions.maxBuffered,
+            maxBufferedMs: this.randomOutletOptions.maxBufferedMs,
         })
         assert.isNumber(
             this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.timestamp
@@ -168,11 +169,11 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         assert.isEqualDeep(FakeStreamInfo.callsToConstructor[0], {
             channelNames: this.randomOutletOptions.channelNames,
             channelFormat: this.randomOutletOptions.channelFormat,
-            sampleRate: this.randomOutletOptions.sampleRate,
+            sampleRateHz: this.randomOutletOptions.sampleRateHz,
             name: this.randomOutletOptions.name,
             type: this.randomOutletOptions.type,
             sourceId: this.randomOutletOptions.sourceId,
-            units: this.randomOutletOptions.unit,
+            units: this.randomOutletOptions.units,
         })
     }
 
@@ -208,7 +209,91 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         await this.LslStreamOutlet({ waitAfterConstructionMs: 10 })
         const endMs = Date.now()
 
-        assert.isAbove(endMs - startMs, 10)
+        assert.isAbove(endMs - startMs, 8)
+    }
+
+    @test()
+    protected static async defaultsMaxBufferedMsToSixMinutesInSeconds() {
+        const outlet = await this.LslStreamOutlet({ maxBufferedMs: undefined })
+
+        assert.isEqualDeep(
+            outlet['maxBufferedMs'],
+            360 * 1000,
+            'Did not set maxBufferedMs as 6 minutes!'
+        )
+    }
+
+    @test()
+    protected static async defaultsManufacturerToNA() {
+        const outlet = await this.LslStreamOutlet({ manufacturer: undefined })
+
+        assert.isEqualDeep(
+            outlet['manufacturer'],
+            'N/A',
+            'Did not set manufacturer as N/A!'
+        )
+    }
+
+    @test()
+    protected static async defaultsUnitsToNA() {
+        const outlet = await this.LslStreamOutlet({ units: undefined })
+        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() {
@@ -219,11 +304,11 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         )
     }
 
-    private static async assertThrowsInvalidSampleRate(sampleRate: number) {
+    private static async assertThrowsInvalidSampleRateHz(sampleRateHz: number) {
         await this.createAndAssertThrows(
-            'sampleRate',
-            sampleRate,
-            `Invalid sample rate! Must be a positive number or zero, not: ${sampleRate}`
+            'sampleRateHz',
+            sampleRateHz,
+            `Invalid sample rate! Must be a positive number or zero, not: ${sampleRateHz}`
         )
     }
 
@@ -237,11 +322,13 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
         )
     }
 
-    private static async assertThrowsInvalidMaxBuffered(maxBuffered: number) {
+    private static async assertThrowsInvalidMaxBufferedMs(
+        maxBufferedMs: number
+    ) {
         await this.createAndAssertThrows(
-            'maxBuffered',
-            maxBuffered,
-            `Invalid max buffered! Must be a positive integer or zero, not: ${maxBuffered}`
+            'maxBufferedMs',
+            maxBufferedMs,
+            `Invalid max buffered! Must be a positive integer or zero, not: ${maxBufferedMs}`
         )
     }
 

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

@@ -1,17 +1,27 @@
+import { randomInt } from 'crypto'
+
 import { test, assert } from '@neurodevs/node-tdd'
 
 import LslWebSocketBridge, {
-    StreamTransportBridge,
+    StreamTransportBridgeOptions,
 } from '../../impl/LslWebSocketBridge.js'
+import FakeStreamInlet from '../../testDoubles/StreamInlet/FakeStreamInlet.js'
+import SpyLslWebSocketBridge from '../../testDoubles/StreamTransportBridge/SpyLslWebSocketBridge.js'
+import FakeWebSocket from '../../testDoubles/WebSockets/FakeWebSocket.js'
+import FakeWebSocketServer from '../../testDoubles/WebSockets/FakeWebSocketServer.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
 export default class LslWebSocketBridgeTest extends AbstractPackageTest {
-    private static instance: StreamTransportBridge
+    private static instance: SpyLslWebSocketBridge
 
     protected static async beforeEach() {
         await super.beforeEach()
 
-        this.instance = this.LslWebSocketBridge()
+        this.setFakeStreamInlet()
+        this.setFakeWebSocketServer()
+        this.setSpyLslWebSocketBridge()
+
+        this.instance = this.LslWebSocketBridge() as SpyLslWebSocketBridge
     }
 
     @test()
@@ -19,7 +29,155 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         assert.isTruthy(this.instance, 'Failed to create instance!')
     }
 
-    private static LslWebSocketBridge() {
-        return LslWebSocketBridge.Create()
+    @test()
+    protected static async createsLslStreamInlet() {
+        const { channelNames, channelFormat, sampleRateHz, chunkSize } =
+            FakeStreamInlet.callsToConstructor[0]?.options ?? {}
+
+        assert.isEqualDeep(
+            {
+                channelNames,
+                channelFormat,
+                sampleRateHz,
+                chunkSize,
+            },
+            this.baseOptions
+        )
+    }
+
+    @test()
+    protected static async activateCallsStartPullingOnInlet() {
+        this.activate()
+
+        assert.isEqual(
+            FakeStreamInlet.numCallsToStartPulling,
+            1,
+            'Did not call startPulling on inlet!'
+        )
+    }
+
+    @test()
+    protected static async deactivateCallsStopPullingOnInlet() {
+        this.activate()
+        this.deactivate()
+
+        assert.isEqual(
+            FakeStreamInlet.numCallsToStopPulling,
+            1,
+            'Did not call stopPulling on inlet!'
+        )
+    }
+
+    @test()
+    protected static async destroyCallsDestroyOnInlet() {
+        this.destroy()
+
+        assert.isEqual(
+            FakeStreamInlet.numCallsToDestroy,
+            1,
+            'Did not call destroy on inlet!'
+        )
+    }
+
+    @test()
+    protected static async createsWebSocketServer() {
+        assert.isEqualDeep(
+            FakeWebSocketServer.callsToConstructor[0],
+            { port: this.wssPort },
+            'Did not create WebSocketServer!'
+        )
+    }
+
+    @test()
+    protected static async activateSendsDataToWebSocketClients() {
+        this.activate()
+
+        const { samples, timestamps } = this.simulateOnDataCallback()
+
+        for (const client of FakeWebSocketServer.clients) {
+            const callToClient = FakeWebSocket.callsToSend.filter(
+                (c) => c.id === client.id
+            )[0]
+
+            assert.isEqualDeep(
+                callToClient?.data,
+                JSON.stringify({
+                    samples,
+                    timestamps,
+                }),
+                'Did not send data to client!'
+            )
+        }
+    }
+
+    @test()
+    protected static async doesNotSendToClientsThatAreNotReady() {
+        for (const client of FakeWebSocketServer.clients) {
+            client.readyState = WebSocket.CONNECTING
+        }
+
+        this.activate()
+        this.simulateOnDataCallback()
+
+        assert.isEqual(
+            FakeWebSocket.callsToSend.length,
+            0,
+            'Sent data to clients that are not ready!'
+        )
+    }
+
+    @test()
+    protected static async destroyClosesWebSocketServer() {
+        this.destroy()
+
+        assert.isEqual(
+            FakeWebSocketServer.numCallsToClose,
+            1,
+            'Did not call close on WebSocketServer!'
+        )
+    }
+
+    @test()
+    protected static async throwsIfActivateIsCalledAfterDestroy() {
+        this.destroy()
+
+        assert.doesThrow(() => {
+            this.activate()
+        }, `\n\n Cannot re-activate bridge after destroying it! \n\n Please create and activate a new instance. \n`)
+    }
+
+    private static activate() {
+        this.instance.activate()
+    }
+
+    private static deactivate() {
+        this.instance.deactivate()
+    }
+
+    private static destroy() {
+        this.instance.destroy()
+    }
+
+    private static simulateOnDataCallback() {
+        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 }
+    }
+
+    private static readonly wssPort = 8080
+
+    private static readonly baseOptions = {
+        channelNames: this.channelNames,
+        channelFormat: 'float32' as const,
+        sampleRateHz: 100 * Math.random(),
+        chunkSize: randomInt(1, 100),
+    }
+
+    private static LslWebSocketBridge(
+        options?: Partial<StreamTransportBridgeOptions>
+    ) {
+        return LslWebSocketBridge.Create({ ...this.baseOptions, ...options })
     }
 }