@soundworks/core 4.0.0-alpha.14 → 4.0.0-alpha.16

package/.jsdoc

@@ -0,0 +1,57 @@
+{
+  "source": {
+    "include": [
+      "misc/assets/DOC.md",
+      "src/client",
+      "src/server",
+      "src/common"
+    ]
+  },
+  "plugins": [
+    "plugins/markdown"
+  ],
+  "opts": {
+    "projectTitle": "Soundworks",
+    "destination": "./docs",
+    "encoding": "utf8",
+    "template": "./node_modules/docdash"
+  },
+  "templates": {
+    "default": {
+      "useLongnameInNav": true
+    },
+    "footer": ""
+  },
+  "docdash": {
+    "sectionOrder": [
+      "Namespaces",
+      "Classes",
+      "Modules",
+      "Externals",
+      "Events",
+      "Mixins",
+      "Tutorials",
+      "Interfaces"
+    ],
+    "scripts": [
+      "assets/custom.css"
+    ],
+    "meta": {
+        "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/",
+        "target":"_blank",
+        "class":"menu-item"
+      },
+      "Github": {
+        "href": "https://github.com/collective-soundworks/soundworks",
+        "target":"_blank",
+        "class":"menu-item"
+      }
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+## v4.0.0-alpha.16 - 15/12/2023
+
+- improve StateCollection performances
+
+## v4.0.0-alpha.15 - 13/12/2023
+
+- Fix several issues with shared states
+- **Breaking Change**: by default, `StateManager::observe` and `SharedStateCollection` now retrieve locally created states

package/README.md

@@ -3,57 +3,38 @@
 [![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)
+![soundworks-logo](./misc/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.
 
-*__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. 
-
-```sh
-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**.
-
-<!--
 ## Documentation
 
 - Guides and Tutorials: [https://soundworks.dev](https://soundworks.dev)
 - API: [https://soundworks.dev/api](https://soundworks.dev/api)
--->
 
-## API
+## Getting started
 
-The API is not publicly published for now. To access the API documentation locally, just clone this repository, go to the v4 branch and launch some http server in the docs directory. For example, using the [serve](https://www.npmjs.com/package/serve) package:
+The best and most simple way to start using **soundworks** is to use the `@soundworks/create` wizard. 
 
 ```sh
-git clone https://github.com/collective-soundworks/soundworks.git
-cd soundworks
-git checkout v4
-serve docs
+npx @soundworks/create@latest
 ```
 
-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.
+![soundworks-create](./misc/assets/soundworks-create-min.gif)
 
-## Share with Us
+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 using **soundworks**.
 
-If you made an application using **soundworks** please let us know here: https://github.com/collective-soundworks/soundworks/discussions/61
+## Misc
 
-## TypeScript Support
+### TypeScript support
 
 Basic TypeScript support will be proposed in a (hopefully) near future. 
 
 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
+### Manual 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.
 
@@ -61,6 +42,10 @@ Note that the `@soundworks/core` package is automatically installed when creatin
 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
+
 ## Credits
 
 [https://soundworks.dev/credits.html](https://soundworks.dev/credits.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.14",
+  "version": "4.0.0-alpha.16",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,51 +43,45 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "doc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R assets docs/",
+    "doc": "rm -Rf docs && jsdoc -c .jsdoc --verbose && cp -R misc/assets docs/",
     "lint": "npx eslint src",
-    "test": "mocha",
-    "toc": "markdown-toc -i README.md",
+    "test": "npx mocha",
+    "test:all": "npx mocha tests/*/*.spec.js",
     "types": "rm -Rf types && tsc",
-    "preversion": "npm run toc && git commit -am 'docs: build' --allow-empty"
+    "postversion": "node ./misc/scripts/check-changelog.js"
   },
   "dependencies": {
-    "@ircam/sc-gettime": "^1.0.1",
-    "@ircam/sc-utils": "^1.1.1",
+    "@ircam/sc-utils": "^1.3.2",
     "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",
     "isomorphic-ws": "^5.0.0",
-    "keyv": "^4.2.2",
-    "keyv-file": "^0.2.0",
-    "lodash.clonedeep": "^4.5.0",
-    "lodash.merge": "^4.6.2",
+    "keyv": "^4.5.4",
+    "keyv-file": "^0.3.0",
+    "lodash": "^4.17.21",
     "pem": "^1.14.8",
     "template-literal": "^1.0.4",
-    "uuid": "^9.0.0",
-    "window-or-global": "^1.0.1",
-    "ws": "^8.12.0"
+    "uuid": "^9.0.1",
+    "ws": "^8.15.0"
   },
   "devDependencies": {
     "@ircam/eslint-config": "^1.3.0",
-    "chai": "^4.3.6",
+    "chai": "^4.3.10",
     "chai-shallow-deep-equal": "^1.4.6",
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
-    "docdash": "^2.0.1",
+    "docdash": "^2.0.2",
     "dotenv": "^16.3.1",
-    "eslint": "^8.44.0",
-    "eslint-plugin-jsdoc": "^46.4.3",
-    "generate-changelog": "^1.8.0",
+    "eslint": "^8.55.0",
+    "eslint-plugin-jsdoc": "^46.9.0",
     "jsdoc": "^4.0.0",
-    "markdown-toc": "^1.2.0",
     "mocha": "^10.2.0",
-    "puppeteer": "^20.7.4",
+    "puppeteer": "^21.6.0",
     "tcp-ping": "^0.1.1",
-    "typescript": "^5.1.6"
+    "typescript": "^5.3.3"
   },
   "optionalDependencies": {
     "bufferutil": "^4.0.5",

package/src/client/Context.js

@@ -1,4 +1,5 @@
 import Client from './Client.js';
+import PromiseStore from '../common/PromiseStore.js';
 import {
   CONTEXT_ENTER_REQUEST,
   CONTEXT_ENTER_RESPONSE,
@@ -7,11 +8,6 @@ import {
   CONTEXT_EXIT_RESPONSE,
   CONTEXT_EXIT_ERROR,
 } from '../common/constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from '../common/promise-store.js';
 
 /**
  * Base class to extend in order to implement a new Context.
@@ -81,12 +77,15 @@ class Context {
      */
     this.status = 'idle';
 
+    /** @private */
+    this._promiseStore = new PromiseStore(this.constructor.name);
+
     this.client.socket.addListener(CONTEXT_ENTER_RESPONSE, (reqId, contextName) => {
       if (contextName !== this.name) {
         return;
       }
 
-      resolveRequest(reqId);
+      this._promiseStore.resolve(reqId);
     });
 
     this.client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
@@ -94,7 +93,7 @@ class Context {
         return;
       }
 
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     this.client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
@@ -102,7 +101,7 @@ class Context {
         return;
       }
 
-      resolveRequest(reqId);
+      this._promiseStore.resolve(reqId);
     });
 
     this.client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
@@ -110,7 +109,7 @@ class Context {
         return;
       }
 
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     this.client.contextManager.register(this);
@@ -206,7 +205,7 @@ class Context {
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = this._promiseStore.add(resolve, reject, 'enter-context');
         this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
     } catch (err) {
@@ -240,7 +239,7 @@ class Context {
     // we need the try/catch block to change the promise rejection into proper error
     try {
       await new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = this._promiseStore.add(resolve, reject, 'exit-context');
         this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
       });
     } catch (err) {

package/src/client/SharedStateCollection.js

@@ -15,8 +15,11 @@ import BaseSharedStateCollection from '../common/BaseSharedStateCollection.js';
 
 /**
  * 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.
+ * created from a given schema name on the network.
+ *
+ * It can optionnaly exclude the states created by the current node.
+ *
+ * See {@link client.StateManager#getCollection} for factory method API
  *
  * ```
  * const collection = await client.stateManager.getCollection('my-schema');

package/src/client/Socket.js

@@ -1,5 +1,4 @@
 import { isBrowser } from '@ircam/sc-utils';
-import fetch from 'cross-fetch';
 import WebSocket from 'isomorphic-ws';
 
 import {

package/src/common/BasePlugin.js

@@ -1,4 +1,4 @@
-import merge from 'lodash.merge';
+import merge from 'lodash/merge.js';
 
 /**
  * @private

package/src/common/BasePluginManager.js

@@ -114,7 +114,7 @@ class BasePluginManager {
 
     this.status = 'inited';
     // instanciate all plugins
-    for (let [id, instance] of this._instances.entries()) {
+    for (let [_id, instance] of this._instances.entries()) {
       instance.onStateChange(_values => this._propagateStateChange(instance));
     }
 

package/src/common/BaseSharedState.js

@@ -1,5 +1,6 @@
 import { isPlainObject } from '@ircam/sc-utils';
 import ParameterBag from './ParameterBag.js';
+import PromiseStore from './PromiseStore.js';
 import {
   DELETE_REQUEST,
   DELETE_RESPONSE,
@@ -13,11 +14,14 @@ import {
   UPDATE_ABORT,
   UPDATE_NOTIFICATION,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
+
+// @todo - replace isOwner by `type`:
+// enum {
+//   'owner'
+//   'attached'
+//   'collection-controlller'
+//   'collection-attached'
+// }
 
 class BaseSharedState {
   constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
@@ -33,8 +37,13 @@ class BaseSharedState {
     this._client = client;
     /** @private */
     this._manager = manager;
-
+    /**
+     * true is the state has been detached or deleted
+     * @private
+     */
     this._detached = false;
+    /* @private */
+    this._promiseStore = new PromiseStore(this.constructor.name);
 
     try {
       /** @private */
@@ -56,13 +65,13 @@ ${JSON.stringify(initValues, null, 2)}`);
     // add listener for state updates
     this._client.transport.addListener(`${UPDATE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId, updates, context) => {
       const updated = await this._commit(updates, context, true, true);
-      resolveRequest(reqId, updated);
+      this._promiseStore.resolve(reqId, updated);
     });
 
     // retrieve values but do not propagate to subscriptions
     this._client.transport.addListener(`${UPDATE_ABORT}-${this.id}-${this.remoteId}`, async (reqId, updates, context) => {
       const updated = await this._commit(updates, context, false, true);
-      resolveRequest(reqId, updated);
+      this._promiseStore.resolve(reqId, updated);
     });
 
     this._client.transport.addListener(`${UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`, async (updates, context) => {
@@ -101,7 +110,7 @@ ${JSON.stringify(initValues, null, 2)}`);
       for (let callback of this._onDetachCallbacks) {
         try {
           await callback();
-        } catch(err) {
+        } catch (err) {
           console.error(err.message);
         }
       }
@@ -112,7 +121,9 @@ ${JSON.stringify(initValues, null, 2)}`);
         }
       }
 
-      this._clearDetach();
+      this._onDetachCallbacks.clear();
+      this._onDeleteCallbacks.clear();
+      this._promiseStore.flush();
     });
 
 
@@ -132,12 +143,14 @@ ${JSON.stringify(initValues, null, 2)}`);
           await callback();
         }
 
-        this._clearDetach();
-        resolveRequest(reqId, this);
+        this._onDetachCallbacks.clear();
+        this._onDeleteCallbacks.clear();
+        this._promiseStore.resolve(reqId, this);
+        this._promiseStore.flush();
       });
 
       this._client.transport.addListener(`${DELETE_ERROR}-${this.id}`, (reqId, msg) => {
-        rejectRequest(reqId, msg);
+        this._promiseStore.reject(reqId, msg);
       });
 
     } else {
@@ -152,13 +165,18 @@ ${JSON.stringify(initValues, null, 2)}`);
           await callback();
         }
 
