@neurodevs/node-lsl 8.0.6 → 8.0.7

package/README.md

@@ -1,2 +1,131 @@
 # node-lsl
-Lab Streaming Layer (LSL) for synchronized streaming of multi-modal, time-series data over a network 
+Lab Streaming Layer (LSL) for synchronized streaming of multi-modal, time-series data over a network.
+
+## Table of Contents
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [LslOutlet](#lsloutlet)
+  - [TimeMarkerOutlet](#timemarkeroutlet) 
+- [Test Doubles](#test-doubles)
+
+## Overview
+
+This package is a Node wrapper around the C++ [liblsl](https://github.com/sccn/liblsl) library. It was developed and tested on a MacOS system with an M2 chip. It should work with any M-series chip: M1, M2, M3. There are known issues for this package with x86 MacOS architectures. It's untested for Windows or Linux.
+
+Please note that this package currently only supports LSL outlets (sending data over a network). It does not yet support LSL inlets (receiving data from a network).
+
+## Installation
+
+First, you need to install the C++ [liblsl](https://github.com/sccn/liblsl) library. On MacOS, you can use Homebrew to install it, as specified in its [documentation](https://github.com/sccn/liblsl?tab=readme-ov-file#getting-and-using-liblsl):
+
+`brew install labstreaminglayer/tap/lsl`
+
+Then, install the package with your preferred package manager (make sure to be in the right directory for your Node project):
+
+`npm install @neurodevs/node-lsl` 
+
+or 
+
+`yarn add @neurodevs/node-lsl`
+
+Finally, add the following to your .env file or otherwise set it as an environmental variable. Update the path to match your system:
+
+```.env
+LIBLSL_PATH=/opt/homebrew/Cellar/lsl/1.16.2/lib/liblsl.1.16.2.dylib
+```
+
+## Usage
+
+### LslOutlet
+
+LSL is often used to stream EEG data over a network. For example, to instantiate an LSL outlet for the [Muse S 2nd generation](https://choosemuse.com/products/muse-s-gen-2) headband:
+
+```typescript
+import { LslOutletImpl } from '@neurodevs/node-lsl'
+
+const outlet = LslOutletImpl.Outlet({
+    name: 'Muse S (2nd gen)',
+    type: 'EEG',
+    channelNames: ['TP9', 'AF7', 'AF8', 'TP10', 'AUX'],
+    sampleRate: 256,
+    channelFormat: 'float32',
+    sourceId: 'muse-s-eeg',
+    manufacturer: 'Interaxon Inc.',
+    unit: 'microvolt',
+    chunkSize: 12,
+    maxBuffered: 360,
+})
+
+// Must be in async function
+await outlet.pushSample(...)
+```
+
+### TimeMarkerOutlet
+
+LSL is also often used to push time markers that mark different phases of an experiment or session:
+
+```typescript
+import { TimeMarkerOutletImpl } from '@neurodevs/node-lsl'
+
+const outlet = TimeMarkerOutletImpl.Outlet()
+
+// Must be in async function
+await outlet.pushSample('phase-1-begin')
+
+// Wait for phase to end
+
+await outlet.pushSample('phase-1-end')
+```
+
+There is also a `pushMarkers` method that pushes a time marker, waits for a specified duration, then pushes the next marker. I recommend that each time marker has a duration of at least 100 ms so that LSL receives the markers in the right order.
+
+```typescript
+const markers = [
+    { name: 'phase-1-begin', durationMs: 30 * 1000 },
+    { name: 'phase-1-end', durationMs: 0.1 * 1000 },
+    { name: 'phase-2-begin', durationMs: 60 * 1000 },
+    ...
+]
+
+// Must be in async function, hangs until complete
+await outlet.pushMarkers(markers)
+```
+
+If you then want to stop the time marker outlet early, you simply do:
+
+```typescript
+outlet.stop()
+```
+
+You can optionally pass any LslOutlet options to the time marker outlet during instantiation. For example, if you want to override the type:
+
+```typescript
+import { TimeMarkerOutletImpl } from '@neurodevs/node-lsl'
+
+const outlet = TimeMarkerOutletImpl.Outlet({
+    type: 'custom-type'
+})
+```
+
+## Test Doubles
+
+This package was developed using test-driven development (TDD). If you also follow TDD, you'll likely want test doubles to fake or mock certain behaviors for these classes.
+
+For example, the `MockTimeMarkerOutlet` class lets you test whether your application appropriately calls its methods without actually doing anything. Set this mock in your test code like this:
+
+```typescript
+import { TimeMarkerOutletImpl, MockTimeMarkerOutlet } from '@neurodevs/node-lsl'
+
+// In your tests / beforeEach
+TimeMarkerOutletImpl.Class = MockTimeMarkerOutlet
+
+const mock = TimeMarkerOutletImpl.Outlet()
+
+// Do something in your application that should start the outlet
+
+const expectedMarkers = ['phase-1-begin', ...]
+mock.assertDidPushSamples(expectedMarkers)
+```
+
+Now, you'll have a failing test. There will be a helpful error message to guide you towards the solution. Basically, you just need to call the `pushSample` method in your application with the expected markers. See examples above for how to do so.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neurodevs/node-lsl",
-  "version": "8.0.6",
+  "version": "8.0.7",
   "main": "build/index.js",
   "repository": {
     "type": "git",
@@ -31,22 +31,22 @@
     "test.rs": "node build/test.js"
   },
   "devDependencies": {
-    "@sprucelabs/jest-json-reporter": "^8.0.69",
-    "@sprucelabs/resolve-path-aliases": "^2.0.45",
-    "@sprucelabs/test": "^9.0.30",
-    "@sprucelabs/test-utils": "^5.1.2",
+    "@sprucelabs/jest-json-reporter": "^8.0.248",
+    "@sprucelabs/resolve-path-aliases": "^2.0.225",
+    "@sprucelabs/test": "^9.0.41",
+    "@sprucelabs/test-utils": "^5.1.188",
     "@types/ffi-napi": "^4.0.10",
-    "@types/node": "^20.14.7",
+    "@types/node": "^22.5.0",
     "chokidar-cli": "^3.0.0",
     "concurrently": "^8.2.2",
-    "eslint": "^9.5.0",
-    "eslint-config-spruce": "^11.2.24",
+    "eslint": "^9.9.0",
+    "eslint-config-spruce": "^11.2.26",
     "jest": "^29.7.0",
     "jest-circus": "^29.7.0",
-    "prettier": "^3.3.2",
+    "prettier": "^3.3.3",
     "ts-node": "^10.9.2",
     "tsc-watch": "^6.2.0",
-    "typescript": "^5.5.2"
+    "typescript": "^5.5.4"
   },
   "description": "Lab Streaming Layer (LSL) bindings for Node",
   "skill": {
@@ -74,12 +74,12 @@
     }
   },
   "dependencies": {
-    "@sprucelabs/error": "^6.0.64",
-    "@sprucelabs/schema": "^30.0.109",
-    "@sprucelabs/spruce-core-schemas": "^40.1.54",
-    "@sprucelabs/spruce-skill-utils": "^31.0.126",
-    "ffi-rs": "^1.0.83",
-    "node-gyp": "^10.1.0",
+    "@sprucelabs/error": "^6.0.246",
+    "@sprucelabs/schema": "^30.0.296",
+    "@sprucelabs/spruce-core-schemas": "^40.1.237",
+    "@sprucelabs/spruce-skill-utils": "^31.0.310",
+    "ffi-rs": "^1.0.90",
+    "node-gyp": "^10.2.0",
     "ref-array-napi": "^1.2.2",
     "ref-napi": "^3.0.3"
   }