@soundworks/core 4.0.0-alpha.7 → 5.0.0

package/types/client/Client.d.ts

@@ -1,115 +1,136 @@
+export const kClientVersionTest: unique symbol;
+export const kClientOnStatusChangeCallbacks: unique symbol;
 export default Client;
 /**
- * The `Client` class is the main entry point for  the client-side of soundworks
+ * The `Client` class is the main entry point for the client-side of a soundworks
  * application.
  *
- * A `Client` instance allows to access soundworks components such as {@link client.StateManager},
- * {@link client.PluginManager},{@link client.Socket} or {@link client.ContextManager}.
- * Its is also responsible for handling the initialization lifecycles of the different
- * soundworks components.
+ * A `soundworks` client can run seamlessly in a browser or in a Node.js runtime.
+ *
+ * It provides an access to the different soundworks components such as the {@link ClientStateManager},
+ * {@link ClientPluginManager}, {@link ClientSocket} and the {@link ClientContextManager}.
  *
  * ```
  * import { Client } from '@soundworks/core/client.js';
- * // create a new soundworks `Client` instance
- * const client = new Client({ role: 'player' });
- * // init and start the client
+ * // create a `Client` instance
+ * const client = new Client({
+ *   role: 'player',
+ *   env: {
+ *     useHttps: false,
+ *     serverAddress: 'localhost',
+ *     port: 8000,
+ *   },
+ * });
+ * // start the client
  * await client.start();
  * ```
- *
- * @memberof client
  */
 declare class Client {
     /**
-     * @param {client.BrowserClientConfig|client.NodeClientConfig} config -
-     *  Configuration of the soundworks client.
+     * @param {ClientConfig} config - Configuration of the soundworks client.
      * @throws Will throw if the given config object is invalid.
      */
-    constructor(config: client.BrowserClientConfig | client.NodeClientConfig);
+    constructor(config: ClientConfig);
+    /**
+     * Package version.
+     *
+     * @type {string}
+     */
+    get version(): string;
     /**
      * Role of the client in the application.
      *
      * @type {string}
      */
-    role: string;
+    get role(): string;
     /**
      * Configuration object.
      *
-     * @type {client.BrowserClientConfig|client.NodeClientConfig}
+     * @type {ClientConfig}
      */
-    config: client.BrowserClientConfig | client.NodeClientConfig;
+    get config(): ClientConfig;
     /**
-     * Session id of the client (incremeted positive number), generated and
-     * retrieved by the server during `client.init`. The counter is reset when
-     * the server restarts.
+     * Session id of the client.
+     *
+     * Incremented positive integer generated and retrieved by the server during
+     * {@link Client#init}. The counter is reset when the server restarts.
      *
      * @type {number}
      */
-    id: number;
+    get id(): number;
     /**
-     * Unique session uuid of the client (uuidv4), generated and retrieved by
-     * the server during {@link client.Client#init}.
+     * Unique session uuid of the client (uuidv4).
      *
+     * Generated and retrieved by the server during {@link Client#init}.
      * @type {string}
      */
-    uuid: string;
+    get uuid(): string;
     /**
-     * Instance of the {@link client.Socket} class that handle websockets communications with
-     * the server.
+     * Authentication token generated by the server.
+     *
+     * Only set if client has gone through authentication process and is considered trusted.
      *
-     * @see {@link client.Socket}
-     * @type {client.Socket}
+     * Generated and retrieved by the server during {@link Client#init}.
+     * @type {string}
      */
-    socket: client.Socket;
+    get token(): string;
     /**
      * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
      *
-     * @type {string}
+     * @type {'node'|'browser'}
+     */
+    get runtime(): "node" | "browser";
+    /**
+     * @deprecated Use {@link Client#runtime} instead.
      */
-    target: string;
+    get target(): "browser" | "node";
     /**
-     * Instance of the {@link client.ContextManager} class.
+     * Instance of the {@link client.Socket} class.
+     *
+     * @see {@link ClientSocket}
+     * @type {ClientSocket}
+     */
+    get socket(): ClientSocket;
+    /**
+     * Instance of the {@link ClientContextManager} class.
      *
      * The context manager can be safely used after `client.init()` has been fulfilled.
      *
-     * @see {@link client.ContextManager}
-     * @type {client.ContextManager}
+     * @see {@link ClientContextManager}
+     * @type {ClientContextManager}
      */
-    contextManager: client.ContextManager;
+    get contextManager(): ClientContextManager;
     /**
-     * Instance of the {@link client.PluginManager} class.
+     * Instance of the {@link ClientPluginManager} class.
      *
      * The context manager can be safely used after `client.init()` has been fulfilled.
      *
-     * @see {@link client.PluginManager}
-     * @type {client.PluginManager}
+     * @see {@link ClientPluginManager}
+     * @type {ClientPluginManager}
      */
-    pluginManager: client.PluginManager;
+    get pluginManager(): ClientPluginManager<any>;
     /**
-     * Instance of the {@link client.StateManager} class.
+     * Instance of the {@link ClientStateManager} class.
      *
      * The context manager can be safely used after `client.init()` has been fulfilled.
      *
-     * @see {@link client.StateManager}
-     * @type {client.StateManager}
+     * @see {@link ClientStateManager}
+     * @type {ClientStateManager}
      */
-    stateManager: client.StateManager;
+    get stateManager(): ClientStateManager;
     /**
-     * Status of the client, 'idle', 'inited', 'started' or 'errored'.
+     * Status of the client.
      *
-     * @type {string}
+     * @type {'idle'|'inited'|'started'|'errored'}
      */
-    status: string;
-    /** @private */
-    private _onStatusChangeCallbacks;
-    /** @private */
-    private _auditState;
+    get status(): "idle" | "inited" | "started" | "errored";
     /**
      * The `init` method is part of the initialization lifecycle of the `soundworks`
-     * client. Most of the time, the `init` method will be implicitly called by the
-     * {@link client.Client#start} method.
+     * client. Most of the time, this method will be implicitly executed by the
+     * {@link Client#start} method.
      *
      * In some situations you might want to call this method manually, in such cases
-     * the method should be called before the {@link client.Client#start} method.
+     * the method should be called before the {@link Client#start} method.
      *
      * What it does:
      * - connect the sockets to be server
@@ -117,27 +138,28 @@ declare class Client {
      * - launch the state manager
      * - initialize all registered plugin
      *
-     * After `await client.init()` is fulfilled, the {@link client.Client#stateManager},
-     * the {@link client.Client#pluginManager} and the {@link client.Client#socket}
+     * After `await client.init()` is fulfilled, the {@link Client#stateManager},
+     * the {@link Client#pluginManager} and the {@link Client#socket}
      * can be safely used.
      *
      * @example
      * import { Client } from '@soundworks/core/client.js'
      *
      * const client = new Client(config);
-     * // optionnal explicit call of `init` before `start`
+     * // optional explicit call of `init` before `start`
      * await client.init();
      * await client.start();
      */
     init(): Promise<void>;
     /**
      * The `start` method is part of the initialization lifecycle of the `soundworks`
-     * client. The `start` method will implicitly call the {@link client.Client#init}
-     * method if it has not been called manually.
+     * client. This method will implicitly execute {@link Client#init} method if it
+     * has not been called manually.
      *
      * What it does:
-     * - optionnaly call {@link client.Client#init}
-     * - starts all the already created contexts (see {@link client.Context})
+     * - implicitly call {@link Client#init} if not done manually
+     * - start all created contexts. For that to happen, you will have to call `client.init`
+     * manually and instantiate the contexts between `client.init()` and `client.start()`
      *
      * @example
      * import { Client } from '@soundworks/core/client.js'
@@ -150,7 +172,7 @@ declare class Client {
      * Stops all started contexts, plugins and terminates the socket connections.
      *
      * In most situations, you might not need to call this method. However, it can
-     * be usefull for unit testing or similar situations where you want to create
+     * be useful for unit testing or similar situations where you want to create
      * and delete several clients in the same process.
      *
      * @example
@@ -166,29 +188,32 @@ declare class Client {
     /**
      * Attach and retrieve the global audit state of the application.
      *
-     * The audit state is a {@link client.SharedState} instance that keeps track of
-     * global informations about the application such as, the number of connected
-     * clients, network latency estimation, etc. It is usefull for controller client
+     * The audit state is a {@link SharedState} instance that keeps track of
+     * global information about the application such as, the number of connected
+     * clients, network latency estimation, etc. It is useful for controller client
      * roles to give the user an overview about the state of the application.
      *
      * The audit state is lazily attached to the client only if this method is called.
      *
-     * @returns {Promise<client.SharedState>}
+     * @returns {Promise<SharedState>}
      * @throws Will throw if called before `client.init()`
-     * @see {@link client.SharedState}
+     * @see {@link SharedState}
      * @example
      * const auditState = await client.getAuditState();
      * auditState.onUpdate(() => console.log(auditState.getValues()), true);
      */
-    getAuditState(): Promise<client.SharedState>;
+    getAuditState(): Promise<SharedState>;
     /**
      * Listen for the status change ('inited', 'started', 'stopped') of the client.
      *
      * @param {Function} callback - Listener to the status change.
-     * @returns {Function} Delete the listener.
+     * @returns {Function} Function that delete the listener when executed.
      */
     onStatusChange(callback: Function): Function;
-    /** @private */
-    private _dispatchStatus;
+    [kClientOnStatusChangeCallbacks]: Set<any>;
+    #private;
 }
