feat(shell-api): add .finish() method to ExplainableCursor MONGOSH-1493 (#2475)

Author: addaleax

packages/shell-api/src/cursor.ts

@@ -62,7 +62,7 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
 
   @returnType('Cursor')
   @serverVersions([ServerVersions.earliest, '3.2.0'])
-  addOption(optionFlagNumber: number): Cursor {
+  addOption(optionFlagNumber: number): this {
     if (optionFlagNumber === 4) {
       throw new MongoshUnimplementedError(
         'the slaveOk option is not supported.',
@@ -86,27 +86,27 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
 
   @returnType('Cursor')
   @serverVersions(['4.4.0', ServerVersions.latest])
-  allowDiskUse(allow?: boolean): Cursor {
+  allowDiskUse(allow?: boolean): this {
     this._cursor.allowDiskUse(allow);
     return this;
   }
 
   @returnType('Cursor')
-  allowPartialResults(): Cursor {
+  allowPartialResults(): this {
     this._addFlag('partial');
     return this;
   }
 
   @returnType('Cursor')
   @serverVersions(['3.4.0', ServerVersions.latest])
-  collation(spec: CollationOptions): Cursor {
+  collation(spec: CollationOptions): this {
     this._cursor.collation(spec);
     return this;
   }
 
   @returnType('Cursor')
   @serverVersions(['3.2.0', ServerVersions.latest])
-  comment(cmt: string): Cursor {
+  comment(cmt: string): this {
     this._cursor.comment(cmt);
     return this;
   }
@@ -130,32 +130,32 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
   }
 
   @returnType('Cursor')
-  hint(index: string): Cursor {
+  hint(index: string): this {
     this._cursor.hint(index);
     return this;
   }
 
   @returnType('Cursor')
-  limit(value: number): Cursor {
+  limit(value: number): this {
     this._cursor.limit(value);
     return this;
   }
 
   @returnType('Cursor')
-  max(indexBounds: Document): Cursor {
+  max(indexBounds: Document): this {
     this._cursor.max(indexBounds);
     return this;
   }
 
   @returnType('Cursor')
   @serverVersions(['3.2.0', ServerVersions.latest])
-  maxAwaitTimeMS(value: number): Cursor {
+  maxAwaitTimeMS(value: number): this {
     this._cursor.maxAwaitTimeMS(value);
     return this;
   }
 
   @returnType('Cursor')
-  min(indexBounds: Document): Cursor {
+  min(indexBounds: Document): this {
     this._cursor.min(indexBounds);
     return this;
   }
@@ -172,13 +172,13 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
   }
 
   @returnType('Cursor')
-  noCursorTimeout(): Cursor {
+  noCursorTimeout(): this {
     this._addFlag('noCursorTimeout');
     return this;
   }
 
   @returnType('Cursor')
-  oplogReplay(): Cursor {
+  oplogReplay(): this {
     this._addFlag('oplogReplay');
     return this;
   }
@@ -188,7 +188,7 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
     mode: ReadPreferenceLike,
     tagSet?: TagSet[],
     hedgeOptions?: HedgeOptions
-  ): Cursor {
+  ): this {
     let pref: ReadPreferenceLike;
 
     // Only conditionally use readPreferenceFromOptions, for java-shell compatibility.
@@ -207,7 +207,7 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
 
   @returnType('Cursor')
   @serverVersions(['3.2.0', ServerVersions.latest])
-  returnKey(enabled: boolean): Cursor {
+  returnKey(enabled: boolean): this {
     this._cursor.returnKey(enabled);
     return this;
   }
@@ -220,7 +220,7 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
   @returnType('Cursor')
   @serverVersions(['3.2.0', ServerVersions.latest])
   @apiVersions([])
-  tailable(opts = { awaitData: false }): Cursor {
+  tailable(opts = { awaitData: false }): this {
     this._tailable = true;
     this._addFlag('tailable');
     if (opts.awaitData) {
@@ -239,13 +239,13 @@ export default class Cursor extends AggregateOrFindCursor<ServiceProviderFindCur
 
   @returnType('Cursor')
   @serverVersions(['3.2.0', ServerVersions.latest])
-  showRecordId(): Cursor {
+  showRecordId(): this {
     this._cursor.showRecordId(true);
     return this;
   }
 
   @returnType('Cursor')
-  readConcern(level: ReadConcernLevel): Cursor {
+  readConcern(level: ReadConcernLevel): this {
     this._cursor = this._cursor.withReadConcern({ level });
     return this;
   }

packages/shell-api/src/explainable-cursor.ts

@@ -1,4 +1,4 @@
-import { shellApiClassDefault } from './decorators';
+import { returnsPromise, shellApiClassDefault } from './decorators';
 import Cursor from './cursor';
 import type Mongo from './mongo';
 import { asPrintable } from './enums';
@@ -21,6 +21,11 @@ export default class ExplainableCursor extends Cursor {
    * Internal method to determine what is printed for this class.
    */
   async [asPrintable](): Promise<any> {
+    return await this.finish();
+  }
+
+  @returnsPromise
+  async finish(): Promise<any> {
     // Cache the result so that we don't explain over and over again for the
     // same object.
     this._explained ??= await this._baseCursor.explain(this._verbosity);

packages/shell-api/src/integration.spec.ts

@@ -1597,6 +1597,16 @@ describe('Shell API (integration)', function () {
         ]);
       });
 
+      it('returns a cursor whose .finish() method returns the explain result', async function () {
+        const cursor = (await explainable.find()).skip(1).limit(1);
+        const result = await cursor.finish();
+        expect(result).to.include.all.keys([
+          'ok',
+          'queryPlanner',
+          'serverInfo',
+        ]);
+      });
+
       describe('after server 4.4', function () {
         skipIfServerVersion(testServer, '<= 4.4');
         it('the explainable cursor reflects collation', async function () {