fix(NODE-3343): allow overriding result document after projection applied

src/cursor/abstract_cursor.ts

@@ -483,6 +483,7 @@ export abstract class AbstractCursor<
    * 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:
    *
+   * @example
    * ```typescript
    * const cursor: FindCursor<Document> = coll.find();
    * const mappedCursor: FindCursor<number> = cursor.map(doc => Object.keys(doc).length);

src/cursor/aggregation_cursor.ts

@@ -10,6 +10,7 @@ import type { ClientSession } from '../sessions';
 import type { OperationParent } from '../operations/command';
 import type { AbstractCursorOptions } from './abstract_cursor';
 import type { ExplainVerbosityLike } from '../explain';
+import type { Projection } from '../mongo_types';
 
 /** @public */
 export interface AggregationCursorOptions extends AbstractCursorOptions, AggregateOptions {}
@@ -134,8 +135,25 @@ export class AggregationCursor<TSchema = Document> extends AbstractCursor<TSchem
     return this;
   }
 
-  /** Add a project stage to the aggregation pipeline */
-  project<T = TSchema>($project: Document): AggregationCursor<T>;
+  /**
+   * Add a project stage to the aggregation pipeline
+   *
+   * @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:** adding a projection 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:
+   *
+   * @example
+   * ```typescript
+   * const cursor: AggregationCursor<{ a: number; b: string }> = coll.aggregate([]);
+   * const projectCursor = cursor.project<{ a: number }>({ a: true });
+   * const aPropOnlyArray: {a: number}[] = await projectCursor.toArray();
+   * ```
+   */
+  project<T = TSchema>($project: Projection<T>): AggregationCursor<T>;
   project($project: Document): this {
     assertUninitialized(this);
     this[kPipeline].push({ $project });

src/cursor/find_cursor.ts

@@ -338,12 +338,24 @@ export class FindCursor<TSchema = Document> extends AbstractCursor<TSchema> {
   }
 
   /**
-   * Sets a field projection for the query.
+   * Add a project stage to the aggregation pipeline
    *
-   * @param value - The field projection object.
+   * @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:** adding a projection 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:
+   *
+   * @example
+   * ```typescript
+   * const cursor: FindCursor<{ a: number; b: string }> = coll.find();
+   * const projectCursor = cursor.project<{ a: number }>({ a: true });
+   * const aPropOnlyArray: {a: number}[] = await projectCursor.toArray();
+   * ```
    */
-  // TODO(NODE-3343): add parameterized cursor return type
-  project<T = TSchema>(value: SchemaMember<T, ProjectionOperators | number | boolean | any>): this;
+  project<T = TSchema>(value: Projection<T>): FindCursor<T>;
   project(value: Projection<TSchema>): this {
     assertUninitialized(this);
     this[kBuiltOptions].projection = value;