@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/types/common/BaseStateManager.d.ts

@@ -1,70 +1,248 @@
+export const kStateManagerInit: unique symbol;
+export const kStateManagerDeleteState: unique symbol;
+export const kStateManagerClient: unique symbol;
 export default BaseStateManager;
 /**
- * @private
+ * Callback executed when a state is created on the network.
  */
+export type stateManagerObserveCallback = () => any;
+/**
+ * Callback to execute in order to remove a {@link stateManagerObserveCallback}
+ * from the list of observer.
+ */
+export type stateManagerDeleteObserveCallback = () => any;
+/**
+ * Callback executed when a state is created on the network.
+ *
+ * @callback stateManagerObserveCallback
+ * @async
+ * @param {string} className - name of the class
+ * @param {number} stateId - id of the state
+ * @param {number} nodeId - id of the node that created the state
+ */
+/**
+ * Callback to execute in order to remove a {@link stateManagerObserveCallback}
+ * from the list of observer.
+ *
+ * @callback stateManagerDeleteObserveCallback
+ */
+/** @private */
 declare class BaseStateManager {
     /**
-     * @param {Number} id - Id of the node.
-     * @param {Object} transport - Transport to use for synchronizing the state.
-     *  Must implement a basic EventEmitter API.
+     * Return a class description from a given class name
+     *
+     * @param {SharedStateClassName} className - Name of the shared state class.
+     *  (cf. ServerStateManager)
+     * @return {SharedStateClassDescription}
+     * @example
+     * const classDescription = await client.stateManager.getClassDescription('my-class');
      */
-    constructor(id: number, transport: any);
-    client: {
-        id: number;
-        transport: any;
-    };
-    _statesById: Map<any, any>;
-    _observeListeners: Set<any>;
-    _cachedSchemas: Map<any, any>;
-    _observeRequestCallbacks: Map<any, any>;
+    getClassDescription(className: SharedStateClassName): SharedStateClassDescription;
     /**
-     * Create a `SharedState` instance from a registered schema.
+     * @deprecated Use {@link BaseStateManager#getClassDescription} instead.
+     */
+    getSchema(className: any): Promise<any>;
+    /**
+     * Create a {@link SharedState} instance from a registered class.
      *
-     * @param {String} schemaName - Name of the schema as given on registration
-     *  (cf. ServerStateManager)
-     * @param {Object} [initValues={}] - Default values for the state.
-     * @returns {client.SharedState|server.SharedState}
-     * @see {@link client.SharedState}
-     * @see {@link server.SharedState}
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {Object.<string, any>} [initValues={}] - Default values of the created shared state.
+     * @returns {Promise<SharedState>}
      * @example
-     * const state = await client.stateManager.create('my-schema');
+     * const state = await client.stateManager.create('my-class');
      */
-    create(schemaName: string, initValues?: any): client.SharedState | server.SharedState;
+    create(className: SharedStateClassName, initValues?: {
+        [x: string]: any;
+    }): Promise<SharedState>;
     /**
-     * Attach to an existing `SharedState` instance.
+     * Attach to an existing {@link SharedState} instance.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the class.
+     * @returns {Promise<SharedState>}
      *
-     * @param {String} schemaName - Name of the schema as given on registration
-     *  (cf. ServerStateManager)
-     * @param {Object} [stateId=null] - Id of the state to attach to. If `null`,
-     *  attach to the first state found with the given schema name (usefull for
-     *  globally shared states owned by the server).
-     * @returns {client.SharedState|server.SharedState}
-     * @see {@link client.SharedState}
-     * @see {@link server.SharedState}
      * @example
-     * const state = await client.stateManager.attach('my-schema');
+     * const state = await client.stateManager.attach('my-class');
      */
-    attach(schemaName: string, stateId?: any): client.SharedState | server.SharedState;
+    attach(className: SharedStateClassName): Promise<SharedState>;
     /**
-     * Observe all the `SharedState` instances that are created on the network.
-     * This can be usefull for clients with some controller role that might want to track
-     * the state of all other clients of the application, to monitor them and/or take
-     * control over them from a single point.
+     * Attach to an existing {@link SharedState} instance.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {number} stateId - Id of the state
+     * @returns {Promise<SharedState>}
      *
-     * @todo Optionnal schema name
-     * @param {server.StateManager~ObserveCallback|client.StateManager~ObserveCallback}
-     *  callback - Function to be called when a new state is created on the network.
-     * @returns {Promise<Function>} - Return a Promise that resolves when the callback
-     *  as been executed for the first time. The promise value is a function which
-     *  allows to stop observing the network.
      * @example
-     * client.stateManager.observe(async (schemaName, stateId, nodeId) => {
-     *   if (schemaName === 'something') {
-     *     const state = await this.client.stateManager.attach(schemaName, stateId);
-     *     console.log(state.getValues());
+     * const state = await client.stateManager.attach('my-class', stateId);
+     */
+    attach(className: SharedStateClassName, stateId: number): Promise<SharedState>;
+    /**
+     * Attach to an existing {@link SharedState} instance.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {string[]} filter - List of parameters of interest
+     * @returns {Promise<SharedState>}
+     *
+     * @example
+     * const state = await client.stateManager.attach('my-class', ['some-param']);
+     */
+    attach(className: SharedStateClassName, filter: string[]): Promise<SharedState>;
+    /**
+     * Attach to an existing {@link SharedState} instance.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {number} stateId - Id of the state
+     * @param {string[]} filter - List of parameters of interest
+     * @returns {Promise<SharedState>}
+     *
+     * @example
+     * const state = await client.stateManager.attach('my-class', stateId, ['some-param']);
+     */
+    attach(className: SharedStateClassName, stateId: number, filter: string[]): Promise<SharedState>;
+    /**
+     * Observe all the {@link SharedState} instances that are created on the network.
+     *
+     * @overload
+     * @param {stateManagerObserveCallback} callback - Function to execute when a
+     *   new {@link SharedState} is created on the network.
+     * @example
+     * client.stateManager.observe(async (className, stateId) => {
+     *   if (className === 'my-shared-state-class') {
+     *     const attached = await client.stateManager.attach(className, stateId);
      *   }
      * });
      */
-    observe(callback: any): Promise<Function>;
+    observe(callback: stateManagerObserveCallback): any;
+    /**
+     * Observe all the {@link SharedState} instances of given {@link SharedStateClassName}
+     * that are created on the network.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Observe only ${@link SharedState}
+     *   of given name.
+     * @param {stateManagerObserveCallback} callback - Function to execute when a
+     *   new {@link SharedState} is created on the network.
+     * @example
+     * client.stateManager.observe('my-shared-state-class', async (className, stateId) => {
+     *   const attached = await client.stateManager.attach(className, stateId);
+     * });
+     */
+    observe(className: SharedStateClassName, callback: stateManagerObserveCallback): any;
+    /**
+     * Observe all the {@link SharedState} instances of given excluding the ones
+     * created by the current node.
+     *
+     * @overload
+     * @param {stateManagerObserveCallback} callback - Function to execute when a
+     *   new {@link SharedState} is created on the network.
+     * @param {object} options - Options.
+     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     *   created by the same node from the collection.
+     * @example
+     * client.stateManager.observe(async (className, stateId) => {
+     *   if (className === 'my-shared-state-class') {
+     *     const attached = await client.stateManager.attach(className, stateId);
+     *   }
+     * }, { excludeLocal: true });
+     */
+    observe(callback: stateManagerObserveCallback, options: {
+        excludeLocal: boolean;
+    }): any;
+    /**
+     * Observe all the {@link SharedState} instances of given {@link SharedStateClassName}
+     * that are created on the network, excluding the ones created by the current node.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Observe only ${@link SharedState}
+     *   of given name.
+     * @param {stateManagerObserveCallback} callback - Function to execute when a
+     *   new {@link SharedState} is created on the network.
+     * @param {object} options - Options.
+     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     *   created by the same node from the collection.
+     * @example
+     * client.stateManager.observe('my-shared-state-class', async (className, stateId) => {
+     *   const attached = await client.stateManager.attach(className, stateId);
+     * }, { excludeLocal: true });
+     */
+    observe(className: SharedStateClassName, callback: stateManagerObserveCallback, options: {
+        excludeLocal: boolean;
+    }): any;
+    /**
+     * Returns a collection of all the states created from a given shared state class.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the shared state class.
+     * @returns {Promise<SharedStateCollection>}
+     *
+     * @example
+     * const collection = await client.stateManager.getCollection(className);
+     */
+    getCollection(className: SharedStateClassName): Promise<SharedStateCollection>;
+    /**
+     * Returns a collection of all the states created from a given shared state class.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the shared state class.
+     * @param {SharedStateParameterName[]} filter - Filter parameter of interest for each
+     *  state of the collection.
+     * @returns {Promise<SharedStateCollection>}
+     *
+     * @example
+     * const collection = await client.stateManager.getCollection(className, ['my-param']);
+     */
+    getCollection(className: SharedStateClassName, filter: SharedStateParameterName[]): Promise<SharedStateCollection>;
+    /**
+     * Returns a collection of all the states created from a given shared state class.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the shared state class.
+     * @param {object} options - Options.
+     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     *  created by the same node from the collection.
+     * @returns {Promise<SharedStateCollection>}
+     *
+     * @example
+     * const collection = await client.stateManager.getCollection(className, { excludeLocal: true });
+     */
+    getCollection(className: SharedStateClassName, options: {
+        excludeLocal: boolean;
+    }): Promise<SharedStateCollection>;
+    /**
+     * Returns a collection of all the states created from a given shared state class.
+     *
+     * @overload
+     * @param {SharedStateClassName} className - Name of the shared state class.
+     * @param {SharedStateParameterName[]} filter - Filter parameter of interest for each
+     *  state of the collection.
+     * @param {object} options - Options.
+     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     *  created by the same node from the collection.
+     * @returns {Promise<SharedStateCollection>}
+     *
+     * @example
+     * const collection = await client.stateManager.getCollection(className, ['my-param'], { excludeLocal: true });
+     */
+    getCollection(className: SharedStateClassName, filter: SharedStateParameterName[], options: {
+        excludeLocal: boolean;
+    }): Promise<SharedStateCollection>;
+    /** @private */
+    private [kStateManagerDeleteState];
+    /**
+     * Executed on `client.init`
+     * @param {Number} id - Id of the node.
+     * @param {Object} transport - Transport to use for synchronizing the states.
+     *  Must implement a basic EventEmitter API.
+     *
+     * @private
+     */
+    private [kStateManagerInit];
+    /** @private */
+    private [kStateManagerClient];
+    #private;
 }
