@soundworks/core 3.7.0 → 4.0.0-alpha.0

package/src/common/BaseStateManager.js

@@ -0,0 +1,200 @@
+import SharedState from './BaseSharedState.js';
+import {
+  CREATE_REQUEST,
+  CREATE_RESPONSE,
+  CREATE_ERROR,
+  ATTACH_REQUEST,
+  ATTACH_RESPONSE,
+  ATTACH_ERROR,
+  OBSERVE_REQUEST,
+  OBSERVE_RESPONSE,
+  OBSERVE_NOTIFICATION,
+  UNOBSERVE_NOTIFICATION,
+  DELETE_SCHEMA,
+} from './constants.js';
+import {
+  storeRequestPromise,
+  resolveRequest,
+  rejectRequest,
+} from './promise-store.js';
+
+/**
+ * @private
+ */
+class BaseStateManager {
+  /**
+   * @param {Number} id - Id of the node.
+   * @param {Object} transport - Transport to use for synchronizing the state.
+   *  Must implement a basic EventEmitter API.
+   */
+  constructor(id, transport) {
+    this.client = { id, transport };
+
+    this._statesById = new Map();
+    this._observeListeners = new Set();
+    this._cachedSchemas = new Map();
+    this._observeRequestCallbacks = new Map();
+
+    // ---------------------------------------------
+    // CREATE
+    // ---------------------------------------------
+
+    this.client.transport.addListener(CREATE_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, initValues) => {
+
+      // cache schema when first dealing it to save some bandwidth
+      if (!this._cachedSchemas.has(schemaName)) {
+        this._cachedSchemas.set(schemaName, schema);
+      }
+
+      schema = this._cachedSchemas.get(schemaName);
+
+      const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, true, this, initValues);
+      this._statesById.set(state.id, state);
+
+      resolveRequest(reqId, state);
+    });
+
+    this.client.transport.addListener(CREATE_ERROR, (reqId, msg) => {
+      rejectRequest(reqId, msg);
+    });
+
+    // ---------------------------------------------
+    // ATTACH (when creator, is attached by default)
+    // ---------------------------------------------
+    this.client.transport.addListener(ATTACH_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, currentValues) => {
+      // cache schema when first dealing with it to save some bandwidth
+      // note: when we make the schemas dynamic at some point
+      // the server should be able to invalidate the schema and send
+      // it again despite the caching.
+      if (!this._cachedSchemas.has(schemaName)) {
+        this._cachedSchemas.set(schemaName, schema);
+      }
+
+      schema = this._cachedSchemas.get(schemaName);
+
+      const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues);
+      this._statesById.set(state.id, state);
+
+      resolveRequest(reqId, state);
+    });
+
+    this.client.transport.addListener(ATTACH_ERROR, (reqId, msg) => {
+      rejectRequest(reqId, msg);
+    });
+
+    // ---------------------------------------------
+    // OBSERVE PEERS (be notified when a state is created, lazy)
+    // ---------------------------------------------
+    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);
+      this._observeRequestCallbacks.delete(reqId);
+
+      const promises = list.map(([schemaName, stateId, nodeId]) => {
+        return callback(schemaName, stateId, nodeId);
+      });
+
+      await Promise.all(promises);
+
+      const unsubscribe = () => {
+        this._observeListeners.delete(callback);
+
+        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));
+      });
+    });
+
+    // ---------------------------------------------
+    // Clear cache when schema is deleted
+    // ---------------------------------------------
+    this.client.transport.addListener(DELETE_SCHEMA, schemaName => {
+      this._cachedSchemas.delete(schemaName);
+    });
+  }
+
+  /**
+   * Create a `SharedState` instance from a registered schema.
+   *
+   * @param {String} schemaName - Name of the schema as given on registration
+   *  (cf. ServerStateManager)
+   * @param {Object} [initValues={}] - Default values for the state.
+   * @returns {client.SharedState|server.SharedState}
+   * @see {@link client.SharedState}
+   * @see {@link server.SharedState}
+   * @example
+   * const state = await client.stateManager.create('my-schema');
+   */
+  async create(schemaName, initValues = {}) {
+    return new Promise((resolve, reject) => {
+      const reqId = storeRequestPromise(resolve, reject);
+      const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
+      this.client.transport.emit(CREATE_REQUEST, reqId, schemaName, requireSchema, initValues);
+    });
+  }
+
+  /**
+   * Attach to an existing `SharedState` instance.
+   *
+   * @param {String} schemaName - Name of the schema as given on registration
+   *  (cf. ServerStateManager)
+   * @param {Object} [stateId=null] - Id of the state to attach to. If `null`,
+   *  attach to the first state found with the given schema name (usefull for
+   *  globally shared states owned by the server).
+   * @returns {client.SharedState|server.SharedState}
+   * @see {@link client.SharedState}
+   * @see {@link server.SharedState}
+   * @example
+   * const state = await client.stateManager.attach('my-schema');
+   */
+  async attach(schemaName, stateId = null) {
+    return new Promise((resolve, reject) => {
+      // @todo - add a timeout
+      const reqId = storeRequestPromise(resolve, reject);
+      const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
+      this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema);
+    });
+  }
+
+  /**
+   * Observe all the `SharedState` instances that are created on the network.
+   * This can be usefull for clients with some controller role that might want to track
+   * 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
+   * @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.
+   * @example
+   * client.stateManager.observe(async (schemaName, stateId, nodeId) => {
+   *   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
+    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);
+    });
+  }
+}
+
+export default BaseStateManager;
+

package/{common → src/common}/ParameterBag.js

@@ -1,18 +1,5 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.types = exports.sharedOptions = exports.default = void 0;
-
-var _lodash = _interopRequireDefault(require("lodash.clonedeep"));
-
-var _fastDeepEqual = _interopRequireDefault(require("fast-deep-equal"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// import types from './types';
-// import shallowClone from 'shallow-clone';
+import cloneDeep from 'lodash.clonedeep';
+import equal from 'fast-deep-equal';
 
 /**
  * @typedef {Object} server.SharedStateManagerServer~schema
@@ -44,7 +31,6 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   }
  * }
  */
