@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/src/common/BatchedTransport.js

@@ -0,0 +1,73 @@
+import { BATCHED_TRANSPORT_CHANNEL } from './constants.js';
+
+/**
+ * This class proxies transports given the SharedStateManager to batch messages
+ *
+ * @param {number} [options.wait=0] - Wait for given number of milliseconds
+ *  for stacking messages before emitting on the network. If 0 is given, network
+ *  message is emitted on next microtask
+ * @private
+ */
+class BatchedTransport {
+  #transport = null;
+  #listeners = new Map();
+  #stack = [];
+  #sending = false;
+
+  constructor(transport) {
+    this.#transport = transport;
+
+    this.#transport.addListener(BATCHED_TRANSPORT_CHANNEL, stack => {
+      stack.forEach(entry => {
+        const [channel, args] = entry;
+        // server side the transport is the same EventEmitter instance
+        // for both state manager server and client, so channel might not exist
+        // one side or the other.
+        if (this.#listeners.has(channel)) {
+          const callbacks = this.#listeners.get(channel);
+          callbacks.forEach(callback => callback(...args));
+        }
+      });
+    });
+  }
+
+  addListener(channel, callback) {
+    if (!this.#listeners.has(channel)) {
+      this.#listeners.set(channel, new Set());
+    }
+
+    const callbacks = this.#listeners.get(channel);
+    callbacks.add(callback);
+  }
+
+  async emit(channel, ...args) {
+    this.#stack.push([channel, args]);
+
+    if (!this.#sending) {
+      this.#sending = true;
+      await false;
+      this.#sending = false;
+      const stack = this.#stack;
+      this.#stack = [];
+      this.#transport.emit(BATCHED_TRANSPORT_CHANNEL, stack);
+    }
+  }
+
+  removeListener(channel, callback) {
+    if (!this.#listeners.has(channel)) {
+      const callbacks = this.#listeners.get(channel);
+      callbacks.delete(callback);
+    }
+  }
+
+  removeAllListeners(channel = null) {
+    if (channel === null) {
+      this.#listeners.clear();
+    } else if (this.#listeners.has(channel)) {
+      const callbacks = this.#listeners.get(channel);
+      callbacks.clear();
+    }
+  }
+}
+
+export default BatchedTransport;

package/src/common/ParameterBag.js

@@ -1,9 +1,14 @@
-import cloneDeep from 'lodash.clonedeep';
+import cloneDeep from 'lodash/cloneDeep.js';
 import equal from 'fast-deep-equal';
 
+import {
+  isPlainObject,
+} from '@ircam/sc-utils';
+
 export const sharedOptions = {
   nullable: false,
   event: false, // if event=true, nullable=true
+  required: false, // if required=true, value si required in initialization values
   metas: {},
   filterChange: true,
   immediate: false,
@@ -17,7 +22,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'boolean') {
-        throw new TypeError(`[SharedState] Invalid value "${value}" for boolean parameter "${name}"`);
+        throw new TypeError(`Invalid value (${value}) for boolean parameter '${name}'`);
       }
 
       return value;
@@ -30,7 +35,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'string') {
-        throw new TypeError(`[SharedState] Invalid value "${value}" for string parameter "${name}"`);
+        throw new TypeError(`Invalid value (${value}) for string parameter '${name}'`);
       }
 
       return value;
@@ -44,9 +49,9 @@ export const types = {
         max: +Infinity,
       });
     },
-    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
+    sanitizeDescription: (def) => {
+      // sanitize `null` values in received description, this prevent a bug when
+      // `min` and `max` are explicitly set to `±Infinity`, the description is stringified
       // when sent over the network and therefore Infinity is transformed to `null`
       //
       // JSON.parse({ a: Infinity });
@@ -63,7 +68,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (!(typeof value === 'number' && Math.floor(value) === value)) {
-        throw new TypeError(`[SharedState] Invalid value "${value}" for integer parameter "${name}"`);
+        throw new TypeError(`Invalid value (${value}) for integer parameter '${name}'`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
@@ -77,9 +82,9 @@ export const types = {
         max: +Infinity,
       });
     },
-    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
+    sanitizeDescription: (def) => {
+      // sanitize `null` values in received description, this prevent a bug when
+      // `min` and `max` are explicitly set to `±Infinity`, the description is stringified
       // when sent over the network and therefore Infinity is transformed to `null`
       //
       // JSON.parse({ a: Infinity });
@@ -96,7 +101,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (typeof value !== 'number' || value !== value) { // reject NaN
-        throw new TypeError(`[SharedState] Invalid value "${value}" for float parameter "${name}"`);
+        throw new TypeError(`Invalid value (${value}) for float parameter '${name}'`);
       }
 
       return Math.max(def.min, Math.min(def.max, value));
@@ -109,7 +114,7 @@ export const types = {
     },
     coerceFunction: (name, def, value) => {
       if (def.list.indexOf(value) === -1) {
-        throw new TypeError(`[SharedState] Invalid value "${value}" for enum parameter "${name}"`);
+        throw new TypeError(`Invalid value (${value}) for enum parameter '${name}'`);
       }
 
 
@@ -129,77 +134,60 @@ export const types = {
 };
 
 
-/**
- * Bag of parameters.
- * @private
- */
+/** @private */
 class ParameterBag {
-  static validateSchema(schema) {
-    for (let name in schema) {
-      const def = schema[name];
+  static validateDescription(description) {
+    for (let name in description) {
+      const def = description[name];
 
       if (!Object.prototype.hasOwnProperty.call(def, 'type')) {
-        throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}": "type" key is required`);
+        throw new TypeError(`Invalid ParameterDescription for param '${name}': 'type' key is required`);
       }
 
       if (!Object.prototype.hasOwnProperty.call(types, def.type)) {
-        throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}": "{ type: '${def.type}' }" does not exists`);
+        throw new TypeError(`Invalid ParameterDescription for param '${name}': type '${def.type}' is not a valid type`);
       }
 
       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 || def.required === true) && key === 'default') {
+          // do nothing:
+          // - default is always null for `event` params
+          // - default is always null for `required` params
+          if ('default' in def && def.default !== null) {
+            throw new TypeError(`Invalid ParameterDescription for param ${name}: 'default' property is set and not null while the parameter definition is declared as 'event' or 'required'`);
+          }
         } else if (!Object.prototype.hasOwnProperty.call(def, key)) {
-          throw new TypeError(`[StateManager.registerSchema] Invalid schema definition - param "${name}" (type "${def.type}"): "${key}" key is required`);
+          throw new TypeError(`Invalid ParameterDescription for param "${name}"; property '${key}' key is required`);
         }
       });
     }
   }
 
