@soundworks/core 5.2.0 → 5.3.0

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.2.0",
+  "version": "5.3.0",
   "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/Client.js

@@ -314,6 +314,10 @@ class Client {
    * await client.start();
    */
   async init() {
+    if (this.#status === 'inited') {
+      throw new DOMException(`Cannot execute 'init' twice on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'idle') {
       throw new DOMException(`Cannot execute 'init' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -391,6 +395,10 @@ class Client {
       await this.init();
     }
 
+    if (this.#status === 'started') {
+      throw new DOMException(`Cannot execute 'start' twice on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'inited') {
       throw new DOMException(`Cannot execute 'start' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -416,6 +424,10 @@ class Client {
    * await client.stop();
    */
   async stop() {
+    if (this.#status === 'stopped') {
+      throw new DOMException(`Cannot execute 'stop' twice on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'started') {
       throw new DOMException(`Cannot execute 'stop' on Client: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }

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

@@ -244,10 +244,10 @@ class BaseStateManager {
       throw new DOMException(`Cannot execute 'getClassDescription' on BaseStateManager: BaseStateManager is not inited`, 'InvalidStateError');
     }
 
-    return new Promise((resolve, reject) => {
-      const reqId = this.#promiseStore.add(resolve, reject, 'BaseStateManager#getClassDescription');
-      this[kStateManagerClient].transport.emit(GET_CLASS_DESCRIPTION_REQUEST, reqId, className);
-    });
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    this[kStateManagerClient].transport.emit(GET_CLASS_DESCRIPTION_REQUEST, reqId, className);
+
+    return promise;
   }
 
   /**
@@ -272,10 +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');
-      this[kStateManagerClient].transport.emit(CREATE_REQUEST, reqId, className, initValues);
-    });
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    this[kStateManagerClient].transport.emit(CREATE_REQUEST, reqId, className, initValues);
+
+    return promise;
   }
 
   /**
@@ -380,10 +380,10 @@ class BaseStateManager {
       }
     }
 
-    return new Promise((resolve, reject) => {
-      const reqId = this.#promiseStore.add(resolve, reject, 'BaseStateManager#attach');
-      this[kStateManagerClient].transport.emit(ATTACH_REQUEST, reqId, className, stateId, filter);
-    });
+    const { id: reqId, promise } = this.#promiseStore.createPromise();
+    this[kStateManagerClient].transport.emit(ATTACH_REQUEST, reqId, className, stateId, filter);
+
+    return promise;
   }
 
   /**
@@ -562,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/ParameterBag.js

@@ -12,6 +12,7 @@ export const sharedOptions = {
   metas: {},
   filterChange: true,
   immediate: false,
+  acknowledge: true,
 };
 
 export const types = {

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

@@ -465,31 +465,31 @@ class SharedState {
 
     const newValues = {};
     const oldValues = {};
-    const localParams = {};
-    const sharedParams = {};
+    const locallyResolvedParam = {};
+    const networkPropagatedParams = {};
     let hasLocalParam = false;
-    let hasSharedParam = false;
-    let forwardParams = undefined;
-    let propagateNow = false;
+    let hasRegularSharedParam = false;
+    let hasNonAcknowledgedParams = false;
+    let syncedOnUpdate = false;
 
     for (let name in updates) {
-      // Try to coerce value early, so that eventual errors are triggered early
-      // on the node requesting the update, and not only on the server side
-      // This throws if name does not exists
+      // Try to coerce value now, so that eventual errors are triggered early
+      // on the node requesting the update and not only on the server side.
       try {
+        // This also throws if name does not exists
         this.#parameters.coerceValue(name, updates[name]);
       } catch (err) {
         throw new TypeError(`Cannot execute 'set' on SharedState (${this.#className}): ${err.message}`);
       }
 
-      // Check that name is in filter list, if any
+      // Make sure that given name is in filter white list (if any)
       if (this.#filter !== null) {
         if (!this.#filter.includes(name)) {
           throw new DOMException(`Cannot execute 'set' on SharedState (${this.#className}): Parameter '${name}' is not in white list`, 'NotSupportedError');
         }
       }
 
-      // `immediate` option behavior
+      // ### `immediate` modifier behavior
       //
       // If immediate=true
       //  - call listeners if value changed
@@ -501,7 +501,7 @@ class SharedState {
       //  - if the node is initiator of the update (UPDATE_RESPONSE), (re-)check
       //    to prevent execute the listeners twice
 
-      // `local` option behavior
+      // ### `local` modifier behavior
       //
       // - If the `updates` object only contains local variables, we can call the
       // update listeners and return a fulfilled promise immediately
@@ -510,9 +510,19 @@ class SharedState {
       // response, call update listeners with server response and resolve promise with
       // the full payload, i.e. reintegrating the local params in the resolve payload
 
-      const { local, immediate, filterChange, event } = this.#parameters.getDescription(name);
+      // ### `acknowledge` modifier behavior
+      //
+      // Same as immediate, but no feedback from server
+
+      const {
+        local,
+        immediate,
+        filterChange,
+        event,
+        acknowledge,
+      } = this.#parameters.getDescription(name);
 
-      if (immediate || local) {
+      if (immediate || local || acknowledge === false) {
         const oldValue = this.#parameters.get(name);
         const [newValue, changed] = this.#parameters.set(name, updates[name]);
 
@@ -520,45 +530,52 @@ class SharedState {
         if (changed || filterChange === false || event) {
           oldValues[name] = oldValue;
           newValues[name] = newValue;
-          propagateNow = true;
+          syncedOnUpdate = true;
         }
       }
 
-      // define params that must go through network or not
       if (local) {
+        // these don't go to the network
         hasLocalParam = true;
-        // get sanitize value for fulfilling promise
-        localParams[name] = this.#parameters.get(name);
+        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
+        hasNonAcknowledgedParams = true;
+        locallyResolvedParam[name] = this.#parameters.get(name);
+        networkPropagatedParams[name] = updates[name];
       } else {
-        // note that immediate are shared params too
-        hasSharedParam = true;
-        sharedParams[name] = updates[name];
+        // note that immediate params are shared and acknowledged
+        hasRegularSharedParam = true;
+        networkPropagatedParams[name] = updates[name];
       }
     }
 
-    // propagate immediate params if changed
-    if (propagateNow) {
+    // params that trigger a synced onUpdate call: immediate, local, non-acknowledged
+    if (syncedOnUpdate) {
       this.#onUpdateCallbacks.forEach(listener => listener(newValues, oldValues));
     }
 
-    // check if we can resolve immediately or if we need to go through network
-    if (hasLocalParam) {
-      if (!hasSharedParam) {
-        return Promise.resolve(localParams);
-      } else {
-        // store local params to fulfill promise with all values, see PromiseStore
-        forwardParams = localParams;
-      }
+    // if we only have local params, we can resolve immediately
+    if (hasLocalParam && !hasNonAcknowledgedParams && !hasRegularSharedParam) {
+      return Promise.resolve(locallyResolvedParam);
     }
 
-    // override updates to be shared on network without local params
-    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();
+    // store local params that should be re-merged w/ regular ones
+    if (Object.keys(locallyResolvedParam).length > 0) {
+      this[kSharedStatePromiseStore].associateResolveData(reqId, locallyResolvedParam);
+    }
+
+    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) {
+      this[kSharedStatePromiseStore].resolve(reqId, {});
+    }
+
+    return promise;
   }
 
   /**
@@ -710,15 +727,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;
     }
   }
 
@@ -745,7 +760,7 @@ class SharedState {
 
       return this.detach();
     } else {
-      throw new DOMException(`Cannot execute 'delete' on SharedState (${this.#className}): SharedState (${this.#id}) is not owned by this node. Use 'SharedState#detach' instead`, 'NotSupportedError');
+      throw new DOMException(`Cannot execute 'delete' on SharedState (${this.#className}): This instance is attached and not owned. Use 'SharedState#detach' instead`, 'NotSupportedError');
     }
   }
 
@@ -813,6 +828,10 @@ class SharedState {
    * @param {Function} callback - Callback to execute when the state is deleted.
    */
   onDelete(callback) {
+    if (!this.#isOwner) {
+      throw new DOMException(`Cannot execute 'onDelete' on SharedState (${this.#className}): This instance is attached and not owned. Use 'SharedState#onDetach' instead`, 'NotSupportedError');
+    }
+
     this.#onDeleteCallbacks.add(callback);
     return () => this.#onDeleteCallbacks.delete(callback);
   }

package/src/common/shared-state-types.js

@@ -52,25 +52,33 @@
  * @property {boolean} [event=false] - Define if the parameter is a volatile, i.e.
  *   its value only exists on an update and is set back to `null` after propagation.
  *   When `true`, `nullable` is automatically set to `true` and `default` to `null`.
+ * @property {boolean} [required=false] - When set to true, the parameter must be
+ *   provided at the creation of the shared state.
  * @property {boolean} [filterChange=true] - When set to `false`, an update will
  *   trigger the propagation of a parameter even when its value didn't change.
- *   This option provides a sort of middle ground between the default behavior
+ *   This modifier provides a sort of middle ground between the default behavior
  *   (e.g. where only changed values are propagated) and the behavior of the `event`
  *   option (which has no state per se). Hence, setting this options to `false` if
  *   `event=true` makes no sens.
  * @property {boolean} [immediate=false] - When set to `true`, an update will
  *   trigger the update listeners immediately on the node that generated the update,
- *   before propagating the change on the network.
- *   This option is useful in cases the network would introduce a noticeable
- *   latency on the client.
+ *   before propagating the change on the network. This modifier is useful in cases
+ *   the network would introduce a noticeable latency on the client.
  *   If for some reason the value is overridden server-side (e.g. in an `updateHook`)
  *   the listeners will be called again when the "real" value is received.
- * @property {boolean} [required=false] - When set to true, the parameter must be
- *   provided in the initialization values when the state is created.
+ *   Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+ *   according to the `set` call.
  * @property {boolean} [local=false] - When set to true, the parameter is never
  *   propagated on the network (hence it is no longer a shared parameter :). This
  *   is useful to declare some common parameter (e.g. some interface state) that
  *   don't need to be shared but to stay in the shared state API paradigm.
+ *   Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+ *   according to the `set` call.
+ * @property {boolean} [acknowledge=true] - When set to false, the acknowledgement
+ *   is never sent back to the shared state that initiated an update. This can be
+ *   useful to e.g. stream values to the network, but can lead to invalid state.
+ *   Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+ *   according to the `set` call.
  * @property {number} [min=-Number.MIN_VALUE] - Minimum value of the parameter. Only applies
  *   for `integer` and `float` types.
  * @property {number} [max=Number.MAX_VALUE] - Maximum value of the parameter. Only applies

package/src/common/version.js

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

package/src/server/Server.js

@@ -482,6 +482,10 @@ class Server {
    * await server.start(); // init is called implicitly
    */
   async init() {
+    if (this.#status === 'inited') {
+      throw new DOMException(`Cannot execute 'init' twice on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'idle') {
       throw new DOMException(`Cannot execute 'init' on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -547,6 +551,10 @@ class Server {
       await this.init();
     }
 
+    if (this.#status === 'started') {
+      throw new DOMException(`Cannot execute 'start' twice on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'inited') {
       throw new DOMException(`Cannot execute 'start' on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }
@@ -601,6 +609,10 @@ class Server {
    * await server.stop();
    */
   async stop() {
+    if (this.#status === 'stopped') {
+      throw new DOMException(`Cannot execute 'stop' twice on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
+    }
+
     if (this.#status !== 'started') {
       throw new DOMException(`Cannot execute 'stop' on Server: Lifecycle methods must be called in following order: init, start, stop`, 'InvalidAccessError');
     }

package/src/server/SharedStatePrivate.js

@@ -16,18 +16,18 @@ import {
 } from '../server/ServerStateManager.js';
 
 /**
- * Filter update object according to filter list.
+ * Filter update object according to a given white list.
  * Return identity is filter is null
  * @param {object} updates
- * @param {array|null} filter
+ * @param {array|null} whiteList
  * @private
  */
-function filterUpdates(updates, filter) {
-  if (filter === null) {
+function whiteListFilterUpdates(updates, whiteList) {
+  if (whiteList === null) {
     return updates;
   }
 
-  return filter.reduce((acc, key) => {
+  return whiteList.reduce((acc, key) => {
     if (key in updates) {
       acc[key] = updates[key];
     }
@@ -35,6 +35,29 @@ function filterUpdates(updates, filter) {
   }, {});
 }
 
+/**
+ * Filter update object according to a given black list.
+ * Return identity is filter is null
+ * @param {object} updates
+ * @param {array|null} filter
+ * @private
+ */
+function blackListFilterUpdates(updates, blackList) {
+  if (blackList === null) {
+    return updates;
+  }
+  // create a shallow copy so we can have multiple filters applied on same source
+  const filtered = Object.assign({}, updates);
+
+  blackList.forEach(key => {
+    if (key in updates) {
+      delete filtered[key];
+    }
+  });
+
+  return filtered;
+}
+
 export const kSharedStatePrivateAttachClient = Symbol('soundworks:shared-state-private-attach-client');
 export const kSharedStatePrivateDetachClient = Symbol('soundworks:shared-state-private-detach-client');
 export const kSharedStatePrivateGetValues = Symbol('soundworks:shared-state-private-get-values');
@@ -122,13 +145,13 @@ class SharedStatePrivate {
 
       if (hookAborted === false) {
         let acknowledgedUpdates = {};
-        let hasUpdates = false;
+        let acknowledgeFilter = [];
 
         for (let name in updates) {
           const [newValue, changed] = this.#parameters.set(name, updates[name]);
           // if `filterChange` is set to `false` we don't check if the value
           // has been changed or not, it is always propagated to client states
-          const { event, filterChange } = this.#parameters.getDescription(name);
+          const { event, filterChange, acknowledge } = this.#parameters.getDescription(name);
 
           // if event type reset internal value to null
           if (event) {
@@ -137,11 +160,14 @@ class SharedStatePrivate {
 
           if ((filterChange && changed) || !filterChange) {
             acknowledgedUpdates[name] = newValue;
-            hasUpdates = true;
+
+            if (acknowledge === false) {
+              acknowledgeFilter.push(name);
+            }
           }
         }
 
-        if (hasUpdates) {
+        if (Object.keys(acknowledgedUpdates).length > 0) {
           // Normal case
           //
           // We need to handle cases where:
@@ -161,25 +187,29 @@ class SharedStatePrivate {
           //
           // @note - instanceId correspond to unique remote state id
 
+          // - Apply acknowledge filter on `acknowledgedUpdates`
+          // - We don't need to apply the regular filter on update request, they are blocked client-side
+          const requesterFilteredUpdates = blackListFilterUpdates(acknowledgedUpdates, acknowledgeFilter);
+
           // propagate RESPONSE to the client that originates the request if not the server
           if (client.id !== -1) {
-            // no need to filter updates on requested, is blocked on client-side
-            client.transport.emit(
-              `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
-              reqId,
-              acknowledgedUpdates,
-            );
+            // propagate only if there something left after applying the acknowledge filter
+            if (Object.keys(requesterFilteredUpdates).length > 0) {
+              client.transport.emit(
+                `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
+                reqId,
+                requesterFilteredUpdates,
+              );
+            };
           }
 
-          // propagate NOTIFICATION to all attached clients except server
+          // propagate NOTIFICATION to all peer states except on server-side
           for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
-            const peer = clientInfos.client;
+            const { client: peer, filter } = clientInfos;
 
             if (instanceId !== peerInstanceId && peer.id !== -1) {
-              const filter = clientInfos.filter;
-              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
-
-              // propagate only if there something left after applying the filter
+              const filteredUpdates = whiteListFilterUpdates(acknowledgedUpdates, filter);
+              // propagate only if there something left after applying the white list filter
               if (Object.keys(filteredUpdates).length > 0) {
                 peer.transport.emit(
                   `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
@@ -191,22 +221,23 @@ class SharedStatePrivate {
 
           // propagate RESPONSE to server if it is the requester
           if (client.id === -1) {
-            // no need to filter updates on requested, is blocked on client-side
-            client.transport.emit(
-              `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
-              reqId,
-              acknowledgedUpdates,
-            );
+            // propagate only if there something left after applying the acknowledge filter
+            if (Object.keys(requesterFilteredUpdates).length > 0) {
+              client.transport.emit(
+                `${UPDATE_RESPONSE}-${this.id}-${instanceId}`,
+                reqId,
+                requesterFilteredUpdates,
+              );
+            }
           }
 
-          // propagate NOTIFICATION to other state attached on the server
+          // propagate NOTIFICATION to all peer states on the server-side
           for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
-            const peer = clientInfos.client;
+            const { client: peer, filter } = clientInfos;
 
             if (instanceId !== peerInstanceId && peer.id === -1) {
-              const filter = clientInfos.filter;
-              const filteredUpdates = filterUpdates(acknowledgedUpdates, filter);
-
+              const filteredUpdates = whiteListFilterUpdates(acknowledgedUpdates, filter);
+              // propagate only if there something left after applying the white list filter
               if (Object.keys(filteredUpdates).length > 0) {
                 peer.transport.emit(
                   `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
@@ -216,8 +247,7 @@ class SharedStatePrivate {
             }
           }
         } else {
-          // propagate back to the requester that the update has been aborted
-          // ignore all other attached clients.
+          // propagate back to the requester that the update has been aborted, ignore all peers
           client.transport.emit(`${UPDATE_ABORT}-${this.id}-${instanceId}`, reqId, updates);
         }
       } else {

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/ParameterBag.d.ts

@@ -5,6 +5,7 @@ export namespace sharedOptions {
     let metas: {};
     let filterChange: boolean;
     let immediate: boolean;
+    let acknowledge: boolean;
 }
 export namespace types {
     export namespace boolean {

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/shared-state-types.d.ts

@@ -42,10 +42,15 @@ type SharedStateParameterDescription = {
      * When `true`, `nullable` is automatically set to `true` and `default` to `null`.
      */
     event?: boolean;
+    /**
+     * - When set to true, the parameter must be
+     * provided at the creation of the shared state.
+     */
+    required?: boolean;
     /**
      * - When set to `false`, an update will
      * trigger the propagation of a parameter even when its value didn't change.
-     * This option provides a sort of middle ground between the default behavior
+     * This modifier provides a sort of middle ground between the default behavior
      * (e.g. where only changed values are propagated) and the behavior of the `event`
      * option (which has no state per se). Hence, setting this options to `false` if
      * `event=true` makes no sens.
@@ -54,25 +59,31 @@ type SharedStateParameterDescription = {
     /**
      * - When set to `true`, an update will
      * trigger the update listeners immediately on the node that generated the update,
-     * before propagating the change on the network.
-     * This option is useful in cases the network would introduce a noticeable
-     * latency on the client.
+     * before propagating the change on the network. This modifier is useful in cases
+     * the network would introduce a noticeable latency on the client.
      * If for some reason the value is overridden server-side (e.g. in an `updateHook`)
      * the listeners will be called again when the "real" value is received.
+     * Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+     * according to the `set` call.
      */
     immediate?: boolean;
-    /**
-     * - When set to true, the parameter must be
-     * provided in the initialization values when the state is created.
-     */
-    required?: boolean;
     /**
      * - When set to true, the parameter is never
      * propagated on the network (hence it is no longer a shared parameter :). This
      * is useful to declare some common parameter (e.g. some interface state) that
      * don't need to be shared but to stay in the shared state API paradigm.
+     * Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+     * according to the `set` call.
      */
     local?: boolean;
+    /**
+     * - When set to false, the acknowledgement
+     * is never sent back to the shared state that initiated an update. This can be
+     * useful to e.g. stream values to the network, but can lead to invalid state.
+     * Setting this modifier to `true` will trigger the `onUpdate` callback synchronously
+     * according to the `set` call.
+     */
+    acknowledge?: boolean;
     /**
      * - Minimum value of the parameter. Only applies
      * for `integer` and `float` types.

package/types/common/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "5.2.0";
+declare const _default: "5.3.0";
 export default _default;