@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/src/client/{Context.js → ClientContext.js}

@@ -1,4 +1,8 @@
 import Client from './Client.js';
+import {
+  kClientContextManagerRegister,
+} from './ClientContextManager.js';
+import PromiseStore from '../common/PromiseStore.js';
 import {
   CONTEXT_ENTER_REQUEST,
   CONTEXT_ENTER_RESPONSE,
@@ -7,19 +11,19 @@ import {
   CONTEXT_EXIT_RESPONSE,
   CONTEXT_EXIT_ERROR,
 } from '../common/constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from '../common/promise-store.js';
+
+export const kClientContextStatus = Symbol('soundworks:client-context-status');
+
+// share between all context, as channels are common to all contexts
+const promiseStore = new PromiseStore('Context');
 
 /**
  * Base class to extend in order to implement a new Context.
  *
  * 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
+ * see {@link Client#role}) and can be in different "contexts" (e.g. different
  * part of the experience such as sections of a music piece, etc.). This class
- * provides a simple and unified way to model these reccuring aspects of an application.
+ * provides a simple and unified way to model these recurring aspects of an application.
  *
  * You can also think of a `Context` as a state of a state machine from which a
  * client can `enter()` or `exit()` (be aware that `soundworks` does not provide
@@ -30,12 +34,12 @@ import {
  * the context. In such case, `soundworks` guarantees that the server-side
  * logic is executed before the `enter()` and `exit()` promises are fulfilled.
  *
- * ```
- * import { Client, Context } from '@soundworks/core/index.js'
+ * ```js
+ * import { Client, ClientContext } from '@soundworks/core/index.js'
  *
  * const client = new Client(config);
  *
- * class MyContext extends Context {
+ * class MyContext extends ClientContext {
  *   async enter() {
  *     await super.enter();
  *     console.log(`client ${this.client.id} entered my context`);
@@ -54,73 +58,78 @@ import {
  * await new Promise(resolve => setTimeout(resolve, 2000));
  * await myContext.exit();
  * ```
- *
- * @memberof client
  */
-class Context {
+class ClientContext {
+  #client = null;
+
   /**
-   * @param {client.Client} client - The soundworks client instance.
+   * @param {Client} client - The soundworks client instance.
    * @throws Will throw if the first argument is not a soundworks client instance.
    */
   constructor(client) {
     if (!(client instanceof Client)) {
-      throw new Error(`[soundworks:Context] Invalid argument, context "${this.name}" should receive a "soundworks.Client" instance as first argument`);
+      throw new TypeError(`Cannot create 'ClientContext' (${this.name}): Argument 1 must be an instance of Client`);
     }
 
-    /**
-     * The soundworks client instance.
-     * @type {client.Client}
-     * @readonly
-     */
-    this.client = client;
-
-    /**
-     * Status of the context, i.e. 'idle', 'inited', 'started', 'errored'
-     * @type {string}
-     * @readonly
-     */
-    this.status = 'idle';
-
-    this.client.socket.addListener(CONTEXT_ENTER_RESPONSE, (reqId, contextName) => {
+    this.#client = client;
+    this[kClientContextStatus] = 'idle';
+
+    this.#client.socket.addListener(CONTEXT_ENTER_RESPONSE, (reqId, contextName) => {
       if (contextName !== this.name) {
         return;
       }
 
-      resolveRequest(reqId);
+      promiseStore.resolve(reqId);
     });
 
-    this.client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
+    this.#client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
       if (contextName !== this.name) {
         return;
       }
 
-      rejectRequest(reqId, msg);
+      promiseStore.reject(reqId, `Cannot execute 'enter' on Context: ${msg}`);
     });
 
-    this.client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
+    this.#client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
       if (contextName !== this.name) {
         return;
       }
 
-      resolveRequest(reqId);
+      promiseStore.resolve(reqId);
     });
 
-    this.client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
+    this.#client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
       if (contextName !== this.name) {
         return;
       }
 
-      rejectRequest(reqId, msg);
+      promiseStore.reject(reqId, `Cannot execute 'exit' on Context: ${msg}`);
     });
 
