mongodb 4.1.0 → 4.1.4

package/src/collection.ts

@@ -40,7 +40,6 @@ import {
   EstimatedDocumentCountOptions
 } from './operations/estimated_document_count';
 import type { FindOptions } from './operations/find';
-import { FindOneOperation } from './operations/find_one';
 import {
   FindOneAndDeleteOperation,
   FindOneAndReplaceOperation,
@@ -100,7 +99,7 @@ import type {
 
 /** @public */
 export interface ModifyResult<TSchema = Document> {
-  value?: TSchema;
+  value: TSchema | null;
   lastErrorObject?: Document;
   ok: 0 | 1;
 }
@@ -415,34 +414,39 @@ export class Collection<TSchema extends Document = Document> {
   updateOne(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Partial<TSchema>
-  ): Promise<UpdateResult | Document>;
+  ): Promise<UpdateResult>;
   updateOne(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Partial<TSchema>,
-    callback: Callback<UpdateResult | Document>
+    callback: Callback<UpdateResult>
   ): void;
   updateOne(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Partial<TSchema>,
     options: UpdateOptions
-  ): Promise<UpdateResult | Document>;
+  ): Promise<UpdateResult>;
   updateOne(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Partial<TSchema>,
     options: UpdateOptions,
-    callback: Callback<UpdateResult | Document>
+    callback: Callback<UpdateResult>
   ): void;
   updateOne(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Partial<TSchema>,
-    options?: UpdateOptions | Callback<UpdateResult | Document>,
-    callback?: Callback<UpdateResult | Document>
-  ): Promise<UpdateResult | Document> | void {
+    options?: UpdateOptions | Callback<UpdateResult>,
+    callback?: Callback<UpdateResult>
+  ): Promise<UpdateResult> | void {
     if (typeof options === 'function') (callback = options), (options = {});
 
     return executeOperation(
       getTopology(this),
-      new UpdateOneOperation(this as TODO_NODE_3286, filter, update, resolveOptions(this, options)),
+      new UpdateOneOperation(
+        this as TODO_NODE_3286,
+        filter,
+        update,
+        resolveOptions(this, options)
+      ) as TODO_NODE_3286,
       callback
     );
   }
@@ -672,54 +676,48 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  findOne(): Promise<TSchema | undefined>;
-  findOne(callback: Callback<TSchema | undefined>): void;
-  findOne(filter: Filter<TSchema>): Promise<TSchema | undefined>;
-  findOne(filter: Filter<TSchema>, callback: Callback<TSchema | undefined>): void;
-  findOne(filter: Filter<TSchema>, options: FindOptions<TSchema>): Promise<TSchema | undefined>;
-  findOne(
-    filter: Filter<TSchema>,
-    options: FindOptions<TSchema>,
-    callback: Callback<TSchema | undefined>
-  ): void;
+  findOne(): Promise<TSchema | null>;
+  findOne(callback: Callback<TSchema | null>): void;
+  findOne(filter: Filter<TSchema>): Promise<TSchema | null>;
+  findOne(filter: Filter<TSchema>, callback: Callback<TSchema | null>): void;
+  findOne(filter: Filter<TSchema>, options: FindOptions): Promise<TSchema | null>;
+  findOne(filter: Filter<TSchema>, options: FindOptions, callback: Callback<TSchema | null>): void;
 
   // allow an override of the schema.
-  findOne<T = TSchema>(): Promise<T | undefined>;
-  findOne<T = TSchema>(callback: Callback<T | undefined>): void;
-  findOne<T = TSchema>(filter: Filter<T>): Promise<T | undefined>;
-  findOne<T = TSchema>(filter: Filter<T>, options?: FindOptions<T>): Promise<T | undefined>;
+  findOne<T = TSchema>(): Promise<T | null>;
+  findOne<T = TSchema>(callback: Callback<T | null>): void;
+  findOne<T = TSchema>(filter: Filter<TSchema>): Promise<T | null>;
+  findOne<T = TSchema>(filter: Filter<TSchema>, options?: FindOptions): Promise<T | null>;
   findOne<T = TSchema>(
-    filter: Filter<T>,
-    options?: FindOptions<T>,
-    callback?: Callback<T | undefined>
+    filter: Filter<TSchema>,
+    options?: FindOptions,
+    callback?: Callback<T | null>
   ): void;
 
   findOne(
-    filter?: Filter<TSchema> | Callback<TSchema | undefined>,
-    options?: FindOptions<TSchema> | Callback<TSchema | undefined>,
-    callback?: Callback<TSchema>
-  ): Promise<TSchema | undefined> | void {
+    filter?: Filter<TSchema> | Callback<TSchema | null>,
+    options?: FindOptions | Callback<TSchema | null>,
+    callback?: Callback<TSchema | null>
+  ): Promise<TSchema | null> | void {
     if (callback != null && typeof callback !== 'function') {
       throw new MongoInvalidArgumentError(
         'Third parameter to `findOne()` must be a callback or undefined'
       );
     }
 
-    if (typeof filter === 'function')
-      (callback = filter as Callback<Document | undefined>), (filter = {}), (options = {});
-    if (typeof options === 'function') (callback = options), (options = {});
-
-    filter ??= {};
+    if (typeof filter === 'function') {
+      callback = filter as Callback<TSchema | null>;
+      filter = {};
+      options = {};
+    }
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    }
 
-    return executeOperation(
-      getTopology(this),
-      new FindOneOperation(
-        this as TODO_NODE_3286,
-        filter,
-        resolveOptions(this, options)
-      ) as TODO_NODE_3286,
-      callback as TODO_NODE_3286
-    );
+    const finalFilter = filter ?? {};
+    const finalOptions = options ?? {};
+    return this.find(finalFilter, finalOptions).limit(-1).batchSize(1).next(callback);
   }
 
   /**
@@ -728,9 +726,9 @@ export class Collection<TSchema extends Document = Document> {
    * @param filter - The filter predicate. If unspecified, then all documents in the collection will match the predicate
    */
   find(): FindCursor<TSchema>;
