@soundworks/core 3.6.0 → 4.0.0-alpha.0

package/common/SharedState.js

@@ -1,480 +0,0 @@
-"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 }; }
-
-// -----------------------------------------------------------
-// define a common namespace...
-// -----------------------------------------------------------
-
-/**
- * Representation of a shared state. The class and its instances are the same
- * client-side and server-side.
- *
- * @memberof common
- *
- * @see {client.SharedStateManagerClient}
- * @see {server.SharedStateManagerServer}
- */
-class SharedState {
-  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
-
-    this._client = client;
-    this._manager = manager;
-
-    try {
-      this._parameters = new _ParameterBag.default(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();
-    this._onDetachCallbacks = new Set();
-    this._onDeleteCallbacks = new Set(); // add listener for state updates
-
-    client.transport.addListener(`${_sharedStateUtils.UPDATE_RESPONSE}-${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
-
-    client.transport.addListener(`${_sharedStateUtils.UPDATE_ABORT}-${id}-${this.remoteId}`, async (reqId, updates, context) => {
-      const updated = await this._commit(updates, context, false, true);
-      (0, _sharedStateUtils.resolveRequest)(reqId, updated);
-    });
-    client.transport.addListener(`${_sharedStateUtils.UPDATE_NOTIFICATION}-${id}-${this.remoteId}`, async (updates, context) => {
-      // cf. https://github.com/collective-soundworks/soundworks/issues/18
-      await this._commit(updates, context, true, false);
-    }); // ---------------------------------------------
-    // DELETE initiated by creator, or schema deleted
-    // ---------------------------------------------
-
-    client.transport.addListener(`${_sharedStateUtils.DELETE_NOTIFICATION}-${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)
-      // ---------------------------------------------
-      client.transport.addListener(`${_sharedStateUtils.DELETE_RESPONSE}-${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);
-      });
-      client.transport.addListener(`${_sharedStateUtils.DELETE_ERROR}-${id}`, (reqId, msg) => {
-        (0, _sharedStateUtils.rejectRequest)(reqId, msg);
-      });
-    } else {
-      // ---------------------------------------------
-      // DETACH
-      // ---------------------------------------------
-      client.transport.addListener(`${_sharedStateUtils.DETACH_RESPONSE}-${id}-${this.remoteId}`, reqId => {
-        this._manager._statesById.delete(this.id);
-
-        this._clearTransport();
-
-        this._onDetachCallbacks.forEach(func => func());
-
-        this._clearDetach();
-
-        (0, _sharedStateUtils.resolveRequest)(reqId, this);
-      }); // the state does not exists anymore in the server (should not happen)
-
-      client.transport.addListener(`${_sharedStateUtils.DETACH_ERROR}-${id}`, (reqId, msg) => {
-        (0, _sharedStateUtils.rejectRequest)(reqId, msg);
-      });
-    }
-  }
-
-  _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`);
-    };
-  }
-
-  _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}`);
-  }
-  /** @private */
-
-
-  async _commit(updates, context, propagate = true, initiator = false) {
-    const newValues = {};
-    const oldValues = {};
-
-    for (let name in updates) {
-      const {
-        immediate,
-        filterChange,
-        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]); // 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`
-        // to avoid retrigger listeners.
-        // If the value has been overriden by the server, `changed` will true
-        // anyway so it should behave correctly.
-        if (!changed || event) {
-          continue;
-        }
-      }
-
-      newValues[name] = newValue;
-      oldValues[name] = oldValue;
-    } // 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 => {
-        promises.push(listener(newValues, oldValues, context));
-      });
-    }
-
-    await Promise.all(promises); // reset events to null after propagation of all listeners
-
-    for (let name in newValues) {
-      const {
-        event
-      } = this._parameters.getSchema(name);
-
-      if (event) {
-        this._parameters.set(name, null);
-      }
-    }
-
-    return newValues;
-  }
-  /**
-   * Updates values of the state. Wait for all subscriptions to be resolved
-   * before resolving itself, i.e.:
-   *
-   * ```js
-   * const a = await server.stateManager.create('a');
-   * let asyncCallbackCalled = false;
-   *
-   * a.subscribe(updates => {
-   *   return new Promise(resolve => {
-   *     setTimeout(() => {
-   *       asyncCallbackCalled = true;
-   *       resolve();
-   *     }, 100);
-   *   });
-   * });
-   *
-   * await a.set({ bool: true });
-   * assert.equal(asyncCallbackCalled, 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
-   *   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}
-   */
-
-
-  async set(updates, context = null) {
-    // 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}"`);
-      } // @note: general idea...
-      // 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)
-      //  - 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);
-
-      if (immediate) {
-        const oldValue = this._parameters.get(name);
-
-        const [newValue, changed] = this._parameters.set(name, updates[name]);
-
-        if (changed || filterChange === false || event) {
-          immediateOldValues[name] = oldValue;
-          immediateNewValues[name] = newValue;
-          propagateNow = true;
-        }
-      }
-    }
-
-    if (propagateNow) {
-      this._subscriptions.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);
-    });
-  }
-  /**
-   * Get a value of the state by its name
-   *
-   * @param {String} name - Name of the param. Throws an error if the name is invalid.
-   * @return {Mixed}
-   */
-
-
-  get(name) {
-    return this._parameters.get(name);
-  }
-  /**
-   * Get a all the key / value pairs of the state.
-   *
-   * @return {Object}
-   */
-
-
-  getValues() {
-    return this._parameters.getValues();
-  }
-  /**
-   * Get the schema that describes the state.
-   *
-   * @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}
-   */
-
-
-  getSchema(name = null) {
-    return this._parameters.getSchema(name);
-  }
-  /**
-   * Get the values with which the state has been initialized.
-   *
-   * @return {Object}
-   */
-
-
-  getInitValues() {
-    return this._parameters.getInitValues();
-  }
-  /**
-   * Get the default values that has been declared in the schema.
-   *
-   * @return {Object}
-   */
-
-
-  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.
-   *
-   * @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}
-   */
-
-  /**
-   * Subscribe to state updates
-   *
-   * @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`)
-   *
-   * @example
-   * state.subscribe(async (newValues, oldValues) =>  {
-   *   for (let [key, value] of Object.entries(newValues)) {
-   *      switch (key) {
-   *        // do something
-   *      }
-   *   }
-   * });
-   */
-
-
-  subscribe(listener, executeListener = false) {
-    this._subscriptions.add(listener);
-
-    if (executeListener === true) {
-      const currentValues = this.getValues();
-      const oldValues = {};
-      const context = null;
-      listener(currentValues, oldValues, context);
-    }
-
-    return () => {
-      this._subscriptions.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
-   *
-   * @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
-   *   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;

package/common/SharedStateManagerClient.js

@@ -1,194 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _SharedState = _interopRequireDefault(require("./SharedState.js"));
-
-var _sharedStateUtils = require("./shared-state-utils.js");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-/**
- * Component dedicated at managing distributed states, accessible through {@link common.SharedState} instances, among the application.
- *
- * An instance of `SharedStateManagerClient` is automatically created by the
- * `soundworks.Client` at initialization (cf. {@link client.Client#stateManager}).
- *
- * Tutorial: [https://collective-soundworks.github.io/tutorials/state-manager.html](https://collective-soundworks.github.io/tutorials/state-manager.html)
- *
- * @memberof client
- * @see {@link common.SharedState}
- * @see {@link server.SharedStateManagerServer}
- * @see {@link client.Client#stateManager}
- */
-class SharedStateManagerClient {
-  /**
-   * @param {Number} id - Id of the node.
-   * @param {Object} transport - Transport to use for synchronizing the state.
-   *  Must implement a basic EventEmitter API.
-   */
-  constructor(id, transport) {
-    this.client = {
-      id,
-      transport
-    };
-    this._statesById = new Map();
-    this._observeListeners = new Set();
-    this._cachedSchemas = new Map();
-    this._observeRequestCallbacks = new Map(); // ---------------------------------------------
-    // CREATE
-    // ---------------------------------------------
-
-    this.client.transport.addListener(_sharedStateUtils.CREATE_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, initValues) => {
-      // cache schema when first dealing it to save some bandwidth
-      if (!this._cachedSchemas.has(schemaName)) {
-        this._cachedSchemas.set(schemaName, schema);
-      }
-
-      schema = this._cachedSchemas.get(schemaName);
-      const state = new _SharedState.default(stateId, remoteId, schemaName, schema, this.client, true, this, initValues);
-
-      this._statesById.set(state.id, state);
-
-      (0, _sharedStateUtils.resolveRequest)(reqId, state);
-    });
-    this.client.transport.addListener(_sharedStateUtils.CREATE_ERROR, (reqId, msg) => {
-      (0, _sharedStateUtils.rejectRequest)(reqId, msg);
-    }); // ---------------------------------------------
-    // ATTACH (when creator, is attached by default)
-    // ---------------------------------------------
-
-    this.client.transport.addListener(_sharedStateUtils.ATTACH_RESPONSE, (reqId, stateId, remoteId, schemaName, schema, currentValues) => {
-      // cache schema when first dealing with it to save some bandwidth
-      // note: when we make the schemas dynamic at some point
-      // the server should be able to invalidate the schema and send
-      // it again despite the caching.
-      if (!this._cachedSchemas.has(schemaName)) {
-        this._cachedSchemas.set(schemaName, schema);
-      }
-
-      schema = this._cachedSchemas.get(schemaName);
-      const state = new _SharedState.default(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues);
-
-      this._statesById.set(state.id, state);
-
-      (0, _sharedStateUtils.resolveRequest)(reqId, state);
-    });
-    this.client.transport.addListener(_sharedStateUtils.ATTACH_ERROR, (reqId, msg) => {
-      (0, _sharedStateUtils.rejectRequest)(reqId, msg);
-    }); // ---------------------------------------------
-    // OBSERVE PEERS (be notified when a state is created, lazy)
-    // ---------------------------------------------
-
-    this.client.transport.addListener(_sharedStateUtils.OBSERVE_RESPONSE, (reqId, ...list) => {
-      // retrieve the callback that have been stored in observe to make sure
-      // we don't call another callback that may have been registered earlier.
-      const callback = this._observeRequestCallbacks.get(reqId);
-
-      this._observeRequestCallbacks.delete(reqId);
-
-      list.forEach(([schemaName, stateId, nodeId]) => {
-        callback(schemaName, stateId, nodeId);
-      });
-      (0, _sharedStateUtils.resolveRequest)(reqId, list);
-    });
-    this.client.transport.addListener(_sharedStateUtils.OBSERVE_NOTIFICATION, (...list) => {
-      list.forEach(([schemaName, stateId, nodeId]) => {
-        this._observeListeners.forEach(callback => callback(schemaName, stateId, nodeId));
-      });
-    }); // ---------------------------------------------
-    // Clear cache when schema is deleted
-    // ---------------------------------------------
-
-    this.client.transport.addListener(_sharedStateUtils.DELETE_SCHEMA, schemaName => {
-      this._cachedSchemas.delete(schemaName);
-    });
-  }
-  /**
-   * Create a {@link common.SharedState} instance from a previsouly registered schema.
-   *
-   * @see {@link common.SharedState}
-   *
-   * @param {String} schemaName - Name of the schema as given on registration
-   *  (cf. ServerStateManager)
-   * @param {Object} [initValues={}] - Default values for the state.
-   *
-   * @return {@link common.SharedState}
-   */
-
-
-  async create(schemaName, initValues = {}) {
-    return new Promise((resolve, reject) => {
-      const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
-      const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
-      this.client.transport.emit(_sharedStateUtils.CREATE_REQUEST, reqId, schemaName, requireSchema, initValues);
-    });
-  }
-  /**
-   * Attach to an existing {@link common.SharedState} instance.
-   *
-   * @see {@link common.SharedState}
-   *
-   * @param {String} schemaName - Name of the schema as given on registration
-   *  (cf. ServerStateManager)
-   * @param {Object} [stateId=null] - Id of the state to attach to. If `null`,
-   *  attach to the first state found with the given schema name (usefull for
-   *  globally shared states owned by the server).
-   *
-   * @return {@link common.SharedState}
-   */
-
-
-  async attach(schemaName, stateId = null) {
-    return new Promise((resolve, reject) => {
-      // @todo - add a timeout
-      const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject);
-      const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
-      this.client.transport.emit(_sharedStateUtils.ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema);
-    });
-  }
-  /**
-   * @callback client.SharedStateManagerClient~observeCallback
-   * @async
-   * @param {String} schemaName - name of the schema
-   * @param {Number} stateId - id of the state
-   * @param {Number} nodeId - id of the node that created the state
-   */
-
-  /**
-   * Observe all the {@link common.SharedState} instances that are created on the network.
-   *
-   * @param {client.SharedStateManagerClient~observeCallback} callback - Function
-   *  to be called when a new state is created on the network.
-   *
-   * @example
-   * this.client.stateManager.observe(async (schemaName, stateId, nodeId) => {
-   *   if (schemaName === 'something') {
-   *     const state = await this.client.stateManager.attach(schemaName, stateId);
-   *     console.log(state.getValues());
-   *   }
-   * });
-   */
-
-
-  observe(callback) {
-    this._observeListeners.add(callback); // store function
-
-
-    new Promise((resolve, reject) => {
-      const reqId = (0, _sharedStateUtils.storeRequestPromise)(resolve, reject); // store the callback to be executed on the response
-
-      this._observeRequestCallbacks.set(reqId, callback);
-
-      this.client.transport.emit(_sharedStateUtils.OBSERVE_REQUEST, reqId);
-    });
-    return () => this._observeListeners.delete(callback);
-  }
-
-}
-
-var _default = SharedStateManagerClient;
-exports.default = _default;