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

package/types/client/{PluginManager.d.ts → ClientPluginManager.d.ts}

@@ -1,29 +1,9 @@
-export default PluginManager;
-export namespace client {
-    /**
-     * ~onStateChangeCallback
-     */
-    type PluginManager = (: object, initiator: client.Plugin | null) => any;
-}
-/**
- * Callback executed when a plugin internal state is updated.
- *
- * @callback client.PluginManager~onStateChangeCallback
- * @param {object<client.Plugin#id, client.Plugin>} fullState - List of all plugins.
- * @param {client.Plugin|null} initiator - Plugin that initiated the update or `null`
- *  if the change was initiated by the state manager (i.e. when the initialization
- *  of the plugins starts).
- */
-/**
- * Delete the registered {@link client.PluginManager~onStateChangeCallback}.
- *
- * @callback client.PluginManager~deleteOnStateChangeCallback
- */
+export default ClientPluginManager;
 /**
  * The `PluginManager` allows to register and retrieve `soundworks` plugins.
  *
  * Plugins should always be registered both client-side and server-side,
- * and before {@link client.Client#start} or {@link server.Server#start}
+ * and before {@link Client#start} or {@link Server#start}
  * to be properly initialized.
  *
  * In some sitautions, you might want to register the same plugin factory several times
@@ -33,7 +13,7 @@ export namespace client {
  * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
  * for more informations on the available plugins.
  *
- * See {@link client.Client#pluginManager}
+ * See {@link Client#pluginManager}
  *
  * ```
  * // client-side
@@ -73,17 +53,15 @@ export namespace client {
  * }, 1000);
  * ```
  *
- * @memberof client
  * @extends BasePluginManager
  * @inheritdoc
  * @hideconstructor
  */
