mongodb 5.1.0 → 5.3.0

package/src/cmap/connection_pool_events.ts

@@ -1,5 +1,18 @@
 import type { ObjectId } from '../bson';
-import type { AnyError } from '../error';
+import {
+  CONNECTION_CHECK_OUT_FAILED,
+  CONNECTION_CHECK_OUT_STARTED,
+  CONNECTION_CHECKED_IN,
+  CONNECTION_CHECKED_OUT,
+  CONNECTION_CLOSED,
+  CONNECTION_CREATED,
+  CONNECTION_POOL_CLEARED,
+  CONNECTION_POOL_CLOSED,
+  CONNECTION_POOL_CREATED,
+  CONNECTION_POOL_READY,
+  CONNECTION_READY
+} from '../constants';
+import type { MongoError } from '../error';
 import type { Connection } from './connection';
 import type { ConnectionPool, ConnectionPoolOptions } from './connection_pool';
 
@@ -8,11 +21,24 @@ import type { ConnectionPool, ConnectionPoolOptions } from './connection_pool';
  * @public
  * @category Event
  */
-export class ConnectionPoolMonitoringEvent {
+export abstract class ConnectionPoolMonitoringEvent {
   /** A timestamp when the event was created  */
   time: Date;
   /** The address (host/port pair) of the pool */
   address: string;
+  /** @internal */
+  abstract name:
+    | typeof CONNECTION_CHECK_OUT_FAILED
+    | typeof CONNECTION_CHECK_OUT_STARTED
+    | typeof CONNECTION_CHECKED_IN
+    | typeof CONNECTION_CHECKED_OUT
+    | typeof CONNECTION_CLOSED
+    | typeof CONNECTION_CREATED
+    | typeof CONNECTION_POOL_CLEARED
+    | typeof CONNECTION_POOL_CLOSED
+    | typeof CONNECTION_POOL_CREATED
+    | typeof CONNECTION_POOL_READY
+    | typeof CONNECTION_READY;
 
   /** @internal */
   constructor(pool: ConnectionPool) {
@@ -29,6 +55,8 @@ export class ConnectionPoolMonitoringEvent {
 export class ConnectionPoolCreatedEvent extends ConnectionPoolMonitoringEvent {
   /** The options used to create this connection pool */
   options?: ConnectionPoolOptions;
+  /** @internal */
+  name = CONNECTION_POOL_CREATED;
 
   /** @internal */
   constructor(pool: ConnectionPool) {
@@ -43,6 +71,9 @@ export class ConnectionPoolCreatedEvent extends ConnectionPoolMonitoringEvent {
  * @category Event
  */
 export class ConnectionPoolReadyEvent extends ConnectionPoolMonitoringEvent {
+  /** @internal */
+  name = CONNECTION_POOL_READY;
+
   /** @internal */
   constructor(pool: ConnectionPool) {
     super(pool);
@@ -55,6 +86,9 @@ export class ConnectionPoolReadyEvent extends ConnectionPoolMonitoringEvent {
  * @category Event
  */
 export class ConnectionPoolClosedEvent extends ConnectionPoolMonitoringEvent {
+  /** @internal */
+  name = CONNECTION_POOL_CLOSED;
+
   /** @internal */
   constructor(pool: ConnectionPool) {
     super(pool);
@@ -69,6 +103,8 @@ export class ConnectionPoolClosedEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionCreatedEvent extends ConnectionPoolMonitoringEvent {
   /** A monotonically increasing, per-pool id for the newly created connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_CREATED;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: { id: number | '<monitor>' }) {
@@ -85,6 +121,8 @@ export class ConnectionCreatedEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionReadyEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_READY;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: Connection) {
@@ -104,17 +142,23 @@ export class ConnectionClosedEvent extends ConnectionPoolMonitoringEvent {
   /** The reason the connection was closed */
   reason: string;
   serviceId?: ObjectId;
+  /** @internal */
+  name = CONNECTION_CLOSED;
+  /** @internal */
+  error: MongoError | null;
 
   /** @internal */
   constructor(
     pool: ConnectionPool,
     connection: Pick<Connection, 'id' | 'serviceId'>,
-    reason: string
+    reason: 'idle' | 'stale' | 'poolClosed' | 'error',
+    error?: MongoError
   ) {
     super(pool);
     this.connectionId = connection.id;
-    this.reason = reason || 'unknown';
+    this.reason = reason;
     this.serviceId = connection.serviceId;
+    this.error = error ?? null;
   }
 }
 
@@ -124,6 +168,9 @@ export class ConnectionClosedEvent extends ConnectionPoolMonitoringEvent {
  * @category Event
  */
 export class ConnectionCheckOutStartedEvent extends ConnectionPoolMonitoringEvent {
+  /** @internal */
+  name = CONNECTION_CHECK_OUT_STARTED;
+
   /** @internal */
   constructor(pool: ConnectionPool) {
     super(pool);
@@ -137,12 +184,21 @@ export class ConnectionCheckOutStartedEvent extends ConnectionPoolMonitoringEven
  */
 export class ConnectionCheckOutFailedEvent extends ConnectionPoolMonitoringEvent {
   /** The reason the attempt to check out failed */
-  reason: AnyError | string;
+  reason: string;
+  /** @internal */
+  error?: MongoError;
+  /** @internal */
+  name = CONNECTION_CHECK_OUT_FAILED;
 
   /** @internal */
-  constructor(pool: ConnectionPool, reason: AnyError | string) {
+  constructor(
+    pool: ConnectionPool,
+    reason: 'poolClosed' | 'timeout' | 'connectionError',
+    error?: MongoError
+  ) {
     super(pool);
     this.reason = reason;
+    this.error = error;
   }
 }
 
@@ -154,6 +210,8 @@ export class ConnectionCheckOutFailedEvent extends ConnectionPoolMonitoringEvent
 export class ConnectionCheckedOutEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_CHECKED_OUT;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: Connection) {
@@ -170,6 +228,8 @@ export class ConnectionCheckedOutEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionCheckedInEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /** @internal */
+  name = CONNECTION_CHECKED_IN;
 
   /** @internal */
   constructor(pool: ConnectionPool, connection: Connection) {
@@ -188,6 +248,8 @@ export class ConnectionPoolClearedEvent extends ConnectionPoolMonitoringEvent {
   serviceId?: ObjectId;
 
   interruptInUseConnections?: boolean;
+  /** @internal */
+  name = CONNECTION_POOL_CLEARED;
 
   /** @internal */
   constructor(

package/src/cmap/handshake/client_metadata.ts

@@ -0,0 +1,272 @@
+import * as os from 'os';
+import * as process from 'process';
+
+import { BSON, Int32 } from '../../bson';
+import { MongoInvalidArgumentError } from '../../error';
+import type { MongoOptions } from '../../mongo_client';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const NODE_DRIVER_VERSION = require('../../../package.json').version;
+
+/**
+ * @public
+ * @see https://github.com/mongodb/specifications/blob/master/source/mongodb-handshake/handshake.rst#hello-command
+ */
+export interface ClientMetadata {
+  driver: {
+    name: string;
+    version: string;
+  };
+  os: {
+    type: string;
+    name?: NodeJS.Platform;
+    architecture?: string;
+    version?: string;
+  };
+  platform: string;
+  application?: {
+    name: string;
+  };
+  /** FaaS environment information */
+  env?: {
+    name: 'aws.lambda' | 'gcp.func' | 'azure.func' | 'vercel';
+    timeout_sec?: Int32;
+    memory_mb?: Int32;
+    region?: string;
+    url?: string;
+  };
+}
+
+/** @public */
+export interface ClientMetadataOptions {
+  driverInfo?: {
+    name?: string;
+    version?: string;
+    platform?: string;
+  };
+  appName?: string;
+}
+
+/** @internal */
+export class LimitedSizeDocument {
+  private document = new Map();
+  /** BSON overhead: Int32 + Null byte */
+  private documentSize = 5;
+  constructor(private maxSize: number) {}
+
+  /** Only adds key/value if the bsonByteLength is less than MAX_SIZE */
+  public ifItFitsItSits(key: string, value: Record<string, any> | string): boolean {
+    // The BSON byteLength of the new element is the same as serializing it to its own document
+    // subtracting the document size int32 and the null terminator.
+    const newElementSize = BSON.serialize(new Map().set(key, value)).byteLength - 5;
+
+    if (newElementSize + this.documentSize > this.maxSize) {
+      return false;
+    }
+
+    this.documentSize += newElementSize;
+
+    this.document.set(key, value);
+
+    return true;
+  }
+
+  toObject(): ClientMetadata {
+    return BSON.deserialize(BSON.serialize(this.document), {
+      promoteLongs: false,
+      promoteBuffers: false,
+      promoteValues: false,
+      useBigInt64: false
+    }) as ClientMetadata;
+  }
+}
+
+type MakeClientMetadataOptions = Pick<MongoOptions, 'appName' | 'driverInfo'>;
+/**
+ * From the specs:
+ * Implementors SHOULD cumulatively update fields in the following order until the document is under the size limit:
+ * 1. Omit fields from `env` except `env.name`.
+ * 2. Omit fields from `os` except `os.type`.
+ * 3. Omit the `env` document entirely.
+ * 4. Truncate `platform`. -- special we do not truncate this field
+ */
+export function makeClientMetadata(options: MakeClientMetadataOptions): ClientMetadata {
+  const metadataDocument = new LimitedSizeDocument(512);
+
+  const { appName = '' } = options;
+  // Add app name first, it must be sent
+  if (appName.length > 0) {
+    const name =
+      Buffer.byteLength(appName, 'utf8') <= 128
+        ? options.appName
+        : Buffer.from(appName, 'utf8').subarray(0, 128).toString('utf8');
+    metadataDocument.ifItFitsItSits('application', { name });
+  }
+
+  const { name = '', version = '', platform = '' } = options.driverInfo;
+
+  const driverInfo = {
+    name: name.length > 0 ? `nodejs|${name}` : 'nodejs',
+    version: version.length > 0 ? `${NODE_DRIVER_VERSION}|${version}` : NODE_DRIVER_VERSION
+  };
+
+  if (!metadataDocument.ifItFitsItSits('driver', driverInfo)) {
+    throw new MongoInvalidArgumentError(
+      'Unable to include driverInfo name and version, metadata cannot exceed 512 bytes'
+    );
+  }
+
+  let runtimeInfo = getRuntimeInfo();
+  if (platform.length > 0) {
+    runtimeInfo = `${runtimeInfo}|${platform}`;
+  }
+
+  if (!metadataDocument.ifItFitsItSits('platform', runtimeInfo)) {
+    throw new MongoInvalidArgumentError(
+      'Unable to include driverInfo platform, metadata cannot exceed 512 bytes'
+    );
+  }
+
+  // Note: order matters, os.type is last so it will be removed last if we're at maxSize
+  const osInfo = new Map()
+    .set('name', process.platform)
+    .set('architecture', process.arch)
+    .set('version', os.release())
+    .set('type', os.type());
+
+  if (!metadataDocument.ifItFitsItSits('os', osInfo)) {
+    for (const key of osInfo.keys()) {
+      osInfo.delete(key);
+      if (osInfo.size === 0) break;
+      if (metadataDocument.ifItFitsItSits('os', osInfo)) break;
+    }
+  }
+
+  const faasEnv = getFAASEnv();
+  if (faasEnv != null) {
+    if (!metadataDocument.ifItFitsItSits('env', faasEnv)) {
+      for (const key of faasEnv.keys()) {
+        faasEnv.delete(key);
+        if (faasEnv.size === 0) break;
+        if (metadataDocument.ifItFitsItSits('env', faasEnv)) break;
+      }
+    }
+  }
+
+  return metadataDocument.toObject();
+}
+
+/**
+ * Collects FaaS metadata.
+ * - `name` MUST be the last key in the Map returned.
+ */
+export function getFAASEnv(): Map<string, string | Int32> | null {
+  const {
+    AWS_EXECUTION_ENV = '',
+    AWS_LAMBDA_RUNTIME_API = '',
+    FUNCTIONS_WORKER_RUNTIME = '',
+    K_SERVICE = '',
+    FUNCTION_NAME = '',
+    VERCEL = '',
+    AWS_LAMBDA_FUNCTION_MEMORY_SIZE = '',
+    AWS_REGION = '',
+    FUNCTION_MEMORY_MB = '',
+    FUNCTION_REGION = '',
+    FUNCTION_TIMEOUT_SEC = '',
+    VERCEL_REGION = ''
+  } = process.env;
+
+  const isAWSFaaS = AWS_EXECUTION_ENV.length > 0 || AWS_LAMBDA_RUNTIME_API.length > 0;
+  const isAzureFaaS = FUNCTIONS_WORKER_RUNTIME.length > 0;
+  const isGCPFaaS = K_SERVICE.length > 0 || FUNCTION_NAME.length > 0;
+  const isVercelFaaS = VERCEL.length > 0;
+
+  // Note: order matters, name must always be the last key
+  const faasEnv = new Map();
+
+  // When isVercelFaaS is true so is isAWSFaaS; Vercel inherits the AWS env
+  if (isVercelFaaS && !(isAzureFaaS || isGCPFaaS)) {
+    if (VERCEL_REGION.length > 0) {
+      faasEnv.set('region', VERCEL_REGION);
+    }
+
+    faasEnv.set('name', 'vercel');
+    return faasEnv;
+  }
+
+  if (isAWSFaaS && !(isAzureFaaS || isGCPFaaS || isVercelFaaS)) {
+    if (AWS_REGION.length > 0) {
+      faasEnv.set('region', AWS_REGION);
+    }
+
+    if (
+      AWS_LAMBDA_FUNCTION_MEMORY_SIZE.length > 0 &&
+      Number.isInteger(+AWS_LAMBDA_FUNCTION_MEMORY_SIZE)
+    ) {
+      faasEnv.set('memory_mb', new Int32(AWS_LAMBDA_FUNCTION_MEMORY_SIZE));
+    }
+
+    faasEnv.set('name', 'aws.lambda');
+    return faasEnv;
+  }
+
+  if (isAzureFaaS && !(isGCPFaaS || isAWSFaaS || isVercelFaaS)) {
+    faasEnv.set('name', 'azure.func');
+    return faasEnv;
+  }
+
+  if (isGCPFaaS && !(isAzureFaaS || isAWSFaaS || isVercelFaaS)) {
+    if (FUNCTION_REGION.length > 0) {
+      faasEnv.set('region', FUNCTION_REGION);
+    }
+
+    if (FUNCTION_MEMORY_MB.length > 0 && Number.isInteger(+FUNCTION_MEMORY_MB)) {
+      faasEnv.set('memory_mb', new Int32(FUNCTION_MEMORY_MB));
+    }
+
+    if (FUNCTION_TIMEOUT_SEC.length > 0 && Number.isInteger(+FUNCTION_TIMEOUT_SEC)) {
+      faasEnv.set('timeout_sec', new Int32(FUNCTION_TIMEOUT_SEC));
+    }
+
+    faasEnv.set('name', 'gcp.func');
+    return faasEnv;
+  }
+
+  return null;
+}
+
+/**
+ * @internal
+ * This type represents the global Deno object and the minimal type contract we expect it to satisfy.
+ */
+declare const Deno: { version?: { deno?: string } } | undefined;
+
+/**
+ * @internal
+ * This type represents the global Bun object and the minimal type contract we expect it to satisfy.
+ */
+declare const Bun: { (): void; version?: string } | undefined;
+
+/**
+ * @internal
+ * Get current JavaScript runtime platform
+ *
+ * NOTE: The version information fetching is intentionally written defensively
+ * to avoid having a released driver version that becomes incompatible
+ * with a future change to these global objects.
+ */
+function getRuntimeInfo(): string {
+  if ('Deno' in globalThis) {
+    const version = typeof Deno?.version?.deno === 'string' ? Deno?.version?.deno : '0.0.0-unknown';
+
+    return `Deno v${version}, ${os.endianness()}`;
+  }
+
+  if ('Bun' in globalThis) {
+    const version = typeof Bun?.version === 'string' ? Bun?.version : '0.0.0-unknown';
+
+    return `Bun v${version}, ${os.endianness()}`;
+  }
+
+  return `Node.js ${process.version}, ${os.endianness()}`;
+}

package/src/cmap/message_stream.ts

@@ -30,13 +30,11 @@ export interface MessageStreamOptions extends DuplexOptions {
 export interface OperationDescription extends BSONSerializeOptions {
   started: number;
   cb: Callback<Document>;
-  command: boolean;
   documentsReturnedIn?: string;
   noResponse: boolean;
   raw: boolean;
   requestId: number;
   session?: ClientSession;
-  socketTimeoutOverride?: boolean;
   agreedCompressor?: CompressorName;
   zlibCompressionLevel?: number;
   $clusterTime?: Document;

package/src/cmap/wire_protocol/compression.ts

@@ -14,7 +14,7 @@ export const Compressor = Object.freeze({
 } as const);
 
 /** @public */
-export type Compressor = typeof Compressor[CompressorName];
+export type Compressor = (typeof Compressor)[CompressorName];
 
 /** @public */
 export type CompressorName = keyof typeof Compressor;

package/src/cmap/wire_protocol/shared.ts

@@ -7,8 +7,7 @@ import type { Server } from '../../sdam/server';
 import type { ServerDescription } from '../../sdam/server_description';
 import type { Topology } from '../../sdam/topology';
 import { TopologyDescription } from '../../sdam/topology_description';
-import type { OpQueryOptions } from '../commands';
-import type { CommandOptions, Connection } from '../connection';
+import type { Connection } from '../connection';
 
 export interface ReadPreferenceOption {
   readPreference?: ReadPreferenceLike;
@@ -35,27 +34,6 @@ export function getReadPreference(cmd: Document, options?: ReadPreferenceOption)
   return readPreference;
 }
 
-export function applyCommonQueryOptions(
-  queryOptions: OpQueryOptions,
-  options: CommandOptions
-): CommandOptions {
-  Object.assign(queryOptions, {
-    raw: typeof options.raw === 'boolean' ? options.raw : false,
-    promoteLongs: typeof options.promoteLongs === 'boolean' ? options.promoteLongs : true,
-    promoteValues: typeof options.promoteValues === 'boolean' ? options.promoteValues : true,
-    promoteBuffers: typeof options.promoteBuffers === 'boolean' ? options.promoteBuffers : false,
-    bsonRegExp: typeof options.bsonRegExp === 'boolean' ? options.bsonRegExp : false,
-    enableUtf8Validation:
-      typeof options.enableUtf8Validation === 'boolean' ? options.enableUtf8Validation : true
-  });
-
-  if (options.session) {
-    queryOptions.session = options.session;
-  }
-
-  return queryOptions;
-}
-
 export function isSharded(topologyOrServer?: Topology | Server | Connection): boolean {
   if (topologyOrServer == null) {
     return false;

package/src/collection.ts

@@ -334,7 +334,7 @@ export class Collection<TSchema extends Document = Document> {
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Partial<TSchema>,
     options?: UpdateOptions
-  ): Promise<UpdateResult> {
+  ): Promise<UpdateResult<TSchema>> {
     return executeOperation(
       this.s.db.s.client,
       new UpdateOneOperation(
@@ -357,7 +357,7 @@ export class Collection<TSchema extends Document = Document> {
     filter: Filter<TSchema>,
     replacement: WithoutId<TSchema>,
     options?: ReplaceOptions
-  ): Promise<UpdateResult | Document> {
+  ): Promise<UpdateResult<TSchema> | Document> {
     return executeOperation(
       this.s.db.s.client,
       new ReplaceOneOperation(
@@ -380,7 +380,7 @@ export class Collection<TSchema extends Document = Document> {
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema>,
     options?: UpdateOptions
-  ): Promise<UpdateResult> {
+  ): Promise<UpdateResult<TSchema>> {
     return executeOperation(
       this.s.db.s.client,
       new UpdateManyOperation(
@@ -568,7 +568,7 @@ export class Collection<TSchema extends Document = Document> {
    * error.
    *
    * **Note**: Unlike {@link Collection#createIndex| createIndex}, this function takes in raw index specifications.
-   * Index specifications are defined {@link http://docs.mongodb.org/manual/reference/command/createIndexes/| here}.
+   * Index specifications are defined {@link https://www.mongodb.com/docs/manual/reference/command/createIndexes/| here}.
    *
    * @param indexSpecs - An array of index specifications to be created
    * @param options - Optional settings for the command
@@ -705,18 +705,18 @@ export class Collection<TSchema extends Document = Document> {
    * | `$near`    | [`$geoWithin`][2] with [`$center`][3] |
    * | `$nearSphere` | [`$geoWithin`][2] with [`$centerSphere`][4] |
    *
-   * [1]: https://docs.mongodb.com/manual/reference/operator/query/expr/
-   * [2]: https://docs.mongodb.com/manual/reference/operator/query/geoWithin/
-   * [3]: https://docs.mongodb.com/manual/reference/operator/query/center/#op._S_center
-   * [4]: https://docs.mongodb.com/manual/reference/operator/query/centerSphere/#op._S_centerSphere
+   * [1]: https://www.mongodb.com/docs/manual/reference/operator/query/expr/
+   * [2]: https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/
+   * [3]: https://www.mongodb.com/docs/manual/reference/operator/query/center/#op._S_center
+   * [4]: https://www.mongodb.com/docs/manual/reference/operator/query/centerSphere/#op._S_centerSphere
    *
    * @param filter - The filter for the count
    * @param options - Optional settings for the command
    *
-   * @see https://docs.mongodb.com/manual/reference/operator/query/expr/
-   * @see https://docs.mongodb.com/manual/reference/operator/query/geoWithin/
-   * @see https://docs.mongodb.com/manual/reference/operator/query/center/#op._S_center
-   * @see https://docs.mongodb.com/manual/reference/operator/query/centerSphere/#op._S_centerSphere
+   * @see https://www.mongodb.com/docs/manual/reference/operator/query/expr/
+   * @see https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/
+   * @see https://www.mongodb.com/docs/manual/reference/operator/query/center/#op._S_center
+   * @see https://www.mongodb.com/docs/manual/reference/operator/query/centerSphere/#op._S_centerSphere
    */
   async countDocuments(
     filter: Document = {},
@@ -916,7 +916,7 @@ export class Collection<TSchema extends Document = Document> {
    *   });
    * ```
    *
-   * @param pipeline - An array of {@link https://docs.mongodb.com/manual/reference/operator/aggregation-pipeline/|aggregation pipeline stages} through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
+   * @param pipeline - An array of {@link https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/|aggregation pipeline stages} through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
    * @param options - Optional settings for the command
    * @typeParam TLocal - Type of the data being detected by the change stream
    * @typeParam TChange - Type of the whole change stream document emitted