@soundworks/core 5.1.2 → 5.2.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## v5.2.1 - 2025-08-11
+
+- Fix: Use CancelablePromise to cancel pending promise rather than reject when a state is deleted
+
+## v5.2.0 - 2025-05-05
+
+- Feat: add ServerStateManager#isClassDefined method
+- Fix: Remove class description cache mechanism to avoid possible concurrency issues when recreating a SharedStateClass with same name
+
 ## v5.1.1 - 2025-04-28
 
 - Hotfix: run behind https proxy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "5.1.2",
+  "version": "5.2.1",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "collaborators": [
     "Benjamin Matuszewski",
@@ -55,6 +55,7 @@
   },
   "dependencies": {
     "@ircam/sc-utils": "^1.8.0",
+    "cancelable-promise": "^4.3.1",
     "chalk": "^5.3.0",
     "fast-deep-equal": "^3.1.3",
     "isomorphic-ws": "^5.0.0",

package/src/client/ClientContext.js

@@ -214,10 +214,10 @@ class ClientContext {
 
     // we need the try/catch block to change the promise rejection into proper error
     try {
-      await new Promise((resolve, reject) => {
-        const reqId = promiseStore.add(resolve, reject, 'ClientContext#enter');
-        this.#client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
-      });
+      const { id: reqId, promise } = promiseStore.createPromise();
+      this.#client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
+
+      await promise;
     } catch (err) {
       throw new Error(err);
     }
@@ -248,10 +248,10 @@ class ClientContext {
   async exit() {
     // we need the try/catch block to change the promise rejection into proper error
     try {
-      await new Promise((resolve, reject) => {
-        const reqId = promiseStore.add(resolve, reject, 'ClientContext#exit');
-        this.#client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
-      });
+      const { id: reqId, promise } = promiseStore.createPromise();
+      this.#client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
+
+      await promise;
     } catch (err) {
       throw new Error(err);
     }

package/src/client/index.js

@@ -18,7 +18,7 @@
  * Environment configuration object.
  *
  * @typedef ClientEnvConfig
- * @type {objecy}
+ * @type {object}
  * @property {number} env.port - Port on which the server is listening.
  * @property {string} env.serverAddress - Domain name or IP of the server.
  *  Mandatory when node clients are declared

package/src/common/BaseStateManager.js

@@ -18,7 +18,7 @@ import {
   OBSERVE_ERROR,
   OBSERVE_NOTIFICATION,
   UNOBSERVE_NOTIFICATION,
-  DELETE_SHARED_STATE_CLASS,
+  // DELETE_SHARED_STATE_CLASS,
   GET_CLASS_DESCRIPTION_REQUEST,
   GET_CLASS_DESCRIPTION_RESPONSE,
   GET_CLASS_DESCRIPTION_ERROR,
@@ -49,7 +49,6 @@ export const kStateManagerClient = Symbol('soundworks:state-manager-client');
 /** @private */
 class BaseStateManager {
   #statesById = new Map();
-  #cachedClasses = new Map(); // <className, definition>
   #observeListeners = new Set(); // Set <[observedClassName, callback, options]>
   #observeRequestCallbacks = new Map(); // Map <reqId, [observedClassName, callback, options]>
   #promiseStore = null;
@@ -100,15 +99,6 @@ class BaseStateManager {
     this[kStateManagerClient].transport.addListener(
       CREATE_RESPONSE,
       (reqId, stateId, instanceId, className, classDescription, initValues) => {
-        // cache class description to save some bandwidth
-        // @note: when we make the class dynamic, we will need some mechanism to
-        // invalidate the cached description
-        if (!this.#cachedClasses.has(className)) {
-          this.#cachedClasses.set(className, classDescription);
-        }
-
-        classDescription = this.#cachedClasses.get(className);
-
         const state = new SharedState({
           manager: this,
           className,
@@ -136,15 +126,6 @@ class BaseStateManager {
     this[kStateManagerClient].transport.addListener(
       ATTACH_RESPONSE,
       (reqId, stateId, instanceId, className, classDescription, currentValues, filter) => {
-        // cache class description to save some bandwidth
-        // @note: when we make the class dynamic, we will need some mechanism to
-        // invalidate the cached description
-        if (!this.#cachedClasses.has(className)) {
-          this.#cachedClasses.set(className, classDescription);
-        }
-
-        classDescription = this.#cachedClasses.get(className);
-
         const state = new SharedState({
           manager: this,
           className,
@@ -224,24 +205,19 @@ class BaseStateManager {
     );
 
     // ---------------------------------------------
-    // Clear cache when a shared state class is deleted
+    // note 2025-05-05: caching of class descriptions has been removed because it
+    // could create concurrency issues
+    // cf. `should be able to recreate a class with the same name` unit test
     // ---------------------------------------------
-    this[kStateManagerClient].transport.addListener(DELETE_SHARED_STATE_CLASS, className => {
-      this.#cachedClasses.delete(className);
-    });
+    // this[kStateManagerClient].transport.addListener(DELETE_SHARED_STATE_CLASS, _className => {});
 
     // ---------------------------------------------
     // Get class description
     // ---------------------------------------------
     this[kStateManagerClient].transport.addListener(
       GET_CLASS_DESCRIPTION_RESPONSE,
-      (reqId, className, classDescription) => {
+      (reqId, _className, classDescription) => {
         const fullDescription = ParameterBag.getFullDescription(classDescription);
-
-        if (!this.#cachedClasses.has(className)) {
-          this.#cachedClasses.set(className, fullDescription);
-        }
-
         this.#promiseStore.resolve(reqId, fullDescription);
       },
     );
@@ -268,14 +244,10 @@ class BaseStateManager {
       throw new DOMException(`Cannot execute 'getClassDescription' on BaseStateManager: BaseStateManager is not inited`, 'InvalidStateError');
     }
 
-    if (this.#cachedClasses.has(className)) {
-      return this.#cachedClasses.get(className);
-    }
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    this[kStateManagerClient].transport.emit(GET_CLASS_DESCRIPTION_REQUEST, reqId, className);
 
-    return new Promise((resolve, reject) => {
-      const reqId = this.#promiseStore.add(resolve, reject, 'BaseStateManager#getClassDescription');
-      this[kStateManagerClient].transport.emit(GET_CLASS_DESCRIPTION_REQUEST, reqId, className);
-    });
+    return promise;
   }
 
   /**
@@ -300,11 +272,10 @@ class BaseStateManager {
       throw new DOMException(`Cannot execute 'create' on BaseStateManager: BaseStateManager is not inited`, 'InvalidStateError');
     }
 
-    return new Promise((resolve, reject) => {
-      const reqId = this.#promiseStore.add(resolve, reject, 'BaseStateManager#create');
-      const requireDescription = this.#cachedClasses.has(className) ? false : true;
-      this[kStateManagerClient].transport.emit(CREATE_REQUEST, reqId, className, requireDescription, initValues);
-    });
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    this[kStateManagerClient].transport.emit(CREATE_REQUEST, reqId, className, initValues);
+
+    return promise;
   }
 
   /**
@@ -409,11 +380,10 @@ class BaseStateManager {
       }
     }
 
-    return new Promise((resolve, reject) => {
-      const reqId = this.#promiseStore.add(resolve, reject, 'BaseStateManager#attach');
-      const requireDescription = this.#cachedClasses.has(className) ? false : true;
-      this[kStateManagerClient].transport.emit(ATTACH_REQUEST, reqId, className, stateId, requireDescription, filter);
-    });
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    this[kStateManagerClient].transport.emit(ATTACH_REQUEST, reqId, className, stateId, filter);
+
+    return promise;
   }
 
   /**
@@ -592,33 +562,33 @@ class BaseStateManager {
     }
 
     // resend request to get updated list of states
-    return new Promise((resolve, reject) => {
-      const reqId = this.#promiseStore.add(resolve, reject, 'BaseStateManager#observe');
-      // store the callback for execution on the response. the returned Promise
-      // is fulfilled once callback has been executed with each existing states
-      const observeInfos = [observedClassName, callback, options];
-      this.#observeRequestCallbacks.set(reqId, observeInfos);
-
-      // NOTE: do not store in `_observeListeners` yet as it can produce race
-      // conditions, e.g.:
-      // ```
-      // await client.stateManager.observe(async (className, stateId, nodeId) => {});
-      // // client now receives OBSERVE_NOTIFICATIONS
-      // await otherClient.stateManager.create('a');
-      // // second observer added in between
-      // client.stateManager.observe(async (className, stateId, nodeId) => {});
-      // ````
-      // OBSERVE_NOTIFICATION is received before the OBSERVE_RESPONSE, then the
-      // second observer is called twice:
-      // - OBSERVE_RESPONSE 1 []
-      // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ]
-      // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ] // this should not happen
-      // - OBSERVE_RESPONSE 1 [ [ 'a', 1, 0 ] ]
-      //
-      // cf. unit test `observe should properly behave in race condition`
-
-      this[kStateManagerClient].transport.emit(OBSERVE_REQUEST, reqId, observedClassName);
-    });
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    // store the callback for execution on the response. the returned Promise
+    // is fulfilled once callback has been executed with each existing states
+    const observeInfos = [observedClassName, callback, options];
+    this.#observeRequestCallbacks.set(reqId, observeInfos);
+
+    // NOTE: do not store in `_observeListeners` yet as it can produce race
+    // conditions, e.g.:
+    // ```
+    // await client.stateManager.observe(async (className, stateId, nodeId) => {});
+    // // client now receives OBSERVE_NOTIFICATIONS
+    // await otherClient.stateManager.create('a');
+    // // second observer added in between
+    // client.stateManager.observe(async (className, stateId, nodeId) => {});
+    // ````
+    // OBSERVE_NOTIFICATION is received before the OBSERVE_RESPONSE, then the
+    // second observer is called twice:
+    // - OBSERVE_RESPONSE 1 []
+    // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ]
+    // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ] // this should not happen
+    // - OBSERVE_RESPONSE 1 [ [ 'a', 1, 0 ] ]
+    //
+    // cf. unit test `observe should properly behave in race condition`
+
+    this[kStateManagerClient].transport.emit(OBSERVE_REQUEST, reqId, observedClassName);
+
+    return promise;
   }
 
   /**

package/src/common/BatchedTransport.js

@@ -1,11 +1,7 @@
 import { BATCHED_TRANSPORT_CHANNEL } from './constants.js';
 
 /**
- * This class proxies transports given the SharedStateManager to batch messages
- *
- * @param {number} [options.wait=0] - Wait for given number of milliseconds
- *  for stacking messages before emitting on the network. If 0 is given, network
- *  message is emitted on next microtask
+ * This class proxies transports, i.e. WebSockets, to batch message sends
  * @private
  */
 class BatchedTransport {

package/src/common/PromiseStore.js

@@ -1,52 +1,68 @@
-import { idGenerator } from '@ircam/sc-utils';
+import { counter } from '@ircam/sc-utils';
+// common js module...
+import cancelable from 'cancelable-promise';
+const { CancelablePromise } = cancelable;
 
 /** @private */
 export default class PromiseStore {
   constructor(name) {
     this.name = name;
     this.store = new Map();
-    this.generateRequestId = idGenerator();
+    this.generateId = counter();
   }
 
-  add(resolve, reject, type, localParams) {
-    const reqId = this.generateRequestId.next().value;
-    this.store.set(reqId, { resolve, reject, type, localParams });
+  createPromise() {
+    const id = this.generateId();
+    let resolve, reject;
 
-    return reqId;
+    const promise = new CancelablePromise((resolveFunc, rejectFunc) => {
+      resolve = resolveFunc;
+      reject = rejectFunc;
+    });
+
+    this.store.set(id, { promise, resolve, reject });
+
+    return { id, promise };
+  }
+
+  // associate data to merge within the data given when calling `resolve`
+  // cf. SharedState#set
+  associateResolveData(id, associatedData) {
+    const stored = this.store.get(id);
+    stored.associatedData = associatedData;
   }
 
-  resolve(reqId, data) {
-    if (this.store.has(reqId)) {
-      const { resolve, localParams } = this.store.get(reqId);
-      this.store.delete(reqId);
+  resolve(id, data) {
+    if (this.store.has(id)) {
+      const { resolve, associatedData } = this.store.get(id);
+      this.store.delete(id);
 
       // re-merge local params into network response
-      if (localParams !== undefined) {
-        Object.assign(data, localParams);
+      if (associatedData !== undefined) {
+        Object.assign(data, associatedData);
       }
 
       resolve(data);
     } else {
-      throw new ReferenceError(`Cannot resolve request id (${reqId}): id does not exist`);
+      throw new ReferenceError(`Cannot resolve request id (${id}): id does not exist`);
     }
   }
 
-  reject(reqId, msg) {
-    if (this.store.has(reqId)) {
-      const { reject } = this.store.get(reqId);
-      this.store.delete(reqId);
+  reject(id, msg) {
+    if (this.store.has(id)) {
+      const { reject } = this.store.get(id);
+      this.store.delete(id);
 
       reject(new Error(msg));
     } else {
-      throw new ReferenceError(`Cannot resolve request id (${reqId}): id does not exist`);
+      throw new ReferenceError(`Cannot resolve request id (${id}): id does not exist`);
     }
   }
 
-  // reject all pending request
+  // cancel all pending request
   flush() {
-    for (let [_reqId, entry] of this.store) {
-      const { reject, type } = entry;
-      reject(new Error(`Discard promise '${type}'`));
+    for (let [_id, entry] of this.store) {
+      entry.promise.cancel();
     }
 
     this.store.clear();

package/src/common/SharedState.js

@@ -555,10 +555,13 @@ class SharedState {
     updates = sharedParams;
 
     // go through server-side normal behavior
-    return new Promise((resolve, reject) => {
-      const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'SharedState#set', forwardParams);
-      this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, updates);
-    });
+    const { id: reqId, promise } = this[kSharedStatePromiseStore].createPromise();
+    if (forwardParams) {
+      this[kSharedStatePromiseStore].associateResolveData(reqId, forwardParams);
+    }
+    this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, updates);
+
+    return promise;
   }
 
   /**
@@ -710,15 +713,13 @@ class SharedState {
     this.#onUpdateCallbacks.clear();
 
     if (this.#isOwner) {
-      return new Promise((resolve, reject) => {
-        const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'SharedState#delete');
-        this.#client.transport.emit(`${DELETE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId);
-      });
+      const { id: reqId, promise } = this[kSharedStatePromiseStore].createPromise();
+      this.#client.transport.emit(`${DELETE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId);
+      return promise;
     } else {
-      return new Promise((resolve, reject) => {
-        const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'SharedState#detach');
-        this.#client.transport.emit(`${DETACH_REQUEST}-${this.#id}-${this.#instanceId}`, reqId);
-      });
+      const { id: reqId, promise } = this[kSharedStatePromiseStore].createPromise();
+      this.#client.transport.emit(`${DETACH_REQUEST}-${this.#id}-${this.#instanceId}`, reqId);
+      return promise;
     }
   }
 

package/src/common/version.js

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

package/src/server/ServerStateManager.js

@@ -19,7 +19,7 @@ import {
   OBSERVE_ERROR,
   OBSERVE_NOTIFICATION,
   UNOBSERVE_NOTIFICATION,
-  DELETE_SHARED_STATE_CLASS,
+  // DELETE_SHARED_STATE_CLASS,
   GET_CLASS_DESCRIPTION_REQUEST,
   GET_CLASS_DESCRIPTION_RESPONSE,
   GET_CLASS_DESCRIPTION_ERROR,
@@ -206,7 +206,7 @@ class ServerStateManager extends BaseStateManager {
     // ---------------------------------------------
     client.transport.addListener(
       CREATE_REQUEST,
-      async (reqId, className, requireDescription, initValues = {}) => {
+      async (reqId, className, initValues = {}) => {
         if (this.#classes.has(className)) {
           try {
             const classDescription = this.#classes.get(className);
@@ -243,7 +243,6 @@ class ServerStateManager extends BaseStateManager {
             this.#sharedStatePrivateById.set(stateId, state);
 
             const currentValues = state.parameters.getValues();
-            const classDescriptionOption = requireDescription ? classDescription : null;
 
             client.transport.emit(
               CREATE_RESPONSE,
@@ -251,7 +250,7 @@ class ServerStateManager extends BaseStateManager {
               stateId,
               instanceId,
               className,
-              classDescriptionOption,
+              classDescription,
               currentValues,
             );
 
@@ -278,7 +277,7 @@ class ServerStateManager extends BaseStateManager {
     // ---------------------------------------------
     client.transport.addListener(
       ATTACH_REQUEST,
-      (reqId, className, stateId = null, requireDescription = true, filter = null) => {
+      (reqId, className, stateId = null, filter = null) => {
         if (this.#classes.has(className)) {
           let state = null;
 
@@ -305,7 +304,6 @@ class ServerStateManager extends BaseStateManager {
             const isOwner = false;
             const currentValues = state.parameters.getValues();
             const classDescription = this.#classes.get(className);
-            const classDescriptionOption = requireDescription ? classDescription : null;
 
             // if filter given, check that all filter entries are valid class keys
             // @todo - improve error reporting: report invalid filters
@@ -327,7 +325,7 @@ class ServerStateManager extends BaseStateManager {
               state.id,
               instanceId,
               className,
-              classDescriptionOption,
+              classDescription,
               currentValues,
               filter,
             );
@@ -525,10 +523,14 @@ class ServerStateManager extends BaseStateManager {
       }
     }
 
-    // clear class cache of all connected clients
-    for (let client of this[kStateManagerClientsByNodeId].values()) {
-      client.transport.emit(`${DELETE_SHARED_STATE_CLASS}`, className);
-    }
+    // ---------------------------------------------
+    // note 2025-05-05: client-side caching of class descriptions has been removed
+    // because it could create concurrency issues
+    // cf. `should be able to recreate a class with the same name` unit test
+    // ---------------------------------------------
+    // for (let client of this[kStateManagerClientsByNodeId].values()) {
+    //   client.transport.emit(`${DELETE_SHARED_STATE_CLASS}`, className);
+    // }
 
     this.#classes.delete(className);
     // delete registered hooks
@@ -545,6 +547,16 @@ class ServerStateManager extends BaseStateManager {
     this.deleteClass(className);
   }
 
+  /**
+   * Check wether a {@link SharedState} is defined or not, given its {@link SharedStateClassName}
+   *
+   * @param {SharedStateClassName} className - Name of the shared state class to delete.
+   * @returns {boolean}
+   */
+  isClassDefined(className) {
+    return this.#classes.has(className);
+  }
+
   /**
    * Register a function for a given class of shared state class to be executed
    * when a state is created.

package/types/client/index.d.ts

@@ -18,7 +18,25 @@ export type ClientAppConfig = {
 /**
  * Environment configuration object.
  */
-export type ClientEnvConfig = objecy;
+export type ClientEnvConfig = {
+    /**
+     * - Port on which the server is listening.
+     */
+    port: number;
+    /**
+     * - Domain name or IP of the server.
+     * Mandatory when node clients are declared
+     */
+    serverAddress: string;
+    /**
+     * - Define is the server run in http or in https.
+     */
+    useHttps: boolean;
+    /**
+     * - If running behind a proxy, base URL of the application.
+     */
+    baseUrl?: string;
+};
 /**
  * Configuration object for a client running in a browser runtime.
  */

package/types/common/BatchedTransport.d.ts

@@ -1,10 +1,6 @@
 export default BatchedTransport;
 /**
- * This class proxies transports given the SharedStateManager to batch messages
- *
- * @param {number} [options.wait=0] - Wait for given number of milliseconds
- *  for stacking messages before emitting on the network. If 0 is given, network
- *  message is emitted on next microtask
+ * This class proxies transports, i.e. WebSockets, to batch message sends
  * @private
  */
 declare class BatchedTransport {

package/types/common/PromiseStore.d.ts

@@ -3,9 +3,13 @@ export default class PromiseStore {
     constructor(name: any);
     name: any;
     store: Map<any, any>;
-    generateRequestId: any;
-    add(resolve: any, reject: any, type: any, localParams: any): any;
-    resolve(reqId: any, data: any): void;
-    reject(reqId: any, msg: any): void;
+    generateId: any;
+    createPromise(): {
+        id: any;
+        promise: any;
+    };
+    associateResolveData(id: any, associatedData: any): void;
+    resolve(id: any, data: any): void;
+    reject(id: any, msg: any): void;
     flush(): void;
 }

package/types/common/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "5.1.2";
+declare const _default: "5.2.1";
 export default _default;

package/types/server/ServerStateManager.d.ts

@@ -130,6 +130,13 @@ declare class ServerStateManager extends BaseStateManager {
      * @deprecated Use {@link ServerStateManager#defineClass} instead.
      */
     deleteSchema(className: any): void;
+    /**
+     * Check wether a {@link SharedState} is defined or not, given its {@link SharedStateClassName}
+     *
+     * @param {SharedStateClassName} className - Name of the shared state class to delete.
+     * @returns {boolean}
+     */
+    isClassDefined(className: SharedStateClassName): boolean;
     /**
      * Register a function for a given class of shared state class to be executed
      * when a state is created.