@soundworks/core 4.0.0-alpha.2 → 4.0.0-alpha.20

package/src/common/BaseSharedStateCollection.js

@@ -0,0 +1,279 @@
+/** @private */
+class BaseSharedStateCollection {
+  constructor(stateManager, schemaName, options = {}) {
+    this._stateManager = stateManager;
+    this._schemaName = schemaName;
+    this._options = Object.assign({ excludeLocal: false }, options);
+
+    this._schema = null;
+    this._states = [];
+
+    this._onUpdateCallbacks = new Set();
+    this._onAttachCallbacks = new Set();
+    this._onDetachCallbacks = new Set();
+    this._unobserve = null;
+  }
+
+  /** @private */
+  async _init() {
+    this._schema = await this._stateManager.getSchema(this._schemaName);
+
+    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId) => {
+      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));
+    }, this._options);
+  }
+
+  /**
+   * Size of the collection, alias `size`
+   * @type {number}
+   * @readonly
+   */
+  get length() {
+    return this._states.length;
+  }
+
+  /**
+   * Size of the collection, , alias `length`
+   * @type {number}
+   * @readonly
+   */
+  get size() {
+    return this._states.length;
+  }
+
+  /**
+   * Name of the schema from which the collection has been created.
+   * @type {String}
+   * @readonly
+   */
+  get schemaName() {
+    return this._schemaName;
+  }
+
+  /**
+   * Definition of schema from which the collection has been created.
+   *
+   * @param {string} [name=null] - If given, returns only the definition
+   *  corresponding to the given param name.
+   * @throws Throws if `name` does not correspond to an existing field
+   *  of the schema.
+   * @return {object}
+   * @example
+   * const schema = collection.getSchema();
+   */
+  getSchema(name = null) {
+    if (name) {
+      return this._schema[name];
+    }
+
+    return this._schema;
+  }
+
+  /**
+   * Get the default values as declared in the schema.
+   *
+   * @return {object}
+   * @example
+   * const defaults = state.getDefaults();
+   */
+  getDefaults() {
+    const defaults = {};
+    for (let name in this._schema) {
+      defaults[name] = this._schema[name].default;
+    }
+    return defaults;
+  }
+
+  /**
+   * 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) {
+    // hot fix for https://github.com/collective-soundworks/soundworks/issues/85
+    // to be cleaned soon
+    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.
+   * @param {Function} executeListener - execute the callback with the states
+   *   already present in the collection.
+   * @returns {Function} - Function that delete the registered listener.
+   */
+  onAttach(callback, executeListener = false) {
+    if (executeListener === true) {
+      this._states.forEach(state => callback(state));
+    }
+
+    this._onAttachCallbacks.add(callback);
+
+    return () => this._onAttachCallbacks.delete(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.
+   * @returns {Function} - Function that delete the registered listener.
+   */
+  onDetach(callback) {
+    this._onDetachCallbacks.add(callback);
+
+    return () => this._onDetachCallbacks.delete(callback);
+  }
+
+  /**
+   * Detach from the collection, i.e. detach all underlying shared states.
+   * @type {number}
+   */
+  async detach() {
+    this._unobserve();
+    this._onUpdateCallbacks.clear();
+
+    const promises = this._states.map(state => state.detach());
+    await Promise.all(promises);
+
+    this._onDetachCallbacks.clear();
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * Iterable API, e.g. for use in `for .. of` loops
+   */
+  [Symbol.iterator]() {
+    let index = 0;
+
+    return {
+      next: () => {
+        if (index >= this._states.length) {
+          return { value: undefined, done: true };
+        } else {
+          return { value: this._states[index++], done: false };
+        }
+      },
+    };
+  }
+}
+
+export default BaseSharedStateCollection;

package/src/common/BaseStateManager.js

@@ -1,4 +1,9 @@
+import { isString, isFunction, isPlainObject } from '@ircam/sc-utils';
 import SharedState from './BaseSharedState.js';
+import SharedStateCollection from './BaseSharedStateCollection.js';
+import BatchedTransport from './BatchedTransport.js';
+import ParameterBag from './ParameterBag.js';
+import PromiseStore from './PromiseStore.js';
 import {
   CREATE_REQUEST,
   CREATE_RESPONSE,
@@ -8,15 +13,14 @@ import {
   ATTACH_ERROR,
   OBSERVE_REQUEST,
   OBSERVE_RESPONSE,
+  OBSERVE_ERROR,
   OBSERVE_NOTIFICATION,
   UNOBSERVE_NOTIFICATION,
   DELETE_SCHEMA,
+  GET_SCHEMA_REQUEST,
+  GET_SCHEMA_RESPONSE,
+  GET_SCHEMA_ERROR,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
 
 /**
  * @private
@@ -28,12 +32,16 @@ class BaseStateManager {
    *  Must implement a basic EventEmitter API.
    */
   constructor(id, transport) {
-    this.client = { id, transport };
+    // proxy transport with BatchedTransport;
+    this.client = { id, transport: new BatchedTransport(transport) };
+
+    this._statesById = new Map(); // <id, state>
+    this._cachedSchemas = new Map(); // <shemaName, definition>
+
+    this._observeListeners = new Set(); // Set <[observedSchemaName, callback, options]>
+    this._observeRequestCallbacks = new Map(); // Map <reqId, [observedSchemaName, callback, options]>
 
-    this._statesById = new Map();
-    this._observeListeners = new Set();
-    this._cachedSchemas = new Map();
-    this._observeRequestCallbacks = new Map();
+    this._promiseStore = new PromiseStore();
 
     // ---------------------------------------------
     // CREATE
@@ -51,11 +59,11 @@ class BaseStateManager {
       const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, true, this, initValues);
       this._statesById.set(state.id, state);
 
-      resolveRequest(reqId, state);
+      this._promiseStore.resolve(reqId, state);
     });
 
     this.client.transport.addListener(CREATE_ERROR, (reqId, msg) => {
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     // ---------------------------------------------
@@ -75,11 +83,11 @@ class BaseStateManager {
       const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues);
       this._statesById.set(state.id, state);
 
-      resolveRequest(reqId, state);
+      this._promiseStore.resolve(reqId, state);
     });
 
     this.client.transport.addListener(ATTACH_ERROR, (reqId, msg) => {
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     // ---------------------------------------------
@@ -88,28 +96,52 @@ 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 observeInfos = this._observeRequestCallbacks.get(reqId);
+      const [observedSchemaName, callback, options] = observeInfos;
+
+      // move observeInfos from `_observeRequestCallbacks` to `_observeListeners`
+      // to guarantee order of execution, @see not in `.observe`
       this._observeRequestCallbacks.delete(reqId);
+      this._observeListeners.add(observeInfos);
 
       const promises = list.map(([schemaName, stateId, nodeId]) => {
-        return callback(schemaName, stateId, nodeId);
+        const filter = this._filterObserve(observedSchemaName, schemaName, nodeId, options);
+
+        if (!filter) {
+          return callback(schemaName, stateId, nodeId);
+        } else {
+          return Promise.resolve();
+        }
       });
 
       await Promise.all(promises);
 
       const unsubscribe = () => {
-        this._observeListeners.delete(callback);
+        this._observeListeners.delete(observeInfos);
 
+        // no more listeners, we can stop receiving notifications from the server
         if (this._observeListeners.size === 0) {
           this.client.transport.emit(UNOBSERVE_NOTIFICATION);
         }
       };
-      resolveRequest(reqId, unsubscribe);
+
+      this._promiseStore.resolve(reqId, unsubscribe);
+    });
+
+    // Observe error can occur if observed schema name does not exists
+    this.client.transport.addListener(OBSERVE_ERROR, (reqId, msg) => {
+      this._observeRequestCallbacks.delete(reqId);
+      this._promiseStore.reject(reqId, msg);
     });
 
-    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(observeInfos => {
+        const [observedSchemaName, callback, options] = observeInfos;
+        const filter = this._filterObserve(observedSchemaName, schemaName, nodeId, options);
+
+        if (!filter) {
+          callback(schemaName, stateId, nodeId);
+        }
       });
     });
 
@@ -119,6 +151,59 @@ class BaseStateManager {
     this.client.transport.addListener(DELETE_SCHEMA, schemaName => {
       this._cachedSchemas.delete(schemaName);
     });
+
+    // ---------------------------------------------
+    // GET SCHEMA
+    // ---------------------------------------------
+    this.client.transport.addListener(GET_SCHEMA_RESPONSE, (reqId, schemaName, schema) => {
+      if (!this._cachedSchemas.has(schemaName)) {
+        this._cachedSchemas.set(schemaName, schema);
+      }
+      // return a populated schema
+      const parameterBag = new ParameterBag(schema);
+      this._promiseStore.resolve(reqId, parameterBag.getSchema());
+    });
+
+    this.client.transport.addListener(GET_SCHEMA_ERROR, (reqId, msg) => {
+      this._promiseStore.reject(reqId, msg);
+    });
+  }
+
+  /** @private */
+  _filterObserve(observedSchemaName, schemaName, creatorId, options) {
+    let filter = true;
+    // schema name filter filer
+    if (observedSchemaName === null || observedSchemaName === schemaName) {
+      filter = false;
+    }
+    // filter state created by client if excludeLocal is true
+    if (options.excludeLocal === true && creatorId === this.client.id) {
+      filter = true;
+    }
+
+    return filter;
+  }
+
+  /**
+   * Return the schema from a given registered schema name
+   *
+   * @param {String} schemaName - Name of the schema as given on registration
+   *  (cf. ServerStateManager)
+   * @example
+   * const schema = await client.stateManager.getSchema('my-schema');
+   */
+  async getSchema(schemaName) {
+    if (this._cachedSchemas.has(schemaName)) {
+      const schema = this._cachedSchemas.get(schemaName);
+      // return a populated schema
+      const parameterBag = new ParameterBag(schema);
+      return parameterBag.getSchema();
+    }
+
+    return new Promise((resolve, reject) => {
+      const reqId = this._promiseStore.add(resolve, reject, 'get-schema');
+      this.client.transport.emit(GET_SCHEMA_REQUEST, reqId, schemaName);
+    });
   }
 
   /**
@@ -135,7 +220,7 @@ class BaseStateManager {
    */
   async create(schemaName, initValues = {}) {
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'create-request');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(CREATE_REQUEST, reqId, schemaName, requireSchema, initValues);
     });
