From a15e807f1be06eacba1243654cac760a1dfafefb Mon Sep 17 00:00:00 2001
From: b-ma <benjamin.matuszewski@gmail.com>
Date: Fri, 4 Oct 2024 16:29:30 +0200
Subject: [PATCH] doc: document overload of `SharedState#set`

---
 misc/assets/custom.css                        |  14 +--
 src/common/SharedState.js                     |  30 +++++-
 src/common/SharedStateCollection.js           |  37 ++++++-
 types/client/ClientStateManager.d.ts          |  15 +--
 types/common/BasePlugin.d.ts                  |   4 +-
 types/common/BaseStateManager.d.ts            | 101 +++++++++---------
 types/common/ParameterBag.d.ts                |  38 ++-----
 types/common/SharedState.d.ts                 |  68 +++++-------
 types/common/SharedStateCollection.d.ts       |  54 +++++++---
 types/common/constants.d.ts                   |   8 +-
 types/common/logger.d.ts                      |   3 +-
 types/common/shared-state-types.d.ts          |   9 +-
 types/server/ServerSocket.d.ts                |  18 +---
 types/server/ServerSockets.d.ts               |  50 ++++-----
 types/server/ServerStateManager.d.ts          |  71 ++++++------
 types/server/SharedStatePrivate.d.ts          |   4 +-
 ....ts => audit-state-class-description.d.ts} |   0
 17 files changed, 277 insertions(+), 247 deletions(-)
 rename types/server/{audit-schema.d.ts => audit-state-class-description.d.ts} (100%)

diff --git a/misc/assets/custom.css b/misc/assets/custom.css
index cad19a48..85045bd5 100644
--- a/misc/assets/custom.css
+++ b/misc/assets/custom.css
@@ -95,8 +95,8 @@ h1 > code {
 }
 
 h4.name {
-  color: #282922;
-  background: #dedede;
+  color: #ffffff;
+  background: #282922;
   border-top: 1px solid #efefef;
   box-shadow: 0 0.05em 0.1em #e1e1e1;
 }
