feat(NODE-4519): deprecate promiseLibrary and PromiseProvider (#3403)

Author: nbbeeken

src/index.ts

@@ -97,11 +97,12 @@ export {
   Logger,
   MongoClient,
   OrderedBulkOperation,
-  // Utils
-  PromiseProvider as Promise,
   UnorderedBulkOperation
 };
 
+// Deprecated, remove in next major
+export { PromiseProvider as Promise };
+
 // enums
 export { BatchType } from './bulk/common';
 export { GSSAPICanonicalizationValue } from './cmap/auth/gssapi';

src/mongo_client.ts

@@ -230,7 +230,10 @@ export interface MongoClientOptions extends BSONSerializeOptions, SupportedNodeC
   raw?: boolean;
   /** A primary key factory function for generation of custom `_id` keys */
   pkFactory?: PkFactory;
-  /** A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible */
+  /**
+   * A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
+   * @deprecated Setting a custom promise library is deprecated the next major version will use the global Promise constructor only.
+   */
   promiseLibrary?: any;
   /** The logging level */
   loggerLevel?: LoggerLevel;

src/promise_provider.ts

@@ -13,17 +13,24 @@ const store: PromiseStore = {
 
 /**
  * Global promise store allowing user-provided promises
+ * @deprecated Setting a custom promise library is deprecated the next major version will use the global Promise constructor only.
  * @public
  */
 export class PromiseProvider {
-  /** Validates the passed in promise library */
+  /**
+   * Validates the passed in promise library
+   * @deprecated Setting a custom promise library is deprecated the next major version will use the global Promise constructor only.
+   */
   static validate(lib: unknown): lib is PromiseConstructor {
     if (typeof lib !== 'function')
       throw new MongoInvalidArgumentError(`Promise must be a function, got ${lib}`);
     return !!lib;
   }
 
-  /** Sets the promise library */
+  /**
+   * Sets the promise library
+   * @deprecated Setting a custom promise library is deprecated the next major version will use the global Promise constructor only.
+   */
   static set(lib: PromiseConstructor): void {
     if (!PromiseProvider.validate(lib)) {
       // validate
@@ -32,7 +39,10 @@ export class PromiseProvider {
     store[kPromise] = lib;
   }
 
-  /** Get the stored promise library, or resolves passed in */
+  /**
+   * Get the stored promise library, or resolves passed in
+   * @deprecated Setting a custom promise library is deprecated the next major version will use the global Promise constructor only.
+   */
   static get(): PromiseConstructor {
     return store[kPromise] as PromiseConstructor;
   }

test/integration/node-specific/custom_promise_library.test.js

@@ -1,7 +1,9 @@
 'use strict';
 
+const { once } = require('events');
 const { expect } = require('chai');
 const { PromiseProvider } = require('../../../src/promise_provider');
+const { MongoClient } = require('../../../src/mongo_client');
 
 class CustomPromise extends Promise {}
 CustomPromise.prototype.isCustomMongo = true;
@@ -11,6 +13,13 @@ describe('Optional PromiseLibrary', function () {
     PromiseProvider.set(Promise);
   });
 
+  it('should emit a deprecation warning when a promiseLibrary is set', async () => {
+    const willEmitWarning = once(process, 'warning');
+    new MongoClient('mongodb://iLoveJavascript', { promiseLibrary: () => {} });
+    const [warning] = await willEmitWarning;
+    expect(warning).to.have.property('message', 'promiseLibrary is a deprecated option');
+  });
+
   it('should correctly implement custom dependency-less promise', function (done) {
     const getCustomPromise = v => new CustomPromise(resolve => resolve(v));
     const getNativePromise = v => new Promise(resolve => resolve(v));

test/types/mongodb.test-d.ts

@@ -23,10 +23,20 @@ expectDeprecated(Db.prototype.unref);
 expectDeprecated(MongoDBDriver.ObjectID);
 expectNotDeprecated(MongoDBDriver.ObjectId);
 
+// We cannot attach a deprecation tag to an export
+// We tried export const Promise = PromiseProvider;
+// but then api-extractor claims PromiseProvider is not exported
+// Instead we've deprecated all the methods on the class
+expectNotDeprecated(MongoDBDriver.Promise);
+expectDeprecated(MongoDBDriver.Promise.validate);
+expectDeprecated(MongoDBDriver.Promise.get);
+expectDeprecated(MongoDBDriver.Promise.set);
+
 declare const options: MongoDBDriver.MongoClientOptions;
 expectDeprecated(options.w);
 expectDeprecated(options.journal);
 expectDeprecated(options.wtimeoutMS);
+expectDeprecated(options.promiseLibrary);
 expectNotDeprecated(options.writeConcern);
 expectType<WriteConcernSettings | WriteConcern | undefined>(options.writeConcern);