-
 /**
  * @typedef {Object} server.SharedStateManagerServer~schemaBooleanDef
  *
@@ -62,15 +48,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   (which has no state per se). As such, setting this options to `false` if
  *   `event=true` does not make sens.
  * @property {Boolean} [immediate=false] - Setting this option to `true` will
- *   trigger any change (e.g. call the subscribe listeners) immediately on the
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
  *   state that generate the update (i.e. calling `set`), before propagating the
  *   change on the network. This option can be usefull in cases the network
  *   would introduce a noticeable latency on the client. If for some reason
- *   the value is overriden server-side (e.g. in an updateHook) the listeners
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
  *   will be called again on when the "real" / final value will be received.
  * @property {Object} [metas={}] - Optionnal metadata of the parameter.
  */
-
 /**
  * @typedef {Object} server.SharedStateManagerServer~schemaStringDef
  *
@@ -88,15 +73,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   (which has no state per se). As such, setting this options to `false` if
  *   `event=true` does not make sens.
  * @property {Boolean} [immediate=false] - Setting this option to `true` will
- *   trigger any change (e.g. call the subscribe listeners) immediately on the
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
  *   state that generate the update (i.e. calling `set`), before propagating the
  *   change on the network. This option can be usefull in cases the network
  *   would introduce a noticeable latency on the client. If for some reason
- *   the value is overriden server-side (e.g. in an updateHook) the listeners
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
  *   will be called again on when the "real" / final value will be received.
  * @property {Object} [metas={}] - Optionnal metadata of the parameter.
  */
-
 /**
  @typedef {Object} server.SharedStateManagerServer~schemaIntegerDef
  *
@@ -116,15 +100,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   (which has no state per se). As such, setting this options to `false` if
  *   `event=true` does not make sens.
  * @property {Boolean} [immediate=false] - Setting this option to `true` will
- *   trigger any change (e.g. call the subscribe listeners) immediately on the
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
  *   state that generate the update (i.e. calling `set`), before propagating the
  *   change on the network. This option can be usefull in cases the network
  *   would introduce a noticeable latency on the client. If for some reason
- *   the value is overriden server-side (e.g. in an updateHook) the listeners
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
  *   will be called again on when the "real" / final value will be received.
  * @property {Object} [metas={}] - Optionnal metadata of the parameter.
  */
