@soundworks/core 3.0.4 → 3.1.0-beta.3

package/common/SharedState.js

@@ -5,9 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
-var _parameters = _interopRequireDefault(require("@ircam/parameters"));
-
-var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
+var _ParameterBag = _interopRequireDefault(require("./ParameterBag.js"));
 
 var _sharedStateUtils = require("./shared-state-utils.js");
 
@@ -27,18 +25,17 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * @see {server.SharedStateManagerServer}
  */
 class SharedState {
-  constructor(id, remoteId, schemaName, schema, client, isCreator, manager, initValues = {}) {
+  constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
     this.id = id;
     this.remoteId = remoteId;
     this.schemaName = schemaName;
-    this._schema = (0, _lodash.default)(schema);
-    this._isCreator = isCreator; // may be the server or any client
+    this._isOwner = isOwner; // may be the server or any client
 
     this._client = client;
     this._manager = manager;
 
     try {
-      this._parameters = (0, _parameters.default)(schema, initValues);
+      this._parameters = new _ParameterBag.default(schema, initValues);
     } catch (err) {
       console.error(err.stack);
       throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
@@ -49,20 +46,18 @@ ${JSON.stringify(initValues, null, 2)}`);
     this._onDetachCallbacks = new Set();
     this._onDeleteCallbacks = new Set(); // add listener for state updates
 
-    client.transport.addListener(`${_sharedStateUtils.UPDATE_RESPONSE}-${id}-${this.remoteId}`, (reqId, updates) => {
-      const updated = this._commit(updates);
-
+    client.transport.addListener(`${_sharedStateUtils.UPDATE_RESPONSE}-${id}-${this.remoteId}`, async (reqId, updates, context) => {
+      const updated = await this._commit(updates, context, true, true);
       (0, _sharedStateUtils.resolveRequest)(reqId, updated);
     }); // retrieve values but do not propagate to subscriptions
 
-    client.transport.addListener(`${_sharedStateUtils.UPDATE_ABORT}-${id}-${this.remoteId}`, (reqId, updates) => {
-      const updated = this._commit(updates, false);
-
+    client.transport.addListener(`${_sharedStateUtils.UPDATE_ABORT}-${id}-${this.remoteId}`, async (reqId, updates, context) => {
+      const updated = await this._commit(updates, context, false, true);
       (0, _sharedStateUtils.resolveRequest)(reqId, updated);
     });
-    client.transport.addListener(`${_sharedStateUtils.UPDATE_NOTIFICATION}-${id}-${this.remoteId}`, updates => {
+    client.transport.addListener(`${_sharedStateUtils.UPDATE_NOTIFICATION}-${id}-${this.remoteId}`, async (updates, context) => {
       // cf. https://github.com/collective-soundworks/soundworks/issues/18
-      this._commit(updates);
+      await this._commit(updates, context, true, false);
     }); // ---------------------------------------------
     // DELETE initiated by creator, or schema deleted
     // ---------------------------------------------
@@ -79,7 +74,7 @@ ${JSON.stringify(initValues, null, 2)}`);
       this._clearDetach();
     });
 
