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

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 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.15",
   "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.json --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,6 @@ import {
   UPDATE_ABORT,
   UPDATE_NOTIFICATION,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
 
 class BaseSharedState {
   constructor(id, remoteId, schemaName, schema, client, isOwner, manager, initValues = {}) {
@@ -33,8 +29,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 +57,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 +102,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 +113,9 @@ ${JSON.stringify(initValues, null, 2)}`);
         }
       }
 
-      this._clearDetach();
+      this._onDetachCallbacks.clear();
+      this._onDeleteCallbacks.clear();
+      this._promiseStore.flush();
     });
 
 
@@ -132,12 +135,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 +157,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 +210,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 +328,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 +361,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);
     });
   }
@@ -477,16 +480,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

@@ -2,10 +2,13 @@
  * @private
  */
 class BaseSharedStateCollection {
-  constructor(stateManager, schemaName) {
+  constructor(stateManager, schemaName, options = {}) {
     this._stateManager = stateManager;
     this._schemaName = schemaName;
+    this._options = Object.assign({ excludeLocal: false }, options);
+
     this._states = [];
+
     this._onUpdateCallbacks = new Set();
     this._onAttachCallbacks = new Set();
     this._onDetachCallbacks = new Set();
@@ -13,7 +16,7 @@ class BaseSharedStateCollection {
   }
 
   async _init() {
-    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId, nodeId) => {
+    this._unobserve = await this._stateManager.observe(this._schemaName, async (schemaName, stateId) => {
       const state = await this._stateManager.attach(schemaName, stateId);
 
       this._states.push(state);
@@ -32,28 +35,36 @@ class BaseSharedStateCollection {
       });
 
       this._onAttachCallbacks.forEach(callback => callback(state));
-    });
+    }, this._options);
   }
 
   /**
-   * Size of the collection
+   * Size of the collection, alias `size`
    * @type {number}
    */
   get length() {
     return this._states.length;
   }
 
+  /**
+   * Size of the collection, , alias `length`
+   * @type {number}
+   */
+  get size() {
+    return this._states.length;
+  }
+
   /**
    * Detach from the collection, i.e. detach all underlying shared states.
    * @type {number}
    */
   async detach() {
     this._unobserve();
+    this._onUpdateCallbacks.clear();
 
-    const promises = Array.from(this._states).map(state => state.detach());
+    const promises = this._states.map(state => state.detach());
     await Promise.all(promises);
 
-    this._onUpdateCallbacks.clear();
     this._onDetachCallbacks.clear();
   }
 
@@ -212,8 +223,8 @@ class BaseSharedStateCollection {
         } else {
           return { value: this._states[index++], done: false };
         }
-      }
-    }
+      },
+    };
   }
 }
 

package/src/common/BaseStateManager.js

@@ -1,6 +1,7 @@
-import { isString, isFunction } from '@ircam/sc-utils';
+import { isString, isFunction, isPlainObject } from '@ircam/sc-utils';
 import SharedState from './BaseSharedState.js';
 import SharedStateCollection from './BaseSharedStateCollection.js';
+import PromiseStore from './PromiseStore.js';
 import {
   CREATE_REQUEST,
   CREATE_RESPONSE,
@@ -10,15 +11,11 @@ import {
   ATTACH_ERROR,
   OBSERVE_REQUEST,
   OBSERVE_RESPONSE,
+  OBSERVE_ERROR,
   OBSERVE_NOTIFICATION,
   UNOBSERVE_NOTIFICATION,
   DELETE_SCHEMA,
 } from './constants.js';
-import {
-  storeRequestPromise,
-  resolveRequest,
-  rejectRequest,
-} from './promise-store.js';
 
 /**
  * @private
@@ -32,10 +29,13 @@ class BaseStateManager {
   constructor(id, transport) {
     this.client = { id, transport };
 
-    this._statesById = new Map();
-    this._observeListeners = new Map(); // Map <callback, filterSchemaName>
-    this._cachedSchemas = new Map();
-    this._observeRequestCallbacks = new Map();
+    this._statesById = new Map(); // <id, state>
+    this._cachedSchemas = new Map(); // <shemaName, definition>
+
+    this._observeListeners = new Set(); // Set <[observedSchemaName, callback, options]>
+    this._observeRequestCallbacks = new Map(); // Map <reqId, [observedSchemaName, callback, options]>
+
+    this._promiseStore = new PromiseStore();
 
     // ---------------------------------------------
     // CREATE
@@ -53,11 +53,11 @@ class BaseStateManager {
       const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, true, this, initValues);
       this._statesById.set(state.id, state);
 
-      resolveRequest(reqId, state);
+      this._promiseStore.resolve(reqId, state);
     });
 
     this.client.transport.addListener(CREATE_ERROR, (reqId, msg) => {
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     // ---------------------------------------------
@@ -77,11 +77,11 @@ class BaseStateManager {
       const state = new SharedState(stateId, remoteId, schemaName, schema, this.client, false, this, currentValues);
       this._statesById.set(state.id, state);
 
-      resolveRequest(reqId, state);
+      this._promiseStore.resolve(reqId, state);
     });
 
     this.client.transport.addListener(ATTACH_ERROR, (reqId, msg) => {
-      rejectRequest(reqId, msg);
+      this._promiseStore.reject(reqId, msg);
     });
 
     // ---------------------------------------------
@@ -90,11 +90,18 @@ class BaseStateManager {
     this.client.transport.addListener(OBSERVE_RESPONSE, async (reqId, ...list) => {
       // retrieve the callback that have been stored in observe to make sure
       // we don't call another callback that may have been registered earlier.
-      const [callback, filterSchemaName] = this._observeRequestCallbacks.get(reqId);
+      const observeInfos = this._observeRequestCallbacks.get(reqId);
+      const [observedSchemaName, callback, options] = observeInfos;
+
+      // move observeInfos from `_observeRequestCallbacks` to `_observeListeners`
+      // to guarantee order of execution, @see not in `.observe`
       this._observeRequestCallbacks.delete(reqId);
+      this._observeListeners.add(observeInfos);
 
       const promises = list.map(([schemaName, stateId, nodeId]) => {
-        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+        const filter = this._filterObserve(observedSchemaName, schemaName, nodeId, options);
+
+        if (!filter) {
           return callback(schemaName, stateId, nodeId);
         } else {
           return Promise.resolve();
@@ -104,19 +111,29 @@ class BaseStateManager {
       await Promise.all(promises);
 
       const unsubscribe = () => {
-        this._observeListeners.delete(callback);
-        // no more listeners, we can stop receiving notification from the server
+        this._observeListeners.delete(observeInfos);
+
+        // no more listeners, we can stop receiving notifications from the server
         if (this._observeListeners.size === 0) {
           this.client.transport.emit(UNOBSERVE_NOTIFICATION);
         }
       };
 
-      resolveRequest(reqId, unsubscribe);
+      this._promiseStore.resolve(reqId, unsubscribe);
+    });
+
+    // Observe error can occur if observed schema name does not exists
+    this.client.transport.addListener(OBSERVE_ERROR, (reqId, msg) => {
+      this._observeRequestCallbacks.delete(reqId);
+      this._promiseStore.reject(reqId, msg);
     });
 
     this.client.transport.addListener(OBSERVE_NOTIFICATION, (schemaName, stateId, nodeId) => {
-      this._observeListeners.forEach((filterSchemaName, callback) => {
-        if (filterSchemaName === '*' || filterSchemaName === schemaName) {
+      this._observeListeners.forEach(observeInfos => {
+        const [observedSchemaName, callback, options] = observeInfos;
+        const filter = this._filterObserve(observedSchemaName, schemaName, nodeId, options);
+
+        if (!filter) {
           callback(schemaName, stateId, nodeId);
         }
       });
@@ -130,6 +147,21 @@ class BaseStateManager {
     });
   }
 
+  /** @private */
+  _filterObserve(observedSchemaName, schemaName, creatorId, options) {
+    let filter = true;
+    // schema name filter filer
+    if (observedSchemaName === null || observedSchemaName === schemaName) {
+      filter = false;
+    }
+    // filter state created by client if excludeLocal is true
+    if (options.excludeLocal === true && creatorId === this.client.id) {
+      filter = true;
+    }
+
+    return filter;
+  }
+
   /**
    * Create a `SharedState` instance from a registered schema.
    *
@@ -144,7 +176,7 @@ class BaseStateManager {
    */
   async create(schemaName, initValues = {}) {
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'create-create');
       const requireSchema = this._cachedSchemas.has(schemaName) ? false : true;
       this.client.transport.emit(CREATE_REQUEST, reqId, schemaName, requireSchema, initValues);
     });
@@ -167,7 +199,7 @@ class BaseStateManager {
   async attach(schemaName, stateId = null) {
     return new Promise((resolve, reject) => {
       // @todo - add a timeout
-      const reqId = storeRequestPromise(resolve, reject);
+      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);
     });
@@ -180,20 +212,31 @@ class BaseStateManager {
    * control over them from a single point.
    *
    * 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.
+   * - The order of execution is not guaranted between nodes, i.e. an state attached
+   * in the `observe` callback could be created before the `async create` method resolves.
+   * - Filtering, i.e. `observedSchemaName` and `options.excludeLocal` are handled
+   * on the node side, the server just notify all state creation activity and
+   * the node executes the given callbacks according to the different filter rules.
+   * Such strategy allows to share the observe notifications between all observers.
    *
-   * @param {String} [schemaName] - optionnal schema name to filter the observed
+   * Alternative signatures:
+   * - .observe(callback)
+   * - .observe(schemaName, callback)
+   * - .observe(callback, options)
+   * - .observe(schemaName, callback, options)
+   *
+   * @param {string} [schemaName] - optionnal schema name to filter the observed
    *  states.
    * @param {server.StateManager~ObserveCallback|client.StateManager~ObserveCallback}
    *  callback - Function to be called when a new state is created on the network.
+   * @param {object} options - Options.
+   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
+   *  created locallly, i.e. by the same node, from the collection.
    * @returns {Promise<Function>} - Returns a Promise that resolves when the given
    *  callback as been executed on each existing states. The promise value is a
    *  function which allows to stop observing the states on the network.
    * @example
-   * client.stateManager.observe(async (schemaName, stateId, nodeId) => {
+   * client.stateManager.observe(async (schemaName, stateId) => {
    *   if (schemaName === 'something') {
    *     const state = await this.client.stateManager.attach(schemaName, stateId);
    *     console.log(state.getValues());
@@ -204,50 +247,127 @@ class BaseStateManager {
   // handle this way and the network overhead is very low for observe notifications:
   // i.e. schemaName, stateId, nodeId
   async observe(...args) {
-    let filterSchemaName;
+
+    const defaultOptions = {
+      excludeLocal: false,
+    };
+
+    let observedSchemaName;
     let callback;
+    let options;
 
-    if (args.length === 1) {
-      filterSchemaName = '*';
-      callback = args[0];
+    switch (args.length) {
+      case 1: {
+        // variation: .observe(callback)
+        if (!isFunction(args[0])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 1 should be a function"`);
+        }
 
