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

package/types/common/SharedState.d.ts

@@ -0,0 +1,297 @@
+export const kSharedStatePromiseStore: unique symbol;
+export default SharedState;
+/**
+ * Callback executed when updates are applied on a {@link SharedState }.
+ */
+export type sharedStateOnUpdateCallback = (newValues: any, oldValues: any, context?: Mixed) => any;
+/**
+ * Delete the registered {@link sharedStateOnUpdateCallback }.
+ */
+export type sharedStateDeleteOnUpdateCallback = () => any;
+/**
+ * Callback executed when updates are applied on a {@link SharedState}.
+ *
+ * @callback sharedStateOnUpdateCallback
+ * @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.
+ */
+/**
+ * Delete the registered {@link sharedStateOnUpdateCallback}.
+ *
+ * @callback sharedStateDeleteOnUpdateCallback
+ */
+/**
+ * The `SharedState` is one of the most important and versatile abstraction provided
+ * by `soundworks`. It represents a set of parameters that are synchronized accross
+ * every nodes of the application (clients and server) that declared some interest
+ * to the shared state.
+ *
+ * A `SharedState` instance is created according to a shared state class definition
+ * which is composed of a {@link SharedStateClassName} and of a {@link SharedStateClassSchema}
+ * registered in the {@link ServerStateManager}. Any number of `SharedState`s
+ * can be created from a single class definition.
+ *
+ * A shared state can be created both by the clients or by the server, in which case
+ * it is generally considered as a global state of the application. Similarly any
+ * node of the application (clients or server) can declare interest and "attach" to
+ * a state created by another node. All node attached to a state can modify its values
+ * and/or react to the modifications applied by other nodes.
+ *
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/server/index.js';
+ *
+ * const server = new Server(config);
+ * // define a shared state class
+ * 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);
+ * ```
+ */
+declare class SharedState {
+    constructor(id: any, remoteId: any, className: any, schema: any, client: any, isOwner: any, manager: any, initValues: any, filter: any);
+    /**
+     * Id of the state
+     * @type {Number}
+     */
+    get id(): number;
+    /**
+     * Name of the underlying {@link SharedState} class.
+     * @type {String}
+     * @deprecated
+     */
+    get schemaName(): string;
+    /**
+     * Name of the underlying {@link SharedState} class.
+     * @type {String}
+     */
+    get className(): string;
+    /**
+     * Indicates if the node is the owner of the state, i.e. if it created the state.
+     * @type {Boolean}
+     */
+    get isOwner(): boolean;
+    /**
+     * Update values of the state.
+     *
+     * The returned `Promise` resolves on an object that contains the applied updates,
+     * and resolves after all the `onUpdate` callbacks have resolved themselves, i.e.:
+     *
+     * ```js
+     * server.stateManager.registerSchema('test', {
+     *   myBool: { type: 'boolean', default: false },
+     * });
+     * const a = await server.stateManager.create('a');
+     *
+     * let asyncCallbackCalled = false;
+     *
+     * a.onUpdate(updates => {
+     *   return new Promise(resolve => {
+     *     setTimeout(() => {
+     *       asyncCallbackCalled = true;
+     *       resolve();
+     *     }, 100);
+     *   });
+     * });
+     *
+     * const updates = await a.set({ myBool: true });
+     * assert.equal(asyncCallbackCalled, true);
+     * assert.deepEqual(updates, { myBool: true });
+     * ```
+     *
+     * @param {object} updates - Key / value pairs of updates to apply to the state.
+     * @param {mixed} [context=null] - Optionnal contextual object 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 all update listeners.
+     * @returns {Promise<Object>} A promise to the (coerced) updates.
+     *
+     * @example
+     * const state = await client.stateManager.attach('globals');
+     * const updates = await state.set({ myParam: Math.random() });
+     */
+    set(updates: object, context?: mixed): Promise<any>;
+    /**
+     * Get the value of a parameter of the state.
+     *
+     * Be aware that in case of 'any' typethe returned value is deeply copied.
+     * While this prevents from pollution of the state by mutating the reference,
+     * this can also lead to performance issues when the parameter contains large
+     * data. In such cases you should use the {@link SharedState#getUnsafe} method
+     * and make sure to treat the returned object as readonly.
+     *
+     * @param {SharedStateParameterName} name - Name of the param.
+     * @return {any}
+     * @throws Throws if `name` does not exists.
+     * @example
+     * const value = state.get('paramName');
+     */
+    get(name: SharedStateParameterName): any;
+    /**
+     * Get an unsafe reference to the value of a parameter of the state.
+     *
+     * Similar to `get` but returns a reference to the underlying value in case of
+     * `any` type. Can be usefull if the underlying value is large (e.g. sensors
+     * recordings, etc.) and deep cloning expensive. Be aware that if changes are
+     * made on the returned object, the state of your application will become
+     * inconsistent.
+     *
+     * @param {SharedStateParameterName} name - Name of the param.
+     * @return {any}
+     * @throws Throws if `name` does not exists.
+     * @example
+     * const value = state.getUnsafe('paramName');
+     */
+    getUnsafe(name: SharedStateParameterName): any;
+    /**
+     * Get all the key / value pairs of the state.
+     *
+     * If a parameter is of `any` type, a deep copy is made.
+     *
+     * @return {object}
+     * @example
+     * const values = state.getValues();
+     */
+    getValues(): object;
+    /**
+     * Get all the key / value pairs of the state.
+     *
+     * Similar to `getValues` but returns a reference to the underlying value in
+     * case of `any` type. Can be usefull if the underlying value is big (e.g.
+     * sensors recordings, etc.) and deep cloning expensive. Be aware that if
+     * changes are made on the returned object, the state of your application will
+     * become inconsistent.
+     *
+     * @return {object}
+     * @example
+     * const values = state.getValues();
+     */
+    getValuesUnsafe(): object;
+    /**
+     * Return the underlying {@link SharedStateClassSchema} or the
+     * {@link SharedStateParameterDescription} if name is given.
+     *
+     * @param {string} [name] - If defined, returns only the parameter description
+     *  of the given param name.
+     * @return {SharedStateClassSchema|SharedStateParameterDescription}
+     * @throws Throws if `name` does not exists.
+     * @example
+     * const schema = state.getSchema();
+     */
+    getSchema(name?: string): SharedStateClassSchema | SharedStateParameterDescription;
+    /**
+     * Get the values with which the state has been created. May defer from the
+     * default values declared in the schema.
+     *
+     * @return {object}
+     * @example
+     * const initValues = state.getInitValues();
+     */
+    getInitValues(): object;
+    /**
+     * Get the default values as declared in the schema.
+     *
+     * @return {object}
+     * @example
+     * const defaults = state.getDefaults();
+     */
+    getDefaults(): object;
+    /**
+     * Detach from the state. If the client is the creator of the state, the state
+     * is deleted and all attached nodes get notified.
+     *
+     * @example
+     * const state = await client.state.attach('globals');
+     * // later
+     * await state.detach();
+     */
+    detach(): Promise<any>;
+    /**
+     * Delete the state. Only the creator/owner of the state can use this method.
+     *
+     * All nodes attached to the state will be detached, triggering any registered
+     * `onDetach` callbacks. The creator of the state will also have its own `onDelete`
+     * callback triggered. The local `onDeatch` and `onDelete` callbacks will be
+     * executed *before* the returned Promise resolves
+     *
+     * @throws Throws if the method is called by a node which is not the owner of
+     * the state.
+     * @example
+     * const state = await client.state.create('my-schema-name');
+     * // later
+     * await state.delete();
+     */
+    delete(): Promise<any>;
+    /**
+     * Subscribe to state updates.
+     *
+     * @param {sharedStateOnUpdateCallback} callback
+     *  Callback to execute when an update is applied on the state.
+     * @param {Boolean} [executeListener=false] - Execute the callback immediately
+     *  with current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
+     * @returns {sharedStateDeleteOnUpdateCallback}
+     * @example
+     * const unsubscribe = state.onUpdate(async (newValues, oldValues, context) =>  {
+     *   for (let [key, value] of Object.entries(newValues)) {
+     *      switch (key) {
+     *        // do something
+     *      }
+     *   }
+     * });
+     *
+     * // later
+     * unsubscribe();
+     */
+    onUpdate(listener: any, executeListener?: boolean): sharedStateDeleteOnUpdateCallback;
+    /**
+     * Register a function to execute when detaching from the state. The function
+     * will be executed before the `detach` promise resolves.
+     *
+     * @param {Function} callback - Callback to execute when detaching from the state.
+     *   Whether the client as called `detach`, or the state has been deleted by its
+     *   creator.
+     */
+    onDetach(callback: Function): () => boolean;
+    /**
+     * 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` and executed
+     * before the `delete` Promise resolves.
+     *
+     * @param {Function} callback - Callback to execute when the state is deleted.
+     */
+    onDelete(callback: Function): () => boolean;
+    /** @private */
+    private [kSharedStatePromiseStore];
+    #private;
+}

