feat(NODE-4681): deprecate modify result (#3459)

Author: durran

src/collection.ts

@@ -99,7 +99,12 @@ import {
 } from './utils';
 import { WriteConcern, WriteConcernOptions } from './write_concern';
 
-/** @public */
+/**
+ * @public
+ * @deprecated This type will be completely removed in 5.0 and findOneAndUpdate,
+ *             findOneAndDelete, and findOneAndReplace will then return the
+ *             actual result document.
+ */
 export interface ModifyResult<TSchema = Document> {
   value: WithId<TSchema> | null;
   lastErrorObject?: Document;

test/types/community/collection/findX.test-d.ts

@@ -348,3 +348,21 @@ expectType<WithId<{ a: number; b: string }> | null>(
 expectType<WithId<{ a: number; b: string }> | null>(
   (await coll.findOneAndDelete({ a: 3 }, { projection: { _id: 0 } })).value
 );
+
+// NODE-3568: Uncomment when ModifyResult is removed in 5.0
+// expectType<WithId<TSchema> | null> | null>((await coll.findOneAndDelete({ a: 3 })));
+// expectType<WithId<TSchema> | null>(
+//   (await coll.findOneAndReplace({ a: 3 }, { a: 5, b: 'new string' }))
+// );
+// expectType<WithId<TSchema> | null>(
+//   (
+//     await coll.findOneAndUpdate(
+//       { a: 3 },
+//       {
+//         $set: {
+//           a: 5
+//         }
+//       }
+//     )
+//   )
+// );