-      if (!isFunction(callback)) {
-        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+        observedSchemaName = null;
+        callback = args[0];
+        options = defaultOptions;
+        break;
       }
-    } else if (args.length === 2) {
-      filterSchemaName = args[0];
-      callback = args[1];
+      case 2: {
+        // variation: .observe(schemaName, callback)
+        if (isString(args[0])) {
+          if (!isFunction(args[1])) {
+            throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be a function"`);
+          }
+
+          observedSchemaName = args[0];
+          callback = args[1];
+          options = defaultOptions;
+
+        // variation: .observe(callback, options) API
+        } else if (isFunction(args[0])) {
+          if (!isPlainObject(args[1])) {
+            throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be an object"`);
+          }
+
+          observedSchemaName = null;
+          callback = args[0];
+          options = Object.assign(defaultOptions, args[1]);
+
+        } else {
+          throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
+        }
 
-      if (!isString(filterSchemaName) || !isFunction(callback)) {
-        throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
+        break;
+      }
+      case 3: {
+        // variation: .observe(schemaName, callback, options)
+        if (!isString(args[0])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 1 should be a string"`);
+        }
+
+        if (!isFunction(args[1])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be a function"`);
+        }
+
+        if (!isPlainObject(args[2])) {
+          throw new TypeError(`[stateManager] Invalid arguments, argument 2 should be an object"`);
+        }
+
+        observedSchemaName = args[0];
+        callback = args[1];
+        options = Object.assign(defaultOptions, args[2]);
+
+        break;
+      }
+      // throw in all other cases
+      default: {
+        throw new Error(`[stateManager] Invalid signature, refer to the StateManager.observe documentation"`);
       }
-    } else {
-      throw new Error(`[stateManager] Invalid arguments, valid signatures are "stateManager.observe(callback)" or "stateManager.observe(schemaName, callback)"`);
     }
 
     // resend request to get updated list of states
     return new Promise((resolve, reject) => {
-      const reqId = storeRequestPromise(resolve, reject);
+      const reqId = this._promiseStore.add(resolve, reject, 'observe-request');
       // store the callback for execution on the response. the returned Promise
       // is fullfiled once callback has been executed with each existing states
-      this._observeRequestCallbacks.set(reqId, [callback, filterSchemaName]);
-      // store the callback for execution on subsequent notifications
-      this._observeListeners.set(callback, filterSchemaName);
-
-      this.client.transport.emit(OBSERVE_REQUEST, reqId);
+      const observeInfos = [observedSchemaName, callback, options];
+      this._observeRequestCallbacks.set(reqId, observeInfos);
+
+      // NOTE: do not store in `_observeListeners` yet as it can produce race
+      // conditions, e.g.:
+      // ```
+      // await client.stateManager.observe(async (schemaName, stateId, nodeId) => {});
+      // // client now receives OBSERVE_NOTIFICATIONS
+      // await otherClient.stateManager.create('a');
+      // // second observer added in between
+      // client.stateManager.observe(async (schemaName, stateId, nodeId) => {});
+      // ````
+      // OBSERVE_NOTIFICATION is received before the OBSERVE_RESPONSE, then the
+      // second observer is called twice:
+      // - OBSERVE_RESPONSE 1 []
+      // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ]
+      // - OBSERVE_NOTIFICATION [ 'a', 1, 0 ] // this should not happen
+      // - OBSERVE_RESPONSE 1 [ [ 'a', 1, 0 ] ]
+      //
+      // cf. unit test `observe should properly behave in race condition`
+
+      this.client.transport.emit(OBSERVE_REQUEST, reqId, observedSchemaName);
     });
   }
 
   /**
-   * Returns a collection of all the states created from the schema name. Except
-   * the ones created by the current node.
+   * Returns a collection of all the states created from the schema name.
    *
    * @param {string} schemaName - Name of the schema.
+   * @param {object} options - Options.
+   * @param {boolean} [options.excludeLocal = false] - If set to true, exclude states
+   *  created locallly, i.e. by the same node, from the collection.
    * @returns {server.SharedStateCollection|client.SharedStateCollection}
    */
