@neurodevs/node-lsl 0.0.1

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

@@ -0,0 +1,217 @@
+import { randomInt } from 'crypto'
+import AbstractSpruceTest, {
+	test,
+	assert,
+	errorAssert,
+	generateId,
+} from '@sprucelabs/test-utils'
+import LiblslImpl, {
+	CreateOutletOptions,
+	CreateStreamInfoOptions,
+	Liblsl,
+	LslBindingsOutlet,
+	LslBindingsStreamInfo,
+	LslSample,
+} from '../../Liblsl'
+import LslOutlet, { ChannelFormat, LslOutletOptions } from '../../LslOutlet'
+
+export const CHANNEL_FORMATS = [
+	'undefined',
+	'float32',
+	'double64',
+	'string',
+	'int32',
+	'int16',
+	'int8',
+	'int64',
+] as const
+
+export default class LslOutletTest extends AbstractSpruceTest {
+	private static spyLsl: SpyLiblsl
+	private static randomOutletOptions: LslOutletOptions
+	private static channelIdx: number
+
+	protected static async beforeEach() {
+		await super.beforeEach()
+		this.channelIdx = randomInt(7)
+		this.randomOutletOptions = {
+			name: generateId(),
+			type: generateId(),
+			channelCount: randomInt(1, 10),
+			sampleRate: Math.random() * 10,
+			channelFormat: CHANNEL_FORMATS[this.channelIdx],
+			sourceId: generateId(),
+			manufacturer: generateId(),
+			unit: generateId(),
+			chunkSize: randomInt(0, 10),
+			maxBuffered: randomInt(0, 10),
+		}
+
+		this.spyLsl = new SpyLiblsl()
+		LiblslImpl.setInstance(this.spyLsl)
+	}
+
+	@test()
+	protected static async throwsWhenMissingRequiredParameters() {
+		//@ts-ignore
+		const err = assert.doesThrow(() => new LslOutlet())
+		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
+			parameters: [
+				'name',
+				'type',
+				'channelCount',
+				'sampleRate',
+				'channelFormat',
+				'sourceId',
+				'manufacturer',
+				'unit',
+				'chunkSize',
+				'maxBuffered',
+			],
+		})
+	}
+
+	@test()
+	protected static async canCreateWithRequiredParams() {
+		this.Outlet()
+	}
+
+	@test()
+	protected static async throwsWithInvalidChannelCount() {
+		this.assertThrowsInvalidChannelCount(0)
+		this.assertThrowsInvalidChannelCount(-1)
+		this.assertThrowsInvalidChannelCount(1.5)
+	}
+
+	@test()
+	protected static async throwsWithInvalidSampleRate() {
+		this.assertThrowsInvalidSampleRate(0)
+		this.assertThrowsInvalidSampleRate(-1)
+		this.assertThrowsInvalidSampleRate(-1.5)
+	}
+
+	@test()
+	protected static async throwsWithInvalidChannelFormat() {
+		//@ts-ignore
+		this.assertDoesThrowInvalidParameters({ channelFormat: generateId() }, [
+			'channelFormat',
+		])
+	}
+
+	@test()
+	protected static async supportsAllKnownChannelFormats() {
+		const valid = CHANNEL_FORMATS
+		for (const format of valid) {
+			this.Outlet({ channelFormat: format as ChannelFormat })
+		}
+	}
+
+	@test()
+	protected static async throwWithInvalidChunkSize() {
+		this.Outlet({ chunkSize: 0 })
+		this.assertThrowsInvalidChunkSize(-1)
+		this.assertThrowsInvalidChunkSize(-1.5)
+		this.assertThrowsInvalidChunkSize(1.5)
+	}
+
+	@test()
+	protected static async throwsWithInvalidMaxBuffered() {
+		this.Outlet({ maxBuffered: 0 })
+		this.assertThrowsInvalidMaxBuffered(-1)
+		this.assertThrowsInvalidMaxBuffered(-1.5)
+		this.assertThrowsInvalidMaxBuffered(1.5)
+	}
+
+	@test('pushing sample sends to lsl 1', [1])
+	@test('pushing sample sends to lsl 2', [1, 2])
+	protected static async pushingSampleSendsToLsl(sample: LslSample) {
+		this.pushSample(sample)
+		assert.isEqual(this.spyLsl.lastPushedOutlet, this.spyLsl.outlet)
+		assert.isEqualDeep(this.spyLsl.lastPushedSample, sample)
+		assert.isEqualDeep(this.spyLsl.lastOutletOptions, {
+			info: this.spyLsl.streamInfo,
+			chunkSize: this.randomOutletOptions.chunkSize,
+			maxBuffered: this.randomOutletOptions.maxBuffered,
+		})
+	}
+
+	@test()
+	protected static async pushingSamplePassesCorrectOptionsToCreateStreamInfo() {
+		this.pushSample([1])
+		const { ...options } = this.randomOutletOptions as any
+
+		delete options.manufacturer
+		delete options.unit
+		delete options.chunkSize
+		delete options.maxBuffered
+
+		assert.isEqualDeep(this.spyLsl.lastStreamInfoOptions, {
+			...options,
+			channelFormat: this.channelIdx,
+		})
+	}
+
+	private static pushSample(sample: LslSample) {
+		const outlet = this.Outlet()
+		outlet.pushSample(sample)
+	}
+
+	private static assertThrowsInvalidMaxBuffered(maxBuffered: number) {
+		this.assertDoesThrowInvalidParameters({ maxBuffered }, ['maxBuffered'])
+	}
+
+	private static assertThrowsInvalidChunkSize(chunkSize: number) {
+		this.assertDoesThrowInvalidParameters({ chunkSize }, ['chunkSize'])
+	}
+
+	private static assertThrowsInvalidSampleRate(sampleRate: number) {
+		this.assertDoesThrowInvalidParameters({ sampleRate }, ['sampleRate'])
+	}
+
+	private static assertThrowsInvalidChannelCount(count: number) {
+		this.assertDoesThrowInvalidParameters({ channelCount: count }, [
+			'channelCount',
+		])
+	}
+
+	private static assertDoesThrowInvalidParameters(
+		options: Partial<LslOutletOptions>,
+		parameters: string[]
+	) {
+		const err = assert.doesThrow(() => this.Outlet(options))
+		errorAssert.assertError(err, 'INVALID_PARAMETERS', {
+			parameters,
+		})
+	}
+
+	private static Outlet(options?: Partial<LslOutletOptions>) {
+		return new LslOutlet({
+			...this.randomOutletOptions,
+			...options,
+		})
+	}
+}
+
+class SpyLiblsl implements Liblsl {
+	public lastPushedOutlet?: LslBindingsOutlet
+	public lastPushedSample?: LslSample
+	public lastOutletOptions?: CreateOutletOptions
+	public lastStreamInfoOptions?: CreateStreamInfoOptions
+	public outlet: LslBindingsOutlet = {} as LslBindingsOutlet
+	public streamInfo: LslBindingsStreamInfo = {} as LslBindingsStreamInfo
+
+	public createStreamInfo(
+		options: CreateStreamInfoOptions
+	): LslBindingsStreamInfo {
+		this.lastStreamInfoOptions = options
+		return this.streamInfo
+	}
+	public createOutlet(options: CreateOutletOptions): LslBindingsOutlet {
+		this.lastOutletOptions = options
+		return this.outlet
+	}
+	public pushSample(outlet: LslBindingsOutlet, sample: LslSample): void {
+		this.lastPushedOutlet = outlet
+		this.lastPushedSample = sample
+	}
+}

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

