@soundworks/core 4.0.0-alpha.7 → 4.0.0-alpha.9

package/README.md

@@ -7,13 +7,13 @@
 
 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
@@ -21,7 +21,7 @@ npx @soundworks/create@latest
 
 ![./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`.
+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
@@ -45,7 +45,7 @@ Feel welcome to open an [issue](https://github.com/collective-soundworks/soundwo
 
 ## Share with Us
 
-If you made an application using `soundworks` please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
+If you made an application using **soundworks** please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
 
 ## TypeScript Support
 
@@ -55,7 +55,7 @@ However, for maintenance reasons, we aim at following the TC39 and W3C specifica
 
 ## 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
@@ -63,28 +63,9 @@ npm install @soundworks/core
 
 ## 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 context of the [CoSiMa](http://cosima.ircam.fr/) research project founded by the French National Research Agency (ANR).
-
-Development is now led by Benjamin Matuszewski, in the [Sound Music Movement Interaction Team](https://www.stms-lab.fr/team/interaction-son-musique-mouvement/) from the Ircam's STMS-LAB.
-
-### Supporting Research Projects
-
-Initial and futher developments has been supported by the following research projects:
-
-- The [DOTS](http://dots.ircam.fr/) project, funded by the French National Research Agency (ANR)
-- The Ircam projects _BeCoMe_ and _SO(a)P_
-- The _Constella(c)tions_ residency, funded by the STARTS program of the European Commission
-- The [RAPID-MIX project](http://rapidmix.goldsmithsdigital.com/), funded by the European Union’s Horizon 2020 research and innovation program
-- The [CoSiMa](http://cosima.ircam.fr/) project, funded by the French National Research Agency (ANR)
-
-### 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)>
+[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.7",
+  "version": "4.0.0-alpha.9",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -48,15 +48,15 @@
     "test": "mocha",
     "toc": "markdown-toc -i README.md",
     "types": "rm -Rf types && tsc",
-    "version": "npm run toc"
+    "preversion": "npm run toc && git commit -am 'docs: build' --allow-empty"
   },
   "dependencies": {
-    "@ircam/sc-gettime": "^1.0.0",
-    "@ircam/sc-utils": "^1.0.1",
-    "chalk": "^5.2.0",
+    "@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.5",
+    "cross-fetch": "^3.1.8",
     "express": "^4.18.1",
     "fast-deep-equal": "^3.1.3",
     "fast-text-encoding": "^1.0.0",
@@ -65,7 +65,7 @@
     "keyv-file": "^0.2.0",
     "lodash.clonedeep": "^4.5.0",
     "lodash.merge": "^4.6.2",
-    "pem": "^1.14.6",
+    "pem": "^1.14.8",
     "template-literal": "^1.0.4",
     "uuid": "^9.0.0",
     "window-or-global": "^1.0.1",
@@ -78,16 +78,16 @@
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
     "docdash": "^2.0.1",
-    "dotenv": "^16.0.3",
-    "eslint": "^8.32.0",
-    "eslint-plugin-jsdoc": "^40.0.0",
+    "dotenv": "^16.3.1",
+    "eslint": "^8.44.0",
+    "eslint-plugin-jsdoc": "^46.4.3",
     "generate-changelog": "^1.8.0",
     "jsdoc": "^4.0.0",
     "markdown-toc": "^1.2.0",
     "mocha": "^10.2.0",
-    "puppeteer": "^19.5.2",
+    "puppeteer": "^20.7.4",
     "tcp-ping": "^0.1.1",
-    "typescript": "^4.9.3"
+    "typescript": "^5.1.6"
   },
   "optionalDependencies": {
     "bufferutil": "^4.0.5",

package/src/common/BaseSharedState.js

@@ -21,10 +21,12 @@ import {
 
 class BaseSharedState {
   constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
-    this.id = id;
-    this.remoteId = remoteId;
-    this.schemaName = schemaName;
-
+    /** @private */
+    this._id = id;
+    /** @private */
+    this._remoteId = remoteId;
+    /** @private */
+    this._schemaName = schemaName;
     /** @private */
     this._isOwner = isOwner; // may be the server or any client
     /** @private */
@@ -32,6 +34,8 @@ class BaseSharedState {
     /** @private */
     this._manager = manager;
 
+    this._detached = false;
+
     try {
       /** @private */
       this._parameters = new ParameterBag(schema, initValues);
@@ -88,14 +92,25 @@ ${JSON.stringify(initValues, null, 2)}`);
     });
 
     // ---------------------------------------------
-    // DELETE initiated by creator, or schema deleted
+    // state has been deleted by its creator or the schema has been deleted
     // ---------------------------------------------
-    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, () => {
+    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, async () => {
       this._manager._statesById.delete(this.id);
       this._clearTransport();
 
-      this._onDetachCallbacks.forEach(callback => callback());
-      this._onDeleteCallbacks.forEach(callback => callback());
+      for (let callback of this._onDetachCallbacks) {
+        try {
+          await callback();
+        } catch(err) {
+          console.error(err.message);
+        }
+      }
+
+      if (this._isOwner) {
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
+      }
 
       this._clearDetach();
     });
