feat(NODE-5241): add option to return modified document (#3710)

Author: durran

src/collection.ts

@@ -100,12 +100,7 @@ import {
 } from './utils';
 import { WriteConcern, type WriteConcernOptions } from './write_concern';
 
-/**
- * @public
- * @deprecated This type will be completely removed and findOneAndUpdate,
- *             findOneAndDelete, and findOneAndReplace will then return the
- *             actual result document.
- */
+/** @public */
 export interface ModifyResult<TSchema = Document> {
   value: WithId<TSchema> | null;
   lastErrorObject?: Document;
@@ -825,10 +820,23 @@ export class Collection<TSchema extends Document = Document> {
    * @param filter - The filter used to select the document to remove
    * @param options - Optional settings for the command
    */
+  async findOneAndDelete(
+    filter: Filter<TSchema>,
+    options: FindOneAndDeleteOptions & { includeResultMetadata: true }
+  ): Promise<ModifyResult<TSchema>>;
+  async findOneAndDelete(
+    filter: Filter<TSchema>,
+    options: FindOneAndDeleteOptions & { includeResultMetadata: false }
+  ): Promise<WithId<TSchema> | null>;
+  async findOneAndDelete(
+    filter: Filter<TSchema>,
+    options: FindOneAndDeleteOptions
+  ): Promise<ModifyResult<TSchema>>;
+  async findOneAndDelete(filter: Filter<TSchema>): Promise<ModifyResult<TSchema>>;
   async findOneAndDelete(
     filter: Filter<TSchema>,
     options?: FindOneAndDeleteOptions
-  ): Promise<ModifyResult<TSchema>> {
+  ): Promise<WithId<TSchema> | ModifyResult<TSchema> | null> {
     return executeOperation(
       this.client,
       new FindOneAndDeleteOperation(
@@ -846,11 +854,30 @@ export class Collection<TSchema extends Document = Document> {
    * @param replacement - The Document that replaces the matching document
    * @param options - Optional settings for the command
    */
+  async findOneAndReplace(
+    filter: Filter<TSchema>,
+    replacement: WithoutId<TSchema>,
+    options: FindOneAndReplaceOptions & { includeResultMetadata: true }
+  ): Promise<ModifyResult<TSchema>>;
+  async findOneAndReplace(
+    filter: Filter<TSchema>,
+    replacement: WithoutId<TSchema>,
+    options: FindOneAndReplaceOptions & { includeResultMetadata: false }
+  ): Promise<WithId<TSchema> | null>;
+  async findOneAndReplace(
+    filter: Filter<TSchema>,
+    replacement: WithoutId<TSchema>,
+    options: FindOneAndReplaceOptions
+  ): Promise<ModifyResult<TSchema>>;
+  async findOneAndReplace(
+    filter: Filter<TSchema>,
+    replacement: WithoutId<TSchema>
+  ): Promise<ModifyResult<TSchema>>;
   async findOneAndReplace(
     filter: Filter<TSchema>,
     replacement: WithoutId<TSchema>,
     options?: FindOneAndReplaceOptions
-  ): Promise<ModifyResult<TSchema>> {
+  ): Promise<WithId<TSchema> | ModifyResult<TSchema> | null> {
     return executeOperation(
       this.client,
       new FindOneAndReplaceOperation(
@@ -869,11 +896,30 @@ export class Collection<TSchema extends Document = Document> {
    * @param update - Update operations to be performed on the document
    * @param options - Optional settings for the command
    */
+  async findOneAndUpdate(
+    filter: Filter<TSchema>,
+    update: UpdateFilter<TSchema>,
+    options: FindOneAndUpdateOptions & { includeResultMetadata: true }
+  ): Promise<ModifyResult<TSchema>>;
+  async findOneAndUpdate(
+    filter: Filter<TSchema>,
+    update: UpdateFilter<TSchema>,
+    options: FindOneAndUpdateOptions & { includeResultMetadata: false }
+  ): Promise<WithId<TSchema> | null>;
+  async findOneAndUpdate(
+    filter: Filter<TSchema>,
+    update: UpdateFilter<TSchema>,
+    options: FindOneAndUpdateOptions
+  ): Promise<ModifyResult<TSchema>>;
+  async findOneAndUpdate(
+    filter: Filter<TSchema>,
+    update: UpdateFilter<TSchema>
+  ): Promise<ModifyResult<TSchema>>;
   async findOneAndUpdate(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema>,
     options?: FindOneAndUpdateOptions
-  ): Promise<ModifyResult<TSchema>> {
+  ): Promise<WithId<TSchema> | ModifyResult<TSchema> | null> {
     return executeOperation(
       this.client,
       new FindOneAndUpdateOperation(

src/operations/find_and_modify.ts

@@ -29,6 +29,8 @@ export interface FindOneAndDeleteOptions extends CommandOperationOptions {
   sort?: Sort;
   /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
   let?: Document;
+  /** Return the raw result document instead of the ModifyResult */
+  includeResultMetadata?: boolean;
 }
 
 /** @public */
@@ -47,6 +49,8 @@ export interface FindOneAndReplaceOptions extends CommandOperationOptions {
   upsert?: boolean;
   /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
   let?: Document;
+  /** Return the raw result document instead of the ModifyResult */
+  includeResultMetadata?: boolean;
 }
 
 /** @public */
@@ -67,6 +71,8 @@ export interface FindOneAndUpdateOptions extends CommandOperationOptions {
   upsert?: boolean;
   /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
   let?: Document;
+  /** Return the raw result document instead of the ModifyResult */
+  includeResultMetadata?: boolean;
 }
 
 /** @internal */
@@ -127,6 +133,8 @@ class FindAndModifyOperation extends CommandOperation<Document> {
       upsert: false
     };
 
+    options.includeResultMetadata ??= true;
+
     const sort = formatSort(options.sort);
     if (sort) {
       this.cmdBase.sort = sort;
@@ -205,7 +213,7 @@ class FindAndModifyOperation extends CommandOperation<Document> {
     // Execute the command
     super.executeCommand(server, session, cmd, (err, result) => {
       if (err) return callback(err);
-      return callback(undefined, result);
+      return callback(undefined, options.includeResultMetadata ? result : result.value ?? null);
     });
   }
 }