-  async getCollection(schemaName) {
-    const collection = new SharedStateCollection(this, schemaName);
-    await collection._init();
+  async getCollection(schemaName, options) {
+    const collection = new SharedStateCollection(this, schemaName, options);
+
+    try {
+      await collection._init();
+    } catch (err) {
+      throw new Error(`Cannot create collection, schema "${schemaName}" does not exists`);
+    }
 
     return collection;
   }

package/src/common/ParameterBag.js

@@ -1,4 +1,4 @@
-import cloneDeep from 'lodash.clonedeep';
+import cloneDeep from 'lodash/cloneDeep.js';
 import equal from 'fast-deep-equal';
 
 export const sharedOptions = {
@@ -394,30 +394,34 @@ class ParameterBag {
   getSchema(name = null) {
     if (name === null) {
       return this._schema;
-    } else {
-      if (!this.has(name)) {
-        throw new ReferenceError(`[SharedState] Cannot get schema description of undefined parameter "${name}"`);
-      }
+    }
 
-      return this._schema[name];
+    if (!this.has(name)) {
+      throw new ReferenceError(`[SharedState] Cannot get schema description of undefined parameter "${name}"`);
     }
+
+    return this._schema[name];
   }
 
   // return the default value, if initValue has been given, return init values
   getInitValues() {
     const initValues = {};
+
     for (let [name, def] of Object.entries(this._schema)) {
       initValues[name] = def.initValue;
     }
+
     return initValues;
   }
 
   // return the default value, if initValue has been given, return init values
   getDefaults() {
     const defaults = {};
+
     for (let [name, def] of Object.entries(this._schema)) {
-      defaults[name] = def.defaults;
+      defaults[name] = def.default;
     }
+
     return defaults;
   }
 }

package/src/common/PromiseStore.js

@@ -0,0 +1,41 @@
+import { idGenerator } from '@ircam/sc-utils';
+
+const generateRequestId = idGenerator();
+
+export default class PromiseStore {
+  constructor(name) {
+    this.name = name;
+    this.store = new Map();
+  }
+
+  add(resolve, reject, type) {
+    const reqId = 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);
+
+    resolve(data);
+  }
+
+  reject(reqId, msg) {
+    const { reject } = this.store.get(reqId);
+    this.store.delete(reqId);
+
+    reject(new Error(msg));
+  }
+
+  // reject all pendeing request
+  flush() {
+    for (let [_reqId, entry] of this.store) {
+      const { reject, type } = entry;
+      reject(new Error(`[${this.name}] Discard promise "${type}", cannot resolve`));
+    }
+
+    this.store.clear();
+  }
+}

package/src/common/SharedStatePrivate.js

@@ -89,49 +89,46 @@ class SharedStatePrivate {
         }
 
         if (hasUpdates) {
-          // send response to requester
-          // client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates);
-
-          // @note: 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, therefore network messages
-          // order would be broken,
-
-          // 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:
+          // 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.
 
-          // this problem could be solved properly with a reducer system:
-          // if (dirty) {
-          //   -> call (async) reducer
-          //   -> get values from reducer
-          //.  -> dispatch to everybody
-          // }
+          // @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);
+          }
 
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to all other attached clients except server
+          // 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);
             }
           }
 
