feat(NODE-5431): add node bindings v6 deprecations (#666)

Author: baileympearson

README.md

@@ -11,8 +11,8 @@ You can install `mongodb-client-encryption` with the following:
 npm install mongodb-client-encryption
 ```
 
-### Development 
-#### Setup 
+### Development
+#### Setup
 
 Run the following command to build libmongocrypt and setup the node bindings for development:
 
@@ -23,10 +23,10 @@ bash ./etc/build-static.sh
 
 #### Testing
 
-Some tests require a standalone server to be running with authentication enabled.  Set up a single 
+Some tests require a standalone server to be running with authentication enabled.  Set up a single
 server running with the following conditions:
 
-| param     | value     | 
+| param     | value     |
 |-----------|-----------|
 | host      | localhost |
 | port      | 27017     |
@@ -41,28 +41,35 @@ npm test
 
 # Documentation
 
+## Deprecation Notice
+
+There are breaking changes planned for this package.  In the next major version, callbacks will be removed
+from the public API on all asynchronous functions.  Additionally, the classes documented here will be
+moved into [node-mongodb-native](https://github.com/mongodb/node-mongodb-native).
+
 ## Classes
 
 <dl>
 <dt><a href="#AutoEncrypter">AutoEncrypter</a></dt>
 <dd><p>An internal class to be used by the driver for auto encryption
 <strong>NOTE</strong>: Not meant to be instantiated directly, this is for internal use only.</p>
 </dd>
-<dt><a href="#ClientEncryption">ClientEncryption</a></dt>
-<dd><p>The public interface for explicit in-use encryption</p>
-</dd>
-<dt><a href="#MongoCryptError">MongoCryptError</a></dt>
+<dt><del><a href="#ClientEncryption">ClientEncryption</a></del></dt>
+<dd></dd>
+<dt><del><a href="#MongoCryptError">MongoCryptError</a></del></dt>
 <dd><p>An error indicating that something went wrong specifically with MongoDB Client Encryption</p>
 </dd>
-<dt><a href="#MongoCryptCreateDataKeyError">MongoCryptCreateDataKeyError</a></dt>
+<dt><del><a href="#MongoCryptCreateDataKeyError">MongoCryptCreateDataKeyError</a></del></dt>
 <dd><p>An error indicating that <code>ClientEncryption.createEncryptedCollection()</code> failed to create data keys</p>
 </dd>
-<dt><a href="#MongoCryptCreateEncryptedCollectionError">MongoCryptCreateEncryptedCollectionError</a></dt>
+<dt><del><a href="#MongoCryptCreateEncryptedCollectionError">MongoCryptCreateEncryptedCollectionError</a></del></dt>
 <dd><p>An error indicating that <code>ClientEncryption.createEncryptedCollection()</code> failed to create a collection</p>
 </dd>
-<dt><a href="#MongoCryptAzureKMSRequestError">MongoCryptAzureKMSRequestError</a></dt>
+<dt><del><a href="#MongoCryptAzureKMSRequestError">MongoCryptAzureKMSRequestError</a></del></dt>
 <dd><p>An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.</p>
 </dd>
+<dt><del><a href="#MongoCryptKMSRequestNetworkTimeoutError">MongoCryptKMSRequestNetworkTimeoutError</a></del></dt>
+<dd></dd>
 </dl>
 
 ## Typedefs
@@ -100,7 +107,7 @@ npm test
 Can be used for <a href="ClientEncryption.encrypt">ClientEncryption.encrypt</a>, and can be used to directly
 query for the data key itself against the key vault namespace.</p>
 </dd>
-<dt><a href="#ClientEncryptionCreateDataKeyCallback">ClientEncryptionCreateDataKeyCallback</a> : <code>function</code></dt>
+<dt><del><a href="#ClientEncryptionCreateDataKeyCallback">ClientEncryptionCreateDataKeyCallback</a> : <code>function</code></del></dt>
 <dd></dd>
 <dt><a href="#AWSEncryptionKeyOptions">AWSEncryptionKeyOptions</a> : <code>object</code></dt>
 <dd><p>Configuration options for making an AWS encryption key</p>
@@ -113,7 +120,7 @@ query for the data key itself against the key vault namespace.</p>
 </dd>
 <dt><a href="#RewrapManyDataKeyResult">RewrapManyDataKeyResult</a> : <code>object</code></dt>
 <dd></dd>
-<dt><a href="#ClientEncryptionEncryptCallback">ClientEncryptionEncryptCallback</a> : <code>function</code></dt>
+<dt><del><a href="#ClientEncryptionEncryptCallback">ClientEncryptionEncryptCallback</a> : <code>function</code></del></dt>
 <dd></dd>
 <dt><a href="#RangeOptions">RangeOptions</a> : <code>object</code></dt>
 <dd><p>min, max, sparsity, and range must match the values set in the encryptedFields of the destination collection.
@@ -282,12 +289,12 @@ the underlying C++ Bindings.
 
 <a name="ClientEncryption"></a>
 
-## ClientEncryption
-The public interface for explicit in-use encryption
-
+## ~~ClientEncryption~~
+***Deprecated***
 
-* [ClientEncryption](#ClientEncryption)
 
+* ~~[ClientEncryption](#ClientEncryption)
+~~
     * [new ClientEncryption(client, options)](#new_ClientEncryption_new)
 
     * _instance_
@@ -318,8 +325,8 @@ The public interface for explicit in-use encryption
         * [.askForKMSCredentials()](#ClientEncryption+askForKMSCredentials)
 
     * _inner_
-        * [~decryptCallback](#ClientEncryption..decryptCallback)
-
+        * ~~[~decryptCallback](#ClientEncryption..decryptCallback)
+~~
 
 <a name="new_ClientEncryption_new"></a>
 
@@ -369,7 +376,7 @@ new ClientEncryption(mongoClient, {
 | [options] | <code>object</code> | Options for creating the data key |
 | [options.masterKey] | [<code>AWSEncryptionKeyOptions</code>](#AWSEncryptionKeyOptions) \| [<code>AzureEncryptionKeyOptions</code>](#AzureEncryptionKeyOptions) \| [<code>GCPEncryptionKeyOptions</code>](#GCPEncryptionKeyOptions) | Idenfities a new KMS-specific key used to encrypt the new data key |
 | [options.keyAltNames] | <code>Array.&lt;string&gt;</code> | An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by _id. |
-| [callback] | [<code>ClientEncryptionCreateDataKeyCallback</code>](#ClientEncryptionCreateDataKeyCallback) | Optional callback to invoke when key is created |
+| [callback] | [<code>ClientEncryptionCreateDataKeyCallback</code>](#ClientEncryptionCreateDataKeyCallback) | DEPRECATED - Callbacks will be removed in the next major version.  Optional callback to invoke when key is created |
 
 Creates a data key used for explicit encryption and inserts it into the key vault namespace
 
@@ -606,7 +613,7 @@ and then create a new collection with the full set of encryptedFields.
 | --- | --- | --- |
 | value | <code>\*</code> | The value that you wish to serialize. Must be of a type that can be serialized into BSON |
 | options | [<code>EncryptOptions</code>](#EncryptOptions) |  |
-| [callback] | [<code>ClientEncryptionEncryptCallback</code>](#ClientEncryptionEncryptCallback) | Optional callback to invoke when value is encrypted |
+| [callback] | [<code>ClientEncryptionEncryptCallback</code>](#ClientEncryptionEncryptCallback) | DEPRECATED: Callbacks will be removed in the next major version.  Optional callback to invoke when value is encrypted |
 
 Explicitly encrypt a provided value. Note that either `options.keyId` or `options.keyAltName` must
 be specified. Specifying both `options.keyId` and `options.keyAltName` is considered an error.
@@ -662,7 +669,7 @@ Only supported when queryType is "rangePreview" and algorithm is "RangePreview".
 | Param | Type | Description |
 | --- | --- | --- |
 | value | <code>Buffer</code> \| <code>Binary</code> | An encrypted value |
-| callback | [<code>decryptCallback</code>](#ClientEncryption..decryptCallback) | Optional callback to invoke when value is decrypted |
+| callback | [<code>decryptCallback</code>](#ClientEncryption..decryptCallback) | DEPRECATED - Callbacks will be removed in the next major version.  Optional callback to invoke when value is decrypted |
 
 Explicitly decrypt a provided encrypted value
 
@@ -692,7 +699,9 @@ the original ones.
 
 <a name="ClientEncryption..decryptCallback"></a>
 
-### *ClientEncryption*~decryptCallback
+### ~~*ClientEncryption*~decryptCallback~~
+***Deprecated***
+
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -701,22 +710,30 @@ the original ones.
 
 <a name="MongoCryptError"></a>
 
-## MongoCryptError
+## ~~MongoCryptError~~
+***Deprecated***
+
 An error indicating that something went wrong specifically with MongoDB Client Encryption
 
 <a name="MongoCryptCreateDataKeyError"></a>
 
-## MongoCryptCreateDataKeyError
+## ~~MongoCryptCreateDataKeyError~~
+***Deprecated***
+
 An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create data keys
 
 <a name="MongoCryptCreateEncryptedCollectionError"></a>
 
-## MongoCryptCreateEncryptedCollectionError
+## ~~MongoCryptCreateEncryptedCollectionError~~
+***Deprecated***
+
 An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create a collection
 
 <a name="MongoCryptAzureKMSRequestError"></a>
 
-## MongoCryptAzureKMSRequestError
+## ~~MongoCryptAzureKMSRequestError~~
+***Deprecated***
+
 An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.
 
 <a name="new_MongoCryptAzureKMSRequestError_new"></a>
@@ -728,6 +745,11 @@ An error indicating that mongodb-client-encryption failed to auto-refresh Azure
 | message | <code>string</code> | 
 | body | <code>object</code> \| <code>undefined</code> | 
 
+<a name="MongoCryptKMSRequestNetworkTimeoutError"></a>
+
+## ~~MongoCryptKMSRequestNetworkTimeoutError~~
+***Deprecated***
+
 <a name="BSONValue"></a>
 
 ## BSONValue
@@ -821,7 +843,9 @@ query for the data key itself against the key vault namespace.
 
 <a name="ClientEncryptionCreateDataKeyCallback"></a>
 
-## ClientEncryptionCreateDataKeyCallback
+## ~~ClientEncryptionCreateDataKeyCallback~~
+***Deprecated***
+
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -881,7 +905,9 @@ Configuration options for making an Azure encryption key
 
 <a name="ClientEncryptionEncryptCallback"></a>
 
-## ClientEncryptionEncryptCallback
+## ~~ClientEncryptionEncryptCallback~~
+***Deprecated***
+
 
 | Param | Type | Description |
 | --- | --- | --- |

etc/README.hbs

@@ -11,8 +11,8 @@ You can install `mongodb-client-encryption` with the following:
 npm install mongodb-client-encryption
 ```
 
-### Development 
-#### Setup 
+### Development
+#### Setup
 
 Run the following command to build libmongocrypt and setup the node bindings for development:
 
@@ -23,10 +23,10 @@ bash ./etc/build-static.sh
 
 #### Testing
 
-Some tests require a standalone server to be running with authentication enabled.  Set up a single 
+Some tests require a standalone server to be running with authentication enabled.  Set up a single
 server running with the following conditions:
 
-| param     | value     | 
+| param     | value     |
 |-----------|-----------|
 | host      | localhost |
 | port      | 27017     |
@@ -41,4 +41,10 @@ npm test
 
 # Documentation
 
+## Deprecation Notice
+
+There are breaking changes planned for this package.  In the next major version, callbacks will be removed
+from the public API on all asynchronous functions.  Additionally, the classes documented here will be
+moved into [node-mongodb-native](https://github.com/mongodb/node-mongodb-native).
+
 {{>main}}

index.d.ts

@@ -28,13 +28,19 @@ export interface DataKey {
 }
 
 /**
+ * @deprecated This class will be moved into the [Node driver](https://github.com/mongodb/node-mongodb-native)
+ * in the next major version and must be imported from the driver.
+ *
  * An error indicating that something went wrong specifically with MongoDB Client Encryption
  */
 export class MongoCryptError extends Error {
   cause?: Error;
 }
 
 /**
+ * @deprecated This class will be moved into the [Node driver](https://github.com/mongodb/node-mongodb-native)
+ * in the next major version and must be imported from the driver.
+ *
  * An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create a collection
  */
 export class MongoCryptCreateEncryptedCollectionError extends MongoCryptError {
@@ -47,6 +53,9 @@ export class MongoCryptCreateEncryptedCollectionError extends MongoCryptError {
 }
 
 /**
+ * @deprecated This class will be moved into the [Node driver](https://github.com/mongodb/node-mongodb-native)
+ * in the next major version and must be imported from the driver.
+ *
  * An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create data keys
  */
 export class MongoCryptCreateDataKeyError extends MongoCryptError {
@@ -59,13 +68,21 @@ export class MongoCryptCreateDataKeyError extends MongoCryptError {
 }
 
 /**
+ * @deprecated This class will be moved into the [Node driver](https://github.com/mongodb/node-mongodb-native)
+ * in the next major version and must be imported from the driver.
+ *
  * An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.
  */
 export class MongoCryptAzureKMSRequestError extends MongoCryptError {
   /* The body of the IMDS request that produced the error, if present. */
   body?: Document ;
 }
 
+/**
+ * @deprecated This class will be moved into the [Node driver](https://github.com/mongodb/node-mongodb-native)
+ * in the next major version and must be imported from the driver.
+ *
+ */
 export class MongoCryptKMSRequestNetworkTimeoutError extends MongoCryptError {}
 
 /**
@@ -78,6 +95,10 @@ export interface ProxyOptions {
   proxyPassword?: string;
 }
 
+/**
+ * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+ * use the Promise overloads instead.
+ */
 export interface ClientEncryptionCreateDataKeyCallback {
   /**
    * @param error If present, indicates an error that occurred in the creation of the data key
@@ -86,6 +107,10 @@ export interface ClientEncryptionCreateDataKeyCallback {
   (error?: Error, dataKeyId?: Binary): void;
 }
 
+/**
+ * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+ * use the Promise overloads instead.
+ */
 export interface ClientEncryptionEncryptCallback {
   /**
    * @param error If present, indicates an error that occurred in the process of encryption
@@ -94,6 +119,10 @@ export interface ClientEncryptionEncryptCallback {
   (error?: Error, result?: Binary): void;
 }
 
+/**
+ * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+ * use the Promise overloads instead.
+ */
 export interface ClientEncryptionDecryptCallback {
   /**
    * @param error If present, indicates an error that occurred in the process of decryption
@@ -479,6 +508,9 @@ export class ClientEncryption {
   ): Promise<Binary>;
 
   /**
+   * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+   * use the Promise overloads instead.
+   *
    * Creates a data key used for explicit encryption and inserts it into the key vault namespace
    * @param provider The KMS provider used for this data key. Must be `'aws'`, `'azure'`, `'gcp'`, or `'local'`
    * @param callback Callback to invoke when key is created
@@ -489,6 +521,9 @@ export class ClientEncryption {
   ): void;
 
   /**
+   * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+   * use the Promise overloads instead.
+   *
    * Creates a data key used for explicit encryption and inserts it into the key vault namespace
    * @param provider The KMS provider used for this data key. Must be `'aws'`, `'azure'`, `'gcp'`, or `'local'`
    * @param options Options for creating the data key
@@ -593,6 +628,9 @@ export class ClientEncryption {
   encrypt(value: any, options: ClientEncryptionEncryptOptions): Promise<Binary>;
 
   /**
+   * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+   * use the Promise overloads instead.
+   *
    * Explicitly encrypt a provided value.
    * Note that either options.keyId or options.keyAltName must be specified.
    * Specifying both options.keyId and options.keyAltName is considered an error.
@@ -630,6 +668,9 @@ export class ClientEncryption {
   decrypt(value: Buffer | Binary): Promise<any>;
 
   /**
+   * @deprecated Callback overloads are deprecated and will be removed in the next major version.  Please
+   * use the Promise overloads instead.
+   *
    * Explicitly decrypt a provided encrypted value
    * @param value An encrypted value
    * @param callback Callback to invoke when value is decrypted