-
 /**
  * @typedef {Object} server.SharedStateManagerServer~schemaFloatDef
  *
@@ -144,15 +127,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   (which has no state per se). As such, setting this options to `false` if
  *   `event=true` does not make sens.
  * @property {Boolean} [immediate=false] - Setting this option to `true` will
- *   trigger any change (e.g. call the subscribe listeners) immediately on the
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
  *   state that generate the update (i.e. calling `set`), before propagating the
  *   change on the network. This option can be usefull in cases the network
  *   would introduce a noticeable latency on the client. If for some reason
- *   the value is overriden server-side (e.g. in an updateHook) the listeners
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
  *   will be called again on when the "real" / final value will be received.
  * @property {Object} [metas={}] - Optionnal metadata of the parameter.
  */
-
 /**
  * @typedef {Object} server.SharedStateManagerServer~schemaEnumDef
  *
@@ -171,15 +153,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   (which has no state per se). As such, setting this options to `false` if
  *   `event=true` does not make sens.
  * @property {Boolean} [immediate=false] - Setting this option to `true` will
- *   trigger any change (e.g. call the subscribe listeners) immediately on the
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
  *   state that generate the update (i.e. calling `set`), before propagating the
  *   change on the network. This option can be usefull in cases the network
  *   would introduce a noticeable latency on the client. If for some reason
- *   the value is overriden server-side (e.g. in an updateHook) the listeners
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
  *   will be called again on when the "real" / final value will be received.
  * @property {Object} [metas={}] - Optionnal metadata of the parameter.
  */
-
 /**
  * @typedef {Object} server.SharedStateManagerServer~schemaAnyDef
  *
@@ -200,65 +181,59 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  *   (which has no state per se). As such, setting this options to `false` if
  *   `event=true` does not make sens.
  * @property {Boolean} [immediate=false] - Setting this option to `true` will
- *   trigger any change (e.g. call the subscribe listeners) immediately on the
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
  *   state that generate the update (i.e. calling `set`), before propagating the
  *   change on the network. This option can be usefull in cases the network
  *   would introduce a noticeable latency on the client. If for some reason
- *   the value is overriden server-side (e.g. in an updateHook) the listeners
+ *   the value is overriden server-side (e.g. in an `updateHook`) the listeners
  *   will be called again on when the "real" / final value will be received.
  * @property {Object} [metas={}] - Optionnal metadata of the parameter.
  */
-const sharedOptions = {
+
+export const sharedOptions = {
   nullable: false,
-  event: false,
-  // if event=true, nullable=true
+  event: false, // if event=true, nullable=true
   metas: {},
   filterChange: true,
-  immediate: false
+  immediate: false,
 };
-exports.sharedOptions = sharedOptions;
-const types = {
+
+export const types = {
   boolean: {
     required: ['default'],
-
     get defaultOptions() {
-      return Object.assign((0, _lodash.default)(sharedOptions), {});
+      return Object.assign(cloneDeep(sharedOptions), {});
     },
-
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'boolean') {
         throw new TypeError(`[stateManager] Invalid value for boolean param "${name}": ${value}`);
       }
 
       return value;
-    }
+    },
   },
   string: {
     required: ['default'],
-
     get defaultOptions() {
-      return Object.assign((0, _lodash.default)(sharedOptions), {});
+      return Object.assign(cloneDeep(sharedOptions), {});
     },
-
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'string') {
         throw new TypeError(`[stateManager] Invalid value for string param "${name}": ${value}`);
       }
 
       return value;