-          if (client.id !== -1) {
+          // propagate RESPONSE to server if it is the requester
+          if (client.id === -1) {
             client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
           }
 
-          for (let [peerRemoteId, peer] of this._attachedClients.entries()) {
-            // propagate notification to server
+          // 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 (client.id === -1) {
-            client.transport.emit(`${UPDATE_RESPONSE}-${this.id}-${remoteId}`, reqId, filteredUpdates, context);
-          }
         } else {
           // propagate back to the requester that the update has been aborted
           // ignore all other attached clients.

package/src/common/constants.js

@@ -21,6 +21,7 @@ export const DETACH_ERROR = 's:dt:err';
 
 export const OBSERVE_REQUEST = 's:o:req';
 export const OBSERVE_RESPONSE = 's:o:res';
+export const OBSERVE_ERROR = 's:o:err';
 export const OBSERVE_NOTIFICATION = 's:o:not';
 
 export const UNOBSERVE_NOTIFICATION = 's:uo:not';
@@ -47,5 +48,5 @@ export const CLIENT_HANDSHAKE_RESPONSE = 'cl:h:res';
 export const CLIENT_HANDSHAKE_ERROR = 'cl:h:err';
 
 // audit state schema name
-export const AUDIT_STATE_NAME = 's:c:audit';
+export const AUDIT_STATE_NAME = 'p:s:audit';
 export const PRIVATE_STATES = [AUDIT_STATE_NAME];

package/src/common/sockets-utils.js

@@ -1,8 +1,7 @@
 import 'fast-text-encoding';
-import root from 'window-or-global';
 
-const encoder = new root.TextEncoder('utf-8');
-const decoder = new root.TextDecoder('utf-8');
+const encoder = new TextEncoder('utf-8');
+const decoder = new TextDecoder('utf-8');
 
 const types = [
   'Int8Array',
@@ -57,7 +56,7 @@ export function unpackBinaryMessage(buffer /* arraybuffer */) {
   const channel = decoder.decode(channelBuffer);
   const type = types[typeIndex];
   // slice (copy) the underlying ArrayBuffer to create a clean TypedArray
-  const data = new root[type](buffer.slice(startOffset));
+  const data = new globalThis[type](buffer.slice(startOffset));
 
   return [channel, data];
 }

package/src/server/Server.js

@@ -5,14 +5,13 @@ import path from 'node:path';
 import os from 'node:os';
 import { X509Certificate, createPrivateKey } from 'node:crypto';
 
-import { getTime } from '@ircam/sc-gettime';
-import { isPlainObject, idGenerator } from '@ircam/sc-utils';
+import { isPlainObject, idGenerator, getTime } from '@ircam/sc-utils';
 import chalk from 'chalk';
 import compression from 'compression';
 import express from 'express';
 import Keyv from 'keyv';
 import { KeyvFile } from 'keyv-file';
-import merge from 'lodash.merge';
+import merge from 'lodash/merge.js';
 import pem from 'pem';
 import compile from 'template-literal';
 

package/src/server/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 server.StateManager#getCollection} for factory method API
  *
  * ```
  * const collection = await server.stateManager.getCollection('my-schema');

package/src/server/Socket.js

@@ -1,4 +1,4 @@
-import { getTime } from '@ircam/sc-gettime';
+import { getTime } from '@ircam/sc-utils';
 import {
   packBinaryMessage,
   unpackBinaryMessage,

package/src/server/StateManager.js

@@ -1,7 +1,7 @@
 import EventEmitter from 'node:events';
 
 import { idGenerator, isString, isPlainObject } from '@ircam/sc-utils';
-import clonedeep from 'lodash.clonedeep';
+import clonedeep from 'lodash/cloneDeep.js';
 
 import BaseStateManager from '../common/BaseStateManager.js';
 import ParameterBag from '../common/ParameterBag.js';
@@ -17,6 +17,7 @@ import {
   ATTACH_ERROR,
   OBSERVE_REQUEST,
   OBSERVE_RESPONSE,
+  OBSERVE_ERROR,
   OBSERVE_NOTIFICATION,
   UNOBSERVE_NOTIFICATION,
   DELETE_SCHEMA,
@@ -359,17 +360,21 @@ class StateManager extends BaseStateManager {
           client.transport.emit(CREATE_RESPONSE, reqId, stateId, remoteId, schemaName, sendedSchema, currentValues);
 
           this._observers.forEach(observer => {
-            if (observer.id !== nodeId) {
+            // prevent propagating infos about internal states
+            if (!PRIVATE_STATES.includes(schemaName)) {
               observer.transport.emit(OBSERVE_NOTIFICATION, schemaName, stateId, nodeId);
             }
           });
         } catch (err) {
-          client.transport.emit(CREATE_ERROR, reqId, err.message);
-          console.error(err.message);
+          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);
       }
     });
@@ -410,36 +415,43 @@ class StateManager extends BaseStateManager {
           client.transport.emit(ATTACH_RESPONSE, reqId, state.id, remoteId, schemaName, sendedSchema, currentValues);
         } else {
           const msg = `Cannot attach, no existing state for schema "${schemaName}" with stateId: "${stateId}"`;
-          client.transport.emit(ATTACH_ERROR, reqId, msg);
           console.error(msg);
+
+          client.transport.emit(ATTACH_ERROR, reqId, msg);
         }
       } else {
         const msg = `Cannot attach, schema "${schemaName}" does not exists`;
-        client.transport.emit(ATTACH_ERROR, reqId, msg);
         console.error(msg);
+
+        client.transport.emit(ATTACH_ERROR, reqId, msg);
       }
     });
 
     // ---------------------------------------------
     // OBSERVE PEERS (be notified when a state is created, lazy)
     // ---------------------------------------------
-    client.transport.addListener(OBSERVE_REQUEST, reqId => {
-      const statesInfos = [];
-
-      this._serverStatesById.forEach(state => {
-        const { schemaName, id, _creatorId } = state;
-        // only track application states
-        // (e.g. do not propagate infos about audit state)
-        if (!PRIVATE_STATES.includes(schemaName) && _creatorId !== client.id) {
-          statesInfos.push([schemaName, id, _creatorId]);
-        }
-      });
+    client.transport.addListener(OBSERVE_REQUEST, (reqId, observedSchemaName) => {
+      if (observedSchemaName === null || this._schemas.has(observedSchemaName)) {
+        const statesInfos = [];
 
-      // add client to observers first because if some (sync) server side
-      // callback throws, the client would never be added to the list
-      this._observers.add(client);
+        this._serverStatesById.forEach(state => {
+          const { schemaName, id, _creatorId } = state;
+
+          // prevent propagating infos about internal states
+          if (!PRIVATE_STATES.includes(schemaName)) {
+            statesInfos.push([schemaName, id, _creatorId]);
+          }
+        });
 
-      client.transport.emit(OBSERVE_RESPONSE, reqId, ...statesInfos);
+        // add client to observers first because if some synchronous server side
+        // callback throws, the client would never be added to the list
+        this._observers.add(client);
+
+        client.transport.emit(OBSERVE_RESPONSE, reqId, ...statesInfos);
+      } else {
+        const msg = `Cannot observe, schema "${observedSchemaName}" does not exists`;
+        client.transport.emit(OBSERVE_ERROR, reqId, msg);
+      }
     });
 
     client.transport.addListener(UNOBSERVE_NOTIFICATION, () => {
@@ -554,7 +566,7 @@ class StateManager extends BaseStateManager {
           attached.transport.emit(`${DELETE_NOTIFICATION}-${state.id}-${remoteId}`);
         }
 
-        this._serverStatesById.delete(this.id);
+        this._serverStatesById.delete(state.id);
       }
     }
 

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

@@ -1,6 +1,6 @@
 import { parentPort } from 'node:worker_threads';
 
-import { getTime } from '@ircam/sc-gettime';
+import { getTime } from '@ircam/sc-utils';
 
 let stack = [];
 let averageLatencyWindow = 5;

package/src/server/crypto.js

@@ -23,16 +23,15 @@ const encryptionIV = crypto
 
 export function encryptData(obj) {
   const data = JSON.stringify(obj);
-  const cipher = crypto.createCipheriv(encryptionMethod, key, encryptionIV)
-  return Buffer.from(
-    cipher.update(data, 'utf8', 'hex') + cipher.final('hex')
-  ).toString('base64')
+  const cipher = crypto.createCipheriv(encryptionMethod, key, encryptionIV);
+
+  return Buffer.from(cipher.update(data, 'utf8', 'hex') + cipher.final('hex')).toString('base64');
 }
 
 export function decryptData(encryptedData) {
-  const buff = Buffer.from(encryptedData, 'base64')
-  const decipher = crypto.createDecipheriv(encryptionMethod, key, encryptionIV)
+  const buff = Buffer.from(encryptedData, 'base64');
+  const decipher = crypto.createDecipheriv(encryptionMethod, key, encryptionIV);
 
-  const decrypted = `${decipher.update(buff.toString('utf8'), 'hex', 'utf8')}${decipher.final('utf8')}`
+  const decrypted = `${decipher.update(buff.toString('utf8'), 'hex', 'utf8')}${decipher.final('utf8')}`;
   return JSON.parse(decrypted);
 }

package/src/common/promise-store.js

@@ -1,25 +0,0 @@
-import { idGenerator } from '@ircam/sc-utils';
-
-const generateRequestId = idGenerator();
-const requestPromises = new Map();
-
-export function storeRequestPromise(resolve, reject) {
-  const reqId = generateRequestId.next().value;
-  requestPromises.set(reqId, { resolve, reject });
-
-  return reqId;
-}
-
-export function resolveRequest(reqId, data) {
-  const { resolve } = requestPromises.get(reqId);
-  requestPromises.delete(reqId);
-
-  resolve(data);
-}
-
-export function rejectRequest(reqId, data) {
-  const { reject } = requestPromises.get(reqId);
-  requestPromises.delete(reqId);
-
-  reject(data);
-}

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "include": ["src/**/*.js"],
-
-  "compilerOptions": {
-    // Tells TypeScript to read JS files, as
-    // normally they are ignored as source files
-    "allowJs": true,
-    // Generate d.ts files
-    "declaration": true,
-    // This compiler run should
-    // only output d.ts files
-    "emitDeclarationOnly": true,
-    // Types should go into this directory.
-    // Removing this would place the .d.ts files
-    // next to the .js files
-    "outDir": "types",
-    // go to js file when using IDE functions like
-    // "Go to Definition" in VSCode
-    "declarationMap": true
-  }
-}