mongodb 4.7.0 → 4.9.0

package/src/collection.ts

@@ -5,6 +5,7 @@ import { UnorderedBulkOperation } from './bulk/unordered';
 import { ChangeStream, ChangeStreamDocument, ChangeStreamOptions } from './change_stream';
 import { AggregationCursor } from './cursor/aggregation_cursor';
 import { FindCursor } from './cursor/find_cursor';
+import { ListIndexesCursor } from './cursor/list_indexes_cursor';
 import type { Db } from './db';
 import { MongoInvalidArgumentError } from './error';
 import type { Logger, LoggerOptions } from './logger';
@@ -57,7 +58,6 @@ import {
   IndexExistsOperation,
   IndexInformationOperation,
   IndexSpecification,
-  ListIndexesCursor,
   ListIndexesOptions
 } from './operations/indexes';
 import {
@@ -725,7 +725,7 @@ export class Collection<TSchema extends Document = Document> {
     }
 
     if (typeof filter === 'function') {
-      callback = filter as Callback<WithId<TSchema> | null>;
+      callback = filter;
       filter = {};
       options = {};
     }
@@ -1128,7 +1128,7 @@ export class Collection<TSchema extends Document = Document> {
       this.s.db.s.client,
       new CountDocumentsOperation(
         this as TODO_NODE_3286,
-        filter as Document,
+        filter,
         resolveOptions(this, options as CountDocumentsOptions)
       ),
       callback
@@ -1191,7 +1191,7 @@ export class Collection<TSchema extends Document = Document> {
     callback?: Callback<any[]>
   ): Promise<any[]> | void {
     if (typeof filter === 'function') {
-      (callback = filter as Callback<any[]>), (filter = {}), (options = {});
+      (callback = filter), (filter = {}), (options = {});
     } else {
       if (arguments.length === 3 && typeof options === 'function') {
         (callback = options), (options = {});
@@ -1544,12 +1544,26 @@ export class Collection<TSchema extends Document = Document> {
     );
   }
 
-  /** Initiate an Out of order batch write operation. All operations will be buffered into insert/update/remove commands executed out of order. */
+  /**
+   * Initiate an Out of order batch write operation. All operations will be buffered into insert/update/remove commands executed out of order.
+   *
+   * @throws MongoNotConnectedError
+   * @remarks
+   * **NOTE:** MongoClient must be connected prior to calling this method due to a known limitation in this legacy implemenation.
+   * However, `collection.bulkWrite()` provides an equivalent API that does not require prior connecting.
+   */
   initializeUnorderedBulkOp(options?: BulkWriteOptions): UnorderedBulkOperation {
     return new UnorderedBulkOperation(this as TODO_NODE_3286, resolveOptions(this, options));
   }
 
-  /** Initiate an In order bulk write operation. Operations will be serially executed in the order they are added, creating a new operation for each switch in types. */
+  /**
+   * Initiate an In order bulk write operation. Operations will be serially executed in the order they are added, creating a new operation for each switch in types.
+   *
+   * @throws MongoNotConnectedError
+   * @remarks
+   * **NOTE:** MongoClient must be connected prior to calling this method due to a known limitation in this legacy implemenation.
+   * However, `collection.bulkWrite()` provides an equivalent API that does not require prior connecting.
+   */
   initializeOrderedBulkOp(options?: BulkWriteOptions): OrderedBulkOperation {
     return new OrderedBulkOperation(this as TODO_NODE_3286, resolveOptions(this, options));
   }
@@ -1596,13 +1610,13 @@ export class Collection<TSchema extends Document = Document> {
    * Updates documents.
    *
    * @deprecated use updateOne, updateMany or bulkWrite
-   * @param selector - The selector for the update operation.
+   * @param filter - The filter for the update operation.
    * @param update - The update operations to be applied to the documents
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
   update(
-    selector: Filter<TSchema>,
+    filter: Filter<TSchema>,
     update: UpdateFilter<TSchema>,
     options: UpdateOptions,
     callback: Callback<Document>
@@ -1613,19 +1627,19 @@ export class Collection<TSchema extends Document = Document> {
     if (typeof options === 'function') (callback = options), (options = {});
     options = options ?? {};
 
-    return this.updateMany(selector, update, options, callback);
+    return this.updateMany(filter, update, options, callback);
   }
 
   /**
    * Remove documents.
    *
    * @deprecated use deleteOne, deleteMany or bulkWrite
-   * @param selector - The selector for the update operation.
+   * @param filter - The filter for the remove operation.
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
   remove(
-    selector: Filter<TSchema>,
+    filter: Filter<TSchema>,
     options: DeleteOptions,
     callback: Callback
   ): Promise<DeleteResult> | void {
@@ -1635,7 +1649,7 @@ export class Collection<TSchema extends Document = Document> {
     if (typeof options === 'function') (callback = options), (options = {});
     options = options ?? {};
 
-    return this.deleteMany(selector, options, callback);
+    return this.deleteMany(filter, options, callback);
   }
 
   /**
@@ -1667,7 +1681,7 @@ export class Collection<TSchema extends Document = Document> {
     callback?: Callback<number>
   ): Promise<number> | void {
     if (typeof filter === 'function') {
-      (callback = filter as Callback<number>), (filter = {}), (options = {});
+      (callback = filter), (filter = {}), (options = {});
     } else {
       if (typeof options === 'function') (callback = options), (options = {});
     }

package/src/connection_string.ts

@@ -1188,7 +1188,7 @@ export const OPTIONS = {
 
       throw new MongoParseError(`Invalid WriteConcern cannot parse: ${JSON.stringify(value)}`);
     }
-  } as OptionDescriptor,
+  },
   wtimeout: {
     deprecated: 'Please use wtimeoutMS instead',
     target: 'writeConcern',

package/src/cursor/abstract_cursor.ts

@@ -14,6 +14,7 @@ import type { MongoClient } from '../mongo_client';
 import { TODO_NODE_3286, TypedEventEmitter } from '../mongo_types';
 import { executeOperation, ExecutionResult } from '../operations/execute_operation';
 import { GetMoreOperation } from '../operations/get_more';
+import { KillCursorsOperation } from '../operations/kill_cursors';
 import { ReadConcern, ReadConcernLike } from '../read_concern';
 import { ReadPreference, ReadPreferenceLike } from '../read_preference';
 import type { Server } from '../sdam/server';
@@ -66,7 +67,7 @@ export interface CursorCloseOptions {
 /** @public */
 export interface CursorStreamOptions {
   /** A transformation method applied to each document emitted by the stream */
-  transform?(doc: Document): Document;
+  transform?(this: void, doc: Document): Document;
 }
 
 /** @public */
@@ -77,8 +78,20 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
   session?: ClientSession;
   readPreference?: ReadPreferenceLike;
   readConcern?: ReadConcernLike;
+  /**
+   * Specifies the number of documents to return in each response from MongoDB
+   */
   batchSize?: number;
+  /**
+   * When applicable `maxTimeMS` controls the amount of time the initial command
+   * that constructs a cursor should take. (ex. find, aggregate, listCollections)
+   */
   maxTimeMS?: number;
+  /**
+   * When applicable `maxAwaitTimeMS` controls the amount of time subsequent getMores
+   * that a cursor uses to fetch more data should take. (ex. cursor.next())
+   */
+  maxAwaitTimeMS?: number;
   /**
    * Comment to apply to the operation.
    *
@@ -88,7 +101,19 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
    * In server versions 4.4 and above, 'comment' can be any valid BSON type.
    */
   comment?: unknown;
+  /**
+   * By default, MongoDB will automatically close a cursor when the
+   * client has exhausted all results in the cursor. However, for [capped collections](https://www.mongodb.com/docs/manual/core/capped-collections)
+   * you may use a Tailable Cursor that remains open after the client exhausts
+   * the results in the initial cursor.
+   */
   tailable?: boolean;
+  /**
+   * If awaitData is set to true, when the cursor reaches the end of the capped collection,
+   * MongoDB blocks the query thread for a period of time waiting for new data to arrive.
+   * When new data is inserted into the capped collection, the blocked thread is signaled
+   * to wake up and return the next batch to the client.
+   */
   awaitData?: boolean;
   noCursorTimeout?: boolean;
 }
@@ -118,7 +143,7 @@ export abstract class AbstractCursor<
   /** @internal */
   [kId]?: Long;
   /** @internal */
-  [kSession]?: ClientSession;
+  [kSession]: ClientSession;
   /** @internal */
   [kServer]?: Server;
   /** @internal */
@@ -154,7 +179,7 @@ export abstract class AbstractCursor<
     }
     this[kClient] = client;
     this[kNamespace] = namespace;
-    this[kDocuments] = []; // TODO: https://github.com/microsoft/TypeScript/issues/36230
+    this[kDocuments] = [];
     this[kInitialized] = false;
     this[kClosed] = false;
     this[kKilled] = false;
@@ -185,8 +210,14 @@ export abstract class AbstractCursor<
       this[kOptions].maxTimeMS = options.maxTimeMS;
     }
 
+    if (typeof options.maxAwaitTimeMS === 'number') {
+      this[kOptions].maxAwaitTimeMS = options.maxAwaitTimeMS;
+    }
+
     if (options.session instanceof ClientSession) {
       this[kSession] = options.session;
+    } else {
+      this[kSession] = this[kClient].startSession({ owner: this, explicit: false });
     }
   }
 
@@ -217,11 +248,11 @@ export abstract class AbstractCursor<
   }
 
   /** @internal */
-  get session(): ClientSession | undefined {
+  get session(): ClientSession {
     return this[kSession];
   }
 
-  set session(clientSession: ClientSession | undefined) {
+  set session(clientSession: ClientSession) {
     this[kSession] = clientSession;
   }
 
@@ -264,7 +295,7 @@ export abstract class AbstractCursor<
   stream(options?: CursorStreamOptions): Readable & AsyncIterable<TSchema> {
     if (options?.transform) {
       const transform = options.transform;
-      const readable = makeCursorStream(this);
+      const readable = new ReadableCursorStream(this);
 
       return readable.pipe(
         new Transform({
@@ -282,7 +313,7 @@ export abstract class AbstractCursor<
       );
     }
 
-    return makeCursorStream(this);
+    return new ReadableCursorStream(this);
   }
 
   hasNext(): Promise<boolean>;
@@ -592,11 +623,12 @@ export abstract class AbstractCursor<
     const session = this[kSession];
     if (session) {
       // We only want to end this session if we created it, and it hasn't ended yet
-      if (session.explicit === false && !session.hasEnded) {
-        session.endSession();
+      if (session.explicit === false) {
+        if (!session.hasEnded) {
+          session.endSession().catch(() => null);
+        }
+        this[kSession] = this.client.startSession({ owner: this, explicit: false });
       }
-
-      this[kSession] = undefined;
     }
   }
 
@@ -613,21 +645,8 @@ export abstract class AbstractCursor<
 
   /** @internal */
   _getMore(batchSize: number, callback: Callback<Document>): void {
-    const cursorId = this[kId];
-    const cursorNs = this[kNamespace];
-    const server = this[kServer];
-
-    if (cursorId == null) {
-      callback(new MongoRuntimeError('Unable to iterate cursor with no id'));
-      return;
-    }
-
-    if (server == null) {
-      callback(new MongoRuntimeError('Unable to iterate cursor without selected server'));
-      return;
-    }
-
-    const getMoreOperation = new GetMoreOperation(cursorNs, cursorId, server, {
+    // 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
@@ -644,24 +663,13 @@ export abstract class AbstractCursor<
    * a significant refactor.
    */
   [kInit](callback: Callback<TSchema | null>): void {
-    if (this[kSession] == null) {
-      if (this[kClient].topology?.shouldCheckForSessionSupport()) {
-        return this[kClient].topology?.selectServer(ReadPreference.primaryPreferred, {}, err => {
-          if (err) return callback(err);
-          return this[kInit](callback);
-        });
-      } else if (this[kClient].topology?.hasSessionSupport()) {
-        this[kSession] = this[kClient].topology?.startSession({ owner: this, explicit: false });
-      }
-    }
-
     this._initialize(this[kSession], (err, state) => {
       if (state) {
         const response = state.response;
         this[kServer] = state.server;
-        this[kSession] = state.session;
 
         if (response.cursor) {
+          // TODO(NODE-2674): Preserve int64 sent from MongoDB
           this[kId] =
             typeof response.cursor.id === 'number'
               ? Long.fromNumber(response.cursor.id)
@@ -714,7 +722,21 @@ function nextDocument<T>(cursor: AbstractCursor): T | null {
   return null;
 }
 
-function next<T>(cursor: AbstractCursor<T>, blocking: boolean, callback: Callback<T | null>): void {
+/**
+ * @param cursor - the cursor on which to call `next`
+ * @param blocking - a boolean indicating whether or not the cursor should `block` until data
+ *     is available.  Generally, this flag is set to `false` because if the getMore returns no documents,
+ *     the cursor has been exhausted.  In certain scenarios (ChangeStreams, tailable await cursors and
+ *     `tryNext`, for example) blocking is necessary because a getMore returning no documents does
+ *     not indicate the end of the cursor.
+ * @param callback - callback to return the result to the caller
+ * @returns
+ */
+export function next<T>(
+  cursor: AbstractCursor<T>,
+  blocking: boolean,
+  callback: Callback<T | null>
+): void {
   const cursorId = cursor[kId];
   if (cursor.closed) {
     return callback(undefined, null);
@@ -829,11 +851,11 @@ function cleanupCursor(
   }
 
   cursor[kKilled] = true;
-  server.killCursors(
-    cursorNs,
-    [cursorId],
-    { ...pluckBSONSerializeOptions(cursor[kOptions]), session },
-    () => completeCleanup()
+
+  return executeOperation(
+    cursor[kClient],
+    new KillCursorsOperation(cursorId, cursorNs, server, { session }),
+    completeCleanup
   );
 }
 
@@ -844,50 +866,41 @@ export function assertUninitialized(cursor: AbstractCursor): void {
   }
 }
 
-function makeCursorStream(cursor: AbstractCursor) {
-  const readable = new Readable({
-    objectMode: true,
-    autoDestroy: false,
-    highWaterMark: 1
-  });
-
-  let initialized = false;
-  let reading = false;
-  let needToClose = true; // NOTE: we must close the cursor if we never read from it, use `_construct` in future node versions
-
-  readable._read = function () {
-    if (initialized === false) {
-      needToClose = false;
-      initialized = true;
-    }
+class ReadableCursorStream extends Readable {
+  private _cursor: AbstractCursor;
+  private _readInProgress = false;
 
-    if (!reading) {
-      reading = true;
-      readNext();
-    }
-  };
+  constructor(cursor: AbstractCursor) {
+    super({
+      objectMode: true,
+      autoDestroy: false,
+      highWaterMark: 1
+    });
+    this._cursor = cursor;
+  }
 
-  readable._destroy = function (error, cb) {
-    if (needToClose) {
-      cursor.close(err => process.nextTick(cb, err || error));
-    } else {
-      cb(error);
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  override _read(size: number): void {
+    if (!this._readInProgress) {
+      this._readInProgress = true;
+      this._readNext();
     }
-  };
+  }
 
-  function readNext() {
-    needToClose = false;
-    next(cursor, true, (err, result) => {
-      needToClose = err ? !cursor.closed : result != null;
+  override _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
+    this._cursor.close(err => process.nextTick(callback, err || error));
+  }
 
+  private _readNext() {
+    next(this._cursor, true, (err, result) => {
       if (err) {
         // NOTE: This is questionable, but we have a test backing the behavior. It seems the
         //       desired behavior is that a stream ends cleanly when a user explicitly closes
         //       a client during iteration. Alternatively, we could do the "right" thing and
         //       propagate the error message by removing this special case.
         if (err.message.match(/server is closed/)) {
-          cursor.close();
-          return readable.push(null);
+          this._cursor.close().catch(() => null);
+          return this.push(null);
         }
 
         // NOTE: This is also perhaps questionable. The rationale here is that these errors tend
@@ -896,25 +909,23 @@ function makeCursorStream(cursor: AbstractCursor) {
         //       that changed to happen in cleanup legitimate errors would not destroy the
         //       stream. There are change streams test specifically test these cases.
         if (err.message.match(/interrupted/)) {
-          return readable.push(null);
+          return this.push(null);
         }
 
-        return readable.destroy(err);
+        return this.destroy(err);
       }
 
       if (result == null) {
-        readable.push(null);
-      } else if (readable.destroyed) {
-        cursor.close();
+        this.push(null);
+      } else if (this.destroyed) {
+        this._cursor.close().catch(() => null);
       } else {
-        if (readable.push(result)) {
-          return readNext();
+        if (this.push(result)) {
+          return this._readNext();
         }
 
-        reading = false;
+        this._readInProgress = false;
       }
     });
   }
-
-  return readable;
 }

package/src/cursor/change_stream_cursor.ts

@@ -0,0 +1,194 @@
+import type { Document, Long, Timestamp } from '../bson';
+import {
+  type ChangeStreamDocument,
+  type ChangeStreamEvents,
+  type OperationTime,
+  type ResumeToken,
+  ChangeStream
+} from '../change_stream';
+import { INIT, RESPONSE } from '../constants';
+import type { MongoClient } from '../mongo_client';
+import type { TODO_NODE_3286 } from '../mongo_types';
+import { AggregateOperation } from '../operations/aggregate';
+import type { CollationOptions } from '../operations/command';
+import { type ExecutionResult, executeOperation } from '../operations/execute_operation';
+import type { ClientSession } from '../sessions';
+import { type Callback, type MongoDBNamespace, maxWireVersion } from '../utils';
+import { type AbstractCursorOptions, AbstractCursor } from './abstract_cursor';
+
+/** @internal */
+export interface ChangeStreamCursorOptions extends AbstractCursorOptions {
+  startAtOperationTime?: OperationTime;
+  resumeAfter?: ResumeToken;
+  startAfter?: ResumeToken;
+  maxAwaitTimeMS?: number;
+  collation?: CollationOptions;
+  fullDocument?: string;
+}
+
+/** @internal */
+export type ChangeStreamAggregateRawResult<TChange> = {
+  $clusterTime: { clusterTime: Timestamp };
+  cursor: {
+    postBatchResumeToken: ResumeToken;
+    ns: string;
+    id: number | Long;
+  } & ({ firstBatch: TChange[] } | { nextBatch: TChange[] });
+  ok: 1;
+  operationTime: Timestamp;
+};
+
+/** @internal */
+export class ChangeStreamCursor<
+  TSchema extends Document = Document,
+  TChange extends Document = ChangeStreamDocument<TSchema>
+> extends AbstractCursor<TChange, ChangeStreamEvents> {
+  _resumeToken: ResumeToken;
+  startAtOperationTime?: OperationTime;
+  hasReceived?: boolean;
+  resumeAfter: ResumeToken;
+  startAfter: ResumeToken;
+  options: ChangeStreamCursorOptions;
+
+  postBatchResumeToken?: ResumeToken;
+  pipeline: Document[];
+
+  /**
+   * @internal
+   *
+   * used to determine change stream resumability
+   */
+  maxWireVersion: number | undefined;
+
+  constructor(
+    client: MongoClient,
+    namespace: MongoDBNamespace,
+    pipeline: Document[] = [],
+    options: ChangeStreamCursorOptions = {}
+  ) {
+    super(client, namespace, options);
+
+    this.pipeline = pipeline;
+    this.options = options;
+    this._resumeToken = null;
+    this.startAtOperationTime = options.startAtOperationTime;
+
+    if (options.startAfter) {
+      this.resumeToken = options.startAfter;
+    } else if (options.resumeAfter) {
+      this.resumeToken = options.resumeAfter;
+    }
+  }
+
+  set resumeToken(token: ResumeToken) {
+    this._resumeToken = token;
+    this.emit(ChangeStream.RESUME_TOKEN_CHANGED, token);
+  }
+
+  get resumeToken(): ResumeToken {
+    return this._resumeToken;
+  }
+
+  get resumeOptions(): ChangeStreamCursorOptions {
+    const options: ChangeStreamCursorOptions = {
+      ...this.options
+    };
+
+    for (const key of ['resumeAfter', 'startAfter', 'startAtOperationTime'] as const) {
+      delete options[key];
+    }
+
+    if (this.resumeToken != null) {
+      if (this.options.startAfter && !this.hasReceived) {
+        options.startAfter = this.resumeToken;
+      } else {
+        options.resumeAfter = this.resumeToken;
+      }
+    } else if (this.startAtOperationTime != null && maxWireVersion(this.server) >= 7) {
+      options.startAtOperationTime = this.startAtOperationTime;
+    }
+
+    return options;
+  }
+
+  cacheResumeToken(resumeToken: ResumeToken): void {
+    if (this.bufferedCount() === 0 && this.postBatchResumeToken) {
+      this.resumeToken = this.postBatchResumeToken;
+    } else {
+      this.resumeToken = resumeToken;
+    }
+    this.hasReceived = true;
+  }
+
+  _processBatch(response: ChangeStreamAggregateRawResult<TChange>): void {
+    const cursor = response.cursor;
+    if (cursor.postBatchResumeToken) {
+      this.postBatchResumeToken = response.cursor.postBatchResumeToken;
+
+      const batch =
+        'firstBatch' in response.cursor ? response.cursor.firstBatch : response.cursor.nextBatch;
+      if (batch.length === 0) {
+        this.resumeToken = cursor.postBatchResumeToken;
+      }
+    }
+  }
+
+  clone(): AbstractCursor<TChange> {
+    return new ChangeStreamCursor(this.client, this.namespace, this.pipeline, {
+      ...this.cursorOptions
+    });
+  }
+
+  _initialize(session: ClientSession, callback: Callback<ExecutionResult>): void {
+    const aggregateOperation = new AggregateOperation(this.namespace, this.pipeline, {
+      ...this.cursorOptions,
+      ...this.options,
+      session
+    });
+
+    executeOperation<TODO_NODE_3286, ChangeStreamAggregateRawResult<TChange>>(
+      session.client,
+      aggregateOperation,
+      (err, response) => {
+        if (err || response == null) {
+          return callback(err);
+        }
+
+        const server = aggregateOperation.server;
+        this.maxWireVersion = maxWireVersion(server);
+
+        if (
+          this.startAtOperationTime == null &&
+          this.resumeAfter == null &&
+          this.startAfter == null &&
+          this.maxWireVersion >= 7
+        ) {
+          this.startAtOperationTime = response.operationTime;
+        }
+
+        this._processBatch(response);
+
+        this.emit(INIT, response);
+        this.emit(RESPONSE);
+
+        // TODO: NODE-2882
+        callback(undefined, { server, session, response });
+      }
+    );
+  }
+
+  override _getMore(batchSize: number, callback: Callback): void {
+    super._getMore(batchSize, (err, response) => {
+      if (err) {
+        return callback(err);
+      }
+
+      this.maxWireVersion = maxWireVersion(this.server);
+      this._processBatch(response as TODO_NODE_3286 as ChangeStreamAggregateRawResult<TChange>);
+
+      this.emit(ChangeStream.MORE, response);
+      this.emit(ChangeStream.RESPONSE);
+      callback(err, response);
+    });
+  }
+}