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

package/src/server/StateManager.js

@@ -5,6 +5,7 @@ import clonedeep from 'lodash.clonedeep';
 import BaseStateManager from '../common/BaseStateManager.js';
 import ParameterBag from '../common/ParameterBag.js';
 import SharedStatePrivate from '../common/SharedStatePrivate.js';
+import { isString, isPlainObject } from '../common/utils.js';
 import {
   SERVER_ID,
   CREATE_REQUEST,
@@ -26,12 +27,224 @@ import { idGenerator } from '../common/utils.js';
 const generateStateId = idGenerator();
 const generateRemoteId = idGenerator();
 
+/**
+ * @typedef {object} server.StateManager~schema
+ *
+ * Description of a schema to be registered by the {@link server.StateManager#registerSchema}
+ *
+ * A schema is the blueprint, or definition from which shared states can be created.
+ *
+ * It consists of a set of key / value pairs where the key is the name of
+ * the parameter, and the value is an object describing the parameter.
+ *
+ * The value can be of any of the foolowing types:
+ * - {@link server.StateManager~schemaBooleanDefinition}
+ * - {@link server.StateManager~schemaStringDefinition}
+ * - {@link server.StateManager~schemaIntegerDefinition}
+ * - {@link server.StateManager~schemaFloatDefinition}
+ * - {@link server.StateManager~schemaEnumDefinition}
+ * - {@link server.StateManager~schemaAnyDefinition}
+ *
+ * @example
+ * const mySchema = {
+ *   triggerSound: {
+ *     type: 'boolean',
+ *     event: true,
+ *   },
+ *   volume: {
+ *     type: 'float'
+ *     default: 0,
+ *     min: -80,
+ *     max: 6,
+ *   }
+ * };
+ *
+ * server.stateManager.registerSchema('my-schema-name', mySchema);
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "boolean" type.
+ *
+ * @typedef {object} server.StateManager~schemaBooleanDefinition
+ * @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.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "string" type.
+ *
+ * @typedef {object} server.StateManager~schemaStringDefinition
+ * @property {string} type='string' - Define a boolean parameter.
+ * @property {string} 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.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "integer" type.
+ *
+ * @typedef {object} server.StateManager~schemaIntegerDefinition
+ * @property {string} type='integer' - Define a boolean parameter.
+ * @property {number} 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.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "float" type.
+ *
+ * @typedef {object} server.StateManager~schemaFloatDefinition
+ * @property {string} [type='float'] - Float parameter.
+ * @property {number} 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.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "enum" type.
+ *
+ * @typedef {object} server.StateManager~schemaEnumDefinition
+ * @property {string} [type='enum'] - Enum parameter.
+ * @property {string} 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.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "any" type.
+ *
+ * Note that the `any` type always return a shallow copy of the state internal
+ * value. Mutating the returned value will therefore not modify the internal state.
+ *
+ * @typedef {object} server.StateManager~schemaAnyDefinition
+ * @property {string} [type='any'] - Parameter of any type.
+ * @property {*} 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.
+ */
+
 /**
  * @callback server.StateManager~ObserveCallback
  * @async
- * @param {String} schemaName - name of the schema
- * @param {Number} stateId - id of the state
- * @param {Number} nodeId - id of the node that created the state
+ * @param {string} schemaName - name of the schema
+ * @param {number} stateId - id of the state
+ * @param {number} nodeId - id of the node that created the state
+ */
+
+/**
+ * @callback server.StateManager~updateHook
+ * @async
+ *
+ * @param {object} updates - Update object as given on a set callback, or
+ *  result of the previous hook
+ * @param {object} currentValues - Current values of the state.
+ * @param {object} [context=null] - Optionnal context passed by the creator
+ *  of the update.
+ *
+ * @return {object} The "real" updates to be applied on the state.
  */
 
 /**
@@ -114,10 +327,10 @@ class StateManager extends BaseStateManager {
    *
    * This is automatically handled by the {@link server.Server} when a client connects.
    *
-   * @param {Number} nodeId - Id of the client node, as given in
+   * @param {number} nodeId - Id of the client node, as given in
    *  {@link client.StateManager}
-   * @param {Object} transport - Tranpsort mecanism to communicate with the
-   *  client. Should implement a basic EventEmitter API.
+   * @param {object} transport - Transport mecanism to communicate with the
+   *  client. Must implement a basic EventEmitter API.
    *
    * @private
    */
@@ -237,7 +450,7 @@ class StateManager extends BaseStateManager {
    *
    * This is automatically handled by the {@link server.Server} when a client disconnects.
    *
-   * @param {Number} nodeId - Id of the client node, as given in
+   * @param {number} nodeId - Id of the client node, as given in
    *  {@link client.StateManager}
    *
    * @private
@@ -280,7 +493,7 @@ class StateManager extends BaseStateManager {
    * Register a schema from which shared states (cf. {@link common.SharedState})
    * can be instanciated.
    *
-   * @param {String} schemaName - Name of the schema.
+   * @param {string} schemaName - Name of the schema.
    * @param {server.StateManager~schema} schema - Data structure
    *  describing the states that will be created from this schema.
    *
@@ -302,10 +515,18 @@ class StateManager extends BaseStateManager {
    * })
    */
   registerSchema(schemaName, schema) {
+    if (!isString(schemaName)) {
+      throw new Error(`[stateManager.registerSchema] Invalid schema name "${schemaName}", should be a string`);
+    }
+
     if (this._schemas.has(schemaName)) {
       throw new Error(`[stateManager.registerSchema] cannot register schema with name: "${schemaName}", schema name already exists`);
     }
 
+    if (!isPlainObject(schema)) {
+      throw new Error(`[stateManager.registerSchema] Invalid schema, should be an object`);
+    }
+
     ParameterBag.validateSchema(schema);
 
     this._schemas.set(schemaName, clonedeep(schema));
@@ -315,11 +536,12 @@ class StateManager extends BaseStateManager {
 
   /**
    * Delete a schema and all associated states.
+   *
    * When a schema is deleted, all states created from this schema are deleted
    * as well, therefore all attached clients are detached and the `onDetach`
    * and `onDelete` callbacks are called on the related states.
    *
-   * @param {String} schemaName - Name of the schema.
+   * @param {string} schemaName - Name of the schema.
    */
   deleteSchema(schemaName) {
     // @note: deleting schema
@@ -344,19 +566,6 @@ class StateManager extends BaseStateManager {
     this._hooksBySchemaName.delete(schemaName);
   }
 
-  /**
-   * @callback server.StateManager~updateHook
-   * @async
-   *
-   * @param {Object} updates - Update object as given on a set callback, or
-   *  result of the previous hook
-   * @param {Object} currentValues - Current values of the state.
-   * @param {Object} [context=null] - Optionnal context passed by the creator
-   *  of the update.
-   *
-   * @return {Object} The "real" updates to be applied on the state.
-   */
-
   /**
    * Register a function for a given schema (e.g. will be applied on all states
    * created from this schema) that will be executed before the update values
@@ -369,7 +578,7 @@ class StateManager extends BaseStateManager {
    * server-side regarless the node on which `set` has been called and before
    * the "actual" update of the state (e.g. before the call of `onUpdate`).
    *
-   * @param {String} schemaName - Kind of states on which applying the hook.
+   * @param {string} schemaName - Kind of states on which applying the hook.
    * @param {server.StateManager~updateHook} updateHook - Function
    *   called between the `set` call and the actual update.
    *
@@ -404,7 +613,6 @@ class StateManager extends BaseStateManager {
 
     return () => hooks.delete(updateHook);
   }
-
 }
 
 export default StateManager;

package/src/server/index.js

@@ -1,23 +1,3 @@
-/**
- * Configuration object for the server.
- *
- * @typedef ServerConfig
- * @memberof server
- * @type {object}
- * @property {object} [app] - Application configration object.
- * @property {object} app.clients - Definition of the application clients.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} [env] - Environment configration object.
- * @property {boolean} env.port - Port on which the server is listening.
- * @property {boolean} env.useHttps - Define is the server run in http or in https.
- * @property {boolean} [env.httpsInfos={}] - Path to cert files for https.
- * @property {boolean} env.serverAddress - Domain name or IP of the server.
- *  Mandatory if node clients are defined
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
-
 /**
  * Server-side part of the *soundworks* framework.
  *