-    this.client.contextManager.register(this);
+    this.#client.contextManager[kClientContextManagerRegister](this);
+  }
+
+  /**
+   * The soundworks client instance.
+   * @type {Client}
+   */
+  get client() {
+    return this.#client;
+  }
+
+  /**
+   * Status of the context.
+   * @type {'idle'|'inited'|'started'|'errored'}
+   */
+  get status() {
+    return this[kClientContextStatus];
   }
 
   /**
-   * Optionnal user-defined name of the context (defaults to the class name).
+   * Optional 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
+   * on this name. If the {@link ServerContextManager} don't find a corresponding
    * user-defined context with the same name, it will use a default (noop) context.
    *
    * @readonly
@@ -138,10 +147,10 @@ class Context {
   }
 
   /**
-   * Start the context. This method is lazilly called when the client enters the
-   * context for the first time (cf. ${client.Context#enter}). If you know some
+   * Start the context. This method is lazily called when the client enters the
+   * context for the first time (cf. ${ClientContext#enter}). If you know some
    * some heavy and/or potentially long job has to be done  when starting the context
-   * (e.g. call to a web service) it may be a good practice to call it explicitely.
+   * (e.g. call to a web service) it may be a good practice to call it explicitly.
    *
    * This method should be implemented to perform operations that are valid for the
    * whole lifetime of the context, regardless the client enters or exits the context.
@@ -178,12 +187,12 @@ class Context {
    * done (e.g. creating a shared state, etc.) when the context is entered.
    *
    * If a server-side part of the context is defined (i.e. a context with the same
-   * {@link client.Context#name}), the corresponding server-side `enter()` method
+   * {@link ClientContext#name}), the corresponding server-side `enter()` method
    * will be executed before the returned Promise is fulfilled.
    *
-   * If the context has not been started yet, the `start` method is implicitely executed.
+   * If the context has not been started yet, the `start` method is implicitly executed.
    *
-   * @returns {Promise} - Promise that resolves when the context is entered.
+   * @returns {Promise<void>} - Promise that resolves when the context is entered.
    * @example
    * class MyContext extends Context {
    *   async enter() {
@@ -200,14 +209,14 @@ class Context {
   async enter() {
     // lazily start the context if registered after `client.start()`
     if (this.status !== 'started' && this.status !== 'errored') {
-      await this.client.contextManager.get(this.name);
+      await this.#client.contextManager.get(this.name);
     }
 
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
-        this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
+        const reqId = promiseStore.add(resolve, reject, 'ClientContext#enter');
+        this.#client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
     } catch (err) {
       throw new Error(err);
@@ -219,10 +228,10 @@ class Context {
    * done (e.g. delete a shared state, etc.) when the context is exited.
    *
    * If a server-side part of the context is defined (i.e. a context with the same
-   * {@link client.Context#name}), the corresponding server-side `exit()` method
+   * {@link ClientContext#name}), the corresponding server-side `exit()` method
    * will be executed before the returned Promise is fulfilled.
    *
-   * @returns {Promise} - Promise that resolves when the context is exited.
+   * @returns {Promise<void>} - Promise that resolves when the context is exited.
    * @example
    * class MyContext extends Context {
    *   async enter() {
@@ -240,8 +249,8 @@ class Context {
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
-        this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
+        const reqId = promiseStore.add(resolve, reject, 'ClientContext#exit');
+        this.#client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
       });
     } catch (err) {
       throw new Error(err);
@@ -249,4 +258,4 @@ class Context {
   }
 }
 
-export default Context;
+export default ClientContext;

package/src/client/ClientContextManager.js

@@ -0,0 +1,115 @@
+import {
+  kClientContextStatus,
+} from './ClientContext.js';
+
+export const kClientContextManagerStart = Symbol('soundworks:client-context-manager-start');
+export const kClientContextManagerStop = Symbol('soundworks:client-context-manager-stop');
+export const kClientContextManagerRegister = Symbol('soundworks:client-context-manager-register');
+
+/** @private */
+class ContextCollection {
+  #inner = [];
+
+  constructor() {
+    this.#inner = [];
+  }
+
+  add(context) {
+    this.#inner.push(context);
+  }
+
+  has(name) {
+    return this.#inner.find(c => c.name === name) !== undefined;
+  }
+
+  get(name) {
+    return this.#inner.find(c => c.name === name);
+  }
+
+  map(func) {
+    return this.#inner.map(func);
+  }
+}
+
+/**
+ * Manage the different contexts and their lifecycle.
+ *
+ * See {@link Client#contextManager}
+ *
+ * _WARNING: In most cases, you should not have to manipulate the context manager directly._
+ *
+ * @hideconstructor
+ */
+class ClientContextManager {
+  #contexts = new ContextCollection();
+  #contextStartPromises = new Map();
+
+  /**
+   * Register the context into the manager. Is called in context constructor.
+   *
+   * @param {ClientContext} context - The context to be registered.
+   * @private
+   */
+  [kClientContextManagerRegister](context) {
+    if (this.#contexts.has(context.name)) {
+      throw new DOMException(`Cannot register '${context.name}': a Context with same name has already been registered`, 'NotSupportedError');
+    }
+
+    this.#contexts.add(context);
+  }
+
+  /**
+   * Start all registered contexts. Called during `client.start()`
+   * @private
+   */
+  async [kClientContextManagerStart]() {
+    const promises = this.#contexts.map(context => this.get(context.name));
+    await Promise.all(promises);
+  }
+
+  /**
+   * Stop all registered contexts. Called during `client.stop()`
+   * @private
+   */
+  async [kClientContextManagerStop]() {
+    const promises = this.#contexts.map(context => context.stop());
+    await Promise.all(promises);
+  }
+
+  /**
+   * Retrieve a started context from its name.
+   *
+   * _WARNING: Most of the time, you should not have to call this method manually._
+   *
+   * @param {string} contextName - Name of the context.
+   * @returns {Promise<ClientContext>}
+   */
+  async get(contextName) {
+    if (!this.#contexts.has(contextName)) {
+      throw new ReferenceError(`Cannot execute 'get' on ClientContextManager: Context '${contextName}' is not registered`);
+    }
+
+    const context = this.#contexts.get(contextName);
+
+    if (this.#contextStartPromises.has(contextName)) {
+      const startPromise = this.#contextStartPromises.get(contextName);
+      await startPromise;
+    } else {
+      context[kClientContextStatus] = 'inited';
+
+      try {
+        const startPromise = context.start();
+        this.#contextStartPromises.set(contextName, startPromise);
+        await startPromise;
+        context[kClientContextStatus] = 'started';
+      } catch (err) {
+        context[kClientContextStatus] = 'errored';
+        throw new Error(`Cannot execute 'get' on ClientContextManager: ${err.message}`);
+      }
+    }
+
+    return context;
+  }
+}
+
+export default ClientContextManager;

