mongodb 4.1.4 → 4.3.0

package/src/collection.ts

@@ -1,101 +1,104 @@
-import { DEFAULT_PK_FACTORY, emitWarningOnce, resolveOptions } from './utils';
-import { ReadPreference, ReadPreferenceLike } from './read_preference';
-import {
-  normalizeHintField,
-  checkCollectionName,
-  MongoDBNamespace,
-  Callback,
-  getTopology
-} from './utils';
-import { Document, BSONSerializeOptions, resolveBSONOptions } from './bson';
-import { MongoInvalidArgumentError } from './error';
-import { UnorderedBulkOperation } from './bulk/unordered';
+import { BSONSerializeOptions, Document, resolveBSONOptions } from './bson';
+import type { AnyBulkWriteOperation, BulkWriteOptions, BulkWriteResult } from './bulk/common';
 import { OrderedBulkOperation } from './bulk/ordered';
+import { UnorderedBulkOperation } from './bulk/unordered';
 import { ChangeStream, ChangeStreamOptions } from './change_stream';
-import { WriteConcern, WriteConcernOptions } from './write_concern';
-import { ReadConcern, ReadConcernLike } from './read_concern';
 import { AggregationCursor } from './cursor/aggregation_cursor';
+import { FindCursor } from './cursor/find_cursor';
+import type { Db } from './db';
+import { MongoInvalidArgumentError } from './error';
+import type { Logger, LoggerOptions } from './logger';
+import type { PkFactory } from './mongo_client';
+import type {
+  Filter,
+  Flatten,
+  OptionalUnlessRequiredId,
+  TODO_NODE_3286,
+  UpdateFilter,
+  WithId,
+  WithoutId
+} from './mongo_types';
 import type { AggregateOptions } from './operations/aggregate';
 import { BulkWriteOperation } from './operations/bulk_write';
+import type { IndexInformationOptions } from './operations/common_functions';
+import type { CountOptions } from './operations/count';
 import { CountDocumentsOperation, CountDocumentsOptions } from './operations/count_documents';
 import {
-  CreateIndexesOperation,
-  CreateIndexOperation,
-  DropIndexOperation,
-  DropIndexesOperation,
-  IndexesOperation,
-  IndexExistsOperation,
-  IndexInformationOperation,
-  CreateIndexesOptions,
-  DropIndexesOptions,
-  ListIndexesOptions,
-  IndexSpecification,
-  IndexDescription,
-  ListIndexesCursor
-} from './operations/indexes';
+  DeleteManyOperation,
+  DeleteOneOperation,
+  DeleteOptions,
+  DeleteResult
+} from './operations/delete';
 import { DistinctOperation, DistinctOptions } from './operations/distinct';
 import { DropCollectionOperation, DropCollectionOptions } from './operations/drop';
 import {
   EstimatedDocumentCountOperation,
   EstimatedDocumentCountOptions
 } from './operations/estimated_document_count';
+import { executeOperation } from './operations/execute_operation';
 import type { FindOptions } from './operations/find';
 import {
   FindOneAndDeleteOperation,
-  FindOneAndReplaceOperation,
-  FindOneAndUpdateOperation,
   FindOneAndDeleteOptions,
+  FindOneAndReplaceOperation,
   FindOneAndReplaceOptions,
+  FindOneAndUpdateOperation,
   FindOneAndUpdateOptions
 } from './operations/find_and_modify';
 import {
+  CreateIndexesOperation,
+  CreateIndexesOptions,
+  CreateIndexOperation,
+  DropIndexesOperation,
+  DropIndexesOptions,
+  DropIndexOperation,
+  IndexDescription,
+  IndexesOperation,
+  IndexExistsOperation,
+  IndexInformationOperation,
+  IndexSpecification,
+  ListIndexesCursor,
+  ListIndexesOptions
+} from './operations/indexes';
+import {
+  InsertManyOperation,
+  InsertManyResult,
   InsertOneOperation,
   InsertOneOptions,
-  InsertOneResult,
-  InsertManyOperation,
-  InsertManyResult
+  InsertOneResult
 } from './operations/insert';
-import {
-  UpdateOneOperation,
-  UpdateManyOperation,
-  UpdateOptions,
-  UpdateResult,
-  ReplaceOneOperation,
-  ReplaceOptions
-} from './operations/update';
-import {
-  DeleteOneOperation,
-  DeleteManyOperation,
-  DeleteOptions,
-  DeleteResult
-} from './operations/delete';
 import { IsCappedOperation } from './operations/is_capped';
 import {
-  MapReduceOperation,
   MapFunction,
-  ReduceFunction,
-  MapReduceOptions
+  MapReduceOperation,
+  MapReduceOptions,
+  ReduceFunction
 } from './operations/map_reduce';