-    if (this._isCreator) {
+    if (this._isOwner) {
       // ---------------------------------------------
       // DELETE (can only delete if creator)
       // ---------------------------------------------
@@ -124,12 +119,12 @@ ${JSON.stringify(initValues, null, 2)}`);
   _clearDetach() {
     this._onDetachCallbacks.clear();
 
-    this._onDeleteCallbacks.clear(); // Monkey patch detach so it throws we called twice. Doing nothing blocks
-    // the process on a second `detach` call as the Promise was never resolved
+    this._onDeleteCallbacks.clear(); // Monkey patch detach so it throws if called twice. Doing nothing blocks
+    // the process on a second `detach` call as the Promise never resolves
 
 
     this.detach = () => {
-      throw new Error(`State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
+      throw new Error(`[stateManager] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
     };
   }
 
@@ -148,50 +143,141 @@ ${JSON.stringify(initValues, null, 2)}`);
   /** @private */
 
 
-  _commit(obj, propagate = true) {
-    const updated = {};
+  async _commit(updates, context, propagate = true, initiator = false) {
+    const newValues = {};
+    const oldValues = {};
+
+    for (let name in updates) {
+      const {
+        immediate,
+        filterChange,
+        event
+      } = this._parameters.getSchema(name); // @note 20211209 - we have an issue here server-side, because if the value
+      // is an object or an array, the reference is shared by everybody, therefore
+      // `changed` is always false and the new value is never propagated...
+      // FIXED - `state.get` now returns a deep copy when `type` is `any`
+
+
+      const oldValue = this._parameters.get(name);
+
+      const [newValue, changed] = this._parameters.set(name, updates[name]); // handle immediate stuff
+
+
+      if (initiator && immediate) {
+        // @note - we don't need to check filterChange here because the value
+        // has been updated in parameters on the `set` side so can rely on `changed`
+        // to avoid retrigger listeners.
+        // If the value has been overriden by the server, `changed` will true
+        // anyway so it should behave correctly.
+        if (!changed || event) {
+          continue;
+        }
+      }
 
-    for (let name in obj) {
-      updated[name] = this._parameters.set(name, obj[name]);
+      newValues[name] = newValue;
+      oldValues[name] = oldValue;
     } // if the `UPDATE_REQUEST` as been aborted by the server, do not propagate
 
 
-    if (propagate) {
-      this._subscriptions.forEach(listener => listener(updated));
+    let promises = [];
+
+    if (propagate && Object.keys(newValues).length > 0) {
+      this._subscriptions.forEach(listener => {
+        promises.push(listener(newValues, oldValues, context));
+      });
     }
 
-    return updated;
+    await Promise.all(promises);
+    return newValues;
   }
   /**
-   * Get the schema that describes the state.
+   * Updates values of the state. Wait for all subscriptions to be resolved
+   * before resolving itself, i.e.:
    *
-   * @return {Object}
-   */
-
-
-  getSchema() {
-    return this._schema;
-  }
-  /**
-   * Updates values of the state.
+   * ```js
+   * const a = await server.stateManager.create('a');
+   * let asyncCallbackCalled = false;
+   *
+   * a.subscribe(updates => {
+   *   return new Promise(resolve => {
+   *     setTimeout(() => {
+   *       asyncCallbackCalled = true;
+   *       resolve();
+   *     }, 100);
+   *   });
+   * });
+   *
+   * await a.set({ bool: true });
+   * assert.equal(asyncCallbackCalled, true);
+   * ```
    *
    * @async
-   * @param {Object} updates - key / value pairs of updates to apply to the state
-   * @return {Object}
+   * @param {Object} updates - key / value pairs of updates to apply to the state.
+   * @param {Mixed} [context=null] - optionnal context that will be propagated
+   *   alongside the updates of the state. The context is valid only for the
+   *   current call and will be passed as third argument to any subscribe listeners.
+   * @return {Promise<Object>} A promise to the (coerced) updates.
+   *
+   * @see {common.SharedState~subscribeCallback}
    */
 
 
-  async set(updates) {
+  async set(updates, context = null) {
+    // handle immediate option
+    const immediateNewValues = {};
+    const immediateOldValues = {};
+    let propagateNow = false;
+
+    for (let name in updates) {
+      // throw early (client-side and not only server-side) if parameter is undefined
+      if (!this._parameters.has(name)) {
+        throw new ReferenceError(`[stateManager] Cannot set value of undefined parameter "${name}"`);
+      } // @note: general idea...
+      // if immediate=true
+      //  - call listeners if value changed
+      //  - go through normal server path
+      //  - retrigger only if response from server is different from current value
+      // if immediate=true && (filterChange=false || event=true)
+      //  - call listeners with value regarless it changed
+      //  - go through normal server path
+      //  - if the node is initiator of the update (UPDATE_RESPONSE), (re-)check
+      //    to prevent execute the listeners twice
+
+
+      const {
+        immediate,
+        filterChange,
+        event
+      } = this._parameters.getSchema(name);
+
+      if (immediate) {
+        const oldValue = this._parameters.get(name);
+
+        const [newValue, changed] = this._parameters.set(name, updates[name]);
+
+        if (changed || filterChange === false) {
+          immediateOldValues[name] = oldValue;
+          immediateNewValues[name] = newValue;
+          propagateNow = true;
+        }
+      }
+    }
+
+    if (propagateNow) {
+      this._subscriptions.forEach(listener => listener(immediateNewValues, immediateOldValues, context));
+    } // go through server-side normal behavior
+
+
     return new Promise((resolve, reject) => {
       const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
 
-      this._client.transport.emit(`${_sharedStateUtils.UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates);
+      this._client.transport.emit(`${_sharedStateUtils.UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
     });
   }
   /**
    * Get a value of the state by its name
    *
-   * @param {String} name - Name of the param
+   * @param {String} name - Name of the param. Throws an error if the name is invalid.
    * @return {Mixed}
    */
 
@@ -209,29 +295,89 @@ ${JSON.stringify(initValues, null, 2)}`);
   getValues() {
     return this._parameters.getValues();
   }
+  /**
+   * Get the schema that describes the state.
+   *
+   * @param {String} [name=null] - if given, returns only the definition
+   *   of the given param name. Throws an error if the name is invalid.
+   * @return {Object}
+   */
+
+
+  getSchema(name = null) {
+    return this._parameters.getSchema(name);
+  }
+  /**
+   * Get the values with which the state has been initialized.
+   *
+   * @return {Object}
+   */
+
+
+  getInitValues() {
+    return this._parameters.getInitValues();
+  }
+  /**
+   * Get the default values that has been declared in the schema.
+   *
+   * @return {Object}
+   */
+
+
+  getDefaults() {
+    return this._parameters.getDefaults();
+  }
   /**
    * @callback common.SharedState~subscribeCallback
-   * @param {Object} updates - key / value pairs of the updates that have been
-   *   applied to the state
+   * @param {Object} newValues - key / value pairs of the updates that have been
+   *   applied to the state.
+   * @param {Object} oldValues - key / value pairs of the related params before
+   *   the updates has been applied to the state.
+   * @param {Mixed} [context=null] - Optionnal context data that has been passed
+   *   with the updates in the `set` call.
+   *
+   * @example
+   * state.subscribe(async (newValues, oldValues[, context=null]) =>  {
+   *   for (let [key, value] of Object.entries(newValues)) {
+   *      switch (key) {
+   *        // do something
+   *      }
+   *   }
+   * });
+   *
+   * @see {common.SharedState#set}
+   * @see {common.SharedState#subscribe}
    */
 
   /**
    * Subscribe to state updates
    *
    * @param {common.SharedState~subscribeCallback} callback - callback to execute
-   *   when an update is commited on the state.
+   *   when an update is applied on the state.
+   * @param {Boolean} [executeListener=false] - execute the given listener with
+   *   current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
+   *
    * @example
-   * state.subscribe(async (updates) =>  {
-   *   for (let [key, value] of Object.entries(updates)) {
-   *      // dispatch
+   * state.subscribe(async (newValues, oldValues) =>  {
+   *   for (let [key, value] of Object.entries(newValues)) {
+   *      switch (key) {
+   *        // do something
+   *      }
    *   }
-   * }
+   * });
    */
 
 
-  subscribe(listener) {
+  subscribe(listener, executeListener = false) {
     this._subscriptions.add(listener);
 
+    if (executeListener === true) {
+      const currentValues = this.getValues();
+      const oldValues = {};
+      const context = null;
+      listener(currentValues, oldValues, context);
+    }
+
     return () => {
       this._subscriptions.delete(listener);
     };
@@ -253,7 +399,7 @@ ${JSON.stringify(initValues, null, 2)}`);
   async detach() {
     this._subscriptions.clear();
 
-    if (this._isCreator) {
+    if (this._isOwner) {
       return new Promise((resolve, reject) => {
         const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
 
@@ -267,6 +413,28 @@ ${JSON.stringify(initValues, null, 2)}`);
       });
     }
   }
+  /**
+   * Delete the state. Only the creator/owner of the state (i.e. a state created using
+   * `create`) can use this method. If a non-owner call this method (i.e. a
+   * state created using `attach`), an error will be thrown.
+   *
+   * @async
+   * @see {common.SharedState#onDetach}
+   * @see {common.SharedState#onDelete}
+   * @see {client.SharedStateManagerClient#create}
+   * @see {server.SharedStateManagerClient#create}
+   * @see {client.SharedStateManagerClient#attach}
+   * @see {server.SharedStateManagerClient#attach}
+   */
+
+
+  async delete() {
+    if (this._isOwner) {
+      return this.detach();
+    } else {
+      throw new Error(`[stateManager] can delete state "${this.schemaName}", only owner of the state (i.e. the node that "create[d]" it) can delete it`);
+    }
+  }
   /**
    * Register a function to execute when detaching from the state
    *

package/common/SharedStateManagerClient.js

@@ -15,7 +15,7 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * Component dedicated at managing distributed states, accessible through {@link common.SharedState} instances, among the application.
  *
  * An instance of `SharedStateManagerClient` is automatically created by the
- * `soundworks.Client` (cf. {@link client.Client#stateManager}).
+ * `soundworks.Client` at initialization (cf. {@link client.Client#stateManager}).
  *
  * Tutorial: [https://collective-soundworks.github.io/tutorials/state-manager.html](https://collective-soundworks.github.io/tutorials/state-manager.html)
  *
@@ -99,6 +99,12 @@ class SharedStateManagerClient {
       list.forEach(([schemaName, stateId, nodeId]) => {
         this._observeListeners.forEach(callback => callback(schemaName, stateId, nodeId));
       });
+    }); // ---------------------------------------------
+    // Clear cache when schema is deleted
+    // ---------------------------------------------
+
+    this.client.transport.addListener(_sharedStateUtils.DELETE_SCHEMA, schemaName => {
+      this._cachedSchemas.delete(schemaName);
     });
   }
   /**

package/common/SharedStateManagerServer.js

@@ -7,7 +7,7 @@ exports.default = void 0;
 
 var _events = _interopRequireDefault(require("events"));
 
-var _parameters = _interopRequireDefault(require("@ircam/parameters"));
+var _ParameterBag = _interopRequireDefault(require("./ParameterBag.js"));
 
 var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
 
@@ -26,8 +26,8 @@ const generateRemoteId = (0, _sharedStateUtils.idGenerator)();
  * The `SharedStateManagerServer` extends the `SharedStateManagerClient` with
  * additionnal functionnalities to register schemas and handle clients.
  *
- * An instance of `SharedStateManagerClient` is automatically created by the
- * `soundworks.Server` (cf. {@link server.Server#stateManager}).
+ * An instance of `SharedStateManagerServer` is automatically created by the
+ * `soundworks.Server` at initialization (cf. {@link server.Server#stateManager}).
  *
  * Tutorial: [https://collective-soundworks.github.io/tutorials/state-manager.html](https://collective-soundworks.github.io/tutorials/state-manager.html)
  *
@@ -49,6 +49,8 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
     this._serverStatesById = new Map();
     this._schemas = new Map();
     this._observers = new Set();
+    this._hooksBySchemaName = new Map(); // protected
+
     this.addClient(localClientId, localTransport);
   }
   /**
@@ -222,38 +224,56 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
     this._clientByNodeId.delete(nodeId);
   }
   /**
-   * Register a schema. The schema definition follows the convention described
-   * here [https://github.com/ircam-jstools/parameters#booleandefinition--object](https://github.com/ircam-jstools/parameters#booleandefinition--object) (@todo - document somewhere else).
+   * Register a schema from which shared states (cf. {@link common.SharedState})
+   * can be instanciated.
    *
    * @param {String} schemaName - Name of the schema.
-   * @param {Object} schema - Description of the state data structure.
+   * @param {server.SharedStateManagerServer~schema} schema - Data structure
+   *  describing the states that will be created from this schema.
+   *
+   * @see {@link server.SharedStateManagerServer#create}
+   * @see {@link client.SharedStateManagerClient#create}
+   *
+   * @example
+   * server.stateManager.registerSchema('my-schema', {
+   *   myBoolean: {
+   *     type: 'boolean'
+   *     default: false,
+   *   },
+   *   myFloat: {
+   *     type: 'float'
+   *     default: 0.1,
+   *     min: -1,
+   *     max: 1
+   *   }
+   * })
    */
 
 
   registerSchema(schemaName, schema) {
     if (this._schemas.has(schemaName)) {
-      throw new Error(`schema "${schemaName}" already registered`);
-    } // throw is schema is invalid
+      throw new Error(`[stateManager.registerSchema] cannot register schema with name: "${schemaName}", schema name already exists`);
+    }
 
+    _ParameterBag.default.validateSchema(schema);
+
+    this._schemas.set(schemaName, (0, _lodash.default)(schema)); // create hooks list
 
-    try {
-      (0, _parameters.default)(schema, {});
-    } catch (err) {
-      throw new Error(`Invalid schema "${schemaName}": ${err.message}`);
-    }
 
-    this._schemas.set(schemaName, (0, _lodash.default)(schema));
+    this._hooksBySchemaName.set(schemaName, new Set());
   }
   /**
    * Delete a schema and all associated states.
-   * When a schema is deleted, all attached clients are detached
-   * and the `onDetach` and `onDelete` callbacks are called.
+   * When a schema is deleted, all states created from this schema are deleted
+   * as well, therefore all attached clients are detached and the `onDetach`
+   * and `onDelete` callbacks are called on the related states.
    *
    * @param {String} schemaName - Name of the schema.
    */
 
 
   deleteSchema(schemaName) {
+    // @note: deleting schema
     for (let [id, state] of this._serverStatesById.entries()) {
       if (state.schemaName === schemaName) {
         for (let [remoteId, attached] of state._attachedClients.entries()) {
@@ -264,9 +284,72 @@ class SharedStateManagerServer extends _SharedStateManagerClient.default {
 
         this._serverStatesById.delete(this.id);
       }
+    } // clear schema cache of all connected clients
+
+
+    for (let client of this._clientByNodeId.values()) {
+      client.transport.emit(`${_sharedStateUtils.DELETE_SCHEMA}`, schemaName);
     }
 
-    this._schemas.delete(schemaName);
+    this._schemas.delete(schemaName); // delete registered hooks
+
+
+    this._hooksBySchemaName.delete(schemaName);
+  }
+  /**
+   * @callback server.SharedStateManagerServer~updateHook
+   *
+   * @param {Object} updates - Update object as given on a set callback, or
+   *  result of the previous hook
+   * @param {Object} currentValues - Current values of the state.
+   * @param {Object} [context=null] - Optionnal context passed by the creator
+   *  of the update.
+   * @return {Object} The "real" updates to be applied on the state.
+   */
+
+  /**
+   * Register a function for a given schema (e.g. will be applied on all states
+   * created from this schema) that will be executed before the update values
+   * are propagated. For example, this could be used to implement a preset system
+   * where all the values of the state are updated from e.g. some data stored in
+   * filesystem while the consumer of the state only want to update the preset name.
+   *
+   * The hook is associated to every state of its kind (i.e. schemaName) and
+   * executed on every update (call of `set`). Note that the hooks are executed
+   * server-side regarless the node on which `set` has been called and before
+   * the "actual" update of the state (e.g. before the call of `subscribe`).
+   *
+   * @example
+   * server.stateManager.registerSchema('hooked', schema);
+   * server.stateManager.registerUpdateHook('hooked', (updates, currentValues) => {
+   *   return {
+   *     ...updates
+   *     numUpdates: currentValues.numUpdates + 1,
+   *   };
+   * });
+   *
+   * const state = await server.stateManager.create('hooked');
+   *
+   * await state.set({ name: 'test' });
+   * state.getValues();
+   * // > { name: 'test', numUpdates: 1 };
+   *
+   * @param {String} schemaName - Kind of states on which applying the hook.
+   * @param {server.SharedStateManagerServer~updateHook} updateHook - Function
+   *   called between the `set` call and the actual update.
+   */
+
+
+  registerUpdateHook(schemaName, updateHook) {
+    // throw error if schemaName has not been registered
+    if (!this._schemas.has(schemaName)) {
+      throw new Error(`[stateManager.registerUpdateHook] cannot register update hook for schema name "${schemaName}", schema name does not exists`);
+    }
+
+    const hooks = this._hooksBySchemaName.get(schemaName);
+
+    hooks.add(updateHook);
+    return () => hooks.delete(updateHook);
   }
 
 }