@soundworks/core 5.4.3 → 5.6.0

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v5.5.0 - 2026-06-10
+
+- CI: move to node 24
+- ClientSocket: expose `close` method for testing purposes
+
 ## v5.4.2 - 2026-02-10
 
 - Chore: upgrade API documentation system

package/README.md

@@ -42,6 +42,12 @@ Note that the `@soundworks/core` package is automatically installed when creatin
 npm install @soundworks/core
 ```
 
+## Developement Notes
+
+### Windows
+
+On windows machine, tests may fail when run in node.js command line, due to `openssl` not being found. This is fixed when run with git command line.
+
 ## Share with Us
 
 If you made an application using **soundworks** please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "5.4.3",
+  "version": "5.6.0",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "collaborators": [
     "Benjamin Matuszewski",
@@ -24,6 +24,16 @@
       "types": "./types/server/index.d.ts"
     }
   },
+  "imports": {
+    "#isomorphic/colored-logger.js": {
+      "module": "./src/common/isomorphic/colored-logger.browser.js",
+      "node": "./src/common/isomorphic/colored-logger.node.js"
+    },
+    "#isomorphic/web-socket.js": {
+      "module": "./src/common/isomorphic/web-socket.browser.js",
+      "node": "./src/common/isomorphic/web-socket.node.js"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/collective-soundworks/soundworks.git"
@@ -41,7 +51,7 @@
     "distributed-system"
   ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "doc": "npm run types && rm -rf docs && jsdoc -c .jsdoc --verbose && cp -R misc/assets docs/",
@@ -56,14 +66,11 @@
   "dependencies": {
     "@ircam/sc-utils": "^1.13.0",
     "cancelable-promise": "^4.3.1",
-    "chalk": "^5.6.2",
-    "fast-deep-equal": "^3.1.3",
-    "isomorphic-ws": "^5.0.0",
+    "defu": "^6.1.7",
+    "dequal": "^2.0.3",
     "keyv": "^5.6.0",
     "keyv-file": "^5.3.3",
-    "lodash": "^4.17.23",
-    "pem": "^1.14.8",
-    "uuid": "^13.0.0",
+    "selfsigned": "^5.5.0",
     "ws": "^8.19.0"
   },
   "devDependencies": {
@@ -73,13 +80,12 @@
     "dotenv": "^17.3.1",
     "eslint": "^10.0.3",
     "jsdoc": "^4.0.5",
-    "mocha": "^11.7.5",
+    "mocha": "^11.7.6",
     "puppeteer": "^24.39.0",
     "tcp-ping": "^0.1.1",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.2"
   },
   "optionalDependencies": {
-    "bufferutil": "^4.1.0",
-    "utf-8-validate": "^6.0.6"
+    "bufferutil": "^4.1.0"
   }
 }

package/src/client/Client.js

@@ -23,7 +23,10 @@ import {
   CLIENT_HANDSHAKE_ERROR,
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
-import logger from '../common/logger.js';
+
+import gatedLogger from '../common/logs/gated-logger.js';
+import warnings from '../common/logs/warnings.js';
+
 import VERSION from '../common/version.js';
 
 // for testing purposes
@@ -132,7 +135,7 @@ class Client {
 
     this[kClientOnStatusChangeCallbacks] = new Set();
 
-    logger.configure(!!config.env.verbose);
+    gatedLogger.verbose = !!this.#config.env.verbose;
   }
 
   /**
@@ -209,7 +212,7 @@ class Client {
    * @deprecated Use {@link Client#runtime} instead.
    */
   get target() {
-    logger.deprecated('Client#target', 'Client#runtime', '4.0.0-alpha.29');
+    warnings.deprecated('Client#target', 'Client#runtime', '4.0.0-alpha.29');
     return this.runtime;
   }
 
@@ -335,7 +338,7 @@ class Client {
           this.#token = token;
 
           if (version !== this.#version) {
-            logger.warnVersionDiscrepancies(this.#role, this.#version, version);
+            warnings.versionDiscrepancies(this.#role, this.#version, version);
           }
 
           resolve();

package/src/client/ClientSocket.js

@@ -1,11 +1,10 @@
 import { isBrowser } from '@ircam/sc-utils';
-import WebSocket from 'isomorphic-ws';
 
+import WebSocket from '#isomorphic/web-socket.js';
 import {
   PING_MESSAGE,
   PONG_MESSAGE,
 } from '../common/constants.js';
-import logger from '../common/logger.js';
 import {
   packStringMessage,
   unpackStringMessage,
@@ -167,7 +166,7 @@ class ClientSocket {
 
           if (e.error) {
             const msg = `ClientSocket error - code: ${e.error.code}, message: ${e.error.message}`;
-            logger.log(msg);
+            console.log(msg);
           }
 
           // Try to reconnect in all cases. Note that if the socket has been connected,
@@ -274,6 +273,13 @@ class ClientSocket {
       this.#listeners.delete(channel);
     }
   }
+
+  /**
+   * Close the socket, will dispatch the close event. For debug testing purpose
+   */
+  close() {
+    this.#socket.close();
+  }
 }
 
 export default ClientSocket;

package/src/common/BasePlugin.js

@@ -1,4 +1,4 @@
-import merge from 'lodash/merge.js';
+import { defu } from 'defu';
 
 // Notes: we use Symbol.for because we need to override this in helpers test
 export const kBasePluginStatus = Symbol.for('soundworks:base-plugin-status');
@@ -171,7 +171,7 @@ class BasePlugin {
    * @see {@link BasePluginManager#onStateChange}
    */
   propagateStateChange(updates) {
-    this.state = merge(this.state, updates);
+    this.state = defu(updates, this.state);
     this.#onStateChangeCallbacks.forEach(callback => callback(this.state));
   }
 }

package/src/common/BasePluginManager.js

@@ -4,7 +4,7 @@ import {
   kBasePluginStatus,
 } from './BasePlugin.js';
 
-import logger from './logger.js';
+import gatedLogger from './logs/gated-logger.js';
 
 export const kPluginManagerStart = Symbol('soundworks:plugin-manager-start');
 export const kPluginManagerStop = Symbol('soundworks:plugin-manager-stop');
@@ -64,7 +64,7 @@ class BasePluginManager {
    * @private
    */
   async [kPluginManagerStart]() {
-    logger.title('starting registered plugins');
+    gatedLogger.title('starting registered plugins');
 
     if (this.#status !== 'idle') {
       throw new DOMException(`Cannot execute 'kPluginManagerStart' on BasePluginManager: Lifecycle methods must be called in following order: kPluginManagerStart, kPluginManagerStop`, 'InvalidAccessError');

package/src/common/BaseStateManager.js

@@ -1,4 +1,9 @@
-import { isString, isFunction, isPlainObject } from '@ircam/sc-utils';
+import {
+  isString,
+  isFunction,
+  isPlainObject,
+} from '@ircam/sc-utils';
+
 import SharedState from './SharedState.js';
 import SharedStateCollection, {
   kSharedStateCollectionInit,
@@ -23,7 +28,7 @@ import {
   GET_CLASS_DESCRIPTION_RESPONSE,
   GET_CLASS_DESCRIPTION_ERROR,
 } from './constants.js';
-import logger from './logger.js';
+import warnings from './logs/warnings.js';
 
 export const kStateManagerInit = Symbol('soundworks:state-manager-init');
 export const kStateManagerDeleteState = Symbol('soundworks:state-manager-delete-state');
@@ -265,7 +270,7 @@ class BaseStateManager {
    * @deprecated Use {@link BaseStateManager#getClassDescription} instead.
    */
   async getSchema(className) {
-    logger.deprecated('BaseStateManager#getSchema', 'BaseStateManager#getClassDescription', '4.0.0-alpha.29');
+    warnings.deprecated('BaseStateManager#getSchema', 'BaseStateManager#getClassDescription', '4.0.0-alpha.29');
     return this.getClassDescription(className);
   }
 

package/src/common/ParameterBag.js

@@ -1,9 +1,9 @@
-import cloneDeep from 'lodash/cloneDeep.js';
-import equal from 'fast-deep-equal';
-
 import {
   isPlainObject,
 } from '@ircam/sc-utils';
+import {
+  dequal,
+} from 'dequal/lite';
 
 export const sharedOptions = {
   nullable: false,
@@ -19,7 +19,7 @@ export const types = {
   boolean: {
     required: ['default'],
     get defaultOptions() {
-      return Object.assign(cloneDeep(sharedOptions), {});
+      return Object.assign(structuredClone(sharedOptions), {});
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'boolean') {
@@ -32,7 +32,7 @@ export const types = {
   string: {
     required: ['default'],
     get defaultOptions() {
-      return Object.assign(cloneDeep(sharedOptions), {});
+      return Object.assign(structuredClone(sharedOptions), {});
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'string') {
@@ -45,7 +45,7 @@ export const types = {
   integer: {
     required: ['default'],
     get defaultOptions() {
-      return Object.assign(cloneDeep(sharedOptions), {
+      return Object.assign(structuredClone(sharedOptions), {
         min: -Infinity,
         max: +Infinity,
       });
@@ -78,7 +78,7 @@ export const types = {
   float: {
     required: ['default'],
     get defaultOptions() {
-      return Object.assign(cloneDeep(sharedOptions), {
+      return Object.assign(structuredClone(sharedOptions), {
         min: -Infinity,
         max: +Infinity,
       });
@@ -111,7 +111,7 @@ export const types = {
   enum: {
     required: ['default', 'list'],
     get defaultOptions() {
-      return Object.assign(cloneDeep(sharedOptions), {});
+      return Object.assign(structuredClone(sharedOptions), {});
     },
     coerceFunction: (name, def, value) => {
       if (def.list.indexOf(value) === -1) {
@@ -125,7 +125,7 @@ export const types = {
   any: {
     required: ['default'],
     get defaultOptions() {
-      return Object.assign(cloneDeep(sharedOptions), {});
+      return Object.assign(structuredClone(sharedOptions), {});
     },
     coerceFunction: (name, def, value) => {
       // no check as it can have any type...
@@ -176,7 +176,7 @@ class ParameterBag {
   }
 
   static getFullDescription(description) {
-    const fullDescription = cloneDeep(description);
+    const fullDescription = structuredClone(description);
 
     for (let [name, def] of Object.entries(fullDescription)) {
       if (types[def.type].sanitizeDescription) {
@@ -213,7 +213,7 @@ class ParameterBag {
     ParameterBag.validateDescription(description);
 
     description = ParameterBag.getFullDescription(description);
-    initValues = cloneDeep(initValues);
+    initValues = structuredClone(initValues);
 
     // make sure initValues make sens according to the given description
     for (let name in initValues) {
@@ -308,7 +308,7 @@ class ParameterBag {
     if (this.#description[name].type === 'any') {
       // we return a deep copy of the object as we don't want the client code to
       // be able to modify our underlying data.
-      return cloneDeep(this.#values[name]);
+      return structuredClone(this.#values[name]);
     } else {
       return this.#values[name];
     }
@@ -369,7 +369,7 @@ class ParameterBag {
   set(name, value) {
     value = this.coerceValue(name, value);
     const currentValue = this.#values[name];
-    const updated = !equal(currentValue, value);
+    const updated = !dequal(currentValue, value);
 
     // we store a deep copy of the object as we don't want the client to be able
     // to modify our underlying data, which leads to unexpected behavior where the
@@ -377,7 +377,7 @@ class ParameterBag {
     // @see tests/common.state-manager.spec.js
     // 'should copy stored value for "any" type to have a predictable behavior'
     if (this.#description[name].type === 'any') {
-      value = cloneDeep(value);
+      value = structuredClone(value);
     }
 
     this.#values[name] = value;

package/src/common/SharedState.js

@@ -14,6 +14,7 @@ import {
   UPDATE_RESPONSE,
   UPDATE_ABORT,
   UPDATE_NOTIFICATION,
+  HAS_SIBLINGS_NOTIFICATION,
 } from './constants.js';
 
 import {
@@ -21,7 +22,7 @@ import {
   kStateManagerDeleteState,
 } from './BaseStateManager.js';
 
-import logger from './logger.js';
+import warnings from './logs/warnings.js';
 
 // for testing purposes
 export const kSharedStatePromiseStore = Symbol('soundworks:shared-state-promise-store');
@@ -108,6 +109,8 @@ class SharedState {
   #filter = null;
   // true is the state has been detached or deleted
   #detached = false;
+  // only valid for owners
+  #hasSiblings = false;
   #parameters = null;
   #onUpdateCallbacks = new Set();
   #onDetachCallbacks = new Set();
@@ -182,6 +185,8 @@ class SharedState {
     // state has been deleted by its creator or the class has been deleted
     // ---------------------------------------------
     this.#client.transport.addListener(`${DELETE_NOTIFICATION}-${this.#id}-${this.#instanceId}`, async () => {
+      this.#detached = true;
+
       this.#manager[kStateManagerDeleteState](this.#id);
       this.#clearTransport();
 
@@ -239,6 +244,10 @@ class SharedState {
         this[kSharedStatePromiseStore].reject(reqId, msg);
       });
 
