@neurodevs/node-lsl 14.1.5 → 16.0.0

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

@@ -18,6 +18,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         await super.beforeEach()
 
         this.setFakeStreamInlet()
+        this.setFakeWebSocket()
         this.setFakeWebSocketServer()
         this.setSpyLslWebSocketBridge()
 
@@ -51,7 +52,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
                 type,
                 sourceId,
             },
-            this.baseOptions
+            this.inletOptions
         )
     }
 
@@ -93,7 +94,7 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
     protected static async createsWebSocketServer() {
         assert.isEqualDeep(
             FakeWebSocketServer.callsToConstructor[0],
-            { port: this.wssPort },
+            { port: this.listenPort },
             'Did not create WebSocketServer!'
         )
     }
@@ -129,8 +130,14 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         this.activate()
         this.simulateOnDataCallback()
 
+        const calls = FakeWebSocket.callsToSend.filter((call) =>
+            Array.from(FakeWebSocketServer.clients).some(
+                (client) => client.id === call.id
+            )
+        )
+
         assert.isEqual(
-            FakeWebSocket.callsToSend.length,
+            calls.length,
             0,
             'Sent data to clients that are not ready!'
         )
@@ -153,22 +160,105 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
 
         assert.doesThrow(() => {
             this.activate()
-        }, `\n\n Cannot re-activate bridge after destroying it! \n\n Please create and activate a new instance. \n`)
+        }, `\n\n Cannot activate bridge after destroying it! \n\n Please create and activate a new instance. \n`)
     }
 
     @test()
