mongodb 4.0.0 → 4.1.2

package/src/cursor/abstract_cursor.ts

@@ -1,7 +1,15 @@
 import { Callback, maybePromise, MongoDBNamespace, ns } from '../utils';
 import { Long, Document, BSONSerializeOptions, pluckBSONSerializeOptions } from '../bson';
-import { ClientSession } from '../sessions';
-import { MongoDriverError } from '../error';
+import { ClientSession, maybeClearPinnedConnection } from '../sessions';
+import {
+  AnyError,
+  MongoRuntimeError,
+  MongoNetworkError,
+  MongoInvalidArgumentError,
+  MongoCursorExhaustedError,
+  MongoTailableCursorError,
+  MongoCursorInUseError
+} from '../error';
 import { ReadPreference, ReadPreferenceLike } from '../read_preference';
 import type { Server } from '../sdam/server';
 import type { Topology } from '../sdam/topology';
@@ -43,9 +51,11 @@ export const CURSOR_FLAGS = [
   'partial'
 ] as const;
 
-/** @public */
+/** @public
+ * @deprecated This interface is deprecated */
 export interface CursorCloseOptions {
   /** Bypass calling killCursors when closing the cursor. */
+  /** @deprecated  the skipKillCursors option is deprecated */
   skipKillCursors?: boolean;
 }
 
@@ -150,7 +160,7 @@ export abstract class AbstractCursor<
       this[kOptions].batchSize = options.batchSize;
     }
 
-    if (typeof options.comment !== 'undefined') {
+    if (options.comment != null) {
       this[kOptions].comment = options.comment;
     }
 
@@ -211,6 +221,10 @@ export abstract class AbstractCursor<
     return this[kKilled];
   }
 
+  get loadBalanced(): boolean {
+    return this[kTopology].loadBalanced;
+  }
+
   /** Returns current buffered documents length */
   bufferedCount(): number {
     return this[kDocuments].length;
@@ -221,9 +235,12 @@ export abstract class AbstractCursor<
     return this[kDocuments].splice(0, number ?? this[kDocuments].length);
   }
 
-  [Symbol.asyncIterator](): AsyncIterator<TSchema | null> {
+  [Symbol.asyncIterator](): AsyncIterator<TSchema, void> {
     return {
-      next: () => this.next<TSchema>().then(value => ({ value, done: value === null }))
+      next: () =>
+        this.next().then(value =>
+          value != null ? { value, done: false } : { value: undefined, done: true }
+        )
     };
   }
 
@@ -263,8 +280,7 @@ export abstract class AbstractCursor<
         return done(undefined, true);
       }
 
