feat(Shard): shard-specific broadcastEval/fetchClientValues + shard Id util (#4991)

src/sharding/Shard.js

@@ -334,18 +334,20 @@ class Shard extends EventEmitter {
 
       // Shard is requesting a property fetch
       if (message._sFetchProp) {
-        this.manager.fetchClientValues(message._sFetchProp).then(
-          results => this.send({ _sFetchProp: message._sFetchProp, _result: results }),
-          err => this.send({ _sFetchProp: message._sFetchProp, _error: Util.makePlainError(err) }),
+        const resp = { _sFetchProp: message._sFetchProp, _sFetchPropShard: message._sFetchPropShard };
+        this.manager.fetchClientValues(message._sFetchProp, message._sFetchPropShard).then(
+          results => this.send({ ...resp, _result: results }),
+          err => this.send({ ...resp, _error: Util.makePlainError(err) }),
         );
         return;
       }
 
       // Shard is requesting an eval broadcast
       if (message._sEval) {
-        this.manager.broadcastEval(message._sEval).then(
-          results => this.send({ _sEval: message._sEval, _result: results }),
-          err => this.send({ _sEval: message._sEval, _error: Util.makePlainError(err) }),
+        const resp = { _sEval: message._sEval, _sEvalShard: message._sEvalShard };
+        this.manager.broadcastEval(message._sEval, message._sEvalShard).then(
+          results => this.send({ ...resp, _result: results }),
+          err => this.send({ ...resp, _error: Util.makePlainError(err) }),
         );
         return;
       }

src/sharding/ShardClientUtil.js

@@ -96,28 +96,29 @@ class ShardClientUtil {
   }
 
   /**
-   * Fetches a client property value of each shard.
+   * Fetches a client property value of each shard, or a given shard.
    * @param {string} prop Name of the client property to get, using periods for nesting
-   * @returns {Promise<Array<*>>}
+   * @param {number} [shard] Shard to fetch property from, all if undefined
+   * @returns {Promise<*>|Promise<Array<*>>}
    * @example
    * client.shard.fetchClientValues('guilds.cache.size')
    *   .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`))
    *   .catch(console.error);
    * @see {@link ShardingManager#fetchClientValues}
    */
-  fetchClientValues(prop) {
+  fetchClientValues(prop, shard) {
     return new Promise((resolve, reject) => {
       const parent = this.parentPort || process;
 
       const listener = message => {
-        if (!message || message._sFetchProp !== prop) return;
+        if (!message || message._sFetchProp !== prop || message._sFetchPropShard !== shard) return;
         parent.removeListener('message', listener);
         if (!message._error) resolve(message._result);
         else reject(Util.makeError(message._error));
       };
       parent.on('message', listener);
 
-      this.send({ _sFetchProp: prop }).catch(err => {
+      this.send({ _sFetchProp: prop, _sFetchPropShard: shard }).catch(err => {
         parent.removeListener('message', listener);
         reject(err);
       });
@@ -125,29 +126,30 @@ class ShardClientUtil {
   }
 
   /**
-   * Evaluates a script or function on all shards, in the context of the {@link Client}s.
+   * Evaluates a script or function on all shards, or a given shard, in the context of the {@link Client}s.
    * @param {string|Function} script JavaScript to run on each shard
-   * @returns {Promise<Array<*>>} Results of the script execution
+   * @param {number} [shard] Shard to run script on, all if undefined
+   * @returns {Promise<*>|Promise<Array<*>>} Results of the script execution
    * @example
    * client.shard.broadcastEval('this.guilds.cache.size')
    *   .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`))
    *   .catch(console.error);
    * @see {@link ShardingManager#broadcastEval}
    */
-  broadcastEval(script) {
+  broadcastEval(script, shard) {
     return new Promise((resolve, reject) => {
       const parent = this.parentPort || process;
       script = typeof script === 'function' ? `(${script})(this)` : script;
 
       const listener = message => {
-        if (!message || message._sEval !== script) return;
+        if (!message || message._sEval !== script || message._sEvalShard !== shard) return;
         parent.removeListener('message', listener);
         if (!message._error) resolve(message._result);
         else reject(Util.makeError(message._error));
       };
       parent.on('message', listener);
 
-      this.send({ _sEval: script }).catch(err => {
+      this.send({ _sEval: script, _sEvalShard: shard }).catch(err => {
         parent.removeListener('message', listener);
         reject(err);
       });
@@ -224,6 +226,18 @@ class ShardClientUtil {
     }
     return this._singleton;
   }
+
+  /**
+   * Get the shard ID for a given guild ID.
+   * @param {Snowflake} guildID Snowflake guild ID to get shard ID for
+   * @param {number} shardCount Number of shards
+   * @returns {number}
+   */
+  static shardIDForGuildID(guildID, shardCount) {
+    const shard = Number(BigInt(guildID) >> 22n) % shardCount;
+    if (shard < 0) throw new Error('SHARDING_SHARD_MISCALCULATION', shard, guildID, shardCount);
+    return shard;
+  }
 }
 
 module.exports = ShardClientUtil;

src/sharding/ShardingManager.js

@@ -222,30 +222,48 @@ class ShardingManager extends EventEmitter {
   }
 
   /**
-   * Evaluates a script on all shards, in the context of the {@link Client}s.
+   * Evaluates a script on all shards, or a given shard, in the context of the {@link Client}s.
    * @param {string} script JavaScript to run on each shard
-   * @returns {Promise<Array<*>>} Results of the script execution
+   * @param {number} [shard] Shard to run on, all if undefined
+   * @returns {Promise<*>|Promise<Array<*>>} Results of the script execution
    */
-  broadcastEval(script) {
-    const promises = [];
-    for (const shard of this.shards.values()) promises.push(shard.eval(script));
-    return Promise.all(promises);
+  broadcastEval(script, shard) {
+    return this._performOnShards('eval', [script], shard);
   }
 
   /**
-   * Fetches a client property value of each shard.
+   * Fetches a client property value of each shard, or a given shard.
    * @param {string} prop Name of the client property to get, using periods for nesting
-   * @returns {Promise<Array<*>>}
+   * @param {number} [shard] Shard to fetch property from, all if undefined
+   * @returns {Promise<*>|Promise<Array<*>>}
    * @example
    * manager.fetchClientValues('guilds.cache.size')
    *   .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`))
    *   .catch(console.error);
    */
-  fetchClientValues(prop) {
+  fetchClientValues(prop, shard) {
+    return this._performOnShards('fetchClientValue', [prop], shard);
+  }
+
+  /**
+   * Runs a method with given arguments on all shards, or a given shard.
+   * @param {string} method Method name to run on each shard
+   * @param {Array<*>} args Arguments to pass through to the method call
+   * @param {number} [shard] Shard to run on, all if undefined
+   * @returns {Promise<*>|Promise<Array<*>>} Results of the method execution
+   * @private
+   */
+  _performOnShards(method, args, shard) {
     if (this.shards.size === 0) return Promise.reject(new Error('SHARDING_NO_SHARDS'));
     if (this.shards.size !== this.shardList.length) return Promise.reject(new Error('SHARDING_IN_PROCESS'));
+
+    if (typeof shard === 'number') {
+      if (this.shards.has(shard)) return this.shards.get(shard)[method](...args);
+      return Promise.reject(new Error('SHARDING_SHARD_NOT_FOUND', shard));
+    }
+
     const promises = [];
-    for (const shard of this.shards.values()) promises.push(shard.fetchClientValue(prop));
+    for (const sh of this.shards.values()) promises.push(sh[method](...args));
     return Promise.all(promises);
   }