@soundworks/core 4.0.0-alpha.27 → 4.0.0-alpha.29

package/src/common/BasePlugin.js

@@ -1,45 +1,43 @@
 import merge from 'lodash/merge.js';
 
+export const kBasePluginStatus = Symbol('soundworks:base-plugin-status');
+
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback pluginOnStateChangeCallback
+ * @param {BasePlugin#state} state - Current state of the plugin.
+ */
+
 /**
- * @private
+ * Delete the registered {@link pluginOnStateChangeCallback}.
+ *
+ * @callback pluginDeleteOnStateChangeCallback
  */
+
+/** @private */
 class BasePlugin {
+  #id = null;
+  #onStateChangeCallbacks = new Set();
+
   constructor(id) {
+    this.#id = id;
     /** @private */
-    this._id = id;
-    /** @private */
-    this._type = this.constructor.name;
-
-    /**
-     * Options of the plugin.
-     *
-     * @type {object}
-     */
-    this.options = {};
+    this[kBasePluginStatus] = 'idle';
 
     /**
      * Placeholder that stores internal (local) state of the plugin. The state
      * should be modified through the `propagateStateChange` method to ensure
-     * the change to be properly propagated to `onStateChange` callbacks.
+     * the change to be properly propagated to manager `onStateChange` callbacks.
      *
      * @type {object}
      * @protected
-     * @see {@link client.Plugin#onStateChange}
-     * @see {@link server.Plugin#onStateChange}
-     * @see {@link client.Plugin#propagateStateChange}
-     * @see {@link server.Plugin#propagateStateChange}
+     * @see {@link ClientPlugin#onStateChange}
+     * @see {@link ServerPlugin#onStateChange}
+     * @see {@link ClientPlugin#propagateStateChange}
+     * @see {@link ServerPlugin#propagateStateChange}
      */
     this.state = {};
-
-    /**
-     * Current status of the plugin, i.e. 'idle', 'inited', 'started', 'errored'
-     *
-     * @type {string}
-     */
-    this.status = 'idle';
-
-    /** @private */
-    this._onStateChangeCallbacks = new Set();
   }
 
   /**
@@ -47,11 +45,11 @@ class BasePlugin {
    *
    * @type {string}
    * @readonly
-   * @see {@link client.PluginManager#register}
-   * @see {@link server.PluginManager#register}
+   * @see {@link ClientPluginManager#register}
+   * @see {@link ServerPluginManager#register}
    */
   get id() {
-    return this._id;
+    return this.#id;
   }
 
   /**
@@ -65,18 +63,28 @@ class BasePlugin {
    * @readonly
    */
   get type() {
-    return this._type;
+    return this.constructor.name;
+  }
+
+  /**
+   * Current status of the plugin.
+   *
+   * @type {'idle'|'inited'|'started'|'errored'}
+   */
+  get status() {
+    return this[kBasePluginStatus];
   }
 
   /**
-   * Start the plugin. This method is automatically called during the client or
-   * server `init()` lifecyle step. After `start()` is fulfilled the plugin should
-   * be ready to use.
+   * Start the plugin.
+   *
+   * This method is automatically called during the client or server `init()` lifecyle
+   * step. After `start()` is fulfilled the plugin should be ready to use.
    *
    * @example
    * // server-side couterpart of a plugin that creates a dedicated global shared
    * // state on which the server-side part can attach.
-   * class MyPlugin extends Plugin {
+   * class MyPlugin extends ServerPlugin {
    *   constructor(server, id) {
    *     super(server, id);
    *
@@ -102,13 +110,14 @@ class BasePlugin {
   async start() {}
 
   /**
-   * Stop the plugin. This method is automatically called during the client or server
-   * `stop()` lifecyle step.
+   * Stop the plugin.
+   *
+   * This method is automatically called during the client or server `stop()` lifecyle step.
    *
    * @example
    * // server-side couterpart of a plugin that creates a dedicated global shared
-   * // state on which the server-side part can attach.
-   * class MyPlugin extends Plugin {
+   * // state on which the client-side part can attach.
+   * class MyPlugin extends ServerPlugin {
    *   constructor(server, id) {
    *     super(server, id);
    *
@@ -137,20 +146,17 @@ class BasePlugin {
   /**
    * Listen to the state changes propagated by {@link BasePlugin.propagateStateChange}
    *
-   * @param {client.Plugin~onStateChangeCallback|server.Plugin~onStateChangeCallback} callback -
-   *  Callback to execute when a state change is propagated.
-   * @returns {client.Plugin~deleteOnStateChangeCallback|server.Plugin~deleteOnStateChangeCallback}
-   *  Execute the function to delete the listener from the callback list.
-   * @see {@link client.Plugin#propagateStateChange}
-   * @see {@link server.Plugin#propagateStateChange}
+   * @param {pluginOnStateChangeCallback} callback - Callback to execute when a state change is propagated.
+   * @returns {pluginDeleteOnStateChangeCallback}
+   *
    * @example
    * const unsubscribe = plugin.onStateChange(pluginState => console.log(pluginState));
    * // stop listening state changes
    * unsubscribe();
    */
   onStateChange(callback) {
-    this._onStateChangeCallbacks.add(callback);
-    return () => this._onStateChangeCallbacks.delete(callback);
+    this.#onStateChangeCallbacks.add(callback);
+    return () => this.#onStateChangeCallbacks.delete(callback);
   }
 
   /**
@@ -159,14 +165,13 @@ class BasePlugin {
    * through the `PluginManager#onStateChange` listeners.
    *
    * @param {object} updates - Updates to be merged in the plugin state.
-   * @see {@link client.Plugin#onStateChange}
-   * @see {@link server.Plugin#onStateChange}
-   * @see {@link client.PluginManager#onStateChange}
-   * @see {@link server.PluginManager#onStateChange}
+   *
+   * @see {@link BasePlugin#onStateChange}
+   * @see {@link BasePluginManager#onStateChange}
    */
   propagateStateChange(updates) {
     merge(this.state, updates);
-    this._onStateChangeCallbacks.forEach(callback => callback(this.state));
+    this.#onStateChangeCallbacks.forEach(callback => callback(this.state));
   }
 }
 

package/src/common/BasePluginManager.js

@@ -1,157 +1,135 @@
 import { isPlainObject, isString } from '@ircam/sc-utils';
 
+import {
+  kBasePluginStatus,
+} from './BasePlugin.js';
+
 import logger from './logger.js';
 
+export const kPluginManagerStart = Symbol('soundworks:plugin-manager-start');
+export const kPluginManagerStop = Symbol('soundworks:plugin-manager-stop');
+export const kPluginManagerInstances = Symbol('soundworks:plugin-manager-instances');
+
 /**
- * Shared functionnality between server-side and client-size plugin manager
+ * Callback executed when a plugin internal state is updated.
  *
- * @private
+ * @callback pluginManagerOnStateChangeCallback
+ * @param {object<string, ClientPlugin|ServerPlugin>} fullState - List of all plugins.
+ * @param {ClientPlugin|ServerPlugin|null} initiator - Plugin that initiated the
+ *  update. The value is `null` if the change was initiated by the state manager
+ *  (e.g. when the initialization of the plugins starts).
  */
-class BasePluginManager {
-  constructor(node) {
-    // node may be either a soundworks server or a soundworks client
-    /** @private */
-    this._node = node;
-    /** @private */
-    this._dependencies = new Map();
-    /** @private */
-    this._instances = new Map();
-    /** @private */
-    this._instanceStartPromises = new Map();
-    /** @private */
-    this._onStateChangeCallbacks = new Set();
-
-    this.status = 'idle';
-  }
 
-  /**
-   * Register a plugin into soundworks.
-   *
-   * _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 {Function} factory - Factory function that returns the Plugin class.
-   * @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 client.PluginManager#register}
-   * @see {@link server.PluginManager#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 = []) {
-    // For now we don't allow to register a plugin after `client|server.init()`.
-    // This is subject to change in the future as we may want to dynamically
-    // register new plugins during application lifetime.
-    if (this._node.status === 'inited') {
-      throw new Error(`[soundworks.PluginManager] Cannot register plugin (${id}) after "client.init()"`);
-    }
+/**
+ * Delete the registered {@link pluginManagerOnStateChangeCallback}.
+ *
+ * @callback pluginManagerDeleteOnStateChangeCallback
+ */
 
-    if (!isString(id)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" first argument should be a string`);
-    }
+/** @private */
+class BasePluginManager {
+  // node may be either the server or a client
+  #node = null;
+  #status = 'idle';
+  #dependencies = new Map();
+  #instanceStartPromises = new Map();
+  #onStateChangeCallbacks = new Set();
 
-    if (!isPlainObject(options)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" third optionnal argument should be an object`);
-    }
+  constructor(node) {
+    this.#node = node;
+    /** #private */
+    this[kPluginManagerInstances] = new Map();
+  }
 
-    if (!Array.isArray(deps)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" fourth optionnal argument should be an array`);
-    }
+  #propagateStateChange(instance = null, status = null) {
+    if (instance !== null) {
+      // status is null if we forward some inner state change from the instance
+      if (status !== null) {
+        instance[kBasePluginStatus] = status;
+      }
 
-    if (this._instances.has(id)) {
-      throw new Error(`[soundworks:PluginManager] Plugin "${id}" already registered`);
+      const fullState = Object.fromEntries(this[kPluginManagerInstances]);
+      this.#onStateChangeCallbacks.forEach(callback => callback(fullState, instance));
+    } else {
+      const fullState = Object.fromEntries(this[kPluginManagerInstances]);
+      this.#onStateChangeCallbacks.forEach(callback => callback(fullState, null));
     }
-
-    // we instanciate the plugin here, so that a plugin can register another one
-    // in its own constructor.
-    //
-    // the dependencies must be created first, so that the instance can call
-    // addDependency in its constructor
-    this._dependencies.set(id, deps);
-
-    const instance = new ctor(this._node, id, options);
-    this._instances.set(id, instance);
   }
 
   /**
-   * Manually add a dependency to a given plugin. Usefull to require a plugin
-   * within a plugin
+   * Initialize all registered plugins.
+   *
+   * Executed during the `Client.init()` or `Server.init()` initialization step.
    *
-   */
-  addDependency(pluginId, dependencyId) {
-    const deps = this._dependencies.get(pluginId);
-    deps.push(dependencyId);
-  }
-
-  /**
-   * Returns the list of the registered plugins ids
-   * @returns {string[]}
-   */
-  getRegisteredPlugins() {
-    return Array.from(this._instances.keys());
-  }
-
-  /**
-   * Initialize all the registered plugin. Executed during the `Client.init()` or
-   * `Server.init()` initialization step.
    * @private
    */
-  async start() {
+  async [kPluginManagerStart]() {
     logger.title('starting registered plugins');
 
-    if (this.status !== 'idle') {
+    if (this.#status !== 'idle') {
       throw new Error(`[soundworks:PluginManager] Cannot call "pluginManager.init()" twice`);
     }
 
-    this.status = 'inited';
+    this.#status = 'inited';
     // instanciate all plugins
-    for (let [_id, instance] of this._instances.entries()) {
-      instance.onStateChange(_values => this._propagateStateChange(instance));
+    for (let instance of this[kPluginManagerInstances].values()) {
+      instance.onStateChange(() => this.#propagateStateChange(instance, null));
     }
 
-    // propagate all 'idle' statuses before start
-    this._propagateStateChange();
+    // propagate all 'idle' status before start
+    this.#propagateStateChange(null, null);
 
-    const promises = Array.from(this._instances.keys()).map(id => this.unsafeGet(id));
+    const promises = Array.from(this[kPluginManagerInstances].keys()).map(id => this.getUnsafe(id));
 
     try {
       await Promise.all(promises);
-      this.status = 'started';
+      this.#status = 'started';
     } catch (err) {
-      this.status = 'errored';
+      this.#status = 'errored';
       throw err; // throw initial error
     }
   }
 
   /** @private */
-  async stop() {
-    for (let instance of this._instances.values()) {
+  async [kPluginManagerStop]() {
+    for (let instance of this[kPluginManagerInstances].values()) {
       await instance.stop();
     }
   }
 
   /**
-   * Retrieve an fully started instance of a registered plugin, without checking
-   * that the pluginManager has started. This is required for starting the plugin
-   * manager itself and to require a plugin from within another plugin
+   * Status of the plugin manager
    *
+   * @type {'idle'|'inited'|'started'|'errored'}
+   */
+  get status() {
+    return this.#status;
+  }
+
+  /**
+   * Alias for existing plugins (i.e. plugin-scriptin), remove once updated
    * @private
    */
   async unsafeGet(id) {
+    return this.getUnsafe(id);
+  }
+
+  /**
+   * Retrieve an fully started instance of a registered plugin without checking
+   * that the pluginManager is started.
+   *
+   * This method is required for starting the plugin manager itself and to require
+   * a plugin from within another plugin.
+   *
+   * _Warning: Unless you are developing your own plugins, you should not have to use
+   * this method_
+   */
+  async getUnsafe(id) {
     if (!isString(id)) {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.get(name)" argument should be a string`);
     }
 
-    if (!this._instances.has(id)) {
+    if (!this[kPluginManagerInstances].has(id)) {
       throw new Error(`[soundworks:PluginManager] Cannot get plugin "${id}", plugin is not registered`);
     }
 
@@ -159,48 +137,124 @@ class BasePluginManager {
     // to be able to properly propagate the states. The code bellow should allow
     // to dynamically register and launch plugins at runtime.
     //
-    // if (!this._instances.has(id)) {
-    //   const { ctor, options } = this._dependencies.get(id);
-    //   const instance = new ctor(this._node, id, options);
-    //   this._instances.set(id, instance);
+    // if (!this[kPluginManagerInstances].has(id)) {
+    //   const { ctor, options } = this.#dependencies.get(id);
+    //   const instance = new ctor(this.#node, id, options);
+    //   this[kPluginManagerInstances].set(id, instance);
     // }
 
-    const instance = this._instances.get(id);
+    const instance = this[kPluginManagerInstances].get(id);
 
     // recursively get the dependency chain
-    const deps = this._dependencies.get(id);
-    const promises = deps.map(id => this.unsafeGet(id));
+    const deps = this.#dependencies.get(id);
+    const promises = deps.map(id => this.getUnsafe(id));
 
     await Promise.all(promises);
 
     // 'plugin.start' has already been called, just await the start promise
-    if (this._instanceStartPromises.has(id)) {
-      await this._instanceStartPromises.get(id);
+    if (this.#instanceStartPromises.has(id)) {
+      await this.#instanceStartPromises.get(id);
     } else {
-      this._propagateStateChange(instance, 'inited');
+      this.#propagateStateChange(instance, 'inited');
       let errored = false;
 
       try {
         const startPromise = instance.start();
-        this._instanceStartPromises.set(id, startPromise);
+        this.#instanceStartPromises.set(id, startPromise);
 
         await startPromise;
       } catch (err) {
         errored = true;
-        this._propagateStateChange(instance, 'errored');
+        this.#propagateStateChange(instance, 'errored');
         throw err;
       }
 
       // this looks silly but it prevents the try / catch to catch errors that could
       // be triggered by the propagate status callback, putting the plugin in errored state
       if (!errored) {
-        this._propagateStateChange(instance, 'started');
+        this.#propagateStateChange(instance, 'started');
       }
     }
 
     return instance;
   }
 
+  /**
+   * 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 {Function} ctor - The class returned by the plugin factory method.
+   * @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 begin 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 = []) {
+    // For now we don't allow to register a plugin after `client|server.init()`.
+    // This is subject to change in the future as we may want to dynamically
+    // register new plugins during application lifetime.
+    if (this.#node.status === 'inited') {
+      throw new Error(`[soundworks.PluginManager] Cannot register plugin (${id}) after "client.init()"`);
+    }
+
+    if (!isString(id)) {
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" first argument should be a string`);
+    }
+
+    if (!isPlainObject(options)) {
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" third optionnal argument should be an object`);
+    }
+
+    if (!Array.isArray(deps)) {
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" fourth optionnal argument should be an array`);
+    }
+
+    if (this[kPluginManagerInstances].has(id)) {
+      throw new Error(`[soundworks:PluginManager] Plugin "${id}" already registered`);
+    }
+
+    // We instanciate the plugin here, so that a plugin can register another one
+    // in its own constructor.
+    //
+    // The dependencies must be created first, so that the instance can call
+    // addDependency in its constructor
+    this.#dependencies.set(id, deps);
+
+    const instance = new ctor(this.#node, id, options);
+    this[kPluginManagerInstances].set(id, instance);
+  }
+
+  /**
+   * Manually add a dependency to a given plugin.
+   *
+   * Usefull to require a plugin within a plugin
+   */
+  addDependency(pluginId, dependencyId) {
+    const deps = this.#dependencies.get(pluginId);
+    deps.push(dependencyId);
+  }
+
+  /**
+   * Returns the list of the registered plugins ids
+   * @returns {string[]}
+   */
+  getRegisteredPlugins() {
+    return Array.from(this[kPluginManagerInstances].keys());
+  }
+
   /**
    * Propagate a notification each time a plugin is updated (status or inner state).
    * The callback will receive the list of all plugins as first parameter, and the
@@ -208,10 +262,8 @@ class BasePluginManager {
    *
    * _In most cases, you should not have to rely on this method._
    *
-   * @param {client.PluginManager~onStateChangeCallback|server.PluginManager~onStateChangeCallback} callback
-   *  Callback to be executed on state change
-   * @param {client.PluginManager~deleteOnStateChangeCallback|client.PluginManager~deleteOnStateChangeCallback}
-   *  Function to execute to listening for changes.
+   * @param {pluginManagerOnStateChangeCallback} callback - Callback to execute on state change
+   * @returns {pluginManagerDeleteOnStateChangeCallback} - Clear the subscription when executed
    * @example
    * const unsubscribe = client.pluginManager.onStateChange(pluginList, initiator => {
    *   // log the current status of all plugins
@@ -227,24 +279,8 @@ class BasePluginManager {
    * unsubscribe();
    */
   onStateChange(callback) {
-    this._onStateChangeCallbacks.add(callback);
-    return () => this._onStateChangeCallbacks.delete(callback);
-  }
-
-  /** @private */
-  _propagateStateChange(instance = null, status = null) {
-    if (instance !== null) {
-      // status is null if wew forward some inner state change from the instance
-      if (status !== null) {
-        instance.status = status;
-      }
-
-      const fullState = Object.fromEntries(this._instances);
-      this._onStateChangeCallbacks.forEach(callback => callback(fullState, instance));
-    } else {
-      const fullState = Object.fromEntries(this._instances);
-      this._onStateChangeCallbacks.forEach(callback => callback(fullState, null));
-    }
+    this.#onStateChangeCallbacks.add(callback);
+    return () => this.#onStateChangeCallbacks.delete(callback);
   }
 }