@soundworks/core 5.5.0 → 5.7.0

package/src/common/SharedStateCollection.js

@@ -1,4 +1,9 @@
-import logger from './logger.js';
+import warnings from './logs/warnings.js';
+
+import {
+  checkValidFilters,
+  sanitizeOnUpdateParams,
+} from './shared-state-utils.js';
 
 /**
  * Callback to execute when an update is triggered on one of the shared states
@@ -6,10 +11,14 @@ import logger from './logger.js';
  *
  * @callback sharedStateCollectionOnUpdateCallback
  * @param {SharedState} state - The shared state instance that triggered the update.
- * @param {Object} newValues - Key / value pairs of the updates that have been
- *  applied to the state.
- * @param {Object} oldValues - Key / value pairs of the updated params before
- *  the updates has been applied to the state.
+ * @param {Object|any} newValues - Key / value pairs of the updates that have been
+ *  applied to the state, or single value if the callback has been registered against
+ *  a parameter name filter.
+ * @param {Object|any} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state, or single value if the callback has been
+ *  registered against a parameter name filter.
+ * @param {sharedStateCollectionDeleteOnUpdateCallback} unsubscribe - Reference to unsubscribe
+ *  function returned by the `SharedStateCollection#onUpdate` method.
  */
 
 /**
@@ -80,8 +89,8 @@ export const kSharedStateCollectionInit = Symbol('soundworks:shared-state-collec
 class SharedStateCollection {
   #stateManager = null;
   #className = null;
-  #filter = null;
   #options = null;
+  #excludeLocal = null;
   #classDescription = null;
   #states = [];
   #onUpdateCallbacks = new Set();
@@ -90,30 +99,25 @@ class SharedStateCollection {
   #onChangeCallbacks = new Set();
   #unobserve = null;
 
-  constructor(stateManager, className, filter = null, options = {}) {
+  constructor(stateManager, className, options = {}) {
     this.#stateManager = stateManager;
     this.#className = className;
-    this.#filter = filter;
-    this.#options = Object.assign({ excludeLocal: false }, options);
+    this.#options = {
+      whiteList: options.whiteList ?? null,
+      blackList: options.blackList ?? null,
+    };
+    this.#excludeLocal = options.excludeLocal ?? false;
   }
 
   /** @private */
   async [kSharedStateCollectionInit]() {
     this.#classDescription = await this.#stateManager.getClassDescription(this.#className);
-
-    // if filter is set, check that it contains only valid param names
-    if (this.#filter !== null) {
-      const keys = Object.keys(this.#classDescription);
-
-      for (let filter of this.#filter) {
-        if (!keys.includes(filter)) {
-          throw new ReferenceError(`Invalid filter key (${filter}) for class "${this.#className}"`);
-        }
-      }
-    }
+    // this is catch by `getCollection`
+    checkValidFilters(this.#options, this.#className, this.#classDescription);
 
     this.#unobserve = await this.#stateManager.observe(this.#className, async (className, stateId) => {
-      const state = await this.#stateManager.attach(className, stateId, this.#filter);
+      const state = await this.#stateManager.attach(className, stateId, this.#options);
+
       this.#states.push(state);
 
       state.onDetach(() => {
@@ -125,13 +129,26 @@ class SharedStateCollection {
       });
 
       state.onUpdate((newValues, oldValues) => {
-        this.#onUpdateCallbacks.forEach(callback => callback(state, newValues, oldValues));
+        this.#onUpdateCallbacks.forEach(listenerPayload => {
+          this.#executeUpdateCallback(state, listenerPayload, newValues, oldValues);
+        });
+
         this.#onChangeCallbacks.forEach(callback => callback());
       });
 
       this.#onAttachCallbacks.forEach(callback => callback(state));
       this.#onChangeCallbacks.forEach(callback => callback());
-    }, this.#options);
+    }, { excludeLocal: this.#excludeLocal });
+  }
+
+  #executeUpdateCallback(state, listenerPayload, newValues, oldValues) {
+    const { paramName, listener, unsubscribe } = listenerPayload;
+
+    if (paramName === null) {
+      return listener(state, newValues, oldValues, unsubscribe);
+    } else if (paramName in newValues) {
+      return listener(state, newValues[paramName], oldValues[paramName], unsubscribe);
+    }
   }
 
   /**
@@ -163,7 +180,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 +188,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);
   }
 
@@ -309,9 +326,37 @@ class SharedStateCollection {
     return Promise.all(promises);
   }
 
+  /**
+   * Subscribe to any updates in the collection.
+   *
+   * @overload
+   * @param {sharedStateCollectionOnUpdateCallback}
+   *  callback - Callback to execute when an update is applied on a state.
+   * @param {Boolean} [executeListener=false] - Execute the callback immediately
+   *  with current state values. Note that `oldValues` will be set to `{}`.
+   * @returns {sharedStateCollectionDeleteOnUpdateCallback} - Function that delete
+   *  the registered listener when executed.
+   */
+  /**
+   * Subscribe to updates in the collection filtered by a given parameter name.
+   *
+   * @overload
+   * @param {SharedStateParameterName} paramName
+   * @param {sharedStateCollectionOnUpdateCallback}
+   *  callback - Callback to execute when an update is applied on a state.
+   * @param {Boolean} [executeListener=false] - Execute the callback immediately
+   *  with current state values. Note that `oldValues` will be set to `{}`.
+   * @returns {sharedStateCollectionDeleteOnUpdateCallback} - Function that delete
+   *  the registered listener when executed.
+   */
   /**
    * Register a function to execute when any shared state of the collection is updated.
    *
+   * Alternative signatures:
+   * - `collection.onUpdate(callback, executeListener)`
+   * - `collection.onUpdate(paramName, callback, executeListener)`
+   *
+   * @param {SharedStateParameterName} paramName
    * @param {sharedStateCollectionOnUpdateCallback}
    *  callback - Callback to execute when an update is applied on a state.
    * @param {Boolean} [executeListener=false] - Execute the callback immediately
@@ -319,28 +364,33 @@ class SharedStateCollection {
    * @returns {sharedStateCollectionDeleteOnUpdateCallback} - Function that delete
    *  the registered listener when executed.
    */
