refactor: move find command building to FindOperation

The primary work of this ticket was to make the `Collection#find`
method behave like other read operations by moving the command
construction to the `FindOperation` itself. Along the way a
number of improvements were made:

 - cursors now know they are tailable and/or awaitData upon
   construction, rather than observing the internal `cmd` they
   are built around. As much as possible the cursor implementation
   now no longer alters behavior after initialization based on
   what is in the internal `cmd` document

 - a number of supported, but undocumented options were added to
   the `find` method itself

 - `bsonOptions` were introduced to the `OperationBase` class as
   a first step towards improving our story around overriding
   these values and passing them to wire protocol methods

NODE-2830

Author: mbroadst

src/bson.ts

@@ -48,3 +48,24 @@ export interface BSONSerializeOptions extends SerializeOptions {
 
   raw?: boolean;
 }
+
+export function pluckBSONSerializeOptions(options: BSONSerializeOptions): BSONSerializeOptions {
+  const {
+    fieldsAsRaw,
+    promoteValues,
+    promoteBuffers,
+    promoteLongs,
+    serializeFunctions,
+    ignoreUndefined,
+    raw
+  } = options;
+  return {
+    fieldsAsRaw,
+    promoteValues,
+    promoteBuffers,
+    promoteLongs,
+    serializeFunctions,
+    ignoreUndefined,
+    raw
+  };
+}

src/cmap/wire_protocol/get_more.ts

@@ -1,5 +1,5 @@
 import { GetMore } from '../commands';
-import { Long, Document } from '../../bson';
+import { Long, Document, pluckBSONSerializeOptions } from '../../bson';
 import { MongoError, MongoNetworkError } from '../../error';
 import { applyCommonQueryOptions } from './shared';
 import { maxWireVersion, collectionNamespace, Callback } from '../../utils';
