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

package/src/common/{BaseSharedStateCollection.js → SharedStateCollection.js}

@@ -1,54 +1,85 @@
-/** @private */
-class BaseSharedStateCollection {
+/**
+ * @callback sharedStateCollectionOnUpdateCallback
+ * @param {SharedState} state - State that triggered the update.
+ * @param {Object} newValues - Key / value pairs of the updates that have been
+ *  applied to the state.
+ * @param {Object} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state.
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
+ *  with the values updates in the `set` call.
+ */
+
+/**
+ * The `SharedStateCollection` interface represent a collection of all states
+ * created from a given schema name on the network.
+ *
+ * It can optionnaly exclude the states created by the current node.
+ *
+ * See {@link ClientStateManager#getCollection} and
+ * {@link ServerStateManager#getCollection} for factory methods API
+ *
+ * ```
+ * const collection = await client.stateManager.getCollection('my-schema');
+ * const allValues = collection.getValues();
+ * collection.onUpdate((state, newValues, oldValues, context) => {
+ *   // do something
+ * });
+ * ```
+ * @hideconstructor
+ */
+class SharedStateCollection {
+  #stateManager = null;
+  #schemaName = null;
+  #filter = null;
+  #options = null;
+  #schema = null;
+  #states = [];
+  #onUpdateCallbacks = new Set();
+  #onAttachCallbacks = new Set();
+  #onDetachCallbacks = new Set();
+  #unobserve = null;
+
   constructor(stateManager, schemaName, filter = null, options = {}) {
-    this._stateManager = stateManager;
-    this._schemaName = schemaName;
-    this._filter = filter;
-    this._options = Object.assign({ excludeLocal: false }, options);
-
-    this._schema = null;
-    this._states = [];
-
-    this._onUpdateCallbacks = new Set();
-    this._onAttachCallbacks = new Set();
-    this._onDetachCallbacks = new Set();
-    this._unobserve = null;
+    this.#stateManager = stateManager;
+    this.#schemaName = schemaName;
+    this.#filter = filter;
+    this.#options = Object.assign({ excludeLocal: false }, options);
   }
 
   /** @private */
   async _init() {
-    this._schema = await this._stateManager.getSchema(this._schemaName);
+    this.#schema = await this.#stateManager.getSchema(this.#schemaName);
 
     // if filter is set, check that it contains only valid param names
-    if (this._filter !== null) {
-      const keys = Object.keys(this._schema);
+    if (this.#filter !== null) {
+      const keys = Object.keys(this.#schema);
 
-      for (let filter of this._filter) {
+      for (let filter of this.#filter) {
         if (!keys.includes(filter)) {
-          throw new ReferenceError(`[SharedStateCollection] Invalid filter key (${filter}) for schema "${this._schemaName}"`)
+          throw new ReferenceError(`[SharedStateCollection] Invalid filter key (${filter}) for schema "${this.#schemaName}"`)
         }
       }
     }
 
-    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId) => {
-      const state = await this._stateManager.attach(schemaName, stateId, this._filter);
-      this._states.push(state);
+    this.#unobserve = await this.#stateManager.observe(this.#schemaName, async (schemaName, stateId) => {
+      const state = await this.#stateManager.attach(schemaName, stateId, this.#filter);
+      this.#states.push(state);
 
       state.onDetach(() => {
-        const index = this._states.indexOf(state);
-        this._states.splice(index, 1);
+        const index = this.#states.indexOf(state);
+        this.#states.splice(index, 1);
 
-        this._onDetachCallbacks.forEach(callback => callback(state));
+        this.#onDetachCallbacks.forEach(callback => callback(state));
       });
 
       state.onUpdate((newValues, oldValues, context) => {
-        Array.from(this._onUpdateCallbacks).forEach(callback => {
+        Array.from(this.#onUpdateCallbacks).forEach(callback => {
           callback(state, newValues, oldValues, context);
         });
       });
 
-      this._onAttachCallbacks.forEach(callback => callback(state));
-    }, this._options);
+      this.#onAttachCallbacks.forEach(callback => callback(state));
+    }, this.#options);
   }
 
   /**
@@ -57,7 +88,7 @@ class BaseSharedStateCollection {
    * @readonly
    */
   get length() {
-    return this._states.length;
+    return this.#states.length;
   }
 
   /**
@@ -66,7 +97,7 @@ class BaseSharedStateCollection {
    * @readonly
    */
   get size() {
-    return this._states.length;
+    return this.#states.length;
   }
 
   /**
@@ -75,7 +106,7 @@ class BaseSharedStateCollection {
    * @readonly
    */
   get schemaName() {
-    return this._schemaName;
+    return this.#schemaName;
   }
 
   /**
@@ -91,10 +122,10 @@ class BaseSharedStateCollection {
    */
   getSchema(name = null) {
     if (name) {
-      return this._schema[name];
+      return this.#schema[name];
     }
 
-    return this._schema;
+    return this.#schema;
   }
 
   /**
@@ -106,8 +137,8 @@ class BaseSharedStateCollection {
    */
   getDefaults() {
     const defaults = {};
-    for (let name in this._schema) {
-      defaults[name] = this._schema[name].default;
+    for (let name in this.#schema) {
+      defaults[name] = this.#schema[name].default;
     }
     return defaults;
   }
@@ -117,7 +148,7 @@ class BaseSharedStateCollection {
    * @return {Object[]}
    */
   getValues() {
-    return this._states.map(state => state.getValues());
+    return this.#states.map(state => state.getValues());
   }
 
   /**
@@ -132,7 +163,7 @@ class BaseSharedStateCollection {
    * @return {Object[]}
    */
   getValuesUnsafe() {
-    return this._states.map(state => state.getValues());
+    return this.#states.map(state => state.getValues());
   }
 
   /**
@@ -144,7 +175,7 @@ class BaseSharedStateCollection {
   get(name) {
     // we can delegate to the state.get(name) method for throwing in case of filtered
     // keys, as the Promise.all will reject on first reject Promise
-    return this._states.map(state => state.get(name));
+    return this.#states.map(state => state.get(name));
   }
 
   /**
@@ -160,7 +191,7 @@ class BaseSharedStateCollection {
   getUnsafe(name) {
     // we can delegate to the state.get(name) method for throwing in case of filtered
     // keys, as the Promise.all will reject on first reject Promise
-    return this._states.map(state => state.get(name));
+    return this.#states.map(state => state.get(name));
   }
 
   /**
@@ -173,14 +204,14 @@ class BaseSharedStateCollection {
   async set(updates, context = null) {
     // we can delegate to the state.set(update) method for throwing in case of
     // filtered keys, as the Promise.all will reject on first reject Promise
-    const promises = this._states.map(state => state.set(updates, context));
+    const promises = this.#states.map(state => state.set(updates, context));
     return Promise.all(promises);
   }
 
   /**
    * Subscribe to any state update of the collection.
    *
-   * @param {server.SharedStateCollection~onUpdateCallback|client.SharedStateCollection~onUpdateCallback}
+   * @param {sharedStateCollectionOnUpdateCallback}
    *  callback - Callback to execute when an update is applied on a state.
    * @param {Boolean} [executeListener=false] - Execute the callback immediately
    *  for all underlying states with current state values. (`oldValues` will be
@@ -188,10 +219,10 @@ class BaseSharedStateCollection {
    * @returns {Function} - Function that delete the registered listener.
    */
   onUpdate(callback, executeListener = false) {
-    this._onUpdateCallbacks.add(callback);
+    this.#onUpdateCallbacks.add(callback);
 
     if (executeListener === true) {
-      this._states.forEach(state => {
+      this.#states.forEach(state => {
         const currentValues = state.getValues();
         const oldValues = {};
         const context = null;
@@ -200,7 +231,7 @@ class BaseSharedStateCollection {
       });
     }
 
-    return () => this._onUpdateCallbacks.delete(callback);
+    return () => this.#onUpdateCallbacks.delete(callback);
   }
 
   /**
@@ -214,12 +245,12 @@ class BaseSharedStateCollection {
    */
   onAttach(callback, executeListener = false) {
     if (executeListener === true) {
-      this._states.forEach(state => callback(state));
+      this.#states.forEach(state => callback(state));
     }
 
-    this._onAttachCallbacks.add(callback);
+    this.#onAttachCallbacks.add(callback);
 
-    return () => this._onAttachCallbacks.delete(callback);
+    return () => this.#onAttachCallbacks.delete(callback);
   }
 
   /**
@@ -230,9 +261,9 @@ class BaseSharedStateCollection {
    * @returns {Function} - Function that delete the registered listener.
    */
   onDetach(callback) {
-    this._onDetachCallbacks.add(callback);
+    this.#onDetachCallbacks.add(callback);
 
-    return () => this._onDetachCallbacks.delete(callback);
+    return () => this.#onDetachCallbacks.delete(callback);
   }
 
   /**
@@ -240,13 +271,13 @@ class BaseSharedStateCollection {
    * @type {number}
    */
   async detach() {
-    this._unobserve();
-    this._onUpdateCallbacks.clear();
+    this.#unobserve();
+    this.#onUpdateCallbacks.clear();
 
-    const promises = this._states.map(state => state.detach());
+    const promises = this.#states.map(state => state.detach());
     await Promise.all(promises);
 
-    this._onDetachCallbacks.clear();
+    this.#onDetachCallbacks.clear();
   }
 
   /**
@@ -256,7 +287,7 @@ class BaseSharedStateCollection {
    *  Its return value is discarded.
    */
   forEach(func) {
-    this._states.forEach(func);
+    this.#states.forEach(func);
   }
 
   /**
@@ -267,7 +298,7 @@ class BaseSharedStateCollection {
    *  Its return value is added as a single element in the new array.
    */
   map(func) {
-    return this._states.map(func);
+    return this.#states.map(func);
   }
 
   /**
@@ -279,7 +310,7 @@ class BaseSharedStateCollection {
    *  alsy value otherwise.
    */
   filter(func) {
-    return this._states.filter(func);
+    return this.#states.filter(func);
   }
 
   /**
@@ -288,7 +319,7 @@ class BaseSharedStateCollection {
    * @param {Function} func - Function that defines the sort order.
    */
   sort(func) {
-    this._states.sort(func);
+    this.#states.sort(func);
   }
 
   /**
@@ -300,7 +331,7 @@ class BaseSharedStateCollection {
    * @return {}
    */
   find(func) {
-    return this._states.find(func);
+    return this.#states.find(func);
   }
 
   /**
@@ -311,14 +342,14 @@ class BaseSharedStateCollection {
 
     return {
       next: () => {
-        if (index >= this._states.length) {
+        if (index >= this.#states.length) {
           return { value: undefined, done: true };
         } else {
-          return { value: this._states[index++], done: false };
+          return { value: this.#states[index++], done: false };
         }
       },
     };
   }
 }
 
-export default BaseSharedStateCollection;
+export default SharedStateCollection;

package/src/common/logger.js

@@ -164,6 +164,11 @@ dependencies on both your server and clients.
 
     console.error(chalk.red(msg));
   },
+
+  deprecated(oldAPI, newAPI) {
+    const msg = `[warning] '${oldAPI}' is deprecated and will be removed in next major version, please use '${newAPI}' instead`;
+    console.warn(chalk.yellow(msg));
+  }
 };
 
 export default logger;

package/src/common/shared-state-types.js

@@ -0,0 +1,76 @@
+/**
+ * User defined name for a class of {@link SharedState}
+ *
+ * @typedef {string} SharedStateClassName
+ */
+
+/**
+ * Description of a {@link SharedState} data structure that describes the structure
+ * of a class of {@link SharedState} to be registered by {@link ServerStateManager#registerSchema}
+ *
+ * A schema is the blueprint, or the definition from which shared states from a
+ * given class can be created.
+ *
+ * It consists of a set of key / value pairs where the key is the name of
+ * the parameter (cf. ${SharedStateParameterName}), and the value is an object
+ * describing the parameter (cf. ${SharedStateParameterDescription}).
+ *
+ * @typedef {Object.<SharedStateParameterName, SharedStateParameterDescription>} SharedStateClassSchema
+ *
+ * @example
+ * const mySchema = {
+ *   triggerSound: {
+ *     type: 'boolean',
+ *     event: true,
+ *   },
+ *   volume: {
+ *     type: 'float'
+ *     default: 0,
+ *     min: -80,
+ *     max: 6,
+ *   }
+ * };
+ *
+ * server.stateManager.registerSchema('my-class-name', mySchema);
+ */
+
+/**
+ * User defined name of a parameter in a class of {@link SharedState}
+ *
+ * @typedef {string} SharedStateParameterName
+ */
+
+/**
+ * Description of a parameter in a class of {@link SharedState}
+ *
+ * @typedef {object} SharedStateParameterDescription
+ * @property {'boolean'|'string'|'integer'|'float'|'enum'|'any'} type - Type of the parameter
+ * @property {any} default - Default value of the parameter. Optional only if
+ *  `nullable = true` or `event = true`
+ * @property {boolean} [nullable=false] - Defines if the parameter is nullable.
+ *   When `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, i.e.
+ *   its value only exists on an update and is set back to `null` after propagation.
+ *   When `true`, `nullable` is automatically set to `true` and `default` to `null`.
+  * @property {boolean} [filterChange=true] - When set to `false`, an update will
+ *   trigger the propagation of a parameter even when its value didn't change.
+ *   This option provides a sort of middle ground between the default bahavior
+ *   (e.g. where only changed values are propagated) and the behavior of the `event`
+ *   option (which has no state per se). Hence, setting this options to `false` if
+ *   `event=true` makes no sens.
+  * @property {boolean} [immediate=false] - When set to `true`, an update will
+ *   trigger the update listeners immediately on the node that generated the update,
+ *   before propagating the change on the network.
+ *   This option is usefull in cases the network would introduce a noticeable
+ *   latency on the client.
+ *   If for some reason the value is overriden server-side (e.g. in an `updateHook`)
+ *   the listeners will be called again when the "real" value is received.
+ * @property {number} [min=-Number.MIN_VALUE] - Minimum value of the parameter. Only applies
+ *   for `integer` and `float` types.
+ * @property {number} [max=Number.MAX_VALUE] - Maximum value of the parameter. Only applies
+ *   for `integer` and `float` types.
+ * @property {Array<any>} [list] - Possible values of the parameter. Only applies and
+ *   mandatory for `enum` type.
+ * @property {object} [metas={}] - Optional metadata of the parameter.
+ */
+

package/src/common/version.js

@@ -1,2 +1,2 @@
 // [WARNING] This file is generated, do not edit
-export default '4.0.0-alpha.27';
+export default '4.0.0-alpha.29';