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

package/src/common/BasePlugin.js

@@ -1,30 +1,14 @@
-import merge from 'lodash.merge';
+import merge from 'lodash/merge.js';
 
 /**
  * @private
  */
 class BasePlugin {
   constructor(id) {
-    /**
-     * User defined ID of the plugin.
-     *
-     * @type {string}
-     * @see {@link client.PluginManager#register}
-     * @see {@link server.PluginManager#register}
-     */
-    this.id = id;
-
-    /**
-     * Type of the plugin, i.e. the ClassName.
-     *
-     * Usefull to do perform some logic based on certain types of plugins without
-     * knowing under which `id` they have been registered. (e.g. creating some generic
-     * views, etc.)
-     *
-     * @type {string}
-     * @readonly
-     */
-    this.type = this.constructor.name;
+    /** @private */
+    this._id = id;
+    /** @private */
+    this._type = this.constructor.name;
 
     /**
      * Options of the plugin.
@@ -58,6 +42,32 @@ class BasePlugin {
     this._onStateChangeCallbacks = new Set();
   }
 
+  /**
+   * User defined ID of the plugin.
+   *
+   * @type {string}
+   * @readonly
+   * @see {@link client.PluginManager#register}
+   * @see {@link server.PluginManager#register}
+   */
+  get id() {
+    return this._id;
+  }
+
+  /**
+   * Type of the plugin, i.e. the ClassName.
+   *
+   * Usefull to do perform some logic based on certain types of plugins without
+   * knowing under which `id` they have been registered. (e.g. creating some generic
+   * views, etc.)
+   *
+   * @type {string}
+   * @readonly
+   */
+  get type() {
+    return this._type;
+  }
+
   /**
    * Start the plugin. This method is automatically called during the client or
    * server `init()` lifecyle step. After `start()` is fulfilled the plugin should

package/src/common/BasePluginManager.js

@@ -1,7 +1,6 @@
-import isPlainObject from 'is-plain-obj';
+import { isPlainObject, isString } from '@ircam/sc-utils';
 
 import logger from './logger.js';
-import { isString } from './utils.js';
 
 /**
  * Shared functionnality between server-side and client-size plugin manager
@@ -14,7 +13,7 @@ class BasePluginManager {
     /** @private */
     this._node = node;
     /** @private */
-    this._registeredPlugins = new Map();
+    this._dependencies = new Map();
     /** @private */
     this._instances = new Map();
     /** @private */
@@ -68,11 +67,29 @@ class BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.register" fourth optionnal argument should be an array`);
     }
 
-    if (this._registeredPlugins.has(id)) {
-      throw new Error(`[soundworks:PluginManager] Plugin "${id}" of type "${ctor.name}" already registered`);
+    if (this._instances.has(id)) {
+      throw new Error(`[soundworks:PluginManager] Plugin "${id}" already registered`);
     }
 
-    this._registeredPlugins.set(id, { ctor, options, deps });
+    // 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
+   *
+   */
+  addDependency(pluginId, dependencyId) {
+    const deps = this._dependencies.get(pluginId);
+    deps.push(dependencyId);
   }
 
   /**
@@ -80,7 +97,7 @@ class BasePluginManager {
    * @returns {string[]}
    */
   getRegisteredPlugins() {
-    return Array.from(this._registeredPlugins.keys());
+    return Array.from(this._instances.keys());
   }
 
   /**
@@ -97,23 +114,21 @@ class BasePluginManager {
 
     this.status = 'inited';
     // instanciate all plugins
-    for (let [id, { ctor, options }] of this._registeredPlugins.entries()) {
-      const instance = new ctor(this._node, id, options);
-      this._instances.set(id, instance);
+    for (let [_id, instance] of this._instances.entries()) {
       instance.onStateChange(_values => this._propagateStateChange(instance));
     }
 
     // propagate all 'idle' statuses before start
     this._propagateStateChange();
 
-    const promises = Array.from(this._registeredPlugins.keys()).map(id => this.unsafeGet(id));
+    const promises = Array.from(this._instances.keys()).map(id => this.unsafeGet(id));
 
     try {
       await Promise.all(promises);
       this.status = 'started';
-    } catch(err) {
+    } catch (err) {
       this.status = 'errored';
-      throw new Error(err);
+      throw err; // throw initial error
     }
   }
 
@@ -126,8 +141,8 @@ class BasePluginManager {
 
   /**
    * Retrieve an fully started instance of a registered plugin, without checking
-   * that the pluginManager is started. This is important for starting the plugin
-   * manager itself.
+   * that the pluginManager has started. This is required for starting the plugin
+   * manager itself and to require a plugin from within another plugin
    *
    * @private
    */
@@ -136,7 +151,7 @@ class BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Invalid argument, "pluginManager.get(name)" argument should be a string`);
     }
 
-    if (!this._registeredPlugins.has(id)) {
+    if (!this._instances.has(id)) {
       throw new Error(`[soundworks:PluginManager] Cannot get plugin "${id}", plugin is not registered`);
     }
 
@@ -145,7 +160,7 @@ class BasePluginManager {
     // to dynamically register and launch plugins at runtime.
     //
     // if (!this._instances.has(id)) {
-    //   const { ctor, options } = this._registeredPlugins.get(id);
+    //   const { ctor, options } = this._dependencies.get(id);
     //   const instance = new ctor(this._node, id, options);
     //   this._instances.set(id, instance);
     // }
@@ -153,7 +168,7 @@ class BasePluginManager {
     const instance = this._instances.get(id);
 
     // recursively get the dependency chain
-    const { deps } = this._registeredPlugins.get(id);
+    const deps = this._dependencies.get(id);
     const promises = deps.map(id => this.unsafeGet(id));
 
     await Promise.all(promises);
@@ -170,7 +185,7 @@ class BasePluginManager {
         this._instanceStartPromises.set(id, startPromise);
 
         await startPromise;
-      } catch(err) {
+      } catch (err) {
         errored = true;
         this._propagateStateChange(instance, 'errored');
         throw err;

package/src/common/BaseSharedState.js

@@ -1,4 +1,6 @@
+import { isPlainObject } from '@ircam/sc-utils';
 import ParameterBag from './ParameterBag.js';
+import PromiseStore from './PromiseStore.js';
 import {
   DELETE_REQUEST,
   DELETE_RESPONSE,
@@ -12,29 +14,41 @@ import {
   UPDATE_ABORT,
   UPDATE_NOTIFICATION,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
+
+// @todo - replace isOwner by `type`:
+// enum {
+//   'owner'
+//   'attached'
+//   'collection-controlller'
+//   'collection-attached'
+// }
 
 class BaseSharedState {
   constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
-    this.id = id;
-    this.remoteId = remoteId;
-    this.schemaName = schemaName;
-
+    /** @private */
+    this._id = id;
+    /** @private */
+    this._remoteId = remoteId;
+    /** @private */
+    this._schemaName = schemaName;
     /** @private */
     this._isOwner = isOwner; // may be the server or any client
     /** @private */
     this._client = client;
     /** @private */
     this._manager = manager;
+    /**
+     * true is the state has been detached or deleted
+     * @private
+     */
+    this._detached = false;
+    /* @private */
+    this._promiseStore = new PromiseStore(this.constructor.name);
 
     try {
       /** @private */
       this._parameters = new ParameterBag(schema, initValues);
-    } catch(err) {
+    } catch (err) {
       console.error(err.stack);
 
       throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
@@ -51,13 +65,13 @@ ${JSON.stringify(initValues, null, 2)}`);
     // add listener for state updates
     this._client.transport.addListener(`${UPDATE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId, updates, context) => {
       const updated = await this._commit(updates, context, true, true);
-      resolveRequest(reqId, updated);
+      this._promiseStore.resolve(reqId, updated);
     });
 
     // retrieve values but do not propagate to subscriptions
     this._client.transport.addListener(`${UPDATE_ABORT}-${this.id}-${this.remoteId}`, async (reqId, updates, context) => {
       const updated = await this._commit(updates, context, false, true);
-      resolveRequest(reqId, updated);
+      this._promiseStore.resolve(reqId, updated);
     });
 
     this._client.transport.addListener(`${UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`, async (updates, context) => {
@@ -87,70 +101,121 @@ ${JSON.stringify(initValues, null, 2)}`);
     });
 
     // ---------------------------------------------