@@ -157,8 +242,7 @@ class BaseStateManager {
    */
   async attach(schemaName, stateId = null) {
     return new Promise((resolve, reject) => {
-      // @todo - add a timeout
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'attach-request');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema);
     });
@@ -170,30 +254,167 @@ 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 order of execution is not guaranted between nodes, i.e. an state attached
+   * in the `observe` callback could be created before the `async create` method resolves.
+   * - Filtering, i.e. `observedSchemaName` and `options.excludeLocal` are handled
+   * on the node side, the server just notify all state creation activity and
+   * the node executes the given callbacks according to the different filter rules.
+   * Such strategy allows to share the observe notifications between all observers.
+   *
+   * Alternative signatures:
+   * - .observe(callback)
+   * - .observe(schemaName, callback)
+   * - .observe(callback, options)
+   * - .observe(schemaName, callback, options)
+   *
+   * @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.
+   * @param {object} options - Options.
+   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
+   *  created locallly, i.e. by the same node, from the collection.
+   * @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) => {
+   * client.stateManager.observe(async (schemaName, stateId) => {
    *   if (schemaName === 'something') {
    *     const state = await this.client.stateManager.attach(schemaName, stateId);
    *     console.log(state.getValues());
    *   }
    * });
    */
-  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) {
+
+    const defaultOptions = {
+      excludeLocal: false,
+    };
+
+    let observedSchemaName;
+    let callback;
+    let options;
+
+    switch (args.length) {
+      case 1: {
+        // variation: .observe(callback)
+        if (!isFunction(args[0])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 1 should be a function"`);
+        }
+
+        observedSchemaName = null;
+        callback = args[0];
+        options = defaultOptions;
+        break;
+      }
+      case 2: {
+        // variation: .observe(schemaName, callback)
+        if (isString(args[0])) {
+          if (!isFunction(args[1])) {
+            throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be a function"`);
+          }
+
+          observedSchemaName = args[0];
+          callback = args[1];
+          options = defaultOptions;
+
+        // variation: .observe(callback, options) API
+        } else if (isFunction(args[0])) {
+          if (!isPlainObject(args[1])) {
+            throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be an object"`);
+          }
+
+          observedSchemaName = null;
+          callback = args[0];
+          options = Object.assign(defaultOptions, args[1]);
+
+        } else {
+          throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
+        }
+
+        break;
+      }
+      case 3: {
+        // variation: .observe(schemaName, callback, options)
+        if (!isString(args[0])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 1 should be a string"`);
+        }
+
+        if (!isFunction(args[1])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be a function"`);
+        }
+
+        if (!isPlainObject(args[2])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be an object"`);
+        }
+
+        observedSchemaName = args[0];
+        callback = args[1];
+        options = Object.assign(defaultOptions, args[2]);
+
+        break;
+      }
+      // throw in all other cases
+      default: {
+        throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
+      }
+    }
+
+    // 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);
-      this.client.transport.emit(OBSERVE_REQUEST, reqId);
+      const reqId = this._promiseStore.add(resolve, reject, 'observe-request');
+      // store the callback for execution on the response. the returned Promise
+      // is fullfiled once callback has been executed with each existing states
+      const observeInfos = [observedSchemaName, 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 (schemaName, stateId, nodeId) => {});
+      // // client now receives OBSERVE_NOTIFICATIONS
+      // await otherClient.stateManager.create('a');
+      // // second observer added in between
+      // client.stateManager.observe(async (schemaName, 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.client.transport.emit(OBSERVE_REQUEST, reqId, observedSchemaName);
     });
   }
+
+  /**
+   * Returns a collection of all the states created from the schema name.
+   *
+   * @param {string} schemaName - Name of the schema.
+   * @param {object} options - Options.
+   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
+   *  created locallly, i.e. by the same node, from the collection.
+   * @returns {server.SharedStateCollection|client.SharedStateCollection}
+   */
+  async getCollection(schemaName, options) {
+    const collection = new SharedStateCollection(this, schemaName, options);
+
+    try {
+      await collection._init();
+    } catch (err) {
+      console.log(err.message);
+      throw new Error(`[stateManager] Cannot create collection, schema "${schemaName}" does not exists`);
+    }
+
+    return collection;
+  }
 }
 
 export default BaseStateManager;