+import type { Hint, OperationOptions } from './operations/operation';
 import { OptionsOperation } from './operations/options_operation';
 import { RenameOperation, RenameOptions } from './operations/rename';
 import { CollStats, CollStatsOperation, CollStatsOptions } from './operations/stats';
-import { executeOperation } from './operations/execute_operation';
-import type { Db } from './db';
-import type { OperationOptions, Hint } from './operations/operation';
-import type { IndexInformationOptions } from './operations/common_functions';
-import type { BulkWriteResult, BulkWriteOptions, AnyBulkWriteOperation } from './bulk/common';
-import type { PkFactory } from './mongo_client';
-import type { Logger, LoggerOptions } from './logger';
-import { FindCursor } from './cursor/find_cursor';
-import type { CountOptions } from './operations/count';
-import type {
-  Filter,
-  TODO_NODE_3286,
-  UpdateFilter,
-  WithId,
-  OptionalId,
-  Flatten
-} from './mongo_types';
+import {
+  ReplaceOneOperation,
+  ReplaceOptions,
+  UpdateManyOperation,
+  UpdateOneOperation,
+  UpdateOptions,
+  UpdateResult
+} from './operations/update';
+import { ReadConcern, ReadConcernLike } from './read_concern';
+import { ReadPreference, ReadPreferenceLike } from './read_preference';
+import {
+  Callback,
+  checkCollectionName,
+  DEFAULT_PK_FACTORY,
+  emitWarningOnce,
+  getTopology,
+  MongoDBNamespace,
+  normalizeHintField,
+  resolveOptions
+} from './utils';
+import { WriteConcern, WriteConcernOptions } from './write_concern';
 
 /** @public */
 export interface ModifyResult<TSchema = Document> {
@@ -109,6 +112,9 @@ export interface CollectionOptions
   extends BSONSerializeOptions,
     WriteConcernOptions,
     LoggerOptions {
+  /**
+   * @deprecated Use readPreference instead
+   */
   slaveOk?: boolean;
   /** Specify a read concern for the collection. (only MongoDB 3.2 or higher supported) */
   readConcern?: ReadConcernLike;
@@ -124,7 +130,6 @@ export interface CollectionPrivate {
   namespace: MongoDBNamespace;
   readPreference?: ReadPreference;
   bsonOptions: BSONSerializeOptions;
-  slaveOk?: boolean;
   collectionHint?: Hint;
   readConcern?: ReadConcern;
   writeConcern?: WriteConcern;
@@ -178,8 +183,7 @@ export class Collection<TSchema extends Document = Document> {
       readPreference: ReadPreference.fromOptions(options),
       bsonOptions: resolveBSONOptions(options, db),
       readConcern: ReadConcern.fromOptions(options),
-      writeConcern: WriteConcern.fromOptions(options),
-      slaveOk: options == null || options.slaveOk == null ? db.slaveOk : options.slaveOk
+      writeConcern: WriteConcern.fromOptions(options)
     };
   }
 
@@ -261,16 +265,22 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  insertOne(doc: OptionalId<TSchema>): Promise<InsertOneResult<TSchema>>;
-  insertOne(doc: OptionalId<TSchema>, callback: Callback<InsertOneResult<TSchema>>): void;
-  insertOne(doc: OptionalId<TSchema>, options: InsertOneOptions): Promise<InsertOneResult<TSchema>>;
+  insertOne(doc: OptionalUnlessRequiredId<TSchema>): Promise<InsertOneResult<TSchema>>;
+  insertOne(
+    doc: OptionalUnlessRequiredId<TSchema>,
+    callback: Callback<InsertOneResult<TSchema>>
+  ): void;
   insertOne(
-    doc: OptionalId<TSchema>,
+    doc: OptionalUnlessRequiredId<TSchema>,
+    options: InsertOneOptions
+  ): Promise<InsertOneResult<TSchema>>;
+  insertOne(
+    doc: OptionalUnlessRequiredId<TSchema>,
     options: InsertOneOptions,
     callback: Callback<InsertOneResult<TSchema>>
   ): void;
   insertOne(
-    doc: OptionalId<TSchema>,
+    doc: OptionalUnlessRequiredId<TSchema>,
     options?: InsertOneOptions | Callback<InsertOneResult<TSchema>>,
     callback?: Callback<InsertOneResult<TSchema>>
   ): Promise<InsertOneResult<TSchema>> | void {
@@ -305,19 +315,22 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  insertMany(docs: OptionalId<TSchema>[]): Promise<InsertManyResult<TSchema>>;
-  insertMany(docs: OptionalId<TSchema>[], callback: Callback<InsertManyResult<TSchema>>): void;
+  insertMany(docs: OptionalUnlessRequiredId<TSchema>[]): Promise<InsertManyResult<TSchema>>;
+  insertMany(
+    docs: OptionalUnlessRequiredId<TSchema>[],
+    callback: Callback<InsertManyResult<TSchema>>
+  ): void;
   insertMany(
-    docs: OptionalId<TSchema>[],
+    docs: OptionalUnlessRequiredId<TSchema>[],
     options: BulkWriteOptions
   ): Promise<InsertManyResult<TSchema>>;
   insertMany(
-    docs: OptionalId<TSchema>[],
+    docs: OptionalUnlessRequiredId<TSchema>[],
     options: BulkWriteOptions,
     callback: Callback<InsertManyResult<TSchema>>
   ): void;
   insertMany(
-    docs: OptionalId<TSchema>[],
+    docs: OptionalUnlessRequiredId<TSchema>[],
     options?: BulkWriteOptions | Callback<InsertManyResult<TSchema>>,
     callback?: Callback<InsertManyResult<TSchema>>
   ): Promise<InsertManyResult<TSchema>> | void {
@@ -459,26 +472,29 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  replaceOne(filter: Filter<TSchema>, replacement: TSchema): Promise<UpdateResult | Document>;
   replaceOne(
     filter: Filter<TSchema>,
-    replacement: TSchema,
+    replacement: WithoutId<TSchema>
+  ): Promise<UpdateResult | Document>;
+  replaceOne(
+    filter: Filter<TSchema>,
+    replacement: WithoutId<TSchema>,
     callback: Callback<UpdateResult | Document>
   ): void;
   replaceOne(
     filter: Filter<TSchema>,
-    replacement: TSchema,
+    replacement: WithoutId<TSchema>,
     options: ReplaceOptions
   ): Promise<UpdateResult | Document>;
   replaceOne(
     filter: Filter<TSchema>,
-    replacement: TSchema,
+    replacement: WithoutId<TSchema>,
     options: ReplaceOptions,
     callback: Callback<UpdateResult | Document>
   ): void;
   replaceOne(
     filter: Filter<TSchema>,
-    replacement: TSchema,
+    replacement: WithoutId<TSchema>,
     options?: ReplaceOptions | Callback<UpdateResult | Document>,
     callback?: Callback<UpdateResult | Document>
   ): Promise<UpdateResult | Document> | void {
@@ -676,12 +692,16 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  findOne(): Promise<TSchema | null>;
-  findOne(callback: Callback<TSchema | null>): void;
-  findOne(filter: Filter<TSchema>): Promise<TSchema | null>;
-  findOne(filter: Filter<TSchema>, callback: Callback<TSchema | null>): void;
-  findOne(filter: Filter<TSchema>, options: FindOptions): Promise<TSchema | null>;
-  findOne(filter: Filter<TSchema>, options: FindOptions, callback: Callback<TSchema | null>): void;
+  findOne(): Promise<WithId<TSchema> | null>;
+  findOne(callback: Callback<WithId<TSchema> | null>): void;
+  findOne(filter: Filter<TSchema>): Promise<WithId<TSchema> | null>;
+  findOne(filter: Filter<TSchema>, callback: Callback<WithId<TSchema> | null>): void;
+  findOne(filter: Filter<TSchema>, options: FindOptions): Promise<WithId<TSchema> | null>;
+  findOne(
+    filter: Filter<TSchema>,
+    options: FindOptions,
+    callback: Callback<WithId<TSchema> | null>
+  ): void;
 
   // allow an override of the schema.
   findOne<T = TSchema>(): Promise<T | null>;
@@ -695,10 +715,10 @@ export class Collection<TSchema extends Document = Document> {
   ): void;
 
   findOne(
-    filter?: Filter<TSchema> | Callback<TSchema | null>,
-    options?: FindOptions | Callback<TSchema | null>,
-    callback?: Callback<TSchema | null>
-  ): Promise<TSchema | null> | void {
+    filter?: Filter<TSchema> | Callback<WithId<TSchema> | null>,
+    options?: FindOptions | Callback<WithId<TSchema> | null>,
+    callback?: Callback<WithId<TSchema> | null>
+  ): Promise<WithId<TSchema> | null> | void {
     if (callback != null && typeof callback !== 'function') {
       throw new MongoInvalidArgumentError(
         'Third parameter to `findOne()` must be a callback or undefined'
@@ -706,7 +726,7 @@ export class Collection<TSchema extends Document = Document> {
     }
 
     if (typeof filter === 'function') {
-      callback = filter as Callback<TSchema | null>;
+      callback = filter as Callback<WithId<TSchema> | null>;
       filter = {};
       options = {};
     }
@@ -725,10 +745,10 @@ export class Collection<TSchema extends Document = Document> {
    *
    * @param filter - The filter predicate. If unspecified, then all documents in the collection will match the predicate
    */
-  find(): FindCursor<TSchema>;
-  find(filter: Filter<TSchema>, options?: FindOptions): FindCursor<TSchema>;
+  find(): FindCursor<WithId<TSchema>>;
+  find(filter: Filter<TSchema>, options?: FindOptions): FindCursor<WithId<TSchema>>;
   find<T>(filter: Filter<TSchema>, options?: FindOptions): FindCursor<T>;
-  find(filter?: Filter<TSchema>, options?: FindOptions): FindCursor<TSchema> {
+  find(filter?: Filter<TSchema>, options?: FindOptions): FindCursor<WithId<TSchema>> {
     if (arguments.length > 2) {
       throw new MongoInvalidArgumentError(
         'Method "collection.find()" accepts at most two arguments'
@@ -738,7 +758,7 @@ export class Collection<TSchema extends Document = Document> {
       throw new MongoInvalidArgumentError('Argument "options" must not be function');
     }
 
-    return new FindCursor<TSchema>(
+    return new FindCursor<WithId<TSchema>>(
       getTopology(this),
       this.s.namespace,
       filter,
@@ -1275,26 +1295,29 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  findOneAndReplace(filter: Filter<TSchema>, replacement: Document): Promise<ModifyResult<TSchema>>;
   findOneAndReplace(
     filter: Filter<TSchema>,
-    replacement: Document,
+    replacement: WithoutId<TSchema>
+  ): Promise<ModifyResult<TSchema>>;
+  findOneAndReplace(
+    filter: Filter<TSchema>,
+    replacement: WithoutId<TSchema>,
     callback: Callback<ModifyResult<TSchema>>
   ): void;
   findOneAndReplace(
     filter: Filter<TSchema>,
-    replacement: Document,
+    replacement: WithoutId<TSchema>,
     options: FindOneAndReplaceOptions
   ): Promise<ModifyResult<TSchema>>;
   findOneAndReplace(
     filter: Filter<TSchema>,
-    replacement: Document,
+    replacement: WithoutId<TSchema>,
     options: FindOneAndReplaceOptions,
     callback: Callback<ModifyResult<TSchema>>
   ): void;
   findOneAndReplace(
     filter: Filter<TSchema>,
-    replacement: Document,
+    replacement: WithoutId<TSchema>,
     options?: FindOneAndReplaceOptions | Callback<ModifyResult<TSchema>>,
     callback?: Callback<ModifyResult<TSchema>>
   ): Promise<ModifyResult<TSchema>> | void {
@@ -1415,6 +1438,7 @@ export class Collection<TSchema extends Document = Document> {
   /**
    * Run Map Reduce across a collection. Be aware that the inline option for out will return an array of results not a collection.
    *
+   * @deprecated collection.mapReduce is deprecated. Use the aggregation pipeline instead. Visit https://docs.mongodb.com/manual/reference/map-reduce-to-aggregation-pipeline for more information on how to translate map-reduce operations to the aggregation pipeline.
    * @param map - The mapping function.
    * @param reduce - The reduce function.
    * @param options - Optional settings for the command
@@ -1446,6 +1470,9 @@ export class Collection<TSchema extends Document = Document> {
     options?: MapReduceOptions<TKey, TValue> | Callback<Document | Document[]>,
     callback?: Callback<Document | Document[]>
   ): Promise<Document | Document[]> | void {
+    emitWarningOnce(
+      'collection.mapReduce is deprecated. Use the aggregation pipeline instead. Visit https://docs.mongodb.com/manual/reference/map-reduce-to-aggregation-pipeline for more information on how to translate map-reduce operations to the aggregation pipeline.'
+    );
     if ('function' === typeof options) (callback = options), (options = {});
     // Out must always be defined (make sure we don't break weirdly on pre 1.8+ servers)
     // TODO NODE-3339: Figure out if this is still necessary given we no longer officially support pre-1.8
@@ -1509,7 +1536,7 @@ export class Collection<TSchema extends Document = Document> {
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
   insert(
-    docs: OptionalId<TSchema>[],
+    docs: OptionalUnlessRequiredId<TSchema>[],
     options: BulkWriteOptions,
     callback: Callback<InsertManyResult<TSchema>>
   ): Promise<InsertManyResult<TSchema>> | void {