@soundworks/core 5.5.0 → 5.7.0

package/src/server/SharedStatePrivate.js

@@ -9,6 +9,7 @@ import {
   UPDATE_RESPONSE,
   UPDATE_ABORT,
   UPDATE_NOTIFICATION,
+  HAS_SIBLINGS_NOTIFICATION,
 } from '../common/constants.js';
 import {
   kServerStateManagerDeletePrivateState,
@@ -23,7 +24,7 @@ import {
  * @private
  */
 function whiteListFilterUpdates(updates, whiteList) {
-  if (whiteList === null) {
+  if (!Array.isArray(whiteList)) {
     return updates;
   }
 
@@ -43,7 +44,7 @@ function whiteListFilterUpdates(updates, whiteList) {
  * @private
  */
 function blackListFilterUpdates(updates, blackList) {
-  if (blackList === null) {
+  if (!Array.isArray(blackList)) {
     return updates;
   }
   // create a shallow copy so we can have multiple filters applied on same source
@@ -58,6 +59,22 @@ function blackListFilterUpdates(updates, blackList) {
   return filtered;
 }
 
+function applyFilters(updates, options) {
+  if (options === null) {
+    return updates;
+  }
+
+  const { whiteList, blackList } = options;
+  // precedence to white list
+  if (Array.isArray(whiteList)) {
+    updates = whiteListFilterUpdates(updates, whiteList);
+  } else if (Array.isArray(blackList)) {
+    updates = blackListFilterUpdates(updates, blackList);
+  }
+
+  return updates;
+}
+
 export const kSharedStatePrivateAttachClient = Symbol('soundworks:shared-state-private-attach-client');
 export const kSharedStatePrivateDetachClient = Symbol('soundworks:shared-state-private-detach-client');
 export const kSharedStatePrivateGetValues = Symbol('soundworks:shared-state-private-get-values');
@@ -73,8 +90,7 @@ class SharedStatePrivate {
   #className = null;
   #manager = null;
   #parameters = null;
-  #creatorId = null;
-  #creatorInstanceId = null;
+  #ownerId = null;
   #attachedClients = new Map();
 
   constructor(manager, className, classDefinition, id, initValues = {}) {
@@ -93,12 +109,8 @@ class SharedStatePrivate {
     return this.#className;
   }
 
-  get creatorId() {
-    return this.#creatorId;
-  }
-
-  get creatorInstanceId() {
-    return this.#creatorInstanceId;
+  get ownerId() {
+    return this.#ownerId;
   }
 
   get attachedClients() {
@@ -113,21 +125,53 @@ class SharedStatePrivate {
     return this.#parameters.getValues();
   }
 
-  [kSharedStatePrivateAttachClient](instanceId, client, isOwner, filter) {
-    const clientInfos = { client, isOwner, filter };
+  [kSharedStatePrivateAttachClient](instanceId, client, isOwner, options) {
+    if (isOwner) {
+      this.#ownerId = client.id;
+    }
+
+    const clientInfos = { client, isOwner, options };
     this.#attachedClients.set(instanceId, clientInfos);
 
+    client.transport.addListener(`${UPDATE_REQUEST}-${this.id}-${instanceId}`, this.#onUpdateRequest(instanceId, client));
+
     if (isOwner) {
-      this.#creatorId = client.id;
-      this.#creatorInstanceId = instanceId;
+      client.transport.addListener(`${DELETE_REQUEST}-${this.id}-${instanceId}`, this.#onDeleteRequest);
+    } else {
+      client.transport.addListener(`${DETACH_REQUEST}-${this.id}-${instanceId}`, this.#onDetachRequest(instanceId, client));
+      this.#updateHasSiblings();
     }
+  }
+
+  [kSharedStatePrivateDetachClient](instanceId, client) {
+    this.#attachedClients.delete(instanceId);
+
+    client.transport.removeAllListeners(`${UPDATE_REQUEST}-${this.id}-${instanceId}`);
+    client.transport.removeAllListeners(`${DELETE_REQUEST}-${this.id}-${instanceId}`);
+    client.transport.removeAllListeners(`${DETACH_REQUEST}-${this.id}-${instanceId}`);
+
+    this.#updateHasSiblings();
+  }
 
-    // attach client listeners
-    client.transport.addListener(`${UPDATE_REQUEST}-${this.id}-${instanceId}`, async (reqId, updates) => {
-      // apply registered hooks
+  /**
+   * Update hasSiblings property on owner
+   */
+  #updateHasSiblings() {
+    for (let [instanceId, clientInfos] of this.attachedClients) {
+      const { client, isOwner } = clientInfos;
+
+      if (isOwner) {
+        const hasSiblings = this.attachedClients.size > 1;
+        client.transport.emit(`${HAS_SIBLINGS_NOTIFICATION}-${this.id}-${instanceId}`, hasSiblings);
+      }
+    }
+  }
+
+  #onUpdateRequest = (instanceId, client) => {
+    return async (reqId, updates) => {
       const hooks = this.#manager[kServerStateManagerGetUpdateHooks](this.className);
       const values = this.#parameters.getValues();
-      // make sur we don't propagate back to requester param that are marked as `acknowledge=false`
+      // Do not propagate back to the requester, params that are marked as `acknowledge=false`
       const acknowledgeFilter = this.#parameters.getParamListByDescriptor('acknowledge', false);
 
       let hookAborted = false;
@@ -185,8 +229,9 @@ class SharedStatePrivate {
           //
           // @note - instanceId correspond to unique remote state id
 
-          // - Apply acknowledge filter on `acknowledgedUpdates`
-          // - We don't need to apply the regular filter on update request, they are blocked client-side
+          // Apply acknowledge filter on `acknowledgedUpdates`
+          // Note that, We don't need to apply the whiteList / blackList filters
+          // for the requester, as they are blocked early on client-side
           const requesterFilteredUpdates = blackListFilterUpdates(acknowledgedUpdates, acknowledgeFilter);
 
           // propagate RESPONSE to the client that originates the request if not the server
@@ -203,11 +248,12 @@ class SharedStatePrivate {
 
           // propagate NOTIFICATION to all peer states except on server-side
           for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
-            const { client: peer, filter } = clientInfos;
+            const { client: peer, options } = clientInfos;
 
             if (instanceId !== peerInstanceId && peer.id !== -1) {
-              const filteredUpdates = whiteListFilterUpdates(acknowledgedUpdates, filter);
-              // propagate only if there something left after applying the white list filter
+              const filteredUpdates = applyFilters(acknowledgedUpdates, options);
+
+              // propagate only if there something left after applying the whiteList/blackList filters
               if (Object.keys(filteredUpdates).length > 0) {
                 peer.transport.emit(
                   `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
@@ -231,11 +277,12 @@ class SharedStatePrivate {
 
           // propagate NOTIFICATION to all peer states on the server-side
           for (let [peerInstanceId, clientInfos] of this.#attachedClients) {
-            const { client: peer, filter } = clientInfos;
+            const { client: peer, options } = clientInfos;
 
             if (instanceId !== peerInstanceId && peer.id === -1) {
-              const filteredUpdates = whiteListFilterUpdates(acknowledgedUpdates, filter);
-              // propagate only if there something left after applying the white list filter
+              const filteredUpdates = applyFilters(acknowledgedUpdates, options);
+
+              // propagate only if there something left after applying the whiteList/blackList filters
               if (Object.keys(filteredUpdates).length > 0) {
                 peer.transport.emit(
                   `${UPDATE_NOTIFICATION}-${this.id}-${peerInstanceId}`,
@@ -253,9 +300,9 @@ class SharedStatePrivate {
             client.transport.emit(`${UPDATE_ABORT}-${this.id}-${instanceId}`, reqId, requesterFilteredUpdates);
           }
         }
-      } else {
-        // @note - abort messages are only sent back to requester
-        // explicitly aborted by hook (return `null`), send back current values to requester
+      } else { // hookAborted === true
+        // when explicitly aborted by a hook (return `null`), we only send
+        // back the current values to the requester
         const currentValues = {};
 
         for (let name in updates) {
@@ -267,46 +314,36 @@ class SharedStatePrivate {
           client.transport.emit(`${UPDATE_ABORT}-${this.id}-${instanceId}`, reqId, requesterFilteredUpdates);
         }
       }
-    });
-
-    if (isOwner) {
-      // delete only if creator
-      client.transport.addListener(`${DELETE_REQUEST}-${this.id}-${instanceId}`, async reqId => {
-        // make sure hooks have been called when `delete()` fulfills
-        await this.#manager[kServerStateManagerDeletePrivateState](this);
-        // --------------------------------------------------------------------
-        // WARNING - MAKE SURE WE DON'T HAVE PROBLEM W/ THAT
-        // --------------------------------------------------------------------
-        // @todo - propagate server-side last, because if a subscription function sends a
-        // message to a client, network messages order are kept coherent
-        // this._subscriptions.forEach(func => func(updated));
-        for (let [instanceId, clientInfos] of this.#attachedClients) {
-          const attached = clientInfos.client;
-          this[kSharedStatePrivateDetachClient](instanceId, attached);
-
-          if (instanceId === this.#creatorInstanceId) {
-            attached.transport.emit(`${DELETE_RESPONSE}-${this.id}-${instanceId}`, reqId);
-          } else {
-            attached.transport.emit(`${DELETE_NOTIFICATION}-${this.id}-${instanceId}`);
-          }
-        }
-      });
-    } else {
-      // detach only if not creator
-      client.transport.addListener(`${DETACH_REQUEST}-${this.id}-${instanceId}`, (reqId) => {
-        this[kSharedStatePrivateDetachClient](instanceId, client);
-        client.transport.emit(`${DETACH_RESPONSE}-${this.id}-${instanceId}`, reqId);
-      });
+    };
+  };
+
+  #onDeleteRequest = async reqId => {
+    // make sure hooks have been called when `delete()` fulfills
+    await this.#manager[kServerStateManagerDeletePrivateState](this);
+    // --------------------------------------------------------------------
+    // WARNING - MAKE SURE WE DON'T HAVE PROBLEM W/ THAT
+    // --------------------------------------------------------------------
+    // @todo - propagate server-side last, because if a subscription function sends a
+    // message to a client, network messages order are kept coherent
+    // this._subscriptions.forEach(func => func(updated));
+    for (let [instanceId, clientInfos] of this.#attachedClients) {
+      const { client, isOwner } = clientInfos;
+      this[kSharedStatePrivateDetachClient](instanceId, client);
+
+      if (isOwner) {
+        client.transport.emit(`${DELETE_RESPONSE}-${this.id}-${instanceId}`, reqId);
+      } else {
+        client.transport.emit(`${DELETE_NOTIFICATION}-${this.id}-${instanceId}`);
+      }
     }
-  }
-
-  [kSharedStatePrivateDetachClient](instanceId, client) {
-    this.#attachedClients.delete(instanceId);
-    // delete listeners
-    client.transport.removeAllListeners(`${UPDATE_REQUEST}-${this.id}-${instanceId}`);
-    client.transport.removeAllListeners(`${DELETE_REQUEST}-${this.id}-${instanceId}`);
-    client.transport.removeAllListeners(`${DETACH_REQUEST}-${this.id}-${instanceId}`);
-  }
+  };
+
+  #onDetachRequest = (instanceId, client) => {
+    return reqId => {
+      this[kSharedStatePrivateDetachClient](instanceId, client);
+      client.transport.emit(`${DETACH_RESPONSE}-${this.id}-${instanceId}`, reqId);
+    };
+  };
 }
 
 export default SharedStatePrivate;

package/src/server/create-http-server.js

@@ -1,32 +1,26 @@
-import http from 'node:http';
-import https from 'node:https';
-import fs from 'node:fs';
 import {
   X509Certificate,
   createPrivateKey,
 } from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import os from 'node:os';
+import {
+  styleText,
+} from 'node:util';
 
-import pem from 'pem';
-import equal from 'fast-deep-equal';
-
-import logger from '../common/logger.js';
-
-/**
- * @private
- * @return {HttpServer|HttpsServer}
- */
-export async function createHttpServer(server) {
-  const serverConfig = server.config;
-
-  if (serverConfig.env.useHttps !== true) {
-    return http.createServer();
-  }
+import selfsigned from 'selfsigned';
 
+async function createHttpsServer(server) {
   // https is more tricky
-  const httpsInfos = serverConfig.env.httpsInfos;
+  const httpsInfos = server.config.env.httpsInfos;
   let useSelfSigned = false;
 
-  if (!httpsInfos || equal(httpsInfos, { cert: null, key: null })) {
+  if (!httpsInfos
+    || !fs.existsSync(httpsInfos.cert)
+    || !fs.existsSync(httpsInfos.key)
+  ) {
     useSelfSigned = true;
   }
 
@@ -77,7 +71,7 @@ export async function createHttpServer(server) {
 
       httpsServer = https.createServer({ key, cert });
     } catch (err) {
-      logger.error(`
+      console.error(`
 Invalid certificate files, please check your:
 - key file: ${httpsInfos.key}
 - cert file: ${httpsInfos.cert}
@@ -86,33 +80,23 @@ Invalid certificate files, please check your:
       throw err;
     }
   } else {
+
     // generate self signed certs or reused already existing ones
     let cert = await server.db.get('httpsCert');
     let key = await server.db.get('httpsKey');
 
     if (!cert || !key) {
       try {
-        const result = await new Promise((resolve, reject) => {
-          pem.createCertificate({ days: 1, selfSigned: true }, async (err, keys) => {
-            if (err) {
-              reject(err);
-              return;
-            }
-
-            resolve({
-              cert: keys.certificate,
-              key: keys.serviceKey,
-            });
-          });
-        });
+        const result = await selfsigned.generate(null);
 
         cert = result.cert;
-        key = result.key;
+        key = result.private;
+
         // store the generated certs to reuse on next start
-        await server.db.set('httpsCert', cert);
-        await server.db.set('httpsKey', key);
+        await server.db.set('httpsCert', cert); // -----BEGIN CERTIFICATE-----
+        await server.db.set('httpsKey', key); // -----BEGIN RSA PRIVATE KEY-----
       } catch (err) {
-        logger.error(err.stack);
+        console.error(err.stack);
         throw err;
       }
     }
@@ -121,7 +105,65 @@ Invalid certificate files, please check your:
     httpsServer = https.createServer({ cert, key });
   }
 
-  logger.httpsCertsInfos(httpsCertsInfos);
+  // Log certificate information, just be verbose
+  console.log(styleText('cyan', `https certificates infos`));
+
+  if (httpsCertsInfos.selfSigned) {
+    console.warn(styleText('yellow', `    -------------------------------------------`));
+    console.warn(styleText('yellow', `    > USING SELF-SIGNED CERTIFICATE.           `));
+    console.warn(styleText('yellow', `    users will face a unsafe web page warning  `));
+    console.warn(styleText('yellow', `    -------------------------------------------`));
+  } else {
+    console.log(`    valid from: ${httpsCertsInfos.validFrom}`);
+    console.log(`    valid to:   ${httpsCertsInfos.validTo}`);
+
+    if (!httpsCertsInfos.isValid) {
+      console.error(styleText('red', `    -------------------------------------------`));
+      console.error(styleText('red', `    > INVALID CERTIFICATE                      `));
+      console.error(styleText('red', `    i.e. you pretend to be safe but you are not`));
+      console.error(styleText('red', `    -------------------------------------------`));
+    } else {
+      if (httpsCertsInfos.daysRemaining < 5) {
+        console.log(styleText('red', `    > CERTIFICATE IS VALID... BUT ONLY ${httpsCertsInfos.daysRemaining} DAYS LEFT, PLEASE CONSIDER UPDATING YOUR CERTS!`));
+      } else if (httpsCertsInfos.daysRemaining < 15) {
+        console.log(styleText('yellow', `    > CERTIFICATE IS VALID - only ${httpsCertsInfos.daysRemaining} days left, be careful...`));
+      } else {
+        console.log(styleText('green', `    > CERTIFICATE IS VALID (${httpsCertsInfos.daysRemaining} days left)`));
+      }
+    }
+  }
 
   return httpsServer;
 }
+
+/**
+ * @private
+ * @return {HttpServer|HttpsServer}
+ */
+export async function createHttpServer(server) {
+  const serverConfig = server.config;
+
+  const httpServer = serverConfig.env.useHttps !== true
+    ? http.createServer()
+    : await createHttpsServer(server);
+
+  return httpServer;
+}
+
+export function logServerInfos(envConfig) {
+  const protocol = envConfig.useHttps ? 'https' : 'http';
+  const port = envConfig.port;
+  const interfaces = os.networkInterfaces();
+
+  console.log(styleText('cyan', `${protocol} server listening on`));
+
+  Object.keys(interfaces).forEach(dev => {
+    interfaces[dev].forEach(details => {
+      if (details.family === 'IPv4') {
+        console.log(`    ${protocol}://${details.address}:${styleText('green', `${port}`)}`);
+      }
+    });
+  });
+
+  console.log(`\n> press "${styleText('bold', 'Ctrl + C')}" to exit`);
+}

package/src/server/crypto.js

@@ -1,11 +1,10 @@
 import crypto from 'node:crypto';
-import { v4 as uuidv4 } from 'uuid';
 
 // adapted from https://dev.to/jobizil/encrypt-and-decrypt-data-in-nodejs-using-aes-256-cbc-2l6d
 // generate a new key and init vector each time the server restart, we don't need
 // any persistency here
-const secretKey = uuidv4();
-const secretIv = uuidv4();
+const secretKey = crypto.randomUUID();
+const secretIv = crypto.randomUUID();
 const encryptionMethod = 'aes-256-cbc';
 
 const key = crypto

package/types/client/Client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../../src/client/Client.js"],"names":[],"mappings":"AA6BA,+CAA2E;AAC3E,2DAAqG;;AAErG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAeE;;;OAGG;IACH,oBAHW,YAAY,EA+DtB;IAED;;;;OAIG;IACH,eAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,YAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,cAFU,YAAY,CAIrB;IAED;;;;;;;OAOG;IACH,UAFU,MAAM,CAIf;IAED;;;;;OAKG;IACH,YAFU,MAAM,CAIf;IAED;;;;;;;OAOG;IACH,aAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,eAFU,MAAM,GAAC,SAAS,CAIzB;IAED;;OAEG;IACH,iCAGC;IAED;;;;;OAKG;IACH,cAFU,YAAY,CAIrB;IAED;;;;;;;OAOG;IACH,sBAFU,oBAAoB,CAI7B;IAED;;;;;;;OAOG;IACH,8CAEC;IAED;;;;;;;OAOG;IACH,oBAFU,kBAAkB,CAI3B;IAED;;;;OAIG;IACH,cAFU,MAAM,GAAC,QAAQ,GAAC,SAAS,GAAC,SAAS,CAI5C;IAqBD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBA0DC;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAgBC;IAED;;;;;;;;;;;;;;;OAeG;IACH,sBAcC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,iBAPa,OAAO,CAAC,WAAW,CAAC,CAiBhC;IAED;;;;;OAKG;IACH,6CAGC;IA3VC,2CAAgD;;CA4VnD;yBAndM,mBAAmB;iCARnB,2BAA2B;gCACF,0BAA0B;+BAQ3B,yBAAyB"}
+{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../../src/client/Client.js"],"names":[],"mappings":"AAgCA,+CAA2E;AAC3E,2DAAqG;;AAErG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAeE;;;OAGG;IACH,oBAHW,YAAY,EA+DtB;IAED;;;;OAIG;IACH,eAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,YAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,cAFU,YAAY,CAIrB;IAED;;;;;;;OAOG;IACH,UAFU,MAAM,CAIf;IAED;;;;;OAKG;IACH,YAFU,MAAM,CAIf;IAED;;;;;;;OAOG;IACH,aAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,eAFU,MAAM,GAAC,SAAS,CAIzB;IAED;;OAEG;IACH,iCAGC;IAED;;;;;OAKG;IACH,cAFU,YAAY,CAIrB;IAED;;;;;;;OAOG;IACH,sBAFU,oBAAoB,CAI7B;IAED;;;;;;;OAOG;IACH,8CAEC;IAED;;;;;;;OAOG;IACH,oBAFU,kBAAkB,CAI3B;IAED;;;;OAIG;IACH,cAFU,MAAM,GAAC,QAAQ,GAAC,SAAS,GAAC,SAAS,CAI5C;IAqBD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBA0DC;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAgBC;IAED;;;;;;;;;;;;;;;OAeG;IACH,sBAcC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,iBAPa,OAAO,CAAC,WAAW,CAAC,CAiBhC;IAED;;;;;OAKG;IACH,6CAGC;IA3VC,2CAAgD;;CA4VnD;yBAtdM,mBAAmB;iCARnB,2BAA2B;gCACF,0BAA0B;+BAQ3B,yBAAyB"}

package/types/client/ClientSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientSocket.d.ts","sourceRoot":"","sources":["../../src/client/ClientSocket.js"],"names":[],"mappings":"AAaA,6CAAsE;;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAOE,wDAIC;IAED;;;;;;;OAOG;IACH,aA4HC;IAoCD;;;;;;OAMG;IACH,cAJW,MAAM,WACH,GAAC,EAAA,QAQd;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,4BAYhB;IAED;;;;;OAKG;IACH,wBAHW,MAAM,4BAYhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAQhB;IAED;;OAEG;IACH,cAEC;IApGD;;;;;;;;;OASG;IACH,2BAWC;;CAgFF"}
+{"version":3,"file":"ClientSocket.d.ts","sourceRoot":"","sources":["../../src/client/ClientSocket.js"],"names":[],"mappings":"AAYA,6CAAsE;;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAOE,wDAIC;IAED;;;;;;;OAOG;IACH,aA4HC;IAoCD;;;;;;OAMG;IACH,cAJW,MAAM,WACH,GAAC,EAAA,QAQd;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,4BAYhB;IAED;;;;;OAKG;IACH,wBAHW,MAAM,4BAYhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAQhB;IAED;;OAEG;IACH,cAEC;IApGD;;;;;;;;;OASG;IACH,2BAWC;;CAgFF"}

package/types/common/BaseStateManager.d.ts

@@ -1,5 +1,6 @@
 export const kStateManagerInit: unique symbol;
 export const kStateManagerDeleteState: unique symbol;
+export const kPendingSharedStateConstructionData: unique symbol;
 export const kStateManagerClient: unique symbol;
 export default BaseStateManager;
 /**
@@ -46,10 +47,6 @@ declare class BaseStateManager {
      * const classDescription = await client.stateManager.getClassDescription('my-class');
      */
     getClassDescription(className: SharedStateClassName): SharedStateClassDescription;
-    /**
-     * @deprecated Use {@link BaseStateManager#getClassDescription} instead.
-     */
-    getSchema(className: any): Promise<any>;
     /**
      * Create a {@link SharedState} instance from a registered class.
      *
@@ -90,26 +87,36 @@ declare class BaseStateManager {
      *
      * @overload
      * @param {SharedStateClassName} className - Name of the class.
-     * @param {string[]} filter - List of parameters of interest
+     * @param {Object} [options={}]
+     * @param {string[]} [options.whiteList] - White list of parameter names to track (as precedence over `blackList`).
+     * @param {string[]} [options.blackList] - Black list of parameter names to ignore.
      * @returns {Promise<SharedState>}
      *
      * @example
      * const state = await client.stateManager.attach('my-class', ['some-param']);
      */
-    attach(className: SharedStateClassName, filter: string[]): Promise<SharedState>;
+    attach(className: SharedStateClassName, options?: {
+        whiteList?: string[] | undefined;
+        blackList?: string[] | undefined;
+    } | undefined): Promise<SharedState>;
     /**
      * Attach to an existing {@link SharedState} instance.
      *
      * @overload
      * @param {SharedStateClassName} className - Name of the class.
      * @param {number} stateId - Id of the state
-     * @param {string[]} filter - List of parameters of interest
+     * @param {object} [options={}]
+     * @param {string[]} [options.whiteList] - White list of parameter names to track (as precedence over `blackList`).
+     * @param {string[]} [options.blackList] - Black list of parameter names to ignore.
      * @returns {Promise<SharedState>}
      *
      * @example
      * const state = await client.stateManager.attach('my-class', stateId, ['some-param']);
      */
-    attach(className: SharedStateClassName, stateId: number, filter: string[]): Promise<SharedState>;
+    attach(className: SharedStateClassName, stateId: number, options?: {
+        whiteList?: string[] | undefined;
+        blackList?: string[] | undefined;
+    } | undefined): Promise<SharedState>;
     /**
      * Observe all the {@link SharedState} instances that are created on the network.
      *
@@ -147,7 +154,7 @@ declare class BaseStateManager {
      * @param {stateManagerObserveCallback} callback - Function to execute when a
      *   new {@link SharedState} is created on the network.
      * @param {object} options - Options.
-     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     * @param {boolean} [options.excludeLocal=false] - If set to true, exclude states
      *   created by the same node from the collection.
      * @example
      * client.stateManager.observe(async (className, stateId) => {
@@ -157,7 +164,7 @@ declare class BaseStateManager {
      * }, { excludeLocal: true });
      */
     observe(callback: stateManagerObserveCallback, options: {
-        excludeLocal: boolean;
+        excludeLocal?: boolean | undefined;
     }): any;
     /**
      * Observe all the {@link SharedState} instances of given {@link SharedStateClassName}
@@ -169,7 +176,7 @@ declare class BaseStateManager {
      * @param {stateManagerObserveCallback} callback - Function to execute when a
      *   new {@link SharedState} is created on the network.
      * @param {object} options - Options.
-     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     * @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 (className, stateId) => {
@@ -177,7 +184,7 @@ declare class BaseStateManager {
      * }, { excludeLocal: true });
      */
     observe(className: SharedStateClassName, callback: stateManagerObserveCallback, options: {
-        excludeLocal: boolean;
+        excludeLocal?: boolean | undefined;
     }): any;
     /**
      * Returns a collection of all the states created from a given shared state class.
@@ -195,48 +202,28 @@ declare class BaseStateManager {
      *
      * @overload
      * @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(className, ['my-param']);
-     */
-    getCollection(className: SharedStateClassName, filter: SharedStateParameterName[]): Promise<SharedStateCollection>;
-    /**
-     * Returns a collection of all the states created from a given shared state class.
-     *
-     * @overload
-     * @param {SharedStateClassName} className - Name of the shared state class.
-     * @param {object} options - Options.
-     * @param {boolean} options.excludeLocal=false - If set to true, exclude states
+     * @param {object} [options={}] - Options.
+     * @param {boolean} [options.excludeLocal=false] - If set to true, exclude states
      *  created by the same node from the collection.
+     * @param {string[]} [options.whiteList] - White list of parameter names to track (as precedence over `blackList`).
+     * @param {string[]} [options.blackList] - Black list of parameter names to ignore.
      * @returns {Promise<SharedStateCollection>}
      *
      * @example
-     * const collection = await client.stateManager.getCollection(className, { excludeLocal: true });
+     * const collection = await client.stateManager.getCollection(className, {
+     *   blackList: ['my-param'],
+     *   excludeLocal: true,
+     * });
      */
-    getCollection(className: SharedStateClassName, options: {
-        excludeLocal: boolean;
-    }): Promise<SharedStateCollection>;
+    getCollection(className: SharedStateClassName, options?: {
+        excludeLocal?: boolean | undefined;
+        whiteList?: string[] | undefined;
+        blackList?: string[] | undefined;
+    } | undefined): Promise<SharedStateCollection>;
     /**
-     * Returns a collection of all the states created from a given shared state class.
-     *
-     * @overload
-     * @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.
-     * @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(className, ['my-param'], { excludeLocal: true });
+     * @deprecated Use {@link BaseStateManager#getClassDescription} instead.
      */
-    getCollection(className: SharedStateClassName, filter: SharedStateParameterName[], options: {
-        excludeLocal: boolean;
-    }): Promise<SharedStateCollection>;
+    getSchema(className: any): Promise<any>;
     /** @private */
     private [kStateManagerDeleteState];
     /**

package/types/common/BaseStateManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseStateManager.d.ts","sourceRoot":"","sources":["../../src/common/BaseStateManager.js"],"names":[],"mappings":"AA2BA,8CAAyE;AACzE,qDAAwF;AAExF,gDAA6E;;;;;;;;;;;AAE7E;;;;;;;;GAQG;AACH;;;;;GAKG;AAEH,eAAe;AACf;IAuLE;;;;;;OAMG;IACH,2CAHW,GAAC,QAKX;IAED;;;;;;;;OAQG;IACH,+BANW,oBAAoB,GAEnB,2BAA2B,CAatC;IAED;;OAEG;IACH,wCAGC;IAED;;;;;;;;OAQG;IACH,kBANW,oBAAoB;;QAElB,OAAO,CAAC,WAAW,CAAC,CAahC;;;;;;;;;;;IAKE,kBACQ,oBAAoB,GAClB,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;IAMA,kBACQ,oBAAoB,WACpB,MAAM,GACJ,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;IAMA,kBACQ,oBAAoB,UACpB,MAAM,EAAE,GACN,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;;IAMA,kBACQ,oBAAoB,WACpB,MAAM,UACN,MAAM,EAAE,GACN,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;;;IAsEA,kBACQ,2BAA2B,OAEnC;;;;;;;;;;;;;;;IAWA,mBACQ,oBAAoB,YAEpB,2BAA2B,OAEnC;;;;;;;;;;;;;;;;;;IASA,kBACQ,2BAA2B,WAGnC;QAAyB,YAAY,EAA7B,OAAO;KAEf,OAAA;;;;;;;;;;;;;;;;;;IAWA,mBACQ,oBAAoB,YAEpB,2BAA2B,WAGnC;QAAyB,YAAY,EAA7B,OAAO;KAEf,OAAA;;;;;;;;;;;IAwJA,yBACQ,oBAAoB,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAExC;;;;;;;;;;;;;IAMA,yBACQ,oBAAoB,UACpB,wBAAwB,EAAE,GAExB,OAAO,CAAC,qBAAqB,CAAC,CAExC;;;;;;;;;;;;;;IAMA,yBACQ,oBAAoB,WAE5B;QAAyB,YAAY,EAA7B,OAAO;KAEf,GAAU,OAAO,CAAC,qBAAqB,CAAC,CAExC;;;;;;;;;;;;;;;;IAMA,yBACQ,oBAAoB,UACpB,wBAAwB,EAAE,WAGlC;QAAyB,YAAY,EAA7B,OAAO;KAEf,GAAU,OAAO,CAAC,qBAAqB,CAAC,CAExC;IA7jBH,eAAe;IACf,mCAEC;IAED;;;;;;;OAOG;IACH,4BA2IC;IA5KC,eAAe;IACf,8BAAgC;;CAupBnC;wBAjtBuB,kBAAkB;kCAGnC,4BAA4B"}
+{"version":3,"file":"BaseStateManager.d.ts","sourceRoot":"","sources":["../../src/common/BaseStateManager.js"],"names":[],"mappings":"AA+BA,8CAAyE;AACzE,qDAAwF;AACxF,gEAA6H;AAE7H,gDAA6E;;;;;;;;;;;AAG7E;;;;;;;;GAQG;AACH;;;;;GAKG;AAEH,eAAe;AACf;IA6EE;;;;;;OAMG;IACH,2CAHW,GAAC,QAKX;IAED;;;;;;;;OAQG;IACH,+BANW,oBAAoB,GAEnB,2BAA2B,CAatC;IAYD;;;;;;;;OAQG;IACH,kBANW,oBAAoB;;QAElB,OAAO,CAAC,WAAW,CAAC,CAahC;;;;;;;;;;;IAyBE,kBACQ,oBAAoB,GAClB,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;IAMA,kBACQ,oBAAoB,WACpB,MAAM,GACJ,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;;;IAMA,kBACQ,oBAAoB;;;oBAIlB,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;;;;IAMA,kBACQ,oBAAoB,WACpB,MAAM;;;oBAIJ,OAAO,CAAC,WAAW,CAAC,CAE9B;;;;;;;;;;;;;;IAgHA,kBACQ,2BAA2B,OAEnC;;;;;;;;;;;;;;;IAWA,mBACQ,oBAAoB,YAEpB,2BAA2B,OAEnC;;;;;;;;;;;;;;;;;;IASA,kBACQ,2BAA2B,WAGnC;QAA0B,YAAY;KAEtC,OAAA;;;;;;;;;;;;;;;;;;IAWA,mBACQ,oBAAoB,YAEpB,2BAA2B,WAGnC;QAA0B,YAAY;KAEtC,OAAA;;;;;;;;;;;IA4NA,yBACQ,oBAAoB,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAExC;;;;;;;;;;;;;;;;;;;IAMA,yBACQ,oBAAoB;;;;oBAMlB,OAAO,CAAC,qBAAqB,CAAC,CAExC;IAqFH;;OAEG;IACH,wCAGC;IA5qBD,eAAe;IACf,mCAEC;IAED;;;;;;;OAOG;IACH,4BAyBC;IA3CC,eAAe;IACf,8BAAgC;;CAirBnC;wBA5uBuB,kBAAkB;kCAGnC,4BAA4B"}