-  constructor(schema, initValues = {}) {
-    if (!schema) {
-      throw new Error(`[ParameterBag] schema is mandatory`);
+  #description = {};
+  #values = {};
+
+  constructor(description, initValues = {}) {
+    if (!isPlainObject(description)) {
+      throw new TypeError(`Cannot construct ParameterBag: argument 1 must be an object`);
     }
 
-    schema = cloneDeep(schema);
+    description = cloneDeep(description);
     initValues = cloneDeep(initValues);
 
-    /**
-     * List of parameters.
-     *
-     * @type {Object<String, Param>}
-     * @name _params
-     * @memberof ParameterBag
-     * @instance
-     * @private
-     */
-    this._values = {};
-
-    /**
-     * List of schema with init values.
-     *
-     * @type {Object<String, paramDefinition>}
-     * @name _schema
-     * @memberof ParameterBag
-     * @instance
-     * @private
-     */
-    this._schema = {};
-
-    ParameterBag.validateSchema(schema);
-
-    // make shure initValues make sens according to the given schema
+    ParameterBag.validateDescription(description);
+
+    // make sure initValues make sens according to the given description
     for (let name in initValues) {
-      if (!Object.prototype.hasOwnProperty.call(schema, name)) {
-        throw new ReferenceError(`[StateManager.create] init value defined for undefined param "${name}"`);
+      if (!Object.prototype.hasOwnProperty.call(description, name)) {
+        throw new ReferenceError(`Invalid init value for parameter '${name}': Parameter does not exists`);
       }
     }
 
-    for (let [name, def] of Object.entries(schema)) {
-      if (types[def.type].sanitizeSchema) {
-        def = types[def.type].sanitizeSchema(def);
+    for (let [name, def] of Object.entries(description)) {
+      if (types[def.type].sanitizeDescription) {
+        def = types[def.type].sanitizeDescription(def);
       }
 
       const { defaultOptions } = types[def.type];
@@ -211,6 +199,15 @@ class ParameterBag {
         def.default = null;
       }
 
+      if (def.required === true) {
+        // throw if value is not given in init values
+        if (initValues[name] === undefined || initValues[name] === null) {
+          throw new TypeError(`Invalid init value for required param "${name}": Init value must be defined`);
+        }
+
+        def.default = initValues[name];
+      }
+
       let initValue;
 
       if (Object.prototype.hasOwnProperty.call(initValues, name)) {
@@ -220,13 +217,12 @@ class ParameterBag {
       }
 
 
-      this._schema[name] = def;
+      this.#description[name] = def;
       // coerce init value and store in definition
       initValue = this.set(name, initValue)[0];
 
-      this._schema[name].initValue = initValue;
-      this._values[name] = initValue;
-
+      this.#description[name].initValue = initValue;
+      this.#values[name] = initValue;
     }
   }
 
@@ -237,7 +233,7 @@ class ParameterBag {
    * @return {Boolean}
    */
   has(name) {
-    return Object.prototype.hasOwnProperty.call(this._schema, name);
+    return Object.prototype.hasOwnProperty.call(this.#description, name);
   }
 
   /**
@@ -249,7 +245,7 @@ class ParameterBag {
   getValues() {
     let values = {};
 
-    for (let name in this._values) {
+    for (let name in this.#values) {
       values[name] = this.get(name);
     }
 
@@ -259,7 +255,7 @@ class ParameterBag {
   /**
    * 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
+   * useful 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.
    *
@@ -268,7 +264,7 @@ class ParameterBag {
   getValuesUnsafe() {
     let values = {};
 
-    for (let name in this._values) {
+    for (let name in this.#values) {
       values[name] = this.getUnsafe(name);
     }
 
@@ -284,21 +280,21 @@ class ParameterBag {
    */
   get(name) {
     if (!this.has(name)) {
-      throw new ReferenceError(`[SharedState] Cannot get value of undefined parameter "${name}"`);
+      throw new ReferenceError(`Cannot get value of undefined parameter '${name}'`);
     }
 
-    if (this._schema[name].type === 'any') {
+    if (this.#description[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]);
+      return cloneDeep(this.#values[name]);
     } else {
-      return this._values[name];
+      return this.#values[name];
     }
   }
 
   /**
    * 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
+   * `any` type. May be useful 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.
@@ -308,28 +304,27 @@ class ParameterBag {
    */
   getUnsafe(name) {
     if (!this.has(name)) {
-      throw new ReferenceError(`[SharedState] Cannot get value of undefined parameter "${name}"`);
+      throw new ReferenceError(`Cannot get value of undefined parameter '${name}'`);
     }
 
-    return this._values[name];
+    return this.#values[name];
   }
 
   /**
-   * Check that the value is valid according to the schema and return it coerced
-   * to the schema definition
+   * Check that the value is valid according to the class definition and return it coerced.
    *
    * @param {String} name - Name of the parameter.
    * @param {Mixed} value - Value of the parameter.
    */
   coerceValue(name, value) {
     if (!this.has(name)) {
-      throw new ReferenceError(`[SharedState] Cannot set value of undefined parameter "${name}"`);
+      throw new ReferenceError(`Cannot set value of undefined parameter "${name}"`);
     }
 
-    const def = this._schema[name];
+    const def = this.#description[name];
 
     if (value === null && def.nullable === false) {
-      throw new TypeError(`[SharedState] Invalid value for ${def.type} param "${name}": value is null and param is not nullable`);
+      throw new TypeError(`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 {
@@ -351,7 +346,7 @@ class ParameterBag {
    */
   set(name, value) {
     value = this.coerceValue(name, value);
-    const currentValue = this._values[name];
+    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
@@ -359,11 +354,11 @@ class ParameterBag {
     // 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') {
+    if (this.#description[name].type === 'any') {
       value = cloneDeep(value);
     }
 
-    this._values[name] = value;
+    this.#values[name] = value;
 
     // return tuple so that the state manager can handle the `filterChange` option
     return [value, updated];
@@ -387,37 +382,39 @@ class ParameterBag {
   // }
 
   /**
-   * Return the given schema along with the initialization values.
-   *
    * @return {object}
    */
-  getSchema(name = null) {
+  getDescription(name = null) {
     if (name === null) {
-      return this._schema;
-    } else {
-      if (!this.has(name)) {
-        throw new ReferenceError(`[SharedState] Cannot get schema description of undefined parameter "${name}"`);
-      }
+      return this.#description;
+    }
 
-      return this._schema[name];
+    if (!this.has(name)) {
+      throw new ReferenceError(`Cannot get description of undefined parameter "${name}"`);
     }
+
+    return this.#description[name];
   }
 
   // return the default value, if initValue has been given, return init values
   getInitValues() {
     const initValues = {};
-    for (let [name, def] of Object.entries(this._schema)) {
+
+    for (let [name, def] of Object.entries(this.#description)) {
       initValues[name] = def.initValue;
     }
+
     return initValues;
   }
 
   // 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;
+
+    for (let [name, def] of Object.entries(this.#description)) {
+      defaults[name] = def.default;
     }
+
     return defaults;
   }
 }

package/src/common/PromiseStore.js

@@ -0,0 +1,54 @@
+import { idGenerator } from '@ircam/sc-utils';
+
+/** @private */
+export default class PromiseStore {
+  constructor(name) {
+    this.name = name;
+    this.store = new Map();
+    this.generateRequestId = idGenerator();
+  }
+
+  add(resolve, reject, type, localParams) {
+    const reqId = this.generateRequestId.next().value;
+    this.store.set(reqId, { resolve, reject, type, localParams });
+
+    return reqId;
+  }
+
+  resolve(reqId, data) {
+    if (this.store.has(reqId)) {
+      const { resolve, localParams } = this.store.get(reqId);
+      this.store.delete(reqId);
+
+      // re-merge local params into network response
+      if (localParams !== undefined) {
+        Object.assign(data, localParams);
+      }
+
+      resolve(data);
+    } else {
+      throw new ReferenceError(`Cannot resolve request id (${reqId}): id does not exist`);
+    }
+  }
+
+  reject(reqId, msg) {
+    if (this.store.has(reqId)) {
+      const { reject } = this.store.get(reqId);
+      this.store.delete(reqId);
+
+      reject(new Error(msg));
+    } else {
+      throw new ReferenceError(`Cannot resolve request id (${reqId}): id does not exist`);
+    }
+  }
+
+  // reject all pending request
+  flush() {
+    for (let [_reqId, entry] of this.store) {
+      const { reject, type } = entry;
+      reject(new Error(`Discard promise '${type}'`));
+    }
+
+    this.store.clear();
+  }
+}