@soundworks/core 4.0.0-alpha.9 → 5.0.0

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

@@ -0,0 +1,82 @@
+/**
+ * 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#defineClass}
+ *
+ * A `SharedStateClassDescription` 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>} SharedStateClassDescription
+ *
+ * @example
+ * const myClassDescription = {
+ *   triggerSound: {
+ *     type: 'boolean',
+ *     event: true,
+ *   },
+ *   volume: {
+ *     type: 'float'
+ *     default: 0,
+ *     min: -80,
+ *     max: 6,
+ *   }
+ * };
+ *
+ * server.stateManager.defineClass('my-class-name', myClassDescription);
+ */
+
+/**
+ * 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 behavior
+ *   (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 useful in cases the network would introduce a noticeable
+ *   latency on the client.
+ *   If for some reason the value is overridden server-side (e.g. in an `updateHook`)
+ *   the listeners will be called again when the "real" value is received.
+ * @property {boolean} [required=false] - When set to true, the parameter must be
+ *   provided in the initialization values when the state is created.
+ * @property {boolean} [local=false] - When set to true, the parameter is never
+ *   propagated on the network (hence it is no longer a shared parameter :). This
+ *   is useful to declare some common parameter (e.g. some interface state) that
+ *   don't need to be shared but to stay in the shared state API paradigm.
+ * @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/sockets-utils.js

@@ -1,67 +1,3 @@
-import 'fast-text-encoding';
-import root from 'window-or-global';
-
-const encoder = new root.TextEncoder('utf-8');
-const decoder = new root.TextDecoder('utf-8');
-
-const types = [
-  'Int8Array',
-  'Uint8Array',
-  'Uint8ClampedArray',
-  'Int16Array',
-  'Uint16Array',
-  'Int32Array',
-  'Uint32Array',
-  'Float32Array',
-  'Float64Array',
-  'BigInt64Array',
-  'BigUint64Array',
-];
-
-// @note - probably some room for optimizations
-
-/** @private */
-export function packBinaryMessage(channel, data) {
-  const channelBuffer = encoder.encode(channel);
-  const channelSize = channelBuffer.byteLength;
-  const startOffset = Math.ceil((channelSize + 3) / data.BYTES_PER_ELEMENT) * data.BYTES_PER_ELEMENT;
-  const bufferSize = startOffset + data.byteLength;
-  const typeName = data.constructor.name;
-  const typeIndex = types.indexOf(typeName);
-
-  if (typeIndex === -1) {
-    throw new Error(`Invalid TypedArray type: ${typeName}`);
-  }
-
-  const view = new Uint8Array(bufferSize);
-  view[0] = channelSize;
-  view[1] = typeIndex;
-  view[2] = startOffset;
-
-  view.set(channelBuffer, 3, channelSize);
-  view.set(new Uint8Array(data.buffer), startOffset, data.byteLength);
-
-  return view.buffer;
-}
-
-/** @private */
-export function unpackBinaryMessage(buffer /* arraybuffer */) {
-  const infos = new Uint8Array(buffer, 0, 3);
-  const channelSize = infos[0];
-  const typeIndex = infos[1];
-  const startOffset = infos[2];
-
-  // need to slice as the library recreates a UInt8Array from the whole buffer
-  // @todo - see if this copy could be avoided (probably needs a pull request)
-  const channelBuffer = new Uint8Array(buffer.slice(3, 3 + channelSize));
-  const channel = decoder.decode(channelBuffer);
-  const type = types[typeIndex];
-  // slice (copy) the underlying ArrayBuffer to create a clean TypedArray
-  const data = new root[type](buffer.slice(startOffset));
-
-  return [channel, data];
-}
-
 /** @private */
 export function packStringMessage(channel, ...args) {
   return JSON.stringify([channel, args]);

package/src/common/version.js

@@ -0,0 +1,2 @@
+// [WARNING] This file is generated, do not edit
+export default '5.0.0';