@soundworks/core 5.0.1 → 5.0.3

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## v5.0.3 - 2025-02-13
+
+- Fix: unexpected error when getting description of shared state class with required parameter
+
 ## v5.0.0 - 2025-01-30
 
 ### Breaking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "5.0.1",
+  "version": "5.0.3",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "collaborators": [
     "Benjamin Matuszewski",
@@ -47,6 +47,7 @@
     "doc": "npm run types && rm -rf docs && jsdoc -c .jsdoc --verbose && cp -R misc/assets docs/",
     "lint": "npx eslint src",
     "test": "npx mocha tests/*/*.spec.js",
+    "test:ci": "npx mocha tests/*/*.spec.js --ci",
     "test:only": "npx mocha",
     "types": "rm -rf types && tsc",
     "preversion": "npm run lint && npm run test && node ./misc/scripts/generate-version-file.js $npm_new_version && npm run types",

package/src/client/ClientPlugin.js

@@ -1,5 +1,7 @@
 import BasePlugin from '../common/BasePlugin.js';
 
+export const kClientPluginName = Symbol.for('soundworks:client-plugin-name');
+
 /**
  * Callback executed when the plugin state is updated.
  *
@@ -31,12 +33,16 @@ import BasePlugin from '../common/BasePlugin.js';
  * @extends BasePlugin
  * @inheritdoc
  */
-class ClientPlugin extends BasePlugin {
+export default class ClientPlugin extends BasePlugin {
+  // Note: we need this workaround in plugin tests, because the test app and
+  // the tested plugin will import different versions of ServerPlugin
+  static [kClientPluginName] = 'ClientPlugin';
+
   #client = null;
+
   /**
    * @param {Client} client - A soundworks client instance.
-   * @param {string} id - User defined id of the plugin as defined in
-   *  {@link ClientPluginManager#register}.
+   * @param {string} id - User defined id of the plugin as defined in {@link ClientPluginManager#register}.
    */
   constructor(client, id) {
     super(id);
@@ -67,5 +73,3 @@ class ClientPlugin extends BasePlugin {
   //  */
   // async deactivate() {}
 }
-
-export default ClientPlugin;

package/src/client/ClientPluginManager.js

@@ -1,6 +1,6 @@
-import BasePluginManager from '../common/BasePluginManager.js';
-import ClientPlugin from './ClientPlugin.js';
 import Client from './Client.js';
+import BasePluginManager from '../common/BasePluginManager.js';
+import { kClientPluginName } from './ClientPlugin.js';
 
 /**
  * The `PluginManager` allows to register and retrieve `soundworks` plugins.
@@ -98,7 +98,7 @@ class ClientPluginManager extends BasePluginManager {
    */
   register(id, ctor, options = {}, deps = []) {
     // Note that other arguments are checked on the BasePluginManager
-    if (!ctor || !(ctor.prototype instanceof ClientPlugin)) {
+    if (!ctor || ctor[kClientPluginName] !== 'ClientPlugin') {
       throw new TypeError(`Cannot execute 'register' on ClientPluginManager: argument 2 must be a class that extends 'ClientPlugin'`);
     }
 

package/src/common/BaseStateManager.js

@@ -236,12 +236,13 @@ class BaseStateManager {
     this[kStateManagerClient].transport.addListener(
       GET_CLASS_DESCRIPTION_RESPONSE,
       (reqId, className, classDescription) => {
+        const fullDescription = ParameterBag.getFullDescription(classDescription);
+
         if (!this.#cachedClasses.has(className)) {
-          this.#cachedClasses.set(className, classDescription);
+          this.#cachedClasses.set(className, fullDescription);
         }
-        // This cannot throw as the SharedState class has already been registered
-        const parameterBag = new ParameterBag(classDescription);
-        this.#promiseStore.resolve(reqId, parameterBag.getDescription());
+
+        this.#promiseStore.resolve(reqId, fullDescription);
       },
     );
 
@@ -268,10 +269,7 @@ class BaseStateManager {
     }
 
     if (this.#cachedClasses.has(className)) {
-      const classDescription = this.#cachedClasses.get(className);
-      // This cannot throw as the SharedState class has already been registered
-      const parameterBag = new ParameterBag(classDescription);
-      return parameterBag.getDescription();
+      return this.#cachedClasses.get(className);
     }
 
     return new Promise((resolve, reject) => {

package/src/common/ParameterBag.js

@@ -165,6 +165,33 @@ class ParameterBag {
     }
   }
 
+  static getFullDescription(description) {
+    const fullDescription = cloneDeep(description);
+
+    for (let [name, def] of Object.entries(fullDescription)) {
+      if (types[def.type].sanitizeDescription) {
+        def = types[def.type].sanitizeDescription(def);
+      }
+
+      const { defaultOptions } = types[def.type];
+      def = Object.assign({}, defaultOptions, def);
+      // if event property is set to true, the param must
+      // be nullable and its default value is `undefined`
+      if (def.event === true) {
+        def.nullable = true;
+        def.default = null;
+      }
+
+      if (def.required === true) {
+        def.default = null;
+      }
+
+      fullDescription[name] = def;
+    }
+
+    return fullDescription;
+  }
+
   #description = {};
   #values = {};
 
@@ -173,11 +200,11 @@ class ParameterBag {
       throw new TypeError(`Cannot construct ParameterBag: argument 1 must be an object`);
     }
 
-    description = cloneDeep(description);
-    initValues = cloneDeep(initValues);
-
     ParameterBag.validateDescription(description);
 
+    description = ParameterBag.getFullDescription(description);
+    initValues = cloneDeep(initValues);
+
     // make sure initValues make sens according to the given description
     for (let name in initValues) {
       if (!Object.prototype.hasOwnProperty.call(description, name)) {
@@ -186,19 +213,6 @@ class ParameterBag {
     }
 
     for (let [name, def] of Object.entries(description)) {
-      if (types[def.type].sanitizeDescription) {
-        def = types[def.type].sanitizeDescription(def);
-      }
-
-      const { defaultOptions } = types[def.type];
-      def = Object.assign({}, defaultOptions, def);
-      // if event property is set to true, the param must
-      // be nullable and its default value is `undefined`
-      if (def.event === true) {
-        def.nullable = true;
-        def.default = null;
-      }
-
       if (def.required === true) {
         // throw if value is not given in init values
         if (initValues[name] === undefined || initValues[name] === null) {
@@ -216,13 +230,11 @@ class ParameterBag {
         initValue = def.default;
       }
 
-
       this.#description[name] = def;
       // coerce init value and store in definition
-      initValue = this.set(name, initValue)[0];
-
-      this.#description[name].initValue = initValue;
-      this.#values[name] = initValue;
+      const coercedInitValue = this.set(name, initValue)[0];
+      this.#description[name].initValue = coercedInitValue;
+      this.#values[name] = coercedInitValue;
     }
   }
 

package/src/common/version.js

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

package/src/server/ServerClient.js

@@ -1,7 +1,7 @@
-import { idGenerator } from '@ircam/sc-utils';
+import { counter } from '@ircam/sc-utils';
 import { v4 as uuid } from 'uuid';
 
-const generateId = idGenerator();
+const generateId = counter();
 
 export const kServerClientToken = Symbol('soundworks:server-client-token');
 
@@ -23,7 +23,7 @@ class ServerClient {
    */
   constructor(role, socket) {
     this.#role = role;
-    this.#id = generateId.next().value;
+    this.#id = generateId();
     this.#uuid = uuid();
     this.#socket = socket;
 

package/src/server/ServerPlugin.js

@@ -1,5 +1,7 @@
 import BasePlugin from '../common/BasePlugin.js';
 
+export const kServerPluginName = Symbol.for('soundworks:server-plugin-name');
+
 /**
  * Base class to extend in order to create the server-side counterpart of a
  * `soundworks` plugin.
@@ -18,14 +20,17 @@ import BasePlugin from '../common/BasePlugin.js';
  * @extends {BasePlugin}
  * @inheritdoc
  */
-class ServerPlugin extends BasePlugin {
+export default class ServerPlugin extends BasePlugin {
+  // Note: we need this workaround in plugin tests, because the test app and
+  // the tested plugin will import different versions of ServerPlugin
+  static [kServerPluginName] = 'ServerPlugin';
+
   #server = null;
   #clients = new Set();
 
   /**
    * @param {Server} server - The soundworks server instance.
-   * @param {string} id - User defined id of the plugin as defined in
-   *  {@link ServerPluginManager#register}.
+   * @param {string} id - User defined id of the plugin as defined in {@link ServerPluginManager#register}.
    */
   constructor(server, id) {
     super(id);
@@ -72,5 +77,3 @@ class ServerPlugin extends BasePlugin {
     this.#clients.delete(client);
   }
 }
-
-export default ServerPlugin;

package/src/server/ServerPluginManager.js

@@ -1,8 +1,8 @@
+import Server from './Server.js';
 import BasePluginManager, {
   kPluginManagerInstances,
 } from '../common/BasePluginManager.js';
-import ServerPlugin from './ServerPlugin.js';
-import Server from './Server.js';
+import { kServerPluginName } from './ServerPlugin.js';
 
 export const kServerPluginManagerCheckRegisteredPlugins = Symbol('soundworks:server-plugin-manager-check-registered-plugins');
 export const kServerPluginManagerAddClient = Symbol('soundworks:server-plugin-manager-add-client');
@@ -140,7 +140,7 @@ class ServerPluginManager extends BasePluginManager {
    */
   register(id, ctor, options = {}, deps = []) {
     // Note that other arguments are checked on the BasePluginManager
-    if (!ctor || !(ctor.prototype instanceof ServerPlugin)) {
+    if (!ctor || ctor[kServerPluginName] !== 'ServerPlugin') {
       throw new TypeError(`Cannot execute 'register' on ServerPluginManager (id: ${id}): argument 2 must be a class that extends 'ServerPlugin'`);
     }
 

package/src/server/ServerSockets.js

@@ -120,7 +120,7 @@ class ServerSockets {
   }
 
   /**
-   * Remove given socket from all rooms.
+   * Delete given socket.
    * @private
    */
   [kSocketsDeleteSocket](socket) {

package/src/server/ServerStateManager.js

@@ -471,21 +471,21 @@ class ServerStateManager extends BaseStateManager {
    */
   defineClass(className, classDescription) {
     if (!isString(className)) {
-      throw new TypeError(`Cannot execute 'defineClass' on ServerStateManager: argument 1 must be of type SharedStateClassName`);
+      throw new TypeError(`Cannot execute 'defineClass' (${className}) on ServerStateManager: argument 1 must be of type SharedStateClassName`);
     }
 
     if (!isPlainObject(classDescription)) {
-      throw new TypeError(`Cannot execute 'defineClass' on ServerStateManager: argument 2 must be of type SharedStateClassDescription`);
+      throw new TypeError(`Cannot execute 'defineClass' (${className}) on ServerStateManager: argument 2 must be of type SharedStateClassDescription`);
     }
 
     if (this.#classes.has(className)) {
-      throw new DOMException(`Cannot execute 'defineClass' on ServerStateManager: SharedState class '${className}' is already defined`, 'NotSupportedError');
+      throw new DOMException(`Cannot execute 'defineClass'(${className})  on ServerStateManager: SharedState class '${className}' is already defined`, 'NotSupportedError');
     }
 
     try {
       ParameterBag.validateDescription(classDescription);
     } catch (err) {
-      throw new TypeError(`Cannot execute 'defineClass' on ServerStateManager: ${err.message}`);
+      throw new TypeError(`Cannot execute 'defineClass' (${className}) on ServerStateManager: ${err.message}`);
     }
 
     this.#classes.set(className, clonedeep(classDescription));
@@ -586,11 +586,11 @@ class ServerStateManager extends BaseStateManager {
    */
   registerCreateHook(className, createHook) {
     if (!this.#classes.has(className)) {
-      throw new TypeError(`Cannot execute 'registerCreateHook' on BaseStateManager: SharedState class '${className}' is not defined`);
+      throw new TypeError(`Cannot execute 'registerCreateHook' (${className}) on BaseStateManager: SharedState class '${className}' is not defined`);
     }
 
     if (!isFunction(createHook)) {
-      throw new TypeError(`Cannot execute 'registerCreateHook' on BaseStateManager: argument 2 must be a function`);
+      throw new TypeError(`Cannot execute 'registerCreateHook' (${className}) on BaseStateManager: argument 2 must be a function`);
     }
 
     const hooks = this.#createHooksByClassName.get(className);
@@ -634,11 +634,11 @@ class ServerStateManager extends BaseStateManager {
    */
   registerDeleteHook(className, deleteHook) {
     if (!this.#classes.has(className)) {
-      throw new TypeError(`Cannot execute 'registerDeleteHook' on BaseStateManager: SharedState class '${className}' is not defined`);
+      throw new TypeError(`Cannot execute 'registerDeleteHook' (${className}) on BaseStateManager: SharedState class '${className}' is not defined`);
     }
 
     if (!isFunction(deleteHook)) {
-      throw new TypeError(`Cannot execute 'registerDeleteHook' on BaseStateManager: argument 2 must be a function`);
+      throw new TypeError(`Cannot execute 'registerDeleteHook' (${className}) on BaseStateManager: argument 2 must be a function`);
     }
 
     const hooks = this.#deleteHooksByClassName.get(className);
@@ -689,11 +689,11 @@ class ServerStateManager extends BaseStateManager {
    */
   registerUpdateHook(className, updateHook) {
     if (!this.#classes.has(className)) {
-      throw new TypeError(`Cannot execute 'registerUpdateHook' on BaseStateManager: SharedState class '${className}' is not defined`);
+      throw new TypeError(`Cannot execute 'registerUpdateHook' (${className}) on BaseStateManager: SharedState class '${className}' is not defined`);
     }
 
     if (!isFunction(updateHook)) {
-      throw new TypeError(`Cannot execute 'registerUpdateHook' on BaseStateManager: argument 2 must be a function`);
+      throw new TypeError(`Cannot execute 'registerUpdateHook' (${className}) on BaseStateManager: argument 2 must be a function`);
     }
 
     const hooks = this.#updateHooksByClassName.get(className);

package/types/client/ClientPlugin.d.ts

@@ -1,8 +1,4 @@
-export default ClientPlugin;
-/**
- * ~onStateChangeCallback
- */
-export type ClientPlugin = (#state: ClientPlugin) => any;
+export const kClientPluginName: unique symbol;
 /**
  * Callback executed when the plugin state is updated.
  *
@@ -32,11 +28,11 @@ export type ClientPlugin = (#state: ClientPlugin) => any;
  * @extends BasePlugin
  * @inheritdoc
  */
-declare class ClientPlugin extends BasePlugin {
+export default class ClientPlugin extends BasePlugin {
+    static [kClientPluginName]: string;
     /**
      * @param {Client} client - A soundworks client instance.
-     * @param {string} id - User defined id of the plugin as defined in
-     *  {@link ClientPluginManager#register}.
+     * @param {string} id - User defined id of the plugin as defined in {@link ClientPluginManager#register}.
      */
     constructor(client: Client, id: string);
     /**
@@ -48,4 +44,8 @@ declare class ClientPlugin extends BasePlugin {
     get client(): Client;
     #private;
 }
+/**
+ * ~onStateChangeCallback
+ */
+export type ClientPlugin = (#state: ClientPlugin) => any;
 import BasePlugin from '../common/BasePlugin.js';

package/types/client/ClientPluginManager.d.ts

@@ -108,5 +108,4 @@ declare class ClientPluginManager<T> extends BasePluginManager {
     get(id: string): Promise<T<ClientPlugin>>;
 }
 import BasePluginManager from '../common/BasePluginManager.js';
-import ClientPlugin from './ClientPlugin.js';
 import Client from './Client.js';

package/types/common/ParameterBag.d.ts

@@ -62,6 +62,7 @@ export default ParameterBag;
 /** @private */
 declare class ParameterBag {
     static validateDescription(description: any): void;
+    static getFullDescription(description: any): any;
     constructor(description: any, initValues?: {});
     /**
      * Define if the parameter exists.

package/types/common/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "5.0.1";
+declare const _default: "5.0.3";
 export default _default;

package/types/server/ServerPlugin.d.ts

@@ -1,4 +1,4 @@
-export default ServerPlugin;
+export const kServerPluginName: unique symbol;
 /**
  * Base class to extend in order to create the server-side counterpart of a
  * `soundworks` plugin.
@@ -17,11 +17,11 @@ export default ServerPlugin;
  * @extends {BasePlugin}
  * @inheritdoc
  */
-declare class ServerPlugin extends BasePlugin {
+export default class ServerPlugin extends BasePlugin {
+    static [kServerPluginName]: string;
     /**
      * @param {Server} server - The soundworks server instance.
-     * @param {string} id - User defined id of the plugin as defined in
-     *  {@link ServerPluginManager#register}.
+     * @param {string} id - User defined id of the plugin as defined in {@link ServerPluginManager#register}.
      */
     constructor(server: Server, id: string);
     /**

package/types/server/ServerPluginManager.d.ts

@@ -112,4 +112,3 @@ declare class ServerPluginManager<T> extends BasePluginManager {
     private [kServerPluginManagerRemoveClient];
 }
 import BasePluginManager from '../common/BasePluginManager.js';
-import ServerPlugin from './ServerPlugin.js';

package/types/server/ServerSockets.d.ts

@@ -32,7 +32,7 @@ declare class ServerSockets {
      */
     private [kSocketsStop];
     /**
-     * Remove given socket from all rooms.
+     * Delete given socket.
      * @private
      */
     private [kSocketsDeleteSocket];