-    protected static async acceptsOptionalWssPort() {
-        FakeWebSocketServer.resetTestDouble()
-
-        const wssPort = randomInt(1000, 9999)
+    protected static async throwsIfDeactivateIsCalledAfterDestroy() {
+        this.destroy()
 
-        this.LslWebSocketBridge({ wssPort })
+        assert.doesThrow(() => {
+            this.deactivate()
+        }, `\n\n Cannot deactivate bridge after destroying it! \n\n Please create and activate a new instance. \n`)
+    }
 
+    @test()
+    protected static async createsWebSocketServerFromPort() {
         assert.isEqual(
             FakeWebSocketServer.callsToConstructor[0]?.port,
-            wssPort,
-            'Did not set port for WebSocketServer!'
+            this.listenPort,
+            'Did not create WebSocketServer with port!'
+        )
+    }
+
+    @test()
+    protected static async createsSocketsFromRemoteUrls() {
+        assert.isEqualDeep(
+            FakeWebSocket.callsToConstructor,
+            this.connectUrls,
+            'Did not create WebSockets for remote URLs!'
+        )
+    }
+
+    @test()
+    protected static async activateSendsDataToRemoteSockets() {
+        this.activate()
+
+        const { samples, timestamps } = this.simulateOnDataCallback()
+
+        const expectedPayload = JSON.stringify({
+            samples,
+            timestamps,
+        })
+
+        assert.isAbove(
+            FakeWebSocket.callsToSend.length,
+            0,
+            'Did not send data to remote sockets!'
         )
+
+        for (const call of FakeWebSocket.callsToSend) {
+            assert.isEqualDeep(
+                call.data,
+                expectedPayload,
+                'Did not send data to remote sockets!'
+            )
+        }
+    }
+
+    @test()
+    protected static async doesNotSendToRemoteSocketsThatAreNotReady() {
+        const sockets = this.instance[
+            'remoteSockets'
+        ]! as unknown as FakeWebSocket[]
+
+        for (const socket of sockets) {
+            socket.readyState = WebSocket.CONNECTING
+        }
+
+        this.activate()
+        this.simulateOnDataCallback()
+
+        const calls = FakeWebSocket.callsToSend.filter((call) =>
+            sockets.some((socket) => socket.id === call.id)
+        )
+
+        assert.isEqual(
+            calls.length,
+            0,
+            'Sent data to sockets that are not ready!'
+        )
+    }
+
+    @test()
+    protected static async destroyClosesRemoteWebSockets() {
+        this.destroy()
+
+        assert.isEqual(
+            FakeWebSocket.numCallsToClose,
+            this.connectUrls.length,
+            'Did not close remote WebSockets!'
+        )
+    }
+
+    @test()
+    protected static async throwsIfNeitherPortNorRemoteUrlsPassed() {
+        assert.doesThrow(() => {
+            this.LslWebSocketBridge({
+                listenPort: undefined,
+                connectUrls: undefined,
+            })
+        }, `At least one of listenPort or connectUrls must be provided!`)
     }
 
     private static activate() {
@@ -191,9 +281,11 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         return { samples, timestamps }
     }
 
-    private static readonly wssPort = 8080
+    private static readonly listenPort = randomInt(1000, 5000)
 
-    private static readonly baseOptions = {
+    private static readonly connectUrls = [this.generateId(), this.generateId()]
+
+    private static readonly inletOptions = {
         channelNames: this.channelNames,
         channelFormat: 'float32' as const,
         sampleRateHz: 100 * Math.random(),
@@ -203,6 +295,12 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
         sourceId: this.generateId(),
     }
 
+    private static readonly baseOptions = {
+        ...this.inletOptions,
+        listenPort: this.listenPort,
+        connectUrls: this.connectUrls,
+    }
+
     private static LslWebSocketBridge(
         options?: Partial<WebSocketBridgeOptions>
     ) {

package/src/impl/LslStreamInfo.ts

@@ -7,14 +7,18 @@ import LiblslAdapter from './LiblslAdapter.js'
 export default class LslStreamInfo implements StreamInfo {
     public static Class?: StreamInfoConstructor
 
-    protected name: string
-    protected type: string
-    protected sourceId: string
-    protected units: string
+    private static instanceCache: Record<string, StreamInfo> = {}
+
+    public readonly name: string
+    public readonly type: string
+    public readonly sourceId: string
+    public readonly channelNames: string[]
+    public readonly channelCount: number
+    public readonly channelFormat: ChannelFormat
+    public readonly sampleRateHz: number
+    public readonly units: string
+
     protected boundInfo!: BoundStreamInfo
-    private channelNames: string[]
-    private channelFormat: ChannelFormat
-    private sampleRateHz: number
 
     private readonly defaultName = `lsl-stream-info-${generateId()}`
     private readonly defaultType = generateId()
@@ -38,6 +42,7 @@ export default class LslStreamInfo implements StreamInfo {
         this.type = type
         this.sourceId = sourceId
         this.channelNames = channelNames
+        this.channelCount = channelNames.length
         this.channelFormat = channelFormat
         this.sampleRateHz = sampleRateHz
         this.units = units
@@ -47,7 +52,14 @@ export default class LslStreamInfo implements StreamInfo {
     }
 
     public static Create(options: StreamInfoOptions) {
-        return new (this.Class ?? this)(options)
+        const key = JSON.stringify(options)
+        let instance = this.instanceCache[key]
+
+        if (instance === undefined) {
+            instance = new (this.Class ?? this)(options)
+            this.instanceCache[key] = instance
+        }
+        return instance
     }
 
     private createStreamInfo() {
@@ -61,10 +73,6 @@ export default class LslStreamInfo implements StreamInfo {
         })
     }
 
-    private get channelCount() {
-        return this.channelNames.length
-    }
-
     private get lslChannelFormat() {
         return CHANNEL_FORMATS_MAP[this.channelFormat]
     }
@@ -91,6 +99,14 @@ export default class LslStreamInfo implements StreamInfo {
 
 export interface StreamInfo {
     destroy(): void
+    readonly name: string
+    readonly type: string
+    readonly sourceId: string
+    readonly units: string
+    readonly channelNames: string[]
+    readonly channelCount: number
+    readonly channelFormat: ChannelFormat
+    readonly sampleRateHz: number
     readonly boundStreamInfo: BoundStreamInfo
 }
 

package/src/impl/LslStreamInlet.ts

@@ -73,8 +73,11 @@ export default class LslStreamInlet implements StreamInlet {
 
     public static Create(options: StreamInletOptions, onData: OnDataCallback) {
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { maxBufferedMs, chunkSize, ...infoOptions } = options
+        const { maxBufferedMs, chunkSize, ...rest } = options
+        const infoOptions: StreamInfoOptions = rest
+
         const info = this.LslStreamInfo(infoOptions)
+
         return new (this.Class ?? this)(info, options, onData)
     }
 

package/src/impl/LslStreamOutlet.ts

@@ -34,7 +34,7 @@ export default class LslStreamOutlet implements StreamOutlet {
     public readonly units: string = 'N/A'
 
     private info: StreamInfo
-    private outlet!: BoundOutlet
+    private boundOutlet!: BoundOutlet
     private pushSampleMethod!: (options: unknown) => LslErrorCode
 
     private lsl = LiblslAdapter.getInstance()
@@ -108,7 +108,7 @@ export default class LslStreamOutlet implements StreamOutlet {
     }
 
     private createStreamOutlet() {
-        this.outlet = this.lsl.createOutlet({
+        this.boundOutlet = this.lsl.createOutlet({
             info: this.boundStreamInfo,
             chunkSize: this.chunkSize,
             maxBufferedMs: this.maxBufferedMs,
@@ -138,7 +138,7 @@ export default class LslStreamOutlet implements StreamOutlet {
         const timestamp = this.lsl.localClock()
 
         const err = this.pushSampleMethod({
-            outlet: this.outlet,
+            outlet: this.boundOutlet,
             sample,
             timestamp,
         })
@@ -155,7 +155,7 @@ export default class LslStreamOutlet implements StreamOutlet {
     }
 
     private destroyBoundOutlet() {
-        this.lsl.destroyOutlet({ outlet: this.outlet })
+        this.lsl.destroyOutlet({ outlet: this.boundOutlet })
     }
 
     private static async waitToAllowSetup(waitAfterConstructionMs: number) {
@@ -194,12 +194,13 @@ export interface StreamOutlet {
     readonly type: string
     readonly sourceId: string
     readonly channelNames: string[]
+    readonly channelCount: number
     readonly channelFormat: ChannelFormat
     readonly sampleRateHz: number
+    readonly units: string
     readonly chunkSize: number
     readonly maxBufferedMs: number
     readonly manufacturer: string
-    readonly units: string
 }
 
 export type StreamOutletConstructor = new (

package/src/impl/LslWebSocketBridge.ts

@@ -1,58 +1,92 @@
-import { WebSocketServer } from 'ws'
+import WebSocket, { WebSocketServer } from 'ws'
 import { ChannelFormat } from './LiblslAdapter.js'
-import LslStreamInlet, { StreamInlet } from './LslStreamInlet.js'
+import LslStreamInlet, {
+    StreamInlet,
+    StreamInletOptions,
+} from './LslStreamInlet.js'
 
 export default class LslWebSocketBridge implements WebSocketBridge {
     public static Class?: WebSocketBridgeConstructor
+    public static WS = WebSocket
     public static WSS = WebSocketServer
 
     private inlet: StreamInlet
-    private wss: WebSocketServer
+    private localServer?: WebSocketServer
+    private remoteSockets?: WebSocket[]
+
     private isDestroyed = false
 
     protected constructor(options: WebSocketBridgeConstructorOptions) {
-        const { inlet, wss } = options
+        const { inlet, localServer, remoteSockets } = options
 
         this.inlet = inlet
-        this.wss = wss
+        this.localServer = localServer
+        this.remoteSockets = remoteSockets
+
+        this.throwIfNoLocalServerOrRemoteSockets()
     }
 
     public static Create(options: WebSocketBridgeOptions) {
-        const { wssPort = 8080 } = options ?? {}
-        const wss = this.WebSocketServer(wssPort)
-        const inlet = this.LslStreamInlet(options, wss)
+        const { listenPort, connectUrls, ...rest } = options
+        const inletOptions: StreamInletOptions = rest
+
+        const localServer = this.WebSocketServer(listenPort)
+        const remoteSockets = this.createSocketsFrom(connectUrls)
+
+        const inlet = this.LslStreamInlet(
+            inletOptions,
+            localServer,
+            remoteSockets
+        )
+
+        return new (this.Class ?? this)({
+            ...options,
+            inlet,
+            localServer,
+            remoteSockets,
+        })
+    }
 
-        return new (this.Class ?? this)({ ...options, inlet, wss })
+    private throwIfNoLocalServerOrRemoteSockets() {
+        if (!(this.localServer || this.remoteSockets)) {
+            throw new Error(this.insufficientOptionsError)
+        }
     }
 
+    private readonly insufficientOptionsError = `At least one of listenPort or connectUrls must be provided!`
+
     public activate() {
-        this.throwIfBridgeIsDestroyed()
+        this.throwIfBridgeIsDestroyed(this.cannotActivateMessage)
         this.startPullingData()
     }
 
-    private throwIfBridgeIsDestroyed() {
+    private throwIfBridgeIsDestroyed(err: string) {
         if (this.isDestroyed) {
-            throw new Error(
-                `\n\n Cannot re-activate bridge after destroying it! \n\n Please create and activate a new instance. \n`
-            )
+            throw new Error(err)
         }
     }
 
+    private readonly cannotActivateMessage = `\n\n Cannot activate bridge after destroying it! \n\n Please create and activate a new instance. \n`
+
     private startPullingData() {
         this.inlet.startPulling()
     }
 
     public deactivate() {
+        this.throwIfBridgeIsDestroyed(this.cannotDeactivateMessage)
         this.stopPullingData()
     }
 
+    private readonly cannotDeactivateMessage = `\n\n Cannot deactivate bridge after destroying it! \n\n Please create and activate a new instance. \n`
+
     private stopPullingData() {
         this.inlet.stopPulling()
     }
 
     public destroy() {
         this.destroyBoundInlet()
-        this.closeWebSocketServer()
+        this.closeLocalServerIfExists()
+        this.closeRemoteSocketsIfExists()
         this.isDestroyed = true
     }
 
@@ -60,44 +94,74 @@ export default class LslWebSocketBridge implements WebSocketBridge {
         this.inlet.destroy()
     }
 
-    private closeWebSocketServer() {
-        this.wss.close()
+    private closeLocalServerIfExists() {
+        this.localServer?.close()
     }
 
-    private static createOnDataCallback(wss: WebSocketServer) {
+    private closeRemoteSocketsIfExists() {
+        this.remoteSockets?.forEach((socket) => socket.close())
+    }
+
+    private static createOnDataCallback(
+        localServer?: WebSocketServer,
+        remoteSockets?: WebSocket[]
+    ) {
         return (samples: Float32Array, timestamps: Float64Array) => {
-            this.broadcastToClients(wss, samples, timestamps)
+            const payload = JSON.stringify({ samples, timestamps })
+
+            if (localServer) {
+                this.broadcastToClients(localServer, payload)
+            }
+
+            if (remoteSockets) {
+                this.sendToSockets(remoteSockets, payload)
+            }
         }
     }
 
     private static broadcastToClients(
-        wss: WebSocketServer,
-        samples: Float32Array<ArrayBufferLike>,
-        timestamps: Float64Array<ArrayBufferLike>
+        localServer: WebSocketServer,
+        payload: string
     ) {
-        for (const client of wss.clients) {
+        for (const client of localServer.clients) {
             if (client.readyState === WebSocket.OPEN) {
-                client.send(
-                    JSON.stringify({
-                        samples,
-                        timestamps,
-                    })
-                )
+                client.send(payload)
             }
         }
     }
 
+    private static sendToSockets(remoteSockets: WebSocket[], payload: string) {
+        for (const socket of remoteSockets) {
+            if (socket.readyState === WebSocket.OPEN) {
+                socket.send(payload)
+            }
+        }
+    }
+
+    private static createSocketsFrom(connectUrls?: string | string[]) {
+        return connectUrls
+            ? (Array.isArray(connectUrls) ? connectUrls : [connectUrls]).map(
+                  (url) => this.WebSocket(url)
+              )
+            : undefined
+    }
+
+    private static WebSocket(url: string) {
+        return new this.WS(url)
+    }
+
+    private static WebSocketServer(listenPort?: number) {
+        return listenPort ? new this.WSS({ port: listenPort }) : undefined
+    }
+
     private static LslStreamInlet(
-        options: WebSocketBridgeOptions,
-        wss: WebSocketServer
+        options: StreamInletOptions,
+        localServer?: WebSocketServer,
+        remoteSockets?: WebSocket[]
     ) {
-        const onData = this.createOnDataCallback(wss)
+        const onData = this.createOnDataCallback(localServer, remoteSockets)
         return LslStreamInlet.Create(options, onData)
     }
-
-    private static WebSocketServer(wssPort: number) {
-        return new this.WSS({ port: wssPort })
-    }
 }
 
 export interface WebSocketBridge {
@@ -118,11 +182,13 @@ export interface WebSocketBridgeOptions {
     name?: string
     type?: string
     sourceId?: string
-    wssPort?: number
+    listenPort?: number
+    connectUrls?: string | string[]
 }
 
 export interface WebSocketBridgeConstructorOptions
     extends WebSocketBridgeOptions {
     inlet: StreamInlet
-    wss: WebSocketServer
+    localServer?: WebSocketServer
+    remoteSockets?: WebSocket[]
 }

package/src/testDoubles/StreamInfo/FakeStreamInfo.ts

@@ -1,3 +1,5 @@
+import generateId from '@neurodevs/generate-id'
+
 import { BoundStreamInfo } from 'impl/LiblslAdapter.js'
 import { StreamInfo, StreamInfoOptions } from '../../impl/LslStreamInfo.js'
 
@@ -7,6 +9,14 @@ export default class FakeStreamInfo implements StreamInfo {
 
     public static boundStreamInfo = {} as BoundStreamInfo
 
+    public name = generateId()
+    public type = generateId()
+    public sourceId = generateId()
+    public channelNames: string[] = [generateId(), generateId()]
+    public channelFormat = 'float32' as const
+    public sampleRateHz = 0
+    public units = 'N/A'
+
     public constructor(options: StreamInfoOptions) {
         FakeStreamInfo.callsToConstructor.push(options)
     }
@@ -15,6 +25,10 @@ export default class FakeStreamInfo implements StreamInfo {
         FakeStreamInfo.numCallsToDestroy++
     }
 
+    public get channelCount() {
+        return this.channelNames.length
+    }
+
     public get boundStreamInfo() {
         return FakeStreamInfo.boundStreamInfo
     }

package/src/testDoubles/StreamInfo/SpyStreamInfo.ts

@@ -1,8 +1,11 @@
 import LslStreamInfo, { StreamInfoOptions } from '../../impl/LslStreamInfo.js'
 
 export default class SpyStreamInfo extends LslStreamInfo {
+    public static numCallsToConstructor = 0
+
     public constructor(options: StreamInfoOptions) {
         super(options)
+        SpyStreamInfo.numCallsToConstructor++
     }
 
     public getBoundInfo() {
@@ -24,4 +27,8 @@ export default class SpyStreamInfo extends LslStreamInfo {
     public getUnits() {
         return this.units
     }
+
+    public static resetTestDouble() {
+        SpyStreamInfo.numCallsToConstructor = 0
+    }
 }

package/src/testDoubles/WebSocketBridge/FakeWebSocketBridge.ts

@@ -1,4 +1,9 @@
-import { WebSocketBridge } from '../../impl/LslWebSocketBridge.js'
+import WebSocket, { WebSocketServer } from 'ws'
+import LslWebSocketBridge, {
+    WebSocketBridge,
+} from '../../impl/LslWebSocketBridge.js'
+import FakeWebSocket from '../WebSockets/FakeWebSocket.js'
+import FakeWebSocketServer from '../WebSockets/FakeWebSocketServer.js'
 
 export default class FakeWebSocketBridge implements WebSocketBridge {
     public static numCallsToConstructor = 0
@@ -23,9 +28,23 @@ export default class FakeWebSocketBridge implements WebSocketBridge {
     }
 
     public static resetTestDouble() {
-        FakeWebSocketBridge.numCallsToConstructor = 0
-        FakeWebSocketBridge.numCallsToActivate = 0
-        FakeWebSocketBridge.numCallsToDeactivate = 0
-        FakeWebSocketBridge.numCallsToDestroy = 0
+        this.numCallsToConstructor = 0
+        this.numCallsToActivate = 0
+        this.numCallsToDeactivate = 0
+        this.numCallsToDestroy = 0
+
+        this.setFakeWebSocket()
+        this.setFakeWebSocketServer()
+    }
+
+    private static setFakeWebSocket() {
+        LslWebSocketBridge.WS = FakeWebSocket as unknown as typeof WebSocket
+        FakeWebSocket.resetTestDouble()
+    }
+
+    private static setFakeWebSocketServer() {
+        LslWebSocketBridge.WSS =
+            FakeWebSocketServer as unknown as typeof WebSocketServer
+        FakeWebSocketServer.resetTestDouble()
     }
 }

package/src/testDoubles/WebSockets/FakeWebSocket.ts

@@ -2,16 +2,29 @@ import generateId from '@neurodevs/generate-id'
 import WebSocket from 'ws'
 
 export default class FakeWebSocket {
+    public static callsToConstructor: (string | undefined)[] = []
     public static callsToSend: { id: string; data: unknown }[] = []
+    public static numCallsToClose = 0
 
     public readyState: number = WebSocket.OPEN
     public id = generateId()
 
+    public constructor(url?: string) {
+        FakeWebSocket.callsToConstructor.push(url)
+    }
+
     public send(data: unknown) {
         FakeWebSocket.callsToSend.push({ id: this.id, data })
     }
 
+    public close() {
+        FakeWebSocket.numCallsToClose++
+        this.readyState = WebSocket.CLOSED
+    }
+
     public static resetTestDouble() {
-        FakeWebSocket.callsToSend = []
+        this.callsToConstructor = []
+        this.callsToSend = []
+        this.numCallsToClose = 0
     }
 }