@soundworks/core 4.0.0-alpha.3 → 4.0.0-alpha.5

package/.github/workflows/main.yml

@@ -0,0 +1,15 @@
+name: "Unit Tests"
+on: push
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v3.3.0
+            - 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,4 +1,4 @@
-# `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/)
@@ -21,7 +21,7 @@ npx @soundworks/create@latest
 
 ![./assets/soundworks-create-min.gif](./assets/soundworks-create-min.gif)
 
-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`.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.3",
+  "version": "4.0.0-alpha.5",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -53,14 +53,14 @@
   },
   "dependencies": {
     "@ircam/sc-gettime": "^1.0.0",
-    "chalk": "^4.1.2",
+    "@ircam/sc-utils": "^1.0.1",
+    "chalk": "^5.2.0",
     "columnify": "^1.6.0",
     "compression": "^1.7.1",
     "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",
@@ -68,25 +68,25 @@
     "pem": "^1.14.6",
     "serve-static": "^1.15.0",
     "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",
+    "docdash": "^2.0.1",
     "dotenv": "^16.0.3",
-    "eslint": "^8.24.0",
-    "eslint-plugin-jsdoc": "^39.6.4",
+    "eslint": "^8.32.0",
+    "eslint-plugin-jsdoc": "^40.0.0",
     "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": "^19.5.2",
     "tcp-ping": "^0.1.1",
     "typescript": "^4.9.3"
   },

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,7 +10,6 @@ import {
   CLIENT_HANDSHAKE_ERROR,
   AUDIT_STATE_NAME,
 } from '../common/constants.js';
-import { isBrowser } from '../common/utils.js';
 import logger from '../common/logger.js';
 
 /**
@@ -251,7 +250,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;
@@ -275,7 +274,7 @@ class Client {
 
         this.socket.send(CLIENT_HANDSHAKE_REQUEST, payload);
       });
-    } catch(err) {
+    } catch (err) {
       throw new Error(err);
     }
 

package/src/client/Context.js

@@ -209,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);
     }
   }
@@ -243,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/Socket.js

@@ -1,3 +1,4 @@
+import { isBrowser } from '@ircam/sc-utils';
 import WebSocket from 'isomorphic-ws';
 
 import {
@@ -7,7 +8,6 @@ import {
   unpackStringMessage,
 } from '../common/sockets-utils.js';
 import logger from '../common/logger.js';
-import { isBrowser } from '../common/utils.js';
 
 // WebSocket events:
 //

package/src/common/BasePluginManager.js

@@ -1,7 +1,6 @@
-import isPlainObject from 'is-plain-obj';
+import { isPlainObject, isString } from '@ircam/sc-utils';
 
 import logger from './logger.js';
-import { isString } from './utils.js';
 
 /**
  * Shared functionnality between server-side and client-size plugin manager
@@ -111,9 +110,9 @@ class BasePluginManager {
     try {
       await Promise.all(promises);
       this.status = 'started';
-    } catch(err) {
+    } catch (err) {
       this.status = 'errored';
-      throw new Error(err);
+      throw err; // throw initial error
     }
   }
 
@@ -170,7 +169,7 @@ class BasePluginManager {
         this._instanceStartPromises.set(id, startPromise);
 
         await startPromise;
-      } catch(err) {
+      } catch (err) {
         errored = true;
         this._propagateStateChange(instance, 'errored');
         throw err;

package/src/common/BaseSharedState.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from '@ircam/sc-utils';
 import ParameterBag from './ParameterBag.js';
 import {
   DELETE_REQUEST,
@@ -34,7 +35,7 @@ class BaseSharedState {
     try {
       /** @private */
       this._parameters = new ParameterBag(schema, initValues);
-    } catch(err) {
+    } catch (err) {
       console.error(err.stack);
 
       throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
@@ -255,6 +256,14 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
+    if (!isPlainObject(updates)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+    }
+
+    if (context !== null && !isPlainObject(context)) {
+      throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
+    }
+
     // handle immediate option
     const immediateNewValues = {};
     const immediateOldValues = {};
@@ -263,7 +272,7 @@ ${JSON.stringify(initValues, null, 2)}`);
     for (let name in updates) {
       // throw early (client-side and not only server-side) if parameter is undefined
       if (!this._parameters.has(name)) {
-        throw new ReferenceError(`[stateManager] Cannot set value of undefined parameter "${name}"`);
+        throw new ReferenceError(`[SharedState] State "${this.schemaName}": cannot set value of undefined parameter "${name}"`);
       }
 
       // @note: general idea...
@@ -407,7 +416,7 @@ ${JSON.stringify(initValues, null, 2)}`);
     if (this._isOwner) {
       return this.detach();
     } else {
-      throw new Error(`[stateManager] can delete state "${this.schemaName}", only owner of the state (i.e. the node that "create[d]" it) can delete it`);
+      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.`);
     }
   }
 

