@soundworks/core 3.6.0 → 4.0.0-alpha.0

package/types/server/StateManager.d.ts

@@ -0,0 +1,190 @@
+export default StateManager;
+export namespace server {
+    /**
+     * ~ObserveCallback
+     */
+    type StateManager = () => any;
+}
+/**
+ * @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
+ */
+/**
+ * The `StateManager` allows to create new {@link server.SharedState}s, or attach
+ * to {@link server.SharedState}s created by other nodes (clients or server). It
+ * can also track all the {@link server.SharedState}s created by other nodes.
+ *
+ * An instance of `StateManager` is automatically created by the `soundworks.Server`
+ * at initialization (cf. {@link server.Server#stateManager}).
+ *
+ * Compared to the {@link client.StateManager}, the `server.StateManager` can also
+ * create and delete schemas, as well as register update hook that are executed when
+ * a state is updated.
+ *
+ * See {@link server.Server#stateManager}
+ *
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/server/index.js';
+ *
+ * const server = new Server(config);
+ * // declare and register the schema of a shared state.
+ * server.stateManager.registerSchema('some-global-state', {
+ *   myRandom: {
+ *     type: 'float',
+ *     default: 0,
+ *   }
+ * });
+ *
+ * await server.start();
+ *
+ * // create a global state server-side
+ * const globalState = await server.stateManager.create('some-global-state');
+ * // listen and react to the changes made by the clients
+ * globalState.onUpdate(updates => console.log(updates));
+ * ```
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/client.index.js';
+ *
+ * const client = new Client(config);
+ * await client.start();
+ *
+ * // attach to the global state created by the server
+ * const globalState = await client.stateManager.attach('some-global-state');
+ *
+ * // update the value of a `myRandom` parameter every seconds
+ * setInterval(() => {
+ *   globalState.set({ myRandom: Math.random() });
+ * }, 1000);
+ * ```
+ *
+ * @memberof server
+ * @extends BaseStateManager
+ * @inheritdoc
+ * @hideconstructor
+ */
+declare class StateManager extends BaseStateManager {
+    constructor();
+    _clientByNodeId: Map<any, any>;
+    _serverStatesById: Map<any, any>;
+    _schemas: Map<any, any>;
+    _observers: Set<any>;
+    _hooksBySchemaName: Map<any, any>;
+    /**
+     * Add a client to the manager.
+     *
+     * This is automatically handled by the {@link server.Server} when a client connects.
+     *
+     * @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.
+     *
+     * @private
+     */
+    private addClient;
+    /**
+     * Remove a client from the manager. Clean all created or attached states.
+     *
+     * This is automatically handled by the {@link server.Server} when a client disconnects.
+     *
+     * @param {Number} nodeId - Id of the client node, as given in
+     *  {@link client.StateManager}
+     *
+     * @private
+     */
+    private removeClient;
+    /**
+     * Register a schema from which shared states (cf. {@link common.SharedState})
+     * can be instanciated.
+     *
+     * @param {String} schemaName - Name of the schema.
+     * @param {server.StateManager~schema} schema - Data structure
+     *  describing the states that will be created from this schema.
+     *
+     * @see {@link server.StateManager#create}
+     * @see {@link client.StateManager#create}
+     *
+     * @example
+     * server.stateManager.registerSchema('my-schema', {
+     *   myBoolean: {
+     *     type: 'boolean'
+     *     default: false,
+     *   },
+     *   myFloat: {
+     *     type: 'float'
+     *     default: 0.1,
+     *     min: -1,
+     *     max: 1
+     *   }
+     * })
+     */
+    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.
+     */
+    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
+     * are propagated. For example, this could be used to implement a preset system
+     * where all the values of the state are updated from e.g. some data stored in
+     * filesystem while the consumer of the state only want to update the preset name.
+     *
+     * The hook is associated to every state of its kind (i.e. schemaName) and
+     * executed on every update (call of `set`). Note that the hooks are executed
+     * 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 {server.StateManager~updateHook} updateHook - Function
+     *   called between the `set` call and the actual update.
+     *
+     * @returns {Fuction} deleteHook - Handler that deletes the hook when executed.
+     *
+     * @example
+     * server.stateManager.registerSchema('hooked', {
+     *   name: { type: 'string', default: null, nullable: true },
+     *   name: { numUpdates: 'integer', default: 0 },
+     * });
+     * server.stateManager.registerUpdateHook('hooked', updates => {
+     *   return {
+     *     ...updates
+     *     numUpdates: currentValues.numUpdates + 1,
+     *   };
+     * });
+     *
+     * const state = await server.stateManager.create('hooked');
+     *
+     * await state.set({ name: 'test' });
+     * const values = state.getValues();
+     * assert.deepEqual(result, { name: 'test', numUpdates: 1 });
+     */
+    registerUpdateHook(schemaName: string, updateHook: any): Fuction;
+}
+import BaseStateManager from "../common/BaseStateManager.js";
+//# sourceMappingURL=StateManager.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=audit-network-latency.worker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit-network-latency.worker.d.ts","sourceRoot":"","sources":["../../src/server/audit-network-latency.worker.js"],"names":[],"mappings":""}

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

