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

package/src/common/ParameterBag.js

@@ -1,195 +1,6 @@
 import cloneDeep from 'lodash.clonedeep';
 import equal from 'fast-deep-equal';
 
-/**
- * @typedef {Object} server.SharedStateManagerServer~schema
- *
- * Description of a schema to be register by the {@link server.ServerStateManagerServer}
- * A schema consists of a combinaison of key value pairs where the key is the
- * name of the parameter, and the value is an object describing the parameter.
- *
- * Available types are:
- * - {@link server.SharedStateManagerServer~schemaBooleanDef}
- * - {@link server.SharedStateManagerServer~schemaStringDef}
- * - {@link server.SharedStateManagerServer~schemaIntegerDef}
- * - {@link server.SharedStateManagerServer~schemaFloatDef}
- * - {@link server.SharedStateManagerServer~schemaEnumDef}
- * - {@link server.SharedStateManagerServer~schemaAnyDef}
- *
- * @example
- * {
- *   myBoolean: {
- *     type: 'boolean'
- *     default: false,
- *   },
- *   myFloat: {
- *     type: 'float'
- *     default: 0.1,
- *     min: -1,
- *     max: 1,
- *     event: true,
- *   }
- * }
- */
-/**
- * @typedef {Object} server.SharedStateManagerServer~schemaBooleanDef
- *
- * @property {String} type='boolean' - Define a boolean parameter.
- * @property {Boolean} default - Default value of the parameter.
- * @property {Boolean} [nullable=false] - Define if the parameter is nullable. If
- *   set to `true` the parameter `default` is set to `null`.
- * @property {Boolean} [event=false] - Define if the parameter is a volatile, e.g.
- *   set its value back to `null` after propagation. When `true`, `nullable` is
- *   automatically set to `true` and `default` to `null`.
- * @property {Boolean} [filterChange=true] - Setting this option to `false` forces
- *   the propagation of a parameter even when its value do not change. It
- *   offers a kind of middle ground between the default bahavior (e.g. where
- *   only changed values are propagated) and the behavior of the `event` option
- *   (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 `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
- *   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
- *
- * @property {String} type='string' - Define a boolean parameter.
- * @property {Mixed} default - Default value of the parameter.
- * @property {Boolean} [nullable=false] - Define if the parameter is nullable. If
- *   set to `true` the parameter `default` is set to `null`.
- * @property {Boolean} [event=false] - Define if the parameter is a volatile, e.g.
- *   set its value back to `null` after propagation. When `true`, `nullable` is
- *   automatically set to `true` and `default` to `null`.
- * @property {Boolean} [filterChange=true] - Setting this option to `false` forces
- *   the propagation of a parameter even when its value do not change. It
- *   offers a kind of middle ground between the default bahavior (e.g. where
- *   only changed values are propagated) and the behavior of the `event` option
- *   (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 `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
- *   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
- *
- * @property {String} type='integer' - Define a boolean parameter.
- * @property {Mixed} default - Default value of the parameter.
- * @property {Number} [min=-Infinity] - Minimum value of the parameter.
- * @property {Number} [max=+Infinity] - Maximum value of the parameter.
- * @property {Boolean} [nullable=false] - Define if the parameter is nullable. If
- *   set to `true` the parameter `default` is set to `null`.
- * @property {Boolean} [event=false] - Define if the parameter is a volatile, e.g.
- *   set its value back to `null` after propagation. When `true`, `nullable` is
- *   automatically set to `true` and `default` to `null`.
- * @property {Boolean} [filterChange=true] - Setting this option to `false` forces
- *   the propagation of a parameter even when its value do not change. It
- *   offers a kind of middle ground between the default bahavior (e.g. where
- *   only changed values are propagated) and the behavior of the `event` option
- *   (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 `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
- *   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
- *
- * @property {String} [type='float'] - Float parameter.
- * @property {Mixed} default - Default value.
- * @property {Number} [min=-Infinity] - Minimum value.
- * @property {Number} [max=+Infinity] - Maximum value.
- * @property {Boolean} [nullable=false] - Define if the parameter is nullable. If
- *   set to `true` the parameter `default` is set to `null`.
- * @property {Boolean} [event=false] - Define if the parameter is a volatile, e.g.
- *   set its value back to `null` after propagation. When `true`, `nullable` is
- *   automatically set to `true` and `default` to `null`.
- * @property {Boolean} [filterChange=true] - Setting this option to `false` forces
- *   the propagation of a parameter even when its value do not change. It
- *   offers a kind of middle ground between the default bahavior (e.g. where
- *   only changed values are propagated) and the behavior of the `event` option
- *   (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 `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
- *   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
- *
- * @property {String} [type='enum'] - Enum parameter.
- * @property {Mixed} default - Default value of the parameter.
- * @property {Array} list - Possible values of the parameter.
- * @property {Boolean} [nullable=false] - Define if the parameter is nullable. If
- *   set to `true` the parameter `default` is set to `null`.
- * @property {Boolean} [event=false] - Define if the parameter is a volatile, e.g.
- *   set its value back to `null` after propagation. When `true`, `nullable` is
- *   automatically set to `true` and `default` to `null`.
- * @property {Boolean} [filterChange=true] - Setting this option to `false` forces
- *   the propagation of a parameter even when its value do not change. It
- *   offers a kind of middle ground between the default bahavior (e.g. where
- *   only changed values are propagated) and the behavior of the `event` option
- *   (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 `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
- *   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
- *
- * Note that the `any` type always return a shallow copy of the state internal
- * value. Mutating the returned value will not modify the internal state.
- *
- * @property {String} [type='any'] - Parameter of any type.
- * @property {Mixed} default - Default value of the parameter.
- * @property {Boolean} [nullable=false] - Define if the parameter is nullable. If
- *   set to `true` the parameter `default` is set to `null`.
- * @property {Boolean} [event=false] - Define if the parameter is a volatile, e.g.
- *   set its value back to `null` after propagation. When `true`, `nullable` is
- *   automatically set to `true` and `default` to `null`.
- * @property {Boolean} [filterChange=true] - Setting this option to `false` forces
- *   the propagation of a parameter even when its value do not change. It
- *   offers a kind of middle ground between the default bahavior (e.g. where
- *   only changed values are propagated) and the behavior of the `event` option
- *   (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 `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
- *   will be called again on when the "real" / final value will be received.
- * @property {Object} [metas={}] - Optionnal metadata of the parameter.
- */
-
 export const sharedOptions = {
   nullable: false,
   event: false, // if event=true, nullable=true
@@ -206,7 +17,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'boolean') {
-        throw new TypeError(`[stateManager] Invalid value for boolean param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for boolean parameter "${name}"`);
       }
 
       return value;