-        this._clearDetach();
-        resolveRequest(reqId, this);
+        this._onDetachCallbacks.clear();
+        this._onDeleteCallbacks.clear();
+        this._promiseStore.resolve(reqId, this);
+        this._promiseStore.flush();
       });
 
       // the state does not exists anymore in the server (should not happen)
       this._client.transport.addListener(`${DETACH_ERROR}-${this.id}`, (reqId, msg) => {
-        rejectRequest(reqId, msg);
+        this._onDetachCallbacks.clear();
+        this._onDeleteCallbacks.clear();
+        this._promiseStore.reject(reqId, msg);
+        this._promiseStore.flush();
       });
     }
   }
@@ -200,13 +218,6 @@ ${JSON.stringify(initValues, null, 2)}`);
     return this._isOwner;
   }
 
-  /** @private */
-  _clearDetach() {
-    this._onDetachCallbacks.clear();
-    this._onDeleteCallbacks.clear();
-    this._detached = true;
-  }
-
   /** @private */
   _clearTransport() {
     // remove listeners
@@ -325,7 +336,7 @@ ${JSON.stringify(initValues, null, 2)}`);
     for (let name in updates) {
       // try to coerce value early, so that eventual errors are triggered early
       // on the node requesting the update
-      const _ = this._parameters.coerceValue(name, updates[name]);
+      this._parameters.coerceValue(name, updates[name]);
 
       // @note: general idea...
       // if immediate=true
@@ -358,7 +369,7 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     // go through server-side normal behavior
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'update-request');
       this._client.transport.emit(`${UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
     });
   }
@@ -426,12 +437,12 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Get the schema from which the state has been created.
+   * Definition of schema from which the state has been created.
    *
-   * @param {string} [name=null] - If given, returns only the definition corresponding
-   *  to the given param name.
+   * @param {string} [name=null] - If given, returns only the definition
+   *  corresponding to the given param name.
    * @throws Throws if `name` does not correspond to an existing field
-   *  of the state.
+   *  of the schema.
    * @return {object}
    * @example
    * const schema = state.getSchema();
@@ -477,16 +488,17 @@ ${JSON.stringify(initValues, null, 2)}`);
       throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
     }
 