-//# sourceMappingURL=Client.d.ts.map
+import ClientSocket from './ClientSocket.js';
+import ClientContextManager from './ClientContextManager.js';
+import ClientPluginManager from './ClientPluginManager.js';
+import ClientStateManager from './ClientStateManager.js';

package/types/client/{Context.d.ts → ClientContext.d.ts}

@@ -1,11 +1,12 @@
-export default Context;
+export const kClientContextStatus: unique symbol;
+export default ClientContext;
 /**
  * Base class to extend in order to implement a new Context.
  *
  * In the `soundworks` paradigm, a client has a "role" (e.g. _player_, _controller_)
- * see {@link client.Client#role}) and can be in different "contexts" (e.g. different
+ * see {@link Client#role}) and can be in different "contexts" (e.g. different
  * part of the experience such as sections of a music piece, etc.). This class
- * provides a simple and unified way to model these reccuring aspects of an application.
+ * provides a simple and unified way to model these recurring aspects of an application.
  *
  * You can also think of a `Context` as a state of a state machine from which a
  * client can `enter()` or `exit()` (be aware that `soundworks` does not provide
@@ -16,12 +17,12 @@ export default Context;
  * the context. In such case, `soundworks` guarantees that the server-side
  * logic is executed before the `enter()` and `exit()` promises are fulfilled.
  *
- * ```
- * import { Client, Context } from '@soundworks/core/index.js'
+ * ```js
+ * import { Client, ClientContext } from '@soundworks/core/index.js'
  *
  * const client = new Client(config);
  *
- * class MyContext extends Context {
+ * class MyContext extends ClientContext {
  *   async enter() {
  *     await super.enter();
  *     console.log(`client ${this.client.id} entered my context`);
@@ -40,50 +41,73 @@ export default Context;
  * await new Promise(resolve => setTimeout(resolve, 2000));
  * await myContext.exit();
  * ```
- *
- * @memberof client
  */
