mongodb 6.8.0-dev.20240802.sha.54efb7d4 → 6.8.0-dev.20240813.sha.b70c8850

package/mongodb.d.ts

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-
 import type { DeserializeOptions , ObjectIdLike , SerializeOptions } from 'bson';
 import { Binary , BSON , BSONRegExp , BSONSymbol , BSONType , Code , DBRef , Decimal128 , deserialize , Document , Double , Int32 , Long , MaxKey , MinKey , ObjectId , serialize , Timestamp , UUID } from 'bson';
 import type { SrvRecord } from 'dns';
@@ -9,7 +7,7 @@ import { Readable , Writable } from 'stream';
 import type { ConnectionOptions as ConnectionOptions_2 , TLSSocket , TLSSocketOptions } from 'tls';
 
 /** @public */
-export declare abstract class AbstractCursor<TSchema = any, CursorEvents extends AbstractCursorEvents = AbstractCursorEvents> extends TypedEventEmitter<CursorEvents> {
+export declare abstract class AbstractCursor<TSchema = any, CursorEvents extends AbstractCursorEvents = AbstractCursorEvents> extends TypedEventEmitter<CursorEvents> implements AsyncDisposable_2 {
     /* Excluded from this release type: cursorId */
     /* Excluded from this release type: cursorSession */
     /* Excluded from this release type: selectedServer */
@@ -50,10 +48,12 @@ export declare abstract class AbstractCursor<TSchema = any, CursorEvents extends
      */
     get killed(): boolean;
     get loadBalanced(): boolean;
+    /* Excluded from this release type: [Symbol.asyncDispose] */
+    /* Excluded from this release type: asyncDispose */
     /** Returns current buffered documents length */
     bufferedCount(): number;
     /** Returns current buffered documents */
-    readBufferedDocuments(number?: number): TSchema[];
+    readBufferedDocuments(number?: number): NonNullable<TSchema>[];
     [Symbol.asyncIterator](): AsyncGenerator<TSchema, void, void>;
     stream(options?: CursorStreamOptions): Readable & AsyncIterable<TSchema>;
     hasNext(): Promise<boolean>;
@@ -72,6 +72,9 @@ export declare abstract class AbstractCursor<TSchema = any, CursorEvents extends
      * @deprecated - Will be removed in a future release. Use for await...of instead.
      */
     forEach(iterator: (doc: TSchema) => boolean | void): Promise<void>;
+    /**
+     * Frees any client-side resources used by the cursor.
+     */
     close(): Promise<void>;
     /**
      * Returns an array of documents. The caller is responsible for making sure that there
@@ -500,6 +503,15 @@ export declare type ArrayOperator<Type> = {
     $sort?: Sort;
 };
 
+/**
+ * @public
+ */
+declare interface AsyncDisposable_2 {
+    /* Excluded from this release type: [Symbol.asyncDispose] */
+    /* Excluded from this release type: asyncDispose */
+}
+export { AsyncDisposable_2 as AsyncDisposable }
+
 /** @public */
 export declare interface Auth {
     /** The username for auth */
@@ -988,7 +1000,9 @@ export declare class CancellationToken extends TypedEventEmitter<{
  * Creates a new Change Stream instance. Normally created using {@link Collection#watch|Collection.watch()}.
  * @public
  */
-export declare class ChangeStream<TSchema extends Document = Document, TChange extends Document = ChangeStreamDocument<TSchema>> extends TypedEventEmitter<ChangeStreamEvents<TSchema, TChange>> {
+export declare class ChangeStream<TSchema extends Document = Document, TChange extends Document = ChangeStreamDocument<TSchema>> extends TypedEventEmitter<ChangeStreamEvents<TSchema, TChange>> implements AsyncDisposable_2 {
+    /* Excluded from this release type: [Symbol.asyncDispose] */
+    /* Excluded from this release type: asyncDispose */
     pipeline: Document[];
     /**
      * @remarks WriteConcern can still be present on the options because
@@ -1047,7 +1061,9 @@ export declare class ChangeStream<TSchema extends Document = Document, TChange e
     [Symbol.asyncIterator](): AsyncGenerator<TChange, void, void>;
     /** Is the cursor closed */
     get closed(): boolean;
-    /** Close the Change Stream */
+    /**
+     * Frees the internal resources used by the change stream.
+     */
     close(): Promise<void>;
     /**
      * Return a modified Readable stream including a possible transform method.
@@ -1909,7 +1925,7 @@ export declare interface ClientMetadataOptions {
  * NOTE: not meant to be instantiated directly.
  * @public
  */
-export declare class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
+export declare class ClientSession extends TypedEventEmitter<ClientSessionEvents> implements AsyncDisposable_2 {
     /* Excluded from this release type: client */
     /* Excluded from this release type: sessionPool */
     hasEnded: boolean;
@@ -1941,11 +1957,16 @@ export declare class ClientSession extends TypedEventEmitter<ClientSessionEvents
     /* Excluded from this release type: unpin */
     get isPinned(): boolean;
     /**
-     * Ends this session on the server
+     * Frees any client-side resources held by the current session.  If a session is in a transaction,
+     * the transaction is aborted.
+     *
+     * Does not end the session on the server.
      *
      * @param options - Optional settings. Currently reserved for future use
      */
     endSession(options?: EndSessionOptions): Promise<void>;
+    /* Excluded from this release type: [Symbol.asyncDispose] */
+    /* Excluded from this release type: asyncDispose */
     /**
      * Advances the operationTime for a ClientSession.
      *
@@ -2787,6 +2808,8 @@ export declare type CompressorName = keyof typeof Compressor;
 /** @public */
 export declare type Condition<T> = AlternativeType<T> | FilterOperators<AlternativeType<T>>;
 
+/* Excluded from this release type: configureExplicitResourceManagement */
+
 /* Excluded from this release type: Connection */
 
 /* Excluded from this release type: CONNECTION_CHECK_OUT_FAILED */
@@ -4902,13 +4925,15 @@ export declare class MongoChangeStreamError extends MongoRuntimeError {
  * await client.insertOne({ name: 'spot', kind: 'dog' });
  * ```
  */
-export declare class MongoClient extends TypedEventEmitter<MongoClientEvents> {
+export declare class MongoClient extends TypedEventEmitter<MongoClientEvents> implements AsyncDisposable_2 {
     /* Excluded from this release type: s */
     /* Excluded from this release type: topology */
     /* Excluded from this release type: mongoLogger */
     /* Excluded from this release type: connectionLock */
     /* Excluded from this release type: [kOptions] */
     constructor(url: string, options?: MongoClientOptions);
+    /* Excluded from this release type: [Symbol.asyncDispose] */
+    /* Excluded from this release type: asyncDispose */
     /* Excluded from this release type: checkForNonGenuineHosts */
     /** @see MongoOptions */
     get options(): Readonly<MongoOptions>;
@@ -4928,7 +4953,15 @@ export declare class MongoClient extends TypedEventEmitter<MongoClientEvents> {
     connect(): Promise<this>;
     /* Excluded from this release type: _connect */
     /**
-     * Close the client and its underlying connections
+     * Cleans up client-side resources used by the MongoCLient and .  This includes:
+     *
+     * - Closes all open, unused connections (see note).
+     * - Ends all in-use sessions with {@link ClientSession#endSession|ClientSession.endSession()}.
+     * - Ends all unused sessions server-side.
+     * - Cleans up any resources being used for auto encryption if auto encryption is enabled.
+     *
+     * @remarks Any in-progress operations are not killed and any connections used by in progress operations
+     * will be cleaned up lazily as operations finish.
      *
      * @param force - Force close, emitting no events
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mongodb",
-  "version": "6.8.0-dev.20240802.sha.54efb7d4",
+  "version": "6.8.0-dev.20240813.sha.b70c8850",
   "description": "The official MongoDB driver for Node.js",
   "main": "lib/index.js",
   "files": [
@@ -73,7 +73,7 @@
     "@types/express": "^4.17.21",
     "@types/kerberos": "^1.1.5",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^20.12.7",
+    "@types/node": "^20.14.10",
     "@types/saslprep": "^1.0.3",
     "@types/semver": "^7.5.8",
     "@types/sinon": "^17.0.3",
@@ -110,7 +110,7 @@
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
     "tsd": "^0.31.0",
-    "typescript": "5.0",
+    "typescript": "5.5",
     "typescript-cached-transpile": "^0.0.6",
     "v8-heapsnapshot": "^1.3.1",
     "yargs": "^17.7.2"
@@ -126,7 +126,7 @@
   "scripts": {
     "build:evergreen": "node .evergreen/generate_evergreen_tasks.js",
     "build:ts": "node ./node_modules/typescript/bin/tsc",
-    "build:dts": "npm run build:ts && api-extractor run && node etc/clean_definition_files.cjs && eslint mongodb.d.ts --fix",
+    "build:dts": "npm run build:ts && api-extractor run && node etc/clean_definition_files.cjs && eslint --no-ignore --fix mongodb.d.ts lib/beta.d.ts",
     "build:docs": "./etc/docs/build.ts",
     "build:typedoc": "typedoc",
     "build:nightly": "node ./.github/scripts/nightly.mjs",
@@ -145,6 +145,7 @@
     "check:unit": "mocha test/unit",
     "check:ts": "node ./node_modules/typescript/bin/tsc -v && node ./node_modules/typescript/bin/tsc --noEmit",
     "check:atlas": "mocha --config test/manual/mocharc.json test/manual/atlas_connectivity.test.ts",
+    "check:resource-management": "mocha --config test/manual/mocharc.json test/manual/resource_management.test.ts",
     "check:drivers-atlas-testing": "mocha --config test/mocha_mongodb.json test/atlas/drivers_atlas_testing.test.ts",
     "check:adl": "mocha --config test/mocha_mongodb.json test/manual/atlas-data-lake-testing",
     "check:aws": "nyc mocha --config test/mocha_mongodb.json test/integration/auth/mongodb_aws.test.ts",

package/src/beta.ts

@@ -0,0 +1,22 @@
+import { type Document } from 'bson';
+
+export * from './index';
+
+/**
+ * @internal
+ *
+ * Since we don't bundle tslib helpers, we need to polyfill this method.
+ *
+ * This is used in the generated JS.  Adapted from https://github.com/microsoft/TypeScript/blob/aafdfe5b3f76f5c41abeec412ce73c86da94c75f/src/compiler/factory/emitHelpers.ts#L1202.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function __exportStar(mod: Document) {
+  for (const key of Object.keys(mod)) {
+    Object.defineProperty(exports, key, {
+      enumerable: true,
+      get: function () {
+        return mod[key];
+      }
+    });
+  }
+}

package/src/change_stream.ts

@@ -18,6 +18,7 @@ import { type InferIdType, TypedEventEmitter } from './mongo_types';
 import type { AggregateOptions } from './operations/aggregate';
 import type { CollationOptions, OperationParent } from './operations/command';
 import type { ReadPreference } from './read_preference';
+import { type AsyncDisposable, configureResourceManagement } from './resource_management';
 import type { ServerSessionId } from './sessions';
 import { filterOptions, getTopology, type MongoDBNamespace, squashError } from './utils';
 
@@ -544,9 +545,23 @@ export type ChangeStreamEvents<
  * @public
  */
 export class ChangeStream<
-  TSchema extends Document = Document,
-  TChange extends Document = ChangeStreamDocument<TSchema>
-> extends TypedEventEmitter<ChangeStreamEvents<TSchema, TChange>> {
+    TSchema extends Document = Document,
+    TChange extends Document = ChangeStreamDocument<TSchema>
+  >
+  extends TypedEventEmitter<ChangeStreamEvents<TSchema, TChange>>
+  implements AsyncDisposable
+{
+  /**
+   * @beta
+   * @experimental
+   * An alias for {@link ChangeStream.close|ChangeStream.close()}.
+   */
+  declare [Symbol.asyncDispose]: () => Promise<void>;
+  /** @internal */
+  async asyncDispose() {
+    await this.close();
+  }
+
   pipeline: Document[];
   /**
    * @remarks WriteConcern can still be present on the options because
@@ -765,7 +780,9 @@ export class ChangeStream<
     return this[kClosed] || this.cursor.closed;
   }
 
-  /** Close the Change Stream */
+  /**
+   * Frees the internal resources used by the change stream.
+   */
   async close(): Promise<void> {
     this[kClosed] = true;
 
@@ -986,3 +1003,5 @@ export class ChangeStream<
     }
   }
 }
+
+configureResourceManagement(ChangeStream.prototype);

package/src/cursor/abstract_cursor.ts

@@ -17,6 +17,7 @@ import { GetMoreOperation } from '../operations/get_more';
 import { KillCursorsOperation } from '../operations/kill_cursors';
 import { ReadConcern, type ReadConcernLike } from '../read_concern';
 import { ReadPreference, type ReadPreferenceLike } from '../read_preference';
+import { type AsyncDisposable, configureResourceManagement } from '../resource_management';
 import type { Server } from '../sdam/server';
 import { ClientSession, maybeClearPinnedConnection } from '../sessions';
 import { type MongoDBNamespace, squashError } from '../utils';
@@ -124,9 +125,12 @@ export type AbstractCursorEvents = {
 
 /** @public */
 export abstract class AbstractCursor<
-  TSchema = any,
-  CursorEvents extends AbstractCursorEvents = AbstractCursorEvents
-> extends TypedEventEmitter<CursorEvents> {
+    TSchema = any,
+    CursorEvents extends AbstractCursorEvents = AbstractCursorEvents
+  >
+  extends TypedEventEmitter<CursorEvents>
+  implements AsyncDisposable
+{
   /** @internal */
   private cursorId: Long | null;
   /** @internal */
@@ -275,14 +279,25 @@ export abstract class AbstractCursor<
     return !!this.cursorClient.topology?.loadBalanced;
   }
 
+  /**
+   * @beta
+   * @experimental
+   * An alias for {@link AbstractCursor.close|AbstractCursor.close()}.
+   */
+  declare [Symbol.asyncDispose]: () => Promise<void>;
+  /** @internal */
+  async asyncDispose() {
+    await this.close();
+  }
+
   /** Returns current buffered documents length */
   bufferedCount(): number {
     return this.documents?.length ?? 0;
   }
 
   /** Returns current buffered documents */
-  readBufferedDocuments(number?: number): TSchema[] {
-    const bufferedDocs: TSchema[] = [];
+  readBufferedDocuments(number?: number): NonNullable<TSchema>[] {
+    const bufferedDocs: NonNullable<TSchema>[] = [];
     const documentsToRead = Math.min(
       number ?? this.documents?.length ?? 0,
       this.documents?.length ?? 0
@@ -297,6 +312,7 @@ export abstract class AbstractCursor<
 
     return bufferedDocs;
   }
+
   async *[Symbol.asyncIterator](): AsyncGenerator<TSchema, void, void> {
     if (this.isClosed) {
       return;
@@ -446,6 +462,9 @@ export abstract class AbstractCursor<
     }
   }
 
+  /**
+   * Frees any client-side resources used by the cursor.
+   */
   async close(): Promise<void> {
     await this.cleanup();
   }
@@ -457,13 +476,22 @@ export abstract class AbstractCursor<
    * cursor.rewind() can be used to reset the cursor.
    */
   async toArray(): Promise<TSchema[]> {
-    const array = [];
+    const array: TSchema[] = [];
+    // at the end of the loop (since readBufferedDocuments is called) the buffer will be empty
+    // then, the 'await of' syntax will run a getMore call
     for await (const document of this) {
       array.push(document);
+      const docs = this.readBufferedDocuments();
+      if (this.transform != null) {
+        for (const doc of docs) {
+          array.push(await this.transformDocument(doc));
+        }
+      } else {
+        array.push(...docs);
+      }
     }
     return array;
   }
-
   /**
    * Add a cursor flag to the cursor
    *
@@ -804,7 +832,7 @@ export abstract class AbstractCursor<
   }
 
   /** @internal */
-  private async transformDocument(document: NonNullable<TSchema>): Promise<TSchema> {
+  private async transformDocument(document: NonNullable<TSchema>): Promise<NonNullable<TSchema>> {
     if (this.transform == null) return document;
 
     try {
@@ -916,3 +944,5 @@ class ReadableCursorStream extends Readable {
     );
   }
 }
+
+configureResourceManagement(AbstractCursor.prototype);

package/src/index.ts

@@ -76,6 +76,7 @@ export {
   MongoWriteConcernError,
   WriteConcernErrorResult
 } from './error';
+export { configureExplicitResourceManagement } from './resource_management';
 export {
   AbstractCursor,
   // Actual driver classes exported
@@ -522,6 +523,7 @@ export type {
   ReadPreferenceLikeOptions,
   ReadPreferenceOptions
 } from './read_preference';
+export type { AsyncDisposable } from './resource_management';
 export type { ClusterTime, TimerQueue } from './sdam/common';
 export type {
   Monitor,

package/src/mongo_client.ts

@@ -34,6 +34,7 @@ import { executeOperation } from './operations/execute_operation';
 import { RunAdminCommandOperation } from './operations/run_command';
 import type { ReadConcern, ReadConcernLevel, ReadConcernLike } from './read_concern';
 import { ReadPreference, type ReadPreferenceMode } from './read_preference';
+import { type AsyncDisposable, configureResourceManagement } from './resource_management';
 import type { ServerMonitoringMode } from './sdam/monitor';
 import type { TagSet } from './sdam/server_description';
 import { readPreferenceServerSelector } from './sdam/server_selection';
@@ -344,7 +345,7 @@ const kOptions = Symbol('options');
  * await client.insertOne({ name: 'spot', kind: 'dog' });
  * ```
  */
-export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
+export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements AsyncDisposable {
   /** @internal */
   s: MongoClientPrivate;
   /** @internal */
@@ -404,6 +405,17 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
     this.checkForNonGenuineHosts();
   }
 
+  /**
+   * @beta
+   * @experimental
+   * An alias for {@link MongoClient.close|MongoClient.close()}.
+   */
+  declare [Symbol.asyncDispose]: () => Promise<void>;
+  /** @internal */
+  async asyncDispose() {
+    await this.close();
+  }
+
   /** @internal */
   private checkForNonGenuineHosts() {
     const documentDBHostnames = this[kOptions].hosts.filter((hostAddress: HostAddress) =>
@@ -570,7 +582,15 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
   }
 
   /**
-   * Close the client and its underlying connections
+   * Cleans up client-side resources used by the MongoCLient and .  This includes:
+   *
+   * - Closes all open, unused connections (see note).
+   * - Ends all in-use sessions with {@link ClientSession#endSession|ClientSession.endSession()}.
+   * - Ends all unused sessions server-side.
+   * - Cleans up any resources being used for auto encryption if auto encryption is enabled.
+   *
+   * @remarks Any in-progress operations are not killed and any connections used by in progress operations
+   * will be cleaned up lazily as operations finish.
    *
    * @param force - Force close, emitting no events
    */
@@ -758,6 +778,8 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
   }
 }
 
+configureResourceManagement(MongoClient.prototype);
+
 /**
  * Parsed Mongo Client Options.
  *

package/src/resource_management.ts

@@ -0,0 +1,74 @@
+/**
+ * @public
+ */
+export interface AsyncDisposable {
+  /**
+   * @beta
+   * @experimental
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+
+  /**
+   * @internal
+   *
+   * A method that wraps disposal semantics for a given resource in the class.
+   */
+  asyncDispose(): Promise<void>;
+}
+
+/** @internal */
+export function configureResourceManagement(target: AsyncDisposable) {
+  Symbol.asyncDispose &&
+    Object.defineProperty(target, Symbol.asyncDispose, {
+      value: async function asyncDispose(this: AsyncDisposable) {
+        await this.asyncDispose();
+      },
+      enumerable: false,
+      configurable: true,
+      writable: true
+    });
+}
+
+/**
+ * @beta
+ * @experimental
+ *
+ * Attaches `Symbol.asyncDispose` methods to the MongoClient, Cursors, sessions and change streams
+ * if Symbol.asyncDispose is defined.
+ *
+ * It's usually not necessary to call this method - the driver attempts to attach these methods
+ * itself when its loaded.  However, sometimes the driver may be loaded before `Symbol.asyncDispose`
+ * is defined, in which case it is necessary to call this method directly.  This can happen if the
+ * application is polyfilling `Symbol.asyncDispose`.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { configureExplicitResourceManagement, MongoClient } from 'mongodb/lib/beta';
+ *
+ * Symbol.asyncDispose ??= Symbol('dispose');
+ * load();
+ *
+ * await using client = new MongoClient(...);
+ * ```
+ */
+export function configureExplicitResourceManagement() {
+  // We must import lazily here, because there's a circular dependency between the resource management
+  // file and each resources' file.  We could move `configureResourceManagement` to a separate
+  // function, but keeping all resource-management related code together seemed preferable and I chose
+  // lazy requiring of resources instead.
+
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { MongoClient } = require('./mongo_client');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { ClientSession } = require('./sessions');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { AbstractCursor } = require('./cursor/abstract_cursor');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { ChangeStream } = require('./change_stream');
+
+  configureResourceManagement(MongoClient.prototype);
+  configureResourceManagement(ClientSession.prototype);
+  configureResourceManagement(AbstractCursor.prototype);
+  configureResourceManagement(ChangeStream.prototype);
+}

package/src/sessions.ts

@@ -27,6 +27,7 @@ import { executeOperation } from './operations/execute_operation';
 import { RunAdminCommandOperation } from './operations/run_command';
 import { ReadConcernLevel } from './read_concern';
 import { ReadPreference } from './read_preference';
+import { type AsyncDisposable, configureResourceManagement } from './resource_management';
 import { _advanceClusterTime, type ClusterTime, TopologyType } from './sdam/common';
 import {
   isTransactionCommand,
@@ -105,7 +106,10 @@ export interface EndSessionOptions {
  * NOTE: not meant to be instantiated directly.
  * @public
  */
-export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
+export class ClientSession
+  extends TypedEventEmitter<ClientSessionEvents>
+  implements AsyncDisposable
+{
   /** @internal */
   client: MongoClient;
   /** @internal */
@@ -255,7 +259,10 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   }
 
   /**
-   * Ends this session on the server
+   * Frees any client-side resources held by the current session.  If a session is in a transaction,
+   * the transaction is aborted.
+   *
+   * Does not end the session on the server.
    *
    * @param options - Optional settings. Currently reserved for future use
    */
@@ -286,6 +293,16 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
       maybeClearPinnedConnection(this, { force: true, ...options });
     }
   }
+  /**
+   * @beta
+   * @experimental
+   * An alias for {@link ClientSession.endSession|ClientSession.endSession()}.
+   */
+  declare [Symbol.asyncDispose]: () => Promise<void>;
+  /** @internal */
+  async asyncDispose() {
+    await this.endSession({ force: true });
+  }
 
   /**
    * Advances the operationTime for a ClientSession.
@@ -484,6 +501,8 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   }
 }
 
+configureResourceManagement(ClientSession.prototype);
+
 const MAX_WITH_TRANSACTION_TIMEOUT = 120000;
 const NON_DETERMINISTIC_WRITE_CONCERN_ERRORS = new Set([
   'CannotSatisfyWriteConcern',