@soundworks/core 4.0.0-alpha.9 → 5.0.0

package/src/common/SharedState.js

@@ -0,0 +1,821 @@
+import { isPlainObject, isString } from '@ircam/sc-utils';
+
+import ParameterBag from './ParameterBag.js';
+import PromiseStore from './PromiseStore.js';
+import {
+  DELETE_REQUEST,
+  DELETE_RESPONSE,
+  DELETE_ERROR,
+  DELETE_NOTIFICATION,
+  DETACH_REQUEST,
+  DETACH_RESPONSE,
+  DETACH_ERROR,
+  UPDATE_REQUEST,
+  UPDATE_RESPONSE,
+  UPDATE_ABORT,
+  UPDATE_NOTIFICATION,
+} from './constants.js';
+
+import {
+  kStateManagerClient,
+  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.
+ */
+
+/**
+ * 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 across
+ * 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 SharedStateClassDescription}
+ * 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.defineClass('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;
+  #instanceId = 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({
+    stateId,
+    instanceId,
+    className,
+    classDescription,
+    isOwner,
+    manager,
+    initValues,
+    filter,
+  }) {
+    this.#manager = manager;
+    this.#client = manager[kStateManagerClient];
+    this.#className = className;
+    this.#id = stateId;
+    this.#instanceId = instanceId;
+    this.#isOwner = isOwner; // may be any node
+    this.#filter = filter;
+
+    try {
+      this.#parameters = new ParameterBag(classDescription, initValues);
+    } catch (err) {
+      throw new Error(`Cannot construct 'SharedState': ${err.message}`);
+    }
+
+    /** @private */
+    this[kSharedStatePromiseStore] = new PromiseStore(this.constructor.name);
+
+    // add listener for state updates
+    this.#client.transport.addListener(`${UPDATE_RESPONSE}-${this.#id}-${this.#instanceId}`, async (reqId, updates) => {
+      const updated = await this.#commit(updates, true, true);
+      this[kSharedStatePromiseStore].resolve(reqId, updated);
+    });
+
+    // retrieve values but do not propagate to subscriptions
+    this.#client.transport.addListener(`${UPDATE_ABORT}-${this.#id}-${this.#instanceId}`, async (reqId, updates) => {
+      const updated = await this.#commit(updates, false, true);
+      this[kSharedStatePromiseStore].resolve(reqId, updated);
+    });
+
+    this.#client.transport.addListener(`${UPDATE_NOTIFICATION}-${this.#id}-${this.#instanceId}`, async (updates) => {
+      // https://github.com/collective-soundworks/soundworks/issues/18
+      //
+      // # note: 2002-10-03
+      //
+      // `setTimeout(async () => this.#commit(updates, 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, true, false))``
+      // does not behave as expected...
+      //
+      // However this breaks the reliability of:
+      // ```
+      // /* given a0, a1 and a2 being 3 similar attached states */
+      // await state.set({ int: i });
+      //
+      // assert.equal(a0.get('int'), i);
+      // assert.equal(a1.get('int'), i);
+      // assert.equal(a2.get('int'), i);
+      // ```
+      // which is far more important than the edge case reported in the issue
+      // therefore this wont be fixed for now
+      this.#commit(updates, true, false);
+    });
+
+    // ---------------------------------------------
+    // state has been deleted by its creator or the class has been deleted
+    // ---------------------------------------------
+    this.#client.transport.addListener(`${DELETE_NOTIFICATION}-${this.#id}-${this.#instanceId}`, async () => {
+      this.#manager[kStateManagerDeleteState](this.#id);
+      this.#clearTransport();
+
+      for (let callback of this.#onDetachCallbacks) {
+        try {
+          await callback();
+        } catch (err) {
+          console.error(err.message);
+        }
+      }
+
+      if (this.#isOwner) {
+        for (let callback of this.#onDeleteCallbacks) {
+          await callback();
+        }
+      }
+
+      this.#onDetachCallbacks.clear();
+      this.#onDeleteCallbacks.clear();
+      this[kSharedStatePromiseStore].flush();
+    });
+
+
+    if (this.#isOwner) {
+      // ---------------------------------------------
+      // the creator has called `.delete()`
+      // ---------------------------------------------
+      this.#client.transport.addListener(`${DELETE_RESPONSE}-${this.#id}-${this.#instanceId}`, async (reqId) => {
+        this.#manager[kStateManagerDeleteState](this.#id);
+        this.#clearTransport();
+
+        for (let callback of this.#onDetachCallbacks) {
+          await callback();
+        }
+
+        for (let callback of this.#onDeleteCallbacks) {
+          await callback();
+        }
+
+        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[kSharedStatePromiseStore].reject(reqId, msg);
+      });
+
+    } else {
+      // ---------------------------------------------
+      // the attached node has called `.detach()`
+      // ---------------------------------------------
+      this.#client.transport.addListener(`${DETACH_RESPONSE}-${this.#id}-${this.#instanceId}`, async (reqId) => {
+        this.#manager[kStateManagerDeleteState](this.#id);
+        this.#clearTransport();
+
+        for (let callback of this.#onDetachCallbacks) {
+          await callback();
+        }
+
+        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[kSharedStatePromiseStore].reject(reqId, msg);
+        this[kSharedStatePromiseStore].flush();
+      });
+    }
+  }
+
+  /**
+   * Id of the state
+   * @type {Number}
+   */
+  get id() {
+    return this.#id;
+  }
+
+  /**
+   * Name of the underlying {@link SharedState} class.
+   * @type {String}
+   */
+  get className() {
+    return this.#className;
+  }
+
+  /**
+   * @deprecated Use {@link SharedState#className} instead.
+   */
+  get schemaName() {
+    logger.deprecated('SharedState#schemaName', 'SharedState#className', '4.0.0-alpha.29');
+    return this.className;
+  }
+
+  /**
+   * Indicates if the node is the owner of the state, i.e. if it created the state.
+   * @type {Boolean}
+   */
+  get isOwner() {
+    return this.#isOwner;
+  }
+
+  #clearTransport() {
+    // remove listeners
+    this.#client.transport.removeAllListeners(`${UPDATE_RESPONSE}-${this.#id}-${this.#instanceId}`);
+    this.#client.transport.removeAllListeners(`${UPDATE_NOTIFICATION}-${this.#id}-${this.#instanceId}`);
+    this.#client.transport.removeAllListeners(`${UPDATE_ABORT}-${this.#id}-${this.#instanceId}`);
+    this.#client.transport.removeAllListeners(`${DELETE_NOTIFICATION}-${this.#id}-${this.#instanceId}`);
+
+    if (this.#isOwner) {
+      this.#client.transport.removeAllListeners(`${DELETE_RESPONSE}-${this.#id}-${this.#instanceId}`);
+      this.#client.transport.removeAllListeners(`${DELETE_ERROR}-${this.#id}-${this.#instanceId}`);
+    } else {
+      this.#client.transport.removeAllListeners(`${DETACH_RESPONSE}-${this.#id}-${this.#instanceId}`);
+      this.#client.transport.removeAllListeners(`${DETACH_ERROR}-${this.#id}-${this.#instanceId}`);
+    }
+  }
+
+  async #commit(updates, propagate = true, initiator = false) {
+    const newValues = {};
+    const oldValues = {};
+
+    for (let name in updates) {
+      const { immediate, event } = this.#parameters.getDescription(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]);
+
+      // handle immediate stuff
+      if (initiator && immediate) {
+        // @note - we don't need to check filterChange here because the value
+        // has been updated in parameters on the `set` side so can rely on `changed`
+        // to avoid retrigger listeners.
+        // If the value has been overridden by the server, `changed` will true
+        // anyway so it should behave correctly.
+        if (!changed || event) {
+          continue;
+        }
+      }
+
+      newValues[name] = newValue;
+      oldValues[name] = oldValue;
+    }
+
+    // if the `UPDATE_REQUEST` as been aborted by the server, do not propagate
+    let promises = [];
+
+    if (propagate && Object.keys(newValues).length > 0) {
+      this.#onUpdateCallbacks.forEach(listener => {
+        promises.push(listener(newValues, oldValues));
+      });
+    }
+
+    // on a given client, `await state.set(update)` resolves after all
+    // update callbacks have themselves resolved
+    await Promise.all(promises);
+
+    // reset events to null after propagation of all listeners
+    for (let name in newValues) {
+      const { event } = this.#parameters.getDescription(name);
+
+      if (event) {
+        this.#parameters.set(name, null);
+      }
+    }
+
+    return newValues;
+  }
+
+  /**
+   * Return the underlying {@link SharedStateClassDescription} or the
+   * {@link SharedStateParameterDescription} if `paramName` is given.
+   *
+   * @param {string} [paramName=null] - If defined, returns the parameter
+   *  description of the given parameter name rather than the full class description.
+   * @return {SharedStateClassDescription|SharedStateParameterDescription}
+   * @throws Throws if `paramName` is not null and does not exists.
+   * @example
+   * const classDescription = state.getDescription();
+   * const paramDescription = state.getDescription('my-param');
+   */
+  getDescription(paramName = null) {
+    try {
+      return this.#parameters.getDescription(paramName);
+    } catch (err) {
+      throw new ReferenceError(`Cannot execute 'getDescription' on SharedState: ${err.message}`);
+    }
+  }
+
+  /**
+   * @deprecated Use {@link SharedState#getDescription} instead.
+   */
+  getSchema(paramName = null) {
+    logger.deprecated('SharedState#getSchema', 'SharedState#getDescription', '4.0.0-alpha.29');
+    return this.getDescription(paramName);
+  }
+
+  /**
+   * 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 {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 },
+   * });
+   * 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 });
+   * ```
+   *
+   * 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>} - Promise to the (coerced) updates.
+   *
+   * @example
+   * const state = await client.stateManager.attach('globals');
+   * const updates = await state.set({ myParam: Math.random() });
+   */
+  async set(updates) {
+    if (this.#detached) {
+      return;
+    }
+
+    if (isPlainObject(arguments[0]) && isPlainObject(arguments[1])) {
+      logger.removed('`context` argument in SharedState.set(updates, context)', 'a regular parameter configured with `event=true`', '4.0.0-alpha.29');
+    }
+
+    if (arguments.length === 2 && isString(updates)) {
+      updates = { [updates]: arguments[1] };
+    } else if (!isPlainObject(updates)) {
+      throw new TypeError(`Cannot execute 'set' on SharedState (${this.#className}): 'updates' argument should be an object`);
+    }
+
+    const newValues = {};
+    const oldValues = {};
+    const localParams = {};
+    const sharedParams = {};
+    let hasLocalParam = false;
+    let hasSharedParam = false;
+    let forwardParams = undefined;
+    let propagateNow = false;
+
+    for (let name in updates) {
+      // 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
+      try {
+        this.#parameters.coerceValue(name, updates[name]);
+      } catch (err) {
+        throw new TypeError(`Cannot execute 'set' on SharedState (${this.#className}): ${err.message}`);
+      }
+
+      // Check that name is in filter list, if any
+      if (this.#filter !== null) {
+        if (!this.#filter.includes(name)) {
+          throw new DOMException(`Cannot execute 'set' on SharedState (${this.#className}): Parameter '${name}' is not in white list`, 'NotSupportedError');
+        }
+      }
+
+      // `immediate` option behavior
+      //
+      // If immediate=true
+      //  - call listeners if value changed
+      //  - go through normal server path
+      //  - retrigger only if response from server is different from current value
+      // If immediate=true && (filterChange=false || event=true)
+      //  - call listeners with value regardless it changed
+      //  - go through normal server path
+      //  - if the node is initiator of the update (UPDATE_RESPONSE), (re-)check
+      //    to prevent execute the listeners twice
+
+      // `local` option behavior
+      //
+      // - If the `updates` object only contains local variables, we can call the
+      // update listeners and return a fulfilled promise immediately
+      // - If parameters that require network communication are present, we call the
+      // update callback onces with the local payload, then we need to wait for the server
+      // 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.getDescription(name);
+
+      if (immediate || local) {
+        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) {
+          oldValues[name] = oldValue;
+          newValues[name] = newValue;
+          propagateNow = true;
+        }
+      }
+
+      // define params that must go through network or not
+      if (local) {
+        hasLocalParam = true;
+        // get sanitize value for fulfilling promise
+        localParams[name] = this.#parameters.get(name);
+      } else {
+        // note that immediate are shared params too
+        hasSharedParam = true;
+        sharedParams[name] = updates[name];
+      }
+    }
+
+    // propagate immediate params if changed
+    if (propagateNow) {
+      this.#onUpdateCallbacks.forEach(listener => listener(newValues, oldValues));
+    }
+
+    // check if we can resolve immediately or if we need to go through network
+    if (hasLocalParam) {
+      if (!hasSharedParam) {
+        return Promise.resolve(localParams);
+      } else {
+        // store local params to fulfill promise with all values, see PromiseStore
+        forwardParams = localParams;
+      }
+    }
+
+    // override updates to be shared on network without local params
+    updates = sharedParams;
+
+    // go through server-side normal behavior
+    return new Promise((resolve, reject) => {
+      const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'SharedState#set', forwardParams);
+      this.#client.transport.emit(`${UPDATE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId, updates);
+    });
+  }
+
+  /**
+   * Get the value of a parameter of the state.
+   *
+   * Be aware that in case of 'any' type, the 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 {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(`Cannot execute 'get' on SharedState (${this.#className}): Parameter '${name}' is not defined`);
+    }
+
+    if (this.#filter !== null) {
+      if (!this.#filter.includes(name)) {
+        throw new DOMException(`Cannot execute 'get' on SharedState (${this.#className}): Parameter '${name}' is not in white list`, 'NotSupportedError');
+      }
+    }
+
+    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. Can be useful 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 {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(`Cannot execute 'getUnsafe' on SharedState (${this.#className}): Parameter '${name}' is not defined`);
+    }
+
+    if (this.#filter !== null) {
+      if (!this.#filter.includes(name)) {
+        throw new DOMException(`Cannot execute 'getUnsafe' on SharedState (${this.#className}): Parameter '${name}' is not in white list`, 'NotSupportedError');
+      }
+    }
+
+    return this.#parameters.getUnsafe(name);
+  }
+
+  /**
+   * Get all the key / value pairs of the state.
+   *
+   * If a parameter is of `any` type, a deep copy is made.
+   *
+   * @return {object}
+   * @example
+   * const values = state.getValues();
+   */
+  getValues() {
+    const values = this.#parameters.getValues();
+
+    if (this.#filter !== null) {
+      for (let name in values) {
+        if (!this.#filter.includes(name)) {
+          delete values[name];
+        }
+      }
+    }
+
+    return values;
+  }
+
+  /**
+   * 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. Can be useful 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.
+   *
+   * @return {object}
+   * @example
+   * const values = state.getValues();
+   */
+  getValuesUnsafe() {
+    const values = this.#parameters.getValuesUnsafe();
+
+    if (this.#filter !== null) {
+      for (let name in values) {
+        if (!this.#filter.includes(name)) {
+          delete values[name];
+        }
+      }
+    }
+
+    return values;
+  }
+
+  /**
+   * Get the values with which the state has been created. May defer from the
+   * default values declared in the class description.
+   *
+   * @return {object}
+   * @example
+   * const initValues = state.getInitValues();
+   */
+  getInitValues() {
+    return this.#parameters.getInitValues();
+  }
+
+  /**
+   * Get the default values as declared in the class description.
+   *
+   * @return {object}
+   * @example
+   * const defaults = state.getDefaults();
+   */
+  getDefaults() {
+    return this.#parameters.getDefaults();
+  }
+
+  /**
+   * Detach from the state. If the client is the creator of the state, the state
+   * is deleted and all attached nodes get notified.
+   *
+   * @example
+   * const state = await client.state.attach('globals');
+   * // later
+   * await state.detach();
+   */
+  async detach() {
+    if (this.#detached) {
+      throw new DOMException(`Cannot execute 'detach' on SharedState (${this.#className}): SharedState (${this.#id}) already detached`, 'NotSupportedError');
+    }
+
+    this.#detached = true; // mark detached early
+    this.#onUpdateCallbacks.clear();
+
+    if (this.#isOwner) {
+      return new Promise((resolve, reject) => {
+        const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'SharedState#delete');
+        this.#client.transport.emit(`${DELETE_REQUEST}-${this.#id}-${this.#instanceId}`, reqId);
+      });
+    } else {
+      return new Promise((resolve, reject) => {
+        const reqId = this[kSharedStatePromiseStore].add(resolve, reject, 'SharedState#detach');
+        this.#client.transport.emit(`${DETACH_REQUEST}-${this.#id}-${this.#instanceId}`, reqId);
+      });
+    }
+  }
+
+  /**
+   * Delete the state. Only the creator/owner of the state can use this method.
+   *
+   * All nodes attached to the state will be detached, triggering any registered
+   * `onDetach` callbacks. The creator of the state will also have its own `onDelete`
+   * callback triggered. The local `onDetach` and `onDelete` callbacks will be
+   * executed *before* the returned Promise resolves
+   *
+   * @throws Throws if the method is called by a node which is not the owner of
+   * the state.
+   * @example
+   * const state = await client.stateManager.create('my-class-name');
+   * // later
+   * await state.delete();
+   */
+  async delete() {
+    if (this.#isOwner) {
+      if (this.#detached) {
+        throw new DOMException(`Cannot execute 'delete' on SharedState (${this.#className}): SharedState (${this.#id}) already deleted`, 'NotSupportedError');
+      }
+
+      return this.detach();
+    } else {
+      throw new DOMException(`Cannot execute 'delete' on SharedState (${this.#className}): SharedState (${this.#id}) is not owned by this node. Use 'SharedState#detach' instead`, 'NotSupportedError');
+    }
+  }
+
+  /**
+   * Subscribe to state updates.
+   *
+   * @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. Note that `oldValues` will be set to `{}`.
+   * @returns {sharedStateDeleteOnUpdateCallback}
+   * @example
+   * const unsubscribe = state.onUpdate(async (newValues, oldValues) =>  {
+   *   for (let [key, value] of Object.entries(newValues)) {
+   *      switch (key) {
+   *        // do something
+   *      }
+   *   }
+   * });
+   *
+   * // later
+   * unsubscribe();
+   */
+  onUpdate(listener, executeListener = false) {
+    this.#onUpdateCallbacks.add(listener);
+
+    if (executeListener === true) {
+      const currentValues = this.getValues();
+      // filter `event: true` parameters from currentValues, having them here is
+      // misleading as we are in the context of a callback, not from an active read
+      const classDescription = this.getDescription();
+
+      for (let name in classDescription) {
+        if (classDescription[name].event === true) {
+          delete currentValues[name];
+        }
+      }
+
+      listener(currentValues, {});
+    }
+
+    return () => {
+      this.#onUpdateCallbacks.delete(listener);
+    };
+  }
+
+  /**
+   * Register a function to execute when detaching from the state. The function
+   * will be executed before the `detach` promise resolves.
+   *
+   * @param {Function} callback - Callback to execute when detaching from the state.
+   *   Whether the client as called `detach`, or the state has been deleted by its
+   *   creator.
+   */
+  onDetach(callback) {
+    this.#onDetachCallbacks.add(callback);
+    return () => this.#onDetachCallbacks.delete(callback);
+  }
+
+  /**
+   * Register a function to execute when the state is deleted. Only called if the
+   * node was the creator of the state. Is called after `onDetach` and executed
+   * before the `delete` Promise resolves.
+   *
+   * @param {Function} callback - Callback to execute when the state is deleted.
+   */
+  onDelete(callback) {
+    this.#onDeleteCallbacks.add(callback);
+    return () => this.#onDeleteCallbacks.delete(callback);
+  }
+}
+
+export default SharedState;