@soundworks/core 3.7.0 → 4.0.0-alpha.0

package/{common/SharedState.js → src/common/BaseSharedState.js}

@@ -1,65 +1,66 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _ParameterBag = _interopRequireDefault(require("./ParameterBag.js"));
-
-var _sharedStateUtils = require("./shared-state-utils.js");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-/**
- * Representation of a shared state.
- *
- * @memberof server
- *
- * @see {server.SharedStateManagerServer}
- */
-
-/**
- * Representation of a shared state.
- *
- * @memberof client
- *
- * @see {client.SharedStateManagerClient}
- */
-class SharedState {
+import ParameterBag from './ParameterBag.js';
+import {
+  DELETE_REQUEST,
+  DELETE_RESPONSE,
+  DELETE_ERROR,
+  DELETE_NOTIFICATION,
+  DETACH_REQUEST,
+  DETACH_RESPONSE,
+  DETACH_ERROR,
+  UPDATE_REQUEST,
+  UPDATE_RESPONSE,
+  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;
-    this._isOwner = isOwner; // may be the server or any client
 
+    /** @private */
+    this._isOwner = isOwner; // may be the server or any client
+    /** @private */
     this._client = client;
+    /** @private */
     this._manager = manager;
 
     try {
-      this._parameters = new _ParameterBag.default(schema, initValues);
-    } catch (err) {
+      /** @private */
+      this._parameters = new ParameterBag(schema, initValues);
+    } catch(err) {
       console.error(err.stack);
+
       throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
 ${JSON.stringify(initValues, null, 2)}`);
     }
 
-    this._subscriptions = new Set();
+    /** @private */
+    this._onUpdateCallbacks = new Set();
+    /** @private */
     this._onDetachCallbacks = new Set();
-    this._onDeleteCallbacks = new Set(); // add listener for state updates
+    /** @private */
+    this._onDeleteCallbacks = new Set();
 
-    this._client.transport.addListener(`${_sharedStateUtils.UPDATE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId, updates, context) => {
+    // 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);
-      (0, _sharedStateUtils.resolveRequest)(reqId, updated);
-    }); // retrieve values but do not propagate to subscriptions
-
+      resolveRequest(reqId, updated);
+    });
 
-    this._client.transport.addListener(`${_sharedStateUtils.UPDATE_ABORT}-${this.id}-${this.remoteId}`, async (reqId, updates, context) => {
+    // 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);
-      (0, _sharedStateUtils.resolveRequest)(reqId, updated);
+      resolveRequest(reqId, updated);
     });
 