-      next<any>(this, true, (err, doc) => {
-        // FIXME(NODE):
+      next<TSchema>(this, true, (err, doc) => {
         if (err) return done(err);
 
         if (doc) {
@@ -279,12 +295,13 @@ export abstract class AbstractCursor<
   }
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
-  next<T = TSchema>(): Promise<T | null>;
-  next<T = TSchema>(callback: Callback<T | null>): void;
-  next<T = TSchema>(callback?: Callback<T | null>): Promise<T | null> | void {
+  next(): Promise<TSchema | null>;
+  next(callback: Callback<TSchema | null>): void;
+  next(callback?: Callback<TSchema | null>): Promise<TSchema | null> | void;
+  next(callback?: Callback<TSchema | null>): Promise<TSchema | null> | void {
     return maybePromise(callback, done => {
       if (this[kId] === Long.ZERO) {
-        return done(new MongoDriverError('Cursor is exhausted'));
+        return done(new MongoCursorExhaustedError());
       }
 
       next(this, true, done);
@@ -294,12 +311,12 @@ export abstract class AbstractCursor<
   /**
    * Try to get the next available document from the cursor or `null` if an empty batch is returned
    */
-  tryNext<T = TSchema>(): Promise<T | null>;
-  tryNext<T = TSchema>(callback: Callback<T | null>): void;
-  tryNext<T = TSchema>(callback?: Callback<T | null>): Promise<T | null> | void {
+  tryNext(): Promise<TSchema | null>;
+  tryNext(callback: Callback<TSchema | null>): void;
+  tryNext(callback?: Callback<TSchema | null>): Promise<TSchema | null> | void {
     return maybePromise(callback, done => {
       if (this[kId] === Long.ZERO) {
-        return done(new MongoDriverError('Cursor is exhausted'));
+        return done(new MongoCursorExhaustedError());
       }
 
       next(this, false, done);
@@ -312,19 +329,19 @@ export abstract class AbstractCursor<
    * @param iterator - The iteration callback.
    * @param callback - The end callback.
    */
-  forEach<T = TSchema>(iterator: (doc: T) => boolean | void): Promise<void>;
-  forEach<T = TSchema>(iterator: (doc: T) => boolean | void, callback: Callback<void>): void;
-  forEach<T = TSchema>(
-    iterator: (doc: T) => boolean | void,
+  forEach(iterator: (doc: TSchema) => boolean | void): Promise<void>;
+  forEach(iterator: (doc: TSchema) => boolean | void, callback: Callback<void>): void;
+  forEach(
+    iterator: (doc: TSchema) => boolean | void,
     callback?: Callback<void>
   ): Promise<void> | void {
     if (typeof iterator !== 'function') {
-      throw new MongoDriverError('Missing required parameter `iterator`');
+      throw new MongoInvalidArgumentError('Argument "iterator" must be a function');
     }
     return maybePromise(callback, done => {
       const transform = this[kTransform];
       const fetchDocs = () => {
-        next<T>(this, true, (err, doc) => {
+        next<TSchema>(this, true, (err, doc) => {
           if (err || doc == null) return done(err);
           let result;
           // NOTE: no need to transform because `next` will do this automatically
@@ -341,7 +358,7 @@ export abstract class AbstractCursor<
           for (let i = 0; i < internalDocs.length; ++i) {
             try {
               result = iterator(
-                (transform ? transform(internalDocs[i]) : internalDocs[i]) as T // TODO(NODE-3283): Improve transform typing
+                (transform ? transform(internalDocs[i]) : internalDocs[i]) as TSchema // TODO(NODE-3283): Improve transform typing
               );
             } catch (error) {
               return done(error);
@@ -359,7 +376,13 @@ export abstract class AbstractCursor<
 
   close(): void;
   close(callback: Callback): void;
+  /**
+   * @deprecated options argument is deprecated
+   */
   close(options: CursorCloseOptions): Promise<void>;
+  /**
+   * @deprecated options argument is deprecated
+   */
   close(options: CursorCloseOptions, callback: Callback): void;
   close(options?: CursorCloseOptions | Callback, callback?: Callback): Promise<void> | void {
     if (typeof options === 'function') (callback = options), (options = {});
@@ -368,49 +391,7 @@ export abstract class AbstractCursor<
     const needsToEmitClosed = !this[kClosed];
     this[kClosed] = true;
 
-    return maybePromise(callback, done => {
-      const cursorId = this[kId];
-      const cursorNs = this[kNamespace];
-      const server = this[kServer];
-      const session = this[kSession];
-
-      if (cursorId == null || server == null || cursorId.isZero() || cursorNs == null) {
-        if (needsToEmitClosed) {
-          this[kId] = Long.ZERO;
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-expect-error
-          this.emit(AbstractCursor.CLOSE);
-        }
-
-        if (session && session.owner === this) {
-          return session.endSession(done);
-        }
-
-        return done();
-      }
-
-      this[kKilled] = true;
-      server.killCursors(
-        cursorNs,
-        [cursorId],
-        { ...pluckBSONSerializeOptions(this[kOptions]), session },
-        () => {
-          if (session && session.owner === this) {
-            return session.endSession(() => {
-              // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-              // @ts-expect-error
-              this.emit(AbstractCursor.CLOSE);
-              done();
-            });
-          }
-
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-expect-error
-          this.emit(AbstractCursor.CLOSE);
-          done();
-        }
-      );
-    });
+    return maybePromise(callback, done => cleanupCursor(this, { needsToEmitClosed }, done));
   }
 
   /**
@@ -421,15 +402,15 @@ export abstract class AbstractCursor<
    *
    * @param callback - The result callback.
    */
-  toArray<T = TSchema>(): Promise<T[]>;
-  toArray<T = TSchema>(callback: Callback<T[]>): void;
-  toArray<T = TSchema>(callback?: Callback<T[]>): Promise<T[]> | void {
+  toArray(): Promise<TSchema[]>;
+  toArray(callback: Callback<TSchema[]>): void;
+  toArray(callback?: Callback<TSchema[]>): Promise<TSchema[]> | void {
     return maybePromise(callback, done => {
-      const docs: T[] = [];
+      const docs: TSchema[] = [];
       const transform = this[kTransform];
       const fetchDocs = () => {
         // NOTE: if we add a `nextBatch` then we should use it here
-        next<T>(this, true, (err, doc) => {
+        next<TSchema>(this, true, (err, doc) => {
           if (err) return done(err);
           if (doc == null) return done(undefined, docs);
 
@@ -437,9 +418,11 @@ export abstract class AbstractCursor<
           docs.push(doc);
 
           // these do need to be transformed since they are copying the rest of the batch
-          const internalDocs = (transform
-            ? this[kDocuments].splice(0, this[kDocuments].length).map(transform)
-            : this[kDocuments].splice(0, this[kDocuments].length)) as T[]; // TODO(NODE-3283): Improve transform typing
+          const internalDocs = (
+            transform
+              ? this[kDocuments].splice(0, this[kDocuments].length).map(transform)
+              : this[kDocuments].splice(0, this[kDocuments].length)
+          ) as TSchema[]; // TODO(NODE-3283): Improve transform typing
 
           if (internalDocs) {
             docs.push(...internalDocs);
@@ -462,11 +445,11 @@ export abstract class AbstractCursor<
   addCursorFlag(flag: CursorFlag, value: boolean): this {
     assertUninitialized(this);
     if (!CURSOR_FLAGS.includes(flag)) {
-      throw new MongoDriverError(`flag ${flag} is not one of ${CURSOR_FLAGS}`);
+      throw new MongoInvalidArgumentError(`Flag ${flag} is not one of ${CURSOR_FLAGS}`);
     }
 
     if (typeof value !== 'boolean') {
-      throw new MongoDriverError(`flag ${flag} must be a boolean value`);
+      throw new MongoInvalidArgumentError(`Flag ${flag} must be a boolean value`);
     }
 
     this[kOptions][flag] = value;
@@ -477,11 +460,12 @@ export abstract class AbstractCursor<
    * Map all documents using the provided function
    * If there is a transform set on the cursor, that will be called first and the result passed to
    * this function's transform.
-   * @remarks
    *
-   * **NOTE:** adding a transform changes the return type of the iteration of this cursor, it **does not** return
-   * a new instance of a cursor. This means when calling map, you should always assign the result to a new
-   * variable. Take note of the following example:
+   * @remarks
+   * **Note for Typescript Users:** adding a transform changes the return type of the iteration of this cursor,
+   * it **does not** return a new instance of a cursor. This means when calling map,
+   * you should always assign the result to a new variable in order to get a correctly typed cursor variable.
+   * Take note of the following example:
    *
    * @example
    * ```typescript
@@ -502,7 +486,7 @@ export abstract class AbstractCursor<
       this[kTransform] = transform;
     }
 
-    return (this as unknown) as AbstractCursor<T>;
+    return this as unknown as AbstractCursor<T>;
   }
 
   /**
@@ -517,7 +501,7 @@ export abstract class AbstractCursor<
     } else if (typeof readPreference === 'string') {
       this[kOptions].readPreference = ReadPreference.fromString(readPreference);
     } else {
-      throw new MongoDriverError('Invalid read preference: ' + readPreference);
+      throw new MongoInvalidArgumentError(`Invalid read preference: ${readPreference}`);
     }
 
     return this;
@@ -546,7 +530,7 @@ export abstract class AbstractCursor<
   maxTimeMS(value: number): this {
     assertUninitialized(this);
     if (typeof value !== 'number') {
-      throw new MongoDriverError('maxTimeMS must be a number');
+      throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');
     }
 
     this[kOptions].maxTimeMS = value;
@@ -561,11 +545,11 @@ export abstract class AbstractCursor<
   batchSize(value: number): this {
     assertUninitialized(this);
     if (this[kOptions].tailable) {
-      throw new MongoDriverError('Tailable cursors do not support batchSize');
+      throw new MongoTailableCursorError('Tailable cursor does not support batchSize');
     }
 
     if (typeof value !== 'number') {
-      throw new MongoDriverError('batchSize requires an integer');
+      throw new MongoInvalidArgumentError('Operation "batchSize" requires an integer');
     }
 
     this[kOptions].batchSize = value;
@@ -617,12 +601,12 @@ export abstract class AbstractCursor<
     const server = this[kServer];
 
     if (cursorId == null) {
-      callback(new MongoDriverError('Unable to iterate cursor with no id'));
+      callback(new MongoRuntimeError('Unable to iterate cursor with no id'));
       return;
     }
 
     if (server == null) {
-      callback(new MongoDriverError('Unable to iterate cursor without selected server'));
+      callback(new MongoRuntimeError('Unable to iterate cursor without selected server'));
       return;
     }
 
@@ -714,7 +698,7 @@ function next<T>(cursor: AbstractCursor, blocking: boolean, callback: Callback<T
       cursor[kInitialized] = true;
 
       if (err || cursorIsDead(cursor)) {
-        return cleanupCursor(cursor, () => callback(err, nextDocument(cursor)));
+        return cleanupCursor(cursor, { error: err }, () => callback(err, nextDocument(cursor)));
       }
 
       next(cursor, blocking, callback);
@@ -724,7 +708,7 @@ function next<T>(cursor: AbstractCursor, blocking: boolean, callback: Callback<T
   }
 
   if (cursorIsDead(cursor)) {
-    return cleanupCursor(cursor, () => callback(undefined, null));
+    return cleanupCursor(cursor, undefined, () => callback(undefined, null));
   }
 
   // otherwise need to call getMore
@@ -741,7 +725,7 @@ function next<T>(cursor: AbstractCursor, blocking: boolean, callback: Callback<T
     }
 
     if (err || cursorIsDead(cursor)) {
-      return cleanupCursor(cursor, () => callback(err, nextDocument(cursor)));
+      return cleanupCursor(cursor, { error: err }, () => callback(err, nextDocument(cursor)));
     }
 
     if (cursor[kDocuments].length === 0 && blocking === false) {
@@ -757,24 +741,75 @@ function cursorIsDead(cursor: AbstractCursor): boolean {
   return !!cursorId && cursorId.isZero();
 }
 
-function cleanupCursor(cursor: AbstractCursor, callback: Callback): void {
-  if (cursor[kDocuments].length === 0) {
-    cursor[kClosed] = true;
-    cursor.emit(AbstractCursor.CLOSE);
+function cleanupCursor(
+  cursor: AbstractCursor,
+  options: { error?: AnyError | undefined; needsToEmitClosed?: boolean } | undefined,
+  callback: Callback
+): void {
+  const cursorId = cursor[kId];
+  const cursorNs = cursor[kNamespace];
+  const server = cursor[kServer];
+  const session = cursor[kSession];
+  const error = options?.error;
+  const needsToEmitClosed = options?.needsToEmitClosed ?? cursor[kDocuments].length === 0;
+
+  if (error) {
+    if (cursor.loadBalanced && error instanceof MongoNetworkError) {
+      return completeCleanup();
+    }
   }
 
-  const session = cursor[kSession];
-  if (session && session.owner === cursor) {
-    session.endSession(callback);
-  } else {
-    callback();
+  if (cursorId == null || server == null || cursorId.isZero() || cursorNs == null) {
+    if (needsToEmitClosed) {
+      cursor[kClosed] = true;
+      cursor[kId] = Long.ZERO;
+      cursor.emit(AbstractCursor.CLOSE);
+    }
+
+    if (session) {
+      if (session.owner === cursor) {
+        return session.endSession({ error }, callback);
+      }
+
+      if (!session.inTransaction()) {
+        maybeClearPinnedConnection(session, { error });
+      }
+    }
+
+    return callback();
   }
+
+  function completeCleanup() {
+    if (session) {
+      if (session.owner === cursor) {
+        return session.endSession({ error }, () => {
+          cursor.emit(AbstractCursor.CLOSE);
+          callback();
+        });
+      }
+
+      if (!session.inTransaction()) {
+        maybeClearPinnedConnection(session, { error });
+      }
+    }
+
+    cursor.emit(AbstractCursor.CLOSE);
+    return callback();
+  }
+
+  cursor[kKilled] = true;
+  server.killCursors(
+    cursorNs,
+    [cursorId],
+    { ...pluckBSONSerializeOptions(cursor[kOptions]), session },
+    () => completeCleanup()
+  );
 }
 
 /** @internal */
 export function assertUninitialized(cursor: AbstractCursor): void {
   if (cursor[kInitialized]) {
-    throw new MongoDriverError('Cursor is already initialized');
+    throw new MongoCursorInUseError();
   }
 }
 
@@ -812,7 +847,7 @@ function makeCursorStream<TSchema extends Document>(cursor: AbstractCursor<TSche
   function readNext() {
     needToClose = false;
     next(cursor, true, (err, result) => {
-      needToClose = err ? !cursor.closed : result !== null;
+      needToClose = err ? !cursor.closed : result != null;
 
       if (err) {
         // NOTE: This is questionable, but we have a test backing the behavior. It seems the
@@ -826,15 +861,17 @@ function makeCursorStream<TSchema extends Document>(cursor: AbstractCursor<TSche
 
         // NOTE: This is also perhaps questionable. The rationale here is that these errors tend
         //       to be "operation interrupted", where a cursor has been closed but there is an
-        //       active getMore in-flight.
-        if (cursor.killed) {
+        //       active getMore in-flight. This used to check if the cursor was killed but once
+        //       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 readable.destroy(err);
       }
 
-      if (result === null) {
+      if (result == null) {
         readable.push(null);
       } else if (readable.destroyed) {
         cursor.close();

package/src/cursor/aggregation_cursor.ts

@@ -7,16 +7,12 @@ import type { Sort } from '../sort';
 import type { Topology } from '../sdam/topology';
 import type { Callback, MongoDBNamespace } from '../utils';
 import type { ClientSession } from '../sessions';
-import type { OperationParent } from '../operations/command';
 import type { AbstractCursorOptions } from './abstract_cursor';
 import type { ExplainVerbosityLike } from '../explain';
-import type { Projection } from '../mongo_types';
 
 /** @public */
 export interface AggregationCursorOptions extends AbstractCursorOptions, AggregateOptions {}
 
-/** @internal */
-const kParent = Symbol('parent');
 /** @internal */
 const kPipeline = Symbol('pipeline');
 /** @internal */
@@ -30,8 +26,6 @@ const kOptions = Symbol('options');
  * @public
  */
 export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchema> {
-  /** @internal */
-  [kParent]: OperationParent; // TODO: NODE-2883
   /** @internal */
   [kPipeline]: Document[];
   /** @internal */
@@ -39,7 +33,6 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
 
   /** @internal */
   constructor(
-    parent: OperationParent,
     topology: Topology,
     namespace: MongoDBNamespace,
     pipeline: Document[] = [],
@@ -47,7 +40,6 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
   ) {
     super(topology, namespace, options);
 
-    this[kParent] = parent;
     this[kPipeline] = pipeline;
     this[kOptions] = options;
   }
@@ -59,7 +51,7 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
   clone(): AggregationCursor<TSchema> {
     const clonedOptions = mergeOptions({}, this[kOptions]);
     delete clonedOptions.session;
-    return new AggregationCursor(this[kParent], this.topology, this.namespace, this[kPipeline], {
+    return new AggregationCursor(this.topology, this.namespace, this[kPipeline], {
       ...clonedOptions
     });
   }
@@ -70,7 +62,7 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
 
   /** @internal */
   _initialize(session: ClientSession | undefined, callback: Callback<ExecutionResult>): void {
-    const aggregateOperation = new AggregateOperation(this[kParent], this[kPipeline], {
+    const aggregateOperation = new AggregateOperation(this.namespace, this[kPipeline], {
       ...this[kOptions],
       ...this.cursorOptions,
       session
@@ -93,11 +85,11 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
     callback?: Callback<Document>
   ): Promise<Document> | void {
     if (typeof verbosity === 'function') (callback = verbosity), (verbosity = true);
-    if (verbosity === undefined) verbosity = true;
+    if (verbosity == null) verbosity = true;
 
     return executeOperation(
       this.topology,
-      new AggregateOperation(this[kParent], this[kPipeline], {
+      new AggregateOperation(this.namespace, this[kPipeline], {
         ...this[kOptions], // NOTE: order matters here, we may need to refine this
         ...this.cursorOptions,
         explain: verbosity
@@ -128,8 +120,8 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
     return this;
   }
 
-  /** Add a out stage to the aggregation pipeline */
-  out($out: number): this {
+  /** Add an out stage to the aggregation pipeline */
+  out($out: { db: string; coll: string } | string): this {
     assertUninitialized(this);
     this[kPipeline].push({ $out });
     return this;
@@ -142,22 +134,44 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
    * In order to strictly type this function you must provide an interface
    * that represents the effect of your projection on the result documents.
    *
-   * **NOTE:** adding a projection changes the return type of the iteration of this cursor,
+   * By default chaining a projection to your cursor changes the returned type to the generic {@link Document} type.
+   * You should specify a parameterized type to have assertions on your final results.
+   *
+   * @example
+   * ```typescript
+   * // Best way
+   * const docs: AggregationCursor<{ a: number }> = cursor.project<{ a: number }>({ _id: 0, a: true });
+   * // Flexible way
+   * const docs: AggregationCursor<Document> = cursor.project({ _id: 0, a: true });
+   * ```
+   *
+   * @remarks
+   * In order to strictly type this function you must provide an interface
+   * that represents the effect of your projection on the result documents.
+   *
+   * **Note for Typescript Users:** adding a transform changes the return type of the iteration of this cursor,
    * it **does not** return a new instance of a cursor. This means when calling project,
-   * you should always assign the result to a new variable. Take note of the following example:
+   * you should always assign the result to a new variable in order to get a correctly typed cursor variable.
+   * Take note of the following example:
    *
    * @example
    * ```typescript
    * const cursor: AggregationCursor<{ a: number; b: string }> = coll.aggregate([]);
-   * const projectCursor = cursor.project<{ a: number }>({ a: true });
+   * const projectCursor = cursor.project<{ a: number }>({ _id: 0, a: true });
    * const aPropOnlyArray: {a: number}[] = await projectCursor.toArray();
+   *
+   * // or always use chaining and save the final cursor
+   *
+   * const cursor = coll.aggregate().project<{ a: string }>({
+   *   _id: 0,
+   *   a: { $convert: { input: '$a', to: 'string' }
+   * }});
    * ```
    */
-  project<T = TSchema>($project: Projection<T>): AggregationCursor<T>;
-  project($project: Document): this {
+  project<T extends Document = Document>($project: Document): AggregationCursor<T> {
     assertUninitialized(this);
     this[kPipeline].push({ $project });
-    return this;
+    return this as unknown as AggregationCursor<T>;
   }
 
   /** Add a lookup stage to the aggregation pipeline */