@neurodevs/node-lsl 18.0.0 → 19.0.0

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

@@ -0,0 +1,535 @@
+import { randomInt } from 'node:crypto'
+
+import { test, assert } from '@neurodevs/node-tdd'
+import { FakeLibndx, NativePeripheral } from '@neurodevs/ndx-native'
+
+import SpyBleController from '../../testDoubles/BleController/SpyBleController.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+import BleDeviceController, {
+    BleControllerOptions,
+} from '../../impl/controllers/BleDeviceController.js'
+
+export default class BleDeviceControllerTest extends AbstractPackageTest {
+    private static instance: SpyBleController
+
+    private static readonly uuid = this.generateId()
+    private static readonly namePrefix = this.generateId()
+    private static readonly discoveredUuid = this.generateId()
+    private static readonly charUuid = this.generateId()
+    private static readonly charValueToWrite = this.generateId()
+    private static readonly rssiIntervalMs = randomInt(1, 5)
+    private static readonly fakeError = this.generateId()
+    private static readonly fake400Error = `400 error: ${this.fakeError}`
+    private static readonly fake500Error = `500 error: ${this.fakeError}`
+
+    private static readonly charCallbacks = [
+        {
+            charUuid: this.generateId(),
+            charName: this.generateId(),
+            onData: async () => {},
+        },
+        {
+            charUuid: this.generateId(),
+            charName: this.generateId(),
+            onData: async () => {},
+        },
+    ]
+
+    private static readonly extraCharCallbacks = [
+        {
+            charUuid: this.generateId(),
+            charName: this.generateId(),
+            onData: async () => {},
+        },
+    ]
+
+    private static onConnected = (_peripheral: NativePeripheral) => {
+        this.wasConnected = true
+    }
+
+    private static wasConnected: boolean
+
+    private static nativePeripheral: NativePeripheral = {
+        uuid: this.generateId(),
+        name: this.generateId(),
+    }
+
+    protected static async beforeAll() {
+        assert.isEqual(
+            BleDeviceController.waitAfterMs,
+            1000,
+            'Set incorrect waitAfterMs!'
+        )
+    }
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        BleDeviceController.waitAfterMs = 0
+        BleDeviceController.Class = SpyBleController
+
+        this.wasConnected = false
+
+        this.instance = await this.BleController()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async connectCallsLibndxCreateBleBackend() {
+        await this.connect()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToCreateBleBackend[0],
+            {
+                deviceUuid: this.uuid,
+            },
+            'Did not call createBleBackend!'
+        )
+    }
+
+    @test()
+    protected static async discoversUuidWhenDeviceUuidNotProvided() {
+        const instance = await this.BleControllerWithPrefix()
+
+        await this.connectWithDiscovery(instance)
+
+        const call = FakeLibndx.callsToDiscoverBleUuid[0]
+
+        assert.isEqual(
+            call?.namePrefix,
+            this.namePrefix,
+            'Did not call discoverBleUuid with deviceNamePrefix!'
+        )
+
+        assert.isFunction(
+            call?.onDiscovered,
+            'Did not pass an onDiscovered callback to discoverBleUuid!'
+        )
+    }
+
+    @test()
+    protected static async doesNotDiscoverUuidWhenDeviceUuidProvided() {
+        await this.connect()
+
+        assert.isEqual(
+            FakeLibndx.callsToDiscoverBleUuid.length,
+            0,
+            'Should not call discoverBleUuid when deviceUuid is provided!'
+        )
+    }
+
+    @test()
+    protected static async usesDiscoveredUuidToCreateBleBackend() {
+        const instance = await this.BleControllerWithPrefix()
+
+        await this.connectWithDiscovery(instance)
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToCreateBleBackend[0],
+            {
+                deviceUuid: this.discoveredUuid,
+            },
+            'Did not create BLE backend with the discovered uuid!'
+        )
+    }
+
+    @test()
+    protected static async usesDiscoveredUuidToStartBleBackend() {
+        const instance = await this.BleControllerWithPrefix()
+
+        await this.connectWithDiscovery(instance)
+
+        assert.isEqual(
+            FakeLibndx.callsToStartBleBackend[0]?.deviceUuid,
+            this.discoveredUuid,
+            'Did not start BLE backend with the discovered uuid!'
+        )
+    }
+
+    @test()
+    protected static async exposesDiscoveredUuid() {
+        const instance = await this.BleControllerWithPrefix()
+
+        await this.connectWithDiscovery(instance)
+
+        assert.isEqual(
+            instance.uuid,
+            this.discoveredUuid,
+            'Did not expose the discovered uuid!'
+        )
+    }
+
+    @test()
+    protected static async createBleBackendThrowsOn400() {
+        this.setFake400Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.instance.connect(),
+            this.fake400Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async createBleBackendThrowsOn500() {
+        this.setFake500Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.instance.connect(),
+            this.fake500Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async connectCallsLibndxStartBleBackend() {
+        await this.connect()
+
+        const call = FakeLibndx.callsToStartBleBackend[0]
+
+        assert.isEqual(
+            call.deviceUuid,
+            this.uuid,
+            'Did not call startBleBackend with correct deviceUuid!'
+        )
+
+        assert.isEqual(
+            call.charCallbacks.length,
+            2,
+            'Did not call startBleBackend with charCallbacks!'
+        )
+
+        let i = 0
+        for (const charCallback of call.charCallbacks) {
+            assert.isEqual(
+                charCallback.charUuid,
+                this.charCallbacks[i].charUuid,
+                'Incorrect charUuid!'
+            )
+
+            assert.isEqual(
+                charCallback.charName,
+                this.charCallbacks[i].charName,
+                'Incorrect charName!'
+            )
+
+            assert.isFunction(
+                charCallback.onData,
+                'Callback is not a function!'
+            )
+            i++
+        }
+    }
+
+    @test()
+    protected static async startBleBackendThrowsOn400() {
+        //@ts-ignore
+        this.instance.createBleBackend = () => {}
+
+        this.setFake400Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.instance.connect(),
+            this.fake400Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async startBleBackendThrowsOn500() {
+        //@ts-ignore
+        this.instance.createBleBackend = () => {}
+
+        this.setFake500Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.instance.connect(),
+            this.fake500Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async connectWaitsForOnConnectedEvent() {
+        await this.connect()
+
+        assert.isTruthy(
+            this.wasConnected,
+            'Did not wait for onConnected event!'
+        )
+    }
+
+    @test()
+    protected static async waitsAfterOnConnectedToDiscoverServices() {
+        const waitAfterMs = 20
+        BleDeviceController.waitAfterMs = waitAfterMs
+
+        await this.connect()
+
+        assert.isTruthy(
+            this.callsToSetTimeout.includes(waitAfterMs),
+            'Did not wait after on connected!'
+        )
+    }
+
+    @test()
+    protected static async writeCharacteristicCallsLibndxBinding() {
+        await this.writeCharacteristic()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToWriteBleCharacteristic[0],
+            {
+                deviceUuid: this.uuid,
+                charUuid: this.charUuid,
+                value: this.charValueToWrite,
+            },
+            'Did not call writeBleCharacteristic as expected!'
+        )
+    }
+
+    @test()
+    protected static async writeCharacteristicThrowsOn400() {
+        this.setFake400Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.writeCharacteristic(),
+            this.fake400Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async writeCharacteristicThrowsOn500() {
+        this.setFake500Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.writeCharacteristic(),
+            this.fake500Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async subscribeCharacteristicsCallsLibndxBinding() {
+        await this.subscribeCharacteristics()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToAddBleCharCallbacks[0],
+            {
+                deviceUuid: this.uuid,
+                charCallbacks: this.extraCharCallbacks,
+            },
+            'Did not call addBleCharCallbacks as expected!'
+        )
+    }
+
+    @test()
+    protected static async subscribeCharacteristicsMergesIntoCharCallbacks() {
+        await this.subscribeCharacteristics()
+
+        assert.isEqualDeep(
+            this.instance.getCharacteristicCallbacks(),
+            [...this.charCallbacks, ...this.extraCharCallbacks],
+            'Did not merge the newly subscribed callbacks into charCallbacks!'
+        )
+    }
+
+    @test()
+    protected static async subscribeCharacteristicsThrowsOn400() {
+        this.setFake400Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.subscribeCharacteristics(),
+            this.fake400Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async callsSetBleRssiInterval() {
+        await this.connect()
+
+        const { deviceUuid, intervalMs } =
+            FakeLibndx.callsToSetBleRssiInterval[0]
+
+        assert.isEqualDeep(
+            { deviceUuid, intervalMs },
+            {
+                deviceUuid: this.uuid,
+                intervalMs: this.rssiIntervalMs,
+            },
+            'Did not call setBleRssiInterval as expected!'
+        )
+    }
+
+    @test()
+    protected static async disconnectCallsLibndxStopBleBackend() {
+        await this.disconnect()
+
+        assert.isEqualDeep(
+            FakeLibndx.callsToStopBleBackend[0],
+            {
+                deviceUuid: this.uuid,
+            },
+            'Did not call stopBleBackend!'
+        )
+    }
+
+    @test()
+    protected static async disconnectThrowsOn400() {
+        this.setFake400Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.disconnect(),
+            this.fake400Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async disconnectThrowsOn500() {
+        this.setFake500Error()
+
+        await assert.doesThrowAsync(
+            async () => await this.disconnect(),
+            this.fake500Error,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async disconnectResetsConnectedFlag() {
+        await this.connect()
+        await this.disconnect()
+
+        assert.isFalse(
+            this.instance.getConnected(),
+            'Did not reset connected flag on disconnect!'
+        )
+    }
+
+    @test()
+    protected static async exposesPeriperalName() {
+        await this.connect()
+
+        assert.isEqual(
+            this.instance.name,
+            this.nativePeripheral.name,
+            'Did not set peripheral name!'
+        )
+    }
+
+    @test()
+    protected static async returnsNAIfNameNotAvailable() {
+        assert.isEqual(
+            this.instance.name,
+            'N/A',
+            'Did not set default name to N/A!'
+        )
+    }
+
+    @test()
+    protected static async throwsWithUnknownErrorIfNoError() {
+        this.setFake500ErrorWithoutError()
+
+        await assert.doesThrowAsync(
+            async () => await this.connect(),
+            'Unknown error',
+            'Did not throw error!'
+        )
+    }
+
+    private static async connect() {
+        const promise = this.instance.connect()
+
+        const startCall = FakeLibndx.callsToStartBleBackend[0]
+        startCall?.onConnected(this.nativePeripheral)
+
+        await promise
+    }
+
+    private static async connectWithDiscovery(instance: SpyBleController) {
+        const promise = instance.connect()
+
+        FakeLibndx.callsToDiscoverBleUuid[0]?.onDiscovered(this.discoveredUuid)
+
+        await this.waitForCall(() => FakeLibndx.callsToStartBleBackend[0])
+
+        FakeLibndx.callsToStartBleBackend[0]?.onConnected(this.nativePeripheral)
+
+        await promise
+    }
+
+    private static async waitForCall<T>(getCall: () => T) {
+        await new Promise<void>((resolve) => {
+            const check = () => {
+                if (getCall()) {
+                    resolve()
+                } else {
+                    setTimeout(check, 0)
+                }
+            }
+            check()
+        })
+    }
+
+    private static async writeCharacteristic() {
+        await this.instance.writeCharacteristic(
+            this.charUuid,
+            this.charValueToWrite
+        )
+    }
+
+    private static async subscribeCharacteristics() {
+        await this.instance.subscribeCharacteristics(this.extraCharCallbacks)
+    }
+
+    private static async disconnect() {
+        await this.instance.disconnect()
+    }
+
+    private static setFake400Error() {
+        FakeLibndx.fakeResult = {
+            status: 400,
+            error: this.fakeError,
+        }
+    }
+
+    private static setFake500Error() {
+        FakeLibndx.fakeResult = {
+            status: 500,
+            error: this.fakeError,
+        }
+    }
+
+    private static setFake500ErrorWithoutError() {
+        FakeLibndx.fakeResult = {
+            status: 500,
+        }
+    }
+
+    private static async BleController(
+        options?: Partial<BleControllerOptions>
+    ) {
+        return (await BleDeviceController.Create({
+            deviceUuid: this.uuid,
+            charCallbacks: this.charCallbacks,
+            onConnected: this.onConnected,
+            rssiIntervalMs: this.rssiIntervalMs,
+            ...options,
+        })) as SpyBleController
+    }
+
+    private static async BleControllerWithPrefix() {
+        return (await BleDeviceController.Create({
+            deviceNamePrefix: this.namePrefix,
+            charCallbacks: this.charCallbacks,
+            onConnected: this.onConnected,
+            rssiIntervalMs: this.rssiIntervalMs,
+        } as unknown as BleControllerOptions)) as SpyBleController
+    }
+}

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

@@ -1,4 +1,5 @@
-import { randomInt } from 'crypto'
+import { randomInt } from 'node:crypto'
+
 import { assert, test } from '@neurodevs/node-tdd'
 
 import LslEventMarkerEmitter, {

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

@@ -386,7 +386,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
     protected static async pushSampleHandlesErrorCode() {
         let passedErrorCode: number | undefined
 
-        StreamInletWorker.handleError = (errorCode: number) => {
+        StreamInletWorker.handleLslError = (errorCode: number) => {
             passedErrorCode = errorCode
         }
 
@@ -400,7 +400,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         assert.isEqualDeep(
             passedErrorCode,
             FakeLiblsl.fakeErrorCode,
-            'Did not pass the expected error code to handleError!'
+            'Did not pass the expected error code to handleLslError!'
         )
     }
 

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

@@ -7,7 +7,7 @@ import LslStreamOutlet, {
     StreamOutletOptions,
 } from '../../impl/LslStreamOutlet.js'
 import {
-    setOutletHandleError,
+    setOutletHandleLslError,
     setOutletLiblslAdapter,
 } from '../../impl/workers/outlet/LslStreamOutlet.worker.js'
 import {
@@ -128,7 +128,7 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
             maxBufferedMs: this.randomOutletOptions.maxBufferedMs,
         })
         assert.isNumber(
-            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.timestamp
+            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.timestampSec
         )
     }
 
@@ -148,7 +148,7 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
             sample
         )
         assert.isNumber(
-            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.timestamp
+            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.timestampSec
         )
     }
 
@@ -159,13 +159,13 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
 
         outlet.pushSample(sample)
         const t1 =
-            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.timestamp
+            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.timestampSec
 
         await this.wait(10)
 
         outlet.pushSample(sample)
         const t2 =
-            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.timestamp
+            this.fakeLiblsl.lastPushSampleStringTimestampOptions?.timestampSec
 
         assert.isNotEqual(t1, t2)
         assert.isEqual(this.fakeLiblsl.localClockHitCount, 2)
@@ -227,13 +227,13 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
     @test()
     protected static async pushSampleAcceptsOptionalPreciseTimestamp() {
         const outlet = await this.FloatOutlet()
-        const fakeTimestamp = Math.random() * 1000
+        const timestampSec = Math.random() * 10000
 
-        outlet.pushSample([1.0], fakeTimestamp)
+        outlet.pushSample([1.0], timestampSec)
 
         assert.isEqual(
-            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.timestamp,
-            fakeTimestamp
+            this.fakeLiblsl.lastPushSampleFloatTimestampOptions?.timestampSec,
+            timestampSec
         )
     }
 
@@ -241,7 +241,7 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
     protected static async pushSampleHandlesErrorCode() {
         let passedErrorCode: number | undefined
 
-        setOutletHandleError((errorCode: number) => {
+        setOutletHandleLslError((errorCode: number) => {
             passedErrorCode = errorCode
         })
 
@@ -265,11 +265,12 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
 
     @test()
     protected static async waitsForTenMsAfterConstructionBeforeReturning() {
-        const startMs = Date.now()
-        await this.LslStreamOutlet({ waitAfterConstructionMs: 10 })
-        const endMs = Date.now()
+        await this.LslStreamOutlet()
 
-        assert.isAbove(endMs - startMs, 8)
+        assert.isTruthy(
+            this.callsToSetTimeout.includes(10),
+            'Did not wait for 10ms after construction!'
+        )
     }
 
     @test()

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

@@ -1,4 +1,5 @@
-import { randomInt } from 'crypto'
+import { randomInt } from 'node:crypto'
+
 import { test, assert } from '@neurodevs/node-tdd'
 
 import { StreamInletOptions } from '../../impl/LslStreamInlet.js'
@@ -152,7 +153,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
         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`)
+        }, `\n\nCannot activate bridge after destroying it! \n\nPlease create and activate a new instance. \n`)
     }
 
     @test()
@@ -161,7 +162,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
         assert.doesThrow(() => {
             this.deactivate()
-        }, `\n\n Cannot deactivate bridge after destroying it! \n\n Please create and activate a new instance. \n`)
+        }, `\n\nCannot deactivate bridge after destroying it! \n\nPlease create and activate a new instance. \n`)
     }
 
     @test()