@depup/mongodb 7.5.0-depup.7 → 7.6.0-depup.0

package/src/operations/execute_operation.ts

@@ -170,10 +170,33 @@ type RetryOptions = {
   timeoutContext: TimeoutContext;
 };
 /** @internal The base backoff duration in milliseconds */
-const BASE_BACKOFF_MS = 100;
+export const BASE_BACKOFF_MS = 100;
 /** @internal The maximum backoff duration in milliseconds */
 const MAX_BACKOFF_MS = 10_000;
 
+/**
+ * @internal
+ * The server-supplied base backoff duration in milliseconds, if the error carries a usable one.
+ *
+ * The server may attach `baseBackoffMS` to an overload error to indicate how long clients should
+ * back off in place of the driver's default. Only a positive value is honoured: the server disables
+ * the behaviour by reporting `0`, in which case we fall back to `BASE_BACKOFF_MS`.
+ */
+export function calculateBaseBackoffMS(error: MongoError): number {
+  if (!(error instanceof MongoServerError)) return BASE_BACKOFF_MS;
+
+  // The server sends baseBackoffMS as an int64, so its runtime type depends on the client's BSON
+  // options: a number by default, a Long under `promoteLongs: false`, a bigint under
+  // `useBigInt64: true`. `Number()` handles all three, so coerce rather than check for `number`.
+  // `errorResponse` is indexed as `any`; narrow to `unknown` so the checks below are real.
+  const raw: unknown = error.errorResponse.baseBackoffMS;
+  const isNumeric = typeof raw === 'number' || typeof raw === 'bigint' || typeof raw === 'object';
+  const baseBackoffMS = isNumeric ? Number(raw) : NaN;
+  const useServerValue = Number.isFinite(baseBackoffMS) && baseBackoffMS > 0;
+  const result = useServerValue ? baseBackoffMS : BASE_BACKOFF_MS;
+  return result;
+}
+
 /**
  * Executes an operation and retries as appropriate
  * @internal
@@ -327,7 +350,11 @@ async function executeOperationWithRetries<
       }
 
       if (operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError)) {
-        const backoffMS = Math.random() * Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** attempt);
+        const baseBackoffMS = calculateBaseBackoffMS(operationError);
+        // The spec numbers the first retry as attempt 1, while `attempt` here is the zero-based
+        // index of the attempt that just failed -- hence the `+ 1`.
+        const backoffMS =
+          Math.random() * Math.min(MAX_BACKOFF_MS, baseBackoffMS * 2 ** (attempt + 1));
 
         // if the backoff would exhaust the CSOT timeout, short-circuit.
         if (timeoutContext.csotEnabled() && backoffMS > timeoutContext.remainingTimeMS) {

package/src/operations/find_and_modify.ts

@@ -2,11 +2,11 @@ import { type Connection } from '..';
 import type { Document } from '../bson';
 import { MongoDBResponse } from '../cmap/wire_protocol/responses';
 import type { Collection } from '../collection';
-import { MongoCompatibilityError, MongoInvalidArgumentError } from '../error';
+import { MongoInvalidArgumentError } from '../error';
 import { ReadPreference } from '../read_preference';
 import type { ClientSession } from '../sessions';
 import { formatSort, type Sort, type SortForCmd } from '../sort';
-import { decorateWithCollation, hasAtomicOperators, maxWireVersion } from '../utils';
+import { decorateWithCollation, hasAtomicOperators } from '../utils';
 import { type WriteConcern, type WriteConcernSettings } from '../write_concern';
 import { CommandOperation, type CommandOperationOptions } from './command';
 import { Aspect, defineAspects } from './operation';
@@ -97,11 +97,6 @@ interface FindAndModifyCmdBase {
   writeConcern?: WriteConcern | WriteConcernSettings;
   /**
    * Comment to apply to the operation.
-   *
-   * In server versions pre-4.4, 'comment' must be string.  A server
-   * error will be thrown if any other type is provided.
-   *
-   * In server versions 4.4 and above, 'comment' can be any valid BSON type.
    */
   comment?: unknown;
 }