+    this._detached = true; // mark detached early
     this._onUpdateCallbacks.clear();
 
     if (this._isOwner) {
       return new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = this._promiseStore.add(resolve, reject, 'delete-request');
         this._client.transport.emit(`${DELETE_REQUEST}-${this.id}-${this.remoteId}`, reqId);
       });
     } else {
       return new Promise((resolve, reject) => {
-        const reqId = storeRequestPromise(resolve, reject);
+        const reqId = this._promiseStore.add(resolve, reject, 'detach-request');
         this._client.transport.emit(`${DETACH_REQUEST}-${this.id}-${this.remoteId}`, reqId);
       });
     }

package/src/common/BaseSharedStateCollection.js

@@ -1,11 +1,20 @@
+import {
+  kCreateCollectionController,
+  kAttachInCollection,
+} from './BaseStateManager.js';
+
 /**
  * @private
  */
 class BaseSharedStateCollection {
-  constructor(stateManager, schemaName) {
+  constructor(stateManager, schemaName, options = {}) {
     this._stateManager = stateManager;
     this._schemaName = schemaName;
+    this._options = Object.assign({ excludeLocal: false }, options);
+
+    this._controller = null;
     this._states = [];
+
     this._onUpdateCallbacks = new Set();
     this._onAttachCallbacks = new Set();
     this._onDetachCallbacks = new Set();
@@ -13,9 +22,15 @@ class BaseSharedStateCollection {
   }
 
   async _init() {
-    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId, nodeId) => {
-      const state = await this._stateManager.attach(schemaName, stateId);
+    this._controller = await this._stateManager[kCreateCollectionController](this._schemaName);
+    this._controller.onUpdate(async (updates, context) => {
+      for (let state of this._states) {
+        await state._commit(updates, context, true, false);
+      }
+    });
 
+    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId) => {
+      const state = await this._stateManager[kAttachInCollection](schemaName, stateId);
       this._states.push(state);
 
       state.onDetach(() => {
@@ -32,11 +47,11 @@ class BaseSharedStateCollection {
       });
 
       this._onAttachCallbacks.forEach(callback => callback(state));
-    });
+    }, this._options);
   }
 
   /**
-   * Size of the collection
+   * Size of the collection, alias `size`
    * @type {number}
    */
   get length() {
@@ -44,17 +59,46 @@ class BaseSharedStateCollection {
   }
 
   /**
-   * Detach from the collection, i.e. detach all underlying shared states.
+   * Size of the collection, , alias `length`
    * @type {number}
    */
-  async detach() {
-    this._unobserve();
+  get size() {
+    return this._states.length;
+  }
 
-    const promises = Array.from(this._states).map(state => state.detach());
-    await Promise.all(promises);
+  /**
+   * Name of the schema from which the collection has been created.
+   * @type {String}
+   * @readonly
+   */
+  get schemaName() {
+    return this._controller.schemaName;
+  }
 
-    this._onUpdateCallbacks.clear();
-    this._onDetachCallbacks.clear();
+  /**
+   * Definition of schema from which the collection has been created.
+   *
+   * @param {string} [name=null] - If given, returns only the definition
+   *  corresponding to the given param name.
+   * @throws Throws if `name` does not correspond to an existing field
+   *  of the schema.
+   * @return {object}
+   * @example
+   * const schema = collection.getSchema();
+   */
+  getSchema(name = null) {
+    return this._controller.getSchema(name);
+  }
+
+  /**
+   * Get the default values as declared in the schema.
+   *
+   * @return {object}
+   * @example
+   * const defaults = state.getDefaults();
+   */
+  getDefaults() {
+    return this._controller.getDefaults();
   }
 
   /**
@@ -83,8 +127,7 @@ class BaseSharedStateCollection {
    *   current call and will be passed as third argument to all update listeners.
    */
   async set(updates, context = null) {
-    const promises = this._states.map(state => state.set(updates, context));
-    return Promise.all(promises);
+    return await this._controller.set(updates, context);
   }
 
   /**
@@ -145,6 +188,22 @@ class BaseSharedStateCollection {
     return () => this._onDetachCallbacks.delete(callback);
   }
 
+  /**
+   * Detach from the collection, i.e. detach all underlying shared states.
+   * @type {number}
+   */
+  async detach() {
+    this._unobserve();
+    this._onUpdateCallbacks.clear();
+
+    await this._controller.delete();
+
+    const promises = this._states.map(state => state.detach());
+    await Promise.all(promises);
+
+    this._onDetachCallbacks.clear();
+  }
+
   /**
    * Execute the given function once for each states of the collection (see `Array.forEach`).
    *
@@ -212,8 +271,8 @@ class BaseSharedStateCollection {
         } else {
           return { value: this._states[index++], done: false };
         }
-      }
-    }
+      },
+    };
   }
 }