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

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,44 @@ import {
   UPDATE_ABORT,
   UPDATE_NOTIFICATION,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
 
-class BaseSharedState {
-  constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
-    this.id = id;
-    this.remoteId = remoteId;
-    this.schemaName = schemaName;
+// @todo - replace isOwner by `type`:
+// enum {
+//   'owner'
+//   'attached'
+//   'collection-controlller'
+//   'collection-attached'
+// }
 
+class BaseSharedState {
+  constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues, filter) {
+    /** @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;
+    /** @private */
+    this._filter = filter;
+
+    /**
+     * 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 +68,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 +104,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);
+        }
+      }
+
+      if (this._isOwner) {
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
+      }
 
-      this._clearDetach();
+      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 +226,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,85 +330,222 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
-    // handle immediate option
-    const immediateNewValues = {};
-    const immediateOldValues = {};
+    if (this._detached) {
+      return;
+    }
+
+    if (!isPlainObject(updates)) {
+      throw new TypeError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+    }
+
+    if (context !== null && !isPlainObject(context)) {
+      throw new TypeError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
+    }
+
+    const newValues = {};
+    const oldValues = {};
+    const localParams = {};
+    const sharedParams = {};
+    let hasLocalParam = false;
+    let hasSharedParam = false;
+    let forwardParams = undefined;
     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, and not only on the server side
+      // This throws if name does not exists
+      this._parameters.coerceValue(name, updates[name]);
+
+      // Check that name is in filter list, if any
+      if (this._filter !== null) {
+        if (!this._filter.includes(name)) {
+          throw new DOMException(`[SharedState] State "${this.schemaName}": cannot set parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+        }
       }
 
-      // @note: general idea...
-      // if immediate=true
+      // `immediate` option behavior
+      //
+      // If immediate=true
       //  - call listeners if value changed
       //  - go through normal server path
       //  - retrigger only if response from server is different from current value
-      // if immediate=true && (filterChange=false || event=true)
+      // If immediate=true && (filterChange=false || event=true)
       //  - call listeners with value regarless it changed
       //  - go through normal server path
       //  - if the node is initiator of the update (UPDATE_RESPONSE), (re-)check
       //    to prevent execute the listeners twice
 
-      const { immediate, filterChange, event } = this._parameters.getSchema(name);
+      // `local` option behavior
+      //
+      // - If the `updates` object only contains local variables, we can call the
+      // update listeners and return a fulfilled promise immediately
+      // - If parameters that require network communication are present, we call the
+      // update callback onces with the local payload, then we need to wait for the server
+      // response, call update listeners with server response and resolve promise with
+      // the full payload, i.e. reintegrating the local params in the resolve payload
+
+      const { local, immediate, filterChange, event } = this._parameters.getSchema(name);
 
-      if (immediate) {
+      if (immediate || local) {
         const oldValue = this._parameters.get(name);
         const [newValue, changed] = this._parameters.set(name, updates[name]);
 
+        // prepare data for immediate propagation of listeners
         if (changed || filterChange === false || event) {
-          immediateOldValues[name] = oldValue;
-          immediateNewValues[name] = newValue;
+          oldValues[name] = oldValue;
+          newValues[name] = newValue;
           propagateNow = true;
         }
       }
+
+      // define params that must go through network or not
+      if (local) {
+        hasLocalParam = true;
+        // get sanitize value for fulfilling promise
+        localParams[name] = this._parameters.get(name);
+      } else {
+        // note that immediate are shared params too
+        hasSharedParam = true;
+        sharedParams[name] = updates[name];
+      }
     }
 
+    // propagate immediate params if changed
     if (propagateNow) {
-      this._onUpdateCallbacks.forEach(listener => listener(immediateNewValues, immediateOldValues, context));
+      this._onUpdateCallbacks.forEach(listener => listener(newValues, oldValues, context));
     }
 
+    // check if we can resolve immediately or if we need to go through network
+    if (hasLocalParam) {
+      if (!hasSharedParam) {
+        return Promise.resolve(localParams);
+      } else {
+        // store local params to fulfill promise with all values, see PromiseStore
+        forwardParams = localParams;
+      }
+    }
+
+    // override updates to be shared on network without local params
+    updates = sharedParams;
+
     // 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', forwardParams);
       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) {
+    if (!this._parameters.has(name)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": Cannot get value of undefined parameter "${name}"`);
+    }
+
+    if (this._filter !== null) {
+      if (!this._filter.includes(name)) {
+        throw new DOMException(`[SharedState] State "${this.schemaName}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+      }
+    }
+
     return this._parameters.get(name);
   }
 
+  /**
+   * 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) {
+    if (!this._parameters.has(name)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": Cannot get value of undefined parameter "${name}"`);
+    }
+
+    if (this._filter !== null) {
+      if (!this._filter.includes(name)) {
+        throw new DOMException(`[SharedState] State "${this.schemaName}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+      }
+    }
+
+    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
    * const values = state.getValues();
    */
   getValues() {
-    return this._parameters.getValues();
+    const values = this._parameters.getValues();
+
+    if (this._filter !== null) {
+      for (let name in values) {
+        if (!this._filter.includes(name)) {
+          delete values[name];
+        }
+      }
+    }
+
+    return values;
   }
 
   /**
-   * Get the schema from which the state has been created.
+   * Get all the key / value pairs of the state.
+   *
+   * 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.
    *
-   * @param {string} [name=null] - If given, returns only the definition corresponding
-   *  to the given param name.
+   * @return {object}
+   * @example
+   * const values = state.getValues();
+   */
+  getValuesUnsafe() {
+    const values = this._parameters.getValuesUnsafe();
+
+    if (this._filter !== null) {
+      for (let name in values) {
+        if (!this._filter.includes(name)) {
+          delete values[name];
+        }
+      }
+    }
+
+    return values;
+  }
+
+  /**
+   * 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.
    * @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 +579,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 +587,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 +609,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 +624,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 +670,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 +684,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);