package/src/client/{Plugin.js → ClientPlugin.js}

@@ -3,14 +3,14 @@ import BasePlugin from '../common/BasePlugin.js';
 /**
  * Callback executed when the plugin state is updated.
  *
- * @callback client.Plugin~onStateChangeCallback
- * @param {client.Plugin#state} state - Current state of the plugin.
+ * @callback ClientPlugin~onStateChangeCallback
+ * @param {ClientPlugin#state} state - Current state of the plugin.
  */
 
 /**
- * Delete the registered {@link client.Plugin~onStateChangeCallback}.
+ * Delete the registered {@link ClientPlugin~onStateChangeCallback}.
  *
- * @callback client.Plugin~deleteOnStateChangeCallback
+ * @callback ClientPlugin~deleteOnStateChangeCallback
  */
 
 /**
@@ -24,44 +24,48 @@ import BasePlugin from '../common/BasePlugin.js';
  * have both a client-side and a server-side part.
  *
  * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
- * for more informations on the available plugins.
+ * for more information on the available plugins.
  *
  * _Creating new plugins should be considered an advanced usage._
  *
- * @memberof client
  * @extends BasePlugin
  * @inheritdoc
  */
-class Plugin extends BasePlugin {
+class ClientPlugin extends BasePlugin {
+  #client = null;
   /**
-   * @param {client.Client} client - The soundworks client instance.
+   * @param {Client} client - A soundworks client instance.
    * @param {string} id - User defined id of the plugin as defined in
-   *  {@link client.PluginManager#register}.
+   *  {@link ClientPluginManager#register}.
    */
   constructor(client, id) {
     super(id);
 
-    /**
-     * Instance of soundworks client.
-     *
-     * @type {client.Client}
-     * @see {@link client.Client}
-     */
-    this.client = client;
+    this.#client = client;
+  }
+
+  /**
+   * Instance of soundworks client.
+   *
+   * @type {Client}
+   * @see {@link Client}
+   */
+  get client() {
+    return this.#client;
   }
 
   // @todo
   // /**
   //  * Interface method to implement if specific logic should be done when a
-  //  * {@link client.Client} enters the plugin.
+  //  * {@link Client} enters the plugin.
   //  */
   // async activate() {}
   //
   // /**
   //  * Interface method to implement if specific logic should be done when a
-  //  * {@link client.Client} exists the plugin.
+  //  * {@link Client} exists the plugin.
   //  */
   // async deactivate() {}
 }
 
-export default Plugin;
+export default ClientPlugin;

package/src/client/{PluginManager.js → ClientPluginManager.js}

@@ -1,38 +1,22 @@
 import BasePluginManager from '../common/BasePluginManager.js';
-import Plugin from './Plugin.js';
+import ClientPlugin from './ClientPlugin.js';
 import Client from './Client.js';
 
-/**
- * Callback executed when a plugin internal state is updated.
- *
- * @callback client.PluginManager~onStateChangeCallback
- * @param {object<client.Plugin#id, client.Plugin>} fullState - List of all plugins.
- * @param {client.Plugin|null} initiator - Plugin that initiated the update or `null`
- *  if the change was initiated by the state manager (i.e. when the initialization
- *  of the plugins starts).
- */
-
-/**
- * Delete the registered {@link client.PluginManager~onStateChangeCallback}.
- *
- * @callback client.PluginManager~deleteOnStateChangeCallback
- */
-
 /**
  * The `PluginManager` allows to register and retrieve `soundworks` plugins.
  *
  * Plugins should always be registered both client-side and server-side,
- * and before {@link client.Client#start} or {@link server.Server#start}
+ * and before {@link Client#start} or {@link Server#start}
  * to be properly initialized.
  *
- * In some sitautions, you might want to register the same plugin factory several times
+ * In some situations, 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.).
  *
  * Refer to the plugins' documentation for more precise examples, and the specific API
  * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
- * for more informations on the available plugins.
+ * for more information on the available plugins.
  *
- * See {@link client.Client#pluginManager}
+ * See {@link Client#pluginManager}
  *
  * ```
  * // client-side
@@ -72,28 +56,50 @@ import Client from './Client.js';
  * }, 1000);
  * ```
  *
- * @memberof client
  * @extends BasePluginManager
  * @inheritdoc
- * @hideconstructor
+ * @template T
  */
-class PluginManager extends BasePluginManager {
+class ClientPluginManager extends BasePluginManager {
   /**
-   * @param {client.Client} client - The soundworks client instance.
+   * @param {Client} client - The soundworks client instance.
+   * @hideconstructor
    */
   constructor(client) {
     if (!(client instanceof Client)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client" as argument`);
+      throw new TypeError(`Cannot construct ClientPluginManager: Argument 1 must be an instance of Client`);
     }
 
     super(client);
   }
 
-  register(id, factory, options = {}, deps = []) {
-    const ctor = factory(Plugin);
-
-    if (!(ctor.prototype instanceof Plugin)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" second argument should be a factory function returning a class extending the "Plugin" base class`);
+  /**
+   * Register a plugin into the manager.
+   *
+   * _A plugin must always be registered both on client-side and on server-side_
+   *
+   * Refer to the plugin documentation to check its options and proper way of
+   * registering it.
+   *
+   * @param {string} id - Unique id of the plugin. Enables the registration of the
+   *  same plugin factory under different ids.
+   * @param {T<ClientPlugin>} ctor - The client-side Class of the plugin.
+   * @param {object} [options={}] - Options to configure the plugin.
+   * @param {array} [deps=[]] - List of plugins' names the plugin depends on, i.e.
+   *  the plugin initialization will start only after the plugins it depends on are
+   *  fully started themselves.
+   * @see {@link ClientPluginManager#register}
+   * @see {@link ServerPluginManager#register}
+   * @example
+   * // client-side
+   * client.pluginManager.register('user-defined-id', pluginFactory);
+   * // server-side
+   * server.pluginManager.register('user-defined-id', pluginFactory);
+   */
+  register(id, ctor, options = {}, deps = []) {
+    // Note that other arguments are checked on the BasePluginManager
+    if (!ctor || !(ctor.prototype instanceof ClientPlugin)) {
+      throw new TypeError(`Cannot execute 'register' on ClientPluginManager: argument 2 must be a class that extends 'ClientPlugin'`);
     }
 
     super.register(id, ctor, options, deps);
@@ -112,21 +118,18 @@ class PluginManager extends BasePluginManager {
    * 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._
-   *
-   * @param {client.Plugin#id} id - Id of the plugin as defined when registered.
-   * @returns {client.Plugin}
-   * @see {@link client.PluginManager#onStateChange}
+   * in a future release._
    *
-   * @private
+   * @param {string} id - Id of the plugin as defined when registered.
+   * @returns {Promise<T<ClientPlugin>>}
    */
   async get(id) {
     if (this.status !== 'started') {
-      throw new Error(`[soundworks.PluginManager] Cannot get plugin before "client.init()"`);
+      throw new DOMException(`Cannot execute 'get' on ClientPluginManager: 'Client#init' has not been called yet`, 'NotSupportedError');
     }
 
-    return super.unsafeGet(id);
+    return super.getUnsafe(id);
   }
 }
 
-export default PluginManager;
+export default ClientPluginManager;