mongodb 4.0.0 → 4.1.2

package/src/cursor/find_cursor.ts

@@ -1,5 +1,5 @@
 import type { Document } from '../bson';
-import { MongoDriverError } from '../error';
+import { MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
 import type { ExplainVerbosityLike } from '../explain';
 import { CountOperation, CountOptions } from '../operations/count';
 import { executeOperation, ExecutionResult } from '../operations/execute_operation';
@@ -12,7 +12,6 @@ import type { ClientSession } from '../sessions';
 import { formatSort, Sort, SortDirection } from '../sort';
 import type { Callback, MongoDBNamespace } from '../utils';
 import { AbstractCursor, assertUninitialized } from './abstract_cursor';
-import type { Projection } from '../mongo_types';
 
 /** @internal */
 const kFilter = Symbol('filter');
@@ -52,7 +51,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
     this[kFilter] = filter || {};
     this[kBuiltOptions] = options;
 
-    if (typeof options.sort !== 'undefined') {
+    if (options.sort != null) {
       this[kBuiltOptions].sort = formatSort(options.sort);
     }
   }
@@ -129,7 +128,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
     callback?: Callback<number>
   ): Promise<number> | void {
     if (typeof options === 'boolean') {
-      throw new MongoDriverError('Invalid first parameter to count');
+      throw new MongoInvalidArgumentError('Invalid first parameter to count');
     }
 
     if (typeof options === 'function') (callback = options), (options = {});
@@ -155,7 +154,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
     callback?: Callback<Document>
   ): Promise<Document> | void {
     if (typeof verbosity === 'function') (callback = verbosity), (verbosity = true);
-    if (verbosity === undefined) verbosity = true;
+    if (verbosity == null) verbosity = true;
 
     return executeOperation(
       this.topology,
@@ -241,7 +240,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   addQueryModifier(name: string, value: string | boolean | number | Document): this {
     assertUninitialized(this);
     if (name[0] !== '$') {
-      throw new MongoDriverError(`${name} is not a valid query modifier`);
+      throw new MongoInvalidArgumentError(`${name} is not a valid query modifier`);
     }
 
     // Strip of the $
@@ -290,7 +289,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
         break;
 
       default:
-        throw new MongoDriverError(`invalid query modifier: ${name}`);
+        throw new MongoInvalidArgumentError(`Invalid query modifier: ${name}`);
     }
 
     return this;
@@ -315,7 +314,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   maxAwaitTimeMS(value: number): this {
     assertUninitialized(this);
     if (typeof value !== 'number') {
-      throw new MongoDriverError('maxAwaitTimeMS must be a number');
+      throw new MongoInvalidArgumentError('Argument for maxAwaitTimeMS must be a number');
     }
 
     this[kBuiltOptions].maxAwaitTimeMS = value;
@@ -330,7 +329,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   maxTimeMS(value: number): this {
     assertUninitialized(this);
     if (typeof value !== 'number') {
-      throw new MongoDriverError('maxTimeMS must be a number');
+      throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');
     }
 
     this[kBuiltOptions].maxTimeMS = value;
@@ -344,22 +343,43 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
    * In order to strictly type this function you must provide an interface
    * that represents the effect of your projection on the result documents.
    *
-   * **NOTE:** adding a projection changes the return type of the iteration of this cursor,
+   * By default chaining a projection to your cursor changes the returned type to the generic
+   * {@link Document} type.
+   * You should specify a parameterized type to have assertions on your final results.
+   *
+   * @example
+   * ```typescript
+   * // Best way
+   * const docs: FindCursor<{ a: number }> = cursor.project<{ a: number }>({ _id: 0, a: true });
+   * // Flexible way
+   * const docs: FindCursor<Document> = cursor.project({ _id: 0, a: true });
+   * ```
+   *
+   * @remarks
+   *
+   * **Note for Typescript Users:** adding a transform changes the return type of the iteration of this cursor,
    * it **does not** return a new instance of a cursor. This means when calling project,
-   * you should always assign the result to a new variable. Take note of the following example:
+   * you should always assign the result to a new variable in order to get a correctly typed cursor variable.
+   * Take note of the following example:
    *
    * @example
    * ```typescript
    * const cursor: FindCursor<{ a: number; b: string }> = coll.find();
-   * const projectCursor = cursor.project<{ a: number }>({ a: true });
+   * const projectCursor = cursor.project<{ a: number }>({ _id: 0, a: true });
    * const aPropOnlyArray: {a: number}[] = await projectCursor.toArray();
+   *
+   * // or always use chaining and save the final cursor
+   *
+   * const cursor = coll.find().project<{ a: string }>({
+   *   _id: 0,
+   *   a: { $convert: { input: '$a', to: 'string' }
+   * }});
    * ```
    */
-  project<T = TSchema>(value: Projection<T>): FindCursor<T>;
-  project(value: Projection<TSchema>): this {
+  project<T extends Document = Document>(value: Document): FindCursor<T> {
     assertUninitialized(this);
     this[kBuiltOptions].projection = value;
-    return this;
+    return this as unknown as FindCursor<T>;
   }
 
   /**
@@ -371,7 +391,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   sort(sort: Sort | string, direction?: SortDirection): this {
     assertUninitialized(this);
     if (this[kBuiltOptions].tailable) {
-      throw new MongoDriverError('Tailable cursor does not support sorting');
+      throw new MongoTailableCursorError('Tailable cursor does not support sorting');
     }
 
     this[kBuiltOptions].sort = formatSort(sort, direction);
@@ -387,7 +407,7 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   allowDiskUse(): this {
     assertUninitialized(this);
     if (!this[kBuiltOptions].sort) {
-      throw new MongoDriverError('allowDiskUse requires a sort specification');
+      throw new MongoInvalidArgumentError('Option "allowDiskUse" requires a sort specification');
     }
     this[kBuiltOptions].allowDiskUse = true;
     return this;
@@ -412,11 +432,11 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   limit(value: number): this {
     assertUninitialized(this);
     if (this[kBuiltOptions].tailable) {
-      throw new MongoDriverError('Tailable cursor does not support limit');
+      throw new MongoTailableCursorError('Tailable cursor does not support limit');
     }
 
     if (typeof value !== 'number') {
-      throw new MongoDriverError('limit requires an integer');
+      throw new MongoInvalidArgumentError('Operation "limit" requires an integer');
     }
 
     this[kBuiltOptions].limit = value;
@@ -431,11 +451,11 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   skip(value: number): this {
     assertUninitialized(this);
     if (this[kBuiltOptions].tailable) {
-      throw new MongoDriverError('Tailable cursor does not support skip');
+      throw new MongoTailableCursorError('Tailable cursor does not support skip');
     }
 
     if (typeof value !== 'number') {
-      throw new MongoDriverError('skip requires an integer');
+      throw new MongoInvalidArgumentError('Operation "skip" requires an integer');
     }
 
     this[kBuiltOptions].skip = value;

package/src/db.ts

@@ -9,7 +9,7 @@ import {
 import { AggregationCursor } from './cursor/aggregation_cursor';
 import { Document, BSONSerializeOptions, resolveBSONOptions } from './bson';
 import { ReadPreference, ReadPreferenceLike } from './read_preference';
-import { MongoDriverError } from './error';
+import { MongoAPIError, MongoInvalidArgumentError } from './error';
 import { Collection, CollectionOptions } from './collection';
 import { ChangeStream, ChangeStreamOptions } from './change_stream';
 import * as CONSTANTS from './constants';
@@ -289,19 +289,21 @@ export class Db {
    * @param pipeline - An array of aggregation stages to be executed
    * @param options - Optional settings for the command
    */
-  aggregate(pipeline: Document[] = [], options?: AggregateOptions): AggregationCursor {
+  aggregate<T = Document>(
+    pipeline: Document[] = [],
+    options?: AggregateOptions
+  ): AggregationCursor<T> {
     if (arguments.length > 2) {
-      throw new MongoDriverError('Third parameter to `db.aggregate()` must be undefined');
+      throw new MongoInvalidArgumentError('Method "db.aggregate()" accepts at most two arguments');
     }
     if (typeof pipeline === 'function') {
-      throw new MongoDriverError('`pipeline` parameter must not be function');
+      throw new MongoInvalidArgumentError('Argument "pipeline" must not be function');
     }
     if (typeof options === 'function') {
-      throw new MongoDriverError('`options` parameter must not be function');
+      throw new MongoInvalidArgumentError('Argument "options" must not be function');
     }
 
     return new AggregationCursor(
-      this,
       getTopology(this),
       this.s.namespace,
       pipeline,
@@ -320,15 +322,12 @@ export class Db {
    * @param name - the collection name we wish to access.
    * @returns return the new Collection instance
    */
-  collection<TSchema extends Document = Document>(name: string): Collection<TSchema>;
   collection<TSchema extends Document = Document>(
     name: string,
-    options?: CollectionOptions
+    options: CollectionOptions = {}
   ): Collection<TSchema> {
-    if (!options) {
-      options = {};
-    } else if (typeof options === 'function') {
-      throw new MongoDriverError('The callback form of this helper has been removed.');
+    if (typeof options === 'function') {
+      throw new MongoInvalidArgumentError('The callback form of this helper has been removed.');
     }
     const finalOptions = resolveOptions(this, options);
     return new Collection<TSchema>(this, name, finalOptions);
@@ -701,7 +700,10 @@ export class Db {
     );
   }
 
-  /** Unref all sockets */
+  /**
+   * Unref all sockets
+   * @deprecated This function is deprecated and will be removed in the next major version.
+   */
   unref(): void {
     getTopology(this).unref();
   }
@@ -737,19 +739,18 @@ export class Db {
   }
 }
 
+// TODO(NODE-3484): Refactor into MongoDBNamespace
 // Validate the database name
 function validateDatabaseName(databaseName: string) {
   if (typeof databaseName !== 'string')
-    throw new MongoDriverError('database name must be a string');
+    throw new MongoInvalidArgumentError('Database name must be a string');
   if (databaseName.length === 0)
-    throw new MongoDriverError('database name cannot be the empty string');
+    throw new MongoInvalidArgumentError('Database name cannot be the empty string');
   if (databaseName === '$external') return;
 
   const invalidChars = [' ', '.', '$', '/', '\\'];
   for (let i = 0; i < invalidChars.length; i++) {
     if (databaseName.indexOf(invalidChars[i]) !== -1)
-      throw new MongoDriverError(
-        `database names cannot contain the character '${invalidChars[i]}'`
-      );
+      throw new MongoAPIError(`database names cannot contain the character '${invalidChars[i]}'`);
   }
 }

package/src/deps.ts

@@ -1,7 +1,10 @@
-import { MongoDriverError } from './error';
+/* eslint-disable @typescript-eslint/no-var-requires */
+import { MongoMissingDependencyError } from './error';
 import type { MongoClient } from './mongo_client';
 import type { deserialize, Document, serialize } from './bson';
-import type { Callback } from './utils';
+import { Callback, parsePackageVersion } from './utils';
+
+export const PKG_VERSION = Symbol('kPkgVersion');
 
 function makeErrorModule(error: any) {
   const props = error ? { kModuleError: error } : {};
@@ -18,15 +21,15 @@ function makeErrorModule(error: any) {
   });
 }
 
-export let Kerberos:
-  | typeof import('kerberos')
-  | { kModuleError: MongoDriverError } = makeErrorModule(
-  new MongoDriverError(
-    'Optional module `kerberos` not found. Please install it to enable kerberos authentication'
-  )
-);
+export let Kerberos: typeof import('kerberos') | { kModuleError: MongoMissingDependencyError } =
+  makeErrorModule(
+    new MongoMissingDependencyError(
+      'Optional module `kerberos` not found. Please install it to enable kerberos authentication'
+    )
+  );
 
 try {
+  // Ensure you always wrap an optional require in the try block NODE-3199
   Kerberos = require('kerberos');
 } catch {} // eslint-disable-line
 
@@ -40,36 +43,120 @@ export interface KerberosClient {
   unwrap: (challenge: string, callback?: Callback<string>) => Promise<string> | void;
 }
 
-export let Snappy: typeof import('snappy') | { kModuleError: MongoDriverError } = makeErrorModule(
-  new MongoDriverError(
+type SnappyLib = {
+  [PKG_VERSION]: { major: number; minor: number; patch: number };
+
+  /**
+   * - Snappy 6.x takes a callback and returns void
+   * - Snappy 7.x returns a promise
+   *
+   * In order to support both we must check the return value of the function
+   * @param buf - Buffer to be compressed
+   * @param callback - ONLY USED IN SNAPPY 6.x
+   */
+  compress(buf: Buffer): Promise<Buffer>;
+  compress(buf: Buffer, callback: (error?: Error, buffer?: Buffer) => void): Promise<Buffer> | void;
+  compress(
+    buf: Buffer,
+    callback?: (error?: Error, buffer?: Buffer) => void
+  ): Promise<Buffer> | void;
+
+  /**
+   * - Snappy 6.x takes a callback and returns void
+   * - Snappy 7.x returns a promise
+   *
+   * In order to support both we must check the return value of the function
+   * @param buf - Buffer to be compressed
+   * @param callback - ONLY USED IN SNAPPY 6.x
+   */
+  uncompress(buf: Buffer, opt: { asBuffer: true }): Promise<Buffer>;
+  uncompress(
+    buf: Buffer,
+    opt: { asBuffer: true },
+    callback: (error?: Error, buffer?: Buffer) => void
+  ): Promise<Buffer> | void;
+  uncompress(
+    buf: Buffer,
+    opt: { asBuffer: true },
+    callback?: (error?: Error, buffer?: Buffer) => void
+  ): Promise<Buffer> | void;
+};
+
+export let Snappy: SnappyLib | { kModuleError: MongoMissingDependencyError } = makeErrorModule(
+  new MongoMissingDependencyError(
     'Optional module `snappy` not found. Please install it to enable snappy compression'
   )
 );
 
 try {
+  // Ensure you always wrap an optional require in the try block NODE-3199
   Snappy = require('snappy');
+  try {
+    (Snappy as any)[PKG_VERSION] = parsePackageVersion(require('snappy/package.json'));
+  } catch {} // eslint-disable-line
 } catch {} // eslint-disable-line
 
-export let saslprep:
-  | typeof import('saslprep')
-  | { kModuleError: MongoDriverError } = makeErrorModule(
-  new MongoDriverError(
-    'Optional module `saslprep` not found.' +
-      ' Please install it to enable Stringprep Profile for User Names and Passwords'
-  )
-);
+export let saslprep: typeof import('saslprep') | { kModuleError: MongoMissingDependencyError } =
+  makeErrorModule(
+    new MongoMissingDependencyError(
+      'Optional module `saslprep` not found.' +
+        ' Please install it to enable Stringprep Profile for User Names and Passwords'
+    )
+  );
 
 try {
+  // Ensure you always wrap an optional require in the try block NODE-3199
   saslprep = require('saslprep');
 } catch {} // eslint-disable-line
 
-export let aws4: typeof import('aws4') | { kModuleError: MongoDriverError } = makeErrorModule(
-  new MongoDriverError(
+interface AWS4 {
+  /**
+   * Created these inline types to better assert future usage of this API
+   * @param options - options for request
+   * @param credentials - AWS credential details, sessionToken should be omitted entirely if its false-y
+   */
+  sign(
+    options: {
+      path: '/';
+      body: string;
+      host: string;
+      method: 'POST';
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded';
+        'Content-Length': number;
+        'X-MongoDB-Server-Nonce': string;
+        'X-MongoDB-GS2-CB-Flag': 'n';
+      };
+      service: string;
+      region: string;
+    },
+    credentials:
+      | {
+          accessKeyId: string;
+          secretAccessKey: string;
+          sessionToken: string;
+        }
+      | {
+          accessKeyId: string;
+          secretAccessKey: string;
+        }
+      | undefined
+  ): {
+    headers: {
+      Authorization: string;
+      'X-Amz-Date': string;
+    };
+  };
+}
+
+export let aws4: AWS4 | { kModuleError: MongoMissingDependencyError } = makeErrorModule(
+  new MongoMissingDependencyError(
     'Optional module `aws4` not found. Please install it to enable AWS authentication'
   )
 );
 
 try {
+  // Ensure you always wrap an optional require in the try block NODE-3199
   aws4 = require('aws4');
 } catch {} // eslint-disable-line
 
@@ -83,7 +170,8 @@ export const AutoEncryptionLoggerLevel = Object.freeze({
 } as const);
 
 /** @public */
-export type AutoEncryptionLoggerLevel = typeof AutoEncryptionLoggerLevel[keyof typeof AutoEncryptionLoggerLevel];
+export type AutoEncryptionLoggerLevel =
+  typeof AutoEncryptionLoggerLevel[keyof typeof AutoEncryptionLoggerLevel];
 
 /** @public */
 export interface AutoEncryptionOptions {

package/src/encrypter.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 import { MongoClient, MongoClientOptions } from './mongo_client';
 import type { AutoEncrypter, AutoEncryptionOptions } from './deps';
-import { MongoDriverError } from './error';
+import { MongoInvalidArgumentError, MongoMissingDependencyError } from './error';
 import { deserialize, serialize } from './bson';
 import type { Callback } from './utils';
 import { MONGO_CLIENT_EVENTS } from './operations/connect';
@@ -26,7 +26,7 @@ export class Encrypter {
 
   constructor(client: MongoClient, uri: string, options: MongoClientOptions) {
     if (typeof options.autoEncryption !== 'object') {
-      throw new MongoDriverError('Options autoEncryption must be specified');
+      throw new MongoInvalidArgumentError('Option "autoEncryption" must be specified');
     }
 
     this.bypassAutoEncryption = !!options.autoEncryption.bypassAutoEncryption;
@@ -103,23 +103,17 @@ export class Encrypter {
   }
 
   static checkForMongoCrypt(): void {
+    let mongodbClientEncryption = undefined;
     try {
-      require.resolve('mongodb-client-encryption');
+      // Ensure you always wrap an optional require in the try block NODE-3199
+      mongodbClientEncryption = require('mongodb-client-encryption');
     } catch (err) {
-      throw new MongoDriverError(
+      throw new MongoMissingDependencyError(
         'Auto-encryption requested, but the module is not installed. ' +
           'Please add `mongodb-client-encryption` as a dependency of your project'
       );
     }
 
-    const mongodbClientEncryption = require('mongodb-client-encryption');
-    if (typeof mongodbClientEncryption.extension !== 'function') {
-      throw new MongoDriverError(
-        'loaded version of `mongodb-client-encryption` does not have property `extension`. ' +
-          'Please make sure you are loading the correct version of `mongodb-client-encryption`'
-      );
-    }
-
     AutoEncrypterClass = mongodbClientEncryption.extension(require('../lib/index')).AutoEncrypter;
   }
 }