@@ -71,7 +71,11 @@ export function getMore(
 
   if (wireVersion < 4) {
     const getMoreOp = new GetMore(ns, cursorId, { numberToReturn: batchSize });
-    const queryOptions = applyCommonQueryOptions({}, cursorState);
+    const queryOptions = applyCommonQueryOptions(
+      {},
+      Object.assign({ bsonOptions: pluckBSONSerializeOptions(options) }, cursorState)
+    );
+
     queryOptions.fullResult = true;
     queryOptions.command = true;
     server.s.pool.write(getMoreOp, queryOptions, queryCallback);

src/cmap/wire_protocol/query.ts

@@ -3,7 +3,7 @@ import { Query } from '../commands';
 import { MongoError } from '../../error';
 import { maxWireVersion, collectionNamespace, Callback } from '../../utils';
 import { getReadPreference, isSharded, applyCommonQueryOptions } from './shared';
-import type { Document } from '../../bson';
+import { Document, pluckBSONSerializeOptions } from '../../bson';
 import type { Server } from '../../sdam/server';
 import type { ReadPreferenceLike } from '../../read_preference';
 import type { InternalCursorState } from '../../cursor/core_cursor';
@@ -32,9 +32,12 @@ export function query(
 
   if (maxWireVersion(server) < 4) {
     const query = prepareLegacyFindQuery(server, ns, cmd, cursorState, options);
-    const queryOptions = applyCommonQueryOptions({}, cursorState);
-    queryOptions.fullResult = true;
+    const queryOptions = applyCommonQueryOptions(
+      {},
+      Object.assign({ bsonOptions: pluckBSONSerializeOptions(options) }, cursorState)
+    );
 
+    queryOptions.fullResult = true;
     if (typeof query.documentsReturnedIn === 'string') {
       queryOptions.documentsReturnedIn = query.documentsReturnedIn;
     }

src/cmap/wire_protocol/shared.ts

@@ -3,12 +3,12 @@ import { TopologyDescription } from '../../sdam/topology_description';
 import { MongoError } from '../../error';
 import { ReadPreference } from '../../read_preference';
 import type { Document } from '../../bson';
-import type { CommandOptions } from './command';
 import type { OpQueryOptions } from '../commands';
 import type { Topology } from '../../sdam/topology';
 import type { Server } from '../../sdam/server';
 import type { ServerDescription } from '../../sdam/server_description';
 import type { ReadPreferenceLike } from '../../read_preference';
+import type { InternalCursorState } from '../../cursor/core_cursor';
 
 export interface ReadPreferenceOption {
   readPreference?: ReadPreferenceLike;
@@ -35,27 +35,28 @@ export function getReadPreference(cmd: Document, options: ReadPreferenceOption):
 
 export function applyCommonQueryOptions(
   queryOptions: OpQueryOptions,
-  options: CommandOptions
+  cursorState: InternalCursorState
 ): OpQueryOptions {
-  Object.assign(queryOptions, {
-    raw: typeof options.raw === 'boolean' ? options.raw : false,
-    promoteLongs: typeof options.promoteLongs === 'boolean' ? options.promoteLongs : true,
-    promoteValues: typeof options.promoteValues === 'boolean' ? options.promoteValues : true,
-    promoteBuffers: typeof options.promoteBuffers === 'boolean' ? options.promoteBuffers : false,
-    monitoring: typeof options.monitoring === 'boolean' ? options.monitoring : false,
-    fullResult: typeof options.fullResult === 'boolean' ? options.fullResult : false
-  });
-
-  if (typeof options.socketTimeout === 'number') {
-    queryOptions.socketTimeout = options.socketTimeout;
-  }
-
-  if (options.session) {
-    queryOptions.session = options.session;
+  if (cursorState.bsonOptions) {
+    Object.assign(queryOptions, {
+      raw: typeof cursorState.bsonOptions.raw === 'boolean' ? cursorState.bsonOptions.raw : false,
+      promoteLongs:
+        typeof cursorState.bsonOptions.promoteLongs === 'boolean'
+          ? cursorState.bsonOptions.promoteLongs
+          : true,
+      promoteValues:
+        typeof cursorState.bsonOptions.promoteValues === 'boolean'
+          ? cursorState.bsonOptions.promoteValues
+          : true,
+      promoteBuffers:
+        typeof cursorState.bsonOptions.promoteBuffers === 'boolean'
+          ? cursorState.bsonOptions.promoteBuffers
+          : false
+    });
   }
 
-  if (typeof options.documentsReturnedIn === 'string') {
-    queryOptions.documentsReturnedIn = options.documentsReturnedIn;
+  if (cursorState.session) {
+    queryOptions.session = cursorState.session;
   }
 
   return queryOptions;

src/collection.ts

@@ -3,10 +3,6 @@ import { ReadPreference, ReadPreferenceLike } from './read_preference';
 import { deprecate } from 'util';
 import {
   normalizeHintField,
-  decorateCommand,
-  decorateWithCollation,
-  decorateWithReadConcern,
-  formattedOrderClause,
   checkCollectionName,
   deprecateOptions,
   MongoDBNamespace,
@@ -91,8 +87,6 @@ import type { Topology } from './sdam/topology';
 import type { Logger, LoggerOptions } from './logger';
 import type { OperationParent } from './operations/command';
 
-const mergeKeys = ['ignoreUndefined'];
-
 /** @public */
 export interface Collection {
   /** @deprecated Use {@link Collection.dropIndexes#Class} instead */
@@ -138,6 +132,7 @@ export interface CollectionPrivate {
   promoteLongs?: boolean;
   promoteValues?: boolean;
   promoteBuffers?: boolean;
+  ignoreUndefined?: boolean;
   collectionHint?: Hint;
   readConcern?: ReadConcern;
   writeConcern?: WriteConcern;
@@ -212,7 +207,11 @@ export class Collection implements OperationParent {
       promoteBuffers:
         options == null || options.promoteBuffers == null
           ? db.s.options?.promoteBuffers
-          : options.promoteBuffers
+          : options.promoteBuffers,
+      ignoreUndefined:
+        options == null || options.ignoreUndefined == null
+          ? db.s.options?.ignoreUndefined
+          : options.ignoreUndefined
     };
   }
 
@@ -680,155 +679,24 @@ export class Collection implements OperationParent {
   /**
    * Creates a cursor for a query that can be used to iterate over results from MongoDB
    *
-   * @param query - The cursor query object.
-   * @param options - Optional settings for the command
+   * @param filter - The query predicate. If unspecified, then all documents in the collection will match the predicate
    */
   find(): Cursor;
-  find(query: Document): Cursor;
-  find(query: Document, options: FindOptions): Cursor;
-  find(query?: Document, options?: FindOptions): Cursor {
+  find(filter: Document): Cursor;
+  find(filter: Document, options: FindOptions): Cursor;
+  find(filter?: Document, options?: FindOptions): Cursor {
     if (arguments.length > 2) {
       throw new TypeError('Third parameter to `collection.find()` must be undefined');
     }
-    if (typeof query === 'function') {
-      throw new TypeError('`query` parameter must not be function');
-    }
     if (typeof options === 'function') {
       throw new TypeError('`options` parameter must not be function');
     }
 
-    let selector =
-      query !== null && typeof query === 'object' && Array.isArray(query) === false ? query : {};
-
-    // Validate correctness off the selector
-    const object = selector;
-    if (Buffer.isBuffer(object)) {
-      const object_size = object[0] | (object[1] << 8) | (object[2] << 16) | (object[3] << 24);
-      if (object_size !== object.length) {
-        const error = new Error(
-          'query selector raw message size does not match message header size [' +
-            object.length +
-            '] != [' +
-            object_size +
-            ']'
-        );
-        error.name = 'MongoError';
-        throw error;
-      }
-    }
-
-    // Check special case where we are using an objectId
-    if (selector != null && selector._bsontype === 'ObjectID') {
-      selector = { _id: selector };
-    }
-
-    if (!options) {
-      options = {};
-    }
-
-    let projection = options.projection || options.fields;
-
-    if (projection && !Buffer.isBuffer(projection) && Array.isArray(projection)) {
-      projection = projection.length
-        ? projection.reduce((result, field) => {
-            result[field] = 1;
-            return result;
-          }, {})
-        : { _id: 1 };
-    }
-
-    // Make a shallow copy of options
-    const newOptions: Document = Object.assign({}, options);
-
-    // Make a shallow copy of the collection options
-    for (const key in this.s.options) {
-      if (mergeKeys.indexOf(key) !== -1) {
-        newOptions[key] = this.s.options[key];
-      }
-    }
-
-    // Unpack options
-    newOptions.skip = options.skip ? options.skip : 0;
-    newOptions.limit = options.limit ? options.limit : 0;
-    newOptions.raw = typeof options.raw === 'boolean' ? options.raw : this.s.raw;
-    newOptions.hint =
-      options.hint != null ? normalizeHintField(options.hint) : this.s.collectionHint;
-    newOptions.timeout = typeof options.timeout === 'undefined' ? undefined : options.timeout;
-    // // If we have overridden slaveOk otherwise use the default db setting
-    newOptions.slaveOk = options.slaveOk != null ? options.slaveOk : this.s.db.slaveOk;
-
-    // Add read preference if needed
-    newOptions.readPreference = ReadPreference.resolve(this, newOptions);
-
-    // Set slave ok to true if read preference different from primary
-    if (
-      newOptions.readPreference != null &&
-      (newOptions.readPreference !== 'primary' || newOptions.readPreference.mode !== 'primary')
-    ) {
-      newOptions.slaveOk = true;
-    }
-
-    // Ensure the query is an object
-    if (selector != null && typeof selector !== 'object') {
-      throw new MongoError('query selector must be an object');
-    }
-
-    // Build the find command
-    const findCommand: Document = {
-      find: this.s.namespace.toString(),
-      limit: newOptions.limit,
-      skip: newOptions.skip,
-      query: selector
-    };
-
-    if (typeof options.allowDiskUse === 'boolean') {
-      findCommand.allowDiskUse = options.allowDiskUse;
-    }
-
-    // Ensure we use the right await data option
-    if (typeof newOptions.awaitdata === 'boolean') {
-      newOptions.awaitData = newOptions.awaitdata;
-    }
-
-    // Translate to new command option noCursorTimeout
-    if (typeof newOptions.timeout === 'boolean') newOptions.noCursorTimeout = newOptions.timeout;
-
-    decorateCommand(findCommand, newOptions, ['session', 'collation']);
-
-    if (projection) findCommand.fields = projection;
-
-    // Add db object to the new options
-    newOptions.db = this.s.db;
-
-    // Set raw if available at collection level
-    if (newOptions.raw == null && typeof this.s.raw === 'boolean') newOptions.raw = this.s.raw;
-    // Set promoteLongs if available at collection level
-    if (newOptions.promoteLongs == null && typeof this.s.promoteLongs === 'boolean')
-      newOptions.promoteLongs = this.s.promoteLongs;
-    if (newOptions.promoteValues == null && typeof this.s.promoteValues === 'boolean')
-      newOptions.promoteValues = this.s.promoteValues;
-    if (newOptions.promoteBuffers == null && typeof this.s.promoteBuffers === 'boolean')
-      newOptions.promoteBuffers = this.s.promoteBuffers;
-
-    // Sort options
-    if (findCommand.sort) {
-      findCommand.sort = formattedOrderClause(findCommand.sort);
-    }
-
-    // Set the readConcern
-    decorateWithReadConcern(findCommand, this, options);
-
-    // Decorate find command with collation options
-
-    decorateWithCollation(findCommand, this, options);
-
-    const cursor = new Cursor(
+    return new Cursor(
       this.s.topology,
-      new FindOperation(this, this.s.namespace, findCommand, newOptions),
-      newOptions
+      new FindOperation(this, this.s.namespace, filter, options),
+      options
     );
-
-    return cursor;
   }
 
   /**