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

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
@@ -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) {
@@ -432,7 +243,7 @@ class ParameterBag {
   /**
    * Return values of all parameters as a flat object.
    *
-   * @return {Object}
+   * @return {object}
    */
   getValues() {
     let values = {};
@@ -448,7 +259,7 @@ class ParameterBag {
    * 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) {
@@ -468,9 +279,9 @@ class ParameterBag {
    * (aka if previous value is different from new value) all registered
    * callbacks are registered.
    *
-   * @param {String} name - Name of the parameter.
+   * @param {string} name - Name of the parameter.
    * @param {Mixed} value - Value of the parameter.
-   * @param {Boolean} [forcePropagation=false] - if true, propagate value even
+   * @param {boolean} [forcePropagation=false] - if true, propagate value even
    *    if the value has not changed.
    * @return {Array} - [new value, updated flag].
    */
@@ -504,7 +315,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,7 +330,7 @@ class ParameterBag {
   /**
    * Return the given schema along with the initialization values.
    *
-   * @return {Object}
+   * @return {object}
    */
   getSchema(name = null) {
     if (name === null) {

package/src/server/Context.js

@@ -2,44 +2,116 @@ import Client from './Client.js';
 import Server from './Server.js';
 
 /**
- * Base class to extend in order to create the server-side counterpart of
- * a {@link client.Context}. If not defined, a default context will be created
+ * Base class to extend in order to implment the optionnal server-side counterpart
+ * of a {@link client.Context}. If not defined, a default context will be created
  * and used by the server.
  *
+ * In the `soundworks` paradigm, a client has a "role" (e.g. _player_, _controller_)
+ * see {@link client.Client#role}) and can be in different "contexts" (e.g. different
+ * part of the experience such as sections of a music piece, etc.). The
+ * {@link client.Context} and optionnal {@link serverContext} abstractions provide
+ * a simple and unified way to model these reccuring aspects of an application.
+ *
+ * If a `server.Context` is recognized as the server-side counterpart of a
+ * {@link client.Context}, based on their respective `name` (see {@link client.Context#name}
+ * and {@link server.Context#name}), `soundworks` will ensure the logic defined
+ * by the server-side Context will be executed at the beginning of the
+ * {@link client.Client#enter} and {@link client.Client#exit} methods. The example
+ * show how soundwords handles (and guarantees) the order of the `enter()` steps
+ * between the client-side and the server-side parts of the context. The same goes
+ * for the `exit()` method.
+ *
+ * ```
+ * // client-side
+ * import { Context } from '@soundworks/core/client.js';
+ *
+ * class MyContext extends Context {
+ *   async enter() {
+ *     // 1. client side context enter() starts
+ *     //    server-side logic is triggered first
+ *     await super.enter();
+ *     // 4. server-side context enter() is fully done
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 5. client-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instanciate the context (assuming the `client.role` is 'test')
+ * const myContext = new MyContext(client);
+ *
+ * // At some point in the application, the client enters the context trigerring
+ * // the steps 1 to 5 described in the client-side and server-side `enter()`
+ * // implementations. Note that the server-side `enter()` is never called manually.
+ * await myContext.enter();
+ * ```
+ *
+ * ```
+ * // server-side
+ * import { Context } from '@soundworks/core/server.js';
+ *
+ * class MyContext extends Context {
+ *   async enter(client) {
+ *     // 2. server-side context enter() starts
+ *     await super.enter(client);
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 3. server-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instantiate the context
+ * const myContext = new Context(server);
+ * ```
+ *
  * @memberof server
  */
 class Context {
+  /**
+   * @param {client.Client} client - The soundworks client instance.
+   * @param {string|string[]} [roles=[]] - Optionnal list of client roles that can
+   *  use this context. In large applications, this may be usefull to guarantee
+   *  that a context can be consumed only by specific client roles, throwing an
+   *  error if any other client role tries to use it. If empty, no access policy
+   *  will be used.
+   * @throws Will throw if the first argument is not a soundworks server instance.
+   */
   constructor(server, roles = []) {
     if (!(server instanceof Server)) {
       throw new Error(`[soundworks:Context] Invalid argument, context "${this.constructor.name}" should receive a "soundworks.Server" instance as first argument`);
     }
 
-    if (roles === null) {
-      throw new Error('Invalid client types');
-    }
-
     /**
      * soundworks server
      * @type {server.Server}
+     * @readonly
      */
     this.server = server;
 
     /**
      * List of clients that are currently in this context
-     * @type {Client[]}
+     * @type {server.Client[]}
      */
     this.clients = new Set();
 
     /**
      * Status of the context ('idle', 'inited', 'started' or 'errored')
-     * @type {String}
+     * @type {string}
+     * @readonly
      */
     this.status = 'idle';
 
     /**
-     * List of client role associated with this context.
+     * List of client roles that can use this context.
+     * @type {string[]}
+     * @readonly
      */
     roles = Array.isArray(roles) ? roles : [roles];
+
+    if (roles.length === 0) {
+      roles = Object.keys(server.config.app.clients);
+    }
+
     this.roles = new Set(roles);
 
     // register in context manager
@@ -47,32 +119,87 @@ class Context {
   }
 
   /**
-   * Name of the context, default to the class name.
-   * Override the `get name()` getter to use a user-defined context name.
+   * Optionnal user-defined name of the context (defaults to the class name).
+   *
+   * The context manager will match the client-side and server-side contexts based
+   * on this name. If the {@link server.ContextManager} don't find a corresponding
+   * user-defined context with the same name, it will use a default (noop) context.
+   *
+   * @readonly
+   * @type {string}
+   * @example
+   * // server-side and client-side contexts are matched based on their respective `name`
+   * class MyContext extends Context {
+   *   get name() {
+   *     return 'my-user-defined-context-name';
+   *   }
+   * }
    */
   get name() {
     return this.constructor.name;
   }
 
   /**
-   * Method automatically called when the server starts, or lazilly called if
-   * the context is created after `server.start()`
+   * Start the context. This method is lazilly called when a client enters the
+   * context for the first time (cf. ${server.Context#enter}). If you know some
+   * some heavy and/or potentially long job has to be done  when starting the context
+   * (e.g. connect to a database, parsing a long file) it may be a good practice
+   * to call it explicitely.
    *
-   * _WARNING: this method should never be called manually._
+   * This method should be implemented to perform operations that are valid for the
+   * whole lifetime of the context, regardless a client enters or exits the context.
+   *
+   * @example
+   * import { Context } from '@soundworks/core/server.js';
+   *
+   * class MyContext extends Context {
+   *   async start() {
+   *     await super.start();
+   *     await this.doSomeLongJob();
+   *   }
+   * }
+   *
+   * // Instantiate the context
+   * const myContext = new Context(server, ['test']);
+   * // manually start the context to perform the long operation before the first
+   * // client enters the context
+   * await myContext.start();
+   * ```
    */
   async start() {}
 
   /**
-   * Method automatically called when the server stops.
+   * Stop the context. The method that is automatically called when the server
+   * stops. It should be used to cleanup context wise operations made in `start()`
+   * (e.g. disconnect from a database, release a file handle).
    *
    * _WARNING: this method should never be called manually._
    */
   async stop() {}
 
   /**
-   * Method automatically called when the client enters the context.
+   * Enter the context. Implement this method to define the logic that should be
+   * done (e.g. creating a shared state, etc.) when a client enters the context.
+   *
+   * If the context has not been started yet, the `start` method is implicitely executed.
    *
    * _WARNING: this method should never be called manually._
+   *
+   * @param {server.Client} client - Server-side representation of the client
+   *  that enters the context.
+   * @returns {Promise} - Promise that resolves when the context is entered.
+   * @example
+   * class MyContext extends Context {
+   *   async enter(client) {
+   *     await super.enter(client);
+   *     registerTheClientSomewhere(client);
+   *   }
+   *
+   *   async exit(client) {
+   *     await super.exit(client);
+   *     unregisterTheClientSomewhere(client);
+   *   }
+   * }
    */
   async enter(client) {
     if (!(client instanceof Client)) {
@@ -83,9 +210,26 @@ class Context {
   }
 
   /**
-   * Method automatically called when the client exits the context.
+   * Exit the context. Implement this method to define the logic that should be
+   * done (e.g. delete a shared state, etc.) when a client exits the context.
    *
-   * _WARNING: this method should never be called manually._
+   * * _WARNING: this method should never be called manually._
+   *
+   * @param {server.Client} client - Server-side representation of the client
+   *  that exits the context.
+   * @returns {Promise} - Promise that resolves when the context is exited.
+   * @example
+   * class MyContext extends Context {
+   *   async enter(client) {
+   *     await super.enter(client);
+   *     this.state = await this.client.stateManager.create('my-context-state');
+   *   }
+   *
+   *   async exit(client) {
+   *     await super.exit(client);
+   *     await this.state.delete();
+   *   }
+   * }
    */
   async exit(client) {
     if (!(client instanceof Client)) {

package/src/server/ContextManager.js

@@ -57,6 +57,7 @@ class ContextCollection {
  * _WARNING: Most of the time, you should not have to manipulate the context manager directly._
  *
  * @memberof server
+ * @hideconstructor
  */
 class ContextManager {
   /**
@@ -91,10 +92,9 @@ class ContextManager {
   /**
    * Retrieve a started context from its name.
    *
-   * @see {server.Context#name}
-   * @param {String} contextName - Name of the context.
+   * _WARNING: Most of the time, you should not have to call this method manually._
    *
-   * @private
+   * @param {server.Context#name} contextName - Name of the context.
    */
   async get(contextName) {
     if (!this._contexts.has(contextName)) {
@@ -136,9 +136,8 @@ class ContextManager {
       if (!this._contexts.has(contextName)) {
         // create default context for all client types
         const ctor = createNamedContextClass(contextName);
-        const roles = Object.keys(this.server.config.app.clients);
         // this will automatically register the context in the context manager
-        new ctor(this.server, roles);
+        new ctor(this.server);
       }
 
       // we ensure context is started, even lazilly after server.start()

package/src/server/Plugin.js

@@ -14,7 +14,8 @@ import BasePlugin from '../common/BasePlugin.js';
  */
 
 /**
- * Base class to extend in order to create new `soundworks` plugins.
+ * Base class to extend in order to create the server-side counterpart of a
+ * `soundworks` plugin.
  *
  * In the `soundworks` paradigm, a plugin is a component that allows to extend
  * the framework capabilities by encapsulating common and reusable logic in

package/src/server/PluginManager.js

@@ -23,7 +23,7 @@ import Server from './Server.js';
  *
  * Plugins should always be registered both client-side and server-side,
  * and before {@link client.Client#start} or {@link server.Server#start}
- * are called for proper initialization.
+ * to be properly initialized.
  *
  * In some sitautions, you might want to register the same plugin factory several times
  * using different ids (e.g. for watching several parts of the file system, etc.).
@@ -33,12 +33,32 @@ import Server from './Server.js';
  * for more informations on the available plugins.
  *
  * ```
+ * // client-side
+ * import { Client } from '@soundworks/core/client.js';
+ * import syncPlugin from '@soundworks/plugin-sync/client.js';
+ *
+ * const client = new Client(config);
+ * // register the plugin before `client.start()`
+ * client.pluginManager.register('sync', syncPlugin);
+ *
+ * await client.start();
+ *
+ * const sync = await client.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * ```
+ * // server-side
  * import { Server } from '@soundworks/core/server.js';
- * import platformPlugin from '@soundworks/plugin-sync/server.js';
+ * import syncPlugin from '@soundworks/plugin-sync/server.js';
  *
  * const server = new Server(config);
  * // register the plugin before `server.start()`
- * server.pluginManager.register('sync', pluginSync);
+ * server.pluginManager.register('sync', syncPlugin);
  *
  * await server.start();
  *
@@ -86,8 +106,8 @@ class PluginManager extends BasePluginManager {
    * initialization (e.g. to display initialization screen, etc.), you should rely
    * on the `onStateChange` method.
    *
-   * _Note: the async API is designed to enable the dynamic creation of plugins (hopefully
-   * without brealing changes) in a future release._
+   * _Note: the async API is designed to enable the dynamic creation of plugins
+   * (hopefully without brealing changes) in a future release._
    *
    * @param {server.Plugin#id} id - Id of the plugin as defined when registered.
    * @returns {server.Plugin}
@@ -100,7 +120,7 @@ class PluginManager extends BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Cannot get plugin before "server.init()"`);
     }
 
-    return super.getUnsafe(id);
+    return super.unsafeGet(id);
   }
 
   // server only methods