@neurodevs/node-lsl 17.1.1 → 18.1.0

package/src/impl/workers/outlet/LslStreamOutlet.worker.ts

@@ -0,0 +1,144 @@
+import { parentPort } from 'node:worker_threads'
+
+import {
+    LiblslAdapter,
+    Liblsl,
+    OutletHandle,
+    handleLslError,
+    LslErrorCode,
+} from '@neurodevs/ndx-native'
+
+import LslStreamInfo, {
+    StreamInfo,
+    StreamInfoOptions,
+} from '../../LslStreamInfo.js'
+
+let lsl = LiblslAdapter.getInstance()
+
+export function setOutletLiblslAdapter(adapter: Liblsl) {
+    LiblslAdapter.setInstance(adapter)
+    lsl = LiblslAdapter.getInstance()
+}
+
+let handleLslErrorFn = handleLslError
+
+export function setOutletHandleLslError(fn: typeof handleLslError) {
+    handleLslErrorFn = fn
+}
+
+let info: StreamInfo
+let handle: OutletHandle
+let pushMethod: (opts: unknown) => LslErrorCode
+
+parentPort?.on('message', (msg: OutletMessage) => {
+    const { type } = msg
+
+    try {
+        switch (type) {
+            case 'createOutlet': {
+                createOutlet(msg)
+                break
+            }
+
+            case 'pushSample': {
+                pushSample(msg)
+                break
+            }
+
+            case 'destroyOutlet': {
+                destroyOutlet()
+                break
+            }
+        }
+    } catch (err) {
+        parentPort?.postMessage({
+            type: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        })
+    }
+})
+
+export function createOutlet(msg: {
+    type: 'createOutlet'
+    payload: CreateOutletPayload
+}) {
+    const { payload } = msg
+
+    info = LslStreamInfo.Create(payload.infoOptions)
+
+    handle = lsl.createOutlet({
+        infoHandle: info.infoHandle,
+        chunkSize: payload.chunkSize,
+        maxBufferedMs: payload.maxBufferedMs,
+    })
+
+    pushMethod = (
+        lsl[payload.pushMethod] as (opts: unknown) => LslErrorCode
+    ).bind(lsl)
+
+    parentPort?.postMessage({ type: 'ready' })
+}
+
+export function pushSample(msg: {
+    type: 'pushSample'
+    payload: PushSamplePayload
+}) {
+    const { payload } = msg
+    const { sample, timestampSec = lsl.localClock() } = payload
+
+    if (!handle || !pushMethod) {
+        throw new Error('Outlet not initialized')
+    }
+
+    const errorCode = pushMethod({
+        outletHandle: handle,
+        sample,
+        timestampSec,
+    })
+
+    try {
+        handleLslErrorFn(errorCode)
+    } catch {
+        parentPort?.postMessage({
+            type: 'error',
+            error: `Error pushing sample: ${LslErrorCode[errorCode]}`,
+        })
+    }
+}
+
+export function destroyOutlet() {
+    if (handle) {
+        lsl.destroyOutlet({ outletHandle: handle })
+    }
+
+    if (info) {
+        lsl.destroyStreamInfo({ infoHandle: info.infoHandle })
+    }
+
+    parentPort?.close()
+}
+
+export type OutletMessage =
+    | {
+          type: 'createOutlet'
+          payload: CreateOutletPayload
+      }
+    | {
+          type: 'pushSample'
+          payload: PushSamplePayload
+      }
+    | {
+          type: 'destroyOutlet'
+      }
+
+export interface CreateOutletPayload {
+    infoOptions: StreamInfoOptions
+    chunkSize: number
+    maxBufferedMs: number
+    pushMethod: 'pushSampleFloatTimestamp' | 'pushSampleStringTimestamp'
+}
+
+export interface PushSamplePayload {
+    sample: unknown
+    timestampSec?: number
+}

package/src/index.ts

@@ -1,27 +1,27 @@
-// EventMarkerOutlet
+// DeviceController
 
-export { default as LslEventMarkerOutlet } from './impl/LslEventMarkerOutlet.js'
-export * from './impl/LslEventMarkerOutlet.js'
+export { default as BleDeviceController } from './impl/controllers/BleDeviceController.js'
+export * from './impl/controllers/BleDeviceController.js'
 
