@soundworks/core 4.0.0-alpha.1 → 4.0.0-alpha.10

package/.eslintrc

@@ -1,7 +1,6 @@
 {
   "extends": [
     "@ircam",
-    "plugin:jsdoc/recommended"
   ],
   "settings": {
     "jsdoc": {

package/.github/workflows/gh-pages.yml

@@ -0,0 +1,31 @@
+name: GH Pages
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: 'Install Node'
+        uses: actions/setup-node@v3.6.0
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build Docs
+        run: npm run doc
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs
+

package/.github/workflows/unit-tests.yml

@@ -0,0 +1,18 @@
+name: Unit Tests
+on: push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: 'Install Node'
+        uses: actions/setup-node@v3.6.0
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: "Run Test"
+        run: npm test -- tests/**.spec.js

package/README.md

@@ -1,24 +1,27 @@
-# `soundworks`
+# soundworks
 
 [![npm version](https://badge.fury.io/js/@soundworks%2Fcore.svg)](https://badge.fury.io/js/@soundworks%2Fcore)
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 
 ![soundworks-logo](./assets/logo-200x200.png)
 
 Open-source creative coding framework for distributed applications based on Web technologies.
 
-Primarily focused on music, `soundworks` aims at supporting rapid development of real-time distributed applications using _JavaScript_. It provides abstractions to hide the complexity of the network and to foster very rapid-prototyping and trial-and-error workflows that are typical in artistic practices.
+Primarily focused on music, **soundworks** aims at supporting rapid development of real-time distributed applications using _JavaScript_. It provides abstractions to hide the complexity of the network and to foster very rapid-prototyping and trial-and-error workflows that are typical in artistic practices.
 
 *__WARNING: The version 4 of `@soundworks/core` is under heavy development.__*
 
 ## Getting Started
 
-The best and most simple way to start using `soundworks` is to use the `@soundworks/create` wizard. 
+The best and most simple way to start using **soundworks** is to use the `@soundworks/create` wizard. 
 
 ```sh
 npx @soundworks/create@latest
 ```
 
-See [https://soundworks.dev/guides/getting-started.html](https://soundworks.dev/guides/getting-started.html) for more informations on the wizard and how to start with `soundworks`.
+![./assets/soundworks-create-min.gif](./assets/soundworks-create-min.gif)
+
+See [https://soundworks.dev/tutorials/getting-started.html](https://soundworks.dev/tutorials/getting-started.html) for more informations on the wizard and how to start with **soundworks**.
 
 <!--
 ## Documentation
@@ -38,43 +41,31 @@ git checkout v4
 serve docs
 ```
 
+Feel welcome to open an [issue](https://github.com/collective-soundworks/soundworks/issues) or a PR if you find any inconsistency, error or missing information in the documentation.
+
+## Share with Us
+
+If you made an application using **soundworks** please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
+
 ## TypeScript Support
 
 Basic TypeScript support will be proposed in a (hopefully) near future. 
 
-However, as we aim to follow the TC39 and W3C specifications as close as possible, we will wait for the https://github.com/tc39/proposal-type-annotations proposal to reach stage 3 to update the source code in a more integrated manner.
+However, for maintenance reasons, we aim at following the TC39 and W3C specifications as close as possible. Therefore, we will wait for the https://github.com/tc39/proposal-type-annotations proposal to reach stage 3 to update the source code in a more integrated manner.
 
 ## Install
 
-Note that the `@soundworks/core` package is automatically installed when creating an application using the `@soundworks/create` wizard, so most of the time you should not have to install this package manually. See [https://soundworks.dev/guides/getting-started.html](https://soundworks.dev/guides/getting-started.html) for more informations on the `soundworks` wizard.
+Note that the `@soundworks/core` package is automatically installed when creating an application using the `@soundworks/create` wizard, so most of the time you should not have to install this package manually. See [https://soundworks.dev/guides/getting-started.html](https://soundworks.dev/guides/getting-started.html) for more informations on the **soundworks** wizard.
 
 ```
 npm install @soundworks/core
 ```
 
-## Share with Us
-
-If you made an application using `soundworks` please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
-
-## Academic Papers
-
-- Benjamin Matuszewski. A Web-Based Framework for Distributed Music System Research and Creation. AES - Journal of the Audio Engineering Society Audio-Accoustics-Application, Audio Engineering Society Inc, 2020. <[hal-03033143](https://hal.archives-ouvertes.fr/hal-03033143)>
-- Benjamin Matuszewski. Soundworks - A Framework for Networked Music Systems on the Web - State of Affairs and New Developments. Proceedings of the Web Audio Conference (WAC) 2019, Dec 2019, Trondheim, Norway. <[hal-02387783](https://hal.archives-ouvertes.fr/hal-02387783)>
-- Benjamin Matuszewski, Norbert Schnell, Frédéric Bevilacqua. Interaction Topologies in Mobile-Based Situated Networked Music Systems. Wireless Communications and Mobile Computing, Hindawi Publishing Corporation, 2019, 2019, pp.9142490. ⟨10.1155/2019/9142490⟩. <[hal-02086673](https://hal.archives-ouvertes.fr/hal-02086673)>
-- Norbert Schnell, Sébastien Robaszkiewicz. Soundworks – A playground for artists and developers to create collaborative mobile web performances. `Proceedings of the Web Audio Conference (WAC'15), 2015, Paris, France. <[hal-01580797](https://hal.archives-ouvertes.fr/hal-01580797)>
-
 ## Credits
 
-`soundworks` has been initiated by [Norbert Schnell](https://github.com/NorbertSchnell), [Sébastien Robaszkiewicz](https://github.com/i-Robi), and [Benjamin Matuszewski](https://github.com/b-ma) at the [ISMM](http://ismm.ircam.fr/) team at [Ircam - Centre Pompidou](http://www.ircam.fr/) in the framework of the [*CoSiMa*](http://cosima.ircam.fr/) research project supported by the [French National Research Agency (ANR)](http://www.agence-nationale-recherche.fr/en/).
-
-Futher developments has been supported in the framework of:
-- The [RAPID-MIX project](http://rapidmix.goldsmithsdigital.com/), funded by the European Union’s Horizon 2020 research and innovation program
-- The Ircam projects _BeCoMe_ and _SO(a)P_
-- The _Constella(c)tions_ residency of the STARTS program of the European Commission.
-
-Development is pursued, led by Benjamin Matuszewski, in the [Interaction Music Movement Team](https://www.stms-lab.fr/team/interaction-son-musique-mouvement/) from the Ircam's STMS-LAB.
+[https://soundworks.dev/credits.html](https://soundworks.dev/credits.html)
 
 ## License
 
-[BSD-3-Clause](https://github.com/collective-soundworks/soundworks/blob/master/LICENSE)
+[BSD-3-Clause](./LICENSE)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.10",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,52 +43,51 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "doc": "npm run jsdoc && npm run types",
-    "jsdoc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
+    "doc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
     "lint": "npx eslint src",
     "test": "mocha",
     "toc": "markdown-toc -i README.md",
     "types": "rm -Rf types && tsc",
-    "version": "npm run toc && npm run doc && git add docs"
+    "preversion": "npm run toc && git commit -am 'docs: build' --allow-empty"
   },
   "dependencies": {
-    "@ircam/sc-gettime": "^1.0.0",
-    "chalk": "^4.1.2",
+    "@ircam/sc-gettime": "^1.0.1",
+    "@ircam/sc-utils": "^1.1.1",
+    "chalk": "^5.3.0",
     "columnify": "^1.6.0",
     "compression": "^1.7.1",
+    "cross-fetch": "^3.1.8",
     "express": "^4.18.1",
     "fast-deep-equal": "^3.1.3",
     "fast-text-encoding": "^1.0.0",
-    "is-plain-obj": "3.0.0",
-    "isomorphic-ws": "^4.0.1",
+    "isomorphic-ws": "^5.0.0",
     "keyv": "^4.2.2",
     "keyv-file": "^0.2.0",
     "lodash.clonedeep": "^4.5.0",
     "lodash.merge": "^4.6.2",
-    "pem": "^1.14.6",
-    "serve-static": "^1.15.0",
+    "pem": "^1.14.8",
     "template-literal": "^1.0.4",
-    "uuid": "^8.3.2",
+    "uuid": "^9.0.0",
     "window-or-global": "^1.0.1",
-    "ws": "^8.11.0"
+    "ws": "^8.12.0"
   },
   "devDependencies": {
-    "@ircam/eslint-config": "^1.0.0",
+    "@ircam/eslint-config": "^1.3.0",
     "chai": "^4.3.6",
     "chai-shallow-deep-equal": "^1.4.6",
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
-    "docdash": "^1.2.0",
-    "dotenv": "^16.0.3",
-    "eslint": "^8.24.0",
-    "eslint-plugin-jsdoc": "^39.6.4",
+    "docdash": "^2.0.1",
+    "dotenv": "^16.3.1",
+    "eslint": "^8.44.0",
+    "eslint-plugin-jsdoc": "^46.4.3",
     "generate-changelog": "^1.8.0",
-    "jsdoc": "^3.6.10",
+    "jsdoc": "^4.0.0",
     "markdown-toc": "^1.2.0",
-    "mocha": "^9.2.2",
-    "puppeteer": "^18.0.5",
+    "mocha": "^10.2.0",
+    "puppeteer": "^20.7.4",
     "tcp-ping": "^0.1.1",
-    "typescript": "^4.9.3"
+    "typescript": "^5.1.6"
   },
   "optionalDependencies": {
     "bufferutil": "^4.0.5",

package/src/client/Client.js

@@ -1,4 +1,4 @@
-import isPlainObject from 'is-plain-obj';
+import { isBrowser, isPlainObject } from '@ircam/sc-utils';
 
 import ContextManager from './ContextManager.js';
 import PluginManager from './PluginManager.js';
@@ -10,11 +10,43 @@ import {
   CLIENT_HANDSHAKE_ERROR,
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
-import { isBrowser } from '../common/utils.js';
 import logger from '../common/logger.js';
 
 /**
- * The `Client` class is the main entry point for  the client-side of soundworks
+ * Configuration object for a client running in a browser runtime.
+ *
+ * @typedef BrowserClientConfig
+ * @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 {string} [env.websockets={}] - Configuration options for websockets.
+ * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
+ */
+
+/**
+ * Configuration object for a client running in a node runtime.
+ *
+ * @typedef NodeClientConfig
+ * @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.serverAddress - Domain name or IP of the server.
+ * @property {boolean} env.useHttps - Define is the server run in http or in https.
+ * @property {boolean} env.port - Port on which the server is listening.
+ * @property {string} [env.websockets={}] - Configuration options for websockets.
+ * @property {string} [env.subpath=''] - If running behind a proxy, path to the application.
+ */
+
+/**
+ * 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},
@@ -166,6 +198,12 @@ class Client {
      */
     this.status = 'idle';
 
+    /**
+     * Token of the client if connected through HTTP authentication.
+     * @private
+     */
+    this.token = null;
+
     /** @private */
     this._onStatusChangeCallbacks = new Set();
     /** @private */
@@ -208,9 +246,10 @@ class Client {
     try {
       await new Promise((resolve, reject) => {
         // wait for handshake response before starting stateManager and pluginManager
-        this.socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid }) => {
+        this.socket.addListener(CLIENT_HANDSHAKE_RESPONSE, async ({ id, uuid, token }) => {
           this.id = id;
           this.uuid = uuid;
+          this.token = token;
 
           resolve();
         });
@@ -218,7 +257,7 @@ class Client {
         this.socket.addListener(CLIENT_HANDSHAKE_ERROR, (err) => {
           let msg = ``;
 
-          switch(err.type) {
+          switch (err.type) {
             case 'invalid-client-type':
               msg = `[soundworks:Client] ${err.message}`;
               break;
@@ -242,7 +281,7 @@ class Client {
 
         this.socket.send(CLIENT_HANDSHAKE_REQUEST, payload);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
 
@@ -269,8 +308,9 @@ class Client {
    * 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.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'

package/src/client/Context.js

@@ -69,11 +69,15 @@ class Context {
 
     /**
      * 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';
 
@@ -113,10 +117,16 @@ class Context {
   }
 
   /**
-   * Name of the context. Defaults to the class name, override to use a user-defined name.
+   * Optionnal user-defined name of the context (defaults to the class name).
    *
-   * @returns {string} - Name of the context.
+   * 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
+   * user-defined context with the same name, it will use a default (noop) 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';
@@ -128,21 +138,38 @@ class Context {
   }
 
   /**
-   * 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 lazilly called when the client enters the
+   * context for the first time (cf. ${client.Context#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.
+   *
+   * 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();
    */
   async start() {}
 
   /**
    * 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._
    */
   async stop() {}
 
@@ -182,7 +209,7 @@ class Context {
         const reqId = storeRequestPromise(resolve, reject);
         this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
   }
@@ -216,7 +243,7 @@ class Context {
         const reqId = storeRequestPromise(resolve, reject);
         this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
   }

package/src/client/ContextManager.js

@@ -78,7 +78,7 @@ class ContextManager {
         this._contextStartPromises.set(contextName, startPromise);
         await startPromise;
         context.status = 'started';
-      } catch(err) {
+      } catch (err) {
         context.status = 'errored';
         throw new Error(err);
       }

package/src/client/Plugin.js

@@ -14,7 +14,8 @@ import BasePlugin from '../common/BasePlugin.js';
  */
 
 /**
- * Base class to extend in order to create new `soundworks` plugins.
+ * 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

package/src/client/PluginManager.js

@@ -23,7 +23,7 @@ import Client from './Client.js';
  *
  * Plugins should always be registered both client-side and server-side,
  * and before {@link client.Client#start} or {@link server.Server#start}
- * are called for proper initialization.
+ * to be properly initialized.
  *
  * In some sitautions, 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.).
@@ -35,12 +35,13 @@ import Client from './Client.js';
  * See {@link client.Client#pluginManager}
  *
  * ```
+ * // client-side
  * import { Client } from '@soundworks/core/client.js';
- * import platformPlugin from '@soundworks/plugin-sync/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', pluginSync);
+ * client.pluginManager.register('sync', syncPlugin);
  *
  * await client.start();
  *
@@ -52,6 +53,25 @@ import Client from './Client.js';
  * }, 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);
+ * ```
+ *
  * @memberof client
  * @extends BasePluginManager
  * @inheritdoc
@@ -63,7 +83,7 @@ class PluginManager extends BasePluginManager {
    */
   constructor(client) {
     if (!(client instanceof Client)) {
-      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client as argument"`);
+      throw new Error(`[soundworks.PluginManager] Invalid argument, "new PluginManager(client)" should receive an instance of "soundworks.Client" as argument`);
     }
 
     super(client);
@@ -91,8 +111,8 @@ class PluginManager extends BasePluginManager {
    * 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 (hopefully
-   * without brealing changes) in a future release._
+   * _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}
@@ -105,18 +125,7 @@ class PluginManager extends BasePluginManager {
       throw new Error(`[soundworks.PluginManager] Cannot get plugin before "client.init()"`);
     }
 
-    return super.getUnsafe(id);
-  }
-
-  // client only methods
-  // ------------------------------------------------------------
-
-  /**
-   * @protected
-   * @ignore
-   */
-  getRegisteredPlugins() {
-    return Array.from(this._registeredPlugins.keys());
+    return super.unsafeGet(id);
   }
 }
 

package/src/client/SharedStateCollection.js

@@ -0,0 +1,35 @@
+import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
+
+// this file exists only for documentation purposesSharedStateCollection.js
+
+/**
+ * @callback client.SharedStateCollection~onUpdateCallback
+ * @param {client.SharedState} state - State that triggered the update.
+ * @param {Object} newValues - Key / value pairs of the updates that have been
+ *  applied to the state.
+ * @param {Object} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state.
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
+ *  with the values updates in the `set` call.
+ */
+
+/**
+ * The `SharedStateCollection` interface represent a collection of all states
+ * created from a given schema name on the network, at the execption of the ones
+ * created by the current node.
+ *
+ * ```
+ * const collection = await client.stateManager.getCollection('my-schema');
+ * const allValues = collection.getValues();
+ * collection.onUpdate((state, newValues, oldValues, context) => {
+ *   // do something
+ * });
+ * ```
+ * @memberof client
+ * @extends BaseSharedStateCollection
+ * @inheritdoc
+ * @hideconstructor
+ */
+class SharedStateCollection extends BaseSharedStateCollection {}
+
+export default SharedStateCollection;