package/types/common/{BaseSharedStateCollection.d.ts → SharedStateCollection.d.ts}

@@ -1,19 +1,35 @@
-export default BaseSharedStateCollection;
-/** @private */
-declare class BaseSharedStateCollection {
+export default SharedStateCollection;
+export type sharedStateCollectionOnUpdateCallback = (state: SharedState, newValues: any, oldValues: any, context?: Mixed) => any;
+/**
+ * @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
+ */
+declare class SharedStateCollection {
     constructor(stateManager: any, schemaName: any, filter?: any, options?: {});
-    _stateManager: any;
-    _schemaName: any;
-    _filter: any;
-    _options: {
-        excludeLocal: boolean;
-    };
-    _schema: any;
-    _states: any[];
-    _onUpdateCallbacks: Set<any>;
-    _onAttachCallbacks: Set<any>;
-    _onDetachCallbacks: Set<any>;
-    _unobserve: any;
     /** @private */
     private _init;
     /**
@@ -100,14 +116,14 @@ declare class BaseSharedStateCollection {
     /**
      * 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
      *  set to `{}`, and `context` to `null`)
      * @returns {Function} - Function that delete the registered listener.
      */
-    onUpdate(callback: any, executeListener?: boolean): Function;
+    onUpdate(callback: sharedStateCollectionOnUpdateCallback, executeListener?: boolean): Function;
     /**
      * Register a function to execute when a state is added to the collection.
      *
@@ -179,5 +195,5 @@ declare class BaseSharedStateCollection {
             done: boolean;
         };
     };
+    #private;
 }
-//# sourceMappingURL=BaseSharedStateCollection.d.ts.map

package/types/common/constants.d.ts

@@ -1,6 +1,5 @@
 export const SERVER_ID: -1;
 export const PING_INTERVAL: number;
-export const PING_LATENCY_TOLERANCE: 1000;
 export const PING_MESSAGE: "h:ping";
 export const PONG_MESSAGE: "h:pong";
 export const BATCHED_TRANSPORT_CHANNEL: "b:t";
@@ -41,4 +40,3 @@ export const CLIENT_HANDSHAKE_RESPONSE: "cl:h:res";
 export const CLIENT_HANDSHAKE_ERROR: "cl:h:err";
 export const AUDIT_STATE_NAME: "p:s:audit";
 export const PRIVATE_STATES: string[];
-//# sourceMappingURL=constants.d.ts.map

package/types/common/logger.d.ts

@@ -9,8 +9,9 @@ declare namespace logger {
     function pluginStarted(name: any): void;
     function pluginReady(name: any): void;
     function pluginErrored(name: any): void;
+    function warnVersionDiscepancies(clientRole: any, clientVersion: any, serverVersion: any): void;
     function log(msg: any): void;
     function warn(msg: any): void;
     function error(msg: any): void;
+    function deprecated(oldAPI: any, newAPI: any): void;
 }
-//# sourceMappingURL=logger.d.ts.map

package/types/common/shared-state-types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * User defined name for a class of {@link SharedState }
+ */
+type SharedStateClassName = string;
+/**
+ * Description of a {@link SharedState } data structure that describes the structure
+ * of a class of {@link SharedState } to be registered by {@link ServerStateManagerregisterSchema }
+ *
+ * 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}).
+ */
+type SharedStateClassSchema = any;
+/**
+ * User defined name of a parameter in a class of {@link SharedState }
+ */
+type SharedStateParameterName = string;
+/**
+ * Description of a parameter in a class of {@link SharedState }
+ */
+type SharedStateParameterDescription = {
+    /**
+     * - Type of the parameter
+     */
+    type: 'boolean' | 'string' | 'integer' | 'float' | 'enum' | 'any';
+    /**
+     * - Default value of the parameter. Optional only if
+     * `nullable = true` or `event = true`
+     */
+    default: any;
+    /**
+     * - Defines if the parameter is nullable.
+     * When `true` the parameter `default` is set to `null`.
+     */
+    nullable?: boolean;
+    /**
+     * - 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`.
+     */
+    event?: boolean;
+    /**
+     * - 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.
+     */
+    filterChange?: boolean;
+    /**
+     * - 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.
+     */
+    immediate?: boolean;
+    /**
+     * - Minimum value of the parameter. Only applies
+     * for `integer` and `float` types.
+     */
+    min?: number;
+    /**
+     * - Maximum value of the parameter. Only applies
+     * for `integer` and `float` types.
+     */
+    max?: number;
+    /**
+     * - Possible values of the parameter. Only applies and
+     * mandatory for `enum` type.
+     */
+    list?: Array<any>;
+    /**
+     * - Optional metadata of the parameter.
+     */
+    metas?: object;
+};

package/types/common/sockets-utils.d.ts

@@ -1,9 +1,4 @@
 /** @private */
-export function packBinaryMessage(channel: any, data: any): ArrayBufferLike;
-/** @private */
-export function unpackBinaryMessage(buffer: any): any[];
-/** @private */
 export function packStringMessage(channel: any, ...args: any[]): string;
 /** @private */
 export function unpackStringMessage(data: any): any;
-//# sourceMappingURL=sockets-utils.d.ts.map

package/types/common/version.d.ts

@@ -1,3 +1,2 @@
-declare const _default: "4.0.0-alpha.22";
+declare const _default: "4.0.0-alpha.29";
 export default _default;
-//# sourceMappingURL=version.d.ts.map