@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/types/client/ClientPluginManager.d.ts

@@ -0,0 +1,112 @@
+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#start} or {@link Server#start}
+ * to be properly initialized.
+ *
+ * In some situations, you might want to register the same plugin factory several times
+ * using different ids (e.g. for watching several parts of the file system, etc.).
+ *
+ * Refer to the plugins' documentation for more precise examples, and the specific API
+ * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more information on the available plugins.
+ *
+ * See {@link Client#pluginManager}
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/core/client.js';
+ * import syncPlugin from '@soundworks/plugin-sync/client.js';
+ *
+ * const client = new Client(config);
+ * // register the plugin before `client.start()`
+ * client.pluginManager.register('sync', syncPlugin);
+ *
+ * await client.start();
+ *
+ * const sync = await client.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/core/server.js';
+ * import syncPlugin from '@soundworks/plugin-sync/server.js';
+ *
+ * const server = new Server(config);
+ * // register the plugin before `server.start()`
+ * server.pluginManager.register('sync', syncPlugin);
+ *
+ * await server.start();
+ *
+ * const sync = await server.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * @extends BasePluginManager
+ * @inheritdoc
+ * @template T
+ */
+declare class ClientPluginManager<T> extends BasePluginManager {
+    /**
+     * @param {Client} client - The soundworks client instance.
+     * @hideconstructor
+     */
+    constructor(client: Client);
+    /**
+     * Register a plugin into the manager.
+     *
+     * _A plugin must always be registered both on client-side and on server-side_
+     *
+     * Refer to the plugin documentation to check its options and proper way of
+     * registering it.
+     *
+     * @param {string} id - Unique id of the plugin. Enables the registration of the
+     *  same plugin factory under different ids.
+     * @param {T<ClientPlugin>} ctor - The client-side Class of the plugin.
+     * @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
+     *  fully started themselves.
+     * @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: T<ClientPlugin>, options?: object, deps?: any[]): void;
+    /**
+     * Retrieve an fully started instance of a registered plugin.
+     *
+     * Be aware that the `get` method resolves only when the plugin is fully 'started',
+     * which is what we want 99.99% of the time. As such, and to prevent the application
+     * to be stuck in some kind of Promise dead lock, this method will throw if
+     * used before `client.init()` (or `client.start()`).
+     *
+     * To handle the remaining 0.01% cases and access plugin instances during their
+     * initialization (e.g. to display initialization screen, etc.), you should rely
+     * on the `onStateChange` method.
+     *
+     * _Note: the async API is designed to enable the dynamic creation of plugins
+     * in a future release._
+     *
+     * @param {string} id - Id of the plugin as defined when registered.
+     * @returns {Promise<T<ClientPlugin>>}
+     */
+    get(id: string): Promise<T<ClientPlugin>>;
+}
+import BasePluginManager from '../common/BasePluginManager.js';
+import ClientPlugin from './ClientPlugin.js';
+import Client from './Client.js';

package/types/client/ClientSocket.d.ts

@@ -0,0 +1,76 @@
+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 triggered only once.
+     *
+     * @private
+     */
+    private [kSocketTerminate];
+    #private;
+}

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

@@ -1,23 +1,22 @@
-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
+ * @param {String} className - Name of the shared state class.
+ * @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) on the network.
+ *
+ * It can also observe all the {@link SharedState}s created on the network.
  *
