mongodb 4.1.3 → 4.2.2

package/src/operations/list_collections.ts

@@ -15,6 +15,8 @@ const LIST_COLLECTIONS_WIRE_VERSION = 3;
 export interface ListCollectionsOptions extends CommandOperationOptions {
   /** Since 4.0: If true, will only return the collection name in the response, and will omit additional info */
   nameOnly?: boolean;
+  /** Since 4.0: If true and nameOnly is true, allows a user without the required privilege (i.e. listCollections action on the database) to run the command when access control is enforced. */
+  authorizedCollections?: boolean;
   /** The batchSize for the returned command cursor or if pre 2.8 the systems batch collection */
   batchSize?: number;
 }
@@ -25,6 +27,7 @@ export class ListCollectionsOperation extends CommandOperation<string[]> {
   db: Db;
   filter: Document;
   nameOnly: boolean;
+  authorizedCollections: boolean;
   batchSize?: number;
 
   constructor(db: Db, filter: Document, options?: ListCollectionsOptions) {
@@ -34,6 +37,7 @@ export class ListCollectionsOperation extends CommandOperation<string[]> {
     this.db = db;
     this.filter = filter;
     this.nameOnly = !!this.options.nameOnly;
+    this.authorizedCollections = !!this.options.authorizedCollections;
 
     if (typeof this.options.batchSize === 'number') {
       this.batchSize = this.options.batchSize;
@@ -90,14 +94,18 @@ export class ListCollectionsOperation extends CommandOperation<string[]> {
       return;
     }
 
-    const command = {
+    return super.executeCommand(server, session, this.generateCommand(), callback);
+  }
+
+  /* This is here for the purpose of unit testing the final command that gets sent. */
+  generateCommand(): Document {
+    return {
       listCollections: 1,
       filter: this.filter,
       cursor: this.batchSize ? { batchSize: this.batchSize } : {},
-      nameOnly: this.nameOnly
+      nameOnly: this.nameOnly,
+      authorizedCollections: this.authorizedCollections
     };
-
-    return super.executeCommand(server, session, command, callback);
   }
 }
 

package/src/operations/operation.ts

@@ -10,7 +10,8 @@ export const Aspect = {
   RETRYABLE: Symbol('RETRYABLE'),
   EXPLAINABLE: Symbol('EXPLAINABLE'),
   SKIP_COLLATION: Symbol('SKIP_COLLATION'),
-  CURSOR_CREATING: Symbol('CURSOR_CREATING')
+  CURSOR_CREATING: Symbol('CURSOR_CREATING'),
+  CURSOR_ITERATING: Symbol('CURSOR_ITERATING')
 } as const;
 
 /** @public */
@@ -31,6 +32,7 @@ export interface OperationOptions extends BSONSerializeOptions {
 
   /** @internal Hints to `executeOperation` that this operation should not unpin on an ended transaction */
   bypassPinningCheck?: boolean;
+  omitReadPreference?: boolean;
 }
 
 /** @internal */
@@ -49,6 +51,7 @@ export abstract class AbstractOperation<TResult = any> {
   readPreference: ReadPreference;
   server!: Server;
   bypassPinningCheck: boolean;
+  trySecondaryWrite: boolean;
 
   // BSON serialization options
   bsonOptions?: BSONSerializeOptions;
@@ -72,6 +75,7 @@ export abstract class AbstractOperation<TResult = any> {
 
     this.options = options;
     this.bypassPinningCheck = !!options.bypassPinningCheck;
+    this.trySecondaryWrite = false;
   }
 
   abstract execute(server: Server, session: ClientSession, callback: Callback<TResult>): void;

package/src/read_preference.ts

@@ -156,7 +156,10 @@ export class ReadPreference {
     }
 
     if (typeof readPreference === 'string') {
-      return new ReadPreference(readPreference as ReadPreferenceMode, readPreferenceTags);
+      return new ReadPreference(readPreference as ReadPreferenceMode, readPreferenceTags, {
+        maxStalenessSeconds: options.maxStalenessSeconds,
+        hedge: options.hedge
+      });
     } else if (!(readPreference instanceof ReadPreference) && typeof readPreference === 'object') {
       const mode = readPreference.mode || readPreference.preference;
       if (mode && typeof mode === 'string') {

package/src/sdam/server.ts

@@ -299,6 +299,14 @@ export class Server extends TypedEventEmitter<ServerEvents> {
     // Clone the options
     const finalOptions = Object.assign({}, options, { wireProtocolCommand: false });
 
+    // There are cases where we need to flag the read preference not to get sent in
+    // the command, such as pre-5.0 servers attempting to perform an aggregate write
+    // with a non-primary read preference. In this case the effective read preference
+    // (primary) is not the same as the provided and must be removed completely.
+    if (finalOptions.omitReadPreference) {
+      delete finalOptions.readPreference;
+    }
+
     // error if collation not supported
     if (collationNotSupported(this, cmd)) {
       callback(new MongoCompatibilityError(`Server ${this.name} does not support collation`));

package/src/sdam/server_selection.ts

@@ -8,6 +8,9 @@ import type { ServerDescription, TagSet } from './server_description';
 const IDLE_WRITE_PERIOD = 10000;
 const SMALLEST_MAX_STALENESS_SECONDS = 90;
 
+//  Minimum version to try writes on secondaries.
+export const MIN_SECONDARY_WRITE_WIRE_VERSION = 13;
+
 /** @public */
 export type ServerSelector = (
   topologyDescription: TopologyDescription,
@@ -28,6 +31,46 @@ export function writableServerSelector(): ServerSelector {
     );
 }
 
+/**
+ * The purpose of this selector is to select the same server, only
+ * if it is in a state that it can have commands sent to it.
+ */
+export function sameServerSelector(description?: ServerDescription): ServerSelector {
+  return (
+    topologyDescription: TopologyDescription,
+    servers: ServerDescription[]
+  ): ServerDescription[] => {
+    if (!description) return [];
+    // Filter the servers to match the provided description only if
+    // the type is not unknown.
+    return servers.filter(sd => {
+      return sd.address === description.address && sd.type !== ServerType.Unknown;
+    });
+  };
+}
+
+/**
+ * Returns a server selector that uses a read preference to select a
+ * server potentially for a write on a secondary.
+ */
+export function secondaryWritableServerSelector(
+  wireVersion?: number,
+  readPreference?: ReadPreference
+): ServerSelector {
+  // If server version < 5.0, read preference always primary.
+  // If server version >= 5.0...
+  // - If read preference is supplied, use that.
+  // - If no read preference is supplied, use primary.
+  if (
+    !readPreference ||
+    !wireVersion ||
+    (wireVersion && wireVersion < MIN_SECONDARY_WRITE_WIRE_VERSION)
+  ) {
+    return readPreferenceServerSelector(ReadPreference.primary);
+  }
+  return readPreferenceServerSelector(readPreference);
+}
+
 /**
  * Reduces the passed in array of servers by the rules of the "Max Staleness" specification
  * found here: https://github.com/mongodb/specifications/blob/master/source/max-staleness/max-staleness.rst

package/src/sdam/srv_polling.ts

@@ -29,18 +29,15 @@ export class SrvPollingEvent {
     this.srvRecords = srvRecords;
   }
 
-  addresses(): Map<string, HostAddress> {
-    return new Map(
-      this.srvRecords.map(record => {
-        const host = new HostAddress(`${record.name}:${record.port}`);
-        return [host.toString(), host];
-      })
-    );
+  hostnames(): Set<string> {
+    return new Set(this.srvRecords.map(r => HostAddress.fromSrvRecord(r).toString()));
   }
 }
 
 /** @internal */
 export interface SrvPollerOptions extends LoggerOptions {
+  srvServiceName: string;
+  srvMaxHosts: number;
   srvHost: string;
   heartbeatFrequencyMS: number;
 }
@@ -58,6 +55,8 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
   logger: Logger;
   haMode: boolean;
   generation: number;
+  srvMaxHosts: number;
+  srvServiceName: string;
   _timeout?: NodeJS.Timeout;
 
   /** @event */
@@ -71,8 +70,10 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
     }
 
     this.srvHost = options.srvHost;
+    this.srvMaxHosts = options.srvMaxHosts ?? 0;
+    this.srvServiceName = options.srvServiceName ?? 'mongodb';
     this.rescanSrvIntervalMS = 60000;
-    this.heartbeatFrequencyMS = options.heartbeatFrequencyMS || 10000;
+    this.heartbeatFrequencyMS = options.heartbeatFrequencyMS ?? 10000;
     this.logger = new Logger('srvPoller', options);
 
     this.haMode = false;
@@ -82,7 +83,7 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
   }
 
   get srvAddress(): string {
-    return `_mongodb._tcp.${this.srvHost}`;
+    return `_${this.srvServiceName}._tcp.${this.srvHost}`;
   }
 
   get intervalMS(): number {
@@ -143,13 +144,13 @@ export class SrvPoller extends TypedEventEmitter<SrvPollerEvents> {
       }
 
       const finalAddresses: dns.SrvRecord[] = [];
-      srvRecords.forEach((record: dns.SrvRecord) => {
+      for (const record of srvRecords) {
         if (matchesParentDomain(record.name, this.srvHost)) {
           finalAddresses.push(record);
         } else {
           this.parentDomainMismatch(record);
         }
-      });
+      }
 
       if (!finalAddresses.length) {
         this.failure('No valid addresses found at host');

package/src/sdam/topology.ts

@@ -27,7 +27,8 @@ import {
   HostAddress,
   ns,
   emitWarning,
-  EventEmitterWithState
+  EventEmitterWithState,
+  shuffle
 } from '../utils';
 import {
   TopologyType,
@@ -140,6 +141,8 @@ export interface TopologyPrivate {
 
 /** @public */
 export interface TopologyOptions extends BSONSerializeOptions, ServerOptions {
+  srvMaxHosts: number;
+  srvServiceName: string;
   hosts: HostAddress[];
   retryWrites: boolean;
   retryReads: boolean;
@@ -182,8 +185,8 @@ export type TopologyEvents = {
   topologyOpening(event: TopologyOpeningEvent): void;
   topologyDescriptionChanged(event: TopologyDescriptionChangedEvent): void;
   error(error: Error): void;
-  /** TODO(NODE-3273) - remove error @internal */
-  open(error: undefined, topology: Topology): void;
+  /** @internal */
+  open(topology: Topology): void;
   close(): void;
   timeout(): void;
 } & Omit<ServerEvents, 'connect'> &
@@ -290,8 +293,15 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
     const topologyType = topologyTypeFromOptions(options);
     const topologyId = globalTopologyCounter++;
 
+    const selectedHosts =
+      options.srvMaxHosts == null ||
+      options.srvMaxHosts === 0 ||
+      options.srvMaxHosts >= seedlist.length
+        ? seedlist
+        : shuffle(seedlist, options.srvMaxHosts);
+
     const serverDescriptions = new Map();
-    for (const hostAddress of seedlist) {
+    for (const hostAddress of selectedHosts) {
       serverDescriptions.set(hostAddress.toString(), new ServerDescription(hostAddress));
     }
 
@@ -339,7 +349,9 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
         options.srvPoller ??
         new SrvPoller({
           heartbeatFrequencyMS: this.s.heartbeatFrequencyMS,
-          srvHost: options.srvHost
+          srvHost: options.srvHost,
+          srvMaxHosts: options.srvMaxHosts,
+          srvServiceName: options.srvServiceName
         });
 
       this.on(Topology.TOPOLOGY_DESCRIPTION_CHANGED, this.s.detectShardedTopology);
@@ -363,7 +375,10 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
 
   private detectSrvRecords(ev: SrvPollingEvent) {
     const previousTopologyDescription = this.s.description;
-    this.s.description = this.s.description.updateFromSrvPollingEvent(ev);
+    this.s.description = this.s.description.updateFromSrvPollingEvent(
+      ev,
+      this.s.options.srvMaxHosts
+    );
     if (this.s.description === previousTopologyDescription) {
       // Nothing changed, so return
       return;
@@ -456,8 +471,7 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
           }
 
           stateTransition(this, STATE_CONNECTED);
-          // TODO(NODE-3273) - remove err
-          this.emit(Topology.OPEN, err, this);
+          this.emit(Topology.OPEN, this);
           this.emit(Topology.CONNECT, this);
 
           if (typeof callback === 'function') callback(undefined, this);
@@ -467,8 +481,7 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
       }
 
       stateTransition(this, STATE_CONNECTED);
-      // TODO(NODE-3273) - remove err
-      this.emit(Topology.OPEN, err, this);
+      this.emit(Topology.OPEN, this);
       this.emit(Topology.CONNECT, this);
 
       if (typeof callback === 'function') callback(undefined, this);
@@ -797,6 +810,10 @@ export class Topology extends TypedEventEmitter<TopologyEvents> {
     return result;
   }
 
+  get commonWireVersion(): number | undefined {
+    return this.description.commonWireVersion;
+  }
+
   get logicalSessionTimeoutMinutes(): number | undefined {
     return this.description.logicalSessionTimeoutMinutes;
   }

package/src/sdam/topology_description.ts

@@ -4,6 +4,7 @@ import { TopologyType, ServerType } from './common';
 import type { ObjectId, Document } from '../bson';
 import type { SrvPollingEvent } from './srv_polling';
 import { MongoError, MongoRuntimeError } from '../error';
+import { shuffle } from '../utils';
 
 // constants related to compatibility checks
 const MIN_SUPPORTED_SERVER_VERSION = WIRE_CONSTANTS.MIN_SUPPORTED_SERVER_VERSION;
@@ -139,23 +140,46 @@ export class TopologyDescription {
    * Returns a new TopologyDescription based on the SrvPollingEvent
    * @internal
    */
-  updateFromSrvPollingEvent(ev: SrvPollingEvent): TopologyDescription {
-    const newAddresses = ev.addresses();
-    const serverDescriptions = new Map(this.servers);
-    for (const address of this.servers.keys()) {
-      if (newAddresses.has(address)) {
-        newAddresses.delete(address);
-      } else {
-        serverDescriptions.delete(address);
+  updateFromSrvPollingEvent(ev: SrvPollingEvent, srvMaxHosts = 0): TopologyDescription {
+    /** The SRV addresses defines the set of addresses we should be using */
+    const incomingHostnames = ev.hostnames();
+    const currentHostnames = new Set(this.servers.keys());
+
+    const hostnamesToAdd = new Set<string>(incomingHostnames);
+    const hostnamesToRemove = new Set<string>();
+    for (const hostname of currentHostnames) {
+      // filter hostnamesToAdd (made from incomingHostnames) down to what is *not* present in currentHostnames
+      hostnamesToAdd.delete(hostname);
+      if (!incomingHostnames.has(hostname)) {
+        // If the SRV Records no longer include this hostname
+        // we have to stop using it
+        hostnamesToRemove.add(hostname);
       }
     }
 
-    if (serverDescriptions.size === this.servers.size && newAddresses.size === 0) {
+    if (hostnamesToAdd.size === 0 && hostnamesToRemove.size === 0) {
+      // No new hosts to add and none to remove
       return this;
     }
 
-    for (const [address, host] of newAddresses) {
-      serverDescriptions.set(address, new ServerDescription(host));
+    const serverDescriptions = new Map(this.servers);
+    for (const removedHost of hostnamesToRemove) {
+      serverDescriptions.delete(removedHost);
+    }
+
+    if (hostnamesToAdd.size > 0) {
+      if (srvMaxHosts === 0) {
+        // Add all!
+        for (const hostToAdd of hostnamesToAdd) {
+          serverDescriptions.set(hostToAdd, new ServerDescription(hostToAdd));
+        }
+      } else if (serverDescriptions.size < srvMaxHosts) {
+        // Add only the amount needed to get us back to srvMaxHosts
+        const selectedHosts = shuffle(hostnamesToAdd, srvMaxHosts - serverDescriptions.size);
+        for (const selectedHostToAdd of selectedHosts) {
+          serverDescriptions.set(selectedHostToAdd, new ServerDescription(selectedHostToAdd));
+        }
+      }
     }
 
     return new TopologyDescription(

package/src/sessions.ts

@@ -8,6 +8,7 @@ import {
   MongoError,
   MongoInvalidArgumentError,
   isRetryableError,
+  isRetryableEndTransactionError,
   MongoCompatibilityError,
   MongoNetworkError,
   MongoWriteConcernError,
@@ -767,7 +768,7 @@ function endTransaction(session: ClientSession, commandName: string, callback: C
         session.unpin();
       }
 
-      if (err && isRetryableError(err as MongoError)) {
+      if (err && isRetryableEndTransactionError(err as MongoError)) {
         // SPEC-1185: apply majority write concern when retrying commitTransaction
         if (command.commitTransaction) {
           // per txns spec, must unpin session in this case

package/src/transactions.ts

@@ -1,6 +1,6 @@
 import { ReadPreference } from './read_preference';
 import { MongoRuntimeError, MongoTransactionError } from './error';
-import { ReadConcern } from './read_concern';
+import { ReadConcern, ReadConcernLike } from './read_concern';
 import { WriteConcern } from './write_concern';
 import type { Server } from './sdam/server';
 import type { CommandOperationOptions } from './operations/command';
@@ -63,7 +63,7 @@ const COMMITTED_STATES: Set<TxnState> = new Set([
 export interface TransactionOptions extends CommandOperationOptions {
   // TODO(NODE-3344): These options use the proper class forms of these settings, it should accept the basic enum values too
   /** A default read concern for commands in this transaction */
-  readConcern?: ReadConcern;
+  readConcern?: ReadConcernLike;
   /** A default writeConcern for commands in this transaction */
   writeConcern?: WriteConcern;
   /** A default read preference for commands in this transaction */

package/src/utils.ts

@@ -28,6 +28,7 @@ import type { CommandOperationOptions, OperationParent } from './operations/comm
 import { ReadPreference } from './read_preference';
 import { URL } from 'url';
 import { MAX_SUPPORTED_WIRE_VERSION } from './cmap/wire_protocol/constants';
+import type { SrvRecord } from 'dns';
 
 /**
  * MongoDB Driver style callback
@@ -41,23 +42,6 @@ export const MAX_JS_INT = Number.MAX_SAFE_INTEGER + 1;
 
 export type AnyOptions = Document;
 
-/**
- * Add a readonly enumerable property.
- * @internal
- */
-export function getSingleProperty(
-  obj: AnyOptions,
-  name: string | number | symbol,
-  value: unknown
-): void {
-  Object.defineProperty(obj, name, {
-    enumerable: true,
-    get() {
-      return value;
-    }
-  });
-}
-
 /**
  * Throws if collectionName is not a valid mongodb collection namespace.
  * @internal
@@ -185,17 +169,6 @@ export function isObject(arg: unknown): arg is object {
   return '[object Object]' === Object.prototype.toString.call(arg);
 }
 
-/** @internal */
-export function decorateCommand(command: Document, options: Document, exclude: string[]): Document {
-  for (const name in options) {
-    if (!exclude.includes(name)) {
-      command[name] = options[name];
-    }
-  }
-
-  return command;
-}
-
 /** @internal */
 export function mergeOptions<T, S>(target: T, source: S): T & S {
   return { ...target, ...source };
@@ -657,11 +630,6 @@ export function databaseNamespace(ns: string): string {
   return ns.split('.')[0];
 }
 
-/** @internal */
-export function collectionNamespace(ns: string): string {
-  return ns.split('.').slice(1).join('.');
-}
-
 /**
  * Synchronously Generate a UUIDv4
  * @internal
@@ -987,7 +955,7 @@ export function makeInterruptibleAsyncInterval(
 ): InterruptibleAsyncInterval {
   let timerId: NodeJS.Timeout | undefined;
   let lastCallTime: number;
-  let lastWakeTime: number;
+  let cannotBeExpedited = false;
   let stopped = false;
 
   options = options ?? {};
@@ -998,10 +966,8 @@ export function makeInterruptibleAsyncInterval(
 
   function wake() {
     const currentTime = clock();
-    const timeSinceLastWake = currentTime - lastWakeTime;
-    const timeSinceLastCall = currentTime - lastCallTime;
-    const timeUntilNextCall = interval - timeSinceLastCall;
-    lastWakeTime = currentTime;
+    const nextScheduledCallTime = lastCallTime + interval;
+    const timeUntilNextCall = nextScheduledCallTime - currentTime;
 
     // For the streaming protocol: there is nothing obviously stopping this
     // interval from being woken up again while we are waiting "infinitely"
@@ -1009,8 +975,17 @@ export function makeInterruptibleAsyncInterval(
     // never completes, the `timeUntilNextCall` will continue to grow
     // negatively unbounded, so it will never trigger a reschedule here.
 
+    // This is possible in virtualized environments like AWS Lambda where our
+    // clock is unreliable. In these cases the timer is "running" but never
+    // actually completes, so we want to execute immediately and then attempt
+    // to reschedule.
+    if (timeUntilNextCall < 0) {
+      executeAndReschedule();
+      return;
+    }
+
     // debounce multiple calls to wake within the `minInterval`
-    if (timeSinceLastWake < minInterval) {
+    if (cannotBeExpedited) {
       return;
     }
 
@@ -1018,14 +993,7 @@ export function makeInterruptibleAsyncInterval(
     // faster than the `minInterval`
     if (timeUntilNextCall > minInterval) {
       reschedule(minInterval);
-    }
-
-    // This is possible in virtualized environments like AWS Lambda where our
-    // clock is unreliable. In these cases the timer is "running" but never
-    // actually completes, so we want to execute immediately and then attempt
-    // to reschedule.
-    if (timeUntilNextCall < 0) {
-      executeAndReschedule();
+      cannotBeExpedited = true;
     }
   }
 
@@ -1037,7 +1005,7 @@ export function makeInterruptibleAsyncInterval(
     }
 
     lastCallTime = 0;
-    lastWakeTime = 0;
+    cannotBeExpedited = false;
   }
 
   function reschedule(ms?: number) {
@@ -1050,7 +1018,7 @@ export function makeInterruptibleAsyncInterval(
   }
 
   function executeAndReschedule() {
-    lastWakeTime = 0;
+    cannotBeExpedited = false;
     lastCallTime = clock();
 
     fn(err => {
@@ -1128,8 +1096,9 @@ export function isSuperset(set: Set<any> | any[], subset: Set<any> | any[]): boo
   return true;
 }
 
-export function setDifference(setA: Iterable<any>, setB: Iterable<any>): Set<any> {
-  const difference = new Set(setA);
+/** Returns the items that are uniquely in setA */
+export function setDifference<T>(setA: Iterable<T>, setB: Iterable<T>): Set<T> {
+  const difference = new Set<T>(setA);
   for (const elem of setB) {
     difference.delete(elem);
   }
@@ -1179,11 +1148,11 @@ export function isRecord(
  * but instead something that is good enough for the purposes of
  * command monitoring.
  */
-export function deepCopy<T extends any>(value: T): T {
+export function deepCopy<T>(value: T): T {
   if (value == null) {
     return value;
   } else if (Array.isArray(value)) {
-    return value.map(item => deepCopy(item)) as T;
+    return value.map(item => deepCopy(item)) as unknown as T;
   } else if (isRecord(value)) {
     const res = {} as any;
     for (const key in value) {
@@ -1198,11 +1167,11 @@ export function deepCopy<T extends any>(value: T): T {
       case 'date':
         return new ctor(Number(value));
       case 'map':
-        return new Map(value as any) as T;
+        return new Map(value as any) as unknown as T;
       case 'set':
-        return new Set(value as any) as T;
+        return new Set(value as any) as unknown as T;
       case 'buffer':
-        return Buffer.from(value as Buffer) as T;
+        return Buffer.from(value as Buffer) as unknown as T;
     }
   }
 
@@ -1352,6 +1321,14 @@ export class HostAddress {
     Object.freeze(this);
   }
 
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return this.inspect();
+  }
+
+  inspect(): string {
+    return `new HostAddress('${this.toString(true)}')`;
+  }
+
   /**
    * @param ipv6Brackets - optionally request ipv6 bracket notation required for connection strings
    */
@@ -1368,6 +1345,10 @@ export class HostAddress {
   static fromString(s: string): HostAddress {
     return new HostAddress(s);
   }
+
+  static fromSrvRecord({ name, port }: SrvRecord): HostAddress {
+    return HostAddress.fromString(`${name}:${port}`);
+  }
 }
 
 export const DEFAULT_PK_FACTORY = {
@@ -1438,3 +1419,33 @@ export function parsePackageVersion({ version }: { version: string }): {
   const [major, minor, patch] = version.split('.').map((n: string) => Number.parseInt(n, 10));
   return { major, minor, patch };
 }
+
+/**
+ * Fisher–Yates Shuffle
+ *
+ * Reference: https://bost.ocks.org/mike/shuffle/
+ * @param sequence - items to be shuffled
+ * @param limit - Defaults to `0`. If nonzero shuffle will slice the randomized array e.g, `.slice(0, limit)` otherwise will return the entire randomized array.
+ */
+export function shuffle<T>(sequence: Iterable<T>, limit = 0): Array<T> {
+  const items = Array.from(sequence); // shallow copy in order to never shuffle the input
+
+  if (limit > items.length) {
+    throw new MongoRuntimeError('Limit must be less than the number of items');
+  }
+
+  let remainingItemsToShuffle = items.length;
+  const lowerBound = limit % items.length === 0 ? 1 : items.length - limit;
+  while (remainingItemsToShuffle > lowerBound) {
+    // Pick a remaining element
+    const randomIndex = Math.floor(Math.random() * remainingItemsToShuffle);
+    remainingItemsToShuffle -= 1;
+
+    // And swap it with the current element
+    const swapHold = items[remainingItemsToShuffle];
+    items[remainingItemsToShuffle] = items[randomIndex];
+    items[randomIndex] = swapHold;
+  }
+
+  return limit % items.length === 0 ? items : items.slice(lowerBound);
+}