@soundworks/core 4.0.0-alpha.28 → 4.0.0-alpha.29

package/src/common/{BaseSharedState.js → SharedState.js}

@@ -1,4 +1,5 @@
 import { isPlainObject } from '@ircam/sc-utils';
+
 import ParameterBag from './ParameterBag.js';
 import PromiseStore from './PromiseStore.js';
 import {
@@ -15,78 +16,147 @@ 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, filter) {
-    /** @private */
-    this._id = id;
-    /** @private */
-    this._remoteId = remoteId;
-    /** @private */
-    this._schemaName = schemaName;
-    /** @private */
-    this._isOwner = isOwner; // may be the server or any client
-    /** @private */
-    this._client = client;
-    /** @private */
-    this._manager = manager;
-    /** @private */
-    this._filter = filter;
-
-    /**
-     * true is the state has been detached or deleted
-     * @private
-     */
-    this._detached = false;
-    /* @private */
-    this._promiseStore = new PromiseStore(this.constructor.name);
+import {
+  kStateManagerDeleteState,
+} from './BaseStateManager.js';
+
+import logger from './logger.js';
+
+// for testing purposes
+export const kSharedStatePromiseStore = Symbol('soundworks:shared-state-promise-store');
+
+/**
+ * Callback executed when updates are applied on a {@link SharedState}.
+ *
+ * @callback sharedStateOnUpdateCallback
+ * @param {Object} newValues - Key / value pairs of the updates that have been
+ *  applied to the state.
+ * @param {Object} oldValues - Key / value pairs of the updated params before
+ *  the updates has been applied to the state.
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
+ *  with the values updates in the `set` call.
+ */
+
+/**
+ * Delete the registered {@link sharedStateOnUpdateCallback}.
+ *
+ * @callback sharedStateDeleteOnUpdateCallback
+ */
+
+/**
+ * The `SharedState` is one of the most important and versatile abstraction provided
+ * by `soundworks`. It represents a set of parameters that are synchronized accross
+ * every nodes of the application (clients and server) that declared some interest
+ * to the shared state.
+ *
+ * A `SharedState` instance is created according to a shared state class definition
+ * which is composed of a {@link SharedStateClassName} and of a {@link SharedStateClassSchema}
+ * registered in the {@link ServerStateManager}. Any number of `SharedState`s
+ * can be created from a single class definition.
+ *
+ * A shared state can be created both by the clients or by the server, in which case
+ * it is generally considered as a global state of the application. Similarly any
+ * node of the application (clients or server) can declare interest and "attach" to
+ * a state created by another node. All node attached to a state can modify its values
+ * and/or react to the modifications applied by other nodes.
+ *
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
+ *
+ * ```
+ * // server-side
+ * import { Server } from '@soundworks/server/index.js';
+ *
+ * const server = new Server(config);
+ * // define a shared state class
+ * server.stateManager.registerSchema('some-global-state', {
+ *   myRandom: {
+ *     type: 'float',
+ *     default: 0,
+ *   }
+ * });
+ *
+ * await server.start();
+ *
+ * // create a global state server-side
+ * const globalState = await server.stateManager.create('some-global-state');
+ * // listen and react to the changes made by the clients
+ * globalState.onUpdate(updates => console.log(updates));
+ * ```
+ *
+ * ```
+ * // client-side
+ * import { Client } from '@soundworks/client.index.js';
+ *
+ * const client = new Client(config);
+ * await client.start();
+ *
+ * // attach to the global state created by the server
+ * const globalState = await client.stateManager.attach('some-global-state');
+ *
+ * // update the value of a `myRandom` parameter every seconds
+ * setInterval(() => {
+ *   globalState.set({ myRandom: Math.random() });
+ * }, 1000);
+ * ```
+ */
+class SharedState {
+  #id = null;
+  #remoteId = null;
+  #className = null;
+  #isOwner = null;
+  #client = null;
+  #manager = null;
+  #filter = null;
+  // true is the state has been detached or deleted
+  #detached = false;
+  #parameters = null;
+  #onUpdateCallbacks = new Set();
+  #onDetachCallbacks = new Set();
+  #onDeleteCallbacks = new Set();
+
+  constructor(id, remoteId, className, schema, client, isOwner, manager, initValues, filter) {
+    this.#id = id;
+    this.#remoteId = remoteId;
+    this.#className = className;
+    this.#isOwner = isOwner; // may be any node
+    this.#client = client;
+    this.#manager = manager;
+    this.#filter = filter;
 
     try {
-      /** @private */
-      this._parameters = new ParameterBag(schema, initValues);
+      this.#parameters = new ParameterBag(schema, initValues);
     } catch (err) {
       console.error(err.stack);
 
-      throw new Error(`Error creating or attaching state "${schemaName}" w/ values:\n
+      throw new Error(`Error creating or attaching state "${className}" w/ values:\n
 ${JSON.stringify(initValues, null, 2)}`);
     }
 
     /** @private */
-    this._onUpdateCallbacks = new Set();
-    /** @private */
-    this._onDetachCallbacks = new Set();
-    /** @private */
-    this._onDeleteCallbacks = new Set();
+    this[kSharedStatePromiseStore] = new PromiseStore(this.constructor.name);
 
     // 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);
-      this._promiseStore.resolve(reqId, updated);
+    this.#client.transport.addListener(`${UPDATE_RESPONSE}-${this.#id}-${this.#remoteId}`, async (reqId, updates, context) => {
+      const updated = await this.#commit(updates, context, true, true);
+      this[kSharedStatePromiseStore].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);
-      this._promiseStore.resolve(reqId, updated);
+    this.#client.transport.addListener(`${UPDATE_ABORT}-${this.#id}-${this.#remoteId}`, async (reqId, updates, context) => {
+      const updated = await this.#commit(updates, context, false, true);
+      this[kSharedStatePromiseStore].resolve(reqId, updated);
     });
 
-    this._client.transport.addListener(`${UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`, async (updates, context) => {
+    this.#client.transport.addListener(`${UPDATE_NOTIFICATION}-${this.#id}-${this.#remoteId}`, async (updates, context) => {
       // https://github.com/collective-soundworks/soundworks/issues/18
       //
       // # note: 2002-10-03
       //
-      // `setTimeout(async () => this._commit(updates, context, true, false));`
+      // `setTimeout(async () => this.#commit(updates, context, true, false));`
       // appears to be the only way to push the update commit in the next event
       // cycle so that `attach` can resolve before the update notification is
       // actually dispatched. The alternative:
-      // `Promise.resolve().then(() => this._commit(updates, context, true, false))``
+      // `Promise.resolve().then(() => this.#commit(updates, context, true, false))``
       // does not behave as expected...
       //
       // However this breaks the reliability of:
@@ -100,17 +170,17 @@ ${JSON.stringify(initValues, null, 2)}`);
       // ```
       // which is far more important than the edge case reported in the issue
       // therefore this wont be fixed for now
-      this._commit(updates, context, true, false);
+      this.#commit(updates, context, true, false);
     });
 
     // ---------------------------------------------
     // state has been deleted by its creator or the schema has been deleted
     // ---------------------------------------------
-    this._client.transport.addListener(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`, async () => {
-      this._manager._statesById.delete(this.id);
-      this._clearTransport();
+    this.#client.transport.addListener(`${DELETE_NOTIFICATION}-${this.#id}-${this.#remoteId}`, async () => {
+      this.#manager[kStateManagerDeleteState](this.#id);
+      this.#clearTransport();
 
-      for (let callback of this._onDetachCallbacks) {
+      for (let callback of this.#onDetachCallbacks) {
         try {
           await callback();
         } catch (err) {
@@ -118,68 +188,68 @@ ${JSON.stringify(initValues, null, 2)}`);
         }
       }
 
-      if (this._isOwner) {
-        for (let callback of this._onDeleteCallbacks) {
+      if (this.#isOwner) {
+        for (let callback of this.#onDeleteCallbacks) {
           await callback();
         }
       }
 
-      this._onDetachCallbacks.clear();
-      this._onDeleteCallbacks.clear();
-      this._promiseStore.flush();
+      this.#onDetachCallbacks.clear();
+      this.#onDeleteCallbacks.clear();
+      this[kSharedStatePromiseStore].flush();
     });
 
 
-    if (this._isOwner) {
+    if (this.#isOwner) {
       // ---------------------------------------------
       // the creator has called `.delete()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
-        this._manager._statesById.delete(this.id);
-        this._clearTransport();
+      this.#client.transport.addListener(`${DELETE_RESPONSE}-${this.#id}-${this.#remoteId}`, async (reqId) => {
+        this.#manager[kStateManagerDeleteState](this.#id);
+        this.#clearTransport();
 
-        for (let callback of this._onDetachCallbacks) {
+        for (let callback of this.#onDetachCallbacks) {
           await callback();
         }
 
-        for (let callback of this._onDeleteCallbacks) {
+        for (let callback of this.#onDeleteCallbacks) {
           await callback();
         }
 
-        this._onDetachCallbacks.clear();
-        this._onDeleteCallbacks.clear();
-        this._promiseStore.resolve(reqId, this);
-        this._promiseStore.flush();
+        this.#onDetachCallbacks.clear();
+        this.#onDeleteCallbacks.clear();
+        this[kSharedStatePromiseStore].resolve(reqId, this);
+        this[kSharedStatePromiseStore].flush();
       });
 
-      this._client.transport.addListener(`${DELETE_ERROR}-${this.id}`, (reqId, msg) => {
-        this._promiseStore.reject(reqId, msg);
+      this.#client.transport.addListener(`${DELETE_ERROR}-${this.#id}`, (reqId, msg) => {
+        this[kSharedStatePromiseStore].reject(reqId, msg);
       });
 
     } else {
       // ---------------------------------------------
       // the attached node has called `.detach()`
       // ---------------------------------------------
-      this._client.transport.addListener(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`, async (reqId) => {
-        this._manager._statesById.delete(this.id);
-        this._clearTransport();
+      this.#client.transport.addListener(`${DETACH_RESPONSE}-${this.#id}-${this.#remoteId}`, async (reqId) => {
+        this.#manager[kStateManagerDeleteState](this.#id);
+        this.#clearTransport();
 
-        for (let callback of this._onDetachCallbacks) {
+        for (let callback of this.#onDetachCallbacks) {
           await callback();
         }
 
-        this._onDetachCallbacks.clear();
-        this._onDeleteCallbacks.clear();
-        this._promiseStore.resolve(reqId, this);
-        this._promiseStore.flush();
+        this.#onDetachCallbacks.clear();
+        this.#onDeleteCallbacks.clear();
+        this[kSharedStatePromiseStore].resolve(reqId, this);
+        this[kSharedStatePromiseStore].flush();
       });
 
       // the state does not exists anymore in the server (should not happen)
-      this._client.transport.addListener(`${DETACH_ERROR}-${this.id}`, (reqId, msg) => {
-        this._onDetachCallbacks.clear();
-        this._onDeleteCallbacks.clear();
-        this._promiseStore.reject(reqId, msg);
-        this._promiseStore.flush();
+      this.#client.transport.addListener(`${DETACH_ERROR}-${this.#id}`, (reqId, msg) => {
+        this.#onDetachCallbacks.clear();
+        this.#onDeleteCallbacks.clear();
+        this[kSharedStatePromiseStore].reject(reqId, msg);
+        this[kSharedStatePromiseStore].flush();
       });
     }
   }
@@ -187,70 +257,65 @@ ${JSON.stringify(initValues, null, 2)}`);
   /**
    * Id of the state
    * @type {Number}
-   * @readonly
    */
   get id() {
-    return this._id;
+    return this.#id;
   }
 
   /**
-   * Unique id of the state for the current node
-   * @readonly
-   * @type {Number}
-   * @private
+   * Name of the underlying {@link SharedState} class.
+   * @type {String}
+   * @deprecated
    */
-  get remoteId() {
-    return this._remoteId;
+  get schemaName() {
+    logger.deprecated('SharedState#schemaName', 'SharedState#className');
+    return this.#className;
   }
 
   /**
-   * Name of the schema
+   * Name of the underlying {@link SharedState} class.
    * @type {String}
-   * @readonly
    */
-  get schemaName() {
-    return this._schemaName;
+  get className() {
+    return this.#className;
   }
 
   /**
-   * Indicates if the node is the owner of the state
+   * Indicates if the node is the owner of the state, i.e. if it created the state.
    * @type {Boolean}
-   * @readonly
    */
   get isOwner() {
-    return this._isOwner;
+    return this.#isOwner;
   }
 
-  /** @private */
-  _clearTransport() {
+  #clearTransport() {
     // remove listeners
-    this._client.transport.removeAllListeners(`${UPDATE_RESPONSE}-${this.id}-${this.remoteId}`);
-    this._client.transport.removeAllListeners(`${UPDATE_NOTIFICATION}-${this.id}-${this.remoteId}`);
-    this._client.transport.removeAllListeners(`${UPDATE_ABORT}-${this.id}-${this.remoteId}`);
-    this._client.transport.removeAllListeners(`${DELETE_NOTIFICATION}-${this.id}-${this.remoteId}`);
-
-    if (this._isOwner) {
-      this._client.transport.removeAllListeners(`${DELETE_RESPONSE}-${this.id}-${this.remoteId}`);
-      this._client.transport.removeAllListeners(`${DELETE_ERROR}-${this.id}-${this.remoteId}`);
+    this.#client.transport.removeAllListeners(`${UPDATE_RESPONSE}-${this.#id}-${this.#remoteId}`);
+    this.#client.transport.removeAllListeners(`${UPDATE_NOTIFICATION}-${this.#id}-${this.#remoteId}`);
+    this.#client.transport.removeAllListeners(`${UPDATE_ABORT}-${this.#id}-${this.#remoteId}`);
+    this.#client.transport.removeAllListeners(`${DELETE_NOTIFICATION}-${this.#id}-${this.#remoteId}`);
+
+    if (this.#isOwner) {
+      this.#client.transport.removeAllListeners(`${DELETE_RESPONSE}-${this.#id}-${this.#remoteId}`);
+      this.#client.transport.removeAllListeners(`${DELETE_ERROR}-${this.#id}-${this.#remoteId}`);
     } else {
-      this._client.transport.removeAllListeners(`${DETACH_RESPONSE}-${this.id}-${this.remoteId}`);
-      this._client.transport.removeAllListeners(`${DETACH_ERROR}-${this.id}-${this.remoteId}`);
+      this.#client.transport.removeAllListeners(`${DETACH_RESPONSE}-${this.#id}-${this.#remoteId}`);
+      this.#client.transport.removeAllListeners(`${DETACH_ERROR}-${this.#id}-${this.#remoteId}`);
     }
   }
 
-  /** @private */
-  async _commit(updates, context, propagate = true, initiator = false) {
+  async #commit(updates, context, propagate = true, initiator = false) {
     const newValues = {};
     const oldValues = {};
 
     for (let name in updates) {
-      const { immediate, event } = this._parameters.getSchema(name);
+      const { immediate, event } = this.#parameters.getSchema(name);
       // @note 20211209 - we had an issue here server-side, because if the value
       // is an object or an array, the reference is shared by everybody, therefore
       // `changed` is always false and the new value is never propagated...
       // FIXED - `state.get` now returns a deep copy when `type` is `any`
-      const oldValue = this._parameters.get(name);
-      const [newValue, changed] = this._parameters.set(name, updates[name]);
+      const oldValue = this.#parameters.get(name);
+      const [newValue, changed] = this.#parameters.set(name, updates[name]);
 
       // handle immediate stuff
       if (initiator && immediate) {
@@ -272,7 +337,7 @@ ${JSON.stringify(initValues, null, 2)}`);
     let promises = [];
 
     if (propagate && Object.keys(newValues).length > 0) {
-      this._onUpdateCallbacks.forEach(listener => {
+      this.#onUpdateCallbacks.forEach(listener => {
         promises.push(listener(newValues, oldValues, context));
       });
     }
@@ -283,10 +348,10 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     // reset events to null after propagation of all listeners
     for (let name in newValues) {
-      const { event } = this._parameters.getSchema(name);
+      const { event } = this.#parameters.getSchema(name);
 
       if (event) {
-        this._parameters.set(name, null);
+        this.#parameters.set(name, null);
       }
     }
 
@@ -296,14 +361,15 @@ ${JSON.stringify(initValues, null, 2)}`);
   /**
    * Update values of the state.
    *
-   * The returned `Promise` resolves on the applied updates, when all the `onUpdate`
-   * callbacks have resolved themselves, i.e.:
+   * The returned `Promise` resolves on an object that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves, i.e.:
    *
    * ```js
    * server.stateManager.registerSchema('test', {
    *   myBool: { type: 'boolean', default: false },
    * });
    * const a = await server.stateManager.create('a');
+   *
    * let asyncCallbackCalled = false;
    *
    * a.onUpdate(updates => {
@@ -320,26 +386,27 @@ ${JSON.stringify(initValues, null, 2)}`);
    * assert.deepEqual(updates, { myBool: true });
    * ```
    *
-   * @param {object} updates - key / value pairs of updates to apply to the state.
-   * @param {mixed} [context=null] - optionnal contextual object that will be propagated
+   * @param {object} updates - Key / value pairs of updates to apply to the state.
+   * @param {mixed} [context=null] - Optionnal contextual object that will be propagated
    *   alongside the updates of the state. The context is valid only for the
    *   current call and will be passed as third argument to all update listeners.
    * @returns {Promise<Object>} A promise to the (coerced) updates.
+   *
    * @example
-   * const state = await client.state.attach('globals');
+   * const state = await client.stateManager.attach('globals');
    * const updates = await state.set({ myParam: Math.random() });
    */
   async set(updates, context = null) {
-    if (this._detached) {
+    if (this.#detached) {
       return;
     }
 
     if (!isPlainObject(updates)) {
-      throw new TypeError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as first parameter`);
+      throw new TypeError(`[SharedState] State "${this.#className}": state.set(updates[, context]) should receive an object as first parameter`);
     }
 
     if (context !== null && !isPlainObject(context)) {
-      throw new TypeError(`[SharedState] State "${this.schemaName}": state.set(updates[, context]) should receive an object as second parameter`);
+      throw new TypeError(`[SharedState] State "${this.#className}": state.set(updates[, context]) should receive an object as second parameter`);
     }
 
     const newValues = {};
@@ -355,12 +422,12 @@ ${JSON.stringify(initValues, null, 2)}`);
       // Try to coerce value early, so that eventual errors are triggered early
       // on the node requesting the update, and not only on the server side
       // This throws if name does not exists
-      this._parameters.coerceValue(name, updates[name]);
+      this.#parameters.coerceValue(name, updates[name]);
 
       // Check that name is in filter list, if any
-      if (this._filter !== null) {
-        if (!this._filter.includes(name)) {
-          throw new DOMException(`[SharedState] State "${this.schemaName}": cannot set parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+      if (this.#filter !== null) {
+        if (!this.#filter.includes(name)) {
+          throw new DOMException(`[SharedState] State "${this.#className}": cannot set parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
         }
       }
 
@@ -385,11 +452,11 @@ ${JSON.stringify(initValues, null, 2)}`);
       // response, call update listeners with server response and resolve promise with
       // the full payload, i.e. reintegrating the local params in the resolve payload
 
-      const { local, immediate, filterChange, event } = this._parameters.getSchema(name);
+      const { local, immediate, filterChange, event } = this.#parameters.getSchema(name);
 
       if (immediate || local) {
-        const oldValue = this._parameters.get(name);
-        const [newValue, changed] = this._parameters.set(name, updates[name]);
+        const oldValue = this.#parameters.get(name);
+        const [newValue, changed] = this.#parameters.set(name, updates[name]);
 
         // prepare data for immediate propagation of listeners
         if (changed || filterChange === false || event) {
@@ -403,7 +470,7 @@ ${JSON.stringify(initValues, null, 2)}`);
       if (local) {
         hasLocalParam = true;
         // get sanitize value for fulfilling promise
-        localParams[name] = this._parameters.get(name);
+        localParams[name] = this.#parameters.get(name);
       } else {
         // note that immediate are shared params too
         hasSharedParam = true;
@@ -413,7 +480,7 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     // propagate immediate params if changed
     if (propagateNow) {
-      this._onUpdateCallbacks.forEach(listener => listener(newValues, oldValues, context));
+      this.#onUpdateCallbacks.forEach(listener => listener(newValues, oldValues, context));
     }
 
     // check if we can resolve immediately or if we need to go through network
@@ -431,62 +498,67 @@ ${JSON.stringify(initValues, null, 2)}`);
 
     // go through server-side normal behavior
     return new Promise((resolve, reject) => {
-      const reqId = this._promiseStore.add(resolve, reject, 'update-request', forwardParams);
-      this._client.transport.emit(`${UPDATE_REQUEST}-${this.id}-${this.remoteId}`, reqId, updates, context);
+      const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'update-request', forwardParams);
+      this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#remoteId}`, reqId, updates, context);
     });
   }
 
   /**
-   * Get the value of a parameter of the state. If the parameter is of `any` type,
-   * a deep copy is returned.
+   * Get the value of a parameter of the state.
+   *
+   * Be aware that in case of 'any' typethe returned value is deeply copied.
+   * While this prevents from pollution of the state by mutating the reference,
+   * this can also lead to performance issues when the parameter contains large
+   * data. In such cases you should use the {@link SharedState#getUnsafe} method
+   * and make sure to treat the returned object as readonly.
    *
-   * @param {string} name - Name of the param.
-   * @throws Throws if `name` does not correspond to an existing field
-   *  of the state.
-   * @return {mixed}
+   * @param {SharedStateParameterName} name - Name of the param.
+   * @return {any}
+   * @throws Throws if `name` does not exists.
    * @example
    * const value = state.get('paramName');
    */
   get(name) {
-    if (!this._parameters.has(name)) {
-      throw new ReferenceError(`[SharedState] State "${this.schemaName}": Cannot get value of undefined parameter "${name}"`);
+    if (!this.#parameters.has(name)) {
+      throw new ReferenceError(`[SharedState] State "${this.#className}": Cannot get value of undefined parameter "${name}"`);
     }
 
-    if (this._filter !== null) {
-      if (!this._filter.includes(name)) {
-        throw new DOMException(`[SharedState] State "${this.schemaName}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+    if (this.#filter !== null) {
+      if (!this.#filter.includes(name)) {
+        throw new DOMException(`[SharedState] State "${this.#className}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
       }
     }
 
-    return this._parameters.get(name);
+    return this.#parameters.get(name);
   }
 
   /**
+   * Get an unsafe reference to the value of a parameter of the state.
+   *
    * Similar to `get` but returns a reference to the underlying value in case of
-   * `any` type. May be usefull if the underlying value is big (e.g. sensors
+   * `any` type. Can be usefull if the underlying value is large (e.g. sensors
    * recordings, etc.) and deep cloning expensive. Be aware that if changes are
    * made on the returned object, the state of your application will become
    * inconsistent.
    *
-   * @param {string} name - Name of the param.
-   * @throws Throws if `name` does not correspond to an existing field
-   *  of the state.
-   * @return {mixed}
+   * @param {SharedStateParameterName} name - Name of the param.
+   * @return {any}
+   * @throws Throws if `name` does not exists.
    * @example
    * const value = state.getUnsafe('paramName');
    */
   getUnsafe(name) {
-    if (!this._parameters.has(name)) {
-      throw new ReferenceError(`[SharedState] State "${this.schemaName}": Cannot get value of undefined parameter "${name}"`);
+    if (!this.#parameters.has(name)) {
+      throw new ReferenceError(`[SharedState] State "${this.#className}": Cannot get value of undefined parameter "${name}"`);
     }
 
-    if (this._filter !== null) {
-      if (!this._filter.includes(name)) {
-        throw new DOMException(`[SharedState] State "${this.schemaName}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
+    if (this.#filter !== null) {
+      if (!this.#filter.includes(name)) {
+        throw new DOMException(`[SharedState] State "${this.#className}": cannot get parameter '${name}', parameter is not in filter list`, 'NotSupportedError');
       }
     }
 
-    return this._parameters.getUnsafe(name);
+    return this.#parameters.getUnsafe(name);
   }
 
   /**
@@ -499,11 +571,11 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const values = state.getValues();
    */
   getValues() {
-    const values = this._parameters.getValues();
+    const values = this.#parameters.getValues();
 
-    if (this._filter !== null) {
+    if (this.#filter !== null) {
       for (let name in values) {
-        if (!this._filter.includes(name)) {
+        if (!this.#filter.includes(name)) {
           delete values[name];
         }
       }
@@ -516,7 +588,7 @@ ${JSON.stringify(initValues, null, 2)}`);
    * Get all the key / value pairs of the state.
    *
    * Similar to `getValues` but returns a reference to the underlying value in
-   * case of `any` type. May be usefull if the underlying value is big (e.g.
+   * case of `any` type. Can be usefull if the underlying value is big (e.g.
    * sensors recordings, etc.) and deep cloning expensive. Be aware that if
    * changes are made on the returned object, the state of your application will
    * become inconsistent.
@@ -526,11 +598,11 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const values = state.getValues();
    */
   getValuesUnsafe() {
-    const values = this._parameters.getValuesUnsafe();
+    const values = this.#parameters.getValuesUnsafe();
 
-    if (this._filter !== null) {
+    if (this.#filter !== null) {
       for (let name in values) {
-        if (!this._filter.includes(name)) {
+        if (!this.#filter.includes(name)) {
           delete values[name];
         }
       }
@@ -540,18 +612,18 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Definition of schema from which the state has been created.
+   * Return the underlying {@link SharedStateClassSchema} or the
+   * {@link SharedStateParameterDescription} if name is given.
    *
-   * @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}
+   * @param {string} [name] - If defined, returns only the parameter description
+   *  of the given param name.
+   * @return {SharedStateClassSchema|SharedStateParameterDescription}
+   * @throws Throws if `name` does not exists.
    * @example
    * const schema = state.getSchema();
    */
   getSchema(name = null) {
-    return this._parameters.getSchema(name);
+    return this.#parameters.getSchema(name);
   }
 
   /**
@@ -563,7 +635,7 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const initValues = state.getInitValues();
    */
   getInitValues() {
-    return this._parameters.getInitValues();
+    return this.#parameters.getInitValues();
   }
 
   /**
@@ -574,7 +646,7 @@ ${JSON.stringify(initValues, null, 2)}`);
    * const defaults = state.getDefaults();
    */
   getDefaults() {
-    return this._parameters.getDefaults();
+    return this.#parameters.getDefaults();
   }
 
   /**
@@ -587,22 +659,22 @@ ${JSON.stringify(initValues, null, 2)}`);
    * await state.detach();
    */
   async detach() {
-    if (this._detached) {
-      throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already detached, cannot detach twice`);
+    if (this.#detached) {
+      throw new Error(`[SharedState] State "${this.#className} (${this.#id})" already detached, cannot detach twice`);
     }
 
-    this._detached = true; // mark detached early
-    this._onUpdateCallbacks.clear();
+    this.#detached = true; // mark detached early
+    this.#onUpdateCallbacks.clear();
 
-    if (this._isOwner) {
+    if (this.#isOwner) {
       return new Promise((resolve, reject) => {
-        const reqId = this._promiseStore.add(resolve, reject, 'delete-request');
-        this._client.transport.emit(`${DELETE_REQUEST}-${this.id}-${this.remoteId}`, reqId);
+        const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'delete-request');
+        this.#client.transport.emit(`${DELETE_REQUEST}-${this.#id}-${this.#remoteId}`, reqId);
       });
     } else {
       return new Promise((resolve, reject) => {
-        const reqId = this._promiseStore.add(resolve, reject, 'detach-request');
-        this._client.transport.emit(`${DETACH_REQUEST}-${this.id}-${this.remoteId}`, reqId);
+        const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'detach-request');
+        this.#client.transport.emit(`${DETACH_REQUEST}-${this.#id}-${this.#remoteId}`, reqId);
       });
     }
   }
@@ -623,25 +695,25 @@ ${JSON.stringify(initValues, null, 2)}`);
    * await state.delete();
    */
   async delete() {
-    if (this._isOwner) {
-      if (this._detached) {
-        throw new Error(`[SharedState] State "${this.schemaName} (${this.id})" already deleted, cannot delete twice`);
+    if (this.#isOwner) {
+      if (this.#detached) {
+        throw new Error(`[SharedState] State "${this.#className} (${this.#id})" already deleted, cannot delete twice`);
       }
 
       return this.detach();
     } else {
-      throw new Error(`[SharedState] Cannot delete state "${this.schemaName}", only the owner of the state (i.e. the node that created it) can delete the state. Use "detach" instead.`);
+      throw new Error(`[SharedState] Cannot delete state "${this.#className}", only the owner of the state (i.e. the node that created it) can delete the state. Use "detach" instead.`);
     }
   }
 
   /**
    * Subscribe to state updates.
    *
-   * @param {client.SharedState~onUpdateCallback|server.SharedState~onUpdateCallback} callback
+   * @param {sharedStateOnUpdateCallback} callback
    *  Callback to execute when an update is applied on the state.
    * @param {Boolean} [executeListener=false] - Execute the callback immediately
    *  with current state values. (`oldValues` will be set to `{}`, and `context` to `null`)
-   * @returns {client.SharedState~deleteOnUpdateCallback|server.SharedState~deleteOnUpdateCallback}
+   * @returns {sharedStateDeleteOnUpdateCallback}
    * @example
    * const unsubscribe = state.onUpdate(async (newValues, oldValues, context) =>  {
    *   for (let [key, value] of Object.entries(newValues)) {
@@ -655,7 +727,7 @@ ${JSON.stringify(initValues, null, 2)}`);
    * unsubscribe();
    */
   onUpdate(listener, executeListener = false) {
-    this._onUpdateCallbacks.add(listener);
+    this.#onUpdateCallbacks.add(listener);
 
     if (executeListener === true) {
       const currentValues = this.getValues();
@@ -665,7 +737,7 @@ ${JSON.stringify(initValues, null, 2)}`);
     }
 
     return () => {
-      this._onUpdateCallbacks.delete(listener);
+      this.#onUpdateCallbacks.delete(listener);
     };
   }
 
@@ -678,8 +750,8 @@ ${JSON.stringify(initValues, null, 2)}`);
    *   creator.
    */
   onDetach(callback) {
-    this._onDetachCallbacks.add(callback);
-    return () => this._onDetachCallbacks.delete(callback);
+    this.#onDetachCallbacks.add(callback);
+    return () => this.#onDetachCallbacks.delete(callback);
   }
 
   /**
@@ -690,9 +762,9 @@ ${JSON.stringify(initValues, null, 2)}`);
    * @param {Function} callback - Callback to execute when the state is deleted.
    */
   onDelete(callback) {
-    this._onDeleteCallbacks.add(callback);
-    return () => this._onDeleteCallbacks.delete(callback);
+    this.#onDeleteCallbacks.add(callback);
+    return () => this.#onDeleteCallbacks.delete(callback);
   }
 }
 
-export default BaseSharedState;
+export default SharedState;