package/src/common/promise-store.js

@@ -1,4 +1,4 @@
-import { idGenerator } from './utils.js';
+import { idGenerator } from '@ircam/sc-utils';
 
 const generateRequestId = idGenerator();
 const requestPromises = new Map();

package/src/server/Client.js

@@ -1,7 +1,6 @@
+import { idGenerator } from '@ircam/sc-utils';
 import { v4 as uuid } from 'uuid';
 
-import { idGenerator } from '../common/utils.js';
-
 const generateId = idGenerator();
 
 /**

package/src/server/ContextManager.js

@@ -114,7 +114,7 @@ class ContextManager {
         this._contextStartPromises.set(contextName, startPromise);
         await startPromise;
         context.status = 'started';
-      } catch(err) {
+      } catch (err) {
         context.status = 'errored';
         throw new Error(err);
       }
@@ -144,7 +144,7 @@ class ContextManager {
       let context;
       try {
         context = await this.get(contextName);
-      } catch(err) {
+      } catch (err) {
         client.socket.send(
           CONTEXT_ENTER_ERROR,
           reqId,
@@ -185,7 +185,7 @@ class ContextManager {
         await context.enter(client);
 
         client.socket.send(CONTEXT_ENTER_RESPONSE, reqId, contextName);
-      } catch(err) {
+      } catch (err) {
         client.socket.send(CONTEXT_ENTER_ERROR, reqId, contextName, err.message);
       }
     });
@@ -207,7 +207,7 @@ class ContextManager {
         try {
           await context.exit(client);
           client.socket.send(CONTEXT_EXIT_RESPONSE, reqId, contextName);
-        } catch(err) {
+        } catch (err) {
           client.socket.send(CONTEXT_EXIT_ERROR, reqId, contextName, err.message);
         }
       } else {

package/src/server/Server.js

@@ -5,10 +5,10 @@ import path from 'node:path';
 import os from 'node:os';
 import { X509Certificate, createPrivateKey } from 'node:crypto';
 
+import { isPlainObject } from '@ircam/sc-utils';
 import chalk from 'chalk';
 import compression from 'compression';
 import express from 'express';
-import isPlainObject from 'is-plain-obj';
 import Keyv from 'keyv';
 import { KeyvFile } from 'keyv-file';
 import merge from 'lodash.merge';
@@ -236,7 +236,7 @@ class Server {
      * // expose assets located in the `soundfiles` directory on the network
      * server.router.use('/soundfiles', express.static('soundfiles')));
      */
-    this.router = express();
+    this.router = express.Router();
     // compression (must be set before serve-static)
     this.router.use(compression());
 
