mongodb 6.8.0-dev.20240731.sha.b26c3280 → 6.8.0-dev.20240808.sha.5565d500

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';
@@ -104,7 +105,7 @@ export type SupportedTLSSocketOptions = Pick<
 
 /** @public */
 export type SupportedSocketOptions = Pick<
-  TcpNetConnectOpts,
+  TcpNetConnectOpts & { autoSelectFamily?: boolean; autoSelectFamilyAttemptTimeout?: number },
   (typeof LEGAL_TCP_SOCKET_OPTIONS)[number]
 >;
 
@@ -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',