-    }
+    },
   },
   integer: {
     required: ['default'],
-
     get defaultOptions() {
-      return Object.assign((0, _lodash.default)(sharedOptions), {
+      return Object.assign(cloneDeep(sharedOptions), {
         min: -Infinity,
-        max: +Infinity
+        max: +Infinity,
       });
     },
-
-    sanitizeSchema: def => {
+    sanitizeSchema: (def) => {
       // sanitize `null` values in received schema, this prevent a bug when
       // `min` and `max` are explicitely set to `±Infinity`, the schema is stringified
       // when sent over the network and therefore Infinity is transformed to `null`
@@ -281,19 +256,17 @@ const types = {
       }
 
       return Math.max(def.min, Math.min(def.max, value));
-    }
+    },
   },
   float: {
     required: ['default'],
-
     get defaultOptions() {
-      return Object.assign((0, _lodash.default)(sharedOptions), {
+      return Object.assign(cloneDeep(sharedOptions), {
         min: -Infinity,
-        max: +Infinity
+        max: +Infinity,
       });
     },
-
-    sanitizeSchema: def => {
+    sanitizeSchema: (def) => {
       // sanitize `null` values in received schema, this prevent a bug when
       // `min` and `max` are explicitely set to `±Infinity`, the schema is stringified
       // when sent over the network and therefore Infinity is transformed to `null`
@@ -311,49 +284,44 @@ const types = {
       return def;
     },
     coerceFunction: (name, def, value) => {
-      if (typeof value !== 'number' || value !== value) {
-        // reject NaN
+      if (typeof value !== 'number' || value !== value) { // reject NaN
         throw new TypeError(`[stateManager] Invalid value for float param "${name}": ${value}`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
-    }
+    },
   },
   enum: {
     required: ['default', 'list'],
-
     get defaultOptions() {
-      return Object.assign((0, _lodash.default)(sharedOptions), {});
+      return Object.assign(cloneDeep(sharedOptions), {});
     },
-
     coerceFunction: (name, def, value) => {
       if (def.list.indexOf(value) === -1) {
         throw new TypeError(`[stateManager] Invalid value for enum param "${name}": ${value}`);
       }
 
+
       return value;
-    }
+    },
   },
   any: {
     required: ['default'],
-
     get defaultOptions() {
-      return Object.assign((0, _lodash.default)(sharedOptions), {});
+      return Object.assign(cloneDeep(sharedOptions), {});
     },
-
     coerceFunction: (name, def, value) => {
       // no check as it can have any type...
       return value;
-    }
-  }
+    },
+  },
 };
+
+
 /**
  * Bag of parameters.
  * @private
  */
-
-exports.types = types;
-
 class ParameterBag {
   static validateSchema(schema) {
     for (let name in schema) {
@@ -368,8 +336,10 @@ class ParameterBag {
       }
 
       const required = types[def.type].required;
+
       required.forEach(key => {
-        if (def.event === true && key === 'default') {// do nothing, default is always null for `event` params
+        if (def.event === true && key === 'default') {
+          // do nothing, default is always null for `event` params
         } else if (!Object.prototype.hasOwnProperty.call(def, key)) {
           throw new TypeError(`[stateManager] Invalid schema definition - param "${name}" (type "${def.type}"): "${key}" key is required`);
         }
@@ -382,8 +352,9 @@ class ParameterBag {
       throw new Error(`[stateManager] schema is mandatory`);
     }
 
-    schema = (0, _lodash.default)(schema);
-    initValues = (0, _lodash.default)(initValues);
+    schema = cloneDeep(schema);
+    initValues = cloneDeep(initValues);
+
     /**
      * List of parameters.
      *
@@ -393,8 +364,8 @@ class ParameterBag {
      * @instance
      * @private
      */
-
     this._values = {};
+
     /**
      * List of schema with init values.
      *
@@ -404,10 +375,11 @@ class ParameterBag {
      * @instance
      * @private
      */
-
     this._schema = {};
-    ParameterBag.validateSchema(schema); // make shure initValues make sens according to the given schema
 
+    ParameterBag.validateSchema(schema);
+
+    // make shure initValues make sens according to the given schema
     for (let name in initValues) {
       if (!Object.prototype.hasOwnProperty.call(schema, name)) {
         throw new ReferenceError(`[stateManager] init value defined for undefined param "${name}"`);
@@ -419,12 +391,10 @@ class ParameterBag {
         def = types[def.type].sanitizeSchema(def);
       }
 
-      const {
-        defaultOptions
-      } = types[def.type];
-      def = Object.assign({}, defaultOptions, def); // if event property is set to true, the param must
+      const { defaultOptions } = types[def.type];
+      def = Object.assign({}, defaultOptions, def);
+      // if event property is set to true, the param must
       // be nullable and its default value is `undefined`
-
       if (def.event === true) {
         def.nullable = true;
         def.default = null;
@@ -438,31 +408,32 @@ class ParameterBag {
         initValue = def.default;
       }
 
-      this._schema[name] = def; // coerce init value and store in definition
 
+      this._schema[name] = def;
+      // coerce init value and store in definition
       initValue = this.set(name, initValue)[0];
+
       this._schema[name].initValue = initValue;
       this._values[name] = initValue;
+
     }
   }
+
   /**
    * Define if the parameter exists.
    *
    * @param {String} name - Name of the parameter.
    * @return {Boolean}
    */
-
-
   has(name) {
     return Object.prototype.hasOwnProperty.call(this._schema, name);
   }
+
   /**
    * Return values of all parameters as a flat object.
    *
    * @return {Object}
    */
-
-
   getValues() {
     let values = {};
 
@@ -472,6 +443,7 @@ class ParameterBag {
 
     return values;
   }
+
   /**
    * Return the value of the given parameter. If the parameter is of `any` type,
    * a deep copy is returned.
@@ -479,19 +451,18 @@ class ParameterBag {
    * @param {String} name - Name of the parameter.
    * @return {Mixed} - Value of the parameter.
    */
-
-
   get(name) {
     if (!this.has(name)) {
       throw new ReferenceError(`[stateManager] Cannot get value of undefined parameter "${name}"`);
     }
 
     if (this._schema[name].type === 'any') {
-      return (0, _lodash.default)(this._values[name]);
+      return cloneDeep(this._values[name]);
     } else {
       return this._values[name];
     }
   }
+
   /**
    * Set the value of a parameter. If the value of the parameter is updated
    * (aka if previous value is different from new value) all registered
@@ -503,17 +474,13 @@ class ParameterBag {
    *    if the value has not changed.
    * @return {Array} - [new value, updated flag].
    */
-
-
   set(name, value) {
     if (!this.has(name)) {
       throw new ReferenceError(`[stateManager] Cannot set value of undefined parameter "${name}"`);
     }
 
     const def = this._schema[name];
-    const {
-      coerceFunction
-    } = types[def.type];
+    const { coerceFunction } = types[def.type];
 
     if (value === null && def.nullable === false) {
       throw new TypeError(`[stateManager] Invalid value for ${def.type} param "${name}": value is null and param is not nullable`);
@@ -524,11 +491,14 @@ class ParameterBag {
     }
 
     const currentValue = this._values[name];
-    const updated = !(0, _fastDeepEqual.default)(currentValue, value);
-    this._values[name] = value; // return tuple so that the state manager can handle the `filterChange` option
+    const updated = !equal(currentValue, value);
+
+    this._values[name] = value;
 
+    // return tuple so that the state manager can handle the `filterChange` option
     return [value, updated];
   }
+
   /**
    * Reset a parameter to its initialization values. Reset all parameters if no argument.
    * @note - prefer `state.set(state.getInitValues())`
@@ -551,8 +521,6 @@ class ParameterBag {
    *
    * @return {Object}
    */
-
-
   getSchema(name = null) {
     if (name === null) {
       return this._schema;
@@ -563,31 +531,25 @@ class ParameterBag {
 
       return this._schema[name];
     }
-  } // return the default value, if initValue has been given, return init values
-
+  }
 
+  // return the default value, if initValue has been given, return init values
   getInitValues() {
     const initValues = {};
-
     for (let [name, def] of Object.entries(this._schema)) {
       initValues[name] = def.initValue;
     }
-
     return initValues;
-  } // return the default value, if initValue has been given, return init values
-
+  }
 
+  // return the default value, if initValue has been given, return init values
   getDefaults() {
     const defaults = {};
-
     for (let [name, def] of Object.entries(this._schema)) {
       defaults[name] = def.defaults;
     }
-
     return defaults;
   }
-
 }
 
-var _default = ParameterBag;
-exports.default = _default;
+export default ParameterBag;