mongodb 6.5.0-dev.20240424.sha.6abc074 → 6.5.0-dev.20240502.sha.9d73f45

package/src/cmap/wire_protocol/on_demand/document.ts

@@ -58,7 +58,7 @@ export class OnDemandDocument {
   private readonly indexFound: Record<number, boolean> = Object.create(null);
 
   /** All bson elements in this document */
-  private readonly elements: BSONElement[];
+  private readonly elements: ReadonlyArray<BSONElement>;
 
   constructor(
     /** BSON bytes, this document begins at offset */
@@ -97,7 +97,7 @@ export class OnDemandDocument {
    * @param name - a basic latin string name of a BSON element
    * @returns
    */
-  private getElement(name: string): CachedBSONElement | null {
+  private getElement(name: string | number): CachedBSONElement | null {
     const cachedElement = this.cache[name];
     if (cachedElement === false) return null;
 
@@ -105,6 +105,22 @@ export class OnDemandDocument {
       return cachedElement;
     }
 
+    if (typeof name === 'number') {
+      if (this.isArray) {
+        if (name < this.elements.length) {
+          const element = this.elements[name];
+          const cachedElement = { element, value: undefined };
+          this.cache[name] = cachedElement;
+          this.indexFound[name] = true;
+          return cachedElement;
+        } else {
+          return null;
+        }
+      } else {
+        return null;
+      }
+    }
+
     for (let index = 0; index < this.elements.length; index++) {
       const element = this.elements[index];
 
@@ -197,6 +213,13 @@ export class OnDemandDocument {
     }
   }
 
+  /**
+   * Returns the number of elements in this BSON document
+   */
+  public size() {
+    return this.elements.length;
+  }
+
   /**
    * Checks for the existence of an element by name.
    *
@@ -222,16 +245,20 @@ export class OnDemandDocument {
    * @param required - whether or not the element is expected to exist, if true this function will throw if it is not present
    */
   public get<const T extends keyof JSTypeOf>(
-    name: string,
+    name: string | number,
     as: T,
     required?: false | undefined
   ): JSTypeOf[T] | null;
 
   /** `required` will make `get` throw if name does not exist or is null/undefined */
-  public get<const T extends keyof JSTypeOf>(name: string, as: T, required: true): JSTypeOf[T];
+  public get<const T extends keyof JSTypeOf>(
+    name: string | number,
+    as: T,
+    required: true
+  ): JSTypeOf[T];
 
   public get<const T extends keyof JSTypeOf>(
-    name: string,
+    name: string | number,
     as: T,
     required?: boolean
   ): JSTypeOf[T] | null {
@@ -303,21 +330,9 @@ export class OnDemandDocument {
     });
   }
 
-  /**
-   * Iterates through the elements of a document reviving them using the `as` BSONType.
-   *
-   * @param as - The type to revive all elements as
-   */
-  public *valuesAs<const T extends keyof JSTypeOf>(as: T): Generator<JSTypeOf[T]> {
-    if (!this.isArray) {
-      throw new BSONError('Unexpected conversion of non-array value to array');
-    }
-    let counter = 0;
-    for (const element of this.elements) {
-      const value = this.toJSValue<T>(element, as);
-      this.cache[counter] = { element, value };
-      yield value;
-      counter += 1;
-    }
+  /** Returns this document's bytes only */
+  toBytes() {
+    const size = getInt32LE(this.bson, this.offset);
+    return this.bson.subarray(this.offset, this.offset + size);
   }
 }

package/src/cmap/wire_protocol/responses.ts

@@ -1,7 +1,62 @@
-import { type BSONSerializeOptions, BSONType, type Document, type Timestamp } from '../../bson';
+import {
+  type BSONSerializeOptions,
+  BSONType,
+  type Document,
+  Long,
+  parseToElementsToArray,
+  type Timestamp
+} from '../../bson';
+import { MongoUnexpectedServerResponseError } from '../../error';
 import { type ClusterTime } from '../../sdam/common';
+import { type MongoDBNamespace, ns } from '../../utils';
 import { OnDemandDocument } from './on_demand/document';
 
+// eslint-disable-next-line no-restricted-syntax
+const enum BSONElementOffset {
+  type = 0,
+  nameOffset = 1,
+  nameLength = 2,
+  offset = 3,
+  length = 4
+}
+/**
+ * Accepts a BSON payload and checks for na "ok: 0" element.
+ * This utility is intended to prevent calling response class constructors
+ * that expect the result to be a success and demand certain properties to exist.
+ *
+ * For example, a cursor response always expects a cursor embedded document.
+ * In order to write the class such that the properties reflect that assertion (non-null)
+ * we cannot invoke the subclass constructor if the BSON represents an error.
+ *
+ * @param bytes - BSON document returned from the server
+ */
+export function isErrorResponse(bson: Uint8Array): boolean {
+  const elements = parseToElementsToArray(bson, 0);
+  for (let eIdx = 0; eIdx < elements.length; eIdx++) {
+    const element = elements[eIdx];
+
+    if (element[BSONElementOffset.nameLength] === 2) {
+      const nameOffset = element[BSONElementOffset.nameOffset];
+
+      // 111 == "o", 107 == "k"
+      if (bson[nameOffset] === 111 && bson[nameOffset + 1] === 107) {
+        const valueOffset = element[BSONElementOffset.offset];
+        const valueLength = element[BSONElementOffset.length];
+
+        // If any byte in the length of the ok number (works for any type) is non zero,
+        // then it is considered "ok: 1"
+        for (let i = valueOffset; i < valueOffset + valueLength; i++) {
+          if (bson[i] !== 0x00) return false;
+        }
+
+        return true;
+      }
+    }
+  }
+
+  return true;
+}
+
 /** @internal */
 export type MongoDBResponseConstructor = {
   new (bson: Uint8Array, offset?: number, isArray?: boolean): MongoDBResponse;
@@ -9,6 +64,10 @@ export type MongoDBResponseConstructor = {
 
 /** @internal */
 export class MongoDBResponse extends OnDemandDocument {
+  static is(value: unknown): value is MongoDBResponse {
+    return value instanceof MongoDBResponse;
+  }
+
   // {ok:1}
   static empty = new MongoDBResponse(new Uint8Array([13, 0, 0, 0, 16, 111, 107, 0, 1, 0, 0, 0, 0]));
 
@@ -83,27 +142,96 @@ export class MongoDBResponse extends OnDemandDocument {
     return this.clusterTime ?? null;
   }
 
-  public override toObject(options: BSONSerializeOptions = {}): Record<string, any> {
+  public override toObject(options?: BSONSerializeOptions): Record<string, any> {
     const exactBSONOptions = {
-      useBigInt64: options.useBigInt64,
-      promoteLongs: options.promoteLongs,
-      promoteValues: options.promoteValues,
-      promoteBuffers: options.promoteBuffers,
-      bsonRegExp: options.bsonRegExp,
-      raw: options.raw ?? false,
-      fieldsAsRaw: options.fieldsAsRaw ?? {},
+      useBigInt64: options?.useBigInt64,
+      promoteLongs: options?.promoteLongs,
+      promoteValues: options?.promoteValues,
+      promoteBuffers: options?.promoteBuffers,
+      bsonRegExp: options?.bsonRegExp,
+      raw: options?.raw ?? false,
+      fieldsAsRaw: options?.fieldsAsRaw ?? {},
       validation: this.parseBsonSerializationOptions(options)
     };
     return super.toObject(exactBSONOptions);
   }
 
-  private parseBsonSerializationOptions({ enableUtf8Validation }: BSONSerializeOptions): {
+  private parseBsonSerializationOptions(options?: { enableUtf8Validation?: boolean }): {
     utf8: { writeErrors: false } | false;
   } {
+    const enableUtf8Validation = options?.enableUtf8Validation;
     if (enableUtf8Validation === false) {
       return { utf8: false };
     }
-
     return { utf8: { writeErrors: false } };
   }
 }
+
+/** @internal */
+export class CursorResponse extends MongoDBResponse {
+  /**
+   * This supports a feature of the FindCursor.
+   * It is an optimization to avoid an extra getMore when the limit has been reached
+   */
+  static emptyGetMore = { id: new Long(0), length: 0, shift: () => null };
+
+  static override is(value: unknown): value is CursorResponse {
+    return value instanceof CursorResponse || value === CursorResponse.emptyGetMore;
+  }
+
+  public id: Long;
+  public ns: MongoDBNamespace | null = null;
+  public batchSize = 0;
+
+  private batch: OnDemandDocument;
+  private iterated = 0;
+
+  constructor(bytes: Uint8Array, offset?: number, isArray?: boolean) {
+    super(bytes, offset, isArray);
+
+    const cursor = this.get('cursor', BSONType.object, true);
+
+    const id = cursor.get('id', BSONType.long, true);
+    this.id = new Long(Number(id & 0xffff_ffffn), Number((id >> 32n) & 0xffff_ffffn));
+
+    const namespace = cursor.get('ns', BSONType.string);
+    if (namespace != null) this.ns = ns(namespace);
+
+    if (cursor.has('firstBatch')) this.batch = cursor.get('firstBatch', BSONType.array, true);
+    else if (cursor.has('nextBatch')) this.batch = cursor.get('nextBatch', BSONType.array, true);
+    else throw new MongoUnexpectedServerResponseError('Cursor document did not contain a batch');
+
+    this.batchSize = this.batch.size();
+  }
+
+  get length() {
+    return Math.max(this.batchSize - this.iterated, 0);
+  }
+
+  shift(options?: BSONSerializeOptions): any {
+    if (this.iterated >= this.batchSize) {
+      return null;
+    }
+
+    const result = this.batch.get(this.iterated, BSONType.object, true) ?? null;
+    this.iterated += 1;
+
+    if (options?.raw) {
+      return result.toBytes();
+    } else {
+      return result.toObject(options);
+    }
+  }
+
+  clear() {
+    this.iterated = this.batchSize;
+  }
+
+  pushMany() {
+    throw new Error('pushMany Unsupported method');
+  }
+
+  push() {
+    throw new Error('push Unsupported method');
+  }
+}

package/src/cursor/abstract_cursor.ts

@@ -1,6 +1,7 @@
 import { Readable, Transform } from 'stream';
 
 import { type BSONSerializeOptions, type Document, Long, pluckBSONSerializeOptions } from '../bson';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
 import {
   type AnyError,
   MongoAPIError,
@@ -144,7 +145,13 @@ export abstract class AbstractCursor<
   /** @internal */
   [kNamespace]: MongoDBNamespace;
   /** @internal */
-  [kDocuments]: List<TSchema>;
+  [kDocuments]: {
+    length: number;
+    shift(bsonOptions?: any): TSchema | null;
+    clear(): void;
+    pushMany(many: Iterable<TSchema>): void;
+    push(item: TSchema): void;
+  };
   /** @internal */
   [kClient]: MongoClient;
   /** @internal */
@@ -286,7 +293,7 @@ export abstract class AbstractCursor<
     const documentsToRead = Math.min(number ?? this[kDocuments].length, this[kDocuments].length);
 
     for (let count = 0; count < documentsToRead; count++) {
-      const document = this[kDocuments].shift();
+      const document = this[kDocuments].shift(this[kOptions]);
       if (document != null) {
         bufferedDocs.push(document);
       }
@@ -382,14 +389,7 @@ export abstract class AbstractCursor<
       return true;
     }
 
-    const doc = await next<TSchema>(this, { blocking: true, transform: false });
-
-    if (doc) {
-      this[kDocuments].unshift(doc);
-      return true;
-    }
-
-    return false;
+    return await next(this, { blocking: true, transform: false, shift: false });
   }
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
@@ -398,7 +398,7 @@ export abstract class AbstractCursor<
       throw new MongoCursorExhaustedError();
     }
 
-    return await next(this, { blocking: true, transform: true });
+    return await next(this, { blocking: true, transform: true, shift: true });
   }
 
   /**
@@ -409,7 +409,7 @@ export abstract class AbstractCursor<
       throw new MongoCursorExhaustedError();
     }
 
-    return await next(this, { blocking: false, transform: true });
+    return await next(this, { blocking: false, transform: true, shift: true });
   }
 
   /**
@@ -633,12 +633,13 @@ export abstract class AbstractCursor<
   protected abstract _initialize(session: ClientSession | undefined): Promise<ExecutionResult>;
 
   /** @internal */
-  async getMore(batchSize: number): Promise<Document | null> {
+  async getMore(batchSize: number, useCursorResponse = false): Promise<Document | null> {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const getMoreOperation = new GetMoreOperation(this[kNamespace], this[kId]!, this[kServer]!, {
       ...this[kOptions],
       session: this[kSession],
-      batchSize
+      batchSize,
+      useCursorResponse
     });
 
     return await executeOperation(this[kClient], getMoreOperation);
@@ -656,7 +657,11 @@ export abstract class AbstractCursor<
       const state = await this._initialize(this[kSession]);
       const response = state.response;
       this[kServer] = state.server;
-      if (response.cursor) {
+      if (CursorResponse.is(response)) {
+        this[kId] = response.id;
+        if (response.ns) this[kNamespace] = response.ns;
+        this[kDocuments] = response;
+      } else if (response.cursor) {
         // TODO(NODE-2674): Preserve int64 sent from MongoDB
         this[kId] =
           typeof response.cursor.id === 'number'
@@ -713,13 +718,42 @@ async function next<T>(
   cursor: AbstractCursor<T>,
   {
     blocking,
-    transform
+    transform,
+    shift
   }: {
     blocking: boolean;
     transform: boolean;
+    shift: false;
   }
-): Promise<T | null> {
+): Promise<boolean>;
+
+async function next<T>(
+  cursor: AbstractCursor<T>,
+  {
+    blocking,
+    transform,
+    shift
+  }: {
+    blocking: boolean;
+    transform: boolean;
+    shift: true;
+  }
+): Promise<T | null>;
+
+async function next<T>(
+  cursor: AbstractCursor<T>,
+  {
+    blocking,
+    transform,
+    shift
+  }: {
+    blocking: boolean;
+    transform: boolean;
+    shift: boolean;
+  }
+): Promise<boolean | T | null> {
   if (cursor.closed) {
+    if (!shift) return false;
     return null;
   }
 
@@ -730,7 +764,8 @@ async function next<T>(
     }
 
     if (cursor[kDocuments].length !== 0) {
-      const doc = cursor[kDocuments].shift();
+      if (!shift) return true;
+      const doc = cursor[kDocuments].shift(cursor[kOptions]);
 
       if (doc != null && transform && cursor[kTransform]) {
         try {
@@ -754,6 +789,7 @@ async function next<T>(
       // cleanupCursor should never throw, but if it does it indicates a bug in the driver
       // and we should surface the error
       await cleanupCursor(cursor, {});
+      if (!shift) return false;
       return null;
     }
 
@@ -762,8 +798,10 @@ async function next<T>(
 
     try {
       const response = await cursor.getMore(batchSize);
-
-      if (response) {
+      if (CursorResponse.is(response)) {
+        cursor[kId] = response.id;
+        cursor[kDocuments] = response;
+      } else if (response) {
         const cursorId =
           typeof response.cursor.id === 'number'
             ? Long.fromNumber(response.cursor.id)
@@ -796,10 +834,12 @@ async function next<T>(
     }
 
     if (cursor[kDocuments].length === 0 && blocking === false) {
+      if (!shift) return false;
       return null;
     }
   } while (!cursor.isDead || cursor[kDocuments].length !== 0);
 
+  if (!shift) return false;
   return null;
 }
 
@@ -921,7 +961,7 @@ class ReadableCursorStream extends Readable {
 
   private _readNext() {
     // eslint-disable-next-line github/no-then
-    next(this._cursor, { blocking: true, transform: true }).then(
+    next(this._cursor, { blocking: true, transform: true, shift: true }).then(
       result => {
         if (result == null) {
           this.push(null);

package/src/cursor/find_cursor.ts

@@ -1,4 +1,5 @@
-import { type Document, Long } from '../bson';
+import { type Document } from '../bson';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
 import { type ExplainVerbosityLike } from '../explain';
 import type { MongoClient } from '../mongo_client';
@@ -34,7 +35,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
   /** @internal */
   [kFilter]: Document;
   /** @internal */
-  [kNumReturned]?: number;
+  [kNumReturned] = 0;
   /** @internal */
   [kBuiltOptions]: FindOptions;
 
@@ -69,7 +70,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
 
   /** @internal */
   async _initialize(session: ClientSession): Promise<ExecutionResult> {
-    const findOperation = new FindOperation(undefined, this.namespace, this[kFilter], {
+    const findOperation = new FindOperation(this.namespace, this[kFilter], {
       ...this[kBuiltOptions], // NOTE: order matters here, we may need to refine this
       ...this.cursorOptions,
       session
@@ -78,7 +79,9 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
     const response = await executeOperation(this.client, findOperation);
 
     // the response is not a cursor when `explain` is enabled
-    this[kNumReturned] = response.cursor?.firstBatch?.length;
+    if (CursorResponse.is(response)) {
+      this[kNumReturned] = response.batchSize;
+    }
 
     // TODO: NODE-2882
     return { server: findOperation.server, session, response };
@@ -107,14 +110,14 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
           // instead, if we determine there are no more documents to request from the server, we preemptively
           // close the cursor
         }
-        return { cursor: { id: Long.ZERO, nextBatch: [] } };
+        return CursorResponse.emptyGetMore;
       }
     }
 
-    const response = await super.getMore(batchSize);
+    const response = await super.getMore(batchSize, this.client.autoEncrypter ? false : true);
     // TODO: wrap this in some logic to prevent it from happening if we don't need this support
-    if (response) {
-      this[kNumReturned] = this[kNumReturned] + response.cursor.nextBatch.length;
+    if (CursorResponse.is(response)) {
+      this[kNumReturned] = this[kNumReturned] + response.batchSize;
     }
 
     return response;
@@ -145,7 +148,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
   async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
     return await executeOperation(
       this.client,
-      new FindOperation(undefined, this.namespace, this[kFilter], {
+      new FindOperation(this.namespace, this[kFilter], {
         ...this[kBuiltOptions], // NOTE: order matters here, we may need to refine this
         ...this.cursorOptions,
         explain: verbosity ?? true

package/src/cursor/run_command_cursor.ts

@@ -125,7 +125,8 @@ export class RunCommandCursor extends AbstractCursor {
     const getMoreOperation = new GetMoreOperation(this.namespace, this.id!, this.server!, {
       ...this.cursorOptions,
       session: this.session,
-      ...this.getMoreOptions
+      ...this.getMoreOptions,
+      useCursorResponse: false
     });
 
     return await executeOperation(this.client, getMoreOperation);

package/src/index.ts

@@ -290,7 +290,11 @@ export type { ConnectionPoolMetrics } from './cmap/metrics';
 export type { StreamDescription, StreamDescriptionOptions } from './cmap/stream_description';
 export type { CompressorName } from './cmap/wire_protocol/compression';
 export type { JSTypeOf, OnDemandDocument } from './cmap/wire_protocol/on_demand/document';
-export type { MongoDBResponse, MongoDBResponseConstructor } from './cmap/wire_protocol/responses';
+export type {
+  CursorResponse,
+  MongoDBResponse,
+  MongoDBResponseConstructor
+} from './cmap/wire_protocol/responses';
 export type { CollectionOptions, CollectionPrivate, ModifyResult } from './collection';
 export type {
   COMMAND_FAILED,

package/src/operations/execute_operation.ts

@@ -1,4 +1,5 @@
 import type { Document } from '../bson';
+import { type CursorResponse } from '../cmap/wire_protocol/responses';
 import {
   isRetryableReadError,
   isRetryableWriteError,
@@ -44,7 +45,7 @@ export interface ExecutionResult {
   /** The session used for this operation, may be implicitly created */
   session?: ClientSession;
   /** The raw server response for the operation */
-  response: Document;
+  response: Document | CursorResponse;
 }
 
 /**

package/src/operations/find.ts

@@ -1,5 +1,5 @@
 import type { Document } from '../bson';
-import type { Collection } from '../collection';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError } from '../error';
 import { ReadConcern } from '../read_concern';
 import type { Server } from '../sdam/server';
@@ -77,13 +77,8 @@ export class FindOperation extends CommandOperation<Document> {
   override options: FindOptions & { writeConcern?: never };
   filter: Document;
 
-  constructor(
-    collection: Collection | undefined,
-    ns: MongoDBNamespace,
-    filter: Document = {},
-    options: FindOptions = {}
-  ) {
-    super(collection, options);
+  constructor(ns: MongoDBNamespace, filter: Document = {}, options: FindOptions = {}) {
+    super(undefined, options);
 
     this.options = { ...options };
     delete this.options.writeConcern;
@@ -111,12 +106,17 @@ export class FindOperation extends CommandOperation<Document> {
       findCommand = decorateWithExplain(findCommand, this.explain);
     }
 
-    return await server.command(this.ns, findCommand, {
-      ...this.options,
-      ...this.bsonOptions,
-      documentsReturnedIn: 'firstBatch',
-      session
-    });
+    return await server.command(
+      this.ns,
+      findCommand,
+      {
+        ...this.options,
+        ...this.bsonOptions,
+        documentsReturnedIn: 'firstBatch',
+        session
+      },
+      this.explain ? undefined : CursorResponse
+    );
   }
 }
 

package/src/operations/get_more.ts

@@ -1,4 +1,5 @@
 import type { Document, Long } from '../bson';
+import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoRuntimeError } from '../error';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
@@ -19,6 +20,8 @@ export interface GetMoreOptions extends OperationOptions {
   maxTimeMS?: number;
   /** TODO(NODE-4413): Address bug with maxAwaitTimeMS not being passed in from the cursor correctly */
   maxAwaitTimeMS?: number;
+
+  useCursorResponse: boolean;
 }
 
 /**
@@ -96,7 +99,12 @@ export class GetMoreOperation extends AbstractOperation {
       ...this.options
     };
 
-    return await server.command(this.ns, getMoreCmd, commandOptions);
+    return await server.command(
+      this.ns,
+      getMoreCmd,
+      commandOptions,
+      this.options.useCursorResponse ? CursorResponse : undefined
+    );
   }
 }