@@ -106,26 +106,26 @@ h4.name {
 }
 
 .signature {
-  color: #3e4035;
+  color: #eeefea;
 }
 
 .signature-attributes {
   font-size: 60%;
-  color: #616354;
+  color: #a2a29e;
   font-style: italic;
   font-weight: lighter;
 }
 
 .type-signature {
-  color: #3e4035;
+  color: #eeefea;
 }
 
 .type-signature:last-child {
-  color: #616354;
+  color: #a2a29e;
 }
 
 h4.name a {
-  color: #3e4035;
+  color: #afafab;
 }
 
 h4.name a:hover {
diff --git a/src/common/SharedState.js b/src/common/SharedState.js
index d9a605c4..f25dc040 100644
--- a/src/common/SharedState.js
+++ b/src/common/SharedState.js
@@ -379,11 +379,31 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Update values of the state.
+   * Update the values of the state.
    *
    * The returned `Promise` resolves on an object that contains the applied updates,
-   * and resolves after all the `onUpdate` callbacks have resolved themselves, i.e.:
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * @overload
+   * @param {object} updates - Key / value pairs of updates to apply to the state.
+   * @returns {Promise<Object>} - Promise to the (coerced) updates.
+   */
+  /**
+   * Update the values of the state.
+   *
+   * The returned `Promise` resolves on an object that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
    *
+   * @overload
+   * @param {SharedStateParameterName} name - Name of the parameter.
+   * @param {*} value - Value of the parameter.
+   * @returns {Promise<Object>} - Promise to the (coerced) updates.
+   */
+  /**
+   * Update the values of the state.
+   *
+   * 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.defineClass('test', {
    *   myBool: { type: 'boolean', default: false },
@@ -406,8 +426,12 @@ ${JSON.stringify(initValues, null, 2)}`);
    * assert.deepEqual(updates, { myBool: true });
    * ```
    *
+   * Alternative signatures:
+   * - `await state.set(updates)`
+   * - `await state.set(name, value)`
+   *
    * @param {object} updates - Key / value pairs of updates to apply to the state.
-   * @returns {Promise<Object>} A promise to the (coerced) updates.
+   * @returns {Promise<Object>} - Promise to the (coerced) updates.
    *
    * @example
    * const state = await client.stateManager.attach('globals');
diff --git a/src/common/SharedStateCollection.js b/src/common/SharedStateCollection.js
index b88089ff..126e0ee1 100644
--- a/src/common/SharedStateCollection.js
+++ b/src/common/SharedStateCollection.js
@@ -115,7 +115,7 @@ class SharedStateCollection {
   }
 
   /**
-   * @deprecated Use ${@link SharedStateCollection#className} instead.
+   * @deprecated Use {@link SharedStateCollection#className} instead.
    */
   get schemaName() {
     logger.deprecated('SharedStateCollection#schemaName', 'SharedStateCollection#className', '4.0.0-alpha.29');
@@ -222,7 +222,40 @@ class SharedStateCollection {
 
   /**
    * Update all states of the collection with given values.
-   * @param {object} updates - key / value pairs of updates to apply to the state.
+   *
+   * The returned `Promise` resolves on a list of objects that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * @overload
+   * @param {object} updates - key / value pairs of updates to apply to the collection.
+   * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+   */
+  /**
+   * Update all states of the collection with given values.
+   *
+   * The returned `Promise` resolves on a list of objects that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * @overload
+   * @param {SharedStateParameterName} name - Name of the parameter.
+   * @param {*} value - Value of the parameter.
+   * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+   */
+  /**
+   * Update all states of the collection with given values.
+   *
+   * The returned `Promise` resolves on a list of objects that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * Alternative signatures:
+   * - `await collection.set(updates)`
+   * - `await collection.set(name, value)`
+   *
+   * @param {object} updates - key / value pairs of updates to apply to the collection.
+   * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+   * @example
+   * const collection = await client.stateManager.getCollection('globals');
+   * const updates = await collection.set({ myParam: Math.random() });
    */
   async set(...args) {
     // we can delegate to the state.set(update) method for throwing in case of
diff --git a/types/client/ClientStateManager.d.ts b/types/client/ClientStateManager.d.ts
index 08842843..798868ac 100644
--- a/types/client/ClientStateManager.d.ts
+++ b/types/client/ClientStateManager.d.ts
@@ -6,14 +6,15 @@ export type ClientStateManager = () => any;
 /**
  * @callback ClientStateManager~ObserveCallback
  * @async
- * @param {String} schemaName - name of the schema
- * @param {Number} stateId - id of the state
- * @param {Number} nodeId - id of the node that created the state
+ * @param {String} className - Name of the shared state class.
+ * @param {Number} stateId - Id of the state.
+ * @param {Number} nodeId - Id of the node that created the state.
  */
 /**
  * The `ClientStateManager` allows to create new {@link SharedState}s, or attach
- * to {@link SharedState}s created by other nodes (clients or server). It
- * can also track all the {@link SharedState}s created by other nodes.
+ * to {@link SharedState}s created by other nodes (clients or server) on the network.
+ *
+ * It can also observe all the {@link SharedState}s created on the network.
  *
  * An instance of `ClientStateManager` is automatically created by the `soundworks.Client`
  * at initialization (cf. {@link client.Client#stateManager}).
@@ -27,8 +28,8 @@ export type ClientStateManager = () => any;
  * import { Server } from '@soundworks/server/index.js';
  *
  * const server = new Server(config);
- * // declare and register the schema of a shared state.
- * server.stateManager.registerSchema('some-global-state', {
+ * // define a class of shared state.
+ * server.stateManager.defineClass('some-global-state', {
  *   myRandom: {
  *     type: 'float',
  *     default: 0,
diff --git a/types/common/BasePlugin.d.ts b/types/common/BasePlugin.d.ts
index 48fb5dca..05c6f782 100644
--- a/types/common/BasePlugin.d.ts
+++ b/types/common/BasePlugin.d.ts
@@ -74,7 +74,7 @@ declare class BasePlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
-     *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+     *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      *       someParam: {
      *         type: 'boolean',
      *         default: false,
@@ -106,7 +106,7 @@ declare class BasePlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
-     *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+     *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      *       someParam: {
      *         type: 'boolean',
      *         default: false,
diff --git a/types/common/BaseStateManager.d.ts b/types/common/BaseStateManager.d.ts
index 368fa74f..52ce112c 100644
--- a/types/common/BaseStateManager.d.ts
+++ b/types/common/BaseStateManager.d.ts
@@ -16,7 +16,7 @@ export type stateManagerDeleteObserveCallback = () => any;
  *
  * @callback stateManagerObserveCallback
  * @async
- * @param {string} schemaName - name of the schema
+ * @param {string} className - name of the class
  * @param {number} stateId - id of the state
  * @param {number} nodeId - id of the node that created the state
  */
@@ -29,68 +29,71 @@ export type stateManagerDeleteObserveCallback = () => any;
 /** @private */
 declare class BaseStateManager {
     /**
-     * Return the schema from a given registered schema name
+     * Return a class description from a given class name
      *
-     * @param {String} schemaName - Name of the schema as given on registration
+     * @param {SharedStateClassName} className - Name of the shared state class.
      *  (cf. ServerStateManager)
-     * @return {SharedStateSchema}
+     * @return {SharedStateClassDescription}
      * @example
-     * const schema = await client.stateManager.getSchema('my-class');
+     * const classDescription = await client.stateManager.getClassDescription('my-class');
      */
-    getSchema(schemaName: string): SharedStateSchema;
+    getClassDescription(className: SharedStateClassName): SharedStateClassDescription;
     /**
-     * Create a {@link SharedState} instance from a registered schema.
+     * @deprecated Use {@link BaseStateManager#getClassDescription} instead.
+     */
+    getSchema(className: any): Promise<any>;
+    /**
+     * Create a {@link SharedState} instance from a registered class.
      *
-     * @param {string} schemaName - Name of the schema as given on registration
-     *  (cf. ServerStateManager)
-     * @param {Object.<string, any>} [initValues={}] - Default values for the state.
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {Object.<string, any>} [initValues={}] - Default values of the created shared state.
      * @returns {Promise<SharedState>}
      * @example
      * const state = await client.stateManager.create('my-class');
      */
-    create(schemaName: string, initValues?: {
+    create(className: SharedStateClassName, initValues?: {
         [x: string]: any;
     }): Promise<SharedState>;
     /**
      * Attach to an existing {@link SharedState} instance.
      *
      * @overload
-     * @param {string} schemaName
+     * @param {SharedStateClassName} className - Name of the class.
      * @returns {Promise<SharedState>}
      *
      * @example
      * const state = await client.stateManager.attach('my-class');
      */
-    attach(schemaName: string): Promise<SharedState>;
+    attach(className: SharedStateClassName): Promise<SharedState>;
     /**
      * Attach to an existing {@link SharedState} instance.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema
+     * @param {SharedStateClassName} className - Name of the class.
      * @param {number} stateId - Id of the state
      * @returns {Promise<SharedState>}
      *
      * @example
      * const state = await client.stateManager.attach('my-class', stateId);
      */
-    attach(schemaName: string, stateId: number): Promise<SharedState>;
+    attach(className: SharedStateClassName, stateId: number): Promise<SharedState>;
     /**
      * Attach to an existing {@link SharedState} instance.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema
+     * @param {SharedStateClassName} className - Name of the class.
      * @param {string[]} filter - List of parameters of interest
      * @returns {Promise<SharedState>}
      *
      * @example
      * const state = await client.stateManager.attach('my-class', ['some-param']);
      */
-    attach(schemaName: string, filter: string[]): Promise<SharedState>;
+    attach(className: SharedStateClassName, filter: string[]): Promise<SharedState>;
     /**
      * Attach to an existing {@link SharedState} instance.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema
+     * @param {SharedStateClassName} className - Name of the class.
      * @param {number} stateId - Id of the state
      * @param {string[]} filter - List of parameters of interest
      * @returns {Promise<SharedState>}
@@ -98,7 +101,7 @@ declare class BaseStateManager {
      * @example
      * const state = await client.stateManager.attach('my-class', stateId, ['some-param']);
      */
-    attach(schemaName: string, stateId: number, filter: string[]): Promise<SharedState>;
+    attach(className: SharedStateClassName, stateId: number, filter: string[]): Promise<SharedState>;
     /**
      * Observe all the {@link SharedState} instances that are created on the network.
      *
@@ -106,9 +109,9 @@ declare class BaseStateManager {
      * @param {stateManagerObserveCallback} callback - Function to execute when a
      *   new {@link SharedState} is created on the network.
      * @example
-     * client.stateManager.observe(async (schemaName, stateId) => {
-     *   if (schemaName === 'my-shared-state-class') {
-     *     const attached = await client.stateManager.attach(schemaName, stateId);
+     * client.stateManager.observe(async (className, stateId) => {
+     *   if (className === 'my-shared-state-class') {
+     *     const attached = await client.stateManager.attach(className, stateId);
      *   }
      * });
      */
@@ -118,16 +121,16 @@ declare class BaseStateManager {
      * that are created on the network.
      *
      * @overload
-     * @param {SharedStateClassName} schemaName - Observe only ${@link SharedState}
+     * @param {SharedStateClassName} className - Observe only ${@link SharedState}
      *   of given name.
      * @param {stateManagerObserveCallback} callback - Function to execute when a
      *   new {@link SharedState} is created on the network.
      * @example
-     * client.stateManager.observe('my-shared-state-class', async (schemaName, stateId) => {
-     *   const attached = await client.stateManager.attach(schemaName, stateId);
+     * client.stateManager.observe('my-shared-state-class', async (className, stateId) => {
+     *   const attached = await client.stateManager.attach(className, stateId);
      * });
      */
-    observe(schemaName: SharedStateClassName, callback: stateManagerObserveCallback): any;
+    observe(className: SharedStateClassName, callback: stateManagerObserveCallback): any;
     /**
      * Observe all the {@link SharedState} instances of given excluding the ones
      * created by the current node.
@@ -139,9 +142,9 @@ declare class BaseStateManager {
      * @param {boolean} options.excludeLocal=false - If set to true, exclude states
      *   created by the same node from the collection.
      * @example
-     * client.stateManager.observe(async (schemaName, stateId) => {
-     *   if (schemaName === 'my-shared-state-class') {
-     *     const attached = await client.stateManager.attach(schemaName, stateId);
+     * client.stateManager.observe(async (className, stateId) => {
+     *   if (className === 'my-shared-state-class') {
+     *     const attached = await client.stateManager.attach(className, stateId);
      *   }
      * }, { excludeLocal: true });
      */
@@ -153,7 +156,7 @@ declare class BaseStateManager {
      * that are created on the network, excluding the ones created by the current node.
      *
      * @overload
-     * @param {SharedStateClassName} schemaName - Observe only ${@link SharedState}
+     * @param {SharedStateClassName} className - Observe only ${@link SharedState}
      *   of given name.
      * @param {stateManagerObserveCallback} callback - Function to execute when a
      *   new {@link SharedState} is created on the network.
@@ -161,58 +164,58 @@ declare class BaseStateManager {
      * @param {boolean} options.excludeLocal=false - If set to true, exclude states
      *   created by the same node from the collection.
      * @example
-     * client.stateManager.observe('my-shared-state-class', async (schemaName, stateId) => {
-     *   const attached = await client.stateManager.attach(schemaName, stateId);
+     * client.stateManager.observe('my-shared-state-class', async (className, stateId) => {
+     *   const attached = await client.stateManager.attach(className, stateId);
      * }, { excludeLocal: true });
      */
-    observe(schemaName: SharedStateClassName, callback: stateManagerObserveCallback, options: {
+    observe(className: SharedStateClassName, callback: stateManagerObserveCallback, options: {
         excludeLocal: boolean;
     }): any;
     /**
-     * Returns a collection of all the states created from the schema name.
+     * Returns a collection of all the states created from a given shared state class.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema.
+     * @param {SharedStateClassName} className - Name of the shared state class.
      * @returns {Promise<SharedStateCollection>}
      *
      * @example
-     * const collection = await client.stateManager.getCollection(schemaName);
+     * const collection = await client.stateManager.getCollection(className);
      */
-    getCollection(schemaName: string): Promise<SharedStateCollection>;
+    getCollection(className: SharedStateClassName): Promise<SharedStateCollection>;
     /**
-     * Returns a collection of all the states created from the schema name.
+     * Returns a collection of all the states created from a given shared state class.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema.
+     * @param {SharedStateClassName} className - Name of the shared state class.
      * @param {SharedStateParameterName[]} filter - Filter parameter of interest for each
      *  state of the collection.
      * @returns {Promise<SharedStateCollection>}
      *
      * @example
-     * const collection = await client.stateManager.getCollection(schemaName, ['my-param']);
+     * const collection = await client.stateManager.getCollection(className, ['my-param']);
      */
-    getCollection(schemaName: string, filter: SharedStateParameterName[]): Promise<SharedStateCollection>;
+    getCollection(className: SharedStateClassName, filter: SharedStateParameterName[]): Promise<SharedStateCollection>;
     /**
-     * Returns a collection of all the states created from the schema name.
+     * Returns a collection of all the states created from a given shared state class.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema.
+     * @param {SharedStateClassName} className - Name of the shared state class.
      * @param {object} options - Options.
      * @param {boolean} options.excludeLocal=false - If set to true, exclude states
      *  created by the same node from the collection.
      * @returns {Promise<SharedStateCollection>}
      *
      * @example
-     * const collection = await client.stateManager.getCollection(schemaName, { excludeLocal: true });
+     * const collection = await client.stateManager.getCollection(className, { excludeLocal: true });
      */
-    getCollection(schemaName: string, options: {
+    getCollection(className: SharedStateClassName, options: {
         excludeLocal: boolean;
     }): Promise<SharedStateCollection>;
     /**
-     * Returns a collection of all the states created from the schema name.
+     * Returns a collection of all the states created from a given shared state class.
      *
      * @overload
-     * @param {string} schemaName - Name of the schema.
+     * @param {SharedStateClassName} className - Name of the shared state class.
      * @param {SharedStateParameterName[]} filter - Filter parameter of interest for each
      *  state of the collection.
      * @param {object} options - Options.
@@ -221,9 +224,9 @@ declare class BaseStateManager {
      * @returns {Promise<SharedStateCollection>}
      *
      * @example
-     * const collection = await client.stateManager.getCollection(schemaName, ['my-param'], { excludeLocal: true });
+     * const collection = await client.stateManager.getCollection(className, ['my-param'], { excludeLocal: true });
      */
-    getCollection(schemaName: string, filter: SharedStateParameterName[], options: {
+    getCollection(className: SharedStateClassName, filter: SharedStateParameterName[], options: {
         excludeLocal: boolean;
     }): Promise<SharedStateCollection>;
     /** @private */
diff --git a/types/common/ParameterBag.d.ts b/types/common/ParameterBag.d.ts
index fb4e01d3..1ab43699 100644
--- a/types/common/ParameterBag.d.ts
+++ b/types/common/ParameterBag.d.ts
@@ -26,7 +26,7 @@ export namespace types {
         export { required_3 as required };
         const defaultOptions_2: any;
         export { defaultOptions_2 as defaultOptions };
-        export function sanitizeSchema(def: any): any;
+        export function sanitizeDescription(def: any): any;
         export function coerceFunction_2(name: any, def: any, value: any): number;
         export { coerceFunction_2 as coerceFunction };
     }
@@ -35,8 +35,8 @@ export namespace types {
         export { required_4 as required };
         const defaultOptions_3: any;
         export { defaultOptions_3 as defaultOptions };
-        export function sanitizeSchema_1(def: any): any;
-        export { sanitizeSchema_1 as sanitizeSchema };
+        export function sanitizeDescription_1(def: any): any;
+        export { sanitizeDescription_1 as sanitizeDescription };
         export function coerceFunction_3(name: any, def: any, value: any): number;
         export { coerceFunction_3 as coerceFunction };
     }
@@ -61,28 +61,8 @@ export namespace types {
 export default ParameterBag;
 /** @private */
 declare class ParameterBag {
-    static validateSchema(schema: any): void;
-    constructor(schema: any, initValues?: {});
-    /**
-     * List of parameters.
-     *
-     * @type {Object<String, Param>}
-     * @name _params
-     * @memberof ParameterBag
-     * @instance
-     * @private
-     */
-    private _values;
-    /**
-     * List of schema with init values.
-     *
-     * @type {Object<String, paramDefinition>}
-     * @name _schema
-     * @memberof ParameterBag
-     * @instance
-     * @private
-     */
-    private _schema;
+    static validateDescription(description: any): void;
+    constructor(description: any, initValues?: {});
     /**
      * Define if the parameter exists.
      *
@@ -127,8 +107,7 @@ declare class ParameterBag {
      */
     getUnsafe(name: string): Mixed;
     /**
-     * Check that the value is valid according to the schema and return it coerced
-     * to the schema definition
+     * Check that the value is valid according to the class definition and return it coerced.
      *
      * @param {String} name - Name of the parameter.
      * @param {Mixed} value - Value of the parameter.
@@ -152,11 +131,10 @@ declare class ParameterBag {
      * @param {string} [name=null] - Name of the parameter to reset.
      */
     /**
-     * Return the given schema along with the initialization values.
-     *
      * @return {object}
      */
-    getSchema(name?: any): object;
+    getDescription(name?: any): object;
     getInitValues(): {};
     getDefaults(): {};
+    #private;
 }
diff --git a/types/common/SharedState.d.ts b/types/common/SharedState.d.ts
index 2fd53c42..802c3a83 100644
--- a/types/common/SharedState.d.ts
+++ b/types/common/SharedState.d.ts
@@ -3,7 +3,7 @@ export default SharedState;
 /**
  * Callback executed when updates are applied on a {@link SharedState }.
  */
-export type sharedStateOnUpdateCallback = (newValues: any, oldValues: any, context?: Mixed) => any;
+export type sharedStateOnUpdateCallback = (newValues: any, oldValues: any) => any;
 /**
  * Delete the registered {@link sharedStateOnUpdateCallback }.
  */
@@ -16,8 +16,6 @@ export type sharedStateDeleteOnUpdateCallback = () => any;
  *  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}.
@@ -31,7 +29,7 @@ export type sharedStateDeleteOnUpdateCallback = () => any;
  * 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}
+ * which is composed of a {@link SharedStateClassName} and of a {@link SharedStateClassDescription}
  * registered in the {@link ServerStateManager}. Any number of `SharedState`s
  * can be created from a single class definition.
  *
@@ -49,7 +47,7 @@ export type sharedStateDeleteOnUpdateCallback = () => any;
  *
  * const server = new Server(config);
  * // define a shared state class
- * server.stateManager.registerSchema('some-global-state', {
+ * server.stateManager.defineClass('some-global-state', {
  *   myRandom: {
  *     type: 'float',
  *     default: 0,
@@ -81,7 +79,7 @@ export type sharedStateDeleteOnUpdateCallback = () => any;
  * ```
  */
 declare class SharedState {
-    constructor(id: any, remoteId: any, className: any, schema: any, client: any, isOwner: any, manager: any, initValues: any, filter: any);
+    constructor(id: any, remoteId: any, className: any, classDescription: any, client: any, isOwner: any, manager: any, initValues: any, filter: any);
     /**
      * Id of the state
      * @type {Number}
@@ -119,44 +117,28 @@ declare class SharedState {
      */
     getSchema(paramName?: any): any;
     /**
-     * Update values of the state.
+     * Update the values of the state.
      *
      * 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 => {
-     *   return new Promise(resolve => {
-     *     setTimeout(() => {
-     *       asyncCallbackCalled = true;
-     *       resolve();
-     *     }, 100);
-     *   });
-     * });
-     *
-     * const updates = await a.set({ myBool: true });
-     * assert.equal(asyncCallbackCalled, true);
-     * assert.deepEqual(updates, { myBool: true });
-     * ```
+     * and resolves after all the `onUpdate` callbacks have resolved themselves
      *
+     * @overload
      * @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.
+     * @returns {Promise<Object>} - Promise to the (coerced) updates.
+     */
+    set(updates: object): Promise<any>;
+    /**
+     * Update the values of the state.
      *
-     * @example
-     * const state = await client.stateManager.attach('globals');
-     * const updates = await state.set({ myParam: Math.random() });
+     * The returned `Promise` resolves on an object that contains the applied updates,
+     * and resolves after all the `onUpdate` callbacks have resolved themselves
+     *
+     * @overload
+     * @param {SharedStateParameterName} name - Name of the parameter.
+     * @param {*} value - Value of the parameter.
+     * @returns {Promise<Object>} - Promise to the (coerced) updates.
      */
-    set(updates: object, context?: mixed): Promise<any>;
+    set(name: SharedStateParameterName, value: any): Promise<any>;
     /**
      * Get the value of a parameter of the state.
      *
@@ -215,7 +197,7 @@ declare class SharedState {
     getValuesUnsafe(): object;
     /**
      * Get the values with which the state has been created. May defer from the
-     * default values declared in the schema.
+     * default values declared in the class description.
      *
      * @return {object}
      * @example
@@ -223,7 +205,7 @@ declare class SharedState {
      */
     getInitValues(): object;
     /**
-     * Get the default values as declared in the schema.
+     * Get the default values as declared in the class description.
      *
      * @return {object}
      * @example
@@ -251,7 +233,7 @@ declare class SharedState {
      * @throws Throws if the method is called by a node which is not the owner of
      * the state.
      * @example
-     * const state = await client.state.create('my-schema-name');
+     * const state = await client.stateManaager.create('my-class-name');
      * // later
      * await state.delete();
      */
@@ -262,10 +244,10 @@ declare class SharedState {
      * @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`)
+     *  with current state values. Note that `oldValues` will be set to `{}`.
      * @returns {sharedStateDeleteOnUpdateCallback}
      * @example
-     * const unsubscribe = state.onUpdate(async (newValues, oldValues, context) =>  {
+     * const unsubscribe = state.onUpdate(async (newValues, oldValues) =>  {
      *   for (let [key, value] of Object.entries(newValues)) {
      *      switch (key) {
      *        // do something
diff --git a/types/common/SharedStateCollection.d.ts b/types/common/SharedStateCollection.d.ts
index fc0d1c6d..8915fb26 100644
--- a/types/common/SharedStateCollection.d.ts
+++ b/types/common/SharedStateCollection.d.ts
@@ -1,5 +1,9 @@
 export default SharedStateCollection;
-export type sharedStateCollectionOnUpdateCallback = (state: SharedState, newValues: any, oldValues: any, context?: Mixed) => any;
+export type sharedStateCollectionOnUpdateCallback = (state: SharedState, newValues: any, oldValues: any) => any;
+/**
+ * Delete the registered {@link sharedStateCollectionOnUpdateCallback }.
+ */
+export type sharedStateCollectionDeleteOnUpdateCallback = () => any;
 /**
  * @callback sharedStateCollectionOnUpdateCallback
  * @param {SharedState} state - State that triggered the update.
@@ -7,12 +11,15 @@ export type sharedStateCollectionOnUpdateCallback = (state: SharedState, newValu
  *  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 sharedStateCollectionOnUpdateCallback}.
+ *
+ * @callback sharedStateCollectionDeleteOnUpdateCallback
  */
 /**
  * The `SharedStateCollection` interface represent a collection of all states
- * created from a given schema name on the network.
+ * created from a given class name on the network.
  *
  * It can optionnaly exclude the states created by the current node.
  *
@@ -20,9 +27,9 @@ export type sharedStateCollectionOnUpdateCallback = (state: SharedState, newValu
  * {@link ServerStateManager#getCollection} for factory methods API
  *
  * ```
- * const collection = await client.stateManager.getCollection('my-schema');
+ * const collection = await client.stateManager.getCollection('my-class');
  * const allValues = collection.getValues();
- * collection.onUpdate((state, newValues, oldValues, context) => {
+ * collection.onUpdate((state, newValues, oldValues) => {
  *   // do something
  * });
  * ```
@@ -70,7 +77,7 @@ declare class SharedStateCollection {
      */
     getDescription(paramName?: string): SharedStateClassDescription | SharedStateParameterDescription;
     /**
-     * Get the default values as declared in the schema.
+     * Get the default values as declared in the class description.
      *
      * @return {object}
      * @example
@@ -114,23 +121,38 @@ declare class SharedStateCollection {
     getUnsafe(name: string): any[];
     /**
      * Update all states of the collection with given values.
-     * @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.
+     *
+     * The returned `Promise` resolves on a list of objects that contains the applied updates,
+     * and resolves after all the `onUpdate` callbacks have resolved themselves
+     *
+     * @overload
+     * @param {object} updates - key / value pairs of updates to apply to the collection.
+     * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
      */
-    set(updates: object, context?: mixed): Promise<any[]>;
+    set(updates: object): Promise<Array<any>>;
+    /**
+     * Update all states of the collection with given values.
+     *
+     * The returned `Promise` resolves on a list of objects that contains the applied updates,
+     * and resolves after all the `onUpdate` callbacks have resolved themselves
+     *
+     * @overload
+     * @param {SharedStateParameterName} name - Name of the parameter.
+     * @param {*} value - Value of the parameter.
+     * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+     */
+    set(name: SharedStateParameterName, value: any): Promise<Array<any>>;
     /**
      * Subscribe to any state update of the collection.
      *
      * @param {sharedStateCollectionOnUpdateCallback}
      *  callback - Callback to execute when an update is applied on a state.
      * @param {Boolean} [executeListener=false] - Execute the callback immediately
-     *  for all underlying states with current state values. (`oldValues` will be
-     *  set to `{}`, and `context` to `null`)
-     * @returns {Function} - Function that delete the registered listener.
+     *  with current state values. Note that `oldValues` will be set to `{}`.
+     * @returns {sharedStateCollectionDeleteOnUpdateCallback} - Function that delete
+     *  the registered listener.
      */
-    onUpdate(callback: sharedStateCollectionOnUpdateCallback, executeListener?: boolean): Function;
+    onUpdate(callback: sharedStateCollectionOnUpdateCallback, executeListener?: boolean): sharedStateCollectionDeleteOnUpdateCallback;
     /**
      * Register a function to execute when a state is added to the collection.
      *
diff --git a/types/common/constants.d.ts b/types/common/constants.d.ts
index 2b44638f..d9fa7108 100644
--- a/types/common/constants.d.ts
+++ b/types/common/constants.d.ts
@@ -25,10 +25,10 @@ export const UPDATE_REQUEST: "s:u:req";
 export const UPDATE_RESPONSE: "s:u:res";
 export const UPDATE_ABORT: "s:u:ab";
 export const UPDATE_NOTIFICATION: "s:u:not";
-export const DELETE_SCHEMA: "s:d:s";
-export const GET_SCHEMA_REQUEST: "s:s:req";
-export const GET_SCHEMA_RESPONSE: "s:s:res";
-export const GET_SCHEMA_ERROR: "s:s:err";
+export const DELETE_SHARED_STATE_CLASS: "s:d:s";
+export const GET_CLASS_DESCRIPTION_REQUEST: "s:s:req";
+export const GET_CLASS_DESCRIPTION_RESPONSE: "s:s:res";
+export const GET_CLASS_DESCRIPTION_ERROR: "s:s:err";
 export const CONTEXT_ENTER_REQUEST: "c:en:req";
 export const CONTEXT_ENTER_RESPONSE: "c:en:res";
 export const CONTEXT_ENTER_ERROR: "c:en:err";
diff --git a/types/common/logger.d.ts b/types/common/logger.d.ts
index 8c2ec163..f2f40ded 100644
--- a/types/common/logger.d.ts
+++ b/types/common/logger.d.ts
@@ -13,5 +13,6 @@ declare namespace logger {
     function pluginReady(name: any): void;
     function pluginErrored(name: any): void;
     function warnVersionDiscepancies(clientRole: any, clientVersion: any, serverVersion: any): void;
-    function deprecated(oldAPI: any, newAPI: any, deprecationVersion: any): void;
+    function deprecated(oldAPI: any, newAPI: any, lastSupportedVersion: any): void;
+    function removed(oldAPI: any, hint: any, lastSupportedVersion: any): never;
 }
diff --git a/types/common/shared-state-types.d.ts b/types/common/shared-state-types.d.ts
index 72094e5a..558c2d44 100644
--- a/types/common/shared-state-types.d.ts
+++ b/types/common/shared-state-types.d.ts
@@ -4,7 +4,7 @@
 type SharedStateClassName = string;
 /**
  * Description of a {@link SharedState } data structure that describes the structure
- * of a class of {@link SharedState } to be registered by {@link ServerStateManagerregisterSchema }
+ * of a class of {@link SharedState } to be registered by {@link ServerStateManagerdefineClass }
  *
  * A `SharedStateClassDescription` is the blueprint, or the definition from which
  * shared states from a given class can be created.
@@ -61,6 +61,13 @@ type SharedStateParameterDescription = {
      * the listeners will be called again when the "real" value is received.
      */
     immediate?: boolean;
+    /**
+     * - When set to true, the parameter is never
+     * propagated on the network (hence it is no longer a shared parameter :). This
+     * is usefull to declare some common parameter (e.g. some interface state) that
+     * don't need to be shared but to stay in the shared state API paradigm.
+     */
+    local?: boolean;
     /**
      * - Minimum value of the parameter. Only applies
      * for `integer` and `float` types.
diff --git a/types/server/ServerSocket.d.ts b/types/server/ServerSocket.d.ts
index 4451c53f..25ac6094 100644
--- a/types/server/ServerSocket.d.ts
+++ b/types/server/ServerSocket.d.ts
@@ -17,14 +17,8 @@ declare class ServerSocket {
     constructor(ws: any, sockets: any);
     /**
      * Reference to the @link{ServerSockets} instance.
-     *
-     * Allows for broadcasting from a given socket instance.
-     *
-     * @type {ServerSockets}
-     * @example
-     * socket.sockets.broadcast('my-room', this, 'update-value', 1);
      */
-    get sockets(): ServerSockets;
+    get sockets(): any;
     /**
      * Reay state of the underlying socket instance.
      *
@@ -62,16 +56,6 @@ declare class ServerSocket {
      * @param {string} channel - Channel name.
      */
     removeAllListeners(channel?: string): void;
-    /**
-     * Add the socket to a room
-     * @param {string} roomId - Id of the room.
-     */
-    addToRoom(roomId: string): void;
-    /**
-     * Remove the socket from a room
-     * @param {string} roomId - Id of the room.
-     */
-    removeFromRoom(roomId: string): void;
     /**
      * Removes all listeners and immediately close the web socket.
      *
diff --git a/types/server/ServerSockets.d.ts b/types/server/ServerSockets.d.ts
index 8254564b..db248c0d 100644
--- a/types/server/ServerSockets.d.ts
+++ b/types/server/ServerSockets.d.ts
@@ -1,6 +1,6 @@
 export const kSocketsStart: unique symbol;
 export const kSocketsStop: unique symbol;
-export const kSocketsRemoveFromAllRooms: unique symbol;
+export const kSocketsDeleteSocket: unique symbol;
 export const kSocketsLatencyStatsWorker: unique symbol;
 export const kSocketsDebugPreventHeartBeat: unique symbol;
 export default ServerSockets;
@@ -12,39 +12,31 @@ export default ServerSockets;
  */
 declare class ServerSockets {
     constructor(server: any, config: any);
+    /** @private */
+    private entries;
+    /** @private */
+    private keys;
+    /** @private */
+    private values;
+    forEach(func: any): void;
     /**
-     * Add a socket to a room.
-     *
-     * _Note that in most cases, you should use a {@link SharedState} instead_
-     *
-     * @param {ServerSocket} socket - Socket to add to the room.
-     * @param {String} roomId - Id of the room.
+     * Initialize sockets, all sockets are added to two rooms by default:
+     * - to the room corresponding to the client `role`
+     * - to the '*' room that holds all connected sockets
+     * @private
      */
-    addToRoom(socket: ServerSocket, roomId: string): void;
+    private [kSocketsStart];
     /**
-     * Remove a socket from a room.
-     *
-     * _Note that in most cases, you should use a {@link SharedState} instead_
-     *
-     * @param {ServerSocket} socket - Socket to remove from the room.
-     * @param {String} roomId - Id of the room.
+     * Terminate all existing sockets.
+     * @private
      */
-    removeFromRoom(socket: ServerSocket, roomId: string): void;
+    private [kSocketsStop];
     /**
-     * Send a message to all clients os given room(s). If no room is specified,
-     * the message is sent to all clients.
-     *
-     * _Note that in most cases, you should use a {@link SharedState} instead_
-     *
-     * @param {String|Array} roomsIds - Ids of the rooms that must receive
-     *  the message. If `null` the message is sent to all clients.
-     * @param {ServerSocket} excludeSocket - Optionnal socket to ignore when
-     *  broadcasting the message, typically the client at the origin of the message.
-     * @param {String} channel - Channel name.
-     * @param {...*} args - Payload of the message. As many arguments as needed, of
-     *  JSON compatible data types (i.e. string, number, boolean, object, array and null).
+     * Remove given socket from all rooms.
+     * @private
      */
-    broadcast(roomIds: any, excludeSocket: ServerSocket, channel: string, ...args: any[]): void;
+    private [kSocketsDeleteSocket];
+    [kSocketsLatencyStatsWorker]: any;
+    [kSocketsDebugPreventHeartBeat]: boolean;
     #private;
 }
-import ServerSocket from './ServerSocket.js';
diff --git a/types/server/ServerStateManager.d.ts b/types/server/ServerStateManager.d.ts
index d03accd2..35d7a427 100644
--- a/types/server/ServerStateManager.d.ts
+++ b/types/server/ServerStateManager.d.ts
@@ -26,8 +26,8 @@ export type serverStateManagerUpdateHook = () => any;
  * at initialization (cf. {@link Server#stateManager}).
  *
  * Compared to the {@link ClientStateManager}, the `ServerStateManager` can also
- * register and delete schemas, as well as register update hook that are executed when
- * a state is updated.
+ * define and delete shared state classes, as well as register hooks executed at
+ * lifecycle phases of a shared state
  *
  * See {@link Server#stateManager}
  *
@@ -38,8 +38,8 @@ export type serverStateManagerUpdateHook = () => any;
  * import { Server } from '@soundworks/server/index.js';
  *
  * const server = new Server(config);
- * // declare and register the schema of a shared state.
- * server.stateManager.registerSchema('some-global-state', {
+ * // declare and register the class of a shared state.
+ * server.stateManager.defineClass('some-global-state', {
  *   myRandom: {
  *     type: 'float',
  *     default: 0,
@@ -76,19 +76,16 @@ export type serverStateManagerUpdateHook = () => any;
  */
 declare class ServerStateManager extends BaseStateManager {
     /**
-     * Define a class of data structure from which {@link SharedState} can be instanciated.
+     * Define a generic class from which {@link SharedState}s can be created.
      *
-     * _In a future revision, this method and its arguments will be renamed_
-     *
-     * @param {SharedStateClassName} schemaName - Name of the schema.
-     * @param {SharedStateSchema} schema - Data structure
-     *  describing the states that will be created from this schema.
+     * @param {SharedStateClassName} className - Name of the class.
+     * @param {SharedStateClassDescription} classDescription - Description of the class.
      *
      * @see {@link ServerStateManager#create}
      * @see {@link ClientStateManager#create}
      *
      * @example
-     * server.stateManager.registerSchema('my-schema', {
+     * server.stateManager.defineClass('my-class', {
      *   myBoolean: {
      *     type: 'boolean'
      *     default: false,
@@ -99,41 +96,47 @@ declare class ServerStateManager extends BaseStateManager {
      *     min: -1,
      *     max: 1
      *   }
-     * })
+     * });
+     */
+    defineClass(className: SharedStateClassName, classDescription: SharedStateClassDescription): void;
+    /**
+     * @deprecated Use {@link ServerStateManager#defineClass} instead.
      */
-    registerSchema(schemaName: SharedStateClassName, schema: SharedStateSchema): void;
+    registerSchema(className: any, classDescription: any): void;
     /**
      * Delete a whole class of {@link ShareState}.
      *
-     * All {@link SharedState} instance that belong to this class are deleted
-     * as well, triggering the `onDetach` and `onDelete` callbacks are called on
-     * the actual {@link SharedState} instances.
-     *
-     * _In a future revision, this method and its arguments will be renamed_
+     * All {@link SharedState} instances created from this class will be deleted
+     * as well, triggering their eventual `onDetach` and `onDelete` callbacks.
      *
-     * @param {SharedStateClassName} schemaName - Name of the schema.
+     * @param {SharedStateClassName} className - Name of the shared state class to delete.
+     */
+    deleteClass(className: SharedStateClassName): void;
+    /**
+     * @deprecated Use {@link ServerStateManager#defineClass} instead.
      */
-    deleteSchema(schemaName: SharedStateClassName): void;
+    deleteSchema(className: any): void;
     /**
-     * Register a function for a given schema (e.g. will be applied on all states
-     * created from this schema) that will be executed before the update values
-     * are propagated. For example, this could be used to implement a preset system
+     * Register a function for a given shared state class the be executed between
+     * `set` instructions and `onUpdate` callback(s).
+     *
+     * For example, this could be used to implement a preset system
      * where all the values of the state are updated from e.g. some data stored in
      * filesystem while the consumer of the state only want to update the preset name.
      *
-     * The hook is associated to every state of its kind (i.e. schemaName) and
-     * executed on every update (call of `set`). Note that the hooks are executed
-     * server-side regarless the node on which `set` has been called and before
-     * the "actual" update of the state (e.g. before the call of `onUpdate`).
+     * The hook is associated to each states created from the given class name
+     * executed on each update (i.e. `state.set(updates)`). Note that the hooks are
+     * executed server-side regarless the node on which `set` has been called and
+     * before the call of the `onUpdate` callback of the shared state.
      *
-     * @param {string} schemaName - Kind of states on which applying the hook.
-     * @param {serverStateManagerUpdateHook} updateHook - Function
-     *   called between the `set` call and the actual update.
+     * @param {string} className - Kind of states on which applying the hook.
+     * @param {serverStateManagerUpdateHook} updateHook - Function called between
+     *  the `set` call and the actual update.
      *
      * @returns {Fuction} deleteHook - Handler that deletes the hook when executed.
      *
      * @example
-     * server.stateManager.registerSchema('hooked', {
+     * server.stateManager.defineClass('hooked', {
      *   value: { type: 'string', default: null, nullable: true },
      *   numUpdates: { type: 'integer', default: 0 },
      * });
@@ -150,13 +153,13 @@ declare class ServerStateManager extends BaseStateManager {
      * const values = state.getValues();
      * assert.deepEqual(result, { value: 'test', numUpdates: 1 });
      */
-    registerUpdateHook(schemaName: string, updateHook: serverStateManagerUpdateHook): Fuction;
+    registerUpdateHook(className: string, updateHook: serverStateManagerUpdateHook): Fuction;
+    /** @private */
+    private [kStateManagerInit];
     /** @private */
     private [kServerStateManagerDeletePrivateState];
     /** @private */
     private [kServerStateManagerGetHooks];
-    /** @private */
-    private [kStateManagerInit];
     /**
      * Add a client to the manager.
      *
diff --git a/types/server/SharedStatePrivate.d.ts b/types/server/SharedStatePrivate.d.ts
index de627430..e76ec1b3 100644
--- a/types/server/SharedStatePrivate.d.ts
+++ b/types/server/SharedStatePrivate.d.ts
@@ -8,9 +8,9 @@ export default SharedStatePrivate;
  * @private
  */
 declare class SharedStatePrivate {
-    constructor(id: any, schemaName: any, schema: any, manager: any, initValues?: {});
+    constructor(id: any, className: any, classDefinition: any, manager: any, initValues?: {});
     get id(): any;
-    get schemaName(): any;
+    get className(): any;
     get creatorId(): any;
     get creatorRemoteId(): any;
     get attachedClients(): Map<any, any>;
diff --git a/types/server/audit-schema.d.ts b/types/server/audit-state-class-description.d.ts
similarity index 100%
rename from types/server/audit-schema.d.ts
rename to types/server/audit-state-class-description.d.ts