@@ -357,7 +357,7 @@ class Server {
 
     // basic http authentication
     if (this.config.env.auth) {
-      this.router.use((req, res, next) => {
+      const soundworksAuth = (req, res, next) => {
 
         const isProtected  = this.config.env.auth.clients
           .map(type => req.path.endsWith(`/${type}`))
@@ -386,7 +386,9 @@ class Server {
           // route not protected
           return next();
         }
-      });
+      };
+
+      this.router.use(soundworksAuth);
     }
 
     // start http server
@@ -411,7 +413,7 @@ class Server {
           // this fails with self-signed certificates for whatever reason...
           try {
             x509 = new X509Certificate(cert);
-          } catch(err) {
+          } catch (err) {
             this._dispatchStatus('errored');
             throw new Error(`[soundworks:Server] Invalid https cert file`);
           }
@@ -423,7 +425,7 @@ class Server {
               this._dispatchStatus('errored');
               throw new Error(`[soundworks:Server] Invalid https key file`);
             }
-          } catch(err) {
+          } catch (err) {
             this._dispatchStatus('errored');
             throw new Error(`[soundworks:Server] Invalid https key file`);
           }
@@ -447,7 +449,7 @@ class Server {
           };
 
           this.httpServer = https.createServer({ key, cert }, this.router);
-        } catch(err) {
+        } catch (err) {
           logger.error(`
 Invalid certificate files, please check your:
 - key file: ${httpsInfos.key}
@@ -726,7 +728,7 @@ Invalid certificate files, please check your:
     try {
       const stats = fs.statSync(clientTmpl);
       template = stats.isFile() ? clientTmpl : defaultTmpl;
-    } catch(err) {
+    } catch (err) {
       template = defaultTmpl;
     }
 
@@ -734,13 +736,13 @@ Invalid certificate files, please check your:
 
     try {
       tmplString = fs.readFileSync(template, 'utf8');
-    } catch(err) {
+    } catch (err) {
       throw new Error(`[soundworks:Server] html template file "${template}" not found`);
     }
 
     const tmpl = templateEngine.compile(tmplString);
-    // http request
-    router.get(route, (req, res) => {
+
+    const soundworksClientHandler = (req, res) => {
       const data = clientConfigFunction(role, this.config, req);
 
       // CORS / COOP / COEP headers for `crossOriginIsolated pages,
@@ -756,7 +758,9 @@ Invalid certificate files, please check your:
 
       const appIndex = tmpl(data);
       res.end(appIndex);
-    });
+    };
+    // http request
+    router.get(route, soundworksClientHandler);
 
     // return route infos for logging on server start
     return route;
@@ -805,7 +809,7 @@ Invalid certificate files, please check your:
 
       try {
         this.pluginManager.checkRegisteredPlugins(registeredPlugins);
-      } catch(err) {
+      } catch (err) {
         socket.send(CLIENT_HANDSHAKE_ERROR, {
           type: 'invalid-plugin-list',
           message: err.message,

package/src/server/SharedState.js

@@ -18,7 +18,6 @@ import BaseSharedState from '../common/BaseSharedState.js';
  * @callback server.SharedState~deleteOnUpdateCallback
  */
 
-
 /**
  * The `SharedState` is one of the most important and versatile abstraction provided
  * by `soundworks`. It represents a set of parameters that are synchronized accross

package/src/server/StateManager.js

@@ -1,11 +1,11 @@
 import EventEmitter from 'node:events';
 
+import { idGenerator, isString, isPlainObject } from '@ircam/sc-utils';
 import clonedeep from 'lodash.clonedeep';
 
 import BaseStateManager from '../common/BaseStateManager.js';
 import ParameterBag from '../common/ParameterBag.js';
 import SharedStatePrivate from '../common/SharedStatePrivate.js';
-import { isString, isPlainObject } from '../common/utils.js';
 import {
   SERVER_ID,
   CREATE_REQUEST,
@@ -22,7 +22,7 @@ import {
   DELETE_SCHEMA,
   PRIVATE_STATES,
 } from '../common/constants.js';
-import { idGenerator } from '../common/utils.js';
+
 
 const generateStateId = idGenerator();
 const generateRemoteId = idGenerator();
@@ -361,7 +361,7 @@ class StateManager extends BaseStateManager {
           this._observers.forEach(observer => {
             observer.transport.emit(OBSERVE_NOTIFICATION, [schemaName, stateId, nodeId]);
           });
-        } catch(err) {
+        } catch (err) {
           client.transport.emit(CREATE_ERROR, reqId, err.message);
           console.error(err.message);
         }

package/src/common/utils.js

@@ -1,28 +0,0 @@
-import isPlainObj from 'is-plain-obj';
-
-// https://stackoverflow.com/questions/17575790/environment-detection-node-js-or-browser
-export const isBrowser = new Function('try {return this===window;}catch(e){ return false;}');
-
-export function* idGenerator() {
-  for (let i = 0; true; i++) {
-    if (i === Number.MAX_SAFE_INTEGER) {
-      i = 0;
-    }
-
-    yield i;
-  }
-}
-
-export function isString(val) {
-  return (typeof val === 'string' || val instanceof String);
-}
-
-export function isFunction(func) {
-  return Object.prototype.toString.call(func) == '[object Function]' ||
-    Object.prototype.toString.call(func) == '[object AsyncFunction]';
-}
-
-export function isPlainObject(obj) {
-  return isPlainObj(obj);
-}
-