@soundworks/core 4.0.0-alpha.1 → 4.0.0-alpha.11

package/src/common/BaseSharedState.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from '@ircam/sc-utils';
 import ParameterBag from './ParameterBag.js';
 import {
   DELETE_REQUEST,
@@ -20,10 +21,12 @@ import {
 
 class BaseSharedState {
   constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
-    this.id = id;
-    this.remoteId = remoteId;
-    this.schemaName = schemaName;
-
+    /** @private */
+    this._id = id;
+    /** @private */
+    this._remoteId = remoteId;
+    /** @private */
+    this._schemaName = schemaName;
     /** @private */
     this._isOwner = isOwner; // may be the server or any client
     /** @private */
@@ -31,10 +34,12 @@ class BaseSharedState {
     /** @private */
     this._manager = manager;
 
+    this._detached = false;
+
     try {
       /** @private */
       this._parameters = new ParameterBag(schema, initValues);
-    } catch(err) {
+    } catch (err) {
       console.error(err.stack);
 
       throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
@@ -87,14 +92,25 @@ ${JSON.stringify(initValues, null, 2)}`);
     });
 
     // ---------------------------------------------
-    // DELETE initiated by creator, or schema deleted
+    // state has been deleted by its creator or the schema has been deleted
     // ---------------------------------------------
-    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, () => {
+    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, async () => {
       this._manager._statesById.delete(this.id);
       this._clearTransport();
 
-      this._onDetachCallbacks.forEach(callback => callback());
-      this._onDeleteCallbacks.forEach(callback => callback());
+      for (let callback of this._onDetachCallbacks) {
+        try {
+          await callback();
+        } catch(err) {
+          console.error(err.message);
+        }
+      }
+
+      if (this._isOwner) {
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
+      }
 
       this._clearDetach();
     });
@@ -102,14 +118,19 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     if (this._isOwner) {
       // ---------------------------------------------
-      // DELETE (can only delete if creator)
+      // the creator has called `.delete()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
+      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
         this._manager._statesById.delete(this.id);
         this._clearTransport();
 
-        this._onDetachCallbacks.forEach(callback => callback());
-        this._onDeleteCallbacks.forEach(callback => callback());
+        for (let callback of this._onDetachCallbacks) {
+          await callback();
+        }
+
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
 
         this._clearDetach();
         resolveRequest(reqId, this);
@@ -121,13 +142,15 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     } else {
       // ---------------------------------------------
-      // DETACH
+      // the attached node has called `.detach()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
+      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
         this._manager._statesById.delete(this.id);
         this._clearTransport();
 
-        this._onDetachCallbacks.forEach(func => func());
+        for (let callback of this._onDetachCallbacks) {
+          await callback();
+        }
 
         this._clearDetach();
         resolveRequest(reqId, this);
@@ -137,20 +160,51 @@ ${JSON.stringify(initValues, null, 2)}`);
       this._client.transport.addListener(`${DETACH_ERROR}-${this.id}`, (reqId, msg) => {
         rejectRequest(reqId, msg);
       });
-
     }
   }
 
+  /**
+   * Id of the state
+   * @type {Number}
+   * @readonly
+   */
+  get id() {
+    return this._id;
+  }
+
+  /**
+   * Unique id of the state for the current node
+   * @readonly
+   * @type {Number}
+   * @private
+   */
+  get remoteId() {
+    return this._remoteId;
+  }
+
+  /**
+   * Name of the schema
+   * @type {String}
+   * @readonly
+   */
+  get schemaName() {
+    return this._schemaName;
+  }
+
+  /**
+   * Indicates if the node is the owner of the state
+   * @type {Boolean}
+   * @readonly
+   */
+  get isOwner() {
+    return this._isOwner;
+  }
+
   /** @private */
   _clearDetach() {
     this._onDetachCallbacks.clear();
     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(`[stateManager] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
-    };
+    this._detached = true;
   }
 
   /** @private */
@@ -255,16 +309,23 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
+    if (!isPlainObject(updates)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+    }
+
+    if (context !== null && !isPlainObject(context)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
+    }
+
     // 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}"`);
-      }
+      // try to coerce value early, so that eventual errors are triggered early
+      // on the node requesting the update
+      const _ = this._parameters.coerceValue(name, updates[name]);
 
       // @note: general idea...
       // if immediate=true
@@ -303,21 +364,41 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Get the value of a paramter of the state.
+   * Get the value of a parameter of the state. If the parameter is of `any` type,
+   * a deep copy is returned.
    *
    * @param {string} name - Name of the param.
    * @throws Throws if `name` does not correspond to an existing field
    *  of the state.
    * @return {mixed}
    * @example
-   * const value = state.get('name');
+   * const value = state.get('paramName');
    */
   get(name) {
     return this._parameters.get(name);
   }
 
   /**
-   * Get all the key / value pairs of the state.
+   * Similar to `get` but returns a reference to the underlying value in case of
+   * `any` type. May be usefull if the underlying value is big (e.g. sensors
+   * recordings, etc.) and deep cloning expensive. Be aware that if changes are
+   * made on the returned object, the state of your application will become
+   * inconsistent.
+   *
+   * @param {string} name - Name of the param.
+   * @throws Throws if `name` does not correspond to an existing field
+   *  of the state.
+   * @return {mixed}
+   * @example
+   * const value = state.getUnsafe('paramName');
+   */
+  getUnsafe(name) {
+    return this._parameters.getUnsafe(name);
+  }
+
+  /**
+   * Get all the key / value pairs of the state. If a parameter is of `any`
+   * type, a deep copy is made.
    *
    * @return {object}
    * @example
@@ -327,6 +408,23 @@ ${JSON.stringify(initValues, null, 2)}`);
     return this._parameters.getValues();
   }
 
+  /**
+   * Get all the key / value pairs of the state. If a parameter is of `any`
+   * type, a deep copy is made.
+   * Similar to `getValues` but returns a reference to the underlying value in
+   * case of `any` type. May be usefull if the underlying value is big (e.g.
+   * sensors recordings, etc.) and deep cloning expensive. Be aware that if
+   * changes are made on the returned object, the state of your application will
+   * become inconsistent.
+   *
+   * @return {object}
+   * @example
+   * const values = state.getValues();
+   */
+  getValuesUnsafe() {
+    return this._parameters.getValuesUnsafe();
+  }
+
   /**
    * Get the schema from which the state has been created.
    *
@@ -367,7 +465,7 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Detach from the state. If the client is the creator of the state, the state
-   * is deleted and all attached nodes get notified
+   * is deleted and all attached nodes get notified.
    *
    * @example
    * const state = await client.state.attach('globals');
@@ -375,6 +473,10 @@ ${JSON.stringify(initValues, null, 2)}`);
    * await state.detach();
    */
   async detach() {
+    if (this._detached) {
+      throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
+    }
+
     this._onUpdateCallbacks.clear();
 
     if (this._isOwner) {
@@ -392,9 +494,11 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Delete the state. Only the creator/owner of the state can use this method.
-   * All nodes attached to the state will be deteched, triggering the `onDetach`
-   * callback. The creator of the state will also have its `onDelete` callback
-   * triggered.
+   *
+   * All nodes attached to the state will be detached, triggering any registered
+   * `onDetach` callbacks. The creator of the state will also have its own `onDelete`
+   * callback triggered. The local `onDeatch` and `onDelete` callbacks will be
+   * executed *before* the returned Promise resolves
    *
    * @throws Throws if the method is called by a node which is not the owner of
    * the state.
@@ -405,16 +509,20 @@ ${JSON.stringify(initValues, null, 2)}`);
    */
   async delete() {
     if (this._isOwner) {
+      if (this._detached) {
+        throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already deleted, cannot delete twice`);
+      }
+
       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`);
+      throw new Error(`[SharedState] Cannot delete state "${this.schemaName}", only the owner of the state (i.e. the node that created it) can delete the state. Use "detach" instead.`);
     }
   }
 
   /**
    * Subscribe to state updates.
    *
-   * @param {client.SharedState~onUpdateCallback|client.SharedState~onUpdateCallback} callback
+   * @param {client.SharedState~onUpdateCallback|server.SharedState~onUpdateCallback} callback
    *  Callback to execute when an update is applied on the state.
    * @param {Boolean} [executeListener=false] - Execute the callback immediately
    *  with current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
@@ -447,10 +555,11 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Register a function to execute when detaching from the state
+   * Register a function to execute when detaching from the state. The function
+   * will be executed before the `detach` promise resolves.
    *
-   * @param {Function} callback - callback to execute when detaching from the state.
-   *   wether the client as called `detach`, or the state has been deleted by its
+   * @param {Function} callback - Callback to execute when detaching from the state.
+   *   Whether the client as called `detach`, or the state has been deleted by its
    *   creator.
    */
   onDetach(callback) {
@@ -460,9 +569,10 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Register a function to execute when the state is deleted. Only called if the
-   * node was the creator of the state. Is called after `onDetach`
+   * node was the creator of the state. Is called after `onDetach` and executed
+   * before the `delete` Promise resolves.
    *
-   * @param {Function} callback - callback to execute when the state is deleted.
+   * @param {Function} callback - Callback to execute when the state is deleted.
    */
   onDelete(callback) {
     this._onDeleteCallbacks.add(callback);

package/src/common/BaseSharedStateCollection.js

@@ -0,0 +1,191 @@
+/**
+ * @private
+ */
+class BaseSharedStateCollection {
+  constructor(stateManager, schemaName) {
+    this._stateManager = stateManager;
+    this._schemaName = schemaName;
+    this._states = [];
+    this._onUpdateCallbacks = new Set();
+    this._onAttachCallbacks = new Set();
+    this._onDetachCallbacks = new Set();
+    this._unobserve = null;
+  }
+
+  async _init() {
+    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId, nodeId) => {
+      const state = await this._stateManager.attach(schemaName, stateId);
+
+      this._states.push(state);
+
+      state.onDetach(() => {
+        const index = this._states.indexOf(state);
+        this._states.splice(index, 1);
+
+        this._onDetachCallbacks.forEach(callback => callback(state));
+      });
+
+      state.onUpdate((newValues, oldValues, context) => {
+        Array.from(this._onUpdateCallbacks).forEach(callback => {
+          callback(state, newValues, oldValues, context);
+        });
+      });
+
+      this._onAttachCallbacks.forEach(callback => callback(state));
+    });
+  }
+
+  /**
+   * Size of the collection
+   * @type {number}
+   */
+  get length() {
+    return this._states.length;
+  }
+
+  /**
+   * Detach from the collection, i.e. detach all underlying shared states.
+   * @type {number}
+   */
+  async detach() {
+    this._unobserve();
+
+    const promises = Array.from(this._states).map(state => state.detach());
+    await Promise.all(promises);
+
+    this._onUpdateCallbacks.clear();
+    this._onDetachCallbacks.clear();
+  }
+
+  /**
+   * Return the current values of all the states in the collection.
+   * @return {Object[]}
+   */
+  getValues() {
+    return this._states.map(state => state.getValues());
+  }
+
+  /**
+   * Return the current param value of all the states in the collection.
+   *
+   * @param {String} name - Name of the parameter
+   * @return {any[]}
+   */
+  get(name) {
+    return this._states.map(state => state.get(name));
+  }
+
+  /**
+   * Update all states of the collection with given values.
+   * @param {object} updates - key / value pairs of updates to apply to the state.
+   * @param {mixed} [context=null] - optionnal contextual object 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 all update listeners.
+   */
+  async set(updates, context = null) {
+    const promises = this._states.map(state => state.set(updates, context));
+    return Promise.all(promises);
+  }
+
+  /**
+   * Subscribe to any state update of the collection.
+   *
+   * @param {server.SharedStateCollection~onUpdateCallback|client.SharedStateCollection~onUpdateCallback}
+   *  callback - Callback to execute when an update is applied on a state.
+   * @param {Boolean} [executeListener=false] - Execute the callback immediately
+   *  for all underlying states with current state values. (`oldValues` will be
+   *  set to `{}`, and `context` to `null`)
+   * @returns {Function} - Function that delete the registered listener.
+   */
+  onUpdate(callback, executeListener = false) {
+    this._onUpdateCallbacks.add(callback);
+
+    if (executeListener === true) {
+      this._states.forEach(state => {
+        const currentValues = state.getValues();
+        const oldValues = {};
+        const context = null;
+
+        callback(state, currentValues, oldValues, context);
+      });
+    }
+
+    return () => this._onUpdateCallbacks.delete(callback);
+  }
+
+  /**
+   * Register a function to execute when a state is added to the collection.
+   *
+   * @param {Function} callback - callback to execute  when a state is added to
+   *   the collection.
+   */
+  onAttach(callback) {
+    this._onAttachCallbacks.add(callback);
+  }
+
+  /**
+   * Register a function to execute when a state is removed from the collection.
+   *
+   * @param {Function} callback - callback to execute  when a state is removed
+   *   from the collection.
+   */
+  onDetach(callback) {
+    this._onDetachCallbacks.add(callback);
+  }
+
+  /**
+   * Execute the given function once for each states of the collection (see `Array.forEach`).
+   *
+   * @param {Function} func - A function to execute for each element in the array.
+   *  Its return value is discarded.
+   */
+  forEach(func) {
+    this._states.forEach(func);
+  }
+
+  /**
+   * Creates a new array populated with the results of calling a provided function
+   * on every state of the collection (see `Array.map`).
+   *
+   * @param {Function} func - A function to execute for each element in the array.
+   *  Its return value is added as a single element in the new array.
+   */
+  map(func) {
+    return this._states.map(func);
+  }
+
+  /**
+   * Creates a shallow copy of a portion of the collection, filtered down to just
+   * the estates that pass the test implemented by the provided function (see `Array.filter`).
+   *
+   * @param {Function} func - A function to execute for each element in the array.
+   *  It should return a truthy to keep the element in the resulting array, and a f
+   *  alsy value otherwise.
+   */
+  filter(func) {
+    return this._states.filter(func);
+  }
+
+  /**
+   * Sort the elements of the collection in place (see `Array.sort`).
+   *
+   * @param {Function} func - Function that defines the sort order.
+   */
+  sort(func) {
+    this._states.sort(func);
+  }
+
+  /**
+   * Returns the first element of the collection that satisfies the provided testing
+   * function. If no values satisfy the testing function, undefined is returned.
+   *
+   * @param {Function} func - Function to execute for each element in the array.
+   *  It should return a truthy value to indicate a matching element has been found.
+   * @return {}
+   */
+  find(func) {
+    return this._states.find(func);
+  }
+}
+
+export default BaseSharedStateCollection;

package/src/common/BaseStateManager.js

@@ -1,4 +1,6 @@
+import { isString, isFunction } from '@ircam/sc-utils';
 import SharedState from './BaseSharedState.js';
+import SharedStateCollection from './BaseSharedStateCollection.js';
 import {
   CREATE_REQUEST,
   CREATE_RESPONSE,
@@ -31,7 +33,7 @@ class BaseStateManager {
     this.client = { id, transport };
 
     this._statesById = new Map();
-    this._observeListeners = new Set();
+    this._observeListeners = new Map(); // Map <callback, filterSchemaName>
     this._cachedSchemas = new Map();
     this._observeRequestCallbacks = new Map();
 
@@ -88,28 +90,35 @@ class BaseStateManager {
     this.client.transport.addListener(OBSERVE_RESPONSE, async (reqId, ...list) => {
       // retrieve the callback that have been stored in observe to make sure
       // we don't call another callback that may have been registered earlier.
-      const callback = this._observeRequestCallbacks.get(reqId);
+      const [callback, filterSchemaName] = this._observeRequestCallbacks.get(reqId);
       this._observeRequestCallbacks.delete(reqId);
 
       const promises = list.map(([schemaName, stateId, nodeId]) => {
-        return callback(schemaName, stateId, nodeId);
+        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+          return callback(schemaName, stateId, nodeId);
+        } else {
+          return Promise.resolve();
+        }
       });
 
       await Promise.all(promises);
 
       const unsubscribe = () => {
         this._observeListeners.delete(callback);
-
+        // no more listeners, we can stop receiving notification from the server
         if (this._observeListeners.size === 0) {
           this.client.transport.emit(UNOBSERVE_NOTIFICATION);
         }
       };
+
       resolveRequest(reqId, unsubscribe);
     });
 
-    this.client.transport.addListener(OBSERVE_NOTIFICATION, (...list) => {
-      list.forEach(([schemaName, stateId, nodeId]) => {
-        this._observeListeners.forEach(callback => callback(schemaName, stateId, nodeId));
+    this.client.transport.addListener(OBSERVE_NOTIFICATION, (schemaName, stateId, nodeId) => {
+      this._observeListeners.forEach((filterSchemaName, callback) => {
+        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+          callback(schemaName, stateId, nodeId);
+        }
       });
     });
 
@@ -170,12 +179,19 @@ class BaseStateManager {
    * the state of all other clients of the application, to monitor them and/or take
    * control over them from a single point.
    *
-   * @todo Optionnal schema name
+   * Notes:
+   * - The states that are created by the same node are not propagated through
+   * the observe callback.
+   * - The order of execution is not guaranted, i.e. an state attached in the
+   * `observe` callback could be created before the `async create` method resolves.
+   *
+   * @param {String} [schemaName] - optionnal schema name to filter the observed
+   *  states.
    * @param {server.StateManager~ObserveCallback|client.StateManager~ObserveCallback}
    *  callback - Function to be called when a new state is created on the network.
-   * @returns {Promise<Function>} - Return a Promise that resolves when the callback
-   *  as been executed for the first time. The promise value is a function which
-   *  allows to stop observing the network.
+   * @returns {Promise<Function>} - Returns a Promise that resolves when the given
+   *  callback as been executed on each existing states. The promise value is a
+   *  function which allows to stop observing the states on the network.
    * @example
    * client.stateManager.observe(async (schemaName, stateId, nodeId) => {
    *   if (schemaName === 'something') {
@@ -184,16 +200,57 @@ class BaseStateManager {
    *   }
    * });
    */
-  async observe(callback) {
-    this._observeListeners.add(callback);
-    // store function
+  // note: all filtering is done only on client-side as it is really more simple to
+  // handle this way and the network overhead is very low for observe notifications:
+  // i.e. schemaName, stateId, nodeId
+  async observe(...args) {
+    let filterSchemaName;
+    let callback;
+
+    if (args.length === 1) {
+      filterSchemaName = '*';
+      callback = args[0];
+
+      if (!isFunction(callback)) {
+        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+      }
+    } else if (args.length === 2) {
+      filterSchemaName = args[0];
+      callback = args[1];
+
+      if (!isString(filterSchemaName) || !isFunction(callback)) {
+        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+      }
+    } else {
+      throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+    }
+
+    // resend request to get updated list of states
     return new Promise((resolve, reject) => {
       const reqId = storeRequestPromise(resolve, reject);
-      // store the callback to be executed on the response
-      this._observeRequestCallbacks.set(reqId, callback);
+      // store the callback for execution on the response. the returned Promise
+      // is fullfiled once callback has been executed with each existing states
+      this._observeRequestCallbacks.set(reqId, [callback, filterSchemaName]);
+      // store the callback for execution on subsequent notifications
+      this._observeListeners.set(callback, filterSchemaName);
+
       this.client.transport.emit(OBSERVE_REQUEST, reqId);
     });
   }
+
+  /**
+   * Returns a collection of all the states created from the schema name. Except
+   * the ones created by the current node.
+   *
+   * @param {string} schemaName - Name of the schema.
+   * @returns {server.SharedStateCollection|client.SharedStateCollection}
+   */
+  async getCollection(schemaName) {
+    const collection = new SharedStateCollection(this, schemaName);
+    await collection._init();
+
+    return collection;
+  }
 }
 
 export default BaseStateManager;