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

package/types/server/StateManager.d.ts

@@ -1,16 +1,241 @@
 export default StateManager;
 export namespace server {
     /**
-     * ~ObserveCallback
+     * ~schema
+     *
+     * Description of a schema to be registered by the {@link server.StateManagerregisterSchema }
+     *
+     * A schema is the blueprint, or definition from which shared states can be created.
+     *
+     * It consists of a set of key / value pairs where the key is the name of
+     * the parameter, and the value is an object describing the parameter.
+     *
+     * The value can be of any of the foolowing types:
+     * - {@link server.StateManager ~schemaBooleanDefinition}
+     * - {@link server.StateManager ~schemaStringDefinition}
+     * - {@link server.StateManager ~schemaIntegerDefinition}
+     * - {@link server.StateManager ~schemaFloatDefinition}
+     * - {@link server.StateManager ~schemaEnumDefinition}
+     * - {@link server.StateManager ~schemaAnyDefinition}
      */
-    type StateManager = () => any;
+    type StateManager = object;
 }
+/**
+ * @typedef {object} server.StateManager~schema
+ *
+ * Description of a schema to be registered by the {@link server.StateManager#registerSchema}
+ *
+ * A schema is the blueprint, or definition from which shared states can be created.
+ *
+ * It consists of a set of key / value pairs where the key is the name of
+ * the parameter, and the value is an object describing the parameter.
+ *
+ * The value can be of any of the foolowing types:
+ * - {@link server.StateManager~schemaBooleanDefinition}
+ * - {@link server.StateManager~schemaStringDefinition}
+ * - {@link server.StateManager~schemaIntegerDefinition}
+ * - {@link server.StateManager~schemaFloatDefinition}
+ * - {@link server.StateManager~schemaEnumDefinition}
+ * - {@link server.StateManager~schemaAnyDefinition}
+ *
+ * @example
+ * const mySchema = {
+ *   triggerSound: {
+ *     type: 'boolean',
+ *     event: true,
+ *   },
+ *   volume: {
+ *     type: 'float'
+ *     default: 0,
+ *     min: -80,
+ *     max: 6,
+ *   }
+ * };
+ *
+ * server.stateManager.registerSchema('my-schema-name', mySchema);
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "boolean" type.
+ *
+ * @typedef {object} server.StateManager~schemaBooleanDefinition
+ * @property {string} type='boolean' - Define a boolean parameter.
+ * @property {boolean} default - Default value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind 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). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be 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 on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "string" type.
+ *
+ * @typedef {object} server.StateManager~schemaStringDefinition
+ * @property {string} type='string' - Define a boolean parameter.
+ * @property {string} default - Default value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind 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). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be 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 on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "integer" type.
+ *
+ * @typedef {object} server.StateManager~schemaIntegerDefinition
+ * @property {string} type='integer' - Define a boolean parameter.
+ * @property {number} default - Default value of the parameter.
+ * @property {number} [min=-Infinity] - Minimum value of the parameter.
+ * @property {number} [max=+Infinity] - Maximum value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind 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). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be 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 on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "float" type.
+ *
+ * @typedef {object} server.StateManager~schemaFloatDefinition
+ * @property {string} [type='float'] - Float parameter.
+ * @property {number} default - Default value.
+ * @property {number} [min=-Infinity] - Minimum value.
+ * @property {number} [max=+Infinity] - Maximum value.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind 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). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be 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 on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "enum" type.
+ *
+ * @typedef {object} server.StateManager~schemaEnumDefinition
+ * @property {string} [type='enum'] - Enum parameter.
+ * @property {string} default - Default value of the parameter.
+ * @property {Array} list - Possible values of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind 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). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be 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 on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
+/**
+ * Describe a {@link server.StateManager~schema} entry of "any" type.
+ *
+ * Note that the `any` type always return a shallow copy of the state internal
+ * value. Mutating the returned value will therefore not modify the internal state.
+ *
+ * @typedef {object} server.StateManager~schemaAnyDefinition
+ * @property {string} [type='any'] - Parameter of any type.
+ * @property {*} default - Default value of the parameter.
+ * @property {boolean} [nullable=false] - Define if the parameter is nullable. If
+ *   set to `true` the parameter `default` is set to `null`.
+ * @property {boolean} [event=false] - Define if the parameter is a volatile, e.g.
+ *   set its value back to `null` after propagation. When `true`, `nullable` is
+ *   automatically set to `true` and `default` to `null`.
+ * @property {boolean} [filterChange=true] - Setting this option to `false` forces
+ *   the propagation of a parameter even when its value do not change. It
+ *   offers a kind 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). As such, setting this options to `false` if
+ *   `event=true` does not make sens.
+ * @property {boolean} [immediate=false] - Setting this option to `true` will
+ *   trigger any change (e.g. call the `onUpdate` listeners) immediately on the
+ *   state that generate the update (i.e. calling `set`), before propagating the
+ *   change on the network. This option can be 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 on when the "real" / final value will be received.
+ * @property {object} [metas={}] - Optionnal metadata of the parameter.
+ */
 /**
  * @callback server.StateManager~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
+ * @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
+ */
+/**
+ * @callback server.StateManager~updateHook
+ * @async
+ *
+ * @param {object} updates - Update object as given on a set callback, or
+ *  result of the previous hook
+ * @param {object} currentValues - Current values of the state.
+ * @param {object} [context=null] - Optionnal context passed by the creator
+ *  of the update.
+ *
+ * @return {object} The "real" updates to be applied on the state.
  */
 /**
  * The `StateManager` allows to create new {@link server.SharedState}s, or attach
@@ -71,9 +296,8 @@ export namespace server {
  * @hideconstructor
  */
 declare class StateManager extends BaseStateManager {
-    constructor();
     _clientByNodeId: Map<any, any>;
-    _serverStatesById: Map<any, any>;
+    _sharedStatePrivateById: Map<any, any>;
     _schemas: Map<any, any>;
     _observers: Set<any>;
     _hooksBySchemaName: Map<any, any>;
@@ -82,10 +306,10 @@ declare class StateManager extends BaseStateManager {
      *
      * This is automatically handled by the {@link server.Server} when a client connects.
      *
-     * @param {Number} nodeId - Id of the client node, as given in
+     * @param {number} nodeId - Id of the client node, as given in
      *  {@link client.StateManager}
-     * @param {Object} transport - Tranpsort mecanism to communicate with the
-     *  client. Should implement a basic EventEmitter API.
+     * @param {object} transport - Transport mecanism to communicate with the
+     *  client. Must implement a basic EventEmitter API.
      *
      * @private
      */
@@ -95,7 +319,7 @@ declare class StateManager extends BaseStateManager {
      *
      * This is automatically handled by the {@link server.Server} when a client disconnects.
      *
-     * @param {Number} nodeId - Id of the client node, as given in
+     * @param {number} nodeId - Id of the client node, as given in
      *  {@link client.StateManager}
      *
      * @private
@@ -105,7 +329,7 @@ declare class StateManager extends BaseStateManager {
      * Register a schema from which shared states (cf. {@link common.SharedState})
      * can be instanciated.
      *
-     * @param {String} schemaName - Name of the schema.
+     * @param {string} schemaName - Name of the schema.
      * @param {server.StateManager~schema} schema - Data structure
      *  describing the states that will be created from this schema.
      *
@@ -129,25 +353,14 @@ declare class StateManager extends BaseStateManager {
     registerSchema(schemaName: string, schema: any): void;
     /**
      * Delete a schema and all associated states.
+     *
      * When a schema is deleted, all states created from this schema are deleted
      * as well, therefore all attached clients are detached and the `onDetach`
      * and `onDelete` callbacks are called on the related states.
      *
-     * @param {String} schemaName - Name of the schema.
+     * @param {string} schemaName - Name of the schema.
      */
     deleteSchema(schemaName: string): void;
-    /**
-     * @callback server.StateManager~updateHook
-     * @async
-     *
-     * @param {Object} updates - Update object as given on a set callback, or
-     *  result of the previous hook
-     * @param {Object} currentValues - Current values of the state.
-     * @param {Object} [context=null] - Optionnal context passed by the creator
-     *  of the update.
-     *
-     * @return {Object} The "real" updates to be applied on the state.
-     */
     /**
      * Register a function for a given schema (e.g. will be applied on all states
      * created from this schema) that will be executed before the update values
@@ -160,7 +373,7 @@ declare class StateManager extends BaseStateManager {
      * server-side regarless the node on which `set` has been called and before
      * the "actual" update of the state (e.g. before the call of `onUpdate`).
      *
-     * @param {String} schemaName - Kind of states on which applying the hook.
+     * @param {string} schemaName - Kind of states on which applying the hook.
      * @param {server.StateManager~updateHook} updateHook - Function
      *   called between the `set` call and the actual update.
      *
@@ -185,6 +398,8 @@ declare class StateManager extends BaseStateManager {
      * assert.deepEqual(result, { name: 'test', numUpdates: 1 });
      */
     registerUpdateHook(schemaName: string, updateHook: any): Fuction;
+    [kIsObservableState](state: any): boolean;
 }
-import BaseStateManager from "../common/BaseStateManager.js";
+import BaseStateManager from '../common/BaseStateManager.js';
+declare const kIsObservableState: unique symbol;
 //# sourceMappingURL=StateManager.d.ts.map

package/types/server/StateManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StateManager.d.ts","sourceRoot":"","sources":["../../src/server/StateManager.js"],"names":[],"mappings":";;;;;;;AA4BA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH;IACE,cAcC;IAPC,+BAAgC;IAChC,iCAAkC;IAClC,wBAAyB;IACzB,qBAA2B;IAC3B,kCAAmC;IAKrC;;;;;;;;;;;OAWG;IACH,kBA6GC;IAED;;;;;;;;;OASG;IACH,qBAgCC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,sDAUC;IAED;;;;;;;OAOG;IACH,uCAqBC;IAED;;;;;;;;;;;OAWG;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,iEAUC;CAEF"}
+{"version":3,"file":"StateManager.d.ts","sourceRoot":"","sources":["../../src/server/StateManager.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;wBAkCa,MAAM;;AADnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH;IAII,+BAAgC;IAChC,uCAAwC;IACxC,wBAAyB;IACzB,qBAA2B;IAC3B,kCAAmC;IAerC;;;;;;;;;;;OAWG;IACH,kBA4KC;IAED;;;;;;;;;OASG;IACH,qBAoCC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,2BArBW,MAAM,qBAuChB;IAED;;;;;;;;OAQG;IACH,yBAFW,MAAM,QAwBhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,+BAxBW,MAAM,4BAkChB;IA5WD,0CAIC;CAyWF;6BAlrB4B,+BAA+B;AA4B5D,gDAAqE"}

package/types/server/audit-network-latency.worker.d.ts

@@ -1,2 +1,3 @@
-export {};
+declare const _default: "\nconst { parentPort } = require('node:worker_threads');\n\nlet stack = [];\nlet averageLatencyWindow = 5;\nlet averageLatencyPeriod = 2;\n\nlet intervalId = null;\nlet meanLatency = 0;\n\nlet getTime;\nlet inited = new Promise(async (resolve) => {\n  module = await import('@ircam/sc-utils');\n  getTime = module.getTime;\n  resolve(true);\n});\n\nparentPort.on('message', async msg => {\n  switch (msg.type) {\n    case 'config': {\n      averageLatencyWindow = msg.value.averageLatencyWindow;\n      averageLatencyPeriod = msg.value.averageLatencyPeriod;\n\n      await inited;\n\n      // launch compute in its own loop so that the number of computation is\n      // decoupled from the number of connected clients\n      clearInterval(intervalId);\n      intervalId = setInterval(computeAverageLatency, averageLatencyPeriod * 1000);\n      break;\n    }\n    case 'add-measurement': {\n      // compute latency considering ping and pong time are equal\n      const entry = msg.value;\n      entry.latency = (entry.pong - entry.ping) / 2;\n      // add new measure to the stack\n      stack.push(entry);\n    }\n  }\n});\n\nfunction computeAverageLatency() {\n  const now = getTime();\n  // remove old measurements from stack\n  stack = stack.filter(entry => entry.pong >= now - averageLatencyWindow);\n\n  // prevent dividing by zero, just return last computed value\n  if (stack.length === 0) {\n    parentPort.postMessage({\n      type: 'computed-average-latency',\n      value: meanLatency,\n    });\n  } else {\n    // compute mean\n    let sum = 0;\n    stack.forEach(entry => sum += entry.latency);\n\n    meanLatency = sum / stack.length;\n    // send result to main thread\n    parentPort.postMessage({\n      type: 'computed-average-latency',\n      value: meanLatency,\n    });\n  }\n}\n";
+export default _default;
 //# sourceMappingURL=audit-network-latency.worker.d.ts.map

package/types/server/audit-schema.d.ts

@@ -1,25 +1,25 @@
 declare namespace _default {
     namespace numClients {
-        export const type: string;
-        const _default: {};
+        export let type: string;
+        let _default: {};
         export { _default as default };
     }
     namespace averageNetworkLatency {
-        const type_1: string;
+        let type_1: string;
         export { type_1 as type };
-        const _default_1: number;
+        let _default_1: number;
         export { _default_1 as default };
     }
     namespace averageNetworkLatencyWindow {
-        const type_2: string;
+        let type_2: string;
         export { type_2 as type };
-        const _default_2: number;
+        let _default_2: number;
         export { _default_2 as default };
     }
     namespace averageNetworkLatencyPeriod {
-        const type_3: string;
+        let type_3: string;
         export { type_3 as type };
-        const _default_3: number;
+        let _default_3: number;
         export { _default_3 as default };
     }
 }

package/types/server/crypto.d.ts

@@ -0,0 +1,3 @@
+export function encryptData(obj: any): string;
+export function decryptData(encryptedData: any): any;
+//# sourceMappingURL=crypto.d.ts.map

package/types/server/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/server/crypto.js"],"names":[],"mappings":"AAuBA,8CAKC;AAED,qDAMC"}

package/types/server/index.d.ts

@@ -1,7 +1,3 @@
 export { default as Server } from "./Server.js";
 export { default as Context } from "./Context.js";
-/**
- * Configuration object for the server.
- */
-export type ServerConfig = any;
 //# sourceMappingURL=index.d.ts.map

package/types/common/promise-store.d.ts

@@ -1,4 +0,0 @@
-export function storeRequestPromise(resolve: any, reject: any): number | void;
-export function resolveRequest(reqId: any, data: any): void;
-export function rejectRequest(reqId: any, data: any): void;
-//# sourceMappingURL=promise-store.d.ts.map

package/types/common/promise-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"promise-store.d.ts","sourceRoot":"","sources":["../../src/common/promise-store.js"],"names":[],"mappings":"AAKA,8EAKC;AAED,4DAKC;AAED,2DAKC"}

package/types/common/utils.d.ts

@@ -1,5 +0,0 @@
-export function idGenerator(): Generator<number, void, unknown>;
-export function isString(val: any): boolean;
-export function isFunction(func: any): boolean;
-export const isBrowser: Function;
-//# sourceMappingURL=utils.d.ts.map

package/types/common/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/common/utils.js"],"names":[],"mappings":"AAGA,gEAQC;AAED,4CAEC;AAED,+CAGC;AAnBD,iCAA6F"}