@@ -0,0 +1,231 @@
+import { randomInt } from 'crypto'
+import AbstractSpruceTest, {
+	test,
+	assert,
+	errorAssert,
+	generateId,
+} from '@sprucelabs/test-utils'
+import ArrayType from 'ref-array-napi'
+import ref from 'ref-napi'
+import LiblslImpl, {
+	CreateStreamInfoOptions,
+	LiblslBindings,
+	Liblsl,
+	LslSample,
+	StreamInfo,
+	CreateOutletOptions,
+	LslBindingsOutlet,
+	LslBindingsStreamInfo,
+} from '../../Liblsl'
+
+export default class LiblslTest extends AbstractSpruceTest {
+	private static lsl: Liblsl
+	private static libraryPath?: string
+	private static libraryOptions?: Record<string, any>
+	private static fakeBindings: LiblslBindings
+	private static fakeStreamInfo: StreamInfo
+	private static fakeOutlet: LslBindingsOutlet
+	private static createStreamInfoParams?: any[]
+	private static createOutletParams?: any[]
+	private static pushSampleParams?: any[]
+	private static localClock: number
+	private static shouldThrowWhenCreatingBindings: boolean
+
+	protected static async beforeEach(): Promise<void> {
+		await super.beforeEach()
+
+		delete this.libraryPath
+		delete this.libraryOptions
+		delete this.createStreamInfoParams
+		delete this.createOutletParams
+		delete this.pushSampleParams
+
+		process.env.LIBLSL_PATH = generateId()
+
+		this.fakeStreamInfo = {}
+		this.fakeOutlet = {}
+		this.localClock = new Date().getTime()
+		this.shouldThrowWhenCreatingBindings = false
+
+		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_push_sample_ft: (...params: any[]) => {
+				this.pushSampleParams = params
+				return 0
+			},
+			lsl_local_clock: () => this.localClock,
+		}
+
+		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')
+				}
+				return this.fakeBindings
+			},
+		}
+
+		LiblslImpl.reset()
+		this.lsl = LiblslImpl.getInstance()
+	}
+
+	@test()
+	protected static async throwsIfNoEnvSet() {
+		delete process.env.LIBLSL_PATH
+		const err = assert.doesThrow(() => new LiblslImpl())
+		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
+			parameters: ['env.LIBLSL_PATH'],
+		})
+	}
+
+	@test()
+	protected static async throwsHelpfulErrorWhenBindingsFailToLoad() {
+		this.shouldThrowWhenCreatingBindings = true
+		const err = assert.doesThrow(() => new LiblslImpl())
+		errorAssert.assertError(err, 'FAILED_TO_LOAD_LIBLSL', {
+			liblslPath: process.env.LIBLSL_PATH,
+		})
+	}
+
+	@test()
+	protected static async worksAsASingleton() {
+		const liblsl = LiblslImpl.getInstance()
+		assert.isInstanceOf(liblsl, LiblslImpl)
+	}
+
+	@test()
+	protected static async singletonIsTheSame() {
+		assert.isEqual(LiblslImpl.getInstance(), LiblslImpl.getInstance())
+	}
+
+	@test()
+	protected static canSetInstance() {
+		const fake = new FakeLiblsl()
+		LiblslImpl.setInstance(fake)
+		assert.isEqual(LiblslImpl.getInstance(), fake)
+	}
+
+	@test()
+	protected static async createsExpectedBindingsToLiblsl() {
+		process.env.LIBLSL_PATH = generateId()
+		new LiblslImpl()
+		assert.isEqual(this.libraryPath, process.env.LIBLSL_PATH)
+		const expected = {
+			lsl_create_streaminfo: [
+				streamInfo,
+				['string', 'string', 'int', 'double', 'int', 'string'],
+			],
+			lsl_create_outlet: [outletType, [streamInfo, 'int', 'int']],
+			lsl_local_clock: ['double', []],
+			lsl_push_sample_ft: ['void', [outletType, FloatArray, 'double']],
+		}
+		assert.isEqual(
+			JSON.stringify(this.libraryOptions),
+			JSON.stringify(expected)
+		)
+	}
+
+	@test()
+	protected static createStreamInfoThrowsWithMissingRequiredParams() {
+		//@ts-ignore
+		const err = assert.doesThrow(() => this.lsl.createStreamInfo())
+		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
+			parameters: [
+				'name',
+				'type',
+				'channelCount',
+				'sampleRate',
+				'channelFormat',
+				'sourceId',
+			],
+		})
+	}
+
+	@test()
+	protected static async canGetStreamInfoWithRequiredParams() {
+		const options = this.generateRandomCreateStreamInfoOptions()
+		const actual = this.lsl.createStreamInfo(options)
+
+		assert.isEqual(actual, this.fakeStreamInfo)
+		assert.isEqualDeep(this.createStreamInfoParams, Object.values(options))
+	}
+
+	@test()
+	protected static async createOutletThrowsWhenMissingRequiredParams() {
+		//@ts-ignore
+		const err = assert.doesThrow(() => this.lsl.createOutlet({}))
+		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
+			parameters: ['info', 'chunkSize', 'maxBuffered'],
+		})
+	}
+
+	@test()
+	protected static async canCreateOutletWithRequiredParams() {
+		const info = this.lsl.createStreamInfo(
+			this.generateRandomCreateStreamInfoOptions()
+		)
+		const options = {
+			info,
+			chunkSize: randomInt(10),
+			maxBuffered: randomInt(10),
+		}
+		const actual = this.lsl.createOutlet(options)
+		assert.isEqualDeep(this.createOutletParams, Object.values(options))
+		assert.isEqual(actual, this.fakeOutlet)
+	}
+
+	@test()
+	protected static async pushSampleThrowsWhenMissingRequiredParams() {
+		//@ts-ignore
+		const err = assert.doesThrow(() => this.lsl.pushSample())
+		errorAssert.assertError(err, 'MISSING_PARAMETERS', {
+			parameters: ['outlet', 'sample'],
+		})
+	}
+
+	@test()
+	protected static async pushSampleCallsBindings() {
+		const expected = [1, 2, 3]
+		this.lsl.pushSample(this.fakeOutlet, expected)
+		assert.isEqual(this.pushSampleParams?.[0], this.fakeOutlet)
+		assert.isEqual(this.pushSampleParams?.[1], expected)
+		assert.isEqual(this.pushSampleParams?.[2], this.localClock)
+	}
+
+	private static generateRandomCreateStreamInfoOptions() {
+		return {
+			name: generateId(),
+			type: generateId(),
+			channelCount: randomInt(10),
+			sampleRate: randomInt(10),
+			channelFormat: randomInt(10),
+			sourceId: generateId(),
+		}
+	}
+}
+
+class FakeLiblsl implements Liblsl {
+	public createOutlet(_options: CreateOutletOptions): LslBindingsOutlet {
+		return {} as LslBindingsOutlet
+	}
+	public createStreamInfo(
+		_options: CreateStreamInfoOptions
+	): LslBindingsStreamInfo {
+		return {} as StreamInfo
+	}
+	public pushSample(_sample: LslSample): void {}
+}
+
+const streamInfo = ref.refType(ref.types.void)
+const outletType = ref.refType(ref.types.void)
+const FloatArray = ArrayType(ref.types.float)