-    // DELETE initiated by creator, or schema deleted
+    // state has been deleted by its creator or the schema has been deleted
     // ---------------------------------------------
-    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, () => {
+    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, async () => {
       this._manager._statesById.delete(this.id);
       this._clearTransport();
 
-      this._onDetachCallbacks.forEach(callback => callback());
-      this._onDeleteCallbacks.forEach(callback => callback());
+      for (let callback of this._onDetachCallbacks) {
+        try {
+          await callback();
+        } catch (err) {
+          console.error(err.message);
+        }
+      }
 
-      this._clearDetach();
+      if (this._isOwner) {
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
+      }
+
+      this._onDetachCallbacks.clear();
+      this._onDeleteCallbacks.clear();
+      this._promiseStore.flush();
     });
 
 
     if (this._isOwner) {
       // ---------------------------------------------
-      // DELETE (can only delete if creator)
+      // the creator has called `.delete()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
+      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
         this._manager._statesById.delete(this.id);
         this._clearTransport();
 
-        this._onDetachCallbacks.forEach(callback => callback());
-        this._onDeleteCallbacks.forEach(callback => callback());
+        for (let callback of this._onDetachCallbacks) {
+          await callback();
+        }
+
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
 
-        this._clearDetach();
-        resolveRequest(reqId, this);
+        this._onDetachCallbacks.clear();
+        this._onDeleteCallbacks.clear();
+        this._promiseStore.resolve(reqId, this);
+        this._promiseStore.flush();
       });
 
       this._client.transport.addListener(`${DELETE_ERROR}-${this.id}`, (reqId, msg) => {
-        rejectRequest(reqId, msg);
+        this._promiseStore.reject(reqId, msg);
       });
 
     } else {
       // ---------------------------------------------
-      // DETACH
+      // the attached node has called `.detach()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
+      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
         this._manager._statesById.delete(this.id);
         this._clearTransport();
 
-        this._onDetachCallbacks.forEach(func => func());
+        for (let callback of this._onDetachCallbacks) {
+          await callback();
+        }
 
-        this._clearDetach();
-        resolveRequest(reqId, this);
+        this._onDetachCallbacks.clear();
+        this._onDeleteCallbacks.clear();
+        this._promiseStore.resolve(reqId, this);
+        this._promiseStore.flush();
       });
 
       // the state does not exists anymore in the server (should not happen)
       this._client.transport.addListener(`${DETACH_ERROR}-${this.id}`, (reqId, msg) => {
-        rejectRequest(reqId, msg);
+        this._onDetachCallbacks.clear();
+        this._onDeleteCallbacks.clear();
+        this._promiseStore.reject(reqId, msg);
+        this._promiseStore.flush();
       });
