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

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 for boolean param "${name}": ${value}`);
       }
 
       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 for string param "${name}": ${value}`);
       }
 
       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 for integer param "${name}": ${value}`);
       }
 
       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 for float param "${name}": ${value}`);
       }
 
       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 for enum param "${name}": ${value}`);
       }
 
 
@@ -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) {
@@ -432,7 +243,7 @@ class ParameterBag {
   /**
    * Return values of all parameters as a flat object.
    *
-   * @return {Object}
+   * @return {object}
    */
   getValues() {
     let values = {};
@@ -448,15 +259,17 @@ 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) {
     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];
@@ -468,22 +281,22 @@ 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].
    */
   set(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 {
@@ -493,6 +306,16 @@ class ParameterBag {
     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 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 +327,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 +342,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/utils.js

@@ -1,3 +1,5 @@
+import isPlainObj from 'is-plain-obj';
+
 // https://stackoverflow.com/questions/17575790/environment-detection-node-js-or-browser
 export const isBrowser = new Function('try {return this===window;}catch(e){ return false;}');
 
@@ -20,3 +22,7 @@ export function isFunction(func) {
     Object.prototype.toString.call(func) == '[object AsyncFunction]';
 }
 
+export function isPlainObject(obj) {
+  return isPlainObj(obj);
+}
+

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()