-  find(filter: Filter<TSchema>, options?: FindOptions<TSchema>): FindCursor<TSchema>;
-  find<T = TSchema>(filter: Filter<T>, options?: FindOptions<T>): FindCursor<T>;
-  find(filter?: Filter<TSchema>, options?: FindOptions<TSchema>): FindCursor<TSchema> {
+  find(filter: Filter<TSchema>, options?: FindOptions): FindCursor<TSchema>;
+  find<T>(filter: Filter<TSchema>, options?: FindOptions): FindCursor<T>;
+  find(filter?: Filter<TSchema>, options?: FindOptions): FindCursor<TSchema> {
     if (arguments.length > 2) {
       throw new MongoInvalidArgumentError(
         'Method "collection.find()" accepts at most two arguments'
@@ -1192,14 +1190,14 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    * @param callback - An optional callback, a Promise will be returned if none is provided
    */
-  indexes(): Promise<Document>;
-  indexes(callback: Callback<Document>): void;
-  indexes(options: IndexInformationOptions): Promise<Document>;
-  indexes(options: IndexInformationOptions, callback: Callback<Document>): void;
+  indexes(): Promise<Document[]>;
+  indexes(callback: Callback<Document[]>): void;
+  indexes(options: IndexInformationOptions): Promise<Document[]>;
+  indexes(options: IndexInformationOptions, callback: Callback<Document[]>): void;
   indexes(
-    options?: IndexInformationOptions | Callback<Document>,
-    callback?: Callback<Document>
-  ): Promise<Document> | void {
+    options?: IndexInformationOptions | Callback<Document[]>,
+    callback?: Callback<Document[]>
+  ): Promise<Document[]> | void {
     if (typeof options === 'function') (callback = options), (options = {});
 
     return executeOperation(
@@ -1368,7 +1366,7 @@ export class Collection<TSchema extends Document = Document> {
    * @param pipeline - An array of aggregation pipelines to execute
    * @param options - Optional settings for the command
    */
-  aggregate<T = TSchema>(
+  aggregate<T = Document>(
     pipeline: Document[] = [],
     options?: AggregateOptions
   ): AggregationCursor<T> {

package/src/connection_string.ts

@@ -6,7 +6,7 @@ import { AuthMechanism } from './cmap/auth/defaultAuthProviders';
 import { ReadPreference, ReadPreferenceMode } from './read_preference';
 import { ReadConcern, ReadConcernLevel } from './read_concern';
 import { W, WriteConcern } from './write_concern';
-import { MongoParseError } from './error';
+import { MongoAPIError, MongoInvalidArgumentError, MongoParseError } from './error';
 import {
   AnyOptions,
   Callback,
@@ -32,6 +32,7 @@ import type { TagSet } from './sdam/server_description';
 import { Logger, LoggerLevel } from './logger';
 import { PromiseProvider } from './promise_provider';
 import { Encrypter } from './encrypter';
+import { Compressor, CompressorName } from './cmap/wire_protocol/compression';
 
 const VALID_TXT_RECORDS = ['authSource', 'replicaSet', 'loadBalanced'];
 
@@ -64,11 +65,12 @@ function matchesParentDomain(srvAddress: string, parentDomain: string): boolean
  */
 export function resolveSRVRecord(options: MongoOptions, callback: Callback<HostAddress[]>): void {
   if (typeof options.srvHost !== 'string') {
-    return callback(new MongoParseError('Cannot resolve empty srv string'));
+    return callback(new MongoAPIError('Option "srvHost" must not be empty'));
   }
 
   if (options.srvHost.split('.').length < 3) {
-    return callback(new MongoParseError('URI does not have hostname, domain name and tld'));
+    // TODO(NODE-3484): Replace with MongoConnectionStringError
+    return callback(new MongoAPIError('URI must include hostname, domain name, and tld'));
   }
 
   // Resolve the SRV record and use the result as the list of hosts to connect to.
@@ -77,14 +79,12 @@ export function resolveSRVRecord(options: MongoOptions, callback: Callback<HostA
     if (err) return callback(err);
 
     if (addresses.length === 0) {
-      return callback(new MongoParseError('No addresses found at host'));
+      return callback(new MongoAPIError('No addresses found at host'));
     }
 
     for (const { name } of addresses) {
       if (!matchesParentDomain(name, lookupAddress)) {
-        return callback(
-          new MongoParseError('Server record does not share hostname with parent URI')
-        );
+        return callback(new MongoAPIError('Server record does not share hostname with parent URI'));
       }
     }
 
@@ -176,7 +176,7 @@ function getBoolean(name: string, value: unknown): boolean {
   const valueString = String(value).toLowerCase();
   if (TRUTHS.has(valueString)) return true;
   if (FALSEHOODS.has(valueString)) return false;
-  throw new MongoParseError(`For ${name} Expected stringified boolean value, got: ${value}`);
+  throw new MongoParseError(`Expected ${name} to be stringified boolean value, got: ${value}`);
 }
 
 function getInt(name: string, value: unknown): number {
@@ -286,7 +286,7 @@ export function parseOptions(
     const values = [...url.searchParams.getAll(key)];
 
     if (values.includes('')) {
-      throw new MongoParseError('URI cannot contain options with no value');
+      throw new MongoAPIError('URI cannot contain options with no value');
     }
 
     if (key.toLowerCase() === 'serverapi') {
@@ -335,6 +335,19 @@ export function parseOptions(
     allOptions.set(key, values);
   }
 
+  if (allOptions.has('tlsCertificateKeyFile') && !allOptions.has('tlsCertificateFile')) {
+    allOptions.set('tlsCertificateFile', allOptions.get('tlsCertificateKeyFile'));
+  }
+
+  if (allOptions.has('tls') || allOptions.has('ssl')) {
+    const tlsAndSslOpts = (allOptions.get('tls') || [])
+      .concat(allOptions.get('ssl') || [])
+      .map(getBoolean.bind(null, 'tls/ssl'));
+    if (new Set(tlsAndSslOpts).size !== 1) {
+      throw new MongoParseError('All values of tls/ssl must be the same.');
+    }
+  }
+
   const unsupportedOptions = setDifference(
     allKeys,
     Array.from(Object.keys(OPTIONS)).map(s => s.toLowerCase())
@@ -384,24 +397,12 @@ export function parseOptions(
     mongoOptions.dbName = 'test';
   }
 
-  if (allOptions.has('tls')) {
-    if (new Set(allOptions.get('tls')?.map(getBoolean)).size !== 1) {
-      throw new MongoParseError('All values of tls must be the same.');
-    }
-  }
-
-  if (allOptions.has('ssl')) {
-    if (new Set(allOptions.get('ssl')?.map(getBoolean)).size !== 1) {
-      throw new MongoParseError('All values of ssl must be the same.');
-    }
-  }
-
   checkTLSOptions(mongoOptions);
 
   if (options.promiseLibrary) PromiseProvider.set(options.promiseLibrary);
 
   if (mongoOptions.directConnection && typeof mongoOptions.srvHost === 'string') {
-    throw new MongoParseError('directConnection not supported with SRV URI');
+    throw new MongoAPIError('SRV URI does not support directConnection');
   }
 
   const lbError = validateLoadBalancedOptions(hosts, mongoOptions);
@@ -612,12 +613,22 @@ export const OPTIONS = {
     target: 'compressors',
     transform({ values }) {
       const compressionList = new Set();
-      for (const compVal of values as string[]) {
-        for (const c of compVal.split(',')) {
-          if (['none', 'snappy', 'zlib'].includes(String(c))) {
+      for (const compVal of values as (CompressorName[] | string)[]) {
+        const compValArray = typeof compVal === 'string' ? compVal.split(',') : compVal;
+        if (!Array.isArray(compValArray)) {
+          throw new MongoInvalidArgumentError(
+            'compressors must be an array or a comma-delimited list of strings'
+          );
+        }
+        for (const c of compValArray) {
+          if (Object.keys(Compressor).includes(String(c))) {
             compressionList.add(String(c));
           } else {
-            throw new MongoParseError(`${c} is not a valid compression mechanism`);
+            throw new MongoInvalidArgumentError(
+              `${c} is not a valid compression mechanism. Must be one of: ${Object.keys(
+                Compressor
+              )}.`
+            );
           }
         }
       }

package/src/cursor/abstract_cursor.ts

@@ -3,7 +3,7 @@ import { Long, Document, BSONSerializeOptions, pluckBSONSerializeOptions } from
 import { ClientSession, maybeClearPinnedConnection } from '../sessions';
 import {
   AnyError,
-  MongoDriverError,
+  MongoRuntimeError,
   MongoNetworkError,
   MongoInvalidArgumentError,
   MongoCursorExhaustedError,
@@ -51,10 +51,11 @@ export const CURSOR_FLAGS = [
   'partial'
 ] as const;
 
-/** @public */
-// TODO: Remove this as the option is never used. (NODE-3489)
+/** @public
+ * @deprecated This interface is deprecated */
 export interface CursorCloseOptions {
   /** Bypass calling killCursors when closing the cursor. */
+  /** @deprecated  the skipKillCursors option is deprecated */
   skipKillCursors?: boolean;
 }
 
@@ -279,8 +280,7 @@ export abstract class AbstractCursor<
         return done(undefined, true);
       }
 
-      next<any>(this, true, (err, doc) => {
-        // FIXME(NODE):
+      next<TSchema>(this, true, (err, doc) => {
         if (err) return done(err);
 
         if (doc) {
@@ -295,9 +295,10 @@ export abstract class AbstractCursor<
   }
 
   /** Get the next available document from the cursor, returns null if no more documents are available. */
-  next<T = TSchema>(): Promise<T | null>;
-  next<T = TSchema>(callback: Callback<T | null>): void;
-  next<T = TSchema>(callback?: Callback<T | null>): Promise<T | null> | void {
+  next(): Promise<TSchema | null>;
+  next(callback: Callback<TSchema | null>): void;
+  next(callback?: Callback<TSchema | null>): Promise<TSchema | null> | void;
+  next(callback?: Callback<TSchema | null>): Promise<TSchema | null> | void {
     return maybePromise(callback, done => {
       if (this[kId] === Long.ZERO) {
         return done(new MongoCursorExhaustedError());
@@ -310,9 +311,9 @@ export abstract class AbstractCursor<
   /**
    * Try to get the next available document from the cursor or `null` if an empty batch is returned
    */
-  tryNext<T = TSchema>(): Promise<T | null>;
-  tryNext<T = TSchema>(callback: Callback<T | null>): void;
-  tryNext<T = TSchema>(callback?: Callback<T | null>): Promise<T | null> | void {
+  tryNext(): Promise<TSchema | null>;
+  tryNext(callback: Callback<TSchema | null>): void;
+  tryNext(callback?: Callback<TSchema | null>): Promise<TSchema | null> | void {
     return maybePromise(callback, done => {
       if (this[kId] === Long.ZERO) {
         return done(new MongoCursorExhaustedError());
@@ -328,10 +329,10 @@ export abstract class AbstractCursor<
    * @param iterator - The iteration callback.
    * @param callback - The end callback.
    */
-  forEach<T = TSchema>(iterator: (doc: T) => boolean | void): Promise<void>;
-  forEach<T = TSchema>(iterator: (doc: T) => boolean | void, callback: Callback<void>): void;
-  forEach<T = TSchema>(
-    iterator: (doc: T) => boolean | void,
+  forEach(iterator: (doc: TSchema) => boolean | void): Promise<void>;
+  forEach(iterator: (doc: TSchema) => boolean | void, callback: Callback<void>): void;
+  forEach(
+    iterator: (doc: TSchema) => boolean | void,
     callback?: Callback<void>
   ): Promise<void> | void {
     if (typeof iterator !== 'function') {
@@ -340,7 +341,7 @@ export abstract class AbstractCursor<
     return maybePromise(callback, done => {
       const transform = this[kTransform];
       const fetchDocs = () => {
-        next<T>(this, true, (err, doc) => {
+        next<TSchema>(this, true, (err, doc) => {
           if (err || doc == null) return done(err);
           let result;
           // NOTE: no need to transform because `next` will do this automatically
@@ -357,7 +358,7 @@ export abstract class AbstractCursor<
           for (let i = 0; i < internalDocs.length; ++i) {
             try {
               result = iterator(
-                (transform ? transform(internalDocs[i]) : internalDocs[i]) as T // TODO(NODE-3283): Improve transform typing
+                (transform ? transform(internalDocs[i]) : internalDocs[i]) as TSchema // TODO(NODE-3283): Improve transform typing
               );
             } catch (error) {
               return done(error);
@@ -373,9 +374,15 @@ export abstract class AbstractCursor<
     });
   }
 
-  close(): Promise<void>;
+  close(): void;
   close(callback: Callback): void;
+  /**
+   * @deprecated options argument is deprecated
+   */
   close(options: CursorCloseOptions): Promise<void>;
+  /**
+   * @deprecated options argument is deprecated
+   */
   close(options: CursorCloseOptions, callback: Callback): void;
   close(options?: CursorCloseOptions | Callback, callback?: Callback): Promise<void> | void {
     if (typeof options === 'function') (callback = options), (options = {});
@@ -395,15 +402,15 @@ export abstract class AbstractCursor<
    *
    * @param callback - The result callback.
    */
-  toArray<T = TSchema>(): Promise<T[]>;
-  toArray<T = TSchema>(callback: Callback<T[]>): void;
-  toArray<T = TSchema>(callback?: Callback<T[]>): Promise<T[]> | void {
+  toArray(): Promise<TSchema[]>;
+  toArray(callback: Callback<TSchema[]>): void;
+  toArray(callback?: Callback<TSchema[]>): Promise<TSchema[]> | void {
     return maybePromise(callback, done => {
-      const docs: T[] = [];
+      const docs: TSchema[] = [];
       const transform = this[kTransform];
       const fetchDocs = () => {
         // NOTE: if we add a `nextBatch` then we should use it here
-        next<T>(this, true, (err, doc) => {
+        next<TSchema>(this, true, (err, doc) => {
           if (err) return done(err);
           if (doc == null) return done(undefined, docs);
 
@@ -411,9 +418,11 @@ export abstract class AbstractCursor<
           docs.push(doc);
 
           // these do need to be transformed since they are copying the rest of the batch
-          const internalDocs = (transform
-            ? this[kDocuments].splice(0, this[kDocuments].length).map(transform)
-            : this[kDocuments].splice(0, this[kDocuments].length)) as T[]; // TODO(NODE-3283): Improve transform typing
+          const internalDocs = (
+            transform
+              ? this[kDocuments].splice(0, this[kDocuments].length).map(transform)
+              : this[kDocuments].splice(0, this[kDocuments].length)
+          ) as TSchema[]; // TODO(NODE-3283): Improve transform typing
 
           if (internalDocs) {
             docs.push(...internalDocs);
@@ -451,11 +460,12 @@ export abstract class AbstractCursor<
    * Map all documents using the provided function
    * If there is a transform set on the cursor, that will be called first and the result passed to
    * this function's transform.
-   * @remarks
    *
-   * **NOTE:** 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 map, you should always assign the result to a new
-   * variable. Take note of the following example:
+   * @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 map,
+   * 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
@@ -476,7 +486,7 @@ export abstract class AbstractCursor<
       this[kTransform] = transform;
     }
 
-    return (this as unknown) as AbstractCursor<T>;
+    return this as unknown as AbstractCursor<T>;
   }
 
   /**
@@ -591,12 +601,12 @@ export abstract class AbstractCursor<
     const server = this[kServer];
 
     if (cursorId == null) {
-      callback(new MongoDriverError('Unable to iterate cursor with no id'));
+      callback(new MongoRuntimeError('Unable to iterate cursor with no id'));
       return;
     }
 
     if (server == null) {
-      callback(new MongoDriverError('Unable to iterate cursor without selected server'));
+      callback(new MongoRuntimeError('Unable to iterate cursor without selected server'));
       return;
     }
 
@@ -762,7 +772,7 @@ function cleanupCursor(
       }
 
       if (!session.inTransaction()) {
-        maybeClearPinnedConnection(session, { error, force: true });
+        maybeClearPinnedConnection(session, { error });
       }
     }
 
@@ -779,7 +789,7 @@ function cleanupCursor(
       }
 
       if (!session.inTransaction()) {
-        maybeClearPinnedConnection(session, { error, force: true });
+        maybeClearPinnedConnection(session, { error });
       }
     }
 

package/src/cursor/aggregation_cursor.ts

@@ -9,7 +9,6 @@ import type { Callback, MongoDBNamespace } from '../utils';
 import type { ClientSession } from '../sessions';
 import type { AbstractCursorOptions } from './abstract_cursor';
 import type { ExplainVerbosityLike } from '../explain';
-import type { Projection } from '../mongo_types';
 
 /** @public */
 export interface AggregationCursorOptions extends AbstractCursorOptions, AggregateOptions {}
@@ -121,8 +120,8 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
     return this;
   }
 
-  /** Add a out stage to the aggregation pipeline */
-  out($out: number): this {
+  /** Add an out stage to the aggregation pipeline */
+  out($out: { db: string; coll: string } | string): this {
     assertUninitialized(this);
     this[kPipeline].push({ $out });
     return this;
@@ -135,22 +134,44 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
    * 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: AggregationCursor<{ a: number }> = cursor.project<{ a: number }>({ _id: 0, a: true });
+   * // Flexible way
+   * const docs: AggregationCursor<Document> = cursor.project({ _id: 0, a: true });
+   * ```
+   *
+   * @remarks
+   * In order to strictly type this function you must provide an interface
+   * that represents the effect of your projection on the result documents.
+   *
+   * **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: AggregationCursor<{ a: number; b: string }> = coll.aggregate([]);
-   * 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.aggregate().project<{ a: string }>({
+   *   _id: 0,
+   *   a: { $convert: { input: '$a', to: 'string' }
+   * }});
    * ```
    */
-  project<T = TSchema>($project: Projection<T>): AggregationCursor<T>;
-  project($project: Document): this {
+  project<T extends Document = Document>($project: Document): AggregationCursor<T> {
     assertUninitialized(this);
     this[kPipeline].push({ $project });
-    return this;
+    return this as unknown as AggregationCursor<T>;
   }
 
   /** Add a lookup stage to the aggregation pipeline */

package/src/cursor/find_cursor.ts

@@ -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');
@@ -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>;
   }
 
   /**