@@ -103,14 +118,19 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     if (this._isOwner) {
       // ---------------------------------------------
-      // DELETE (can only delete if creator)
+      // the creator has called `.delete()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
+      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
         this._manager._statesById.delete(this.id);
         this._clearTransport();
 
-        this._onDetachCallbacks.forEach(callback => callback());
-        this._onDeleteCallbacks.forEach(callback => callback());
+        for (let callback of this._onDetachCallbacks) {
+          await callback();
+        }
+
+        for (let callback of this._onDeleteCallbacks) {
+          await callback();
+        }
 
         this._clearDetach();
         resolveRequest(reqId, this);
@@ -122,13 +142,15 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     } else {
       // ---------------------------------------------
-      // DETACH
+      // the attached node has called `.detach()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, (reqId) => {
+      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
         this._manager._statesById.delete(this.id);
         this._clearTransport();
 
-        this._onDetachCallbacks.forEach(func => func());
+        for (let callback of this._onDetachCallbacks) {
+          await callback();
+        }
 
         this._clearDetach();
         resolveRequest(reqId, this);
@@ -141,16 +163,48 @@ ${JSON.stringify(initValues, null, 2)}`);
     }
   }
 
+  /**
+   * Id of the state
+   * @type {Number}
+   * @readonly
+   */
+  get id() {
+    return this._id;
+  }
+
+  /**
+   * Unique id of the state for the current node
+   * @readonly
+   * @type {Number}
+   * @private
+   */
+  get remoteId() {
+    return this._remoteId;
+  }
+
+  /**
+   * Name of the schema
+   * @type {String}
+   * @readonly
+   */
+  get schemaName() {
+    return this._schemaName;
+  }
+
+  /**
+   * Indicates if the node is the owner of the state
+   * @type {Boolean}
+   * @readonly
+   */
+  get isOwner() {
+    return this._isOwner;
+  }
+
   /** @private */
   _clearDetach() {
     this._onDetachCallbacks.clear();
     this._onDeleteCallbacks.clear();
-
-    // Monkey patch detach so it throws if called twice. Doing nothing blocks
-    // the process on a second `detach` call as the Promise never resolves
-    this.detach = () => {
-      throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
-    };
+    this._detached = true;
   }
 
   /** @private */
@@ -411,7 +465,7 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Detach from the state. If the client is the creator of the state, the state
-   * is deleted and all attached nodes get notified
+   * is deleted and all attached nodes get notified.
    *
    * @example
    * const state = await client.state.attach('globals');
@@ -419,6 +473,10 @@ ${JSON.stringify(initValues, null, 2)}`);
    * await state.detach();
    */
   async detach() {
+    if (this._detached) {
+      throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
+    }
+
     this._onUpdateCallbacks.clear();
 
     if (this._isOwner) {
@@ -436,9 +494,11 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Delete the state. Only the creator/owner of the state can use this method.
-   * All nodes attached to the state will be deteched, triggering the `onDetach`
-   * callback. The creator of the state will also have its `onDelete` callback
-   * triggered.
+   *
+   * All nodes attached to the state will be detached, triggering any registered
+   * `onDetach` callbacks. The creator of the state will also have its own `onDelete`
+   * callback triggered. The local `onDeatch` and `onDelete` callbacks will be
+   * executed *before* the returned Promise resolves
    *
    * @throws Throws if the method is called by a node which is not the owner of
    * the state.
@@ -449,6 +509,10 @@ ${JSON.stringify(initValues, null, 2)}`);
    */
   async delete() {
     if (this._isOwner) {
+      if (this._detached) {
+        throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already deleted, cannot delete twice`);
+      }
+
       return this.detach();
     } else {
       throw new Error(`[SharedState] Cannot delete state "${this.schemaName}", only the owner of the state (i.e. the node that created it) can delete the state. Use "detach" instead.`);
@@ -491,7 +555,8 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Register a function to execute when detaching from the state
+   * Register a function to execute when detaching from the state. The function
+   * will be executed before the `detach` promise resolves.
    *
    * @param {Function} callback - Callback to execute when detaching from the state.
    *   Whether the client as called `detach`, or the state has been deleted by its
@@ -504,7 +569,8 @@ ${JSON.stringify(initValues, null, 2)}`);
 
   /**
    * Register a function to execute when the state is deleted. Only called if the
-   * node was the creator of the state. Is called after `onDetach`
+   * node was the creator of the state. Is called after `onDetach` and executed
+   * before the `delete` Promise resolves.
    *
    * @param {Function} callback - Callback to execute when the state is deleted.
    */

package/src/common/BaseStateManager.js

@@ -179,8 +179,11 @@ class BaseStateManager {
    * the state of all other clients of the application, to monitor them and/or take
    * control over them from a single point.
    *
-   * Note that the states that are created by the same node are not propagated through
+   * Notes:
+   * - The states that are created by the same node are not propagated through
    * the observe callback.
+   * - The order of execution is not guaranted, i.e. an state attached in the
+   * `observe` callback could be created before the `async create` method resolves.
    *
    * @param {String} [schemaName] - optionnal schema name to filter the observed
    *  states.

package/src/server/Server.js

@@ -25,6 +25,7 @@ import StateManager from './StateManager.js';
 import Sockets from './Sockets.js';
 import logger from '../common/logger.js';
 import {
+  SERVER_ID,
   CLIENT_HANDSHAKE_REQUEST,
   CLIENT_HANDSHAKE_RESPONSE,
   CLIENT_HANDSHAKE_ERROR,
@@ -331,6 +332,15 @@ class Server {
     setTerminalTitle(this);
   }
 
+  /**
+   * Id of the server, a constant set to -1
+   * @type {Number}
+   * @readonly
+   */
+  get id() {
+    return SERVER_ID;
+  }
+
   /**
    * The `init` method is part of the initialization lifecycle of the `soundworks`
    * server. Most of the time, the `init` method will be implicitly called by the