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

package/.jsdoc

@@ -23,9 +23,12 @@
     "footer": ""
   },
   "docdash": {
+    "search": true,
+    "typedefs": true,
     "sectionOrder": [
       "Namespaces",
       "Classes",
+      "Global",
       "Modules",
       "Externals",
       "Events",
@@ -40,7 +43,6 @@
         "title": "soundworks",
         "description": "Documentation of soundworks, a full-stack JavaScript framework for distributed WebAudio and multimedia applications"
     },
-    "search": true,
     "menu": {
       "Website": {
         "href":"http://soundworks.dev/",

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v4.0.0-alpha.29 - 23/09/2023
+
+- Feat: add required option for SharedState parameter
+- Chore: Renamed all classes to avoid namespace in doc and improve typescript support
+- Chore: improve shared states abstractions naming
+
 ## v4.0.0-alpha.28 - 06/09/2025
 
 - Fix: make it can work without `node_modules` when bundled to `.cjs` for use in Max
@@ -12,7 +18,7 @@
 
 ## v4.0.0-alpha.25 - 24/05/2025
 
-- Fix: better default behavior for websocket connection URL
+- Fix: better default behavior for WebSocket connection URL
 
 ## v4.0.0-alpha.24 - 24/05/2025
 
@@ -22,14 +28,14 @@
 
 - Breaking: remove binary socket
 - Fix: do not terminate socket on missed heartbeat, which seems to create false positive, just warn instead
-- Refactor: some work toward upgrading code to es2022
+- Refactor: some work toward upgrading code to ES2022
 
 ## v4.0.0-alpha.22 - 16/05/2025
 
 - Feat: allow configuring socket endpoint on browser clients
 - Feat: check and warn if version inconsistency between server and client
 
-## v4.0.0-alpha.21 - 6/05/2025
+## v4.0.0-alpha.21 - 06/05/2025
 
 - Fix: prevent multiple 'close' events
 - Fix: disable heartbeat check on client-side, was unstable
@@ -44,7 +50,7 @@
 
 ## v4.0.0-alpha.19 - 17/01/2024
 
-- Hotfix for #85
+- Hot fix for #85
 
 ## v4.0.0-alpha.18 - 15/01/2024
 
@@ -52,7 +58,7 @@
 
 ## v4.0.0-alpha.17 - 16/12/2023
 
-- Support bundling the server to cjs for Max externals
+- Support bundling the server to common js for Max externals
 
 ## v4.0.0-alpha.16 - 15/12/2023
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.28",
+  "version": "4.0.0-alpha.29",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,11 +43,11 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "doc": "rm -Rf docs && jsdoc -c .jsdoc --verbose && cp -R misc/assets docs/",
+    "doc": "npm run types && rm -rf docs && jsdoc -c .jsdoc --verbose && cp -R misc/assets docs/",
     "lint": "npx eslint src",
-    "test": "npx mocha",
-    "test:all": "npx mocha tests/*/*.spec.js",
-    "types": "rm -Rf types && tsc",
+    "test": "npx mocha tests/*/*.spec.js",
+    "test:only": "npx mocha",
+    "types": "rm -rf types && tsc",
     "preversion": "node ./misc/scripts/generate-version-file.js $npm_new_version",
     "postversion": "node ./misc/scripts/check-changelog.js && git commit -am \"$npm_new_version\" --allow-empty"
   },

package/src/client/Client.js

@@ -1,11 +1,21 @@
 import { isBrowser, isPlainObject } from '@ircam/sc-utils';
 
-import ContextManager from './ContextManager.js';
-import PluginManager from './PluginManager.js';
-import Socket, {
+import ClientContextManager, {
+  kClientContextManagerStart,
+  kClientContextManagerStop,
+} from './ClientContextManager.js';
+import ClientPluginManager from './ClientPluginManager.js';
+import {
+  kPluginManagerStart,
+  kPluginManagerStop,
+} from '../common/BasePluginManager.js';
+import ClientSocket, {
   kSocketTerminate,
-} from './Socket.js';
-import StateManager from './StateManager.js';
+} from './ClientSocket.js';
+import ClientStateManager from './ClientStateManager.js';
+import {
+  kStateManagerInit,
+} from '../common/BaseStateManager.js';
 
 import {
   CLIENT_HANDSHAKE_REQUEST,
@@ -14,53 +24,40 @@ import {
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
 import logger from '../common/logger.js';
-import version from '../common/version.js';
+import VERSION from '../common/version.js';
 
 // for testing purposes
 export const kClientVersionTest = Symbol('soundworks:client-version-test');
-
-/**
- * Configuration object for a client running in a browser runtime.
- *
- * @typedef ClientConfig
- * @memberof client
- * @type {object}
- * @property {string} role - Role of the client in the application (e.g. 'player', 'controller').
- * @property {object} [app] - Application configration object.
- * @property {string} [app.name=''] - Name of the application.
- * @property {string} [app.author=''] - Name of the author.
- * @property {object} [env] - Environment configration object.
- * @property {boolean} env.useHttps - Define if the websocket should use secure connection.
- * @property {boolean} [env.serverAddress=''] - Address the socket server. Mandatory for
- *  node clients. For browser clients, use `window.location.domain` as fallback if empty.
- * @property {boolean} env.port - Port of the socket server.
- * @property {string} [env.websockets={}] - Configuration options for websockets.
- * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
- */
+export const kClientOnStatusChangeCallbacks = Symbol('soundworks:client-on-status-change-callbacks');
 
 /**
  * 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
  */
 class Client {
+  #config = null;
   #version = null;
   #role = null;
-  #config = null;
   #id = null;
   #uuid = null;
   #target = null;
@@ -71,11 +68,10 @@ class Client {
   #status = 'idle';
   // Token of the client if connected through HTTP authentication.
   #token = null;
-  #onStatusChangeCallbacks = new Set();
   #auditState = null;
 
   /**
-   * @param {client.ClientConfig} 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) {
@@ -118,13 +114,7 @@ class Client {
       this.#config.env = {};
     }
 
-    // minimal configuration for websockets
-    this.#config.env.websockets = Object.assign({
-      path: 'socket',
-      pingInterval: 5000,
-    }, config.env.websockets);
-
-    this.#version = version;
+    this.#version = VERSION;
     // allow override though config for testing
     if (config[kClientVersionTest]) {
       this.#version = config[kClientVersionTest];
@@ -132,12 +122,17 @@ class Client {
 
     this.#role = config.role;
     this.#target = isBrowser() ? 'browser' : 'node';
-    this.#socket = new Socket();
-    this.#contextManager = new ContextManager();
-    this.#pluginManager = new PluginManager(this);
-    this.#stateManager = new StateManager();
+    this.#socket = new ClientSocket(this.#role, this.#config, {
+      path: 'socket',
+      retryConnectionRefusedTimeout: 1000,
+    });
+    this.#contextManager = new ClientContextManager();
+    this.#pluginManager = new ClientPluginManager(this);
+    this.#stateManager = new ClientStateManager();
     this.#status = 'idle';
 
+    this[kClientOnStatusChangeCallbacks] = new Set();
+
     logger.configure(!!config.env.verbose);
   }
 
@@ -162,7 +157,7 @@ class Client {
   /**
    * Configuration object.
    *
-   * @type {client.ClientConfig}
+   * @type {ClientConfig}
    */
   get config() {
     return this.#config;
@@ -183,7 +178,7 @@ class Client {
   /**
    * Unique session uuid of the client (uuidv4).
    *
-   * Generated and retrieved by the server during {@link client.Client#init}.
+   * Generated and retrieved by the server during {@link Client#init}.
    * @type {string}
    */
   get uuid() {
@@ -203,53 +198,53 @@ class Client {
   /**
    * Instance of the {@link client.Socket} class.
    *
-   * @see {@link client.Socket}
-   * @type {client.Socket}
+   * @see {@link ClientSocket}
+   * @type {ClientSocket}
    */
   get socket() {
     return this.#socket;
   }
 
   /**
-   * Instance of the {@link client.ContextManager} class.
+   * 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}
    */
   get contextManager() {
     return this.#contextManager;
   }
 
   /**
-   * 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}
    */
   get pluginManager() {
     return this.#pluginManager;
   }
 
   /**
-   * 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}
    */
   get stateManager() {
     return this.#stateManager;
   }
 
   /**
-   * Status of the client, 'idle', 'inited', 'started' or 'errored'.
+   * Status of the client.
    *
-   * @type {string}
+   * @type {'idle'|'inited'|'started'|'errored'}
    */
   get status() {
     return this.#status;
@@ -267,7 +262,7 @@ class Client {
     // execute all callbacks in parallel
     const promises = [];
 
-    for (let callback of this.#onStatusChangeCallbacks) {
+    for (let callback of this[kClientOnStatusChangeCallbacks]) {
       promises.push(callback(status));
     }
 
@@ -276,11 +271,11 @@ class Client {
 
   /**
    * 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
@@ -288,8 +283,8 @@ 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
@@ -302,7 +297,7 @@ class Client {
    */
   async init() {
     // init socket communications
-    await this.#socket.init(this.#role, this.#config);
+    await this.#socket.init();
 
     // we need the try/catch block to change the promise rejection into proper error
     try {
@@ -354,24 +349,24 @@ class Client {
     }
 
     // init state manager
-    this.#stateManager.init(this.id, {
+    this.#stateManager[kStateManagerInit](this.id, {
       emit: this.#socket.send.bind(this.#socket), // need to alias this
       addListener: this.#socket.addListener.bind(this.#socket),
       removeAllListeners: this.#socket.removeAllListeners.bind(this.#socket),
     });
 
-    await this.#pluginManager.start();
+    await this.#pluginManager[kPluginManagerStart]();
 
     await this.#dispatchStatus('inited');
   }
 
   /**
    * 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:
-   * - implicitly call {@link client.Client#init} if not done manually
+   * - 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()`
    *
@@ -390,7 +385,7 @@ class Client {
       throw new Error(`[soundworks:Server] Cannot call "client.start()" twice`);
     }
 
-    await this.#contextManager.start();
+    await this.#contextManager[kClientContextManagerStart]();
     await this.#dispatchStatus('started');
   }
 
@@ -415,8 +410,8 @@ class Client {
       throw new Error(`[soundworks:Client] Cannot "client.stop()" before "client.start()"`);
     }
 
-    await this.#contextManager.stop();
-    await this.#pluginManager.stop();
+    await this.#contextManager[kClientContextManagerStop]();
+    await this.#pluginManager[kPluginManagerStop]();
     await this.#socket[kSocketTerminate]();
 
     await this.#dispatchStatus('stopped');
@@ -425,16 +420,16 @@ 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
+   * The audit state is a {@link 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
    * 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);
@@ -458,8 +453,8 @@ class Client {
    * @returns {Function} Function that delete the listener when executed.
    */
   onStatusChange(callback) {
-    this.#onStatusChangeCallbacks.add(callback);
-    return () => this.#onStatusChangeCallbacks.delete(callback);
+    this[kClientOnStatusChangeCallbacks].add(callback);
+    return () => this[kClientOnStatusChangeCallbacks].delete(callback);
   }
 }
 

package/src/client/{Context.js → ClientContext.js}

@@ -1,4 +1,7 @@
 import Client from './Client.js';
+import {
+  kClientContextManagerRegister,
+} from './ClientContextManager.js';
 import PromiseStore from '../common/PromiseStore.js';
 import {
   CONTEXT_ENTER_REQUEST,
@@ -9,6 +12,8 @@ import {
   CONTEXT_EXIT_ERROR,
 } from '../common/constants.js';
 
+export const kClientContextStatus = Symbol('soundworks:client-context-status');
+
 // share between all context, as channels are common to all contexts
 const promiseStore = new PromiseStore('Context');
 
@@ -16,7 +21,7 @@ const promiseStore = new PromiseStore('Context');
  * 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.
  *
@@ -29,12 +34,12 @@ const promiseStore = new PromiseStore('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`);
@@ -53,34 +58,23 @@ const promiseStore = new PromiseStore('Context');
  * await new Promise(resolve => setTimeout(resolve, 2000));
  * await myContext.exit();
  * ```
- *
- * @memberof client
  */
-class Context {
+class ClientContext {
+  #client = null;
+
   /**
-   * @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) {
     if (!(client instanceof Client)) {
-      throw new Error(`[soundworks:Context] Invalid argument, context "${this.name}" should receive a "soundworks.Client" instance as first argument`);
+      throw new Error(`[soundworks:ClientContext] Invalid argument, context "${this.name}" should receive a "soundworks.Client" instance as first argument`);
     }
 
-    /**
-     * The soundworks client instance.
-     * @type {client.Client}
-     * @readonly
-     */
-    this.client = client;
-
-    /**
-     * Status of the context, i.e. 'idle', 'inited', 'started', 'errored'
-     * @type {string}
-     * @readonly
-     */
-    this.status = 'idle';
-
-    this.client.socket.addListener(CONTEXT_ENTER_RESPONSE, (reqId, contextName) => {
+    this.#client = client;
+    this[kClientContextStatus] = 'idle';
+
+    this.#client.socket.addListener(CONTEXT_ENTER_RESPONSE, (reqId, contextName) => {
       if (contextName !== this.name) {
         return;
       }
@@ -88,7 +82,7 @@ class Context {
       promiseStore.resolve(reqId);
     });
 
-    this.client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
+    this.#client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
       if (contextName !== this.name) {
         return;
       }
@@ -96,7 +90,7 @@ class Context {
       promiseStore.reject(reqId, msg);
     });
 
-    this.client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
+    this.#client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
       if (contextName !== this.name) {
         return;
       }
@@ -104,7 +98,7 @@ class Context {
       promiseStore.resolve(reqId);
     });
 
-    this.client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
+    this.#client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
       if (contextName !== this.name) {
         return;
       }
@@ -112,14 +106,30 @@ class Context {
       promiseStore.reject(reqId, msg);
     });
 
-    this.client.contextManager.register(this);
+    this.#client.contextManager[kClientContextManagerRegister](this);
+  }
+
+  /**
+   * The soundworks client instance.
+   * @type {Client}
+   */
+  get client() {
+    return this.#client;
+  }
+
+  /**
+   * Status of the context.
+   * @type {'idle'|'inited'|'started'|'errored'}
+   */
+  get status() {
+    return this[kClientContextStatus];
   }
 
   /**
    * Optionnal 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 server.ContextManager} don't find a corresponding
+   * 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.
    *
    * @readonly
@@ -138,7 +148,7 @@ class Context {
 
   /**
    * Start the context. This method is lazilly called when the client enters the
-   * context for the first time (cf. ${client.Context#enter}). If you know some
+   * 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 explicitely.
    *
@@ -177,12 +187,12 @@ 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.
    *
-   * @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() {
@@ -199,14 +209,14 @@ class Context {
   async enter() {
     // lazily start the context if registered after `client.start()`
     if (this.status !== 'started' && this.status !== 'errored') {
-      await this.client.contextManager.get(this.name);
+      await this.#client.contextManager.get(this.name);
     }
 
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
         const reqId = promiseStore.add(resolve, reject, 'enter-context');
-        this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
+        this.#client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
     } catch (err) {
       throw new Error(err);
@@ -218,10 +228,10 @@ class Context {
    * 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() {
@@ -240,7 +250,7 @@ class Context {
     try {
       await new Promise((resolve, reject) => {
         const reqId = promiseStore.add(resolve, reject, 'exit-context');
-        this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
+        this.#client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
       });
     } catch (err) {
       throw new Error(err);
@@ -248,4 +258,4 @@ class Context {
   }
 }
 
-export default Context;
+export default ClientContext;