@depup/mongodb 7.1.0-depup.0

package/src/read_preference.ts

@@ -0,0 +1,256 @@
+import type { Document } from './bson';
+import { MongoInvalidArgumentError } from './error';
+import type { TagSet } from './sdam/server_description';
+import type { ClientSession } from './sessions';
+
+/** @public */
+export type ReadPreferenceLike = ReadPreference | ReadPreferenceMode;
+
+/** @public */
+export const ReadPreferenceMode = Object.freeze({
+  primary: 'primary',
+  primaryPreferred: 'primaryPreferred',
+  secondary: 'secondary',
+  secondaryPreferred: 'secondaryPreferred',
+  nearest: 'nearest'
+} as const);
+
+/** @public */
+export type ReadPreferenceMode = (typeof ReadPreferenceMode)[keyof typeof ReadPreferenceMode];
+
+/** @public */
+export interface HedgeOptions {
+  /** Explicitly enable or disable hedged reads. */
+  enabled?: boolean;
+}
+
+/** @public */
+export interface ReadPreferenceOptions {
+  /** Max secondary read staleness in seconds, Minimum value is 90 seconds.*/
+  maxStalenessSeconds?: number;
+  /** Server mode in which the same query is dispatched in parallel to multiple replica set members. */
+  hedge?: HedgeOptions;
+}
+
+/** @public */
+export interface ReadPreferenceLikeOptions extends ReadPreferenceOptions {
+  readPreference?:
+    | ReadPreferenceLike
+    | {
+        mode?: ReadPreferenceMode;
+        preference?: ReadPreferenceMode;
+        tags?: TagSet[];
+        maxStalenessSeconds?: number;
+      };
+}
+
+/** @public */
+export interface ReadPreferenceFromOptions extends ReadPreferenceLikeOptions {
+  session?: ClientSession;
+  readPreferenceTags?: TagSet[];
+  hedge?: HedgeOptions;
+}
+
+/**
+ * The **ReadPreference** class is a class that represents a MongoDB ReadPreference and is
+ * used to construct connections.
+ * @public
+ *
+ * @see https://www.mongodb.com/docs/manual/core/read-preference/
+ */
+export class ReadPreference {
+  mode: ReadPreferenceMode;
+  tags?: TagSet[];
+  hedge?: HedgeOptions;
+  maxStalenessSeconds?: number;
+
+  public static PRIMARY = ReadPreferenceMode.primary;
+  public static PRIMARY_PREFERRED = ReadPreferenceMode.primaryPreferred;
+  public static SECONDARY = ReadPreferenceMode.secondary;
+  public static SECONDARY_PREFERRED = ReadPreferenceMode.secondaryPreferred;
+  public static NEAREST = ReadPreferenceMode.nearest;
+
+  public static primary = new ReadPreference(ReadPreferenceMode.primary);
+  public static primaryPreferred = new ReadPreference(ReadPreferenceMode.primaryPreferred);
+  public static secondary = new ReadPreference(ReadPreferenceMode.secondary);
+  public static secondaryPreferred = new ReadPreference(ReadPreferenceMode.secondaryPreferred);
+  public static nearest = new ReadPreference(ReadPreferenceMode.nearest);
+
+  /**
+   * @param mode - A string describing the read preference mode (primary|primaryPreferred|secondary|secondaryPreferred|nearest)
+   * @param tags - A tag set used to target reads to members with the specified tag(s). tagSet is not available if using read preference mode primary.
+   * @param options - Additional read preference options
+   */
+  constructor(mode: ReadPreferenceMode, tags?: TagSet[], options?: ReadPreferenceOptions) {
+    if (!ReadPreference.isValid(mode)) {
+      throw new MongoInvalidArgumentError(`Invalid read preference mode ${JSON.stringify(mode)}`);
+    }
+    if (options == null && typeof tags === 'object' && !Array.isArray(tags)) {
+      options = tags;
+      tags = undefined;
+    } else if (tags && !Array.isArray(tags)) {
+      throw new MongoInvalidArgumentError('ReadPreference tags must be an array');
+    }
+
+    this.mode = mode;
+    this.tags = tags;
+    this.hedge = options?.hedge;
+    this.maxStalenessSeconds = undefined;
+
+    options = options ?? {};
+    if (options.maxStalenessSeconds != null) {
+      if (options.maxStalenessSeconds <= 0) {
+        throw new MongoInvalidArgumentError('maxStalenessSeconds must be a positive integer');
+      }
+
+      this.maxStalenessSeconds = options.maxStalenessSeconds;
+    }
+
+    if (this.mode === ReadPreference.PRIMARY) {
+      if (this.tags && Array.isArray(this.tags) && this.tags.length > 0) {
+        throw new MongoInvalidArgumentError('Primary read preference cannot be combined with tags');
+      }
+
+      if (this.maxStalenessSeconds) {
+        throw new MongoInvalidArgumentError(
+          'Primary read preference cannot be combined with maxStalenessSeconds'
+        );
+      }
+
+      if (this.hedge) {
+        throw new MongoInvalidArgumentError(
+          'Primary read preference cannot be combined with hedge'
+        );
+      }
+    }
+  }
+
+  // Support the deprecated `preference` property introduced in the porcelain layer
+  get preference(): ReadPreferenceMode {
+    return this.mode;
+  }
+
+  static fromString(mode: string): ReadPreference {
+    return new ReadPreference(mode as ReadPreferenceMode);
+  }
+
+  /**
+   * Construct a ReadPreference given an options object.
+   *
+   * @param options - The options object from which to extract the read preference.
+   */
+  static fromOptions(options?: ReadPreferenceFromOptions): ReadPreference | undefined {
+    if (!options) return;
+    const readPreference =
+      options.readPreference ?? options.session?.transaction.options.readPreference;
+    const readPreferenceTags = options.readPreferenceTags;
+
+    if (readPreference == null) {
+      return;
+    }
+
+    if (typeof readPreference === 'string') {
+      return new ReadPreference(readPreference, 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') {
+        return new ReadPreference(mode, readPreference.tags ?? readPreferenceTags, {
+          maxStalenessSeconds: readPreference.maxStalenessSeconds,
+          hedge: options.hedge
+        });
+      }
+    }
+
+    if (readPreferenceTags) {
+      readPreference.tags = readPreferenceTags;
+    }
+
+    return readPreference as ReadPreference;
+  }
+
+  /**
+   * Replaces options.readPreference with a ReadPreference instance
+   */
+  static translate(options: ReadPreferenceLikeOptions): ReadPreferenceLikeOptions {
+    if (options.readPreference == null) return options;
+    const r = options.readPreference;
+
+    if (typeof r === 'string') {
+      options.readPreference = new ReadPreference(r);
+    } else if (r && !(r instanceof ReadPreference) && typeof r === 'object') {
+      const mode = r.mode || r.preference;
+      if (mode && typeof mode === 'string') {
+        options.readPreference = new ReadPreference(mode, r.tags, {
+          maxStalenessSeconds: r.maxStalenessSeconds
+        });
+      }
+    } else if (!(r instanceof ReadPreference)) {
+      throw new MongoInvalidArgumentError(`Invalid read preference: ${r}`);
+    }
+
+    return options;
+  }
+
+  /**
+   * Validate if a mode is legal
+   *
+   * @param mode - The string representing the read preference mode.
+   */
+  static isValid(mode: string): boolean {
+    const VALID_MODES = new Set([
+      ReadPreference.PRIMARY,
+      ReadPreference.PRIMARY_PREFERRED,
+      ReadPreference.SECONDARY,
+      ReadPreference.SECONDARY_PREFERRED,
+      ReadPreference.NEAREST,
+      null
+    ]);
+
+    return VALID_MODES.has(mode as ReadPreferenceMode);
+  }
+
+  /**
+   * Validate if a mode is legal
+   *
+   * @param mode - The string representing the read preference mode.
+   */
+  isValid(mode?: string): boolean {
+    return ReadPreference.isValid(typeof mode === 'string' ? mode : this.mode);
+  }
+
+  /**
+   * Indicates that this readPreference needs the "SecondaryOk" bit when sent over the wire
+   * @see https://www.mongodb.com/docs/manual/reference/mongodb-wire-protocol/#op-query
+   */
+  secondaryOk(): boolean {
+    const NEEDS_SECONDARYOK = new Set<string>([
+      ReadPreference.PRIMARY_PREFERRED,
+      ReadPreference.SECONDARY,
+      ReadPreference.SECONDARY_PREFERRED,
+      ReadPreference.NEAREST
+    ]);
+
+    return NEEDS_SECONDARYOK.has(this.mode);
+  }
+
+  /**
+   * Check if the two ReadPreferences are equivalent
+   *
+   * @param readPreference - The read preference with which to check equality
+   */
+  equals(readPreference: ReadPreference): boolean {
+    return readPreference.mode === this.mode;
+  }
+
+  /** Return JSON representation */
+  toJSON(): Document {
+    const readPreference = { mode: this.mode } as Document;
+    if (Array.isArray(this.tags)) readPreference.tags = this.tags;
+    if (this.maxStalenessSeconds) readPreference.maxStalenessSeconds = this.maxStalenessSeconds;
+    if (this.hedge) readPreference.hedge = this.hedge;
+    return readPreference;
+  }
+}

