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);
  });
  }
 }