@neurodevs/ndx-native 0.1.0 → 0.3.0

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

@@ -0,0 +1,279 @@
+import { test, assert } from '@neurodevs/node-tdd'
+
+import LibndxAdapter, {
+    Libndx,
+    LibndxBindings,
+} from '../../impl/LibndxAdapter.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+import { DataType, define, OpenParams } from 'ffi-rs'
+import { FfiRsDefineOptions } from '../../types.js'
+import FakeLibndx from '../../testDoubles/Libndx/FakeLibndx.js'
+
+export default class LibndxAdapterTest extends AbstractPackageTest {
+    public static ffiRsDefine = define
+
+    private static instance: Libndx
+    private static libndxPath = this.generateId()
+    private static shouldThrowWhenLoadingBindings: boolean
+    private static fakeBindings: LibndxBindings
+
+    private static ffiRsOpenOptions?: OpenParams
+    private static ffiRsDefineOptions?: FfiRsDefineOptions
+
+    private static readonly bleDeviceUuid = this.generateId()
+    private static readonly ftdiSerialNumber = this.generateId()
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        this.shouldThrowWhenLoadingBindings = false
+        this.fakeBindings = this.FakeBindings()
+        this.clearAndFakeFfi()
+
+        this.resetInstance()
+        this.instance = this.LibndxAdapter()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async throwsWhenBindingsFailToLoad() {
+        this.resetInstance()
+        this.shouldThrowWhenLoadingBindings = true
+
+        const err = assert.doesThrow(() => this.LibndxAdapter())
+        const actual = (err.message ?? err.stack).replace(/\s+/g, '')
+
+        assert.isEqual(
+            actual,
+            this.failedToLoadError,
+            'Did not receive the expected error!'
+        )
+    }
+
+    @test()
+    protected static async callsFfiRsOpenWithRequiredOptions() {
+        assert.isEqualDeep(this.ffiRsOpenOptions, {
+            library: 'ndx',
+            path: this.libndxPath,
+        })
+    }
+
+    @test()
+    protected static async callsFfiRsDefineWithRequiredOptions() {
+        assert.isEqualDeep(
+            this.ffiRsDefineOptions,
+            {
+                create_ble_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                start_ble_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                stop_ble_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                destroy_ble_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                create_ftdi_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                start_ftdi_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                stop_ftdi_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+                destroy_ftdi_backend: {
+                    library: 'ndx',
+                    retType: DataType.String,
+                    paramsType: [DataType.String],
+                },
+            },
+            'Did not pass valid options to ffiRsDefine!'
+        )
+    }
+
+    @test()
+    protected static async getInstanceReturnsASingleton() {
+        assert.isEqual(LibndxAdapter.getInstance(), LibndxAdapter.getInstance())
+    }
+
+    @test()
+    protected static canSetInstance() {
+        const fake = new FakeLibndx()
+        LibndxAdapter.setInstance(fake)
+        assert.isEqual(LibndxAdapter.getInstance(), fake)
+    }
+
+    @test()
+    protected static async createBleBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.createBleBackend({
+            deviceUuid: this.bleDeviceUuid,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'createBleBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async startBleBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.startBleBackend({
+            deviceUuid: this.bleDeviceUuid,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'startBleBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async stopBleBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.stopBleBackend({
+            deviceUuid: this.bleDeviceUuid,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'stopBleBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async destroyBleBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.destroyBleBackend({
+            deviceUuid: this.bleDeviceUuid,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'destroyBleBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async createFtdiBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.createFtdiBackend({
+            serialNumber: this.ftdiSerialNumber,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'createFtdiBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async startFtdiBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.startFtdiBackend({
+            serialNumber: this.ftdiSerialNumber,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'startFtdiBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async stopFtdiBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.stopFtdiBackend({
+            serialNumber: this.ftdiSerialNumber,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(json, 'stopFtdiBackend did not return a JSON string!')
+    }
+
+    @test()
+    protected static async destroyFtdiBackendCallsBindingAndReturnsJsonString() {
+        const raw = this.instance.destroyFtdiBackend({
+            serialNumber: this.ftdiSerialNumber,
+        })
+        const json = JSON.parse(raw)
+
+        assert.isTruthy(
+            json,
+            'destroyFtdiBackend did not return a JSON string!'
+        )
+    }
+
+    private static clearAndFakeFfi() {
+        delete this.ffiRsOpenOptions
+        delete this.ffiRsDefineOptions
+        this.fakeFfiRsOpen()
+        this.fakeFfiRsDefine()
+    }
+
+    private static fakeFfiRsOpen() {
+        LibndxAdapter.ffiRsOpen = (options) => {
+            this.ffiRsOpenOptions = options
+        }
+    }
+
+    private static fakeFfiRsDefine() {
+        LibndxAdapter.ffiRsDefine = ((options) => {
+            this.ffiRsDefineOptions = options
+
+            if (this.shouldThrowWhenLoadingBindings) {
+                throw new Error(this.fakeErrorMessage)
+            }
+
+            return this.fakeBindings as any
+        }) as typeof define
+    }
+
+    private static get failedToLoadError() {
+        return `
+            \n -----------------------------------
+            \n Failed to load libndx! Tried to load from: 
+            \n     ${this.libndxPath}
+            \n Instructions to save your day (on MacOS):
+            \n     1. git clone https://github.com/neurodevs/libndx.git
+            \n     2. cd libndx && cmake -S . -B build && cmake --build build
+            \n     3. sudo cp build/libndx.dylib /opt/local/lib/
+            \n     4. Try whatever you were doing again!
+            \n Modify step 3 for your OS if you are not on MacOS.
+            \n If you're still unsure, ask an LLM with this error and your OS. 
+            \n You could also post an issue on the repo:
+            \n     https://github.com/neurodevs/ndx-native/issues
+            \n Good luck!
+            \n @ericthecurious
+            \n -----------------------------------
+            \n Original error: ${this.fakeErrorMessage}
+            \n
+        `.replace(/\s+/g, '')
+    }
+
+    private static FakeBindings(): LibndxBindings {
+        return {
+            create_ble_backend: () => JSON.stringify({}),
+            start_ble_backend: () => JSON.stringify({}),
+            stop_ble_backend: () => JSON.stringify({}),
+            destroy_ble_backend: () => JSON.stringify({}),
+            create_ftdi_backend: () => JSON.stringify({}),
+            start_ftdi_backend: () => JSON.stringify({}),
+            stop_ftdi_backend: () => JSON.stringify({}),
+            destroy_ftdi_backend: () => JSON.stringify({}),
+        }
+    }
+
+    private static resetInstance() {
+        LibndxAdapter.resetInstance()
+    }
+
+    private static LibndxAdapter() {
+        return LibndxAdapter.getInstance({
+            libndxPath: this.libndxPath,
+        })
+    }
+}

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

@@ -7,10 +7,10 @@ import { test, assert } from '@neurodevs/node-tdd'
 import { DataType, OpenParams } from 'ffi-rs'
 
 import LibxdfAdapter, {
-    FfiRsDefineOptions,
     LibxdfBindings,
     XdfFile,
 } from '../../impl/LibxdfAdapter.js'
+import { FfiRsDefineOptions } from 'types.js'
 import SpyLibxdf from '../../testDoubles/Libxdf/SpyLibxdf.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
@@ -44,8 +44,8 @@ export default class LibxdfTest extends AbstractPackageTest {
     }
 
     @test()
-    protected static canCreateInstance() {
-        assert.isTruthy(this.instance, 'Should create an instance!')
+    protected static createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
     }
 
     @test()
@@ -90,7 +90,7 @@ export default class LibxdfTest extends AbstractPackageTest {
                     paramsType: [DataType.String],
                 },
             },
