@neurodevs/node-lsl 3.3.0 → 4.0.0

package/src/__tests__/behavioral/LslOutlet.test.ts

@@ -90,21 +90,55 @@ export default class LslOutletTest extends AbstractSpruceTest {
 		}
 	}
 
-	@test('pushing [1, 2] sample sends to LSL', [1, 2])
-	@test('pushing [1] sample sends to LSL', [1])
-	protected static async canPushSampleToLsl(sample: LslSample) {
-		this.pushSample(sample)
+	@test('pushing [1, 2] sample sends to LSL', [1.0, 2.0])
+	@test('pushing [1] sample sends to LSL', [1.0])
+	protected static async canPushFloatSampleToLsl(sample: LslSample) {
+		const outlet = this.FloatOutlet()
+		outlet.pushSample(sample)
 
 		assert.isEqual(
-			this.spyLiblsl.lastPushSampleOptions?.outlet,
+			this.spyLiblsl.lastPushSampleFtOptions?.outlet,
 			this.spyLiblsl.outlet
 		)
-		assert.isEqualDeep(this.spyLiblsl.lastPushSampleOptions?.sample, sample)
+		assert.isEqualDeep(this.spyLiblsl.lastPushSampleFtOptions?.sample, sample)
 		assert.isEqualDeep(this.spyLiblsl.lastCreateOutletOptions, {
 			info: this.spyLiblsl.streamInfo,
 			chunkSize: this.randomOutletOptions.chunkSize,
 			maxBuffered: this.randomOutletOptions.maxBuffered,
 		})
+		assert.isNumber(this.spyLiblsl.lastPushSampleFtOptions?.timestamp)
+	}
+
+	@test()
+	protected static async canPushStringSampleToLsl() {
+		const sample = [generateId()]
+		const outlet = this.StringOutlet()
+
+		outlet.pushSample(sample)
+
+		assert.isEqual(
+			this.spyLiblsl.lastPushSampleStrtOptions?.outlet,
+			this.spyLiblsl.outlet
+		)
+		assert.isEqualDeep(this.spyLiblsl.lastPushSampleStrtOptions?.sample, sample)
+		assert.isNumber(this.spyLiblsl.lastPushSampleStrtOptions?.timestamp)
+	}
+
+	@test()
+	protected static async pushingStringTwiceGivesDifferentTimestamps() {
+		const outlet = this.StringOutlet()
+		const sample = [generateId()]
+
+		outlet.pushSample(sample)
+		const t1 = this.spyLiblsl.lastPushSampleStrtOptions?.timestamp
+
+		await this.wait(10)
+
+		outlet.pushSample(sample)
+		const t2 = this.spyLiblsl.lastPushSampleStrtOptions?.timestamp
+
+		assert.isNotEqual(t1, t2)
+		assert.isEqual(this.spyLiblsl.localClockHitCount, 2)
 	}
 
 	@test()
@@ -163,17 +197,32 @@ export default class LslOutletTest extends AbstractSpruceTest {
 
 	@test()
 	protected static async pushSampleShouldNotCreateMultipleOutlets() {
-		const outlet = this.Outlet()
-		outlet.pushSample([1])
-		outlet.pushSample([2])
-		outlet.pushSample([3])
+		const outlet = this.FloatOutlet()
+		outlet.pushSample([1.0])
+		outlet.pushSample([2.0])
+		outlet.pushSample([3.0])
 
 		assert.isEqual(this.spyLiblsl.createStreamInfoHitCount, 1)
 	}
 
-	private static pushSample(sample: LslSample) {
-		const outlet = this.Outlet()
-		outlet.pushSample(sample)
+	@test()
+	protected static async pushSampleThrowsWithUnsupportedType() {
+		const unsupportedTypes = [
+			'undefined',
+			'double64',
+			'int32',
+			'int16',
+			'int8',
+			'int64',
+		] as const
+
+		for (let unsupportedType of unsupportedTypes) {
+			const outlet = this.Outlet({ channelFormat: unsupportedType })
+			assert.doesThrow(
+				() => outlet.pushSample([]),
+				`This method currently does not support the ${unsupportedType} type! Please implement it.`
+			)
+		}
 	}
 
 	private static assertThrowsInvalidMaxBuffered(maxBuffered: number) {
@@ -211,6 +260,14 @@ export default class LslOutletTest extends AbstractSpruceTest {
 			...options,
 		})
 	}
+
+	private static StringOutlet() {
+		return this.Outlet({ channelFormat: 'string' })
+	}
+
+	private static FloatOutlet() {
+		return this.Outlet({ channelFormat: 'float32' })
+	}
 }
 
 class CheckingOutlet extends LslOutlet {

package/src/__tests__/behavioral/TimeMarkerOutlet.test.ts

@@ -19,7 +19,7 @@ export default class TimeMarkerOutletTest extends AbstractSpruceTest {
 	@test()
 	protected static async loadsWithTimeMarkerSpecificOptions() {
 		const outlet = this.Outlet()
-		assert.isEqualDeep(outlet.options, {
+		assert.isEqualDeep(outlet.spyOptions, {
 			name: 'Time markers',
 			type: 'Markers',
 			channelNames: ['Markers'],
@@ -37,7 +37,7 @@ export default class TimeMarkerOutletTest extends AbstractSpruceTest {
 	protected static async canOverrideDefaultOptions() {
 		const options = generateRandomOutletOptions(randomInt(8))
 		const outlet = this.Outlet(options)
-		assert.isEqualDeep(outlet.options, options)
+		assert.isEqualDeep(outlet.spyOptions, options)
 	}
 
 	private static Outlet(options?: Partial<LslOutletOptions>) {
@@ -46,9 +46,9 @@ export default class TimeMarkerOutletTest extends AbstractSpruceTest {
 }
 
 class SpyTimeMarkerOutlet extends TimeMarkerOutlet {
-	public options: LslOutletOptions
+	public spyOptions: LslOutletOptions
 	public constructor(options: LslOutletOptions) {
 		super(options)
-		this.options = options
+		this.spyOptions = options
 	}
 }

package/src/__tests__/implementation/Liblsl.test.ts

@@ -10,17 +10,13 @@ import ref from 'ref-napi'
 import LiblslImpl, {
 	Liblsl,
 	LiblslBindings,
-	CreateStreamInfoOptions,
-	AppendChannelsToStreamInfoOptions,
-	CreateOutletOptions,
-	DestroyOutletOptions,
-	PushSampleOptions,
 	LslChannel,
 	BoundOutlet,
 	BoundStreamInfo,
 	BoundDesc,
 	BoundChild,
 } from '../../Liblsl'
+import { SpyLiblsl } from '../support/SpyLiblsl'
 
 export default class LiblslTest extends AbstractSpruceTest {
 	private static lsl: Liblsl
@@ -35,9 +31,9 @@ export default class LiblslTest extends AbstractSpruceTest {
 	private static appendChildParams: any[] = []
 	private static createOutletParams?: any[]
 	private static destroyOutletParams?: any[]
-	private static pushSampleParams?: any[]
+	private static pushSampleFtParams?: any[]
+	private static pushSampleStrtParams?: any[]
 	private static appendChildValueParams: any[]
-	private static localClock: number
 	private static shouldThrowWhenCreatingBindings: boolean
 	private static getDescriptionParams?: [BoundStreamInfo]
 	private static fakeChildNamedChannel: BoundChild
@@ -51,7 +47,7 @@ export default class LiblslTest extends AbstractSpruceTest {
 		delete this.createStreamInfoParams
 		delete this.createOutletParams
 		delete this.destroyOutletParams
-		delete this.pushSampleParams
+		delete this.pushSampleFtParams
 		delete this.getDescriptionParams
 		this.appendChildParams = []
 		this.appendChildValueParams = []
@@ -63,54 +59,19 @@ export default class LiblslTest extends AbstractSpruceTest {
 		this.fakeOutlet = {}
 		this.fakeChildNamedChannels = {}
 		this.fakeChildNamedChannel = {}
+		this.fakeBindings = this.FakeBindings()
 
-		this.localClock = new Date().getTime()
 		this.shouldThrowWhenCreatingBindings = false
 
 		this.appendChildHitCount = 0
 
-		this.fakeBindings = {
-			lsl_create_streaminfo: (...params: any[]) => {
-				this.createStreamInfoParams = params
-				return this.fakeStreamInfo
-			},
-			lsl_create_outlet: (...params: any[]) => {
-				this.createOutletParams = params
-				return this.fakeOutlet
-			},
-			lsl_destroy_outlet: (...params: any[]) => {
-				this.destroyOutletParams = params
-				return
-			},
-			lsl_push_sample_ft: (...params: any[]) => {
-				this.pushSampleParams = params
-				return 0
-			},
-			lsl_local_clock: () => this.localClock,
-			lsl_get_desc: (info: BoundStreamInfo) => {
-				this.getDescriptionParams = [info]
-				return this.fakeDesc
-			},
-			lsl_append_child: (...params: any) => {
-				this.appendChildParams.push(params)
-				if (this.appendChildHitCount === 0) {
-					this.appendChildHitCount++
-					return this.fakeChildNamedChannels
-				}
-				return this.fakeChildNamedChannel
-			},
-			lsl_append_child_value: (...params: any[]) => {
-				this.appendChildValueParams.push(params)
-			},
-		}
-
 		LiblslImpl.ffi = {
 			//@ts-ignore
 			Library: (path: string, options: Record<string, any>) => {
 				this.libraryPath = path
 				this.libraryOptions = options
 				if (this.shouldThrowWhenCreatingBindings) {
-					throw new Error('Failed to create bindings')
+					throw new Error('Failed to create bindings!')
 				}
 				return this.fakeBindings
 			},
@@ -173,11 +134,20 @@ export default class LiblslTest extends AbstractSpruceTest {
 	}
 
 	@test()
-	protected static async throwsWhenPushSampleIsMissingRequiredParams() {
+	protected static async throwsWhenPushSampleFtIsMissingRequiredParams() {
 		//@ts-ignore
-		const err = assert.doesThrow(() => this.lsl.pushSample())
+		const err = assert.doesThrow(() => this.lsl.pushSampleFt())
 		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
-			parameters: ['outlet', 'sample'],
+			parameters: ['outlet', 'sample', 'timestamp'],
+		})
+	}
+
+	@test()
+	protected static async throwsWhenPushSampleStrtIsMissingRequiredParams() {
+		//@ts-ignore
+		const err = assert.doesThrow(() => this.lsl.pushSampleFt())
+		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
+			parameters: ['outlet', 'sample', 'timestamp'],
 		})
 	}
 
@@ -194,7 +164,7 @@ export default class LiblslTest extends AbstractSpruceTest {
 
 	@test()
 	protected static canSetInstance() {
-		const fake = new FakeLiblsl()
+		const fake = new SpyLiblsl()
 		LiblslImpl.setInstance(fake)
 		assert.isEqual(LiblslImpl.getInstance(), fake)
 	}
@@ -213,6 +183,7 @@ export default class LiblslTest extends AbstractSpruceTest {
 			lsl_destroy_outlet: ['void', [outletType]],
 			lsl_local_clock: ['double', []],
 			lsl_push_sample_ft: ['void', [outletType, FloatArray, 'double']],
+			lsl_push_sample_strt: ['void', [outletType, StringArray, 'double']],
 			lsl_get_desc: [xmlPtr, [streamInfo]],
 			lsl_append_child: [xmlPtr, [xmlPtr, 'string']],
 			lsl_append_child_value: [xmlPtr, [xmlPtr, 'string', 'string']],
@@ -240,16 +211,33 @@ export default class LiblslTest extends AbstractSpruceTest {
 	}
 
 	@test()
-	protected static async canPushSampleWithRequiredParams() {
-		const expected = [1, 2, 3]
+	protected static async canPushFloatSample() {
+		const expected = [1.0, 2.0, 3.0]
+		const timestamp = randomInt(100)
 		const options = {
 			outlet: this.fakeOutlet,
 			sample: expected,
+			timestamp,
 		}
-		this.lsl.pushSample(options)
-		assert.isEqual(this.pushSampleParams?.[0], this.fakeOutlet)
-		assert.isEqual(this.pushSampleParams?.[1], expected)
-		assert.isEqual(this.pushSampleParams?.[2], this.localClock)
+		this.lsl.pushSampleFt(options)
+		assert.isEqual(this.pushSampleFtParams?.[0], this.fakeOutlet)
+		assert.isEqual(this.pushSampleFtParams?.[1], expected)
+		assert.isEqual(this.pushSampleFtParams?.[2], timestamp)
+	}
+
+	@test()
+	protected static async canPushStringSample() {
+		const expected = [generateId()]
+		const timestamp = randomInt(100)
+		const options = {
+			outlet: this.fakeOutlet,
+			sample: expected,
+			timestamp,
+		}
+		this.lsl.pushSampleStrt(options)
+		assert.isEqual(this.pushSampleStrtParams?.[0], this.fakeOutlet)
+		assert.isEqualDeep(this.pushSampleStrtParams?.[1], expected)
+		assert.isEqual(this.pushSampleStrtParams?.[2], timestamp)
 	}
 
 	@test()
@@ -313,6 +301,14 @@ export default class LiblslTest extends AbstractSpruceTest {
 		assert.isEqualDeep(this.destroyOutletParams, Object.values(options))
 	}
 
+	@test()
+	protected static async callingLocalClockTwiceReturnsDifferentTimestamps() {
+		const t1 = this.lsl.localClock()
+		await this.wait(10)
+		const t2 = this.lsl.localClock()
+		assert.isNotEqual(t1, t2)
+	}
+
 	private static createRandomStreamInfo() {
 		return this.lsl.createStreamInfo(
 			this.generateRandomCreateStreamInfoOptions()
@@ -348,27 +344,48 @@ export default class LiblslTest extends AbstractSpruceTest {
 			sourceId: generateId(),
 		}
 	}
-}
 
-class FakeLiblsl implements Liblsl {
-	public createStreamInfo(_options: CreateStreamInfoOptions): BoundStreamInfo {
-		return {} as BoundStreamInfo
-	}
-
-	public appendChannelsToStreamInfo(
-		_options: AppendChannelsToStreamInfoOptions
-	): void {}
-
-	public createOutlet(_options: CreateOutletOptions): BoundOutlet {
-		return {} as BoundOutlet
+	private static FakeBindings(): LiblslBindings {
+		return {
+			lsl_create_streaminfo: (...params: any[]) => {
+				this.createStreamInfoParams = params
+				return this.fakeStreamInfo
+			},
+			lsl_create_outlet: (...params: any[]) => {
+				this.createOutletParams = params
+				return this.fakeOutlet
+			},
+			lsl_destroy_outlet: (...params: any[]) => {
+				this.destroyOutletParams = params
+			},
+			lsl_push_sample_ft: (...params: any[]) => {
+				this.pushSampleFtParams = params
+			},
+			lsl_push_sample_strt: (...params: any[]) => {
+				this.pushSampleStrtParams = params
+			},
+			lsl_local_clock: () => new Date().getTime(),
+			lsl_get_desc: (info: BoundStreamInfo) => {
+				this.getDescriptionParams = [info]
+				return this.fakeDesc
+			},
+			lsl_append_child: (...params: any) => {
+				this.appendChildParams.push(params)
+				if (this.appendChildHitCount === 0) {
+					this.appendChildHitCount++
+					return this.fakeChildNamedChannels
+				}
+				return this.fakeChildNamedChannel
+			},
+			lsl_append_child_value: (...params: any[]) => {
+				this.appendChildValueParams.push(params)
+			},
+		}
 	}
-
-	public destroyOutlet(_options: DestroyOutletOptions): void {}
-
-	public pushSample(_options: PushSampleOptions): void {}
 }
 
 const streamInfo = ref.refType(ref.types.void)
 const outletType = ref.refType(ref.types.void)
 const FloatArray = ArrayType(ref.types.float)
+const StringArray = ArrayType(ref.types.CString)
 const xmlPtr = ref.refType(ref.types.void)

package/src/__tests__/support/SpyLiblsl.ts

@@ -1,23 +1,27 @@
 import {
-	CreateOutletOptions,
-	CreateStreamInfoOptions,
 	Liblsl,
 	BoundOutlet,
 	BoundStreamInfo,
+	CreateStreamInfoOptions,
 	AppendChannelsToStreamInfoOptions,
-	PushSampleOptions,
+	CreateOutletOptions,
+	PushSampleFtOptions as PushSampleFtOptions,
+	PushSampleStrtOptions,
 } from '../../Liblsl'
 
 export class SpyLiblsl implements Liblsl {
+	public outlet: BoundOutlet = {} as BoundOutlet
+	public streamInfo: BoundStreamInfo = {} as BoundStreamInfo
+
 	public lastCreateStreamInfoOptions?: CreateStreamInfoOptions
 	public lastAppendChannelsToStreamInfoOptions?: AppendChannelsToStreamInfoOptions
 	public lastCreateOutletOptions?: CreateOutletOptions
-	public lastPushSampleOptions?: PushSampleOptions
+	public lastPushSampleFtOptions?: PushSampleFtOptions
+	public lastPushSampleStrtOptions?: PushSampleStrtOptions
 
-	public outlet: BoundOutlet = {} as BoundOutlet
-	public streamInfo: BoundStreamInfo = {} as BoundStreamInfo
 	public createStreamInfoHitCount = 0
 	public destroyOutletHitCount = 0
+	public localClockHitCount = 0
 
 	public createStreamInfo(options: CreateStreamInfoOptions): BoundStreamInfo {
 		this.createStreamInfoHitCount++
@@ -27,7 +31,7 @@ export class SpyLiblsl implements Liblsl {
 
 	public appendChannelsToStreamInfo(
 		options: AppendChannelsToStreamInfoOptions
-	): void {
+	) {
 		this.lastAppendChannelsToStreamInfoOptions = options
 	}
 
@@ -40,7 +44,16 @@ export class SpyLiblsl implements Liblsl {
 		this.destroyOutletHitCount++
 	}
 
-	public pushSample(options: PushSampleOptions): void {
-		this.lastPushSampleOptions = options
+	public pushSampleFt(options: PushSampleFtOptions) {
+		this.lastPushSampleFtOptions = options
+	}
+
+	public pushSampleStrt(options: PushSampleStrtOptions) {
+		this.lastPushSampleStrtOptions = options
+	}
+
+	public localClock() {
+		this.localClockHitCount++
+		return new Date().getTime()
 	}
 }