-
     }
   }
 
-  /** @private */
-  _clearDetach() {
-    this._onDetachCallbacks.clear();
-    this._onDeleteCallbacks.clear();
-
-    // Monkey patch detach so it throws if called twice. Doing nothing blocks
-    // the process on a second `detach` call as the Promise never resolves
-    this.detach = () => {
-      throw new Error(`[stateManager] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
-    };
+  /**
+   * Id of the state
+   * @type {Number}
+   * @readonly
+   */
+  get id() {
+    return this._id;
+  }
+
+  /**
+   * Unique id of the state for the current node
+   * @readonly
+   * @type {Number}
+   * @private
+   */
+  get remoteId() {
+    return this._remoteId;
+  }
+
+  /**
+   * Name of the schema
+   * @type {String}
+   * @readonly
+   */
+  get schemaName() {
+    return this._schemaName;
+  }
+
+  /**
+   * Indicates if the node is the owner of the state
+   * @type {Boolean}
+   * @readonly
+   */
+  get isOwner() {
+    return this._isOwner;
   }
 
   /** @private */
@@ -158,9 +223,16 @@ ${JSON.stringify(initValues, null, 2)}`);
     // remove listeners
     this._client.transport.removeAllListeners(`${UPDATE_RESPONSE}-${this.id}-${this.remoteId}`);
     this._client.transport.removeAllListeners(`${UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`);
-    this._client.transport.removeAllListeners(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`);
+    this._client.transport.removeAllListeners(`${UPDATE_ABORT}-${this.id}-${this.remoteId}`);
     this._client.transport.removeAllListeners(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`);
-    this._client.transport.removeAllListeners(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`);
+
+    if (this._isOwner) {
+      this._client.transport.removeAllListeners(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`);
+      this._client.transport.removeAllListeners(`${DELETE_ERROR}-${this.id}-${this.remoteId}`);
+    } else {
+      this._client.transport.removeAllListeners(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`);
+      this._client.transport.removeAllListeners(`${DETACH_ERROR}-${this.id}-${this.remoteId}`);
+    }
   }
 
   /** @private */
@@ -255,16 +327,27 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
+    if (this._detached) {
+      return;
+    }
+
+    if (!isPlainObject(updates)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+    }
+
+    if (context !== null && !isPlainObject(context)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
+    }
+
     // handle immediate option
     const immediateNewValues = {};
     const immediateOldValues = {};
     let propagateNow = false;
 
     for (let name in updates) {
-      // throw early (client-side and not only server-side) if parameter is undefined
-      if (!this._parameters.has(name)) {
-        throw new ReferenceError(`[stateManager] Cannot set value of undefined parameter "${name}"`);
-      }
+      // try to coerce value early, so that eventual errors are triggered early
+      // on the node requesting the update
+      this._parameters.coerceValue(name, updates[name]);
 
       // @note: general idea...
       // if immediate=true
@@ -297,27 +380,47 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     // go through server-side normal behavior
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'update-request');
       this._client.transport.emit(`${UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
     });
   }
 
   /**
-   * Get the value of a paramter of the state.
+   * Get the value of a parameter of the state. If the parameter is of `any` type,
+   * a deep copy is returned.
    *
    * @param {string} name - Name of the param.
    * @throws Throws if `name` does not correspond to an existing field
    *  of the state.
    * @return {mixed}
    * @example
-   * const value = state.get('name');
+   * const value = state.get('paramName');
    */
   get(name) {
     return this._parameters.get(name);
   }
 
   /**
-   * Get all the key / value pairs of the state.
+   * Similar to `get` but returns a reference to the underlying value in case of
+   * `any` type. May be usefull if the underlying value is big (e.g. sensors
+   * recordings, etc.) and deep cloning expensive. Be aware that if changes are
+   * made on the returned object, the state of your application will become
+   * inconsistent.
+   *
+   * @param {string} name - Name of the param.
+   * @throws Throws if `name` does not correspond to an existing field
+   *  of the state.
+   * @return {mixed}
+   * @example
+   * const value = state.getUnsafe('paramName');
+   */
+  getUnsafe(name) {
+    return this._parameters.getUnsafe(name);
+  }
+
+  /**
+   * Get all the key / value pairs of the state. If a parameter is of `any`
+   * type, a deep copy is made.
    *
    * @return {object}
    * @example
@@ -328,12 +431,29 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Get the schema from which the state has been created.
+   * Get all the key / value pairs of the state. If a parameter is of `any`
+   * type, a deep copy is made.
+   * Similar to `getValues` but returns a reference to the underlying value in
+   * case of `any` type. May be usefull if the underlying value is big (e.g.
+   * sensors recordings, etc.) and deep cloning expensive. Be aware that if
+   * changes are made on the returned object, the state of your application will
+   * become inconsistent.
+   *
+   * @return {object}
+   * @example
+   * const values = state.getValues();
+   */
+  getValuesUnsafe() {
+    return this._parameters.getValuesUnsafe();
+  }
+
+  /**
+   * Definition of schema from which the state has been created.
    *
-   * @param {string} [name=null] - If given, returns only the definition corresponding
-   *  to the given param name.
+   * @param {string} [name=null] - If given, returns only the definition
+   *  corresponding to the given param name.
    * @throws Throws if `name` does not correspond to an existing field
-   *  of the state.
+   *  of the schema.
    * @return {object}
    * @example
    * const schema = state.getSchema();
@@ -367,7 +487,7 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Detach from the state. If the client is the creator of the state, the state
-   * is deleted and all attached nodes get notified
+   * is deleted and all attached nodes get notified.
    *
    * @example
    * const state = await client.state.attach('globals');
@@ -375,16 +495,21 @@ ${JSON.stringify(initValues, null, 2)}`);
    * await state.detach();
    */
   async detach() {
+    if (this._detached) {
+      throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
+    }
+
+    this._detached = true; // mark detached early
     this._onUpdateCallbacks.clear();
 
     if (this._isOwner) {
       return new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = this._promiseStore.add(resolve, reject, 'delete-request');
         this._client.transport.emit(`${DELETE_REQUEST}-${this.id}-${this.remoteId}`, reqId);
       });
     } else {
       return new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = this._promiseStore.add(resolve, reject, 'detach-request');
         this._client.transport.emit(`${DETACH_REQUEST}-${this.id}-${this.remoteId}`, reqId);
       });
     }