-export { default as FakeEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/FakeEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/FakeEventMarkerOutlet.js'
+export { default as FakeBleController } from './testDoubles/BleController/FakeBleController.js'
+export * from './testDoubles/BleController/FakeBleController.js'
 
-export { default as MockEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/MockEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/MockEventMarkerOutlet.js'
+export { default as SpyBleController } from './testDoubles/BleController/SpyBleController.js'
+export * from './testDoubles/BleController/SpyBleController.js'
 
-export { default as SpyEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
+// EventMarkerEmitter
 
-export { default as ThrowingEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/ThrowingEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/ThrowingEventMarkerOutlet.js'
+export { default as LslEventMarkerEmitter } from './impl/LslEventMarkerEmitter.js'
+export * from './impl/LslEventMarkerEmitter.js'
 
-// Liblsl
+export { default as FakeEventMarkerEmitter } from './testDoubles/EventMarkerEmitter/FakeEventMarkerEmitter.js'
+export * from './testDoubles/EventMarkerEmitter/FakeEventMarkerEmitter.js'
 
-export { default as LiblslAdapter } from './impl/LiblslAdapter.js'
-export * from './impl/LiblslAdapter.js'
+export { default as SpyEventMarkerEmitter } from './testDoubles/EventMarkerEmitter/SpyEventMarkerEmitter.js'
+export * from './testDoubles/EventMarkerEmitter/SpyEventMarkerEmitter.js'
 
-export { default as FakeLiblsl } from './testDoubles/Liblsl/FakeLiblsl.js'
-export * from './testDoubles/Liblsl/FakeLiblsl.js'
+export { default as ThrowingEventMarkerEmitter } from './testDoubles/EventMarkerEmitter/ThrowingEventMarkerEmitter.js'
+export * from './testDoubles/EventMarkerEmitter/ThrowingEventMarkerEmitter.js'
 
 // StreamInfo
 

package/src/scripts/discoverMuse.ts

@@ -0,0 +1,50 @@
+import koffi from 'koffi'
+
+import BleDeviceController from '../impl/controllers/BleDeviceController.js'
+
+const MUSE_CHARACTERISTIC_UUIDS: Record<string, string> = {
+    CONTROL: '273E0001-4C4D-454D-96BE-F03BAC821358',
+    TELEMETRY: '273E000B-4C4D-454D-96BE-F03BAC821358',
+    GYROSCOPE: '273E0009-4C4D-454D-96BE-F03BAC821358',
+    ACCELEROMETER: '273E000A-4C4D-454D-96BE-F03BAC821358',
+    PPG_AMBIENT: '273E000F-4C4D-454D-96BE-F03BAC821358',
+    PPG_INFRARED: '273E0010-4C4D-454D-96BE-F03BAC821358',
+    PPG_RED: '273E0011-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP9: '273E0003-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF7: '273E0004-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF8: '273E0005-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP10: '273E0006-4C4D-454D-96BE-F03BAC821358',
+    EEG_AUX: '273E0007-4C4D-454D-96BE-F03BAC821358',
+}
+
+const CONTROL_UUID = MUSE_CHARACTERISTIC_UUIDS['CONTROL']
+
+const charCallbacks = Object.entries(MUSE_CHARACTERISTIC_UUIDS).map(
+    ([name, uuid]) => {
+        return {
+            charUuid: uuid,
+            charName: name,
+            onData: (data: Buffer, length: number, timestampSec: number) => {
+                const bytes = koffi.decode(data, 'uint8', length) as number[]
+                console.info(`[${timestampSec}] length=${length}`, bytes)
+            },
+        }
+    }
+)
+
+const muse = await BleDeviceController.Create({
+    deviceNamePrefix: 'Muse',
+    charCallbacks,
+    rssiIntervalMs: 1000,
+})
+
+await muse.connect()
+
+for (const cmd of ['h', 'p50', 's', 'd']) {
+    await muse.writeCharacteristic(CONTROL_UUID, cmd)
+    await new Promise((resolve) => setTimeout(resolve, 100))
+}
+
+await new Promise((resolve) => setTimeout(resolve, 5 * 1000))
+
+await muse.disconnect()

package/src/scripts/finalizeHandles.ts

@@ -0,0 +1,63 @@
+export type DestroyHandle = () => void // Do not make this async
+
+const destroyHandles = new Set<DestroyHandle>()
+
+let isFinalizing = false
+
+export function register(destroy: DestroyHandle) {
+    if (isFinalizing) {
+        destroy()
+        return
+    }
+
+    destroyHandles.add(destroy)
+
+    const unregister = () => {
+        destroyHandles.delete(destroy)
+    }
+
+    return unregister
+}
+
+function finalizeHandles() {
+    if (isFinalizing) {
+        return
+    }
+    isFinalizing = true
+
+    for (const destroy of destroyHandles) {
+        try {
+            destroy()
+        } catch (err) {
+            console.error('Error during finalization:', err)
+        }
+    }
+
+    destroyHandles.clear()
+}
+
+process.once('SIGINT', finalizeHandles)
+
+process.once('SIGTERM', finalizeHandles)
+
+process.once('uncaughtException', (err) => {
+    console.error('Uncaught exception:', err)
+    finalizeHandles()
+    process.exit(1)
+})
+
+process.once('unhandledRejection', (reason) => {
+    console.error('Unhandled rejection:', reason)
+    finalizeHandles()
+    process.exit(1)
+})
+
+process.once('beforeExit', () => {
+    if (destroyHandles.size > 0 && !isFinalizing) {
+        console.warn(
+            'Warning: process is exiting with active handles.\n' +
+                'Did you forget to call destroy()? Finalizing automatically.'
+        )
+        finalizeHandles()
+    }
+})

package/src/scripts/runLslEventMarkerEmitter.ts

@@ -0,0 +1,15 @@
+import LslEventMarkerEmitter from '../impl/LslEventMarkerEmitter.js'
+
+const outlet = await LslEventMarkerEmitter.Create()
+
+const markers = [
+    { name: 'phase-1-begin', waitAfterMs: 100 },
+    { name: 'phase-1-end', waitAfterMs: 100 },
+    { name: 'never-reached-marker', waitAfterMs: 100 },
+]
+
+void outlet.emitMany(markers)
+
+await new Promise((resolve) => setTimeout(resolve, 250))
+
+outlet.interrupt()

package/src/scripts/runMuse.ts

@@ -0,0 +1,50 @@
+import koffi from 'koffi'
+
+import BleDeviceController from '../impl/controllers/BleDeviceController.js'
+
+const MUSE_CHARACTERISTIC_UUIDS: Record<string, string> = {
+    CONTROL: '273E0001-4C4D-454D-96BE-F03BAC821358',
+    TELEMETRY: '273E000B-4C4D-454D-96BE-F03BAC821358',
+    GYROSCOPE: '273E0009-4C4D-454D-96BE-F03BAC821358',
+    ACCELEROMETER: '273E000A-4C4D-454D-96BE-F03BAC821358',
+    PPG_AMBIENT: '273E000F-4C4D-454D-96BE-F03BAC821358',
+    PPG_INFRARED: '273E0010-4C4D-454D-96BE-F03BAC821358',
+    PPG_RED: '273E0011-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP9: '273E0003-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF7: '273E0004-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF8: '273E0005-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP10: '273E0006-4C4D-454D-96BE-F03BAC821358',
+    EEG_AUX: '273E0007-4C4D-454D-96BE-F03BAC821358',
+}
+
+const CONTROL_UUID = MUSE_CHARACTERISTIC_UUIDS['CONTROL']
+
+const charCallbacks = Object.entries(MUSE_CHARACTERISTIC_UUIDS).map(
+    ([name, uuid]) => {
+        return {
+            charUuid: uuid,
+            charName: name,
+            onData: (data: Buffer, length: number, timestampSec: number) => {
+                const bytes = koffi.decode(data, 'uint8', length) as number[]
+                console.info(`[${timestampSec}] length=${length}`, bytes)
+            },
+        }
+    }
+)
+
+const muse = await BleDeviceController.Create({
+    deviceUuid: 'CA6A61B7-B7A8-AF24-3C9E-04A6A5012554',
+    charCallbacks,
+    rssiIntervalMs: 1000,
+})
+
+await muse.connect()
+
+for (const cmd of ['h', 'p50', 's', 'd']) {
+    await muse.writeCharacteristic(CONTROL_UUID, cmd)
+    await new Promise((resolve) => setTimeout(resolve, 100))
+}
+
+await new Promise((resolve) => setTimeout(resolve, 5 * 1000))
+
+await muse.disconnect()

package/src/scripts/runOutletToInlet.ts

@@ -1,11 +1,13 @@
 import LslStreamInlet from '../impl/LslStreamInlet.js'
 import LslStreamOutlet from '../impl/LslStreamOutlet.js'
 
+const sourceId = 'TestOutletID'
+
 console.log('Creating outlet...')
 const outlet = await LslStreamOutlet.Create({
     name: 'TestOutlet',
     type: 'TEST',
-    sourceId: 'TestOutletID',
+    sourceId,
     sampleRateHz: 100,
     channelNames: ['Ch1', 'Ch2', 'Ch3'],
     channelFormat: 'float32',
@@ -16,20 +18,18 @@ const outlet = await LslStreamOutlet.Create({
 
 console.log('Creating inlet...')
 
-const inletOptions = {
-    info: outlet.info,
-    chunkSize: 1,
-}
-
 const inlet = await LslStreamInlet.Create(
-    inletOptions,
+    {
+        sourceId,
+        chunkSize: 1,
+    },
     (samples, timestamps) => {
         console.log('Received samples:', samples, 'at timestamps:', timestamps)
     }
 )
 
 console.log('Start pulling...')
-inlet.startPulling()
+await inlet.startPulling()
 
 console.log('Waiting for 100 ms...')
 await new Promise((resolve) => setTimeout(resolve, 100))
@@ -49,3 +49,5 @@ for (let i = 0; i < 30; i++) {
     outlet.pushSample(sample)
     await new Promise((resolve) => setTimeout(resolve, 100))
 }
+
+process.exit(0)

package/src/scripts/testDestroyOutlet.ts

@@ -0,0 +1,5 @@
+import LslEventMarkerEmitter from '../impl/LslEventMarkerEmitter.js'
+
+const emitter = await LslEventMarkerEmitter.Create()
+
+emitter.destroy()

package/src/testDoubles/BleController/FakeBleController.ts

@@ -0,0 +1,70 @@
+import generateId from '@neurodevs/generate-id'
+import {
+    BleController,
+    BleControllerOptions,
+} from '../../impl/controllers/BleDeviceController.js'
+
+export default class FakeBleController implements BleController {
+    public static callsToConstructor: (BleControllerOptions | undefined)[] = []
+
+    public static numCallsToConnect = 0
+
+    public static callsToWriteCharacteristic: {
+        characteristicUuid: string
+        value: string
+    }[] = []
+
+    public static numCallsToDisconnect = 0
+
+    public static fakeCharacteristics: Record<string, unknown> = {}
+    public static fakeName = `fake-${generateId()}`
+
+    private _uuid: string
+    private _name: string
+
+    public constructor(options?: BleControllerOptions) {
+        const { deviceUuid } = options ?? {}
+
+        this._uuid = deviceUuid ?? generateId()
+        this._name = FakeBleController.fakeName
+
+        FakeBleController.callsToConstructor.push(options)
+    }
+
+    public async connect() {
+        FakeBleController.numCallsToConnect++
+    }
+
+    public async writeCharacteristic(
+        characteristicUuid: string,
+        value: string
+    ) {
+        FakeBleController.callsToWriteCharacteristic.push({
+            characteristicUuid,
+            value,
+        })
+    }
+
+    public async disconnect() {
+        FakeBleController.numCallsToDisconnect++
+    }
+
+    public get uuid() {
+        return this._uuid
+    }
+
+    public get name() {
+        return this._name
+    }
+
+    public static resetTestDouble() {
+        this.callsToConstructor = []
+        this.numCallsToConnect = 0
+        this.callsToWriteCharacteristic = []
+        this.numCallsToDisconnect = 0
+    }
+}
+
+export interface CallToBleControllerConstructor {
+    options: BleControllerOptions
+}

package/src/testDoubles/BleController/SpyBleController.ts

@@ -0,0 +1,61 @@
+import BleDeviceController, {
+    BleControllerOptions,
+} from '../../impl/controllers/BleDeviceController.js'
+
+export default class SpyBleController extends BleDeviceController {
+    public infoLogs: string[] = []
+    public warnLogs: string[] = []
+    public errorLogs: string[] = []
+
+    public constructor(options: BleControllerOptions) {
+        super(options)
+    }
+
+    public getCharacteristicCallbacks() {
+        return this.charCallbacks
+    }
+
+    public getRssiIntervalMs() {
+        return this.rssiIntervalMs
+    }
+
+    public getConnected() {
+        return this.connected
+    }
+
+    public setLogInfoSpy() {
+        this.infoLogs = []
+
+        this.log.info = (...args: unknown[]) => {
+            const message = args.join(' ')
+            this.infoLogs.push(message)
+            return message
+        }
+    }
+
+    public setLogWarnSpy() {
+        this.warnLogs = []
+
+        this.log.warn = (...args: unknown[]) => {
+            const message = args.join(' ')
+            this.warnLogs.push(message)
+            return message
+        }
+    }
+
+    public setLogErrorSpy() {
+        this.errorLogs = []
+
+        this.log.error = (...args: unknown[]) => {
+            const message = args.join(' ')
+            this.errorLogs.push(message)
+            return message
+        }
+    }
+
+    public resetTestDouble() {
+        this.infoLogs = []
+        this.warnLogs = []
+        this.errorLogs = []
+    }
+}

package/src/testDoubles/EventMarkerEmitter/FakeEventMarkerEmitter.ts

@@ -0,0 +1,46 @@
+import {
+    EventMarkerEmitter,
+    EventMarkerOptions,
+    TimedEventMarker,
+} from '../../impl/LslEventMarkerEmitter.js'
+
+export default class FakeEventMarkerEmitter implements EventMarkerEmitter {
+    public static numCallsToConstructor = 0
+
+    public static callsToEmit: {
+        markerName: string
+        options?: EventMarkerOptions
+    }[] = []
+
+    public static callsToEmitMany: TimedEventMarker[][] = []
+    public static numCallsToInterrupt = 0
+    public static numCallsToDestroy = 0
+
+    public constructor() {
+        FakeEventMarkerEmitter.numCallsToConstructor++
+    }
+
+    public async emit(markerName: string, options?: EventMarkerOptions) {
+        FakeEventMarkerEmitter.callsToEmit.push({ markerName, options })
+    }
+
+    public async emitMany(markers: TimedEventMarker[]) {
+        FakeEventMarkerEmitter.callsToEmitMany.push(markers)
+    }
+
+    public interrupt() {
+        FakeEventMarkerEmitter.numCallsToInterrupt++
+    }
+
+    public destroy() {
+        FakeEventMarkerEmitter.numCallsToDestroy++
+    }
+
+    public static resetTestDouble() {
+        this.numCallsToConstructor = 0
+        this.callsToEmit = []
+        this.callsToEmitMany = []
+        this.numCallsToInterrupt = 0
+        this.numCallsToDestroy = 0
+    }
+}

package/src/testDoubles/EventMarkerEmitter/SpyEventMarkerEmitter.ts

@@ -0,0 +1,31 @@
+import LslEventMarkerEmitter from '../../impl/LslEventMarkerEmitter.js'
+import { StreamOutlet } from '../../impl/LslStreamOutlet.js'
+
+export default class SpyEventMarkerEmitter extends LslEventMarkerEmitter {
+    public static shouldCallWaitOnSuper = false
+
+    public totalwaitAfterMs: number
+
+    public constructor(outlet: StreamOutlet) {
+        super(outlet)
+
+        this.totalwaitAfterMs = 0
+    }
+
+    public async wait(waitAfterMs: number) {
+        this.totalwaitAfterMs += waitAfterMs
+
+        if (SpyEventMarkerEmitter.shouldCallWaitOnSuper) {
+            return super.wait(waitAfterMs)
+        }
+        return Promise.resolve()
+    }
+
+    public getStreamOutlet() {
+        return this.outlet
+    }
+
+    public resetTestDouble() {
+        this.totalwaitAfterMs = 0
+    }
+}

package/src/testDoubles/EventMarkerEmitter/ThrowingEventMarkerEmitter.ts

@@ -0,0 +1,29 @@
+import {
+    EventMarkerEmitter,
+    EventMarkerOptions,
+    TimedEventMarker,
+} from '../../impl/LslEventMarkerEmitter.js'
+
+export default class ThrowingEventMarkerEmitter implements EventMarkerEmitter {
+    private errorMsg = 'Intentional throwing: '
+
+    public constructor() {
+        throw new Error(this.errorMsg + 'constructor')
+    }
+
+    public async emit(_markerName: string, _options?: EventMarkerOptions) {
+        throw new Error(this.errorMsg + 'emit')
+    }
+
+    public async emitMany(_markers: TimedEventMarker[]) {
+        throw new Error(this.errorMsg + 'emitMany')
+    }
+
+    public interrupt() {
+        throw new Error(this.errorMsg + 'interrupt')
+    }
+
+    public destroy() {
+        throw new Error(this.errorMsg + 'destroy')
+    }
+}

package/src/testDoubles/StreamInfo/FakeStreamInfo.ts

@@ -1,13 +1,13 @@
 import generateId from '@neurodevs/generate-id'
+import { InfoHandle } from '@neurodevs/ndx-native'
 
-import { BoundStreamInfo } from 'impl/LiblslAdapter.js'
 import { StreamInfo, StreamInfoOptions } from '../../impl/LslStreamInfo.js'
 
 export default class FakeStreamInfo implements StreamInfo {
     public static callsToConstructor: (StreamInfoOptions | undefined)[] = []
     public static numCallsToDestroy = 0
 
-    public static boundInfo = {} as BoundStreamInfo
+    public static infoHandle = {} as InfoHandle
 
     public name = generateId()
     public type = generateId()
@@ -29,8 +29,8 @@ export default class FakeStreamInfo implements StreamInfo {
         return this.channelNames.length
     }
 
-    public get boundInfo() {
-        return FakeStreamInfo.boundInfo
+    public get infoHandle() {
+        return FakeStreamInfo.infoHandle
     }
 
     public static resetTestDouble() {