-            'Please pass valid options to ffiRsDefine!'
+            'Did not pass valid options to ffiRsDefine!'
         )
     }
 
@@ -101,7 +101,7 @@ export default class LibxdfTest extends AbstractPackageTest {
         assert.isEqualDeep(
             this.loadXdfCalls[0],
             [this.path],
-            'Should have called load_xdf_to_json(path)!'
+            'Did not call load_xdf_to_json(path)!'
         )
     }
 
@@ -241,7 +241,6 @@ export default class LibxdfTest extends AbstractPackageTest {
     private static readonly fakeNominalSampleRate = 0
     private static readonly fakeEventName = generateId()
     private static readonly fakeEventTimestamp = 0
-    private static readonly fakeErrorMessage = 'Fake error message!'
 
     private static fakeSerializedXdf = `{"streams": [{"stream_id": ${this.fakeStreamId}, "time_series": [], "time_stamps": [], "stream_info": {"channel_count": ${this.fakeChannelCount}, "channel_format": "${this.fakeChannelFormat}", "nominal_srate": ${this.fakeNominalSampleRate}, "stream_name": "${this.fakeStreamName}", "stream_type": "${this.fakeStreamType}"}}], "events": [{"stream_id": ${this.fakeStreamId}, "event_name": "${this.fakeEventName}", "event_timestamp": ${this.fakeEventTimestamp}}]}`
 

package/src/impl/LiblslAdapter.ts

@@ -9,7 +9,7 @@ import {
 } from 'ffi-rs'
 
 import { CHANNEL_FORMATS } from '../consts.js'
-import { LslErrorCode } from '../lib/handleError.js'
+import { LslErrorCode } from '../lib/handleLslError.js'
 
 export default class LiblslAdapter implements Liblsl {
     public static open = open
@@ -29,20 +29,6 @@ export default class LiblslAdapter implements Liblsl {
         this.tryToLoadBindings()
     }
 
-    private tryToLoadBindings() {
-        try {
-            this.loadBindings()
-        } catch (error) {
-            this.throwFailedToLoadLiblsl(error as Error)
-        }
-    }
-
-    private throwFailedToLoadLiblsl(error: Error) {
-        throw new Error(
-            `Loading the liblsl dylib failed! I tried to load it from ${this.liblslPath}.\n\n${error.message}\n\n`
-        )
-    }
-
     public static getInstance() {
         if (!this.instance) {
             this.setInstance(new this())
@@ -58,9 +44,13 @@ export default class LiblslAdapter implements Liblsl {
         delete this.instance
     }
 
-    private loadBindings() {
-        this.openLiblsl()
-        this.bindings = this.defineLiblslBindings()
+    private tryToLoadBindings() {
+        try {
+            this.openLiblsl()
+            this.defineBindings()
+        } catch (error) {
+            this.throwFailedToLoadLiblsl(error as Error)
+        }
     }
 
     private openLiblsl() {
@@ -70,8 +60,113 @@ export default class LiblslAdapter implements Liblsl {
         })
     }
 
-    private defineLiblslBindings() {
-        return this.define(this.liblslFuncs) as LiblslBindings
+    private defineBindings() {
+        this.bindings = this.define({
+            lsl_local_clock: {
+                library: 'lsl',
+                retType: DataType.Double,
+                paramsType: [],
+            },
+            lsl_create_streaminfo: {
+                library: 'lsl',
+                retType: DataType.External,
+                paramsType: [
+                    DataType.String,
+                    DataType.String,
+                    DataType.I32,
+                    DataType.Double,
+                    DataType.I32,
+                    DataType.String,
+                ],
+            },
+            lsl_destroy_streaminfo: {
+                library: 'lsl',
+                retType: DataType.Void,
+                paramsType: [DataType.External],
+            },
+            lsl_create_outlet: {
+                library: 'lsl',
+                retType: DataType.External,
+                paramsType: [DataType.External, DataType.I32, DataType.I32],
+            },
+            lsl_push_sample_ft: {
+                library: 'lsl',
+                retType: DataType.I32,
+                paramsType: [
+                    DataType.External,
+                    DataType.FloatArray,
+                    DataType.Double,
+                ],
+            },
+            lsl_push_sample_strt: {
+                library: 'lsl',
+                retType: DataType.I32,
+                paramsType: [
+                    DataType.External,
+                    DataType.StringArray,
+                    DataType.Double,
+                ],
+            },
+            lsl_destroy_outlet: {
+                library: 'lsl',
+                retType: DataType.Void,
+                paramsType: [DataType.External],
+            },
+            lsl_create_inlet: {
+                library: 'lsl',
+                retType: DataType.External,
+                paramsType: [
+                    DataType.External,
+                    DataType.I32,
+                    DataType.I32,
+                    DataType.I32,
+                ],
+            },
+            lsl_inlet_flush: {
+                library: 'lsl',
+                retType: DataType.I32,
+                paramsType: [DataType.External],
+            },
+            lsl_destroy_inlet: {
+                library: 'lsl',
+                retType: DataType.Void,
+                paramsType: [DataType.External],
+            },
+            lsl_get_desc: {
+                library: 'lsl',
+                retType: DataType.External,
+                paramsType: [DataType.External],
+            },
+            lsl_get_channel_count: {
+                library: 'lsl',
+                retType: DataType.I32,
+                paramsType: [DataType.External],
+            },
+            lsl_append_child: {
+                library: 'lsl',
+                retType: DataType.External,
+                paramsType: [DataType.External, DataType.String],
+            },
+            lsl_append_child_value: {
+                library: 'lsl',
+                retType: DataType.External,
+                paramsType: [
+                    DataType.External,
+                    DataType.String,
+                    DataType.String,
+                ],
+            },
+        }) as LiblslBindings
+    }
+
+    private throwFailedToLoadLiblsl(error: Error) {
+        throw new Error(
+            `Loading the liblsl dylib failed! I tried to load it from ${this.liblslPath}.\n\n${error.message}\n\n`
+        )
+    }
+
+    public localClock() {
+        return this.bindings.lsl_local_clock([])
     }
 
     public createStreamInfo(options: CreateStreamInfoOptions) {
@@ -119,7 +214,7 @@ export default class LiblslAdapter implements Liblsl {
         this.bindings.lsl_destroy_streaminfo([infoHandle])
     }
 
-    public async resolveByProp(options: ResolveByPropOptions) {
+    public resolveByProp(options: ResolveByPropOptions) {
         const { prop, value, minResults = 1, timeoutMs = 1000 } = options
 
         const maxResults = 1024
@@ -134,7 +229,7 @@ export default class LiblslAdapter implements Liblsl {
             })
         )[0]
 
-        const numResults = await this.load({
+        const numResults = this.load({
             library: 'lsl',
             funcName: 'lsl_resolve_byprop',
             retType: DataType.I32,
@@ -154,7 +249,6 @@ export default class LiblslAdapter implements Liblsl {
                 minResults,
                 timeoutMs / 1000,
             ],
-            runInNewThread: true,
         })
 
         const handles: InfoHandle[] = []
@@ -233,16 +327,15 @@ export default class LiblslAdapter implements Liblsl {
         return this.bindings.lsl_get_channel_count([infoHandle])
     }
 
-    public async openStream(options: OpenStreamOptions) {
+    public openStream(options: OpenStreamOptions) {
         const { inletHandle, timeoutMs, errorCodePtr } = options
 
-        await this.load({
+        this.load({
             library: 'lsl',
             funcName: 'lsl_open_stream',
             retType: DataType.Void,
             paramsType: [DataType.External, DataType.Double, DataType.External],
             paramsValue: [inletHandle, timeoutMs / 1000, errorCodePtr],
-            runInNewThread: true,
         })
     }
 
@@ -334,10 +427,6 @@ export default class LiblslAdapter implements Liblsl {
         this.bindings.lsl_destroy_inlet([inletHandle])
     }
 
-    public localClock() {
-        return this.bindings.lsl_local_clock([])
-    }
-
     private get open() {
         return LiblslAdapter.open
     }
@@ -353,116 +442,19 @@ export default class LiblslAdapter implements Liblsl {
     private get alloc() {
         return LiblslAdapter.alloc
     }
-
-    private get liblslFuncs() {
-        return {
-            lsl_create_streaminfo: {
-                library: 'lsl',
-                retType: DataType.External,
-                paramsType: [
-                    DataType.String,
-                    DataType.String,
-                    DataType.I32,
-                    DataType.Double,
-                    DataType.I32,
-                    DataType.String,
-                ],
-            },
-            lsl_destroy_streaminfo: {
-                library: 'lsl',
-                retType: DataType.Void,
-                paramsType: [DataType.External],
-            },
-            lsl_create_outlet: {
-                library: 'lsl',
-                retType: DataType.External,
-                paramsType: [DataType.External, DataType.I32, DataType.I32],
-            },
-            lsl_push_sample_ft: {
-                library: 'lsl',
-                retType: DataType.I32,
-                paramsType: [
-                    DataType.External,
-                    DataType.FloatArray,
-                    DataType.Double,
-                ],
-            },
-            lsl_push_sample_strt: {
-                library: 'lsl',
-                retType: DataType.I32,
-                paramsType: [
-                    DataType.External,
-                    DataType.StringArray,
-                    DataType.Double,
-                ],
-            },
-            lsl_destroy_outlet: {
-                library: 'lsl',
-                retType: DataType.Void,
-                paramsType: [DataType.External],
-            },
-            lsl_create_inlet: {
-                library: 'lsl',
-                retType: DataType.External,
-                paramsType: [
-                    DataType.External,
-                    DataType.I32,
-                    DataType.I32,
-                    DataType.I32,
-                ],
-            },
-            lsl_inlet_flush: {
-                library: 'lsl',
-                retType: DataType.I32,
-                paramsType: [DataType.External],
-            },
-            lsl_destroy_inlet: {
-                library: 'lsl',
-                retType: DataType.Void,
-                paramsType: [DataType.External],
-            },
-            lsl_get_desc: {
-                library: 'lsl',
-                retType: DataType.External,
-                paramsType: [DataType.External],
-            },
-            lsl_get_channel_count: {
-                library: 'lsl',
-                retType: DataType.I32,
-                paramsType: [DataType.External],
-            },
-            lsl_append_child: {
-                library: 'lsl',
-                retType: DataType.External,
-                paramsType: [DataType.External, DataType.String],
-            },
-            lsl_append_child_value: {
-                library: 'lsl',
-                retType: DataType.External,
-                paramsType: [
-                    DataType.External,
-                    DataType.String,
-                    DataType.String,
-                ],
-            },
-            lsl_local_clock: {
-                library: 'lsl',
-                retType: DataType.Double,
-                paramsType: [],
-            },
-        }
-    }
 }
 
 export interface Liblsl {
     liblslPath: string
 
+    localClock(): number
+
     createStreamInfo(options: CreateStreamInfoOptions): InfoHandle
     destroyStreamInfo(options: DestroyStreamInfoOptions): void
     appendChannelsToStreamInfo(options: AppendChannelsToStreamInfoOptions): void
     getChannelCount(options: GetChannelCountOptions): number
 
-    resolveByProp(options: ResolveByPropOptions): Promise<InfoHandle[]>
+    resolveByProp(options: ResolveByPropOptions): InfoHandle[]
 
     createOutlet(options: CreateOutletOptions): OutletHandle
 
@@ -477,14 +469,12 @@ export interface Liblsl {
     destroyOutlet(options: DestroyOutletOptions): void
 
     createInlet(options: CreateInletOptions): InletHandle
-    openStream(options: OpenStreamOptions): Promise<void>
+    openStream(options: OpenStreamOptions): void
     closeStream(options: CloseStreamOptions): void
     pullSample(options: PullSampleOptions): number
     pullChunk(options: PullChunkOptions): number
     flushInlet(options: FlushInletOptions): void
     destroyInlet(options: DestroyInletOptions): void
-
-    localClock(): number
 }
 
 export interface CreateStreamInfoOptions {
@@ -577,6 +567,8 @@ export interface DestroyInletOptions {
 }
 
 export interface LiblslBindings {
+    lsl_local_clock(args: []): number
+
     lsl_create_streaminfo(
         args: [string, string, number, number, number, string]
     ): InfoHandle
@@ -595,8 +587,6 @@ export interface LiblslBindings {
     lsl_create_inlet(args: any): InletHandle
     lsl_inlet_flush(args: [InletHandle]): void
     lsl_destroy_inlet(args: any): void
-
-    lsl_local_clock(args: []): number
 }
 
 export type ChannelFormat = (typeof CHANNEL_FORMATS)[number]