@@ -392,9 +517,11 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Delete the state. Only the creator/owner of the state can use this method.
-   * All nodes attached to the state will be deteched, triggering the `onDetach`
-   * callback. The creator of the state will also have its `onDelete` callback
-   * triggered.
+   *
+   * All nodes attached to the state will be detached, triggering any registered
+   * `onDetach` callbacks. The creator of the state will also have its own `onDelete`
+   * callback triggered. The local `onDeatch` and `onDelete` callbacks will be
+   * executed *before* the returned Promise resolves
    *
    * @throws Throws if the method is called by a node which is not the owner of
    * the state.
@@ -405,16 +532,20 @@ ${JSON.stringify(initValues, null, 2)}`);
    */
   async delete() {
     if (this._isOwner) {
+      if (this._detached) {
+        throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already deleted, cannot delete twice`);
+      }
+
       return this.detach();
     } else {
-      throw new Error(`[stateManager] can delete state "${this.schemaName}", only owner of the state (i.e. the node that "create[d]" it) can delete it`);
+      throw new Error(`[SharedState] Cannot delete state "${this.schemaName}", only the owner of the state (i.e. the node that created it) can delete the state. Use "detach" instead.`);
     }
   }
 
   /**
    * Subscribe to state updates.
    *
-   * @param {client.SharedState~onUpdateCallback|client.SharedState~onUpdateCallback} callback
+   * @param {client.SharedState~onUpdateCallback|server.SharedState~onUpdateCallback} callback
    *  Callback to execute when an update is applied on the state.
    * @param {Boolean} [executeListener=false] - Execute the callback immediately
    *  with current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
@@ -447,10 +578,11 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Register a function to execute when detaching from the state
+   * Register a function to execute when detaching from the state. The function
+   * will be executed before the `detach` promise resolves.
    *
-   * @param {Function} callback - callback to execute when detaching from the state.
-   *   wether the client as called `detach`, or the state has been deleted by its
+   * @param {Function} callback - Callback to execute when detaching from the state.
+   *   Whether the client as called `detach`, or the state has been deleted by its
    *   creator.
    */
   onDetach(callback) {
@@ -460,9 +592,10 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Register a function to execute when the state is deleted. Only called if the
-   * node was the creator of the state. Is called after `onDetach`
+   * node was the creator of the state. Is called after `onDetach` and executed
+   * before the `delete` Promise resolves.
    *
-   * @param {Function} callback - callback to execute when the state is deleted.
+   * @param {Function} callback - Callback to execute when the state is deleted.
    */
   onDelete(callback) {
     this._onDeleteCallbacks.add(callback);