-declare class Context {
+declare class ClientContext {
     /**
-     * @param {client.Client} client - The soundworks client instance.
+     * @param {Client} client - The soundworks client instance.
      * @throws Will throw if the first argument is not a soundworks client instance.
      */
-    constructor(client: client.Client);
+    constructor(client: Client);
     /**
      * The soundworks client instance.
+     * @type {Client}
      */
-    client: Client;
+    get client(): Client;
     /**
-     * Status of the context, i.e. 'idle', 'inited', 'started', 'errored'
+     * Status of the context.
+     * @type {'idle'|'inited'|'started'|'errored'}
      */
-    status: string;
+    get status(): "idle" | "inited" | "started" | "errored";
     /**
-     * Name of the context. Defaults to the class name, override to use a user-defined name.
+     * Optional user-defined name of the context (defaults to the class name).
+     *
+     * The context manager will match the client-side and server-side contexts based
+     * on this name. If the {@link ServerContextManager} don't find a corresponding
+     * user-defined context with the same name, it will use a default (noop) context.
      *
-     * @returns {string} - Name of the context.
+     * @readonly
+     * @type {string}
      * @example
+     * // server-side and client-side contexts are matched based on their respective `name`
      * class MyContext extends Context {
      *   get name() {
      *     return 'my-user-defined-context-name';
      *   }
      * }
      */
-    get name(): string;
+    readonly get name(): string;
     /**
-     * Start the context. This method is automatically called when `await client.start()`
-     * is called, or lazilly called when entering the context (i.e. `context.enter()`)
-     * if the context has been created after `client.start()`.
+     * Start the context. This method is lazily called when the client enters the
+     * context for the first time (cf. ${ClientContext#enter}). If you know some
+     * some heavy and/or potentially long job has to be done  when starting the context
+     * (e.g. call to a web service) it may be a good practice to call it explicitly.
+     *
+     * This method should be implemented to perform operations that are valid for the
+     * whole lifetime of the context, regardless the client enters or exits the context.
+     *
+     * @example
+     * import { Context } from '@soundworks/core/client.js';
+     *
+     * class MyContext extends Context {
+     *   async start() {
+     *     await super.start();
+     *     await this.doSomeLongJob();
+     *   }
+     * }
      *
-     * In some situation, you might want to implement this method to handle application
-     * wise behavior regardeless the client enters or exists the context.
+     * // Instantiate the context
+     * const myContext = new Context(client);
+     * // manually start the context to perform the long operation before the client
+     * // enters the context.
+     * await myContext.start();
      */
     start(): Promise<void>;
     /**
      * Stop the context. This method is automatically called when `await client.stop()`
-     * is called.
+     * is called. It should be used to cleanup context wise operations made in `start()`
+     * (e.g. destroy the reusable audio graph).
      *
-     * In some situation, you might want to implement this method to handle application
-     * wise behavior regardeless the client enters or exists the context.
+     * _WARNING: this method should never be called manually._
      */
     stop(): Promise<void>;
     /**
@@ -91,12 +115,12 @@ declare class Context {
      * done (e.g. creating a shared state, etc.) when the context is entered.
      *
      * If a server-side part of the context is defined (i.e. a context with the same
-     * {@link client.Context#name}), the corresponding server-side `enter()` method
+     * {@link ClientContext#name}), the corresponding server-side `enter()` method
      * will be executed before the returned Promise is fulfilled.
      *
-     * If the context has not been started yet, the `start` method is implicitely executed.
+     * If the context has not been started yet, the `start` method is implicitly executed.
      *
-     * @returns {Promise} - Promise that resolves when the context is entered.
+     * @returns {Promise<void>} - Promise that resolves when the context is entered.
      * @example
      * class MyContext extends Context {
      *   async enter() {
@@ -110,16 +134,16 @@ declare class Context {
      *   }
      * }
      */
-    enter(): Promise<any>;
+    enter(): Promise<void>;
     /**
      * Exit the context. Implement this method to define the logic that should be
      * done (e.g. delete a shared state, etc.) when the context is exited.
      *
      * If a server-side part of the context is defined (i.e. a context with the same
-     * {@link client.Context#name}), the corresponding server-side `exit()` method
+     * {@link ClientContext#name}), the corresponding server-side `exit()` method
      * will be executed before the returned Promise is fulfilled.
      *
-     * @returns {Promise} - Promise that resolves when the context is exited.
+     * @returns {Promise<void>} - Promise that resolves when the context is exited.
      * @example
      * class MyContext extends Context {
      *   async enter() {
@@ -133,7 +157,8 @@ declare class Context {
      *   }
      * }
      */
-    exit(): Promise<any>;
+    exit(): Promise<void>;
+    [kClientContextStatus]: string;
+    #private;
 }
-import Client from "./Client.js";
-//# sourceMappingURL=Context.d.ts.map
+import Client from './Client.js';

package/types/client/{ContextManager.d.ts → ClientContextManager.d.ts}

@@ -1,45 +1,42 @@
-export default ContextManager;
+export const kClientContextManagerStart: unique symbol;
+export const kClientContextManagerStop: unique symbol;
+export const kClientContextManagerRegister: unique symbol;
+export default ClientContextManager;
 /**
  * Manage the different contexts and their lifecycle.
  *
- * See {@link client.Client#contextManager}
+ * See {@link Client#contextManager}
  *
  * _WARNING: In most cases, you should not have to manipulate the context manager directly._
  *
- * @memberof client
  * @hideconstructor
  */
-declare class ContextManager {
-    /** @private */
-    private _contexts;
-    /** @private */
-    private _contextStartPromises;
-    /**
-     * Register the context into the manager. Is called in context constructor.
-     *
-     * @param {client.Context} context - The context to be registered.
-     * @private
-     */
-    private register;
+declare class ClientContextManager {
     /**
      * Retrieve a started context from its name.
      *
      * _WARNING: Most of the time, you should not have to call this method manually._
      *
-     * @param {client.Context#name} contextName - Name of the context.
+     * @param {string} contextName - Name of the context.
+     * @returns {Promise<ClientContext>}
      */
-    get(contextName: any): Promise<any>;
+    get(contextName: string): Promise<ClientContext>;
     /**
-     * Start all registered contexts. Called during `client.start()`
+     * Register the context into the manager. Is called in context constructor.
      *
+     * @param {ClientContext} context - The context to be registered.
+     * @private
+     */
+    private [kClientContextManagerRegister];
+    /**
+     * Start all registered contexts. Called during `client.start()`
      * @private
      */
-    private start;
+    private [kClientContextManagerStart];
     /**
      * Stop all registered contexts. Called during `client.stop()`
-     *
      * @private
      */
-    private stop;
+    private [kClientContextManagerStop];
+    #private;
 }
-//# sourceMappingURL=ContextManager.d.ts.map

package/types/client/ClientPlugin.d.ts

@@ -0,0 +1,51 @@
+export default ClientPlugin;
+/**
+ * ~onStateChangeCallback
+ */
+export type ClientPlugin = (#state: ClientPlugin) => any;
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback ClientPlugin~onStateChangeCallback
+ * @param {ClientPlugin#state} state - Current state of the plugin.
+ */
+/**
+ * Delete the registered {@link ClientPlugin~onStateChangeCallback}.
+ *
+ * @callback ClientPlugin~deleteOnStateChangeCallback
+ */
+/**
+ * Base class to extend in order to create the client-side counterpart of a
+ * `soundworks` plugin.
+ *
+ * In the `soundworks` paradigm, a plugin is a component that allows to extend
+ * the framework capabilities by encapsulating common and reusable logic in
+ * an application wise perspective. For example, plugins are available to handle
+ * clock synchronization, to deal with the file system, etc. Plugin should always
+ * have both a client-side and a server-side part.
+ *
+ * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more information on the available plugins.
+ *
+ * _Creating new plugins should be considered an advanced usage._
+ *
+ * @extends BasePlugin
+ * @inheritdoc
+ */
+declare class ClientPlugin extends BasePlugin {
+    /**
+     * @param {Client} client - A soundworks client instance.
+     * @param {string} id - User defined id of the plugin as defined in
+     *  {@link ClientPluginManager#register}.
+     */
+    constructor(client: Client, id: string);
+    /**
+     * Instance of soundworks client.
+     *
+     * @type {Client}
+     * @see {@link Client}
+     */
+    get client(): Client;
+    #private;
+}
+import BasePlugin from '../common/BasePlugin.js';