@soundworks/core 4.0.0-alpha.15 → 4.0.0-alpha.17

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

@@ -1,3 +1,11 @@
+## v4.0.0-alpha.17 - 16/12/2023
+
+- Support bundling the server to cjs for Max externals
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soundworks/core",
-  "version": "4.0.0-alpha.15",
+  "version": "4.0.0-alpha.17",
   "description": "Open-source creative coding framework for distributed applications based on Web technologies",
   "authors": [
     "Benjamin Matuszewski",
@@ -43,7 +43,7 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "doc": "rm -Rf docs && jsdoc -c .jsdoc.json --verbose && cp -R misc/assets docs/",
+    "doc": "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",

package/src/client/Context.js

@@ -9,6 +9,9 @@ import {
   CONTEXT_EXIT_ERROR,
 } from '../common/constants.js';
 
+// share between all context, as channels are common to all contexts
+const promiseStore = new PromiseStore('Context');
+
 /**
  * Base class to extend in order to implement a new Context.
  *
@@ -77,15 +80,12 @@ 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;
       }
 
-      this._promiseStore.resolve(reqId);
+      promiseStore.resolve(reqId);
     });
 
     this.client.socket.addListener(CONTEXT_ENTER_ERROR, (reqId, contextName, msg) => {
@@ -93,7 +93,7 @@ class Context {
         return;
       }
 
-      this._promiseStore.reject(reqId, msg);
+      promiseStore.reject(reqId, msg);
     });
 
     this.client.socket.addListener(CONTEXT_EXIT_RESPONSE, (reqId, contextName) => {
@@ -101,7 +101,7 @@ class Context {
         return;
       }
 
-      this._promiseStore.resolve(reqId);
+      promiseStore.resolve(reqId);
     });
 
     this.client.socket.addListener(CONTEXT_EXIT_ERROR, (reqId, contextName, msg) => {
@@ -109,7 +109,7 @@ class Context {
         return;
       }
 
-      this._promiseStore.reject(reqId, msg);
+      promiseStore.reject(reqId, msg);
     });
 
     this.client.contextManager.register(this);
@@ -205,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 = this._promiseStore.add(resolve, reject, 'enter-context');
+        const reqId = promiseStore.add(resolve, reject, 'enter-context');
         this.client.socket.send(CONTEXT_ENTER_REQUEST, reqId, this.name);
       });
     } catch (err) {
@@ -239,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 = this._promiseStore.add(resolve, reject, 'exit-context');
+        const reqId = promiseStore.add(resolve, reject, 'exit-context');
         this.client.socket.send(CONTEXT_EXIT_REQUEST, reqId, this.name);
       });
     } catch (err) {

package/src/common/BaseSharedState.js

@@ -15,6 +15,14 @@ import {
   UPDATE_NOTIFICATION,
 } from './constants.js';
 
+// @todo - replace isOwner by `type`:
+// enum {
+//   'owner'
+//   'attached'
+//   'collection-controlller'
+//   'collection-attached'
+// }
+
 class BaseSharedState {
   constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
     /** @private */
@@ -312,6 +320,10 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
+    if (this._detached) {
+      return;
+    }
+
     if (!isPlainObject(updates)) {
       throw new ReferenceError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
     }
@@ -429,12 +441,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();

package/src/common/BaseSharedStateCollection.js

@@ -1,12 +1,16 @@
-/**
- * @private
- */
+import {
+  kCreateCollectionController,
+  kAttachInCollection,
+} from './BaseStateManager.js';
+
+/** @private */
 class BaseSharedStateCollection {
   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();
@@ -15,10 +19,17 @@ class BaseSharedStateCollection {
     this._unobserve = null;
   }
 
+  /** @private */
   async _init() {
-    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId) => {
-      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(() => {
@@ -55,17 +66,38 @@ class BaseSharedStateCollection {
   }
 
   /**
-   * Detach from the collection, i.e. detach all underlying shared states.
-   * @type {number}
+   * Name of the schema from which the collection has been created.
+   * @type {String}
+   * @readonly
    */
-  async detach() {
-    this._unobserve();
-    this._onUpdateCallbacks.clear();
+  get schemaName() {
+    return this._controller.schemaName;
+  }
 
-    const promises = this._states.map(state => state.detach());
-    await Promise.all(promises);
+  /**
+   * 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);
+  }
 
-    this._onDetachCallbacks.clear();
+  /**
+   * Get the default values as declared in the schema.
+   *
+   * @return {object}
+   * @example
+   * const defaults = state.getDefaults();
+   */
+  getDefaults() {
+    return this._controller.getDefaults();
   }
 
   /**
@@ -94,8 +126,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);
   }
 
   /**
@@ -156,6 +187,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`).
    *

package/src/common/BaseStateManager.js

@@ -17,6 +17,9 @@ import {
   DELETE_SCHEMA,
 } from './constants.js';
 
+export const kCreateCollectionController = Symbol('BaseStateManager::createCollectionController');
+export const kAttachInCollection = Symbol('BaseStateManager::attachInCollection');
+
 /**
  * @private
  */
@@ -176,12 +179,24 @@ class BaseStateManager {
    */
   async create(schemaName, initValues = {}) {
     return new Promise((resolve, reject) => {
-      const reqId = this._promiseStore.add(resolve, reject, 'create-create');
+      const reqId = this._promiseStore.add(resolve, reject, 'create-request');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(CREATE_REQUEST, reqId, schemaName, requireSchema, initValues);
     });
   }
 
+
+  /**
+   * @private
+   */
+  async [kCreateCollectionController](schemaName) {
+    return new Promise((resolve, reject) => {
+      const reqId = this._promiseStore.add(resolve, reject, 'create-collection-controller-request');
+      const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
+      this.client.transport.emit(CREATE_REQUEST, reqId, schemaName, requireSchema, {}, true);
+    });
+  }
+
   /**
    * Attach to an existing `SharedState` instance.
    *
@@ -198,13 +213,20 @@ class BaseStateManager {
    */
   async attach(schemaName, stateId = null) {
     return new Promise((resolve, reject) => {
-      // @todo - add a timeout
       const reqId = this._promiseStore.add(resolve, reject, 'attach-request');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema);
     });
   }
 
+  async [kAttachInCollection](schemaName, stateId) {
+    return new Promise((resolve, reject) => {
+      const reqId = this._promiseStore.add(resolve, reject, 'attach-in-collection-request');
+      const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
+      this.client.transport.emit(ATTACH_REQUEST, reqId, schemaName, stateId, requireSchema, true);
+    });
+  }
+
   /**
    * Observe all the `SharedState` instances that are created on the network.
    * This can be usefull for clients with some controller role that might want to track
@@ -366,6 +388,7 @@ class BaseStateManager {
     try {
       await collection._init();
     } catch (err) {
+      console.log(err.message)
       throw new Error(`Cannot create collection, schema "${schemaName}" does not exists`);
     }
 

package/src/common/PromiseStore.js

@@ -1,32 +1,39 @@
 import { idGenerator } from '@ircam/sc-utils';
 
-const generateRequestId = idGenerator();
-
 export default class PromiseStore {
   constructor(name) {
     this.name = name;
     this.store = new Map();
+    this.generateRequestId = idGenerator();
   }
 
   add(resolve, reject, type) {
-    const reqId = generateRequestId.next().value;
+    const reqId = this.generateRequestId.next().value;
     this.store.set(reqId, { resolve, reject, type });
 
     return reqId;
   }
 
   resolve(reqId, data) {
-    const { resolve } = this.store.get(reqId);
-    this.store.delete(reqId);
+    if (this.store.has(reqId)) {
+      const { resolve } = this.store.get(reqId);
+      this.store.delete(reqId);
 
-    resolve(data);
+      resolve(data);
+    } else {
+      throw new Error(`[${this.name}] cannot resolve request id (${reqId}), id does not exist`);
+    }
   }
 
   reject(reqId, msg) {
-    const { reject } = this.store.get(reqId);
-    this.store.delete(reqId);
+    if (this.store.has(reqId)) {
+      const { reject } = this.store.get(reqId);
+      this.store.delete(reqId);
 
-    reject(new Error(msg));
+      reject(new Error(msg));
+    } else {
+      throw new Error(`[${this.name}] cannot reject request id (${reqId}), id does not exist`);
+    }
   }
 
   // reject all pendeing request

package/src/common/SharedStatePrivate.js

@@ -13,13 +13,14 @@ import {
 
 /**
  * The "real" state, this instance is kept private by the server.StateManager.
- * It cannot be accessed without a SharedState proxy
+ * It can only be accessed through a SharedState proxy.
  * @private
  */
 class SharedStatePrivate {
   constructor(id, schemaName, schema, manager, initValues = {}) {
     this.id = id;
     this.schemaName = schemaName;
+    this.isCollectionController = false;
 
     this._manager = manager;
     this._parameters = new ParameterBag(schema, initValues);
@@ -29,10 +30,16 @@ class SharedStatePrivate {
     this._creatorId = null;
   }
 
-  _attachClient(remoteId, client, isOwner = false) {
-    this._attachedClients.set(remoteId, client);
+  _attachClient(remoteId, client, isOwner = false, inCollection = false) {
+
+    // isOwner && inCollection  -> collection controller
+    // !isOwner && inCollection -> attached in collection
+
+    const clientInfos = { client, isOwner, inCollection };
+    this._attachedClients.set(remoteId, clientInfos);
 
     if (isOwner) {
+      this.isCollectionController = inCollection;
       this._creatorRemoteId = remoteId;
       this._creatorId = client.id;
     }
@@ -89,44 +96,97 @@ class SharedStatePrivate {
         }
 
         if (hasUpdates) {
-          // We need to handle cases where:
-          // - client state (client.id: 2) sends a request
-          // - server attached state (client.id: -1) spot a problem and overrides the value
-          // We want the remote client (id: 2) to receive in the right order:
-          // * 1. the value it requested,
-          // * 2. the value overriden by the server-side attached state (id: -1)
-          //
-          // such problem is now better solved with the the upateHook system, none
-          // nonetheway we don't want to introduce inconsistencies here
-          //
-          // Then we propagate server-side last, because as the server transport
-          // is synchronous it can break ordering if a subscription function makes
-          // itself an update in reaction to an update. Propagating to server last
-          // alllows to maintain network messages order consistent.
-
-          // @note - remoteId correspond to unique remote state id
-
-          // propagate RESPONSE to the client that originates the request if not the server
-          if (client.id !== -1) {
-            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
-          }
+          // Collection Controller logic
+          if (isOwner && inCollection) {
+            // notify the requester back
+            // no need to check for attached clients as it is not observable
+            client.transport.emit(
+              `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
+              reqId, filteredUpdates, context
+            );
+
+            // loop through all private states
+            for (let [stateId, state] of this._manager._sharedStatePrivateById) {
+              // pick all states with same schema name and not this
+              if (state !== this && this.schemaName === state.schemaName) {
+                // notify all attached clients except those who belong to a collection
+                // i.e. !isOwner && inCollection, they will be notified by their own
+                // collection controller
+                for (let [remoteId, clientInfos] of state._attachedClients) {
+                  const { client, isOwner, inCollection } = clientInfos;
+
+                  if (!clientInfos.isOwner && clientInfos.inCollection) {
+                    continue;
+                  } else {
+                    const peer = clientInfos.client;
+
+                    peer.transport.emit(
+                      `${UPDATE_NOTIFICATION}-${state.id}-${remoteId}`,
+                      filteredUpdates, context
+                    );
+                  }
+                }
+              }
+            }
+          } else {
 
-          // propagate NOTIFICATION to all other attached clients except server
-          for (let [peerRemoteId, peer] of this._attachedClients) {
-            if (remoteId !== peerRemoteId && peer.id !== -1) {
-              peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
+            // Normal case
+
+            // We need to handle cases where:
+            // - client state (client.id: 2) sends a request
+            // - server attached state (client.id: -1) spot a problem and overrides the value
+            // We want the remote client (id: 2) to receive in the right order:
+            // * 1. the value it requested,
+            // * 2. the value overriden by the server-side attached state (id: -1)
+            //
+            // such problem is now better solved with the the upateHook system, none
+            // nonetheway we don't want to introduce inconsistencies here
+            //
+            // Then we propagate server-side last, because as the server transport
+            // is synchronous it can break ordering if a subscription function makes
+            // itself an update in reaction to an update. Propagating to server last
+            // alllows to maintain network messages order consistent.
+
+            // @note - remoteId correspond to unique remote state id
+
+            // propagate RESPONSE to the client that originates the request if not the server
+            if (client.id !== -1) {
+              client.transport.emit(
+                `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
+                reqId, filteredUpdates, context
+              );
             }
-          }
 
-          // propagate RESPONSE to server if it is the requester
-          if (client.id === -1) {
-            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
-          }
+            // propagate NOTIFICATION to all other attached clients except server
+            for (let [peerRemoteId, clientInfos] of this._attachedClients) {
+              const peer = clientInfos.client;
+
+              if (remoteId !== peerRemoteId && peer.id !== -1) {
+                peer.transport.emit(
+                  `${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`,
+                  filteredUpdates, context
+                );
+              }
+            }
+
+            // propagate RESPONSE to server if it is the requester
+            if (client.id === -1) {
+              client.transport.emit(
+                `${UPDATE_RESPONSE}-${this.id}-${remoteId}`,
+                reqId, filteredUpdates, context
+              );
+            }
+
+            // propagate NOTIFICATION other attached state that belongs to server
+            for (let [peerRemoteId, clientInfos] of this._attachedClients) {
+              const peer = clientInfos.client;
 
-          // propagate NOTIFICATION other attached state that belongs to server
-          for (let [peerRemoteId, peer] of this._attachedClients) {
-            if (remoteId !== peerRemoteId && peer.id === -1) {
-              peer.transport.emit(`${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`, filteredUpdates, context);
+              if (remoteId !== peerRemoteId && peer.id === -1) {
+                peer.transport.emit(
+                  `${UPDATE_NOTIFICATION}-${this.id}-${peerRemoteId}`,
+                  filteredUpdates, context
+                );
+              }
             }
           }
         } else {
@@ -149,14 +209,15 @@ class SharedStatePrivate {
     if (isOwner) {
       // delete only if creator
       client.transport.addListener(`${DELETE_REQUEST}-${this.id}-${remoteId}`, (reqId) => {
-        this._manager._serverStatesById.delete(this.id);
+        this._manager._sharedStatePrivateById.delete(this.id);
         // --------------------------------------------------------------------
         // WARNING - MAKE SURE WE DON'T HAVE PROBLEM W/ THAT
         // --------------------------------------------------------------------
         // @todo - propagate server-side last, because if a subscription function sends a
         // message to a client, network messages order are kept coherent
         // this._subscriptions.forEach(func => func(updated));
-        for (let [remoteId, attached] of this._attachedClients.entries()) {
+        for (let [remoteId, clientInfos] of this._attachedClients) {
+          const attached = clientInfos.client;
           this._detachClient(remoteId, attached);
 
           if (remoteId === this._creatorRemoteId) {

package/src/server/Sockets.js

@@ -1,14 +1,17 @@
 import { Worker } from 'node:worker_threads';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+// import { fileURLToPath } from 'node:url';
 
 import querystring from 'querystring';
 import { WebSocketServer } from 'ws';
 import WebSocket from 'ws';
 
 import Socket from './Socket.js';
+import networkLatencyWorker from './audit-network-latency.worker.js';
 
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
+// this crashes when bundling server to cjs module for Max, fallback to
+// string worker for now
+// const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
 /**
  * Manager all {@link server.Socket} instances.
@@ -45,8 +48,9 @@ class Sockets {
    */
   async start(server, config, onConnectionCallback) {
     // init audit stuff for network latency estimation
-    const workerPathname = path.join(__dirname, 'audit-network-latency.worker.js');
-    this._latencyStatsWorker = new Worker(workerPathname);
+    // @see note about __dirname
+    // const workerPathname = path.join(__dirname, 'audit-network-latency.worker.js');
+    this._latencyStatsWorker = new Worker(networkLatencyWorker, { eval: true });
     this._auditState = await server.getAuditState();
 
     this._auditState.onUpdate(updates => {

package/src/server/StateManager.js

@@ -28,6 +28,8 @@ import {
 const generateStateId = idGenerator();
 const generateRemoteId = idGenerator();
 
+const kIsObservableState = Symbol('StateManager::isObservableState');
+
 /**
  * @typedef {object} server.StateManager~schema
  *
@@ -315,7 +317,7 @@ class StateManager extends BaseStateManager {
     super(localClientId, localTransport);
 
     this._clientByNodeId = new Map();
-    this._serverStatesById = new Map();
+    this._sharedStatePrivateById = new Map();
     this._schemas = new Map();
     this._observers = new Set();
     this._hooksBySchemaName = new Map(); // protected
@@ -323,6 +325,12 @@ class StateManager extends BaseStateManager {
     this.addClient(localClientId, localTransport);
   }
 
+  [kIsObservableState](state) {
+    const { schemaName, isCollectionController } = state;
+    // is observable only if not in private state and not a controller state
+    return !PRIVATE_STATES.includes(schemaName) && !isCollectionController;
+  }
+
   /**
    * Add a client to the manager.
    *
@@ -342,90 +350,107 @@ class StateManager extends BaseStateManager {
     // ---------------------------------------------
     // CREATE
     // ---------------------------------------------
-    client.transport.addListener(CREATE_REQUEST, (reqId, schemaName, requireSchema, initValues = {}) => {
-      if (this._schemas.has(schemaName)) {
-        try {
-          const schema = this._schemas.get(schemaName);
-          const stateId = generateStateId.next().value;
-          const remoteId = generateRemoteId.next().value;
-          // id, schemaName, schema, manager, initValues = {}
-          const state = new SharedStatePrivate(stateId, schemaName, schema, this, initValues);
-
-          state._attachClient(remoteId, client, true); // attach client to the state
-          this._serverStatesById.set(stateId, state);
-
-          const currentValues = state._parameters.getValues();
-          const sendedSchema = requireSchema ? schema : null;
-
-          client.transport.emit(CREATE_RESPONSE, reqId, stateId, remoteId, schemaName, sendedSchema, currentValues);
-
-          this._observers.forEach(observer => {
-            // prevent propagating infos about internal states
-            if (!PRIVATE_STATES.includes(schemaName)) {
-              observer.transport.emit(OBSERVE_NOTIFICATION, schemaName, stateId, nodeId);
+    client.transport.addListener(
+      CREATE_REQUEST,
+      (reqId, schemaName, requireSchema, initValues = {}, inCollection = false) => {
+        if (this._schemas.has(schemaName)) {
+          try {
+            const schema = this._schemas.get(schemaName);
+            const stateId = generateStateId.next().value;
+            const remoteId = generateRemoteId.next().value;
+            const state = new SharedStatePrivate(stateId, schemaName, schema, this, initValues);
+
+             // attach client to the state as owner
+            const isOwner = true;
+            state._attachClient(remoteId, client, isOwner, inCollection);
+
+            this._sharedStatePrivateById.set(stateId, state);
+
+            const currentValues = state._parameters.getValues();
+            const schemaOption = requireSchema ? schema : null;
+
+            client.transport.emit(
+              CREATE_RESPONSE,
+              reqId, stateId, remoteId, schemaName, schemaOption, currentValues
+            );
+
+            const isObservable = this[kIsObservableState](state);
+
+            if (isObservable) {
+              this._observers.forEach(observer => {
+                observer.transport.emit(OBSERVE_NOTIFICATION, schemaName, stateId, nodeId);
+              });
             }
-          });
-        } catch (err) {
-          const msg = `Cannot create state "${schemaName}", ${err.message}`;
+          } catch (err) {
+            const msg = `Cannot create state "${schemaName}", ${err.message}`;
+            console.error(msg);
+
+            client.transport.emit(CREATE_ERROR, reqId, msg);
+          }
+        } else {
+          const msg = `Cannot create state "${schemaName}", schema does not exists`;
           console.error(msg);
 
           client.transport.emit(CREATE_ERROR, reqId, msg);
         }
-      } else {
-        const msg = `Cannot create state "${schemaName}", schema does not exists`;
-        console.error(msg);
-
-        client.transport.emit(CREATE_ERROR, reqId, msg);
       }
-    });
+    );
 
     // ---------------------------------------------
     // ATTACH (when creator, is attached by default)
     // ---------------------------------------------
-    client.transport.addListener(ATTACH_REQUEST, (reqId, schemaName, stateId = null, requireSchema = true) => {
-      if (this._schemas.has(schemaName)) {
-        let state = null;
-
-        if (stateId !== null && this._serverStatesById.has(stateId)) {
-          state = this._serverStatesById.get(stateId);
-        } else if (stateId === null) {
-          // if no `stateId` given, we try to find the first state with the given
-          // `schemaName` in the list, this allow a client to attach to a global
-          // state created by the server (or some persistant client) without
-          // having to know the `stateId` (e.g. some global state...)
-          for (let existingState of this._serverStatesById.values()) {
-            if (existingState.schemaName === schemaName) {
-              state = existingState;
-              break;
+    client.transport.addListener(
+      ATTACH_REQUEST,
+      (reqId, schemaName, stateId = null, requireSchema = true, inCollection = false) => {
+        if (this._schemas.has(schemaName)) {
+          let state = null;
+
+          if (stateId !== null && this._sharedStatePrivateById.has(stateId)) {
+            state = this._sharedStatePrivateById.get(stateId);
+          } else if (stateId === null) {
+            // if no `stateId` given, we try to find the first state with the given
+            // `schemaName` in the list, this allow a client to attach to a global
+            // state created by the server (or some persistant client) without
+            // having to know the `stateId` (e.g. some global state...)
+            for (let existingState of this._sharedStatePrivateById.values()) {
+              if (existingState.schemaName === schemaName) {
+                state = existingState;
+                break;
+              }
             }
           }
-        }
 
-        if (state !== null) {
-          // @note - we use a unique remote id to allow a client to attach
-          // several times to the same state.
-          // i.e. same state -> several remote attach on the same node
-          const remoteId = generateRemoteId.next().value;
-          const schema = this._schemas.get(schemaName);
-          const currentValues = state._parameters.getValues();
-
-          state._attachClient(remoteId, client, false);
-          // send schema for client-side instanciation
-          const sendedSchema = requireSchema ? schema : null;
-          client.transport.emit(ATTACH_RESPONSE, reqId, state.id, remoteId, schemaName, sendedSchema, currentValues);
+          if (state !== null) {
+            // @note - we use a unique remote id to allow a client to attach
+            // several times to the same state.
+            // i.e. same state -> several remote attach on the same node
+            const remoteId = generateRemoteId.next().value;
+            const isOwner = false;
+            state._attachClient(remoteId, client, isOwner, inCollection);
+
+            const currentValues = state._parameters.getValues();
+            const schema = this._schemas.get(schemaName);
+            const schemaOption = requireSchema ? schema : null;
+
+            client.transport.emit(
+              ATTACH_RESPONSE,
+              reqId, state.id, remoteId, schemaName, schemaOption, currentValues
+            );
+
+          } else {
+            const msg = `Cannot attach, no existing state for schema "${schemaName}" with stateId: "${stateId}"`;
+            console.error(msg);
+
+            client.transport.emit(ATTACH_ERROR, reqId, msg);
+          }
         } else {
-          const msg = `Cannot attach, no existing state for schema "${schemaName}" with stateId: "${stateId}"`;
+          const msg = `Cannot attach, schema "${schemaName}" does not exists`;
           console.error(msg);
 
           client.transport.emit(ATTACH_ERROR, reqId, msg);
         }
-      } else {
-        const msg = `Cannot attach, schema "${schemaName}" does not exists`;
-        console.error(msg);
-
-        client.transport.emit(ATTACH_ERROR, reqId, msg);
       }
-    });
+    );
 
     // ---------------------------------------------
     // OBSERVE PEERS (be notified when a state is created, lazy)
@@ -434,11 +459,11 @@ class StateManager extends BaseStateManager {
       if (observedSchemaName === null || this._schemas.has(observedSchemaName)) {
         const statesInfos = [];
 
-        this._serverStatesById.forEach(state => {
-          const { schemaName, id, _creatorId } = state;
+        this._sharedStatePrivateById.forEach(state => {
+          const isObservable = this[kIsObservableState](state);
 
-          // prevent propagating infos about internal states
-          if (!PRIVATE_STATES.includes(schemaName)) {
+          if (isObservable) {
+            const { schemaName, id, _creatorId } = state;
             statesInfos.push([schemaName, id, _creatorId]);
           }
         });
@@ -470,18 +495,22 @@ class StateManager extends BaseStateManager {
    * @private
    */
   removeClient(nodeId) {
-    for (let [_id, state] of this._serverStatesById.entries()) {
+    for (let [_id, state] of this._sharedStatePrivateById.entries()) {
       let deleteState = false;
 
       // define if the client is the creator of the state, in which case
       // everybody must delete it
-      for (let [remoteId, attachedClient] of state._attachedClients.entries()) {
+      for (let [remoteId, clientInfos] of state._attachedClients) {
+        const attachedClient = clientInfos.client;
+
         if (nodeId === attachedClient.id && remoteId === state._creatorRemoteId) {
           deleteState = true;
         }
       }
 
-      for (let [remoteId, attachedClient] of state._attachedClients.entries()) {
+      for (let [remoteId, clientInfos] of state._attachedClients) {
+        const attachedClient = clientInfos.client;
+
         if (nodeId === attachedClient.id) {
           state._detachClient(remoteId, attachedClient);
         }
@@ -492,7 +521,7 @@ class StateManager extends BaseStateManager {
             attachedClient.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
           }
 
-          this._serverStatesById.delete(state.id);
+          this._sharedStatePrivateById.delete(state.id);
         }
       }
     }
@@ -559,14 +588,15 @@ class StateManager extends BaseStateManager {
    */
   deleteSchema(schemaName) {
     // @note: deleting schema
-    for (let [_id, state] of this._serverStatesById.entries()) {
+    for (let [_id, state] of this._sharedStatePrivateById) {
       if (state.schemaName === schemaName) {
-        for (let [remoteId, attached] of state._attachedClients.entries()) {
+        for (let [remoteId, clientInfos] of state._attachedClients) {
+          const attached = clientInfos.client;
           state._detachClient(remoteId, attached);
           attached.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
         }
 
-        this._serverStatesById.delete(state.id);
+        this._sharedStatePrivateById.delete(state.id);
       }
     }
 

package/src/server/audit-network-latency.worker.js

@@ -1,6 +1,8 @@
-import { parentPort } from 'node:worker_threads';
-
-import { getTime } from '@ircam/sc-utils';
+// NOTICE: we use this syntax so that the server can be bundled to cjs
+// with esbuild, so we can ship a cjs server bundle into Max.
+// Should move back to regular esm module once Max has fixed its loader
+export default `
+const { parentPort } = require('node:worker_threads');
 
 let stack = [];
 let averageLatencyWindow = 5;
@@ -9,12 +11,21 @@ let averageLatencyPeriod = 2;
 let intervalId = null;
 let meanLatency = 0;
 
-parentPort.on('message', msg => {
+let getTime;
+let inited = new Promise(async (resolve) => {
+  module = await import('@ircam/sc-utils');
+  getTime = module.getTime;
+  resolve(true);
+});
+
+parentPort.on('message', async msg => {
   switch (msg.type) {
     case 'config': {
       averageLatencyWindow = msg.value.averageLatencyWindow;
       averageLatencyPeriod = msg.value.averageLatencyPeriod;
 
+      await inited;
+
       // launch compute in its own loop so that the number of computation is
       // decoupled from the number of connected clients
       clearInterval(intervalId);
@@ -55,3 +66,4 @@ function computeAverageLatency() {
     });
   }
 }
+`;