- * 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}
@@ -29,8 +28,8 @@ export namespace client {
  * 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', {
+ * // define a class of shared state.
+ * server.stateManager.defineClass('some-global-state', {
  *   myRandom: {
  *     type: 'float',
  *     default: 0,
@@ -61,12 +60,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
+import BaseStateManager from '../common/BaseStateManager.js';

package/types/client/index.d.ts

@@ -1,11 +1,38 @@
-export { default as Context } from "./Context.js";
 export { default as Client } from "./Client.js";
+export { default as ClientPlugin } from "./ClientPlugin.js";
+export { default as ClientContext } from "./ClientContext.js";
+export { default as version } from "../common/version.js";
 /**
- * Configuration object for a client running in a browser runtime.
+ * Application configuration object.
+ */
+export type ClientAppConfig = {
+    /**
+     * - Name of the application.
+     */
+    name?: string;
+    /**
+     * - Name of the author.
+     */
+    author?: string;
+};
+/**
+ * Environment configuration object.
  */
-export type BrowserClientConfig = any;
+export type ClientEnvConfig = objecy;
 /**
- * Configuration object for a client running in a node runtime.
+ * Configuration object for a client running in a browser runtime.
  */
-export type NodeClientConfig = any;
-//# sourceMappingURL=index.d.ts.map
+export type ClientConfig = {
+    /**
+     * - Role of the client in the application (e.g. 'player', 'controller').
+     */
+    role: string;
+    /**
+     * - Application configuration object.
+     */
+    app: ClientAppConfig;
+    /**
+     * - Environment configuration object.
+     */
+    env: ClientEnvConfig;
+};

package/types/common/BasePlugin.d.ts

@@ -1,68 +1,80 @@
+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);
+    /**
+     * 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 manager `onStateChange` callbacks.
+     *
+     * @type {object}
+     * @protected
+     * @see {@link ClientPlugin#onStateChange}
+     * @see {@link ServerPlugin#onStateChange}
+     * @see {@link ClientPlugin#propagateStateChange}
+     * @see {@link ServerPlugin#propagateStateChange}
+     */
+    protected state: object;
     /**
      * User defined ID of the plugin.
      *
      * @type {string}
-     * @see {@link client.PluginManager#register}
-     * @see {@link server.PluginManager#register}
+     * @readonly
+     * @see {@link ClientPluginManager#register}
+     * @see {@link ServerPluginManager#register}
      */
-    id: string;
+    readonly get id(): string;
     /**
      * Type of the plugin, i.e. the ClassName.
      *
-     * Usefull to do perform some logic based on certain types of plugins without
+     * Useful to do perform some logic based on certain types of plugins without
      * knowing under which `id` they have been registered. (e.g. creating some generic
      * views, etc.)
      *
      * @type {string}
      * @readonly
      */
-    readonly type: string;
+    readonly get type(): string;
     /**
-     * Options of the plugin.
+     * Current status of the plugin.
      *
-     * @type {object}
+     * @type {'idle'|'inited'|'started'|'errored'}
      */
-    options: object;
+    get status(): "idle" | "inited" | "started" | "errored";
     /**
-     * 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.
-     *
-     * @type {object}
-     * @protected
-     * @see {@link client.Plugin#onStateChange}
-     * @see {@link server.Plugin#onStateChange}
-     * @see {@link client.Plugin#propagateStateChange}
-     * @see {@link server.Plugin#propagateStateChange}
-     */
-    protected state: object;
-    /**
-     * Current status of the plugin, i.e. 'idle', 'inited', 'started', 'errored'
+     * Start the plugin.
      *
-     * @type {string}
-     */
-    status: string;
-    /** @private */
-    private _onStateChangeCallbacks;
-    /**
-     * 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.
+     * This method is automatically called during the client or server `init()` lifecycle
+     * 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
+     * // server-side counterpart 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);
      *
-     *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+     *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      *       someParam: {
      *         type: 'boolean',
      *         default: false,
@@ -83,17 +95,18 @@ 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()` lifecycle 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 {
+     * // server-side counterpart of a plugin that creates a dedicated global shared
+     * // state on which the client-side part can attach.
+     * class MyPlugin extends ServerPlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
-     *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+     *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      *       someParam: {
      *         type: 'boolean',
      *         default: false,
@@ -117,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,61 +1,98 @@
+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.
  *
- * @private
+ * @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}.
+ *
+ * @callback pluginManagerDeleteOnStateChangeCallback
+ */
+/** @private */
 declare class BasePluginManager {
     constructor(node: any);
-    /** @private */
-    private _node;
-    /** @private */
-    private _registeredPlugins;
-    /** @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-scripting), remove once updated
+     * @private
+     * @deprecated
+     */
+    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_
      *
-     * Refer to the plugin documentation to check its options and proper way of
-     * registering it.
+     * Plugins must be registered between the instantiation of {@link Client} and {@link Server},
+     * and their respective initialization, i.e.:
+     *
+     * ```js
+     * const client = new Client(config);
+     * client.pluginManager.register('my-plugin', plugin);
+     * await client.start();
+     * ```
+     *
+     * Refer to the plugins documentation to check their configuration options and API.
      *
      * @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;
     /**
-     * Initialize all the registered plugin. Executed during the `Client.init()` or
-     * `Server.init()` initialization step.
-     * @private
+     * Manually add a dependency to a given plugin.
+     *
+     * Useful to require a plugin within a plugin
      */
-    private start;
-    stop(): Promise<void>;
+    addDependency(pluginId: any, dependencyId: any): void;
     /**
-     * Retrieve an fully started instance of a registered plugin, without checking
-     * that the pluginManager is started. This is important for starting the plugin
-     * manager itself.
-     *
-     * @private
+     * Returns the list of the registered plugins ids
+     * @returns {string[]}
      */
-    private getUnsafe;
+    getRegisteredPlugins(): string[];
     /**
      * 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
@@ -63,10 +100,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
@@ -81,8 +116,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 {@link Client#init} or {@link Client#stop} initialization step.
+     *
+     * @private
+     */
+    private [kPluginManagerStart];
+    /** @private */
+    private [kPluginManagerStop];
     /** @private */
-    private _propagateStateChange;
+    private [kPluginManagerInstances];
+    #private;
 }
-//# sourceMappingURL=BasePluginManager.d.ts.map