@neurodevs/ndx-native 0.0.1

package/src/impl/LibxdfAdapter.ts

@@ -0,0 +1,227 @@
+import fs from 'fs'
+import {
+    MangledNameExtractor,
+    MangledNameMap,
+} from '@neurodevs/node-mangled-names'
+import { DataType, define, FieldType, FuncObj, open } from 'ffi-rs'
+
+export default class LibxdfAdapter implements Libxdf {
+    public static Class?: LibxdfConstructor
+    public static ffiRsOpen = open
+    public static ffiRsDefine = define
+    private static readonly loadXdfName = 'load_xdf_to_json'
+    private static unmangledNames = [this.loadXdfName]
+
+    protected bindings!: LibxdfBindings
+    private libxdfPath: string
+    private mangledNameMap: MangledNameMap
+
+    protected constructor(libxdfPath: string, mangledNameMap: MangledNameMap) {
+        this.libxdfPath = libxdfPath
+        this.mangledNameMap = mangledNameMap
+
+        this.tryToLoadBindings()
+    }
+
+    public static async Create(
+        libxdfPath: string,
+        throwIfPathNotExists = true
+    ) {
+        if (throwIfPathNotExists && !fs.existsSync(libxdfPath)) {
+            throw new Error(this.generateFailedMessage(libxdfPath))
+        }
+
+        const mangledNameMap = await this.loadMangledNameMap(libxdfPath)
+        return new (this.Class ?? this)(libxdfPath, mangledNameMap)
+    }
+
+    private tryToLoadBindings() {
+        try {
+            this.bindings = this.loadBindings()
+        } catch (err: unknown) {
+            this.throwFailedToLoadLiblsl(err)
+        }
+    }
+
+    private loadBindings() {
+        this.openLibxdf()
+        return this.defineBindings()
+    }
+
+    private openLibxdf() {
+        LibxdfAdapter.ffiRsOpen({
+            library: 'xdf',
+            path: this.libxdfPath,
+        })
+    }
+
+    private defineBindings() {
+        const funcs = this.unmangledNames.reduce((acc, name) => {
+            const mangledName = this.mangledNameMap[name].slice(1)
+
+            // @ts-ignore
+            acc[mangledName] = {
+                library: 'xdf',
+                retType: DataType.String,
+                paramsType: [DataType.String],
+            }
+            return acc
+        }, {})
+
+        return LibxdfAdapter.ffiRsDefine(funcs)
+    }
+
+    private throwFailedToLoadLiblsl(err: unknown) {
+        throw new Error(this.generateFailedMessage(err))
+    }
+
+    private generateFailedMessage(err: unknown) {
+        return `
+			${LibxdfAdapter.generateFailedMessage(this.libxdfPath)}
+            \n ${err}
+            \n
+		`
+    }
+
+    public loadXdf(path: string) {
+        const mangledName = this.mangledNameMap[this.loadXdfName].slice(1)
+        const mangledFunc = this.bindings[mangledName]
+
+        const serializedData = mangledFunc([path])
+        const parsedData = JSON.parse(serializedData) as LibxdfFile
+
+        if (!parsedData.events) {
+            parsedData.events = []
+        }
+
+        const mappedStreams = parsedData.streams.map((stream) => ({
+            id: stream.stream_id,
+            name: stream.stream_info.stream_name,
+            type: stream.stream_info.stream_type,
+            channelCount: stream.stream_info.channel_count,
+            channelFormat: stream.stream_info.channel_format,
+            nominalSampleRateHz: stream.stream_info.nominal_srate,
+            data: stream.time_series,
+            timestamps: stream.time_stamps,
+        }))
+
+        const mappedEvents = parsedData.events.map((event) => ({
+            name: event.event_name,
+            timestamp: event.event_timestamp,
+            streamId: event.stream_id,
+        }))
+
+        return {
+            path,
+            streams: mappedStreams,
+            events: mappedEvents,
+        }
+    }
+
+    private get unmangledNames() {
+        return LibxdfAdapter.unmangledNames
+    }
+
+    private get loadXdfName() {
+        return LibxdfAdapter.loadXdfName
+    }
+
+    private static generateFailedMessage(libxdfPath: string) {
+        return `
+			\n -----------------------------------
+			\n Failed to load libxdf! Tried to load from: 
+			\n     ${libxdfPath}
+			\n Instructions to save your day (on MacOS):
+			\n     1. git clone https://github.com/neurodevs/libxdf.git
+			\n     2. cd libxdf && cmake -S . -B build && cmake --build build
+			\n     3. sudo cp build/libxdf.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 Check the official repo for OS-specific instructions:
+			\n     https://github.com/xdf-modules/libxdf
+			\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/node-xdf/issues
+			\n Good luck!
+			\n @ericthecurious
+			\n -----------------------------------
+        `
+    }
+
+    private static async loadMangledNameMap(libxdfPath: string) {
+        const extractor = this.MangledNameExtractor()
+        return await extractor.extract(libxdfPath, this.unmangledNames)
+    }
+
+    private static MangledNameExtractor() {
+        return MangledNameExtractor.Create()
+    }
+}
+
+export interface Libxdf {
+    loadXdf(path: string): XdfFile
+}
+
+export type LibxdfConstructor = new (
+    libxdfPath: string,
+    mangledNameMap: MangledNameMap
+) => Libxdf
+
+export type LibxdfBindings = Record<string, (path: string[]) => string>
+
+export type LibxdfStatusCode = 0 | Exclude<number, 0>
+
+export type FfiRsDefineOptions = FuncObj<
+    FieldType,
+    boolean | undefined,
+    boolean | undefined
+>
+
+export interface XdfFile {
+    path: string
+    streams: XdfStream[]
+    events: XdfEvent[]
+}
+
+export interface XdfStream {
+    id: number
+    name: string
+    type: string
+    channelCount: number
+    channelFormat: string
+    nominalSampleRateHz: number
+    data: number[][]
+    timestamps: number[]
+}
+
+export interface XdfEvent {
+    name: string
+    timestamp: number
+    streamId: number
+}
+
+export interface LibxdfFile {
+    streams: LibxdfStream[]
+    events: LibxdfEvent[]
+}
+
+export interface LibxdfStream {
+    stream_id: number
+    stream_info: LibxdfStreamInfo
+    time_series: number[][]
+    time_stamps: number[]
+}
+
+export interface LibxdfStreamInfo {
+    channel_count: number
+    channel_format: string
+    nominal_srate: number
+    stream_name: string
+    stream_type: string
+}
+
+export interface LibxdfEvent {
+    stream_id: number
+    event_name: string
+    event_timestamp: number
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// Labrecorder
+
+export { default as LabrecorderAdapter } from './impl/LabrecorderAdapter.js'
+export * from './impl/LabrecorderAdapter.js'
+
+export { default as FakeLabrecorder } from './testDoubles/Labrecorder/FakeLabrecorder.js'
+export * from './testDoubles/Labrecorder/FakeLabrecorder.js'
+
+// Liblsl
+
+export { default as LiblslAdapter } from './impl/LiblslAdapter.js'
+export * from './impl/LiblslAdapter.js'
+
+export { default as FakeLiblsl } from './testDoubles/Liblsl/FakeLiblsl.js'
+export * from './testDoubles/Liblsl/FakeLiblsl.js'
+
+// Libxdf
+
+export { default as LibxdfAdapter } from './impl/LibxdfAdapter.js'
+export * from './impl/LibxdfAdapter.js'
+
+export { default as FakeLibxdf } from './testDoubles/Libxdf/FakeLibxdf.js'
+export * from './testDoubles/Libxdf/FakeLibxdf.js'
+
+export { default as SpyLibxdf } from './testDoubles/Libxdf/SpyLibxdf.js'
+export * from './testDoubles/Libxdf/SpyLibxdf.js'

package/src/lib/handleError.ts

@@ -0,0 +1,24 @@
+export default function handleError(errorCode: number) {
+    switch (errorCode) {
+        case 0:
+            return
+        case -1:
+            throw new Error(`The liblsl operation failed due to a timeout!`)
+        case -2:
+            throw new Error(`The liblsl stream has been lost!`)
+        case -3:
+            throw new Error(`A liblsl argument was incorrectly specified!`)
+        case -4:
+            throw new Error(`An internal liblsl error has occurred!`)
+        default:
+            throw new Error(`An unknown liblsl error has occurred!`)
+    }
+}
+
+export enum LslErrorCode {
+    Ok = 0,
+    Timeout = -1,
+    Lost = -2,
+    BadArgument = -3,
+    InternalError = -4,
+}

package/src/testDoubles/Labrecorder/FakeLabrecorder.ts

@@ -0,0 +1,37 @@
+import { RecordingHandle, Labrecorder } from '../../impl/LabrecorderAdapter.js'
+
+export default class FakeLabrecorder implements Labrecorder {
+    public static constructorCalls: string[] = []
+
+    public static createRecordingCalls: {
+        filename: string
+        watchFor: string[]
+    }[] = []
+
+    public static stopRecordingCalls: RecordingHandle[] = []
+    public static deleteRecordingCalls: RecordingHandle[] = []
+
+    public constructor(labrecorderPath: string) {
+        FakeLabrecorder.constructorCalls.push(labrecorderPath)
+    }
+
+    public createRecording(filename: string, watchFor: string[]) {
+        FakeLabrecorder.createRecordingCalls.push({ filename, watchFor })
+        return {} as RecordingHandle
+    }
+
+    public stopRecording(recording: RecordingHandle) {
+        FakeLabrecorder.stopRecordingCalls.push(recording)
+    }
+
+    public deleteRecording(recording: RecordingHandle) {
+        FakeLabrecorder.deleteRecordingCalls.push(recording)
+    }
+
+    public static resetTestDouble() {
+        this.constructorCalls = []
+        this.createRecordingCalls = []
+        this.stopRecordingCalls = []
+        this.deleteRecordingCalls = []
+    }
+}

package/src/testDoubles/Liblsl/FakeLiblsl.ts

@@ -0,0 +1,204 @@
+import generateId from '@neurodevs/generate-id'
+
+import {
+    OutletHandle,
+    InfoHandle,
+    CreateStreamInfoOptions,
+    AppendChannelsToStreamInfoOptions,
+    CreateOutletOptions,
+    PushSampleFloatTimestampOptions,
+    PushSampleStringTimestampOptions,
+    Liblsl,
+    CreateInletOptions,
+    DestroyInletOptions,
+    InletHandle,
+    FlushInletOptions,
+    PullChunkOptions,
+    PullSampleOptions,
+    DestroyStreamInfoOptions,
+    ResolveByPropOptions,
+    DestroyOutletOptions,
+    OpenStreamOptions,
+    CloseStreamOptions,
+    GetChannelCountOptions,
+} from 'impl/LiblslAdapter.js'
+
+export default class FakeLiblsl implements Liblsl {
+    public static fakeInfoHandles: InfoHandle[] = []
+
+    public static fakeSamples: Float32Array[] = [
+        new Float32Array([1, 2, 3]),
+        new Float32Array([4, 5, 6]),
+    ]
+
+    public static fakeChunks: Float32Array[] = [
+        new Float32Array([1, 2, 3, 4, 5, 6]),
+        new Float32Array([1, 2, 3, 4, 5, 6]),
+    ]
+
+    public static fakeTimestamps: Float64Array[] = [
+        new Float64Array([7, 8]),
+        new Float64Array([7, 8]),
+    ]
+
+    public static fakeChannelCount = 3
+    public static fakeErrorCode = 0
+
+    public liblslPath: string = generateId()
+
+    public fakeSamples = FakeLiblsl.fakeSamples.slice()
+    public fakeChunks = FakeLiblsl.fakeChunks.slice()
+    public fakeTimestamps = FakeLiblsl.fakeTimestamps.slice()
+
+    public outletHandle: OutletHandle = {} as OutletHandle
+    public infoHandle: InfoHandle = {} as InfoHandle
+
+    public lastCreateStreamInfoOptions?: CreateStreamInfoOptions
+    public lastAppendChannelsToStreamInfoOptions?: AppendChannelsToStreamInfoOptions
+    public lastDestroyStreamInfoOptions?: DestroyStreamInfoOptions
+    public lastResolveByPropOptions?: ResolveByPropOptions
+    public lastGetChannelCountOptions?: GetChannelCountOptions
+
+    public lastCreateOutletOptions?: CreateOutletOptions
+    public lastPushSampleFloatTimestampOptions?: PushSampleFloatTimestampOptions
+    public lastPushSampleStringTimestampOptions?: PushSampleStringTimestampOptions
+    public lastDestroyOutletOptions?: DestroyOutletOptions
+
+    public lastCreateInletOptions?: CreateInletOptions
+    public lastOpenStreamOptions?: OpenStreamOptions
+    public lastCloseStreamOptions?: CloseStreamOptions
+    public lastPullSampleOptions?: PullSampleOptions
+    public lastPullChunkOptions?: PullChunkOptions
+    public lastFlushInletOptions?: FlushInletOptions
+    public lastDestroyInletOptions?: DestroyInletOptions
+
+    public createStreamInfoHitCount = 0
+    public createOutletHitCount = 0
+    public destroyOutletHitCount = 0
+    public createInletHitCount = 0
+    public flushInletHitCount = 0
+    public destroyInletHitCount = 0
+    public localClockHitCount = 0
+    public pushSampleStringTimestampHitCount = 0
+
+    public createStreamInfo(options: CreateStreamInfoOptions) {
+        this.createStreamInfoHitCount++
+        this.lastCreateStreamInfoOptions = options
+        return this.infoHandle
+    }
+
+    public appendChannelsToStreamInfo(
+        options: AppendChannelsToStreamInfoOptions
+    ) {
+        this.lastAppendChannelsToStreamInfoOptions = options
+    }
+
+    public getChannelCount(options: GetChannelCountOptions) {
+        this.lastGetChannelCountOptions = options
+        return FakeLiblsl.fakeChannelCount
+    }
+
+    public destroyStreamInfo(options: DestroyStreamInfoOptions) {
+        this.lastDestroyStreamInfoOptions = options
+    }
+
+    public async resolveByProp(options: ResolveByPropOptions) {
+        this.lastResolveByPropOptions = options
+        return FakeLiblsl.fakeInfoHandles
+    }
+
+    public pushSampleFloatTimestamp(options: PushSampleFloatTimestampOptions) {
+        this.lastPushSampleFloatTimestampOptions = options
+        return FakeLiblsl.fakeErrorCode
+    }
+
+    public pushSampleStringTimestamp(
+        options: PushSampleStringTimestampOptions
+    ) {
+        this.lastPushSampleStringTimestampOptions = options
+        this.pushSampleStringTimestampHitCount++
+        return FakeLiblsl.fakeErrorCode
+    }
+
+    public createOutlet(options: CreateOutletOptions) {
+        this.createOutletHitCount++
+        this.lastCreateOutletOptions = options
+        return this.outletHandle
+    }
+
+    public destroyOutlet(options: DestroyOutletOptions) {
+        this.destroyOutletHitCount++
+        this.lastDestroyOutletOptions = options
+    }
+
+    public createInlet(options: CreateInletOptions) {
+        this.createInletHitCount++
+        this.lastCreateInletOptions = options
+        return {} as InletHandle
+    }
+
+    public async openStream(options: OpenStreamOptions) {
+        this.lastOpenStreamOptions = options
+    }
+
+    public async closeStream(options: CloseStreamOptions) {
+        this.lastCloseStreamOptions = options
+    }
+
+    public pullSample(options: PullSampleOptions) {
+        this.lastPullSampleOptions = options
+
+        const sample = this.fakeSamples.shift()
+
+        if (sample) {
+            return 1
+        }
+
+        return 0
+    }
+
+    public pullChunk(options: PullChunkOptions) {
+        this.lastPullChunkOptions = options
+
+        const chunk = this.fakeChunks.shift()
+        const timestamps = this.fakeTimestamps.shift()
+
+        if (chunk && timestamps) {
+            return 1
+        }
+
+        return 0
+    }
+
+    public flushInlet(options: FlushInletOptions) {
+        this.flushInletHitCount++
+        this.lastFlushInletOptions = options
+    }
+
+    public destroyInlet(options: DestroyInletOptions) {
+        this.destroyInletHitCount++
+        this.lastDestroyInletOptions = options
+    }
+
+    public localClock() {
+        this.localClockHitCount++
+        return new Date().getTime()
+    }
+
+    public resetTestDouble() {
+        this.lastCreateStreamInfoOptions = undefined
+        this.lastAppendChannelsToStreamInfoOptions = undefined
+        this.lastCreateOutletOptions = undefined
+        this.lastPushSampleFloatTimestampOptions = undefined
+        this.lastPushSampleStringTimestampOptions = undefined
+
+        this.createStreamInfoHitCount = 0
+        this.destroyOutletHitCount = 0
+        this.localClockHitCount = 0
+        this.pushSampleStringTimestampHitCount = 0
+
+        this.fakeSamples = FakeLiblsl.fakeSamples.slice()
+        this.fakeChunks = FakeLiblsl.fakeChunks.slice()
+        this.fakeTimestamps = FakeLiblsl.fakeTimestamps.slice()
+    }
+}

package/src/testDoubles/Libxdf/FakeLibxdf.ts

@@ -0,0 +1,33 @@
+import { MangledNameMap } from '@neurodevs/node-mangled-names'
+
+import { Libxdf, XdfFile } from '../../impl/LibxdfAdapter.js'
+
+export default class FakeLibxdf implements Libxdf {
+    public static libxdfPath?: string
+    public static loadXdfCalls: string[] = []
+    public static mangledNameMap: MangledNameMap
+    public static fakeXdfFile: XdfFile = { path: '', streams: [], events: [] }
+
+    public constructor(libxdfPath: string, mangledNameMap: MangledNameMap) {
+        FakeLibxdf.libxdfPath = libxdfPath
+        FakeLibxdf.mangledNameMap = mangledNameMap
+    }
+
+    public loadXdf(path: string) {
+        FakeLibxdf.loadXdfCalls.push(path)
+        return this.fakeXdfFile
+    }
+
+    public get mangledNameMap() {
+        return FakeLibxdf.mangledNameMap
+    }
+
+    public get fakeXdfFile() {
+        return FakeLibxdf.fakeXdfFile
+    }
+
+    public static resetTestDouble() {
+        FakeLibxdf.libxdfPath = undefined
+        FakeLibxdf.loadXdfCalls = []
+    }
+}

package/src/testDoubles/Libxdf/SpyLibxdf.ts

@@ -0,0 +1,13 @@
+import { MangledNameMap } from '@neurodevs/node-mangled-names'
+
+import LibxdfAdapter from '../../impl/LibxdfAdapter.js'
+
+export default class SpyLibxdf extends LibxdfAdapter {
+    public constructor(libxdfPath: string, mangledNameMap: MangledNameMap) {
+        super(libxdfPath, mangledNameMap)
+    }
+
+    public getBindings() {
+        return this.bindings
+    }
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+	"compilerOptions": {
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"target": "ES2022",
+		"lib": ["ES2022"],
+		"types": ["node"],
+		"baseUrl": "src",
+		"outDir": "build",
+		"sourceMap": false,
+		"strict": true,
+		"noImplicitAny": true,
+		"noImplicitReturns": true,
+		"noUnusedLocals": true,
+		"forceConsistentCasingInFileNames": true,
+		"declaration": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"moduleDetection": "force",
+		"allowJs": true,
+		"resolveJsonModule": true,
+		"experimentalDecorators": true
+	},
+	"include": [
+		"src/*.ts",
+		"src/**/*.ts"
+	]
+}