package/src/errors/SpruceError.ts

@@ -0,0 +1,23 @@
+import BaseSpruceError from '@sprucelabs/error'
+import ErrorOptions from '#spruce/errors/options.types'
+
+export default class SpruceError extends BaseSpruceError<ErrorOptions> {
+	/** an easy to understand version of the errors */
+	public friendlyMessage(): string {
+		const { options } = this
+		let message
+		switch (options?.code) {
+			case 'FAILED_TO_LOAD_LIBLSL':
+				message = `Well shoot! Loading the liblsl dylib failed. I tried to load it from ${options.liblslPath}.`
+				break
+			default:
+				message = super.friendlyMessage()
+		}
+
+		const fullMessage = options.friendlyMessage
+			? options.friendlyMessage
+			: message
+
+		return fullMessage
+	}
+}

package/src/errors/failedToLoadLiblsl.builder.ts

@@ -0,0 +1,12 @@
+import { buildErrorSchema } from '@sprucelabs/schema'
+
+export default buildErrorSchema({
+	id: 'failedToLoadLiblsl',
+	name: 'FAILED_TO_LOAD_LIBLSL',
+	fields: {
+		liblslPath: {
+			type: 'text',
+			isRequired: true,
+		},
+	},
+})

package/src/index.ts

@@ -0,0 +1,5 @@
+export { default as LiblslImpl } from './Liblsl'
+export * from './Liblsl'
+
+export { default as LiblslOutlet } from './LslOutlet'
+export * from './LslOutlet'

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+	"compilerOptions": {
+		"skipLibCheck": true,
+		"module": "commonjs",
+		"esModuleInterop": true,
+		"target": "ES2017",
+		"lib": [
+			"DOM",
+			"es2017",
+			"ES2020"
+		],
+		"declaration": true,
+		"noImplicitAny": true,
+		"allowJs": true,
+		"forceConsistentCasingInFileNames": true,
+		"noImplicitReturns": true,
+		"strict": true,
+		"noUnusedLocals": true,
+		"resolveJsonModule": true,
+		"moduleResolution": "node",
+		"sourceMap": false,
+		"outDir": "build",
+		"baseUrl": "src",
+		"experimentalDecorators": true,
+		"paths": {
+			"#spruce/*": [
+				".spruce/*"
+			]
+		}
+	},
+	"include": [
+		"./src/*.ts",
+		"./src/**/*.ts",
+		"./src/.spruce/**/*"
+	],
+	"exclude": [
+		"build",
+		"esm"
+	]
+}