@@ -219,7 +30,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'string') {
-        throw new TypeError(`[stateManager] Invalid value for string param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for string parameter "${name}"`);
       }
 
       return value;
@@ -252,7 +63,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (!(typeof value === 'number' && Math.floor(value) === value)) {
-        throw new TypeError(`[stateManager] Invalid value for integer param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for integer parameter "${name}"`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
@@ -285,7 +96,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'number' || value !== value) { // reject NaN
-        throw new TypeError(`[stateManager] Invalid value for float param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for float parameter "${name}"`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
@@ -298,7 +109,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (def.list.indexOf(value) === -1) {
-        throw new TypeError(`[stateManager] Invalid value for enum param "${name}": ${value}`);
+        throw new TypeError(`[SharedState] Invalid value "${value}" for enum parameter "${name}"`);
       }
 
 
@@ -328,11 +139,11 @@ class ParameterBag {
       const def = schema[name];
 
       if (!Object.prototype.hasOwnProperty.call(def, 'type')) {
-        throw new TypeError(`[stateManager] Invalid schema definition - param "${name}": "type" key is required`);
+        throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}": "type" key is required`);
       }
 
       if (!Object.prototype.hasOwnProperty.call(types, def.type)) {
-        throw new TypeError(`[stateManager] Invalid schema definition - param "${name}": "{ type: '${def.type}' }" does not exists`);
+        throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}": "{ type: '${def.type}' }" does not exists`);
       }
 
       const required = types[def.type].required;
@@ -341,7 +152,7 @@ class ParameterBag {
         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`);
+          throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}" (type "${def.type}"): "${key}" key is required`);
         }
       });
     }