package/src/sdam/common.ts

@@ -0,0 +1,74 @@
+import type { Binary, Long, Timestamp } from '../bson';
+import type { ClientSession } from '../sessions';
+import type { Topology } from './topology';
+
+// shared state names
+export const STATE_CLOSING = 'closing';
+export const STATE_CLOSED = 'closed';
+export const STATE_CONNECTING = 'connecting';
+export const STATE_CONNECTED = 'connected';
+
+/**
+ * An enumeration of topology types we know about
+ * @public
+ */
+export const TopologyType = Object.freeze({
+  Single: 'Single',
+  ReplicaSetNoPrimary: 'ReplicaSetNoPrimary',
+  ReplicaSetWithPrimary: 'ReplicaSetWithPrimary',
+  Sharded: 'Sharded',
+  Unknown: 'Unknown',
+  LoadBalanced: 'LoadBalanced'
+} as const);
+
+/** @public */
+export type TopologyType = (typeof TopologyType)[keyof typeof TopologyType];
+
+/**
+ * An enumeration of server types we know about
+ * @public
+ */
+export const ServerType = Object.freeze({
+  Standalone: 'Standalone',
+  Mongos: 'Mongos',
+  PossiblePrimary: 'PossiblePrimary',
+  RSPrimary: 'RSPrimary',
+  RSSecondary: 'RSSecondary',
+  RSArbiter: 'RSArbiter',
+  RSOther: 'RSOther',
+  RSGhost: 'RSGhost',
+  Unknown: 'Unknown',
+  LoadBalancer: 'LoadBalancer'
+} as const);
+
+/** @public */
+export type ServerType = (typeof ServerType)[keyof typeof ServerType];
+
+/**
+ * @public
+ * Gossiped in component for the cluster time tracking the state of user databases
+ * across the cluster. It may optionally include a signature identifying the process that
+ * generated such a value.
+ */
+export interface ClusterTime {
+  clusterTime: Timestamp;
+  /** Used to validate the identity of a request or response's ClusterTime. */
+  signature?: {
+    hash: Binary;
+    keyId: Long;
+  };
+}
+
+/** Shared function to determine clusterTime for a given topology or session */
+export function _advanceClusterTime(
+  entity: Topology | ClientSession,
+  $clusterTime: ClusterTime
+): void {
+  if (entity.clusterTime == null) {
+    entity.clusterTime = $clusterTime;
+  } else {
+    if ($clusterTime.clusterTime.greaterThan(entity.clusterTime.clusterTime)) {
+      entity.clusterTime = $clusterTime;
+    }
+  }
+}