@@ -0,0 +1,27 @@
+declare namespace _default {
+    namespace numClients {
+        export const type: string;
+        const _default: {};
+        export { _default as default };
+    }
+    namespace averageNetworkLatency {
+        const type_1: string;
+        export { type_1 as type };
+        const _default_1: number;
+        export { _default_1 as default };
+    }
+    namespace averageNetworkLatencyWindow {
+        const type_2: string;
+        export { type_2 as type };
+        const _default_2: number;
+        export { _default_2 as default };
+    }
+    namespace averageNetworkLatencyPeriod {
+        const type_3: string;
+        export { type_3 as type };
+        const _default_3: number;
+        export { _default_3 as default };
+    }
+}
+export default _default;
+//# sourceMappingURL=audit-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit-schema.d.ts","sourceRoot":"","sources":["../../src/server/audit-schema.js"],"names":[],"mappings":""}

package/types/server/index.d.ts

@@ -0,0 +1,7 @@
+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/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.js"],"names":[],"mappings":""}

package/client/AbstractExperience.js

@@ -1,54 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _debug = _interopRequireDefault(require("debug"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-const log = (0, _debug.default)('soundworks:lifecycle');
-/**
- * Base class to extend for implementing a client of a soundworks application.
- *
- * @memberof client
- */
-
-class AbstractExperience {
-  constructor(client) {
-    // @todo - check that it's a soundworks instance
-    if (!client) {
-      throw new Error(`${this.constructor.name} should receive the "Client" instance as first argument`);
-    }
-
-    this.client = client;
-  }
-  /**
-   * Require a registered plugin.
-   * @see {client.PluginManager#register}
-   *
-   * @param {String} name - Name of the plugin as given when registered.
-   */
-
-
-  require(name) {
-    return this.client.pluginManager.get(name, true);
-  }
-  /**
-   * Start the experience. This lifecycle method is called by the soundworks
-   * client when all the required plugins are `ready` and thus the `Experience``
-   * can start with all the necessary informations and plugins ready to be consumed.
-   */
-
-
-  start() {
-    log(`> experience "${this.constructor.name}" start`);
-    this.client.socket.send('s:exp:enter');
-  }
-
-}
-
-var _default = AbstractExperience;
-exports.default = _default;

package/client/AbstractPlugin.js

@@ -1,230 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _debug = _interopRequireDefault(require("debug"));
-
-var _lodash = _interopRequireDefault(require("lodash.merge"));
-
-var _Signal = _interopRequireDefault(require("../common/Signal.js"));
-
-var _SignalAll = _interopRequireDefault(require("../common/SignalAll.js"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-const log = (0, _debug.default)('soundworks:lifecycle');
-/**
- * Base class to extend for implementing a new plugin.
- *
- * A plugin should always be provided wrapped in a factory function to allow for
- * dynamically extend this class and avoid circular dependencies.
- *
- * @example
- * function myPluginFactory(AbstractPlugin) {
- *   class MyPlugin extends AbstractPlugin {
- *     constructor(client, name, options) {
- *       super(client, name);
- *       // ...
- *     }
- *
- *     async start() {
- *       await ...
- *       this.started();
- *       await ...
- *       this.ready();
- *     }
- *   }
- *
- *   return MyPlugin;
- * }
- * // then register the factory
- * client.pluginManager.register('my-plugin', myPluginFactory, { options }, []);
- *
- * @param {client.Client} client - instance of the soundworks Client
- * @param {String} name - user defined name of the plugin
- *
- * @memberof client
- */
-
-class AbstractPlugin {
-  constructor(client, name) {
-    if (!client) {
-      throw new Error(`[plugin] 1rst argument should be an instance of Client`);
-    }
-
-    if (!name) {
-      throw new Error(`[plugin] 2nd argument should be a valid name`);
-    }
-    /**
-     * Instance of the soundworks client
-     * @see {client.Client}
-     * @type {String}
-     */
-
-
-    this.client = client;
-    /**
-     * Name of the plugin, as defined on registration.
-     * @type {String}
-     */
-
-    this.name = name;
-    /**
-     * Options of the plugin.
-     * @type {Object}
-     */
-
-    this.options = {};
-    /**
-     * Signals defining the process state.
-     * @type {Object}
-     */
-
-    /** @private */
-
-    this.signals = {
-      start: new _SignalAll.default(),
-      started: new _Signal.default(),
-      ready: new _Signal.default(),
-      errored: new _Signal.default() // @needs a payload
-
-    }; // start when all required signals are fired
-
-    this.signals.start.addObserver(value => this.start());
-    this.started = this.started.bind(this);
-    this.ready = this.ready.bind(this);
-    this.error = this.error.bind(this);
-  }
-  /**
-   * Helper function to merge default options and user-defined options.
-   *
-   * @example
-   * this.options = this.configure(defaults, options);
-   */
-
-
-  configure(defaults, options) {
-    return (0, _lodash.default)({}, defaults, options);
-  }
-  /**
-   * Interface method to override when implementing child class.
-   *
-   * _Important: the derived class MUST call {@link client.AbstractPlugin#started}
-   * and {@link client.AbstractPlugin#ready} to notify soundworks about the
-   * state of the plugin_
-   *
-   * @see {client.AbstractPlugin#started}
-   * @see {client.AbstractPlugin#ready}
-   *
-   * @example
-   * class MyDelayPlugin extends AbstractPlugin {
-   *   // ...
-   *   async start() {
-   *     this.state = await this.client.stateManager.attach(`s:${this.name}`);
-   *     this.started();
-   *     // do [async] stuff
-   *     setTimeout(() => this.ready(), 3000);
-   *   }
-   * }
-   */
-
-
-  start() {
-    throw new Error(`plugin "${this.name}": "start()" not implemented or "super.start()" called`);
-  }
-  /**
-   * Lifecyle method to call in the {@link client.AbstractPlugin#start} method
-   * when the plugin is effectively started, as it may have to
-   * do some asynchonous job at start (e.g. creating a shared state, waiting for
-   * user input, etc.).
-   *
-   * _Must be called between before {@link client.AbstractPlugin#ready}._
-   *
-   * @see {client.AbstractPlugin#start}
-   * @see {client.AbstractPlugin#ready}
-   *
-   * @example
-   * class MyDelayPlugin extends AbstractPlugin {
-   *   // start() is executed when the `start` signal pass to `true`
-   *   async start() {
-   *     this.state = await this.client.stateManager.attach(`s:${this.name}`);
-   *     this.started();
-   *     // do [async] stuff
-   *     setTimeout(() => this.ready(), 3000);
-   *   }
-   * }
-   */
-
-
-  started() {
-    // @note - these check are mostly there for development help. Could be
-    // replaced with decorators.
-    if (this.signals.start.value === false) {
-      throw new Error(`plugin "${this.name}" cannot "started" before "start"`);
-    }
-
-    if (this.signals.started.value === true) {
-      throw new Error(`plugin "${this.name}" cannot be "started" twice`);
-    } // @note - this as no strong incidence on the initialization lifecycle,
-    // maybe should be enforced
-
-
-    log(`> plugin "${this.name}" started`);
-    this.signals.started.value = true;
-  }
-  /**
-   * Lifecyle method to call in the {@link client.AbstractPlugin#start} method
-   * when the plugin has completely finished its initialization should be
-   * considered as ready. Calling this method notify soundworks that the
-   * initialization process can continue or that the application can start
-   * safely (cf. {@link client.AbstractExperience#start})
-   *
-   * @see {client.AbstractPlugin#start}
-   * @see {client.AbstractPlugin#started}
-   * @see {client.AbstractExperience#start}
-   *
-   * @example
-   * class MyDelayPlugin extends AbstractPlugin {
-   *   // ...
-   *   async start() {
-   *     this.state = await this.client.stateManager.attach(`s:${this.name}`);
-   *     this.started();
-   *     // do [async] stuff
-   *     setTimeout(() => this.ready(), 3000);
-   *   }
-   * }
-   */
-
-
-  ready() {
-    // @note - these check are mostly there for development help. Could be
-    // replaced with decorators.
-    if (this.signals.start.value === false) {
-      throw new Error(`plugin "${this.name}" cannot "ready" before "start"`);
-    }
-
-    if (this.signals.started.value === false) {
-      throw new Error(`plugin "${this.name}" cannot "ready" before "started"`);
-    }
-
-    if (this.signals.ready.value === true) {
-      throw new Error(`plugin "${this.name}" cannot be "ready" twice`);
-    }
-
-    log(`> plugin "${this.name}" ready`);
-    this.signals.ready.value = true;
-  }
-
-  error(msg) {
-    log(`> plugin "${this.name}" error: ${msg}`);
-    this.signals.errored.msg = msg;
-    this.signals.errored.value = true;
-  }
-
-}
-
-var _default = AbstractPlugin;
-exports.default = _default;