@@ -349,7 +160,7 @@ class ParameterBag {
 
   constructor(schema, initValues = {}) {
     if (!schema) {
-      throw new Error(`[stateManager] schema is mandatory`);
+      throw new Error(`[ParameterBag] schema is mandatory`);
     }
 
     schema = cloneDeep(schema);
@@ -382,7 +193,7 @@ class ParameterBag {
     // 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}"`);
+        throw new ReferenceError(`[StateManager.create] init value defined for undefined param "${name}"`);
       }
     }
 
@@ -422,7 +233,7 @@ class ParameterBag {
   /**
    * Define if the parameter exists.
    *
-   * @param {String} name - Name of the parameter.
+   * @param {string} name - Name of the parameter.
    * @return {Boolean}
    */
   has(name) {
@@ -430,9 +241,10 @@ class ParameterBag {
   }
 
   /**
-   * Return values of all parameters as a flat object.
+   * Return values of all parameters as a flat object. If a parameter is of `any`
+   * type, a deep copy is made.
    *
-   * @return {Object}
+   * @return {object}
    */
   getValues() {
     let values = {};
@@ -444,19 +256,40 @@ class ParameterBag {
     return values;
   }
 
+  /**
+   * Return values of all parameters as a flat object. 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}
+   */
+  getValuesUnsafe() {
+    let values = {};
+
+    for (let name in this._values) {
+      values[name] = this.getUnsafe(name);
+    }
+
+    return values;
+  }
+
   /**
    * Return the value of the given parameter. If the parameter is of `any` type,
    * a deep copy is returned.
    *
-   * @param {String} name - Name of the parameter.
+   * @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}"`);
+      throw new ReferenceError(`[SharedState] Cannot get value of undefined parameter "${name}"`);
     }
 
     if (this._schema[name].type === 'any') {
+      // we return a deep copy of the object as we don't want the client code to
+      // be able to modify our underlying data.
       return cloneDeep(this._values[name]);
     } else {
       return this._values[name];
@@ -464,35 +297,72 @@ class ParameterBag {
   }
 
   /**
-   * 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
-   * callbacks are registered.
+   * 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 parameter.
+   * @return {Mixed} - Value of the parameter.
+   */
+  getUnsafe(name) {
+    if (!this.has(name)) {
+      throw new ReferenceError(`[SharedState] Cannot get value of undefined parameter "${name}"`);
+    }
+
+    return this._values[name];
+  }
+
+  /**
+   * Check that the value is valid according to the schema and return it coerced
+   * to the schema definition
    *
    * @param {String} name - Name of the parameter.
    * @param {Mixed} value - Value of the parameter.
-   * @param {Boolean} [forcePropagation=false] - if true, propagate value even
-   *    if the value has not changed.
-   * @return {Array} - [new value, updated flag].
    */
-  set(name, value) {
+  coerceValue(name, value) {
     if (!this.has(name)) {
-      throw new ReferenceError(`[stateManager] Cannot set value of undefined parameter "${name}"`);
+      throw new ReferenceError(`[SharedState] Cannot set value of undefined parameter "${name}"`);
     }
 
     const def = this._schema[name];
-    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`);
+      throw new TypeError(`[SharedState] Invalid value for ${def.type} param "${name}": value is null and param is not nullable`);
     } else if (value === null && def.nullable === true) {
       value = null;
     } else {
+      const { coerceFunction } = types[def.type];
       value = coerceFunction(name, def, value);
     }
 
+    return value;
+  }
+
+  /**
+   * 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
+   * callbacks are registered.
+   *
+   * @param {string} name - Name of the parameter.
+   * @param {Mixed} value - Value of the parameter.
+   * @return {Array} - [new value, updated flag].
+   */
+  set(name, value) {
+    value = this.coerceValue(name, value);
     const currentValue = this._values[name];
     const updated = !equal(currentValue, value);
 
+    // we store a deep copy of the object as we don't want the client to be able
+    // to modify our underlying data, which leads to unexpected behavior where the
+    // deep equal check to returns true, and therefore the update is not triggered.
+    // @see tests/common.state-manager.spec.js
+    // 'should copy stored value for "any" type to have a predictable behavior'
+    if (this._schema[name].type === 'any') {
+      value = cloneDeep(value);
+    }
+
     this._values[name] = value;
 
     // return tuple so that the state manager can handle the `filterChange` option
@@ -504,7 +374,7 @@ class ParameterBag {
    * @note - prefer `state.set(state.getInitValues())`
    *         or     `state.set(state.getDefaultValues())`
    *
-   * @param {String} [name=null] - Name of the parameter to reset.
+   * @param {string} [name=null] - Name of the parameter to reset.
    */
   // reset(name = null) {
   //   if (name !== null) {
@@ -519,14 +389,14 @@ class ParameterBag {
   /**
    * Return the given schema along with the initialization values.
    *
-   * @return {Object}
+   * @return {object}
    */
   getSchema(name = null) {
     if (name === null) {
       return this._schema;
     } else {
       if (!this.has(name)) {
-        throw new ReferenceError(`[stateManager] Cannot get schema description of undefined parameter "${name}"`);
+        throw new ReferenceError(`[SharedState] Cannot get schema description of undefined parameter "${name}"`);
       }
 
       return this._schema[name];

package/src/common/promise-store.js

@@ -1,4 +1,4 @@
-import { idGenerator } from './utils.js';
+import { idGenerator } from '@ircam/sc-utils';
 
 const generateRequestId = idGenerator();
 const requestPromises = new Map();

package/src/server/Client.js

@@ -1,7 +1,6 @@
+import { idGenerator } from '@ircam/sc-utils';
 import { v4 as uuid } from 'uuid';
 
-import { idGenerator } from '../common/utils.js';
-
 const generateId = idGenerator();
 
 /**
@@ -44,6 +43,12 @@ class Client {
      * @type {server.Socket}
      */
     this.socket = socket;
+
+    /**
+     * Is set in server._onSocketConnection
+     * @private
+     */
+    this.token = null;
   }
 }