@@ -146,7 +141,7 @@ export class FindAndModifyOperation extends CommandOperation<Document> {
   }
 
   override buildCommandDocument(
-    connection: Connection,
+    _connection: Connection,
     _session?: ClientSession
   ): Document & FindAndModifyCmdBase {
     const options = this.options;
@@ -191,13 +186,6 @@ export class FindAndModifyOperation extends CommandOperation<Document> {
     decorateWithCollation(command, options);
 
     if (options.hint) {
-      const unacknowledgedWrite = this.writeConcern?.w === 0;
-      if (unacknowledgedWrite && maxWireVersion(connection) < 9) {
-        throw new MongoCompatibilityError(
-          'hint for the findAndModify command is only supported on MongoDB 4.4+'
-        );
-      }
-
       command.hint = options.hint;
     }
 

package/src/operations/get_more.ts

@@ -4,7 +4,7 @@ import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoRuntimeError } from '../error';
 import type { Server, ServerCommandOptions } from '../sdam/server';
 import { type TimeoutContext } from '../timeout';
-import { maxWireVersion, type MongoDBNamespace } from '../utils';
+import { type MongoDBNamespace } from '../utils';
 import { AbstractOperation, Aspect, defineAspects, type OperationOptions } from './operation';
 
 /** @internal */
@@ -13,8 +13,6 @@ export interface GetMoreOptions extends OperationOptions {
   batchSize?: number;
   /**
    * Comment to apply to the operation.
-   *
-   * getMore only supports 'comment' in server versions 4.4 and above.
    */
   comment?: unknown;
   /** Number of milliseconds to wait before aborting the query. */
@@ -55,7 +53,7 @@ export class GetMoreOperation extends AbstractOperation<CursorResponse> {
     return 'getMore' as const;
   }
 
-  override buildCommand(connection: Connection): Document {
+  override buildCommand(_connection: Connection): Document {
     if (this.cursorId == null || this.cursorId.isZero()) {
       throw new MongoRuntimeError('Unable to iterate cursor with no id');
     }
@@ -82,7 +80,7 @@ export class GetMoreOperation extends AbstractOperation<CursorResponse> {
 
     // we check for undefined specifically here to allow falsy values
     // eslint-disable-next-line no-restricted-syntax
-    if (this.options.comment !== undefined && maxWireVersion(connection) >= 9) {
+    if (this.options.comment !== undefined) {
       getMoreCmd.comment = this.options.comment;
     }
 

package/src/operations/indexes.ts

@@ -3,9 +3,8 @@ import { type Connection } from '../cmap/connection';
 import { CursorResponse, MongoDBResponse } from '../cmap/wire_protocol/responses';
 import type { Collection } from '../collection';
 import { type AbstractCursorOptions } from '../cursor/abstract_cursor';
-import { MongoCompatibilityError } from '../error';
 import { type OneOrMore } from '../mongo_types';
-import { isObject, maxWireVersion, type MongoDBNamespace } from '../utils';
+import { isObject, type MongoDBNamespace } from '../utils';
 import {
   type CollationOptions,
   CommandOperation,
@@ -138,7 +137,7 @@ export interface CreateIndexesOptions extends Omit<CommandOperationOptions, 'wri
   expireAfterSeconds?: number;
   /** Allows users to configure the storage engine on a per-index basis when creating an index. (MongoDB 3.0 or higher) */
   storageEngine?: Document;
-  /** (MongoDB 4.4. or higher) Specifies how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. This option accepts the same values for the "w" field in a write concern plus "votingMembers", which indicates all voting data-bearing nodes. */
+  /** Specifies how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. This option accepts the same values for the "w" field in a write concern plus "votingMembers", which indicates all voting data-bearing nodes. */
   commitQuorum?: number | string;
   /** Specifies the index version number, either 0 or 1. */
   version?: number;
@@ -159,7 +158,7 @@ export interface CreateIndexesOptions extends Omit<CommandOperationOptions, 'wri
   bucketSize?: number;
   // wildcard indexes
   wildcardProjection?: Document;
-  /** Specifies that the index should exist on the target collection but should not be used by the query planner when executing operations. (MongoDB 4.4 or higher) */
+  /** Specifies that the index should exist on the target collection but should not be used by the query planner when executing operations. */
   hidden?: boolean;
 }
 
@@ -299,20 +298,13 @@ export class CreateIndexesOperation extends CommandOperation<string[]> {
     return 'createIndexes';
   }
 
-  override buildCommandDocument(connection: Connection): Document {
+  override buildCommandDocument(_connection: Connection): Document {
     const options = this.options;
     const indexes = this.indexes;
 
-    const serverWireVersion = maxWireVersion(connection);
-
     const cmd: Document = { createIndexes: this.collectionName, indexes };
 
     if (options.commitQuorum != null) {
-      if (serverWireVersion < 9) {
-        throw new MongoCompatibilityError(
-          'Option `commitQuorum` for `createIndexes` not supported on servers < 4.4'
-        );
-      }
       cmd.commitQuorum = options.commitQuorum;
     }
     return cmd;
@@ -385,16 +377,14 @@ export class ListIndexesOperation extends CommandOperation<CursorResponse> {
     return 'listIndexes' as const;
   }
 
-  override buildCommandDocument(connection: Connection): Document {
-    const serverWireVersion = maxWireVersion(connection);
-
+  override buildCommandDocument(_connection: Connection): Document {
     const cursor = this.options.batchSize ? { batchSize: this.options.batchSize } : {};
 
     const command: Document = { listIndexes: this.collectionNamespace.collection, cursor };
 
     // we check for undefined specifically here to allow falsy values
     // eslint-disable-next-line no-restricted-syntax
-    if (serverWireVersion >= 9 && this.options.comment !== undefined) {
+    if (this.options.comment !== undefined) {
       command.comment = this.options.comment;
     }
 

package/src/operations/insert.ts

@@ -1,6 +1,7 @@
 import { type Connection } from '..';
 import type { Document } from '../bson';
 import type { BulkWriteOptions } from '../bulk/common';
+import { makeDocumentSequence } from '../cmap/commands';
 import { MongoDBResponse } from '../cmap/wire_protocol/responses';
 import type { Collection } from '../collection';
 import { MongoServerError } from '../error';
@@ -15,12 +16,20 @@ export class InsertOperation extends CommandOperation<Document> {
   override options: BulkWriteOptions;
 
   documents: Document[];
+  /** @internal Per-operation pre-serialized BSON, reused to build a DocumentSequence. */
+  serializedOperations?: Uint8Array[];
 
-  constructor(ns: MongoDBNamespace, documents: Document[], options: BulkWriteOptions) {
+  constructor(
+    ns: MongoDBNamespace,
+    documents: Document[],
+    options: BulkWriteOptions,
+    serializedOperations?: Uint8Array[]
+  ) {
     super(undefined, options);
     this.options = { ...options, checkKeys: options.checkKeys ?? false };
     this.ns = ns;
     this.documents = documents;
+    this.serializedOperations = serializedOperations;
   }
 
   override get commandName() {
@@ -32,7 +41,9 @@ export class InsertOperation extends CommandOperation<Document> {
     const ordered = typeof options.ordered === 'boolean' ? options.ordered : true;
     const command: Document = {
       insert: this.ns.collection,
-      documents: this.documents,
+      documents: this.serializedOperations
+        ? makeDocumentSequence('documents', this.documents, this.serializedOperations)
+        : this.documents,
       ordered
     };
 

package/src/operations/list_collections.ts

@@ -4,7 +4,6 @@ import { CursorResponse, ExplainedCursorResponse } from '../cmap/wire_protocol/r
 import { type CursorTimeoutContext, type CursorTimeoutMode } from '../cursor/abstract_cursor';
 import type { Db } from '../db';
 import { type Abortable } from '../mongo_types';
-import { maxWireVersion } from '../utils';
 import { CommandOperation, type CommandOperationOptions } from './command';
 import { Aspect, defineAspects } from './operation';
 
@@ -12,11 +11,11 @@ import { Aspect, defineAspects } from './operation';
 export interface ListCollectionsOptions
   extends Omit<CommandOperationOptions, 'writeConcern'>,
     Abortable {
-  /** Since 4.0: If true, will only return the collection name in the response, and will omit additional info */
+  /** If true, will only return the collection name in the response, and will omit additional info */
   nameOnly?: boolean;
-  /** Since 4.0: If true and nameOnly is true, allows a user without the required privilege (i.e. listCollections action on the database) to run the command when access control is enforced. */
+  /** If true and nameOnly is true, allows a user without the required privilege (i.e. listCollections action on the database) to run the command when access control is enforced. */
   authorizedCollections?: boolean;
-  /** The batchSize for the returned command cursor or if pre 2.8 the systems batch collection */
+  /** The batchSize for the returned command cursor */
   batchSize?: number;
   /** @internal */
   timeoutMode?: CursorTimeoutMode;
@@ -63,7 +62,7 @@ export class ListCollectionsOperation extends CommandOperation<CursorResponse> {
     return 'listCollections' as const;
   }
 
-  override buildCommandDocument(connection: Connection): Document {
+  override buildCommandDocument(_connection: Connection): Document {
     const command: Document = {
       listCollections: 1,
       filter: this.filter,
@@ -74,7 +73,7 @@ export class ListCollectionsOperation extends CommandOperation<CursorResponse> {
 
     // we check for undefined specifically here to allow falsy values
     // eslint-disable-next-line no-restricted-syntax
-    if (maxWireVersion(connection) >= 9 && this.options.comment !== undefined) {
+    if (this.options.comment !== undefined) {
       command.comment = this.options.comment;
     }
 

package/src/operations/list_databases.ts

@@ -3,7 +3,7 @@ import type { Document } from '../bson';
 import { MongoDBResponse } from '../cmap/wire_protocol/responses';
 import type { Db } from '../db';
 import type { ClientSession } from '../sessions';
-import { maxWireVersion, MongoDBNamespace } from '../utils';
+import { MongoDBNamespace } from '../utils';
 import { CommandOperation, type CommandOperationOptions } from './command';
 import { Aspect, defineAspects } from './operation';
 
@@ -40,7 +40,7 @@ export class ListDatabasesOperation extends CommandOperation<ListDatabasesResult
     return 'listDatabases' as const;
   }
 
-  override buildCommandDocument(connection: Connection, _session?: ClientSession): Document {
+  override buildCommandDocument(_connection: Connection, _session?: ClientSession): Document {
     const cmd: Document = { listDatabases: 1 };
 
     if (typeof this.options.nameOnly === 'boolean') {
@@ -57,7 +57,7 @@ export class ListDatabasesOperation extends CommandOperation<ListDatabasesResult
 
     // we check for undefined specifically here to allow falsy values
     // eslint-disable-next-line no-restricted-syntax
-    if (maxWireVersion(connection) >= 9 && this.options.comment !== undefined) {
+    if (this.options.comment !== undefined) {
       cmd.comment = this.options.comment;
     }
 

package/src/operations/update.ts

@@ -1,4 +1,5 @@
 import type { Document } from '../bson';
+import { makeDocumentSequence } from '../cmap/commands';
 import { type Connection } from '../cmap/connection';
 import { MongoDBResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError, MongoServerError } from '../error';
@@ -74,17 +75,21 @@ export class UpdateOperation extends CommandOperation<Document> {
   override SERVER_COMMAND_RESPONSE_TYPE = MongoDBResponse;
   override options: UpdateOptions & { ordered?: boolean };
   statements: UpdateStatement[];
+  /** @internal */
+  serializedOperations?: Uint8Array[];
 
   constructor(
     ns: MongoDBNamespace,
     statements: UpdateStatement[],
-    options: UpdateOptions & { ordered?: boolean }
+    options: UpdateOptions & { ordered?: boolean },
+    serializedOperations?: Uint8Array[]
   ) {
     super(undefined, options);
     this.options = options;
     this.ns = ns;
 
     this.statements = statements;
+    this.serializedOperations = serializedOperations;
   }
 
   override get commandName() {
@@ -103,7 +108,9 @@ export class UpdateOperation extends CommandOperation<Document> {
     const options = this.options;
     const command: Document = {
       update: this.ns.collection,
-      updates: this.statements,
+      updates: this.serializedOperations
+        ? makeDocumentSequence('updates', this.statements, this.serializedOperations)
+        : this.statements,
       ordered: options.ordered ?? true
     };
 

package/src/operations/validate_collection.ts

@@ -8,7 +8,7 @@ import { CommandOperation, type CommandOperationOptions } from './command';
 
 /** @public */
 export interface ValidateCollectionOptions extends Omit<CommandOperationOptions, 'rawData'> {
-  /** Validates a collection in the background, without interrupting read or write traffic (only in MongoDB 4.4+) */
+  /** Validates a collection in the background, without interrupting read or write traffic */
   background?: boolean;
 }
 

package/src/runtime_adapters.ts

@@ -1,8 +1,9 @@
 /* eslint-disable no-restricted-imports*/
 
-// We squash the restricted import errors here because we are using type-only imports, which
-// do not impact the driver's actual runtime dependencies.
-// We also allow restricted imports in this file, because we expect this file to be the only place actually importing restricted Node APIs.
+// We squash the restricted import errors here: the module-scope imports are type-only, and the
+// one runtime dependency this file takes — the dynamic `import('os')` fallback in
+// resolveRuntimeAdapters — is deliberate: this file is expected to be the only place that loads
+// restricted Node APIs at runtime.
 
 import type * as os from 'os';
 
@@ -11,8 +12,9 @@ import { type MongoClientOptions } from './mongo_client';
 /**
  * @internal
  *
- * This propery can be set on the global object to allow the driver to require otherwise blocked modules.
- * This is used by our test suite to allow tests to access the `os` module without allowing user code to do so.
+ * Legacy escape hatch for the test sandbox's restricted `require`: the driver no longer sets this
+ * property (the os adapter loads via dynamic `import()`), but the vm test harness
+ * still checks it. Kept until the sandbox contract is revisited in a follow-up.
  */
 export const ALLOWED_DRIVER_REQUIRE_PROPERTY_NAME = 'allowedDriverRequire';
 
@@ -47,18 +49,17 @@ export interface Runtime {
 /**
  * @internal
  *
- * Given a MongoClientOptions, this function resolves the set of runtime options, providing Nodejs implementations if
- * not provided by in `options`, and returns a `Runtime`.
+ * Given a MongoClientOptions, this function resolves the set of runtime options, providing Nodejs
+ * implementations if not provided in `options`, and returns a `Runtime`.
+ *
+ * Resolution is asynchronous because the default `os` adapter is loaded via a dynamic `import()`.
+ * Unlike `require`, dynamic import exists in every module system the driver ships into or is
+ * bundled into (CJS, ESM, and bundled ESM output), and the literal specifier keeps it
+ * statically analyzable for bundlers. The promise is created during synchronous
+ * options parsing and awaited later by consumers, so the public constructor stays synchronous.
  */
-export function resolveRuntimeAdapters(options: MongoClientOptions): Runtime {
-  (globalThis as any)[ALLOWED_DRIVER_REQUIRE_PROPERTY_NAME] = true;
-  try {
-    const runtime = {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      os: options.runtimeAdapters?.os ?? require('os')
-    };
-    return runtime;
-  } finally {
-    (globalThis as any)[ALLOWED_DRIVER_REQUIRE_PROPERTY_NAME] = false;
-  }
+export async function resolveRuntimeAdapters(options: MongoClientOptions): Promise<Runtime> {
+  return {
+    os: options.runtimeAdapters?.os ?? (await import('os'))
+  };
 }

package/src/sdam/server.ts

@@ -494,7 +494,7 @@ export class Server extends TypedEventEmitter<ServerEvents> {
     } else {
       if (
         (isRetryableWritesEnabled(this.topology) || isTransactionCommand(cmd)) &&
-        needsRetryableWriteLabel(error, maxWireVersion(this), this.description.type) &&
+        needsRetryableWriteLabel(error) &&
         !inActiveTransaction(session, cmd)
       ) {
         error.addErrorLabel(MongoErrorLabel.RetryableWriteError);

package/src/sessions.ts

@@ -771,7 +771,7 @@ export class ClientSession
       ) {
         // 2. If `transactionAttempt` > 0:
         if (isRetry) {
-          // 2.1 Calculate backoffMS to be jitter * min(BACKOFF_INITIAL * 1.5 ** (transactionAttempt - 1), BACKOFF_MAX).
+          // 2.1 Calculate backoffMS to be jitter * min(BACKOFF_INITIAL * 1.5 ** (transactionAttempt), BACKOFF_MAX).
           //  If elapsed time + backoffMS > TIMEOUT_MS, then propagate the previously encountered error to the caller of
           //  withTransaction as per timeout error propagation and return immediately. Otherwise, sleep for backoffMS.
           //  2.1.1 jitter is a random float between [0, 1), optionally including 1, depending on what is most natural
@@ -785,10 +785,7 @@ export class ClientSession
           const jitter = Math.random();
           const backoffMS =
             jitter *
-            Math.min(
-              BACKOFF_INITIAL_MS * BACKOFF_GROWTH ** (transactionAttempt - 1),
-              BACKOFF_MAX_MS
-            );
+            Math.min(BACKOFF_INITIAL_MS * BACKOFF_GROWTH ** transactionAttempt, BACKOFF_MAX_MS);
 
           if (processTimeMS() + backoffMS >= deadline) {
             throw makeTimeoutError(

package/src/utils.ts

@@ -343,9 +343,7 @@ export function maxWireVersion(handshakeAware?: Connection | Topology | Server):
     // object being checked will be a connection, and we will have a hello response on
     // it. For other cases, such as retryable writes, the object will be a server or
     // topology, and there will be no hello response on those objects, so we return
-    // the max wire version so we support retryability. Once we have a min supported
-    // wire version of 9, then the needsRetryableWriteLabel() check can remove the
-    // usage of passing the wire version into it.
+    // the max wire version so we support retryability.
     if (handshakeAware.loadBalanced) {
       return MAX_SUPPORTED_WIRE_VERSION;
     }

package/tsconfig.json

@@ -5,8 +5,15 @@
     "strict": true,
     "alwaysStrict": true,
     "target": "ES2023",
-    "module": "commonJS",
-    "moduleResolution": "node",
+    // node16 still emits CommonJS for this package (no "type": "module") but, unlike
+    // `module: commonjs`, models Node's real semantics: dynamic `import()` is legal inside CJS
+    // and is preserved verbatim instead of being downleveled to `require()` (NODE-7603).
+    "module": "node16",
+    "moduleResolution": "node16",
+    // node16 defaults esModuleInterop on; keep it off to preserve this package's historical
+    // emit exactly (`import * as x` stays `const x = require(...)`, no __importStar wrappers —
+    // which sinon-based module stubbing in the test suite also relies on).
+    "esModuleInterop": false,
     "skipLibCheck": true,
     "lib": [
       "es2023"