@neurodevs/node-lsl 16.1.0 → 17.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neurodevs/node-lsl",
-  "version": "16.1.0",
+  "version": "17.1.0",
   "description": "Lab Streaming Layer (LSL) bindings for Node",
   "type": "module",
   "keywords": [
@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "@neurodevs/generate-id": "^1.0.9",
-    "ffi-rs": "^1.3.0",
-    "node-gyp": "^10.2.0",
+    "ffi-rs": "^1.3.1",
+    "node-gyp": "^12.1.0",
     "ref-array-napi": "^1.2.2",
     "ref-napi": "^3.0.3",
     "ws": "^8.18.3"
@@ -54,18 +54,18 @@
   "devDependencies": {
     "@neurodevs/node-tdd": "^0.2.2",
     "@types/ffi-napi": "^4.0.10",
-    "@types/node": "^22.9.0",
+    "@types/node": "^24.10.1",
     "@types/ws": "^8.18.1",
     "chokidar-cli": "^3.0.0",
-    "concurrently": "^9.1.0",
-    "eslint": "^9.15.0",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.39.1",
     "eslint-config-spruce": "^11.2.26",
-    "jest": "^29.7.0",
-    "jest-circus": "^29.7.0",
-    "prettier": "^3.3.3",
+    "jest": "^30.2.0",
+    "jest-circus": "^30.2.0",
+    "prettier": "^3.7.4",
     "ts-node": "^10.9.2",
-    "tsc-watch": "^6.2.1",
-    "typescript": "^5.6.3"
+    "tsc-watch": "^7.2.0",
+    "typescript": "^5.9.3"
   },
   "jest": {
     "testRunner": "jest-circus/runner",

package/src/__tests__/AbstractPackageTest.ts

@@ -78,6 +78,7 @@ export default class AbstractPackageTest extends AbstractModuleTest {
         FakeWebSocketServer.resetTestDouble()
     }
 
+    protected static readonly info = new FakeStreamInfo()
     protected static readonly name_ = this.generateId()
     protected static readonly type = this.generateId()
     protected static readonly sourceId = this.generateId()
@@ -97,19 +98,14 @@ export default class AbstractPackageTest extends AbstractModuleTest {
     protected static readonly sampleRateHz = Math.floor(Math.random() * 100)
     protected static readonly maxBufferedMs = Math.floor(Math.random() * 1000)
 
-    protected static LslStreamInlet(
+    protected static async LslStreamInlet(
         options: Partial<StreamInletOptions>,
         onData: OnDataCallback
     ) {
         const defaultOptions = {
-            sampleRateHz: 0,
-            channelNames: this.channelNames,
-            channelFormat: 'float32',
+            info: this.info,
             chunkSize: this.chunkSize,
             maxBufferedMs: this.maxBufferedMs,
-            name: this.name_,
-            type: this.type,
-            sourceId: this.sourceId,
             ...options,
         } as StreamInletOptions
 

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

@@ -196,7 +196,7 @@ export default class LslStreamInfoTest extends AbstractPackageTest {
         assert.isEqualDeep(
             this.fakeLiblsl.lastAppendChannelsToStreamInfoOptions,
             {
-                info: this.instance.getBoundInfo(),
+                info: this.instance.boundInfo,
                 channels: this.channelNames.map((label: string) => ({
                     label,
                     units: this.units,
@@ -213,15 +213,15 @@ export default class LslStreamInfoTest extends AbstractPackageTest {
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastDestroyStreamInfoOptions?.info,
-            this.instance.getBoundInfo(),
+            this.instance.boundInfo,
             'Should have called destroyStreamInfo!'
         )
     }
 
     @test()
-    protected static async doesNotCreateNewStreamInfoIfPassedBoundStreamInfo() {
+    protected static async doesNotCreateNewStreamInfoIfPassedBoundInfo() {
         this.LslStreamInfo({
-            boundStreamInfo: this.instance.getBoundInfo(),
+            boundInfo: this.instance.boundInfo,
         })
 
         assert.isEqual(
@@ -232,22 +232,33 @@ export default class LslStreamInfoTest extends AbstractPackageTest {
     }
 
     @test()
-    protected static async setsBoundStreamInfoWhenPassed() {
+    protected static async setsBoundInfoWhenPassed() {
         const instance = this.LslStreamInfo({
-            boundStreamInfo: this.instance.getBoundInfo(),
+            boundInfo: this.instance.boundInfo,
         })
 
         assert.isEqualDeep(
-            instance.getBoundInfo(),
-            this.instance.getBoundInfo(),
+            instance.boundInfo,
+            this.instance.boundInfo,
+            'Should have set bound stream info!'
+        )
+    }
+
+    @test()
+    protected static async cachesInfoAttributesByBoundInfo() {
+        const cached = LslStreamInfo.From(this.instance.boundInfo)
+
+        assert.isEqualDeep(
+            cached,
+            this.instance,
             'Should have set bound stream info!'
         )
     }
 
     private static readonly defaultOptions = {
-        name: this.generateId(),
-        type: this.generateId(),
-        sourceId: this.generateId(),
+        name: this.name,
+        type: this.type,
+        sourceId: this.sourceId,
         channelNames: this.channelNames,
         channelFormat: 'float32',
         sampleRateHz: 100 * Math.random(),

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

@@ -1,6 +1,6 @@
 import { test, assert } from '@neurodevs/node-tdd'
+
 import { StreamInletOptions } from '../../impl/LslStreamInlet.js'
-import FakeStreamInfo from '../../testDoubles/StreamInfo/FakeStreamInfo.js'
 import { SpyStreamInlet } from '../../testDoubles/StreamInlet/SpyStreamInlet.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
@@ -21,7 +21,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
         this.callsToOnData = []
 
-        this.instance = this.LslStreamInlet()
+        this.instance = await this.LslStreamInlet()
     }
 
     @test()
@@ -29,33 +29,6 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         assert.isTruthy(this.instance, 'Failed to create instance!')
     }
 
-    @test()
-    protected static async createsStreamInfoWithExpectedOptions() {
-        assert.isEqualDeep(
-            FakeStreamInfo.callsToConstructor[0],
-            {
-                channelNames: this.channelNames,
-                channelFormat: 'float32',
-                sampleRateHz: 0,
-                name: this.name_,
-                type: this.type,
-                sourceId: this.sourceId,
-            },
-            'Stream info should have expected options!'
-        )
-    }
-
-    @test()
-    protected static async uniqueNameHasSetPrefix() {
-        const instance = this.LslStreamInlet({ name: undefined })
-
-        assert.doesInclude(
-            instance.getName(),
-            'lsl-inlet-',
-            'Name should have set prefix!'
-        )
-    }
-
     @test()
     protected static async callsBindingsToCreateStreamInlet() {
         const fakeInfo = this.instance.getStreamInfo()
@@ -65,7 +38,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         assert.isEqualDeep(
             this.fakeLiblsl.lastCreateInletOptions,
             {
-                info: fakeInfo.boundStreamInfo,
+                info: fakeInfo.boundInfo,
                 maxBufferedMs: this.maxBufferedMs,
             },
             'Should have called createInlet!'
@@ -282,7 +255,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
     private static async runInletWithOptions(
         options?: Partial<StreamInletOptions>
     ) {
-        const inlet = this.LslStreamInlet(options)
+        const inlet = await this.LslStreamInlet(options)
         await this.startThenStop(inlet)
         return inlet
     }
@@ -317,12 +290,14 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         this.callsToOnData.push({ samples, timestamps })
     }
 
-    protected static LslStreamInlet(options?: Partial<StreamInletOptions>) {
-        return AbstractPackageTest.LslStreamInlet(
+    protected static async LslStreamInlet(
+        options?: Partial<StreamInletOptions>
+    ) {
+        return (await AbstractPackageTest.LslStreamInlet(
             {
                 ...options,
             },
             this.onData
-        ) as SpyStreamInlet
+        )) as SpyStreamInlet
     }
 }

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

@@ -1,10 +1,10 @@
 import { randomInt } from 'crypto'
-
 import { test, assert } from '@neurodevs/node-tdd'
 
 import LslWebSocketBridge, {
     WebSocketBridgeOptions,
 } from '../../impl/LslWebSocketBridge.js'
+import FakeStreamInfo from '../../testDoubles/StreamInfo/FakeStreamInfo.js'
 import FakeStreamInlet from '../../testDoubles/StreamInlet/FakeStreamInlet.js'
 import SpyLslWebSocketBridge from '../../testDoubles/WebSocketBridge/SpyLslWebSocketBridge.js'
 import FakeWebSocket from '../../testDoubles/WebSockets/FakeWebSocket.js'
@@ -23,7 +23,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         this.setFakeWebSocketServer()
         this.setSpyLslWebSocketBridge()
 
-        this.instance = this.LslWebSocketBridge() as SpyLslWebSocketBridge
+        this.instance =
+            (await this.LslWebSocketBridge()) as SpyLslWebSocketBridge
     }
 
     @test()
@@ -33,25 +34,15 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     @test()
     protected static async createsLslStreamInlet() {
-        const {
-            channelNames,
-            channelFormat,
-            sampleRateHz,
-            chunkSize,
-            name,
-            type,
-            sourceId,
-        } = FakeStreamInlet.callsToConstructor[0]?.options ?? {}
+        const call = FakeStreamInlet.callsToConstructor[0]
+
+        const info = call?.info
+        const chunkSize = call?.options?.chunkSize
 
         assert.isEqualDeep(
             {
-                channelNames,
-                channelFormat,
-                sampleRateHz,
+                info,
                 chunkSize,
-                name,
-                type,
-                sourceId,
             },
             this.inletOptions
         )
@@ -254,8 +245,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
     @test()
     protected static async throwsIfNeitherPortNorRemoteUrlsPassed() {
-        assert.doesThrow(() => {
-            this.LslWebSocketBridge({
+        await assert.doesThrowAsync(async () => {
+            await this.LslWebSocketBridge({
                 listenPort: undefined,
                 connectUrls: undefined,
             })
@@ -287,13 +278,8 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
     private static readonly connectUrls = [this.generateId(), this.generateId()]
 
     private static readonly inletOptions = {
-        channelNames: this.channelNames,
-        channelFormat: 'float32' as const,
-        sampleRateHz: 100 * Math.random(),
+        info: new FakeStreamInfo(),
         chunkSize: randomInt(1, 100),
-        name: this.generateId(),
-        type: this.generateId(),
-        sourceId: this.generateId(),
     }
 
     private static readonly baseOptions = {

package/src/impl/LslStreamInfo.ts

@@ -7,6 +7,8 @@ import LiblslAdapter from './LiblslAdapter.js'
 export default class LslStreamInfo implements StreamInfo {
     public static Class?: StreamInfoConstructor
 
+    private static instanceCache = new Map<BoundStreamInfo, StreamInfo>()
+
     public readonly name: string
     public readonly type: string
     public readonly sourceId: string
@@ -15,26 +17,20 @@ export default class LslStreamInfo implements StreamInfo {
     public readonly channelFormat: ChannelFormat
     public readonly sampleRateHz: number
     public readonly units: string
-
-    protected boundInfo!: BoundStreamInfo
-
-    private readonly defaultName = `lsl-stream-info-${generateId()}`
-    private readonly defaultType = generateId()
-    private readonly defaultSourceId = generateId()
-    private readonly defaultUnits = 'N/A'
+    public readonly boundInfo: BoundStreamInfo
 
     private lsl = LiblslAdapter.getInstance()
 
     protected constructor(options: StreamInfoOptions) {
         const {
-            name = this.defaultName,
-            type = this.defaultType,
-            sourceId = this.defaultSourceId,
+            name = `lsl-stream-info-${generateId()}`,
+            type = generateId(),
+            sourceId = generateId(),
             channelNames,
             channelFormat,
             sampleRateHz,
-            units = this.defaultUnits,
-            boundStreamInfo,
+            units = 'N/A',
+            boundInfo,
         } = options
 
         this.name = name
@@ -46,20 +42,29 @@ export default class LslStreamInfo implements StreamInfo {
         this.sampleRateHz = sampleRateHz
         this.units = units
 
-        if (!boundStreamInfo) {
-            this.createStreamInfo()
+        if (!boundInfo) {
+            this.boundInfo = this.createStreamInfo()
             this.appendChannelsToStreamInfo()
         } else {
-            this.boundInfo = boundStreamInfo
+            this.boundInfo = boundInfo
         }
     }
 
     public static Create(options: StreamInfoOptions) {
-        return new (this.Class ?? this)(options)
+        const instance = new (this.Class ?? this)(options)
+
+        const { boundInfo: handle } = instance
+        this.instanceCache.set(handle, instance)
+
+        return instance
+    }
+
+    public static From(handle: BoundStreamInfo) {
+        return this.instanceCache.get(handle)!
     }
 
     private createStreamInfo() {
-        this.boundInfo = this.lsl.createStreamInfo({
+        return this.lsl.createStreamInfo({
             name: this.name,
             type: this.type,
             sourceId: this.sourceId,
@@ -87,10 +92,6 @@ export default class LslStreamInfo implements StreamInfo {
     public destroy() {
         this.lsl.destroyStreamInfo({ info: this.boundInfo })
     }
-
-    public get boundStreamInfo() {
-        return this.boundInfo
-    }
 }
 
 export interface StreamInfo {
@@ -103,7 +104,7 @@ export interface StreamInfo {
     readonly channelCount: number
     readonly channelFormat: ChannelFormat
     readonly sampleRateHz: number
-    readonly boundStreamInfo: BoundStreamInfo
+    readonly boundInfo: BoundStreamInfo
 }
 
 type StreamInfoConstructor = new (options: StreamInfoOptions) => StreamInfo
@@ -116,5 +117,5 @@ export interface StreamInfoOptions {
     type?: string
     sourceId?: string
     units?: string
-    boundStreamInfo?: BoundStreamInfo
+    boundInfo?: BoundStreamInfo
 }

package/src/impl/LslStreamInlet.ts

@@ -1,13 +1,9 @@
-import generateId from '@neurodevs/generate-id'
 import { createPointer, DataType, JsExternal, unwrapPointer } from 'ffi-rs'
 
 import handleError from '../handleError.js'
-import { BoundInlet, ChannelFormat } from './LiblslAdapter.js'
+import { BoundInlet } from './LiblslAdapter.js'
 import LiblslAdapter from './LiblslAdapter.js'
-import LslStreamInfo, {
-    StreamInfo,
-    StreamInfoOptions,
-} from './LslStreamInfo.js'
+import { StreamInfo } from './LslStreamInfo.js'
 
 export default class LslStreamInlet implements StreamInlet {
     public static Class?: StreamInletConstructor
@@ -15,13 +11,10 @@ export default class LslStreamInlet implements StreamInlet {
     public isRunning = false
 
     protected info: StreamInfo
-    protected name: string
-    private channelNames: string[]
     private channelCount: number
     private chunkSize: number
     private maxBufferedMs: number
     private timeoutMs: number
-
     private onData: OnDataCallback
 
     protected inlet!: BoundInlet
@@ -40,28 +33,19 @@ export default class LslStreamInlet implements StreamInlet {
     private errorCodeBuffer!: Buffer<ArrayBuffer>
     private errorCodeBufferPtr!: JsExternal
 
-    private readonly defaultName = `lsl-inlet-${generateId()}`
     private readonly sixMinutesInMs = 360 * 1000
 
     private lsl = LiblslAdapter.getInstance()
 
     protected constructor(
         info: StreamInfo,
-        options: StreamInletOptions,
+        options: StreamInletConstructorOptions,
         onData: OnDataCallback
     ) {
-        const {
-            name = this.defaultName,
-            channelNames,
-            chunkSize,
-            maxBufferedMs,
-            timeoutMs,
-        } = options ?? {}
+        const { chunkSize, maxBufferedMs, timeoutMs } = options ?? {}
 
         this.info = info
-        this.name = name
-        this.channelNames = channelNames
-        this.channelCount = this.channelNames.length
+        this.channelCount = this.info.channelCount
         this.chunkSize = chunkSize
         this.maxBufferedMs = maxBufferedMs ?? this.sixMinutesInMs
         this.timeoutMs = timeoutMs ?? 0
@@ -71,13 +55,11 @@ export default class LslStreamInlet implements StreamInlet {
         this.createBoundInlet()
     }
 
-    public static Create(options: StreamInletOptions, onData: OnDataCallback) {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { maxBufferedMs, chunkSize, ...rest } = options
-        const infoOptions: StreamInfoOptions = rest
-
-        const info = this.LslStreamInfo(infoOptions)
-
+    public static async Create(
+        options: StreamInletOptions,
+        onData: OnDataCallback
+    ) {
+        const { info } = options
         return new (this.Class ?? this)(info, options, onData)
     }
 
@@ -91,15 +73,11 @@ export default class LslStreamInlet implements StreamInlet {
 
     private createBoundInlet() {
         this.inlet = this.lsl.createInlet({
-            info: this.boundStreamInfo,
+            info: this.info.boundInfo,
             maxBufferedMs: this.maxBufferedMs,
         })
     }
 
-    private get boundStreamInfo() {
-        return this.info.boundStreamInfo
-    }
-
     public startPulling() {
         this.isRunning = true
 
@@ -266,10 +244,6 @@ export default class LslStreamInlet implements StreamInlet {
     private destroyBoundInlet() {
         this.lsl.destroyInlet({ inlet: this.inlet })
     }
-
-    private static LslStreamInfo(options: StreamInfoOptions) {
-        return LslStreamInfo.Create(options)
-    }
 }
 
 export interface StreamInlet {
@@ -282,24 +256,19 @@ export interface StreamInlet {
 
 export type StreamInletConstructor = new (
     info: StreamInfo,
-    options: StreamInletOptions,
+    options: StreamInletConstructorOptions,
     onData: OnDataCallback
 ) => StreamInlet
 
 export interface StreamInletOptions {
-    channelNames: string[]
-    channelFormat: ChannelFormat
-    sampleRateHz: number
+    info: StreamInfo
     chunkSize: number
     maxBufferedMs?: number
     timeoutMs?: number
-    name?: string
-    type?: string
-    sourceId?: string
-    manufacturer?: string
-    units?: string
 }
 
+export type StreamInletConstructorOptions = Omit<StreamInletOptions, 'info'>
+
 export type OnDataCallback = (
     samples: Float32Array,
     timestamps: Float64Array

package/src/impl/LslStreamOutlet.ts

@@ -21,6 +21,7 @@ import LslStreamInfo, {
 export default class LslStreamOutlet implements StreamOutlet {
     public static Class?: StreamOutletConstructor
 
+    public readonly info: StreamInfo
     public readonly name: string
     public readonly type: string
     public readonly sourceId: string
@@ -33,7 +34,6 @@ export default class LslStreamOutlet implements StreamOutlet {
     public readonly manufacturer: string = 'N/A'
     public readonly units: string = 'N/A'
 
-    private info: StreamInfo
     private boundOutlet!: BoundOutlet
     private pushSampleMethod!: (options: unknown) => LslErrorCode
 
@@ -109,16 +109,12 @@ export default class LslStreamOutlet implements StreamOutlet {
 
     private createStreamOutlet() {
         this.boundOutlet = this.lsl.createOutlet({
-            info: this.boundStreamInfo,
+            info: this.info.boundInfo,
             chunkSize: this.chunkSize,
             maxBufferedMs: this.maxBufferedMs,
         })
     }
 
-    private get boundStreamInfo() {
-        return this.info.boundStreamInfo
-    }
-
     private setPushSampleMethod() {
         this.pushSampleMethod = (
             this.lsl[this.pushMethod] as (options: unknown) => LslErrorCode
@@ -146,12 +142,12 @@ export default class LslStreamOutlet implements StreamOutlet {
     }
 
     public destroy() {
-        this.destroyBoundStreamInfo()
+        this.destroyBoundInfo()
         this.destroyBoundOutlet()
     }
 
-    private destroyBoundStreamInfo() {
-        this.lsl.destroyStreamInfo({ info: this.boundStreamInfo })
+    private destroyBoundInfo() {
+        this.lsl.destroyStreamInfo({ info: this.info.boundInfo })
     }
 
     private destroyBoundOutlet() {
@@ -190,6 +186,7 @@ export default class LslStreamOutlet implements StreamOutlet {
 export interface StreamOutlet {
     pushSample(sample: LslSample): void
     destroy(): void
+    readonly info: StreamInfo
     readonly name: string
     readonly type: string
     readonly sourceId: string

package/src/impl/LslWebSocketBridge.ts

@@ -1,5 +1,5 @@
 import WebSocket, { WebSocketServer } from 'ws'
-import { ChannelFormat } from './LiblslAdapter.js'
+import { StreamInfo } from './LslStreamInfo.js'
 import LslStreamInlet, {
     StreamInlet,
     StreamInletOptions,
@@ -26,14 +26,14 @@ export default class LslWebSocketBridge implements WebSocketBridge {
         this.throwIfNoLocalServerOrRemoteSockets()
     }
 
-    public static Create(options: WebSocketBridgeOptions) {
+    public static async Create(options: WebSocketBridgeOptions) {
         const { listenPort, connectUrls, ...rest } = options
         const inletOptions: StreamInletOptions = rest
 
         const localServer = this.WebSocketServer(listenPort)
         const remoteSockets = this.createSocketsFrom(connectUrls)
 
-        const inlet = this.LslStreamInlet(
+        const inlet = await this.LslStreamInlet(
             inletOptions,
             localServer,
             remoteSockets
@@ -154,7 +154,7 @@ export default class LslWebSocketBridge implements WebSocketBridge {
         return listenPort ? new this.WSS({ port: listenPort }) : undefined
     }
 
-    private static LslStreamInlet(
+    private static async LslStreamInlet(
         options: StreamInletOptions,
         localServer?: WebSocketServer,
         remoteSockets?: WebSocket[]
@@ -175,19 +175,13 @@ export type WebSocketBridgeConstructor = new (
 ) => WebSocketBridge
 
 export interface WebSocketBridgeOptions {
-    channelNames: string[]
-    channelFormat: ChannelFormat
-    sampleRateHz: number
+    info: StreamInfo
     chunkSize: number
-    name?: string
-    type?: string
-    sourceId?: string
     listenPort?: number
     connectUrls?: string | string[]
 }
 
-export interface WebSocketBridgeConstructorOptions
-    extends WebSocketBridgeOptions {
+export interface WebSocketBridgeConstructorOptions extends WebSocketBridgeOptions {
     inlet: StreamInlet
     localServer?: WebSocketServer
     remoteSockets?: WebSocket[]