-//# sourceMappingURL=BaseStateManager.d.ts.map
+import SharedState from './SharedState.js';
+import SharedStateCollection from './SharedStateCollection.js';

package/types/common/BatchedTransport.d.ts

@@ -0,0 +1,17 @@
+export default BatchedTransport;
+/**
+ * This class proxies transports given the SharedStateManager to batch messages
+ *
+ * @param {number} [options.wait=0] - Wait for given number of milliseconds
+ *  for stacking messages before emitting on the network. If 0 is given, network
+ *  message is emitted on next microtask
+ * @private
+ */
+declare class BatchedTransport {
+    constructor(transport: any);
+    addListener(channel: any, callback: any): void;
+    emit(channel: any, ...args: any[]): Promise<void>;
+    removeListener(channel: any, callback: any): void;
+    removeAllListeners(channel?: any): void;
+    #private;
+}

package/types/common/ParameterBag.d.ts

@@ -1,126 +1,125 @@
 export namespace sharedOptions {
-    const nullable: boolean;
-    const event: boolean;
-    const metas: {};
-    const filterChange: boolean;
-    const immediate: boolean;
+    let nullable: boolean;
+    let event: boolean;
+    let required: boolean;
+    let metas: {};
+    let filterChange: boolean;
+    let immediate: boolean;
 }
 export namespace types {
     export namespace boolean {
-        const required: string[];
-        function coerceFunction(name: any, def: any, value: any): boolean;
+        let required_1: string[];
+        export { required_1 as required };
+        export const defaultOptions: any;
+        export function coerceFunction(name: any, def: any, value: any): boolean;
     }
     export namespace string {
-        const required_1: string[];
-        export { required_1 as required };
+        let required_2: string[];
+        export { required_2 as required };
+        const defaultOptions_1: any;
+        export { defaultOptions_1 as defaultOptions };
         export function coerceFunction_1(name: any, def: any, value: any): string;
         export { coerceFunction_1 as coerceFunction };
     }
     export namespace integer {
-        const required_2: string[];
-        export { required_2 as required };
-        export function sanitizeSchema(def: any): any;
+        let required_3: string[];
+        export { required_3 as required };
+        const defaultOptions_2: any;
+        export { defaultOptions_2 as defaultOptions };
+        export function sanitizeDescription(def: any): any;
         export function coerceFunction_2(name: any, def: any, value: any): number;
         export { coerceFunction_2 as coerceFunction };
     }
     export namespace float {
-        const required_3: string[];
-        export { required_3 as required };
-        export function sanitizeSchema_1(def: any): any;
-        export { sanitizeSchema_1 as sanitizeSchema };
+        let required_4: string[];
+        export { required_4 as required };
+        const defaultOptions_3: any;
+        export { defaultOptions_3 as defaultOptions };
+        export function sanitizeDescription_1(def: any): any;
+        export { sanitizeDescription_1 as sanitizeDescription };
         export function coerceFunction_3(name: any, def: any, value: any): number;
         export { coerceFunction_3 as coerceFunction };
     }
     export namespace _enum {
-        const required_4: string[];
-        export { required_4 as required };
+        let required_5: string[];
+        export { required_5 as required };
+        const defaultOptions_4: any;
+        export { defaultOptions_4 as defaultOptions };
         export function coerceFunction_4(name: any, def: any, value: any): any;
         export { coerceFunction_4 as coerceFunction };
     }
     export { _enum as enum };
     export namespace any {
-        const required_5: string[];
-        export { required_5 as required };
+        let required_6: string[];
+        export { required_6 as required };
+        const defaultOptions_5: any;
+        export { defaultOptions_5 as defaultOptions };
         export function coerceFunction_5(name: any, def: any, value: any): any;
         export { coerceFunction_5 as coerceFunction };
     }
 }
 export default ParameterBag;
