feat(FindCursor): fluent builder for allowDiskUse option (#2678)

NODE-2955

src/cursor/find_cursor.ts

@@ -353,6 +353,21 @@ export class FindCursor extends AbstractCursor {
     return this;
   }
 
+  /**
+   * Allows disk use for blocking sort operations exceeding 100MB memory. (MongoDB 3.2 or higher)
+   *
+   * @remarks
+   * {@link https://docs.mongodb.com/manual/reference/command/find/#find-cmd-allowdiskuse | find command allowDiskUse documentation}
+   */
+  allowDiskUse(): this {
+    assertUninitialized(this);
+    if (!this[kBuiltOptions].sort) {
+      throw new MongoError('allowDiskUse requires a sort specification');
+    }
+    this[kBuiltOptions].allowDiskUse = true;
+    return this;
+  }
+
   /**
    * Set the collation options for the cursor.
    *

src/operations/find.ts

@@ -52,7 +52,7 @@ export interface FindOptions extends CommandOperationOptions {
   noCursorTimeout?: boolean;
   /** Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields). */
   collation?: CollationOptions;
-  /** Enables writing to temporary files on the server. */
+  /** Allows disk use for blocking sort operations exceeding 100MB memory. (MongoDB 3.2 or higher) */
   allowDiskUse?: boolean;
   /** Determines whether to close the cursor after the first batch. Defaults to false. */
   singleBatch?: boolean;

test/functional/cursor.test.js

@@ -1,5 +1,5 @@
 'use strict';
-const { assert: test, filterForCommands, withMonitoredClient } = require('./shared');
+const { assert: test, filterForCommands, withClient, withMonitoredClient } = require('./shared');
 const { setupDatabase } = require('./shared');
 const fs = require('fs');
 const { expect } = require('chai');
@@ -4089,5 +4089,37 @@ describe('Cursor', function () {
         beta: 1
       });
     });
+
+    it('should use allowDiskUse option on sort', {
+      metadata: { requires: { mongodb: '>=4.4' } },
+      test: withMonitoredClient('find', function (client, events, done) {
+        const db = client.db('test');
+        db.collection('test_sort_allow_disk_use', (err, collection) => {
+          expect(err).to.not.exist;
+          const cursor = collection.find({}).sort(['alpha', 1]).allowDiskUse();
+          cursor.next(err => {
+            expect(err).to.not.exist;
+            const { command } = events.shift();
+            expect(command.sort).to.deep.equal({ alpha: 1 });
+            expect(command.allowDiskUse).to.be.true;
+            cursor.close(done);
+          });
+        });
+      })
+    });
+
+    it('should error if allowDiskUse option used without sort', {
+      metadata: { requires: { mongodb: '>=4.4' } },
+      test: withClient(function (client, done) {
+        const db = client.db('test');
+        db.collection('test_sort_allow_disk_use', (err, collection) => {
+          expect(err).to.not.exist;
+          expect(() => collection.find({}).allowDiskUse()).to.throw(
+            /allowDiskUse requires a sort specification/
+          );
+          done();
+        });
+      })
+    });
   });
 });