docs: connect

Author: nbbeeken

src/mongo_client.ts

@@ -594,20 +594,13 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
   }
 
   /**
-   * Connect to MongoDB using a url
+   * An optional method to verify a typical set of preconditions before using a MongoClient.
+   * For detailed information about the connect process see the MongoClient.connect static method documentation.
    *
-   * @remarks
-   * Calling `connect` is optional since the first operation you perform will call `connect` if it's needed.
-   * `timeoutMS` will bound the time any operation can take before throwing a timeout error.
-   * However, when the operation being run is automatically connecting your `MongoClient` the `timeoutMS` will not apply to the time taken to connect the MongoClient.
-   * This means the time to setup the `MongoClient` does not count against `timeoutMS`.
-   * If you are using `timeoutMS` we recommend connecting your client explicitly in advance of any operation to avoid this inconsistent execution time.
-   *
-   * @remarks
-   * The driver will look up corresponding SRV and TXT records if the connection string starts with `mongodb+srv://`.
-   * If those look ups throw a DNS Timeout error, the driver will retry the look up once.
+   * @param url - The MongoDB connection string (supports `mongodb://` and `mongodb+srv://` schemes)
+   * @param options - Optional configuration options for the client
    *
-   * @see docs.mongodb.org/manual/reference/connection-string/
+   * @see https://www.mongodb.com/docs/manual/reference/connection-string/
    */
   async connect(): Promise<this> {
     if (this.connectionLock) {
@@ -868,21 +861,35 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
   }
 
   /**
-   * Connect to MongoDB using a url
+   * Creates a new MongoClient instance and immediately connects it to MongoDB.
+   * This convenience method combines `new MongoClient(url, options)` and `client.connect()` in a single step.
+   *
+   * Connect can be helpful to detect configuration issues early by validating:
+   * - **DNS Resolution**: Verifies that SRV records and hostnames in the connection string resolve DNS entries
+   * - **Network Connectivity**: Confirms that host addresses are reachable and ports are open
+   * - **TLS Configuration**: Validates SSL/TLS certificates, CA files, and encryption settings are correct
+   * - **Authentication**: Verifies that provided credentials are valid
+   * - **Server Compatibility**: Ensures the MongoDB server version is supported by this driver version
+   * - **Load Balancer Setup**: For load-balanced deployments, confirms the service is properly configured
+   *
+   * @returns A promise that resolves to the same MongoClient instance once connected
    *
    * @remarks
-   * Calling `connect` is optional since the first operation you perform will call `connect` if it's needed.
-   * `timeoutMS` will bound the time any operation can take before throwing a timeout error.
-   * However, when the operation being run is automatically connecting your `MongoClient` the `timeoutMS` will not apply to the time taken to connect the MongoClient.
-   * This means the time to setup the `MongoClient` does not count against `timeoutMS`.
-   * If you are using `timeoutMS` we recommend connecting your client explicitly in advance of any operation to avoid this inconsistent execution time.
+   * **Connection is Optional:** Calling `connect` is optional since any operation method (`find`, `insertOne`, etc.)
+   * will automatically perform these same validation steps if the client is not already connected.
+   * However, explicitly calling `connect` can make sense for:
+   * - **Fail-fast Error Detection**: Non-transient connection issues (hostname unresolved, port refused connection) are discovered immediately rather than during your first operation
+   * - **Predictable Performance**: Eliminates first connection overhead from your first database operation
    *
    * @remarks
-   * The programmatically provided options take precedence over the URI options.
+   * **Connection Pooling Impact:** Calling `connect` will populate the connection pool with one connection
+   * to a server selected by the client's configured `readPreference` (defaults to primary).
    *
    * @remarks
-   * The driver will look up corresponding SRV and TXT records if the connection string starts with `mongodb+srv://`.
-   * If those look ups throw a DNS Timeout error, the driver will retry the look up once.
+   * **Timeout Behavior:** When using `timeoutMS`, the connection establishment time does not count against
+   * the timeout for subsequent operations. This means `connect` runs without a `timeoutMS` limit, while
+   * your database operations will still respect the configured timeout. If you need predictable operation
+   * timing with `timeoutMS`, call `connect` explicitly before performing operations.
    *
    * @see https://www.mongodb.com/docs/manual/reference/connection-string/
    */