feat(NODE-3867): deprecate cursor count and update v4 docs (#3127)

Author: nbbeeken

docs/CHANGES_4.0.0.md

@@ -96,6 +96,13 @@ for await (const doc of cursor) {
 Prior to the this release there was inconsistency surrounding how the cursor would error if a setting like limit was applied after cursor execution had begun.
 Now, an error along the lines of: `Cursor is already initialized` is thrown.
 
+##### Cursor.count always respects skip and limit
+
+> Updated: Feb 3rd 2022
+
+The `applySkipLimit` argument has been removed from `cursor.count`, cursors will always passthrough the skip and limit to the underlying count operation.
+It is recommended that users utilize the `collection.countDocuments` or `collection.estimatedDocumentCount` APIs.
+
 #### ChangeStream must be used as an iterator or an event emitter
 
 You cannot use ChangeStream as an iterator after using as an EventEmitter nor visa versa.

src/cursor/find_cursor.ts

@@ -9,8 +9,7 @@ import type { Hint } from '../operations/operation';
 import type { Topology } from '../sdam/topology';
 import type { ClientSession } from '../sessions';
 import { formatSort, Sort, SortDirection } from '../sort';
-import type { Callback, MongoDBNamespace } from '../utils';
-import { mergeOptions } from '../utils';
+import { Callback, emitWarningOnce, mergeOptions, MongoDBNamespace } from '../utils';
 import { AbstractCursor, assertUninitialized } from './abstract_cursor';
 
 /** @internal */
@@ -118,15 +117,24 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
     });
   }
 
-  /** Get the count of documents for this cursor */
+  /**
+   * Get the count of documents for this cursor
+   * @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead
+   */
   count(): Promise<number>;
+  /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */
   count(callback: Callback<number>): void;
+  /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */
   count(options: CountOptions): Promise<number>;
+  /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */
   count(options: CountOptions, callback: Callback<number>): void;
   count(
     options?: CountOptions | Callback<number>,
     callback?: Callback<number>
   ): Promise<number> | void {
+    emitWarningOnce(
+      'cursor.count is deprecated and will be removed in the next major version, please use `collection.estimatedDocumentCount` or `collection.countDocuments` instead '
+    );
     if (typeof options === 'boolean') {
       throw new MongoInvalidArgumentError('Invalid first parameter to count');
     }

test/types/mongodb.test-d.ts

@@ -6,7 +6,7 @@ import * as MongoDBDriver from '../../src';
 import type { ChangeStreamDocument } from '../../src/change_stream';
 import { Collection } from '../../src/collection';
 import { AggregationCursor } from '../../src/cursor/aggregation_cursor';
-import type { FindCursor } from '../../src/cursor/find_cursor';
+import { FindCursor } from '../../src/cursor/find_cursor';
 import { MongoClient } from '../../src/mongo_client';
 import { Topology } from '../../src/sdam/topology';
 
@@ -17,6 +17,7 @@ expectDeprecated(Collection.prototype.remove);
 expectDeprecated(Collection.prototype.count);
 expectDeprecated(Collection.prototype.mapReduce);
 expectDeprecated(AggregationCursor.prototype.geoNear);
+expectDeprecated(FindCursor.prototype.count);
 expectDeprecated(Topology.prototype.unref);
 expectDeprecated(Db.prototype.unref);
 expectDeprecated(MongoDBDriver.ObjectID);