-    this._client.transport.addListener(`${_sharedStateUtils.UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`, async (updates, context) => {
+    this._client.transport.addListener(`${UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`, async (updates, context) => {
       // https://github.com/collective-soundworks/soundworks/issues/18
       //
       // # note: 2002-10-03
@@ -83,113 +84,100 @@ ${JSON.stringify(initValues, null, 2)}`);
       // which is far more important than the edge case reported in the issue
       // therefore this wont be fixed for now
       this._commit(updates, context, true, false);
-    }); // ---------------------------------------------
+    });
+
+    // ---------------------------------------------
     // DELETE initiated by creator, or schema deleted
     // ---------------------------------------------
-
-
-    this._client.transport.addListener(`${_sharedStateUtils.DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, () => {
+    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, () => {
       this._manager._statesById.delete(this.id);
-
       this._clearTransport();
 
       this._onDetachCallbacks.forEach(callback => callback());
-
       this._onDeleteCallbacks.forEach(callback => callback());
 
       this._clearDetach();
     });
 
+
     if (this._isOwner) {
       // ---------------------------------------------
       // DELETE (can only delete if creator)
       // ---------------------------------------------
-      this._client.transport.addListener(`${_sharedStateUtils.DELETE_RESPONSE}-${this.id}-${this.remoteId}`, reqId => {
+      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
         this._manager._statesById.delete(this.id);
-
         this._clearTransport();
 
         this._onDetachCallbacks.forEach(callback => callback());
-
         this._onDeleteCallbacks.forEach(callback => callback());
 
         this._clearDetach();
-
-        (0, _sharedStateUtils.resolveRequest)(reqId, this);
+        resolveRequest(reqId, this);
       });
 
-      this._client.transport.addListener(`${_sharedStateUtils.DELETE_ERROR}-${this.id}`, (reqId, msg) => {
-        (0, _sharedStateUtils.rejectRequest)(reqId, msg);
+      this._client.transport.addListener(`${DELETE_ERROR}-${this.id}`, (reqId, msg) => {
+        rejectRequest(reqId, msg);
       });
+
     } else {
       // ---------------------------------------------
       // DETACH
       // ---------------------------------------------
-      this._client.transport.addListener(`${_sharedStateUtils.DETACH_RESPONSE}-${this.id}-${this.remoteId}`, reqId => {
+      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
         this._manager._statesById.delete(this.id);
-
         this._clearTransport();
 
         this._onDetachCallbacks.forEach(func => func());
 
         this._clearDetach();
+        resolveRequest(reqId, this);
+      });
 
-        (0, _sharedStateUtils.resolveRequest)(reqId, this);
-      }); // the state does not exists anymore in the server (should not happen)
-
-
-      this._client.transport.addListener(`${_sharedStateUtils.DETACH_ERROR}-${this.id}`, (reqId, msg) => {
-        (0, _sharedStateUtils.rejectRequest)(reqId, msg);
+      // 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);
       });
+
     }
   }
 
+  /** @private */
   _clearDetach() {
     this._onDetachCallbacks.clear();
+    this._onDeleteCallbacks.clear();
 
-    this._onDeleteCallbacks.clear(); // Monkey patch detach so it throws if called twice. Doing nothing blocks
+    // 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`);
     };
   }
 
+  /** @private */
   _clearTransport() {
     // remove listeners
-    this._client.transport.removeAllListeners(`${_sharedStateUtils.UPDATE_RESPONSE}-${this.id}-${this.remoteId}`);
-
-    this._client.transport.removeAllListeners(`${_sharedStateUtils.UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`);
-
-    this._client.transport.removeAllListeners(`${_sharedStateUtils.DELETE_RESPONSE}-${this.id}-${this.remoteId}`);
-
-    this._client.transport.removeAllListeners(`${_sharedStateUtils.DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`);
-
-    this._client.transport.removeAllListeners(`${_sharedStateUtils.DETACH_RESPONSE}-${this.id}-${this.remoteId}`);
+    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(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`);
+    this._client.transport.removeAllListeners(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`);
   }
-  /** @private */
-
 
+  /** @private */
   async _commit(updates, context, propagate = true, initiator = false) {
     const newValues = {};
     const oldValues = {};
 
     for (let name in updates) {
-      const {
-        immediate,
-        event
-      } = this._parameters.getSchema(name); // @note 20211209 - we had an issue here server-side, because if the value
+      const { immediate, event } = this._parameters.getSchema(name);
+      // @note 20211209 - we had an issue here server-side, because if the value
       // is an object or an array, the reference is shared by everybody, therefore
       // `changed` is always false and the new value is never propagated...
       // FIXED - `state.get` now returns a deep copy when `type` is `any`
-
-
       const oldValue = this._parameters.get(name);
+      const [newValue, changed] = this._parameters.set(name, updates[name]);
 
-      const [newValue, changed] = this._parameters.set(name, updates[name]); // handle immediate stuff
-
-
+      // handle immediate stuff
       if (initiator && immediate) {
         // @note - we don't need to check filterChange here because the value
         // has been updated in parameters on the `set` side so can rely on `changed`
@@ -203,25 +191,24 @@ ${JSON.stringify(initValues, null, 2)}`);
 
       newValues[name] = newValue;
       oldValues[name] = oldValue;
-    } // if the `UPDATE_REQUEST` as been aborted by the server, do not propagate
-
+    }
 
+    // if the `UPDATE_REQUEST` as been aborted by the server, do not propagate
     let promises = [];
 
     if (propagate && Object.keys(newValues).length > 0) {
-      this._subscriptions.forEach(listener => {
+      this._onUpdateCallbacks.forEach(listener => {
         promises.push(listener(newValues, oldValues, context));
       });
-    } // on a given client, `await state.set(update)` resolves when all
-    // subscription have resolved themselves
-
+    }
 
-    await Promise.all(promises); // reset events to null after propagation of all listeners
+    // on a given client, `await state.set(update)` resolves after all
+    // update callbacks have themselves resolved
+    await Promise.all(promises);
 
+    // reset events to null after propagation of all listeners
     for (let name in newValues) {
-      const {
-        event
-      } = this._parameters.getSchema(name);
+      const { event } = this._parameters.getSchema(name);
 
       if (event) {
         this._parameters.set(name, null);
@@ -230,15 +217,21 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     return newValues;
   }
+
   /**
-   * Updates values of the state. Wait for all subscriptions to be resolved
-   * before resolving itself, i.e.:
+   * Update values of the state.
+   *
+   * The returned `Promise` resolves on the applied updates, when all the `onUpdate`
+   * callbacks have resolved themselves, i.e.:
    *
    * ```js
+   * server.stateManager.registerSchema('test', {
+   *   myBool: { type: 'boolean', default: false },
+   * });
    * const a = await server.stateManager.create('a');
    * let asyncCallbackCalled = false;
    *
-   * a.subscribe(updates => {
+   * a.onUpdate(updates => {
    *   return new Promise(resolve => {
    *     setTimeout(() => {
    *       asyncCallbackCalled = true;
@@ -247,21 +240,20 @@ ${JSON.stringify(initValues, null, 2)}`);
    *   });
    * });
    *
-   * await a.set({ bool: true });
+   * const updates = await a.set({ myBool: true });
    * assert.equal(asyncCallbackCalled, true);
+   * assert.deepEqual(updates, { myBool: true });
    * ```
    *
-   * @async
-   * @param {Object} updates - key / value pairs of updates to apply to the state.
-   * @param {Mixed} [context=null] - optionnal context that will be propagated
+   * @param {object} updates - key / value pairs of updates to apply to the state.
+   * @param {mixed} [context=null] - optionnal contextual object that will be propagated
    *   alongside the updates of the state. The context is valid only for the
-   *   current call and will be passed as third argument to any subscribe listeners.
-   * @return {Promise<Object>} A promise to the (coerced) updates.
-   *
-   * @see {common.SharedState~subscribeCallback}
+   *   current call and will be passed as third argument to all update listeners.
+   * @returns {Promise<Object>} A promise to the (coerced) updates.
+   * @example
+   * const state = await client.state.attach('globals');
+   * const updates = await state.set({ myParam: Math.random() });
    */
-
-
   async set(updates, context = null) {
     // handle immediate option
     const immediateNewValues = {};
@@ -272,7 +264,9 @@ ${JSON.stringify(initValues, null, 2)}`);
       // 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}"`);
-      } // @note: general idea...
+      }
+
+      // @note: general idea...
       // if immediate=true
       //  - call listeners if value changed
       //  - go through normal server path
@@ -283,16 +277,10 @@ ${JSON.stringify(initValues, null, 2)}`);
       //  - 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);
+      const { immediate, filterChange, event } = this._parameters.getSchema(name);
 
       if (immediate) {
         const oldValue = this._parameters.get(name);
-
         const [newValue, changed] = this._parameters.set(name, updates[name]);
 
         if (changed || filterChange === false || event) {
@@ -304,112 +292,147 @@ ${JSON.stringify(initValues, null, 2)}`);
     }
 
     if (propagateNow) {
-      this._subscriptions.forEach(listener => listener(immediateNewValues, immediateOldValues, context));
-    } // go through server-side normal behavior
-
+      this._onUpdateCallbacks.forEach(listener => listener(immediateNewValues, immediateOldValues, context));
+    }
 
+    // go through server-side normal behavior
     return new Promise((resolve, reject) => {
-      const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
-
-      this._client.transport.emit(`${_sharedStateUtils.UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
+      const reqId = storeRequestPromise(resolve, reject);
+      this._client.transport.emit(`${UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
     });
   }
+
   /**
-   * Get a value of the state by its name
+   * Get the value of a paramter of the state.
    *
-   * @param {String} name - Name of the param. Throws an error if the name is invalid.
-   * @return {Mixed}
+   * @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');
    */
-
-
   get(name) {
     return this._parameters.get(name);
   }
+
   /**
-   * Get a all the key / value pairs of the state.
+   * Get all the key / value pairs of the state.
    *
-   * @return {Object}
+   * @return {object}
+   * @example
+   * const values = state.getValues();
    */
-
-
   getValues() {
     return this._parameters.getValues();
   }
+
   /**
-   * Get the schema that describes the state.
+   * Get the schema from which the state has been created.
    *
-   * @param {String} [name=null] - if given, returns only the definition
-   *   of the given param name. Throws an error if the name is invalid.
-   * @return {Object}
+   * @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.
+   * @return {object}
+   * @example
+   * const schema = state.getSchema();
    */
-
-
   getSchema(name = null) {
     return this._parameters.getSchema(name);
   }
+
   /**
-   * Get the values with which the state has been initialized.
+   * Get the values with which the state has been created. May defer from the
+   * default values declared in the schema.
    *
-   * @return {Object}
+   * @return {object}
+   * @example
+   * const initValues = state.getInitValues();
    */
-
-
   getInitValues() {
     return this._parameters.getInitValues();
   }
+
   /**
-   * Get the default values that has been declared in the schema.
+   * Get the default values as declared in the schema.
    *
-   * @return {Object}
+   * @return {object}
+   * @example
+   * const defaults = state.getDefaults();
    */
-
-
   getDefaults() {
     return this._parameters.getDefaults();
   }
+
   /**
-   * @callback common.SharedState~subscribeCallback
-   * @param {Object} newValues - key / value pairs of the updates that have been
-   *   applied to the state.
-   * @param {Object} oldValues - key / value pairs of the related params before
-   *   the updates has been applied to the state.
-   * @param {Mixed} [context=null] - Optionnal context data that has been passed
-   *   with the updates in the `set` call.
+   * Detach from the state. If the client is the creator of the state, the state
+   * is deleted and all attached nodes get notified
    *
    * @example
-   * state.subscribe(async (newValues, oldValues[, context=null]) =>  {
-   *   for (let [key, value] of Object.entries(newValues)) {
-   *      switch (key) {
-   *        // do something
-   *      }
-   *   }
-   * });
-   *
-   * @see {common.SharedState#set}
-   * @see {common.SharedState#subscribe}
+   * const state = await client.state.attach('globals');
+   * // later
+   * await state.detach();
    */
+  async detach() {
+    this._onUpdateCallbacks.clear();
+
+    if (this._isOwner) {
+      return new Promise((resolve, reject) => {
+        const reqId = storeRequestPromise(resolve, reject);
+        this._client.transport.emit(`${DELETE_REQUEST}-${this.id}-${this.remoteId}`, reqId);
+      });
+    } else {
+      return new Promise((resolve, reject) => {
+        const reqId = storeRequestPromise(resolve, reject);
+        this._client.transport.emit(`${DETACH_REQUEST}-${this.id}-${this.remoteId}`, reqId);
+      });
+    }
+  }
 
   /**
-   * Subscribe to state updates
+   * 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.
    *
-   * @param {common.SharedState~subscribeCallback} callback - callback to execute
-   *   when an update is applied on the state.
-   * @param {Boolean} [executeListener=false] - execute the given listener with
-   *   current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
+   * @throws Throws if the method is called by a node which is not the owner of
+   * the state.
+   * @example
+   * const state = await client.state.create('my-schema-name');
+   * // later
+   * await state.delete();
+   */
+  async delete() {
+    if (this._isOwner) {
+      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`);
+    }
+  }
+
+  /**
+   * Subscribe to state updates.
    *
+   * @param {client.SharedState~onUpdateCallback|client.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`)
+   * @returns {client.SharedState~deleteOnUpdateCallback|server.SharedState~deleteOnUpdateCallback}
    * @example
-   * state.subscribe(async (newValues, oldValues) =>  {
+   * const unsubscribe = state.onUpdate(async (newValues, oldValues, context) =>  {
    *   for (let [key, value] of Object.entries(newValues)) {
    *      switch (key) {
    *        // do something
    *      }
    *   }
    * });
+   *
+   * // later
+   * unsubscribe();
    */
-
-
-  subscribe(listener, executeListener = false) {
-    this._subscriptions.add(listener);
+  onUpdate(listener, executeListener = false) {
+    this._onUpdateCallbacks.add(listener);
 
     if (executeListener === true) {
       const currentValues = this.getValues();
@@ -419,62 +442,10 @@ ${JSON.stringify(initValues, null, 2)}`);
     }
 
     return () => {
-      this._subscriptions.delete(listener);
+      this._onUpdateCallbacks.delete(listener);
     };
   }
-  /**
-   * Detach from the state. If the client is the creator of the state, the state
-   * is deleted and all attached nodes get notified
-   *
-   * @async
-   * @see {common.SharedState#onDetach}
-   * @see {common.SharedState#onDelete}
-   * @see {client.SharedStateManagerClient#create}
-   * @see {server.SharedStateManagerClient#create}
-   * @see {client.SharedStateManagerClient#attach}
-   * @see {server.SharedStateManagerClient#attach}
-   */
-
-
-  async detach() {
-    this._subscriptions.clear();
-
-    if (this._isOwner) {
-      return new Promise((resolve, reject) => {
-        const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
-
-        this._client.transport.emit(`${_sharedStateUtils.DELETE_REQUEST}-${this.id}-${this.remoteId}`, reqId);
-      });
-    } else {
-      return new Promise((resolve, reject) => {
-        const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
-
-        this._client.transport.emit(`${_sharedStateUtils.DETACH_REQUEST}-${this.id}-${this.remoteId}`, reqId);
-      });
-    }
-  }
-  /**
-   * Delete the state. Only the creator/owner of the state (i.e. a state created using
-   * `create`) can use this method. If a non-owner call this method (i.e. a
-   * state created using `attach`), an error will be thrown.
-   *
-   * @async
-   * @see {common.SharedState#onDetach}
-   * @see {common.SharedState#onDelete}
-   * @see {client.SharedStateManagerClient#create}
-   * @see {server.SharedStateManagerClient#create}
-   * @see {client.SharedStateManagerClient#attach}
-   * @see {server.SharedStateManagerClient#attach}
-   */
-
 
-  async delete() {
-    if (this._isOwner) {
-      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`);
-    }
-  }
   /**
    * Register a function to execute when detaching from the state
    *
@@ -482,28 +453,21 @@ ${JSON.stringify(initValues, null, 2)}`);
    *   wether the client as called `detach`, or the state has been deleted by its
    *   creator.
    */
-
-
   onDetach(callback) {
     this._onDetachCallbacks.add(callback);
-
     return () => this._onDetachCallbacks.delete(callback);
   }
+
   /**
    * 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`
    *
    * @param {Function} callback - callback to execute when the state is deleted.
    */
-
-
   onDelete(callback) {
     this._onDeleteCallbacks.add(callback);
-
     return () => this._onDeleteCallbacks.delete(callback);
   }
-
 }
 
-var _default = SharedState;
-exports.default = _default;
+export default BaseSharedState;