@neurodevs/node-lsl 20.0.0 → 22.1.0

package/src/__tests__/impl/{BleDeviceController.test.ts → BleGattController.test.ts}

@@ -3,14 +3,14 @@ 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 SpyBleGatt from '../../testDoubles/BleGatt/SpyBleGatt.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
-import BleDeviceController, {
-    BleControllerOptions,
-} from '../../impl/controllers/BleDeviceController.js'
+import BleGattController, {
+    BleGattOptions,
+} from '../../impl/controllers/BleGattController.js'
 
-export default class BleDeviceControllerTest extends AbstractPackageTest {
-    private static instance: SpyBleController
+export default class BleGattControllerTest extends AbstractPackageTest {
+    private static instance: SpyBleGatt
 
     private static readonly uuid = this.generateId()
     private static readonly namePrefix = this.generateId()
@@ -56,7 +56,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
 
     protected static async beforeAll() {
         assert.isEqual(
-            BleDeviceController.waitAfterMs,
+            BleGattController.waitAfterMs,
             1000,
             'Set incorrect waitAfterMs!'
         )
@@ -65,12 +65,12 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
     protected static async beforeEach() {
         await super.beforeEach()
 
-        BleDeviceController.waitAfterMs = 0
-        BleDeviceController.Class = SpyBleController
+        BleGattController.waitAfterMs = 0
+        BleGattController.Class = SpyBleGatt
 
         this.wasConnected = false
 
-        this.instance = this.BleDeviceController()
+        this.instance = this.BleGattController()
     }
 
     @test()
@@ -83,17 +83,17 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
         await this.connect()
 
         assert.isEqualDeep(
-            FakeLibndx.callsToCreateBleBackend[0],
+            FakeLibndx.callsToCreateBleGattBackend[0],
             {
                 deviceUuid: this.uuid,
             },
-            'Did not call createBleBackend!'
+            'Did not call createBleGattBackend!'
         )
     }
 
     @test()
     protected static async discoversUuidWhenDeviceUuidNotProvided() {
-        const instance = await this.BleControllerWithPrefix()
+        const instance = await this.BleGattControllerWithPrefix()
 
         await this.connectWithDiscovery(instance)
 
@@ -124,12 +124,12 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
 
     @test()
     protected static async usesDiscoveredUuidToCreateBleBackend() {
-        const instance = await this.BleControllerWithPrefix()
+        const instance = await this.BleGattControllerWithPrefix()
 
         await this.connectWithDiscovery(instance)
 
         assert.isEqualDeep(
-            FakeLibndx.callsToCreateBleBackend[0],
+            FakeLibndx.callsToCreateBleGattBackend[0],
             {
                 deviceUuid: this.discoveredUuid,
             },
@@ -139,12 +139,12 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
 
     @test()
     protected static async usesDiscoveredUuidToStartBleBackend() {
-        const instance = await this.BleControllerWithPrefix()
+        const instance = await this.BleGattControllerWithPrefix()
 
         await this.connectWithDiscovery(instance)
 
         assert.isEqual(
-            FakeLibndx.callsToStartBleBackend[0]?.deviceUuid,
+            FakeLibndx.callsToStartBleGattBackend[0]?.deviceUuid,
             this.discoveredUuid,
             'Did not start BLE backend with the discovered uuid!'
         )
@@ -152,7 +152,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
 
     @test()
     protected static async exposesDiscoveredUuid() {
-        const instance = await this.BleControllerWithPrefix()
+        const instance = await this.BleGattControllerWithPrefix()
 
         await this.connectWithDiscovery(instance)
 
@@ -189,18 +189,18 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
     protected static async connectCallsLibndxStartBleBackend() {
         await this.connect()
 
-        const call = FakeLibndx.callsToStartBleBackend[0]
+        const call = FakeLibndx.callsToStartBleGattBackend[0]
 
         assert.isEqual(
             call.deviceUuid,
             this.uuid,
-            'Did not call startBleBackend with correct deviceUuid!'
+            'Did not call startBleGattBackend with correct deviceUuid!'
         )
 
         assert.isEqual(
             call.charCallbacks.length,
             2,
-            'Did not call startBleBackend with charCallbacks!'
+            'Did not call startBleGattBackend with charCallbacks!'
         )
 
         let i = 0
@@ -228,7 +228,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
     @test()
     protected static async startBleBackendThrowsOn400() {
         //@ts-ignore
-        this.instance.createBleBackend = () => {}
+        this.instance.createBleGattBackend = () => {}
 
         this.setFake400Error()
 
@@ -242,7 +242,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
     @test()
     protected static async startBleBackendThrowsOn500() {
         //@ts-ignore
-        this.instance.createBleBackend = () => {}
+        this.instance.createBleGattBackend = () => {}
 
         this.setFake500Error()
 
@@ -266,7 +266,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
     @test()
     protected static async waitsAfterOnConnectedToDiscoverServices() {
         const waitAfterMs = 20
-        BleDeviceController.waitAfterMs = waitAfterMs
+        BleGattController.waitAfterMs = waitAfterMs
 
         await this.connect()
 
@@ -281,13 +281,13 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
         await this.writeCharacteristic()
 
         assert.isEqualDeep(
-            FakeLibndx.callsToWriteBleCharacteristic[0],
+            FakeLibndx.callsToWriteBleGattChar[0],
             {
                 deviceUuid: this.uuid,
                 charUuid: this.charUuid,
                 value: this.charValueToWrite,
             },
-            'Did not call writeBleCharacteristic as expected!'
+            'Did not call writeBleGattChar as expected!'
         )
     }
 
@@ -318,12 +318,12 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
         await this.subscribeCharacteristics()
 
         assert.isEqualDeep(
-            FakeLibndx.callsToAddBleCharCallbacks[0],
+            FakeLibndx.callsToRegisterBleGattCharCallbacks[0],
             {
                 deviceUuid: this.uuid,
                 charCallbacks: this.extraCharCallbacks,
             },
-            'Did not call addBleCharCallbacks as expected!'
+            'Did not call registerBleGattCharCallbacks as expected!'
         )
     }
 
@@ -354,7 +354,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
         await this.connect()
 
         const { deviceUuid, intervalMs } =
-            FakeLibndx.callsToSetBleRssiInterval[0]
+            FakeLibndx.callsToStartBleGattRssiPolling[0]
 
         assert.isEqualDeep(
             { deviceUuid, intervalMs },
@@ -362,7 +362,7 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
                 deviceUuid: this.uuid,
                 intervalMs: this.rssiIntervalMs,
             },
-            'Did not call setBleRssiInterval as expected!'
+            'Did not call startBleGattRssiPolling as expected!'
         )
     }
 
@@ -371,11 +371,11 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
         await this.disconnect()
 
         assert.isEqualDeep(
-            FakeLibndx.callsToStopBleBackend[0],
+            FakeLibndx.callsToStopBleGattBackend[0],
             {
                 deviceUuid: this.uuid,
             },
-            'Did not call stopBleBackend!'
+            'Did not call stopBleGattBackend!'
         )
     }
 
@@ -446,20 +446,22 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
     private static async connect() {
         const promise = this.instance.connect()
 
-        const startCall = FakeLibndx.callsToStartBleBackend[0]
+        const startCall = FakeLibndx.callsToStartBleGattBackend[0]
         startCall?.onConnected(this.nativePeripheral)
 
         await promise
     }
 
-    private static async connectWithDiscovery(instance: SpyBleController) {
+    private static async connectWithDiscovery(instance: SpyBleGatt) {
         const promise = instance.connect()
 
         FakeLibndx.callsToDiscoverBleUuid[0]?.onDiscovered(this.discoveredUuid)
 
-        await this.waitForCall(() => FakeLibndx.callsToStartBleBackend[0])
+        await this.waitForCall(() => FakeLibndx.callsToStartBleGattBackend[0])
 
-        FakeLibndx.callsToStartBleBackend[0]?.onConnected(this.nativePeripheral)
+        FakeLibndx.callsToStartBleGattBackend[0]?.onConnected(
+            this.nativePeripheral
+        )
 
         await promise
     }
@@ -512,20 +514,18 @@ export default class BleDeviceControllerTest extends AbstractPackageTest {
         }
     }
 
-    private static BleDeviceController(
-        options?: Partial<BleControllerOptions>
-    ) {
-        return BleDeviceController.Create({
+    private static BleGattController(options?: Partial<BleGattOptions>) {
+        return BleGattController.Create({
             deviceUuid: this.uuid,
             charCallbacks: this.charCallbacks,
             onConnected: this.onConnected,
             rssiIntervalMs: this.rssiIntervalMs,
             ...options,
-        }) as SpyBleController
+        }) as SpyBleGatt
     }
 
-    private static BleControllerWithPrefix() {
-        return this.BleDeviceController({
+    private static BleGattControllerWithPrefix() {
+        return this.BleGattController({
             deviceNamePrefix: this.namePrefix,
             deviceUuid: undefined,
         })

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

@@ -0,0 +1,158 @@
+import { test, assert } from '@neurodevs/node-tdd'
+
+import BleObserverController, {
+    BleObserver,
+} from '../../impl/controllers/BleObserverController.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+import { FakeLibndx } from '@neurodevs/ndx-native'
+
+export default class BleObserverControllerTest extends AbstractPackageTest {
+    private static instance: BleObserver
+    private static passedAdvertisements: PassedAdvertisement[]
+
+    private static readonly fakeError = this.generateId()
+
+    private static readonly data = Buffer.from([0x01, 0x02, 0x03])
+    private static readonly length = 3
+    private static readonly timestampSec = 1234.5
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        this.passedAdvertisements = []
+
+        this.instance = this.BleObserverController()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async startObservingCreatesBleObserverBackend() {
+        await this.startObserving()
+
+        assert.isEqualDeep(FakeLibndx.callsToCreateBleObserver[0], {
+            deviceUuid: this.deviceUuid,
+        })
+    }
+
+    @test()
+    protected static async startObservingStartsBleObserverBackend() {
+        await this.startObserving()
+
+        const { deviceUuid, onAdvertisement } =
+            FakeLibndx.callsToStartBleObserver[0]
+
+        assert.isEqual(
+            deviceUuid,
+            this.deviceUuid,
+            'Did not pass deviceUuid to startBleObserverBackend!'
+        )
+        assert.isFunction(
+            onAdvertisement,
+            'Did not pass onAdvertisement to startBleObserverBackend!'
+        )
+    }
+
+    @test()
+    protected static async passesExpectedArgsToOnAdvertisement() {
+        await this.startObserving()
+
+        FakeLibndx.callsToStartBleObserver[0]?.onAdvertisement(
+            this.data,
+            this.length,
+            this.timestampSec
+        )
+
+        assert.isEqualDeep(
+            this.passedAdvertisements[0],
+            {
+                data: this.data,
+                length: this.length,
+                timestampSec: this.timestampSec,
+            },
+            'Did not pass expected args to onAdvertisement!'
+        )
+    }
+
+    @test()
+    protected static async stopObservingStopsBleObserverBackend() {
+        await this.stopObserving()
+
+        assert.isEqualDeep(FakeLibndx.callsToStopBleObserver[0], {
+            deviceUuid: this.deviceUuid,
+        })
+    }
+
+    @test()
+    protected static async createBleObserverBackendThrowsOnError() {
+        this.setFakeErrorResult()
+
+        //@ts-ignore
+        this.instance.startBleObserverBackend = () => {}
+
+        await assert.doesThrowAsync(
+            async () => await this.startObserving(),
+            this.fakeError,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async startObservingThrowsOnError() {
+        this.setFakeErrorResult()
+
+        await assert.doesThrowAsync(
+            async () => await this.startObserving(),
+            this.fakeError,
+            'Did not throw error!'
+        )
+    }
+
+    @test()
+    protected static async stopObservingThrowsOnError() {
+        this.setFakeErrorResult()
+
+        await assert.doesThrowAsync(
+            async () => await this.stopObserving(),
+            this.fakeError,
+            'Did not throw error!'
+        )
+    }
+
+    private static setFakeErrorResult() {
+        FakeLibndx.fakeResult = {
+            status: 400,
+            error: this.fakeError,
+        }
+    }
+
+    private static async startObserving() {
+        await this.instance.startObserving()
+    }
+
+    private static async stopObserving() {
+        await this.instance.stopObserving()
+    }
+
+    private static BleObserverController() {
+        return BleObserverController.Create({
+            deviceUuid: this.deviceUuid,
+            onAdvertisement: (
+                data: Buffer,
+                length: number,
+                timestampSec: number
+            ) => {
+                this.passedAdvertisements.push({ data, length, timestampSec })
+            },
+        })
+    }
+}
+
+type PassedAdvertisement = {
+    data: Buffer
+    length: number
+    timestampSec: number
+}

package/src/__tests__/impl/{LslEventMarkerEmitter.test.ts → LslEventMarkerOutlet.test.ts}

@@ -2,26 +2,25 @@ import { randomInt } from 'node:crypto'
 
 import { assert, test } from '@neurodevs/node-tdd'
 
-import LslEventMarkerEmitter, {
+import LslEventMarkerOutlet, {
     EmitOptions,
-} from '../../impl/LslEventMarkerEmitter.js'
+} from '../../impl/LslEventMarkerOutlet.js'
 import { LslOutletOptions } from '../../impl/LslStreamOutlet.js'
-import SpyLslEmitter from '../../testDoubles/LslEmitter/SpyLslEmitter.js'
+import SpyEventMarkerOutlet from '../../testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
 import generateRandomOutletOptions from '../../testDoubles/generateRandomOutletOptions.js'
 import FakeLslOutlet from '../../testDoubles/LslOutlet/FakeLslOutlet.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
-export default class EventMarkerEmitterTest extends AbstractPackageTest {
-    private static instance: SpyLslEmitter
+export default class EventMarkerOutletTest extends AbstractPackageTest {
+    private static instance: SpyEventMarkerOutlet
 
     protected static async beforeEach() {
         await super.beforeEach()
 
-        this.setFakeLiblsl()
         this.setFakeLslOutlet()
-        this.setSpyLslEmitter()
+        this.setSpyEventMarkerOutlet()
 
-        this.instance = await this.LslEventMarkerEmitter()
+        this.instance = await this.LslEventMarkerOutlet()
     }
 
     private static readonly markerName = this.generateId()
@@ -68,7 +67,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
     @test()
     protected static async canOverrideDefaultOptions() {
         const options = generateRandomOutletOptions()
-        await this.LslEventMarkerEmitter(options)
+        await this.LslEventMarkerOutlet(options)
 
         assert.isEqualDeep(FakeLslOutlet.callsToConstructor[1], options)
     }
@@ -86,7 +85,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
             'Pushed the wrong marker!'
         )
 
-        assert.isEqual(this.instance.totalwaitAfterMs, marker.waitAfterMs)
+        assert.isEqual(this.instance.totalWaitAfterMs, marker.waitAfterMs)
     }
 
     @test()
@@ -96,7 +95,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
         assert.isEqual(FakeLslOutlet.callsToPushSample.length, 2)
 
         assert.isEqual(
-            this.instance.totalwaitAfterMs,
+            this.instance.totalWaitAfterMs,
             markers[0].waitAfterMs + markers[1].waitAfterMs
         )
     }
@@ -104,7 +103,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
     @test('interrupts on first marker', 1)
     @test('interrupts on second marker', 2)
     @test('interrupts on third marker', 3)
-    protected static async emitterIsInterruptable(bailIdx: number) {
+    protected static async outletIsInterruptable(bailIdx: number) {
         let hitCount = 0
 
         this.streamOutlet.pushSample = () => {
@@ -170,7 +169,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
 
     @test()
     protected static async emitWaitsForMsIfPassed() {
-        SpyLslEmitter.shouldCallWaitOnSuper = true
+        SpyEventMarkerOutlet.shouldCallWaitOnSuper = true
 
         const waitAfterMs = 10
 
@@ -217,7 +216,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
 
     @test()
     protected static async sourceIdIsUniqueAcrossInstances() {
-        const instance = await this.LslEventMarkerEmitter()
+        const instance = await this.LslEventMarkerOutlet()
 
         assert.isNotEqual(
             instance['outlet'].sourceId,
@@ -237,7 +236,7 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
 
     @test()
     protected static async emitManyThrowsIfCalledWhileAlreadyRunning() {
-        void EventMarkerEmitterTest.emitManyOnce()
+        void EventMarkerOutletTest.emitManyOnce()
 
         await assert.doesThrowAsync(async () => {
             await this.emitManyFor(5, 1)
@@ -306,13 +305,15 @@ export default class EventMarkerEmitterTest extends AbstractPackageTest {
     }
 
     private static async setupOutlet() {
-        LslEventMarkerEmitter.Class = LslEventMarkerEmitter as any
-        this.instance = await this.LslEventMarkerEmitter()
+        LslEventMarkerOutlet.Class = LslEventMarkerOutlet as any
+        this.instance = await this.LslEventMarkerOutlet()
     }
 
-    private static async LslEventMarkerEmitter(
+    private static async LslEventMarkerOutlet(
         options?: Partial<LslOutletOptions>
     ) {
-        return (await LslEventMarkerEmitter.Create(options)) as SpyLslEmitter
+        return (await LslEventMarkerOutlet.Create(
+            options
+        )) as SpyEventMarkerOutlet
     }
 }

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

@@ -0,0 +1,135 @@
+import { test, assert } from '@neurodevs/node-tdd'
+
+import LslJsonOutlet, {
+    JsonOutlet,
+    JsonOutletOptions,
+} from '../../impl/LslJsonOutlet.js'
+import FakeLslOutlet from '../../testDoubles/LslOutlet/FakeLslOutlet.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+
+export default class LslJsonOutletTest extends AbstractPackageTest {
+    private static instance: JsonOutlet
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        this.setFakeLslOutlet()
+
+        LslJsonOutlet.backupIdCounter = 0
+
+        this.instance = await this.LslJsonOutlet()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async loadsWithJsonSpecificOptionsOnce() {
+        assert.isEqualDeep(FakeLslOutlet.callsToConstructor[0], {
+            name: `JSON (json-1)`,
+            type: 'JSON',
+            sourceId: 'json-1',
+            channelNames: ['JSON'],
+            channelFormat: 'string',
+            sampleRateHz: 0,
+            chunkSize: 1,
+        })
+    }
+
+    @test()
+    protected static async loadsWithJsonSpecificOptionsTwice() {
+        await this.LslJsonOutlet()
+
+        assert.isEqualDeep(FakeLslOutlet.callsToConstructor[1], {
+            name: `JSON (json-2)`,
+            type: 'JSON',
+            sourceId: 'json-2',
+            channelNames: ['JSON'],
+            channelFormat: 'string',
+            sampleRateHz: 0,
+            chunkSize: 1,
+        })
+    }
+
+    @test()
+    protected static async canOverrideDefaultOptions() {
+        const channelName = this.generateId()
+
+        await this.LslJsonOutlet({
+            name: this.name_,
+            type: this.type,
+            sourceId: this.sourceId,
+            channelName,
+            sampleRateHz: this.sampleRateHz,
+            chunkSize: this.chunkSize,
+        })
+
+        assert.isEqualDeep(FakeLslOutlet.callsToConstructor[1], {
+            name: this.name_,
+            type: this.type,
+            sourceId: this.sourceId,
+            channelNames: [channelName],
+            channelFormat: 'string',
+            sampleRateHz: this.sampleRateHz,
+            chunkSize: this.chunkSize,
+        })
+    }
+
+    @test()
+    protected static async pushJsonSerializesAndPushesToLslOutlet() {
+        const data = { [this.generateId()]: this.generateId() }
+
+        this.instance.pushJson(data)
+
+        assert.isEqualDeep(FakeLslOutlet.callsToPushSample[0]?.sample, [
+            JSON.stringify(data),
+        ])
+    }
+
+    @test()
+    protected static async destroyCallsDestroyOnLslOutlet() {
+        this.instance.destroy()
+
+        assert.isEqual(
+            FakeLslOutlet.numCallsToDestroy,
+            1,
+            'Did not call destroy on outlet!'
+        )
+    }
+
+    @test()
+    protected static async pushJsonThrowsIfPayloadExceedsMaxBytesPerSample() {
+        const maxBytesPerSample = 10
+
+        const instance = await this.LslJsonOutlet({ maxBytesPerSample })
+        const data = { [this.generateId()]: this.generateId() }
+
+        assert.doesThrow(
+            () => instance.pushJson(data),
+            `Payload of ${JSON.stringify(data).length} bytes exceeds maxBytesPerSample of ${maxBytesPerSample}!`
+        )
+    }
+
+    @test()
+    protected static async countsUtf8BytesNotCharacters() {
+        const data = { emoji: '😀😀😀' }
+
+        const json = JSON.stringify(data)
+        const totalBytes = Buffer.byteLength(json)
+
+        const maxBytesPerSample = json.length
+
+        const instance = await this.LslJsonOutlet({ maxBytesPerSample })
+
+        assert.doesThrow(
+            () => instance.pushJson(data),
+            `Payload of ${totalBytes} bytes exceeds maxBytesPerSample of ${maxBytesPerSample}!`
+        )
+    }
+
+    private static LslJsonOutlet(options?: JsonOutletOptions) {
+        return LslJsonOutlet.Create(options)
+    }
+}

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

@@ -11,7 +11,6 @@ export default class LslStreamInfoTest extends AbstractPackageTest {
     protected static async beforeEach() {
         await super.beforeEach()
 
-        this.setFakeLiblsl()
         this.setSpyLslInfo()
 
         this.instance = this.LslStreamInfo()

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

@@ -53,7 +53,6 @@ export default class LslStreamInletTest extends AbstractPackageTest {
     protected static async beforeEach() {
         await super.beforeEach()
 
-        this.setFakeLiblsl()
         this.setFakeLslInfo()
         this.setSpyLslInlet()