feat(NODE-4970): deprecate collStats collection helper (#3638)

Co-authored-by: Durran Jordan <durran@gmail.com>

src/collection.ts

@@ -784,6 +784,9 @@ export class Collection<TSchema extends Document = Document> {
   /**
    * Get all the collection statistics.
    *
+   * @deprecated the `collStats` operation will be removed in the next major release.  Please
+   * use an aggregation pipeline with the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) stage instead
+   *
    * @param options - Optional settings for the command
    */
   async stats(options?: CollStatsOptions): Promise<CollStats> {

src/operations/stats.ts

@@ -7,7 +7,11 @@ import type { Callback } from '../utils';
 import { CommandOperation, CommandOperationOptions } from './command';
 import { Aspect, defineAspects } from './operation';
 
-/** @public */
+/**
+ * @public
+ * @deprecated the `collStats` operation will be removed in the next major release.  Please
+ * use an aggregation pipeline with the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) stage instead
+ */
 export interface CollStatsOptions extends CommandOperationOptions {
   /** Divide the returned sizes by scale value. */
   scale?: number;
@@ -77,6 +81,8 @@ export class DbStatsOperation extends CommandOperation<Document> {
 }
 
 /**
+ * @deprecated the `collStats` operation will be removed in the next major release.  Please
+ * use an aggregation pipeline with the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) stage instead
  * @public
  * @see https://www.mongodb.com/docs/manual/reference/command/collStats/
  */
@@ -130,7 +136,10 @@ export interface CollStats extends Document {
   scaleFactor: number;
 }
 
-/** @public */
+/**
+ * @public
+ * @deprecated This type is only used for the deprecated `collStats` operation and will be removed in the next major release.
+ */
 export interface WiredTigerData extends Document {
   LSM: {
     'bloom filter false positives': number;

test/spec/client-side-encryption/tests/legacy/bypassedCommand.json

@@ -78,7 +78,7 @@
       ]
     },
     {
-      "description": "current op is not bypassed",
+      "description": "kill op is not bypassed",
       "clientOptions": {
         "autoEncryptOpts": {
           "kmsProviders": {
@@ -90,14 +90,15 @@
         {
           "name": "runCommand",
           "object": "database",
-          "command_name": "currentOp",
+          "command_name": "killOp",
           "arguments": {
             "command": {
-              "currentOp": 1
+              "killOp": 1,
+              "op": 1234
             }
           },
           "result": {
-            "errorContains": "command not supported for auto encryption: currentOp"
+            "errorContains": "command not supported for auto encryption: killOp"
           }
         }
       ]

test/spec/client-side-encryption/tests/legacy/bypassedCommand.yml

@@ -26,17 +26,18 @@ tests:
           command:
             ping: 1
           command_name: ping
-  - description: "current op is not bypassed"
+  - description: "kill op is not bypassed"
     clientOptions:
       autoEncryptOpts:
         kmsProviders:
           aws: {} # Credentials filled in from environment.
     operations:
       - name: runCommand
         object: database
-        command_name: currentOp
+        command_name: killOp
         arguments:
           command:
-            currentOp: 1
+            killOp: 1
+            op: 1234 
         result:
-          errorContains: "command not supported for auto encryption: currentOp"
+          errorContains: "command not supported for auto encryption: killOp"

test/spec/unified-test-format/valid-pass/collectionData-createOptions.json

@@ -0,0 +1,79 @@
+{
+  "description": "collectionData-createOptions",
+  "schemaVersion": "1.9",
+  "runOnRequirements": [
+    {
+      "minServerVersion": "3.6",
+      "serverless": "forbid"
+    }
+  ],
+  "createEntities": [
+    {
+      "client": {
+        "id": "client0"
+      }
+    },
+    {
+      "database": {
+        "id": "database0",
+        "client": "client0",
+        "databaseName": "database0"
+      }
+    },
+    {
+      "collection": {
+        "id": "collection0",
+        "database": "database0",
+        "collectionName": "coll0"
+      }
+    }
+  ],
+  "initialData": [
+    {
+      "collectionName": "coll0",
+      "databaseName": "database0",
+      "createOptions": {
+        "capped": true,
+        "size": 4096
+      },
+      "documents": [
+        {
+          "_id": 1,
+          "x": 11
+        }
+      ]
+    }
+  ],
+  "tests": [
+    {
+      "description": "collection is created with the correct options",
+      "operations": [
+        {
+          "object": "collection0",
+          "name": "aggregate",
+          "arguments": {
+            "pipeline": [
+              {
+                "$collStats": {
+                  "storageStats": {}
+                }
+              },
+              {
+                "$project": {
+                  "capped": "$storageStats.capped",
+                  "maxSize": "$storageStats.maxSize"
+                }
+              }
+            ]
+          },
+          "expectResult": [
+            {
+              "capped": true,
+              "maxSize": 4096
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

test/spec/unified-test-format/valid-pass/collectionData-createOptions.yml

@@ -0,0 +1,42 @@
+description: collectionData-createOptions
+
+schemaVersion: "1.9"
+
+runOnRequirements:
+  - minServerVersion: "3.6"
+    # Capped collections cannot be created on serverless instances.
+    serverless: forbid
+
+createEntities:
+  - client:
+      id: &client0 client0
+  - database:
+      id: &database0 database0
+      client: *client0
+      databaseName: &database0Name database0
+  - collection:
+      id: &collection0 collection0
+      database: *database0
+      collectionName: &collection0Name coll0
+
+initialData:
+  - collectionName: *collection0Name
+    databaseName: *database0Name
+    createOptions:
+      capped: true
+      # With MMAPv1, the size field cannot be less than 4096.
+      size: &cappedSize 4096
+    documents:
+      - { _id: 1, x: 11 }
+
+tests:
+  - description: collection is created with the correct options
+    operations:
+      - object: *collection0
+        name: aggregate
+        arguments:
+          pipeline:
+            - $collStats: { storageStats: {} }
+            - $project: { capped: '$storageStats.capped', maxSize: '$storageStats.maxSize'}
+        expectResult:
+          - { capped: true, maxSize: *cappedSize }

test/tools/unified-spec-runner/runner.ts

@@ -118,38 +118,44 @@ async function runUnifiedTest(
     // The test runner MUST use the internal MongoClient for these operations.
     if (unifiedSuite.initialData) {
       trace('initialData');
-      for (const collData of unifiedSuite.initialData) {
-        const db = utilClient.db(collData.databaseName);
-        const collection = db.collection(collData.collectionName, {
+      for (const { databaseName, collectionName } of unifiedSuite.initialData) {
+        const db = utilClient.db(databaseName);
+        const collection = db.collection(collectionName, {
           writeConcern: { w: 'majority' }
         });
 
         trace('listCollections');
-        const collectionList = await db
-          .listCollections({ name: collData.collectionName })
-          .toArray();
+        const collectionList = await db.listCollections({ name: collectionName }).toArray();
         if (collectionList.length !== 0) {
           trace('drop');
           expect(await collection.drop()).to.be.true;
         }
       }
 
-      for (const collData of unifiedSuite.initialData) {
-        const db = utilClient.db(collData.databaseName);
-        const collection = db.collection(collData.collectionName, {
+      for (const {
+        databaseName,
+        collectionName,
+        createOptions,
+        documents = []
+      } of unifiedSuite.initialData) {
+        const db = utilClient.db(databaseName);
+        const collection = db.collection(collectionName, {
           writeConcern: { w: 'majority' }
         });
 
-        if (!collData.documents?.length) {
+        if (createOptions || !documents.length) {
           trace('createCollection');
-          await db.createCollection(collData.collectionName, {
+          const options = createOptions ?? {};
+          await db.createCollection(collectionName, {
+            ...options,
             writeConcern: { w: 'majority' }
           });
-          continue;
         }
 
-        trace('insertMany');
-        await collection.insertMany(collData.documents);
+        if (documents.length > 0) {
+          trace('insertMany');
+          await collection.insertMany(documents);
+        }
       }
     }
 

test/tools/unified-spec-runner/schema.ts

@@ -238,6 +238,7 @@ export interface CollectionOrDatabaseOptions {
 export interface CollectionData {
   collectionName: string;
   databaseName: string;
+  createOptions?: Document;
   documents: Document[];
 }
 export interface Test {