-  onUpdate(callback, executeListener = false) {
-    this.#onUpdateCallbacks.add(callback);
+  onUpdate(...args) {
+    const { paramName, listener, executeListener } = sanitizeOnUpdateParams(this, ...args);
+
+    const listenerPayload = { paramName, listener };
+    this.#onUpdateCallbacks.add(listenerPayload);
+    // create unsubscribe and add to payload, to pass it back to the listeners as argument
+    listenerPayload.unsubscribe = () => this.#onUpdateCallbacks.delete(listenerPayload);
 
     if (executeListener === true) {
       // filter `event: true` parameters from currentValues, having them here is
       // misleading as we are in the context of a callback, not from an active read
-      const description = this.getDescription();
+      const classDescription = this.getDescription();
 
       this.#states.forEach(state => {
         const currentValues = state.getValues();
 
-        for (let name in description) {
-          if (description[name].event === true) {
+        for (let name in classDescription) {
+          if (classDescription[name].event === true) {
             delete currentValues[name];
           }
         }
 
-        callback(state, currentValues, {});
+        this.#executeUpdateCallback(state, listenerPayload, currentValues, {});
       });
     }
 
-    return () => this.#onUpdateCallbacks.delete(callback);
+    return listenerPayload.unsubscribe;
   }
 
   /**

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/shared-state-utils.js

@@ -0,0 +1,102 @@
+import {
+  isString,
+  isFunction,
+} from '@ircam/sc-utils';
+
+export function sanitizeOnUpdateParams(caller, paramNameOrListener, listenerOrExecuteCallback, someExecuteListener) {
+  const className = caller.constructor.name;
+
+  let paramName;
+  let listener;
+  let executeListener;
+
+  // updateUpdate(listener)
+  if (arguments.length === 2) {
+    if (!isFunction(paramNameOrListener)) {
+      throw new TypeError(`Cannot execute 'onUpdate(listener)' on ${className} (overload resolution failed): listener must be a function`);
+    }
+
+    paramName = null;
+    listener = paramNameOrListener;
+    executeListener = false;
+  }
+
+  // updateUpdate(paramName, listener)
+  // updateUpdate(listener, executeListener)
+  if (arguments.length === 3) {
+    if (isString(paramNameOrListener)) {
+      if (!isFunction(listenerOrExecuteCallback)) {
+        throw new TypeError(`Cannot execute 'onUpdate(paramName, listener)' on ${className} (overload resolution failed): listener must be a function`);
+      }
+
+      paramName = paramNameOrListener;
+      listener = listenerOrExecuteCallback;
+      executeListener = false;
+
+    } else if (isFunction(paramNameOrListener)) {
+      if (typeof listenerOrExecuteCallback !== 'boolean') {
+        throw new TypeError(`Cannot execute 'onUpdate(callback, executeListener)' on ${className} (overload resolution failed): executeListener must be a boolean`);
+      }
+
+      paramName = null;
+      listener = paramNameOrListener;
+      executeListener = listenerOrExecuteCallback;
+    } else {
+      throw new TypeError(`Cannot execute 'onUpdate' on ${className} (overload resolution failed): possible signatures 'onUpdate(paramName, listener)' or 'onUpdate(listener, executeListener)'`);
+    }
+  }
+
+  // onUpdate(paramName, listener, executeListener)
+  if (arguments.length === 4) {
+    if (!isString(paramNameOrListener)) {
+      throw new TypeError(`Cannot execute 'onUpdate(paramName, listener, executeListener)' on ${className} (overload resolution failed): paramName must be a string`);
+    }
+
+    if (!isFunction(listenerOrExecuteCallback)) {
+      throw new TypeError(`Cannot execute 'onUpdate(paramName, listener, executeListener)' on ${className} (overload resolution failed): listener must be a function`);
+    }
+
+    if (typeof someExecuteListener !== 'boolean') {
+      throw new TypeError(`Cannot execute 'onUpdate(paramName, listener, executeListener)' on ${className} (overload resolution failed): executeListener must be a boolean`);
+    }
+
+    paramName = paramNameOrListener;
+    listener = listenerOrExecuteCallback;
+    executeListener = someExecuteListener;
+  }
+
+  // Check that paramName exists in description
+  if (paramName !== null) {
+    try {
+      caller.getDescription(paramName);
+    } catch {
+      throw new ReferenceError(`Cannot execute 'onUpdate' on ${className}: parameter '${paramName}' does not exists`);
+    }
+  }
+
+  return { paramName, listener, executeListener };
+}
+
+
+/**
+ * Check that given filters match the class description
+ * Used in ServerStateManager and SharedStateCollection
+ * @private
+ */
+export function checkValidFilters(options, className, classDescription) {
+  const classParams = Object.keys(classDescription);
+
+  for (let filterName of ['whiteList', 'backList']) {
+    if (!options[filterName]) {
+      continue;
+    }
+
+    const list = options[filterName];
+    const invalid = list.filter(paramName => !classParams.includes(paramName));
+
+    if (invalid.length > 0) {
+      const msg = `Invalid filter (${invalid.join(', ')}) for shared state class '${className}'`;
+      throw new Error(msg);
+    }
+  }
+}

package/src/common/version.js

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

package/src/server/Server.js

@@ -1,8 +1,6 @@
 import EventEmitter from 'node:events';
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
-
 
 import {
   isPlainObject,
@@ -10,10 +8,12 @@ import {
   counter,
   getTime,
 } from '@ircam/sc-utils';
-import chalk from 'chalk';
 import Keyv from 'keyv';
 import { KeyvFile } from 'keyv-file';
-import _ from 'lodash';
+import { defu } from 'defu';
+
+import gatedLogger from '../common/logs/gated-logger.js';
+import warnings from '../common/logs/warnings.js';
 
 import auditClassDescription from './audit-state-class-description.js';
 import {
@@ -22,6 +22,7 @@ import {
 } from './crypto.js';
 import {
   createHttpServer,
+  logServerInfos,
 } from './create-http-server.js';
 import ServerClient, {
   kServerClientToken,
@@ -57,7 +58,6 @@ import ServerSockets, {
   kSocketsStart,
   kSocketsStop,
 } from './ServerSockets.js';
-import logger from '../common/logger.js';
 import {
   SERVER_ID,
   CLIENT_HANDSHAKE_REQUEST,
@@ -159,7 +159,7 @@ class Server {
       throw new TypeError(`Cannot construct 'Server': Parameter 1 must be an object`);
     }
 
-    config = _.merge({}, DEFAULT_CONFIG, config);
+    config = defu(config, DEFAULT_CONFIG);
 
     // ---------------------------------------------------------------------
     // Deprecation checks for config
@@ -170,7 +170,7 @@ class Server {
       const clientConfig = config.app.clients[role];
 
       if (clientConfig.target) {
-        logger.deprecated('ClientDescription#target', 'ClientDescription#runtime (or run `npx soundworks --upgrade-config` to upgrade your config files)', '4.0.0-alpha.29');
+        warnings.deprecated('ClientDescription#target', 'ClientDescription#runtime (or run `npx soundworks --upgrade-config` to upgrade your config files)', '4.0.0-alpha.29');
         clientConfig.runtime = clientConfig.target;
         delete clientConfig.target;
       }
@@ -178,7 +178,7 @@ class Server {
 
     // `env.subpath` to `env.baseUrl`
     if ('subpath' in config.env) {
-      logger.deprecated('ServerConfig#subpath', 'ServerConfig#baseUrl (or run `npx soundworks --upgrade-config` to upgrade your config files)', '4.0.0-alpha.29');
+      warnings.deprecated('ServerConfig#subpath', 'ServerConfig#baseUrl (or run `npx soundworks --upgrade-config` to upgrade your config files)', '4.0.0-alpha.29');
       config.env.baseUrl = config.env.subpath;
       delete config.env.subpath;
     }
@@ -240,7 +240,7 @@ class Server {
     // register audit state schema
     this.#stateManager.defineClass(AUDIT_STATE_NAME, auditClassDescription);
 
-    logger.configure(this.#config.env.verbose);
+    gatedLogger.verbose = !!this.#config.env.verbose;
   }
 
   /**
@@ -506,7 +506,7 @@ class Server {
         const { configureHttpRouter } = await import('@soundworks/helpers/server.js');
         configureHttpRouter(this);
       } catch (err) {
-        logger.warn('Could not apply patch for deprecated `useDefaultApplicationTemplate` method. Please use `configureHttpRouter` from helpers instead.');
+        console.warn('Could not apply patch for deprecated `useDefaultApplicationTemplate` method. Please use `configureHttpRouter` from helpers instead.');
         throw err;
       }
     }
@@ -516,7 +516,7 @@ class Server {
       this.#httpServer = await createHttpServer(this);
       await this.#dispatchStatus('http-server-ready');
     } catch (err) {
-      logger.error(err.message);
+      console.error(err.message);
       await this.#dispatchStatus('errored');
       throw err;
     }
@@ -564,31 +564,19 @@ class Server {
     // start `SocketServer`
     await this.#sockets[kSocketsStart]();
     // start httpServer
-    return new Promise(resolve => {
-      const port = this.#config.env.port;
-      const protocol = this.#config.env.useHttps ? 'https' : 'http';
-      const interfaces = os.networkInterfaces();
-
-      this.#httpServer.listen(port, async () => {
-        logger.title(`${protocol} server listening on`);
-
-        Object.keys(interfaces).forEach(dev => {
-          interfaces[dev].forEach(details => {
-            if (details.family === 'IPv4') {
-              logger.ip(protocol, details.address, port);
-            }
-          });
-        });
+    const { promise, resolve } = Promise.withResolvers();
 
-        await this.#dispatchStatus('started');
+    this.#httpServer.listen(this.#config.env.port, async () => {
+      if (this.#config.env.verbose) {
+        logServerInfos(this.#config.env);
+      }
 
-        if (this.#config.env.type === 'development') {
-          logger.log(`\n> press "${chalk.bold('Ctrl + C')}" to exit`);
-        }
+      await this.#dispatchStatus('started');
 
-        resolve();
-      });
+      resolve();
     });
+
+    return promise;
   }
 
   /**
@@ -709,7 +697,7 @@ class Server {
       }
 
       if (version !== this.#version) {
-        logger.warnVersionDiscrepancies(role, version, this.#version);
+        warnings.versionDiscrepancies(role, version, this.#version);
       }
 
       try {
@@ -872,7 +860,7 @@ class Server {
     // @note - keyv-file doesn't seems to works
     const store = new KeyvFile({ filename });
     const db = new Keyv({ namespace, store });
-    db.on('error', err => logger.error(`[soundworks:Server] db ${namespace} error: ${err}`));
+    db.on('error', err => console.error(`namespaced db ("${namespace}") error:`, err));
 
     return db;
   }
@@ -881,7 +869,7 @@ class Server {
    * @deprecated
    */
   useDefaultApplicationTemplate() {
-    logger.deprecated('Server#useDefaultApplicationTemplate', '`configureHttpRouter(server)` from the `@soundworks/helpers/server.js` package', '4.0.0-alpha.29');
+    warnings.deprecated('Server#useDefaultApplicationTemplate', '`configureHttpRouter(server)` from the `@soundworks/helpers/server.js` package', '4.0.0-alpha.29');
     this.#useDefaultApplicationTemplate = true;
   }
 }

package/src/server/ServerClient.js

@@ -1,5 +1,9 @@
-import { counter } from '@ircam/sc-utils';
-import { v4 as uuid } from 'uuid';
+import crypto from 'node:crypto';
+
+import {
+  counter,
+} from '@ircam/sc-utils';
+
 
 const generateId = counter();
 
@@ -24,7 +28,7 @@ class ServerClient {
   constructor(role, socket) {
     this.#role = role;
     this.#id = generateId();
-    this.#uuid = uuid();
+    this.#uuid = crypto.randomUUID();
     this.#socket = socket;
 
     /**