feat(shell-api,autocomplete): skip deprecated methods MONGOSH-509 (#589)

Mark methods as deprecated and skip them for autocompletion.

Author: addaleax

packages/autocomplete/index.spec.ts

@@ -179,8 +179,11 @@ describe('completer.completer', () => {
 
     it('returns all suggestions', async() => {
       const i = 'db.';
-      const dbComplete = Object.keys(shellSignatures.Database.attributes as any);
-      const adjusted = dbComplete.map(c => `${i}${c}`);
+      const attr = shellSignatures.Database.attributes as any;
+      const dbComplete = Object.keys(attr);
+      const adjusted = dbComplete
+        .filter(c => !attr[c].deprecated)
+        .map(c => `${i}${c}`);
       expect(await completer(noParams, i)).to.deep.equal([adjusted, i]);
     });
 
@@ -221,7 +224,7 @@ describe('completer.completer', () => {
     it('returns all suggestions', async() => {
       const i = 'db.shipwrecks.';
       const collComplete = Object.keys(shellSignatures.Collection.attributes as any);
-      const adjusted = collComplete.filter(c => !['count', 'update', 'remove'].includes(c)).map(c => `${i}${c}`);
+      const adjusted = collComplete.filter(c => !['count', 'update', 'remove', 'insert', 'save'].includes(c)).map(c => `${i}${c}`);
 
       expect(await completer(sharded440, i)).to.deep.equal([adjusted, i]);
     });

packages/autocomplete/index.ts

@@ -1,6 +1,6 @@
 /* eslint complexity: 0, camelcase: 0, no-nested-ternary: 0 */
 
-import { signatures as shellSignatures, Topologies } from '@mongosh/shell-api';
+import { signatures as shellSignatures, Topologies, TypeSignature } from '@mongosh/shell-api';
 import semver from 'semver';
 import {
   CONVERSION_OPERATORS,
@@ -14,6 +14,8 @@ import {
   ON_PREM
 } from 'mongodb-ace-autocompleter';
 
+type TypeSignatureAttributes = { [key: string]: TypeSignature };
+
 export interface AutocompleteParameters {
   topology: () => Topologies;
   connectionInfo: () => undefined | {
@@ -49,13 +51,13 @@ const GROUP = '$group';
  * @returns {array} Matching Completions, Current User Input.
  */
 async function completer(params: AutocompleteParameters, line: string): Promise<[string[], string]> {
-  const SHELL_COMPLETIONS = shellSignatures.ShellApi.attributes;
-  const COLL_COMPLETIONS = shellSignatures.Collection.attributes;
-  const DB_COMPLETIONS = shellSignatures.Database.attributes;
-  const AGG_CURSOR_COMPLETIONS = shellSignatures.AggregationCursor.attributes;
-  const COLL_CURSOR_COMPLETIONS = shellSignatures.Cursor.attributes;
-  const RS_COMPLETIONS = shellSignatures.ReplicaSet.attributes;
-  const SHARD_COMPLETE = shellSignatures.Shard.attributes;
+  const SHELL_COMPLETIONS = shellSignatures.ShellApi.attributes as TypeSignatureAttributes;
+  const COLL_COMPLETIONS = shellSignatures.Collection.attributes as TypeSignatureAttributes;
+  const DB_COMPLETIONS = shellSignatures.Database.attributes as TypeSignatureAttributes;
+  const AGG_CURSOR_COMPLETIONS = shellSignatures.AggregationCursor.attributes as TypeSignatureAttributes;
+  const COLL_CURSOR_COMPLETIONS = shellSignatures.Cursor.attributes as TypeSignatureAttributes;
+  const RS_COMPLETIONS = shellSignatures.ReplicaSet.attributes as TypeSignatureAttributes;
+  const SHARD_COMPLETE = shellSignatures.Shard.attributes as TypeSignatureAttributes;
 
   // keep initial line param intact to always return in return statement
   // check for contents of line with:
@@ -174,17 +176,29 @@ function filterQueries(params: AutocompleteParameters, completions: any, prefix:
   return hits.map(h => `${split}${h.name}`);
 }
 
-function filterShellAPI(params: AutocompleteParameters, completions: any, prefix: string, split?: string[]): string[] {
-  const hits: string[] = Object.keys(completions).filter((c: any) => {
+function filterShellAPI(
+  params: AutocompleteParameters,
+  completions: { [key: string]: TypeSignature },
+  prefix: string,
+  split?: string[]): string[] {
+  const hits: string[] = Object.keys(completions).filter((c: string) => {
     if (!c.startsWith(prefix)) return false;
+    if (completions[c].deprecated) return false;
+
     const serverVersion = params.connectionInfo()?.server_version;
     if (!serverVersion) return true;
+
+    const acceptableVersions = completions[c].serverVersions;
     const isAcceptableVersion =
-      (semver.gte(serverVersion, completions[c].serverVersions[0]) &&
-       semver.lte(serverVersion, completions[c].serverVersions[1]));
+      !acceptableVersions ||
+      (semver.gte(serverVersion, acceptableVersions[0]) &&
+       semver.lte(serverVersion, acceptableVersions[1]));
+
+    const acceptableTopologies = completions[c].topologies;
     const isAcceptableTopology =
-      !completions[c].topologies ||
-      completions[c].topologies.includes(params.topology());
+      !acceptableTopologies ||
+      acceptableTopologies.includes(params.topology());
+
     return isAcceptableVersion && isAcceptableTopology;
   });
 

packages/shell-api/src/aggregation-cursor.spec.ts

@@ -24,6 +24,7 @@ describe('AggregationCursor', () => {
       expect(signatures.AggregationCursor.attributes.map).to.deep.equal({
         type: 'function',
         returnsPromise: false,
+        deprecated: false,
         returnType: 'AggregationCursor',
         platforms: ALL_PLATFORMS,
         topologies: ALL_TOPOLOGIES,

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

@@ -35,6 +35,7 @@ describe('Bulk API', () => {
         expect(signatures.Bulk.attributes.find).to.deep.equal({
           type: 'function',
           returnsPromise: false,
+          deprecated: false,
           returnType: 'BulkFindOp',
           platforms: ALL_PLATFORMS,
           topologies: ALL_TOPOLOGIES,
@@ -236,6 +237,7 @@ describe('Bulk API', () => {
         expect(signatures.BulkFindOp.attributes.hint).to.deep.equal({
           type: 'function',
           returnsPromise: false,
+          deprecated: false,
           returnType: 'BulkFindOp',
           platforms: ALL_PLATFORMS,
           topologies: ALL_TOPOLOGIES,

packages/shell-api/src/change-stream-cursor.spec.ts

@@ -30,6 +30,7 @@ describe('ChangeStreamCursor', () => {
       expect(signatures.ChangeStreamCursor.attributes.next).to.deep.equal({
         type: 'function',
         returnsPromise: true,
+        deprecated: false,
         returnType: { type: 'unknown', attributes: {} },
         platforms: ALL_PLATFORMS,
         topologies: ALL_TOPOLOGIES,

packages/shell-api/src/change-stream-cursor.ts

@@ -3,7 +3,8 @@ import {
   returnsPromise,
   returnType,
   hasAsyncChild,
-  ShellApiClass
+  ShellApiClass,
+  deprecated
 } from './decorators';
 import {
   ChangeStream,
@@ -58,6 +59,7 @@ export default class ChangeStreamCursor extends ShellApiClass {
   }
 
   @returnsPromise
+  @deprecated
   async hasNext(): Promise<void> {
     printWarning(
       'If there are no documents in the batch, hasNext will block. Use tryNext if you want to check if there ' +

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

@@ -40,6 +40,7 @@ describe('Collection', () => {
       expect(signatures.Collection.attributes.aggregate).to.deep.equal({
         type: 'function',
         returnsPromise: true,
+        deprecated: false,
         returnType: 'AggregationCursor',
         platforms: ALL_PLATFORMS,
         topologies: ALL_TOPOLOGIES,

packages/shell-api/src/collection.ts

@@ -9,7 +9,8 @@ import {
   serverVersions,
   ShellApiClass,
   shellApiClassDefault,
-  topologies
+  topologies,
+  deprecated
 } from './decorators';
 import { ADMIN_DB, asPrintable, namespaceInfo, ServerVersions, Topologies } from './enums';
 import {
@@ -233,6 +234,7 @@ export default class Collection extends ShellApiClass {
    * @returns {Integer} The promise of the count.
    */
   @returnsPromise
+  @deprecated
   @serverVersions([ServerVersions.earliest, '4.0.0'])
   async count(query = {}, options: CountOptions = {}): Promise<number> {
     this._emitCollectionApiCall(
@@ -592,6 +594,8 @@ export default class Collection extends ShellApiClass {
    * @return {InsertManyResult}
    */
   @returnsPromise
+  @deprecated
+  @serverVersions([ServerVersions.earliest, '3.6.0'])
   async insert(docs: Document | Document[], options: BulkWriteOptions = {}): Promise<InsertManyResult> {
     printDeprecationWarning(
       'Collection.insert() is deprecated. Use insertOne, insertMany or bulkWrite.',
@@ -702,6 +706,7 @@ export default class Collection extends ShellApiClass {
    * @return {Promise}
    */
   @returnsPromise
+  @deprecated
   @serverVersions([ServerVersions.earliest, '3.2.0'])
   async remove(query: Document, options: boolean | RemoveShellOptions = {}): Promise<DeleteResult | Document> {
     printDeprecationWarning(
@@ -730,6 +735,7 @@ export default class Collection extends ShellApiClass {
   }
 
   @returnsPromise
+  @deprecated
   save(): Promise<void> {
     throw new MongoshInvalidInputError('Collection.save() is deprecated. Use insertOne, insertMany, updateOne or updateMany.');
   }
@@ -772,6 +778,7 @@ export default class Collection extends ShellApiClass {
   }
 
   @returnsPromise
+  @deprecated
   @serverVersions([ServerVersions.earliest, '3.2.0'])
   async update(filter: Document, update: Document, options: UpdateOptions & { multi?: boolean } = {}): Promise<UpdateResult | Document> {
     printDeprecationWarning(

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

@@ -28,6 +28,7 @@ describe('Cursor', () => {
       expect(signatures.Cursor.attributes.map).to.deep.equal({
         type: 'function',
         returnsPromise: false,
+        deprecated: false,
         returnType: 'Cursor',
         platforms: ALL_PLATFORMS,
         topologies: ALL_TOPOLOGIES,

packages/shell-api/src/cursor.ts

@@ -6,7 +6,8 @@ import {
   serverVersions,
   ShellApiClass,
   shellApiClassDefault,
-  toShellResult
+  toShellResult,
+  deprecated
 } from './decorators';
 import {
   ServerVersions,
@@ -75,7 +76,6 @@ export default class Cursor extends ShellApiClass {
     if (optionFlagNumber === 4) {
       throw new MongoshUnimplementedError('the slaveOk option is not supported.', CommonErrors.NotImplemented);
     }
-
     const optionFlag: CursorFlag | undefined = (CURSOR_FLAGS as any)[optionFlagNumber];
 
     if (!optionFlag) {
@@ -340,6 +340,7 @@ export default class Cursor extends ShellApiClass {
     return this;
   }
 
+  @deprecated
   @serverVersions([ServerVersions.earliest, '4.0.0'])
   maxScan(): void {
     throw new MongoshDeprecatedError(