-declare class PluginManager extends BasePluginManager {
+declare class ClientPluginManager extends BasePluginManager {
     /**
-     * @param {client.Client} client - The soundworks client instance.
+     * @param {Client} client - The soundworks client instance.
      */
-    constructor(client: client.Client);
-    register(id: any, factory: any, options?: {}, deps?: any[]): void;
+    constructor(client: Client);
     /**
      * Retrieve an fully started instance of a registered plugin.
      *
@@ -97,15 +75,14 @@ declare class PluginManager extends BasePluginManager {
      * on the `onStateChange` method.
      *
      * _Note: the async API is designed to enable the dynamic creation of plugins
-     * (hopefully without brealing changes) in a future release._
-     *
-     * @param {client.Plugin#id} id - Id of the plugin as defined when registered.
-     * @returns {client.Plugin}
-     * @see {@link client.PluginManager#onStateChange}
+     * in a future release._
      *
-     * @private
+     * @param {string} id - Id of the plugin as defined when registered.
+     * @returns {Promise<ClientPlugin>}
+     * @see {@link ClientPluginManager#onStateChange}
      */
-    private get;
+    get(id: string): Promise<ClientPlugin>;
 }
 import BasePluginManager from '../common/BasePluginManager.js';
-//# sourceMappingURL=PluginManager.d.ts.map
+import ClientPlugin from './ClientPlugin.js';
+import Client from './Client.js';

package/types/client/ClientSocket.d.ts

@@ -0,0 +1,74 @@
+export const kSocketTerminate: unique symbol;
+export default ClientSocket;
+/**
+ * The ClientSocket class is a simple publish / subscribe wrapper built on top of the
+ * [isomorphic-ws](https://github.com/heineiuo/isomorphic-ws) library.
+ * An instance of `ClientSocket` is automatically created by the `soundworks.Client`
+ * (see {@link Client#socket}).
+ *
+ * _Important: In most cases, you should consider using a {@link SharedState}
+ * rather than directly using the sockets._
+ *
+ * The ClientSocket class concurrently opens two different WebSockets:
+ * - a socket configured with `binaryType = 'blob'` for JSON compatible data
+ *  types (i.e. string, number, boolean, object, array and null).
+ * - a socket configured with `binaryType= 'arraybuffer'` for efficient streaming
+ *  of binary data.
+ *
+ * Both sockets re-emits all "native" ws events ('open', 'upgrade', 'close', 'error'
+ *  and 'message'.
+ *
+ * @hideconstructor
+ */
+declare class ClientSocket {
+    constructor(role: any, config: any, socketOptions: any);
+    /**
+     * Initialize a websocket connection with the server. Automatically called
+     * during {@link Client#init}
+     *
+     * @param {string} role - Role of the client (see {@link Client#role})
+     * @param {object} config - Configuration of the sockets
+     * @private
+     */
+    private init;
+    /**
+     * Send messages with JSON compatible data types on a given channel.
+     *
+     * @param {string} channel - Channel name.
+     * @param {...*} args - Payload of the message. As many arguments as needed, of
+     *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
+     */
+    send(channel: string, ...args: any[]): void;
+    /**
+     * Listen messages with JSON compatible data types on a given channel.
+     *
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to execute when a message is received,
+     *  arguments of the callback function will match the arguments sent using the
+     *  {@link ServerSocket#send} method.
+     */
+    addListener(channel: string, callback: Function): void;
+    /**
+     * Remove a listener from JSON compatible messages on a given channel.
+     *
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Callback to remove.
+     */
+    removeListener(channel: string, callback: Function): void;
+    /**
+     * Remove all listeners of messages with JSON compatible data types.
+     *
+     * @param {string} channel - Channel name.
+     */
+    removeAllListeners(channel?: string): void;
+    /**
+     * Removes all listeners and immediately close the two sockets. Is automatically
+     * called on `client.stop()`
+     *
+     * Is also called when a disconnection is detected by the heartbeat (note that
+     * in this case, the launcher will call `client.stop()` but the listeners are
+     * already cleared so the event will be trigerred only once.
+     */
+    [kSocketTerminate](): Promise<void>;
+    #private;
+}

package/types/client/{StateManager.d.ts → ClientStateManager.d.ts}

@@ -1,23 +1,21 @@
-export default StateManager;
-export namespace client {
-    /**
-     * ~ObserveCallback
-     */
-    type StateManager = () => any;
-}
+export default ClientStateManager;
+/**
+ * ~ObserveCallback
+ */
+export type ClientStateManager = () => any;
 /**
- * @callback client.StateManager~ObserveCallback
+ * @callback ClientStateManager~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 client.SharedState}s, or attach
- * to {@link client.SharedState}s created by other nodes (clients or server). It
- * can also track all the {@link client.SharedState}s created by other nodes.
+ * The `ClientStateManager` allows to create new {@link SharedState}s, or attach
+ * to {@link SharedState}s created by other nodes (clients or server). It
+ * can also track all the {@link SharedState}s created by other nodes.
  *
- * An instance of `StateManager` is automatically created by the `soundworks.Client`
+ * An instance of `ClientStateManager` is automatically created by the `soundworks.Client`
  * at initialization (cf. {@link client.Client#stateManager}).
  *
  * See {@link client.Client#stateManager}
@@ -61,12 +59,10 @@ export namespace client {
  * }, 1000);
  * ```
  *
- * @memberof client
  * @extends BaseStateManager
  * @inheritdoc
  * @hideconstructor
  */
-declare class StateManager extends BaseStateManager {
+declare class ClientStateManager extends BaseStateManager {
 }
 import BaseStateManager from '../common/BaseStateManager.js';
-//# sourceMappingURL=StateManager.d.ts.map

package/types/client/index.d.ts

@@ -1,3 +1,27 @@
-export { default as Context } from "./Context.js";
 export { default as Client } from "./Client.js";
-//# sourceMappingURL=index.d.ts.map
+export { default as ClientContext } from "./ClientContext.js";
+/**
+ * Configuration object for a client running in a browser runtime.
+ */
+export type ClientConfig = {
+    /**
+     * - Role of the client in the application (e.g. 'player', 'controller').
+     */
+    role: string;
+    /**
+     * - Application configuration object.
+     */
+    app?: {
+        name?: string;
+        author?: string;
+    };
+    /**
+     * - Environment configuration object.
+     */
+    env: {
+        useHttps: boolean;
+        serverAddress: string;
+        port: number;
+        subpath?: string;
+    };
+};

package/types/common/BasePlugin.d.ts

@@ -1,47 +1,47 @@
+export const kBasePluginStatus: unique symbol;
 export default BasePlugin;
 /**
- * @private
+ * Callback executed when the plugin state is updated.
  */
+export type pluginOnStateChangeCallback = (#state: BasePlugin) => any;
+/**
+ * Delete the registered {@link pluginOnStateChangeCallback }.
+ */
+export type pluginDeleteOnStateChangeCallback = () => any;
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback pluginOnStateChangeCallback
+ * @param {BasePlugin#state} state - Current state of the plugin.
+ */
+/**
+ * Delete the registered {@link pluginOnStateChangeCallback}.
+ *
+ * @callback pluginDeleteOnStateChangeCallback
+ */
+/** @private */
 declare class BasePlugin {
     constructor(id: any);
-    /** @private */
-    private _id;
-    /** @private */
-    private _type;
-    /**
-     * Options of the plugin.
-     *
-     * @type {object}
-     */
-    options: object;
     /**
      * Placeholder that stores internal (local) state of the plugin. The state
      * should be modified through the `propagateStateChange` method to ensure
-     * the change to be properly propagated to `onStateChange` callbacks.
+     * the change to be properly propagated to manager `onStateChange` callbacks.
      *
      * @type {object}
      * @protected
-     * @see {@link client.Plugin#onStateChange}
-     * @see {@link server.Plugin#onStateChange}
-     * @see {@link client.Plugin#propagateStateChange}
-     * @see {@link server.Plugin#propagateStateChange}
+     * @see {@link ClientPlugin#onStateChange}
+     * @see {@link ServerPlugin#onStateChange}
+     * @see {@link ClientPlugin#propagateStateChange}
+     * @see {@link ServerPlugin#propagateStateChange}
      */
     protected state: object;
-    /**
-     * Current status of the plugin, i.e. 'idle', 'inited', 'started', 'errored'
-     *
-     * @type {string}
-     */
-    status: string;
-    /** @private */
-    private _onStateChangeCallbacks;
     /**
      * User defined ID of the plugin.
      *
      * @type {string}
      * @readonly
-     * @see {@link client.PluginManager#register}
-     * @see {@link server.PluginManager#register}
+     * @see {@link ClientPluginManager#register}
+     * @see {@link ServerPluginManager#register}
      */
     readonly get id(): string;
     /**
@@ -56,14 +56,21 @@ declare class BasePlugin {
      */
     readonly get type(): string;
     /**
-     * Start the plugin. This method is automatically called during the client or
-     * server `init()` lifecyle step. After `start()` is fulfilled the plugin should
-     * be ready to use.
+     * Current status of the plugin.
+     *
+     * @type {'idle'|'inited'|'started'|'errored'}
+     */
+    get status(): "idle" | "inited" | "started" | "errored";
+    /**
+     * Start the plugin.
+     *
+     * This method is automatically called during the client or server `init()` lifecyle
+     * step. After `start()` is fulfilled the plugin should be ready to use.
      *
      * @example
      * // server-side couterpart of a plugin that creates a dedicated global shared
      * // state on which the server-side part can attach.
-     * class MyPlugin extends Plugin {
+     * class MyPlugin extends ServerPlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
@@ -88,13 +95,14 @@ declare class BasePlugin {
      */
     start(): Promise<void>;
     /**
-     * Stop the plugin. This method is automatically called during the client or server
-     * `stop()` lifecyle step.
+     * Stop the plugin.
+     *
+     * This method is automatically called during the client or server `stop()` lifecyle step.
      *
      * @example
      * // server-side couterpart of a plugin that creates a dedicated global shared
-     * // state on which the server-side part can attach.
-     * class MyPlugin extends Plugin {
+     * // state on which the client-side part can attach.
+     * class MyPlugin extends ServerPlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
@@ -122,29 +130,27 @@ declare class BasePlugin {
     /**
      * Listen to the state changes propagated by {@link BasePlugin.propagateStateChange}
      *
-     * @param {client.Plugin~onStateChangeCallback|server.Plugin~onStateChangeCallback} callback -
-     *  Callback to execute when a state change is propagated.
-     * @returns {client.Plugin~deleteOnStateChangeCallback|server.Plugin~deleteOnStateChangeCallback}
-     *  Execute the function to delete the listener from the callback list.
-     * @see {@link client.Plugin#propagateStateChange}
-     * @see {@link server.Plugin#propagateStateChange}
+     * @param {pluginOnStateChangeCallback} callback - Callback to execute when a state change is propagated.
+     * @returns {pluginDeleteOnStateChangeCallback}
+     *
      * @example
      * const unsubscribe = plugin.onStateChange(pluginState => console.log(pluginState));
      * // stop listening state changes
      * unsubscribe();
      */
-    onStateChange(callback: any): client.Plugin;
+    onStateChange(callback: pluginOnStateChangeCallback): pluginDeleteOnStateChangeCallback;
     /**
      * Apply updates to the plugin state and propagate the updated state to the
      * `onStateChange` listeners. The state changes will also be propagated
      * through the `PluginManager#onStateChange` listeners.
      *
      * @param {object} updates - Updates to be merged in the plugin state.
-     * @see {@link client.Plugin#onStateChange}
-     * @see {@link server.Plugin#onStateChange}
-     * @see {@link client.PluginManager#onStateChange}
-     * @see {@link server.PluginManager#onStateChange}
+     *
+     * @see {@link BasePlugin#onStateChange}
+     * @see {@link BasePluginManager#onStateChange}
      */
     propagateStateChange(updates: object): void;
+    /** @private */
+    private [kBasePluginStatus];
+    #private;
 }
-//# sourceMappingURL=BasePlugin.d.ts.map

package/types/common/BasePluginManager.d.ts

@@ -1,24 +1,56 @@
+export const kPluginManagerStart: unique symbol;
+export const kPluginManagerStop: unique symbol;
+export const kPluginManagerInstances: unique symbol;
 export default BasePluginManager;
 /**
- * Shared functionnality between server-side and client-size plugin manager
+ * Callback executed when a plugin internal state is updated.
+ */
+export type pluginManagerOnStateChangeCallback = (: object, initiator: ClientPlugin | ServerPlugin | null) => any;
+/**
+ * Delete the registered {@link pluginManagerOnStateChangeCallback }.
+ */
+export type pluginManagerDeleteOnStateChangeCallback = () => any;
+/**
+ * Callback executed when a plugin internal state is updated.
+ *
+ * @callback pluginManagerOnStateChangeCallback
+ * @param {object<string, ClientPlugin|ServerPlugin>} fullState - List of all plugins.
+ * @param {ClientPlugin|ServerPlugin|null} initiator - Plugin that initiated the
+ *  update. The value is `null` if the change was initiated by the state manager
+ *  (e.g. when the initialization of the plugins starts).
+ */
+/**
+ * Delete the registered {@link pluginManagerOnStateChangeCallback}.
  *
- * @private
+ * @callback pluginManagerDeleteOnStateChangeCallback
  */
+/** @private */
 declare class BasePluginManager {
     constructor(node: any);
-    /** @private */
-    private _node;
-    /** @private */
-    private _dependencies;
-    /** @private */
-    private _instances;
-    /** @private */
-    private _instanceStartPromises;
-    /** @private */
-    private _onStateChangeCallbacks;
-    status: string;
     /**
-     * Register a plugin into soundworks.
+     * Status of the plugin manager
+     *
+     * @type {'idle'|'inited'|'started'|'errored'}
+     */
+    get status(): "idle" | "inited" | "started" | "errored";
+    /**
+     * Alias for existing plugins (i.e. plugin-scriptin), remove once updated
+     * @private
+     */
+    private unsafeGet;
+    /**
+     * Retrieve an fully started instance of a registered plugin without checking
+     * that the pluginManager is started.
+     *
+     * This method is required for starting the plugin manager itself and to require
+     * a plugin from within another plugin.
+     *
+     * _Warning: Unless you are developing your own plugins, you should not have to use
+     * this method_
+     */
+    getUnsafe(id: any): Promise<any>;
+    /**
+     * Register a plugin into the manager.
      *
      * _A plugin must always be registered both on client-side and on server-side_
      *
@@ -27,24 +59,24 @@ declare class BasePluginManager {
      *
      * @param {string} id - Unique id of the plugin. Enables the registration of the
      *  same plugin factory under different ids.
-     * @param {Function} factory - Factory function that returns the Plugin class.
+     * @param {Function} ctor - The class returned by the plugin factory method.
      * @param {object} [options={}] - Options to configure the plugin.
      * @param {array} [deps=[]] - List of plugins' names the plugin depends on, i.e.
-     *  the plugin initialization will start only after the plugins it depends on are
+     *  the plugin initialization will begin only after the plugins it depends on are
      *  fully started themselves.
-     * @see {@link client.PluginManager#register}
-     * @see {@link server.PluginManager#register}
+     * @see {@link ClientPluginManager#register}
+     * @see {@link ServerPluginManager#register}
      * @example
      * // client-side
      * client.pluginManager.register('user-defined-id', pluginFactory);
      * // server-side
      * server.pluginManager.register('user-defined-id', pluginFactory);
      */
-    register(id: string, ctor: any, options?: object, deps?: any[]): void;
+    register(id: string, ctor: Function, options?: object, deps?: any[]): void;
     /**
-     * Manually add a dependency to a given plugin. Usefull to require a plugin
-     * within a plugin
+     * Manually add a dependency to a given plugin.
      *
+     * Usefull to require a plugin within a plugin
      */
     addDependency(pluginId: any, dependencyId: any): void;
     /**
@@ -52,22 +84,6 @@ declare class BasePluginManager {
      * @returns {string[]}
      */
     getRegisteredPlugins(): string[];
-    /**
-     * Initialize all the registered plugin. Executed during the `Client.init()` or
-     * `Server.init()` initialization step.
-     * @private
-     */
-    private start;
-    /** @private */
-    private stop;
-    /**
-     * Retrieve an fully started instance of a registered plugin, without checking
-     * that the pluginManager has started. This is required for starting the plugin
-     * manager itself and to require a plugin from within another plugin
-     *
-     * @private
-     */
-    private unsafeGet;
     /**
      * Propagate a notification each time a plugin is updated (status or inner state).
      * The callback will receive the list of all plugins as first parameter, and the
@@ -75,10 +91,8 @@ declare class BasePluginManager {
      *
      * _In most cases, you should not have to rely on this method._
      *
-     * @param {client.PluginManager~onStateChangeCallback|server.PluginManager~onStateChangeCallback} callback
-     *  Callback to be executed on state change
-     * @param {client.PluginManager~deleteOnStateChangeCallback|client.PluginManager~deleteOnStateChangeCallback}
-     *  Function to execute to listening for changes.
+     * @param {pluginManagerOnStateChangeCallback} callback - Callback to execute on state change
+     * @returns {pluginManagerDeleteOnStateChangeCallback} - Clear the subscription when executed
      * @example
      * const unsubscribe = client.pluginManager.onStateChange(pluginList, initiator => {
      *   // log the current status of all plugins
@@ -93,8 +107,18 @@ declare class BasePluginManager {
      * // stop listening for updates later
      * unsubscribe();
      */
-    onStateChange(callback: any): () => boolean;
+    onStateChange(callback: pluginManagerOnStateChangeCallback): pluginManagerDeleteOnStateChangeCallback;
+    /**
+     * Initialize all registered plugins.
+     *
+     * Executed during the `Client.init()` or `Server.init()` initialization step.
+     *
+     * @private
+     */
+    private [kPluginManagerStart];
     /** @private */
-    private _propagateStateChange;
+    private [kPluginManagerStop];
+    /** #private */
+    [kPluginManagerInstances]: Map<any, any>;
+    #private;
 }
-//# sourceMappingURL=BasePluginManager.d.ts.map