-export namespace server {
+/** @private */
+declare class ParameterBag {
+    static validateDescription(description: any): void;
+    constructor(description: any, initValues?: {});
     /**
-     * ~schema
-     *
-     * Description of a schema to be register by the {@link server.ServerStateManagerServer }
-     * A schema consists of a combinaison of key value pairs where the key is the
-     * name of the parameter, and the value is an object describing the parameter.
+     * Define if the parameter exists.
      *
-     * Available types are:
-     * - {@link server.SharedStateManagerServer ~schemaBooleanDef}
-     * - {@link server.SharedStateManagerServer ~schemaStringDef}
-     * - {@link server.SharedStateManagerServer ~schemaIntegerDef}
-     * - {@link server.SharedStateManagerServer ~schemaFloatDef}
-     * - {@link server.SharedStateManagerServer ~schemaEnumDef}
-     * - {@link server.SharedStateManagerServer ~schemaAnyDef}
+     * @param {string} name - Name of the parameter.
+     * @return {Boolean}
      */
-    type SharedStateManagerServer = any;
-}
-/**
- * Bag of parameters.
- * @private
- */
-declare class ParameterBag {
-    static validateSchema(schema: any): void;
-    constructor(schema: any, initValues?: {});
+    has(name: string): boolean;
     /**
-     * List of parameters.
+     * Return values of all parameters as a flat object. If a parameter is of `any`
+     * type, a deep copy is made.
      *
-     * @type {Object<String, Param>}
-     * @name _params
-     * @memberof ParameterBag
-     * @instance
-     * @private
+     * @return {object}
      */
-    private _values;
+    getValues(): object;
     /**
-     * List of schema with init values.
+     * Return values of all parameters as a flat object. Similar to `getValues` but
+     * returns a reference to the underlying value in case of `any` type. May be
+     * useful 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.
      *
-     * @type {Object<String, paramDefinition>}
-     * @name _schema
-     * @memberof ParameterBag
-     * @instance
-     * @private
+     * @return {object}
      */
-    private _schema;
+    getValuesUnsafe(): object;
     /**
-     * Define if the parameter exists.
+     * Return the value of the given parameter. If the parameter is of `any` type,
+     * a deep copy is returned.
      *
-     * @param {String} name - Name of the parameter.
-     * @return {Boolean}
+     * @param {string} name - Name of the parameter.
+     * @return {Mixed} - Value of the parameter.
      */
-    has(name: string): boolean;
+    get(name: string): Mixed;
     /**
-     * Return values of all parameters as a flat object.
+     * Similar to `get` but returns a reference to the underlying value in case of
+     * `any` type. May be useful 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}
+     * @param {string} name - Name of the parameter.
+     * @return {Mixed} - Value of the parameter.
      */
-    getValues(): any;
+    getUnsafe(name: string): Mixed;
     /**
-     * Return the value of the given parameter. If the parameter is of `any` type,
-     * a deep copy is returned.
+     * Check that the value is valid according to the class definition and return it coerced.
      *
      * @param {String} name - Name of the parameter.
-     * @return {Mixed} - Value of the parameter.
+     * @param {Mixed} value - Value of the parameter.
      */
-    get(name: string): Mixed;
+    coerceValue(name: string, value: Mixed): Mixed;
     /**
      * Set the value of a parameter. If the value of the parameter is updated
      * (aka if previous value is different from new value) all registered
      * callbacks are registered.
      *
-     * @param {String} name - Name of the parameter.
+     * @param {string} name - Name of the parameter.
      * @param {Mixed} value - Value of the parameter.
-     * @param {Boolean} [forcePropagation=false] - if true, propagate value even
-     *    if the value has not changed.
      * @return {Array} - [new value, updated flag].
      */
     set(name: string, value: Mixed): any[];
@@ -129,15 +128,13 @@ declare class ParameterBag {
      * @note - prefer `state.set(state.getInitValues())`
      *         or     `state.set(state.getDefaultValues())`
      *
-     * @param {String} [name=null] - Name of the parameter to reset.
+     * @param {string} [name=null] - Name of the parameter to reset.
      */
     /**
-     * Return the given schema along with the initialization values.
-     *
-     * @return {Object}
+     * @return {object}
      */
-    getSchema(name?: any): any;
+    getDescription(name?: any): object;
     getInitValues(): {};
     getDefaults(): {};
+    #private;
 }
-//# sourceMappingURL=ParameterBag.d.ts.map

package/types/common/PromiseStore.d.ts

@@ -0,0 +1,11 @@
+/** @private */
+export default class PromiseStore {
+    constructor(name: any);
+    name: any;
+    store: Map<any, any>;
+    generateRequestId: any;
+    add(resolve: any, reject: any, type: any, localParams: any): any;
+    resolve(reqId: any, data: any): void;
+    reject(reqId: any, msg: any): void;
+    flush(): void;
+}