package/src/sdam/events.ts

@@ -0,0 +1,219 @@
+import type { Document } from '../bson';
+import {
+  SERVER_CLOSED,
+  SERVER_DESCRIPTION_CHANGED,
+  SERVER_HEARTBEAT_FAILED,
+  SERVER_HEARTBEAT_STARTED,
+  SERVER_HEARTBEAT_SUCCEEDED,
+  SERVER_OPENING,
+  TOPOLOGY_CLOSED,
+  TOPOLOGY_DESCRIPTION_CHANGED,
+  TOPOLOGY_OPENING
+} from '../constants';
+import type { ServerDescription } from './server_description';
+import type { TopologyDescription } from './topology_description';
+
+/**
+ * Emitted when server description changes, but does NOT include changes to the RTT.
+ * @public
+ * @category Event
+ */
+export class ServerDescriptionChangedEvent {
+  /** A unique identifier for the topology */
+  topologyId: number;
+  /** The address (host/port pair) of the server */
+  address: string;
+  /** The previous server description */
+  previousDescription: ServerDescription;
+  /** The new server description */
+  newDescription: ServerDescription;
+  name = SERVER_DESCRIPTION_CHANGED;
+
+  /** @internal */
+  constructor(
+    topologyId: number,
+    address: string,
+    previousDescription: ServerDescription,
+    newDescription: ServerDescription
+  ) {
+    this.topologyId = topologyId;
+    this.address = address;
+    this.previousDescription = previousDescription;
+    this.newDescription = newDescription;
+  }
+}
+
+/**
+ * Emitted when server is initialized.
+ * @public
+ * @category Event
+ */
+export class ServerOpeningEvent {
+  /** A unique identifier for the topology */
+  topologyId: number;
+  /** The address (host/port pair) of the server */
+  address: string;
+  /** @internal */
+  name = SERVER_OPENING;
+
+  /** @internal */
+  constructor(topologyId: number, address: string) {
+    this.topologyId = topologyId;
+    this.address = address;
+  }
+}
+
+/**
+ * Emitted when server is closed.
+ * @public
+ * @category Event
+ */
+export class ServerClosedEvent {
+  /** A unique identifier for the topology */
+  topologyId: number;
+  /** The address (host/port pair) of the server */
+  address: string;
+  /** @internal */
+  name = SERVER_CLOSED;
+
+  /** @internal */
+  constructor(topologyId: number, address: string) {
+    this.topologyId = topologyId;
+    this.address = address;
+  }
+}
+
+/**
+ * Emitted when topology description changes.
+ * @public
+ * @category Event
+ */
+export class TopologyDescriptionChangedEvent {
+  /** A unique identifier for the topology */
+  topologyId: number;
+  /** The old topology description */
+  previousDescription: TopologyDescription;
+  /** The new topology description */
+  newDescription: TopologyDescription;
+  /** @internal */
+  name = TOPOLOGY_DESCRIPTION_CHANGED;
+
+  /** @internal */
+  constructor(
+    topologyId: number,
+    previousDescription: TopologyDescription,
+    newDescription: TopologyDescription
+  ) {
+    this.topologyId = topologyId;
+    this.previousDescription = previousDescription;
+    this.newDescription = newDescription;
+  }
+}
+
+/**
+ * Emitted when topology is initialized.
+ * @public
+ * @category Event
+ */
+export class TopologyOpeningEvent {
+  /** A unique identifier for the topology */
+  topologyId: number;
+  /** @internal */
+  name = TOPOLOGY_OPENING;
+
+  /** @internal */
+  constructor(topologyId: number) {
+    this.topologyId = topologyId;
+  }
+}
+
+/**
+ * Emitted when topology is closed.
+ * @public
+ * @category Event
+ */
+export class TopologyClosedEvent {
+  /** A unique identifier for the topology */
+  topologyId: number;
+  /** @internal */
+  name = TOPOLOGY_CLOSED;
+
+  /** @internal */
+  constructor(topologyId: number) {
+    this.topologyId = topologyId;
+  }
+}
+
+/**
+ * Emitted when the server monitor’s hello command is started - immediately before
+ * the hello command is serialized into raw BSON and written to the socket.
+ *
+ * @public
+ * @category Event
+ */
+export class ServerHeartbeatStartedEvent {
+  /** The connection id for the command */
+  connectionId: string;
+  /** Is true when using the streaming protocol */
+  awaited: boolean;
+  /** @internal */
+  name = SERVER_HEARTBEAT_STARTED;
+
+  /** @internal */
+  constructor(connectionId: string, awaited: boolean) {
+    this.connectionId = connectionId;
+    this.awaited = awaited;
+  }
+}
+
+/**
+ * Emitted when the server monitor’s hello succeeds.
+ * @public
+ * @category Event
+ */
+export class ServerHeartbeatSucceededEvent {
+  /** The connection id for the command */
+  connectionId: string;
+  /** The execution time of the event in ms */
+  duration: number;
+  /** The command reply */
+  reply: Document;
+  /** Is true when using the streaming protocol */
+  awaited: boolean;
+  /** @internal */
+  name = SERVER_HEARTBEAT_SUCCEEDED;
+
+  /** @internal */
+  constructor(connectionId: string, duration: number, reply: Document | null, awaited: boolean) {
+    this.connectionId = connectionId;
+    this.duration = duration;
+    this.reply = reply ?? {};
+    this.awaited = awaited;
+  }
+}
+
+/**
+ * Emitted when the server monitor’s hello fails, either with an “ok: 0” or a socket exception.
+ * @public
+ * @category Event
+ */
+export class ServerHeartbeatFailedEvent {
+  /** The connection id for the command */
+  connectionId: string;
+  /** The execution time of the event in ms */
+  duration: number;
+  /** The command failure */
+  failure: Error;
+  /** Is true when using the streaming protocol */
+  awaited: boolean;
+  /** @internal */
+  name = SERVER_HEARTBEAT_FAILED;
+
+  /** @internal */
+  constructor(connectionId: string, duration: number, failure: Error, awaited: boolean) {
+    this.connectionId = connectionId;
+    this.duration = duration;
+    this.failure = failure;
+    this.awaited = awaited;
+  }
+}