+      this.#client.transport.addListener(`${HAS_SIBLINGS_NOTIFICATION}-${this.#id}-${this.#instanceId}`, hasSiblings => {
+        this.#hasSiblings = hasSiblings;
+      });
+
     } else {
       // ---------------------------------------------
       // the attached node has called `.detach()`
@@ -291,7 +300,7 @@ class SharedState {
    * @deprecated Use {@link SharedState#className} instead.
    */
   get schemaName() {
-    logger.deprecated('SharedState#schemaName', 'SharedState#className', '4.0.0-alpha.29');
+    warnings.deprecated('SharedState#schemaName', 'SharedState#className', '4.0.0-alpha.29');
     return this.className;
   }
 
@@ -303,6 +312,24 @@ class SharedState {
     return this.#isOwner;
   }
 
+  /**
+   * Indicates if the node as siblings, i.e. if several versions of the same state
+   * exists on the network
+   * Always return true if the state instance is attached
+   * @type {Boolean}
+   */
+  get hasSiblings() {
+    if (this.#detached) {
+      return false;
+    }
+
+    if (!this.isOwner) {
+      return true;
+    }
+
+    return this.#hasSiblings;
+  }
+
   #clearTransport() {
     // remove listeners
     this.#client.transport.removeAllListeners(`${UPDATE_RESPONSE}-${this.#id}-${this.#instanceId}`);
@@ -397,7 +424,7 @@ class SharedState {
    * @deprecated Use {@link SharedState#getDescription} instead.
    */
   getSchema(paramName = null) {
-    logger.deprecated('SharedState#getSchema', 'SharedState#getDescription', '4.0.0-alpha.29');
+    warnings.deprecated('SharedState#getSchema', 'SharedState#getDescription', '4.0.0-alpha.29');
     return this.getDescription(paramName);
   }
 
@@ -466,7 +493,7 @@ class SharedState {
     }
 
     if (isPlainObject(arguments[0]) && isPlainObject(arguments[1])) {
-      logger.removed('`context` argument in SharedState.set(updates, context)', 'a regular parameter configured with `event=true`', '4.0.0-alpha.29');
+      warnings.removed('`context` argument in SharedState.set(updates, context)', 'a regular parameter configured with `event=true`', '4.0.0-alpha.29');
     }
 
     if (arguments.length === 2 && isString(updates)) {
@@ -551,11 +578,14 @@ class SharedState {
         hasLocalParam = true;
         locallyResolvedParam[name] = this.#parameters.get(name);
       } else if (acknowledge === false) {
-        // these go to the network but don't receive an ack
-        // they are both locally forwarded and network propagated then
+        // when acknowledge is false, e.g. streaming values, values are
+        // propagated on the network only if hasSiblings is true
         hasNonAcknowledgedParams = true;
         locallyResolvedParam[name] = this.#parameters.get(name);
-        networkPropagatedParams[name] = updates[name];
+        // propagate only if there is an attached state somewhere
+        if (this.hasSiblings) {
+          networkPropagatedParams[name] = updates[name];
+        }
       } else {
         // note that immediate params are shared and acknowledged
         hasRegularSharedParam = true;
@@ -580,7 +610,9 @@ class SharedState {
       this[kSharedStatePromiseStore].associateResolveData(reqId, locallyResolvedParam);
     }
 
-    this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, networkPropagatedParams);
+    if (Object.keys(networkPropagatedParams).length > 0) {
+      this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, networkPropagatedParams);
+    }
 
     // if we don't have regular shared params, we can resolve now
     if (!hasRegularSharedParam) {

package/src/common/SharedStateCollection.js

@@ -1,4 +1,4 @@
-import logger from './logger.js';
+import warnings from './logs/warnings.js';
 
 /**
  * Callback to execute when an update is triggered on one of the shared states
@@ -163,7 +163,7 @@ class SharedStateCollection {
    * @deprecated Use {@link SharedStateCollection#className} instead.
    */
   get schemaName() {
-    logger.deprecated('SharedStateCollection#schemaName', 'SharedStateCollection#className', '4.0.0-alpha.29');
+    warnings.deprecated('SharedStateCollection#schemaName', 'SharedStateCollection#className', '4.0.0-alpha.29');
     return this.className;
   }
 
@@ -171,7 +171,7 @@ class SharedStateCollection {
    * @deprecated Use {@link SharedStateCollection#getDescription} instead.
    */
   getSchema(paramName = null) {
-    logger.deprecated('SharedStateCollection#getSchema', 'SharedStateCollection#getDescription', '4.0.0-alpha.29');
+    warnings.deprecated('SharedStateCollection#getSchema', 'SharedStateCollection#getDescription', '4.0.0-alpha.29');
     return this.getDescription(paramName);
   }
 

package/src/common/constants.js

@@ -44,6 +44,8 @@ export const GET_CLASS_DESCRIPTION_REQUEST = 's:s:req';
 export const GET_CLASS_DESCRIPTION_RESPONSE = 's:s:res';
 export const GET_CLASS_DESCRIPTION_ERROR = 's:s:err';
 
+export const HAS_SIBLINGS_NOTIFICATION = 's:hs:not';
+
 // context channels
 export const CONTEXT_ENTER_REQUEST = 'c:en:req';
 export const CONTEXT_ENTER_RESPONSE = 'c:en:res';

package/src/common/isomorphic/colored-logger.browser.js

@@ -0,0 +1,17 @@
+/**
+ * @private
+ */
+export default {
+  title(msg) {
+    console.log(`%c${msg}`, 'color: cyan');
+  },
+  log(msg) {
+    console.log(msg);
+  },
+  warn(msg) {
+    console.warn(`%c${msg}`, 'color: yellow');
+  },
+  error(msg) {
+    console.error(`%c${msg}`, 'color: red');
+  },
+};

package/src/common/isomorphic/colored-logger.node.js

@@ -0,0 +1,19 @@
+import { styleText } from 'node:util';
+
+/**
+ * @private
+ */
+export default {
+  title(msg) {
+    console.log(styleText('cyan', msg));
+  },
+  log(msg) {
+    console.log(msg);
+  },
+  warn(msg) {
+    console.warn(styleText('yellow', msg));
+  },
+  error(msg) {
+    console.error(styleText('red', msg));
+  },
+};

package/src/common/isomorphic/web-socket.browser.js

@@ -0,0 +1 @@
+export default globalThis.WebSocket;

package/src/common/isomorphic/web-socket.node.js

@@ -0,0 +1,3 @@
+import { default as WebSocket } from 'ws';
+
+export default WebSocket;

package/src/common/logs/gated-logger.js

@@ -0,0 +1,30 @@
+import coloredLogger from '#isomorphic/colored-logger.js';
+
+/**
+ * @private
+ */
+export default {
+  // Note that setting verbose to false is mainly useful for tests
+  verbose: true,
+
+  title(msg) {
+    if (this.verbose) {
+      coloredLogger.title(msg);
+    }
+  },
+  log(msg) {
+    if (this.verbose) {
+      coloredLogger.log(msg);
+    }
+  },
+  warn(msg) {
+    if (this.verbose) {
+      coloredLogger.warn(msg);
+    }
+  },
+  error(msg) {
+    if (this.verbose) {
+      coloredLogger.error(msg);
+    }
+  },
+};

package/src/common/logs/warnings.js

@@ -0,0 +1,36 @@
+import coloredLogger from '#isomorphic/colored-logger.js';
+
+export default {
+  versionDiscrepancies(clientRole, clientVersion, serverVersion) {
+    coloredLogger.warn(`
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+WARNING
+
+Version discrepancies between server and "${clientRole}" client:
++ server: ${serverVersion} | client: ${clientVersion}
+
+This might lead to unexpected behavior, you should consider to re-install your
+dependencies on both your server and clients.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`);
+  },
+
+  deprecated(oldAPI, newAPI, lastSupportedVersion) {
+    if (!lastSupportedVersion) {
+      throw new Error(`Invalid 'logger.deprecated call: a deprecation version is required`);
+    }
+
+    const msg = `DEPRECATION WARNING: \`${oldAPI}\` is deprecated (last supported version: ${lastSupportedVersion}) and will be removed in the next major revision, please use ${newAPI} instead.\n`;
+    coloredLogger.warn(msg);
+  },
+
+  removed(oldAPI, hint, lastSupportedVersion) {
+    if (!lastSupportedVersion) {
+      throw new Error(`Invalid 'logger.deprecated call: a deprecation version is required`);
+    }
+
+    const msg = `"${oldAPI}" has been removed (last supported version: ${lastSupportedVersion}), please use "${hint}" instead.`;
+    throw new Error(msg);
+  },
+};

package/src/common/version.js

@@ -1,2 +1,2 @@
 // [WARNING] This file is generated, do not edit
-export default '5.4.3';
+export default '5.6.0';