feat: Support options for upsert model method (#711)

Author: joshuat

docs/api/model.md

@@ -471,10 +471,11 @@ Calls the MongoDB [`findOneAndUpdate()`](https://mongodb.github.io/node-mongodb-
 
 **Parameters:**
 
-| Name     | Type                        | Attribute |
-| -------- | --------------------------- | --------- |
-| `filter` | `PaprFilter<TSchema>`       | required  |
-| `update` | `PaprUpdateFilter<TSchema>` | required  |
+| Name      | Type                        | Attribute |
+| --------- | --------------------------- | --------- |
+| `filter`  | `PaprFilter<TSchema>`       | required  |
+| `update`  | `PaprUpdateFilter<TSchema>` | required  |
+| `options` | `FindOneAndUpdateOptions`   | optional  |
 
 **Returns:**
 
@@ -484,4 +485,12 @@ Calls the MongoDB [`findOneAndUpdate()`](https://mongodb.github.io/node-mongodb-
 
 ```ts
 const user = await User.upsert({ firstName: 'John', lastName: 'Wick' }, { $set: { age: 40 } });
+
+const userProjected = await User.upsert(
+  { firstName: 'John', lastName: 'Wick' },
+  { $set: { age: 40 } },
+  { projection: { lastName: 1 } }
+);
+userProjected.firstName; // TypeScript error
+userProjected.lastName; // valid
 ```

src/__tests__/model.test.ts

@@ -2506,6 +2506,41 @@ describe('model', () => {
       );
     });
 
+    test('with projection', async () => {
+      const date = new Date();
+      const result = await simpleModel.upsert(
+        { foo: 'foo' },
+        { $set: { ham: date } },
+        { projection }
+      );
+
+      expect(result).toBe(doc);
+      expectType<{
+        _id: ObjectId;
+        foo: string;
+        ham?: Date;
+      }>(result);
+
+      expectType<string>(result.foo);
+      // @ts-expect-error `bar` is undefined here
+      result.bar;
+      expectType<Date | undefined>(result.ham);
+
+      expect(collection.findOneAndUpdate).toHaveBeenCalledWith(
+        { foo: 'foo' },
+        {
+          $set: { ham: date },
+          $setOnInsert: { bar: 123456 },
+        },
+        {
+          ignoreUndefined: true,
+          projection,
+          returnDocument: 'after',
+          upsert: true,
+        }
+      );
+    });
+
     test('throws error on failure', async () => {
       (
         collection.findOneAndUpdate as jest.Mocked<Collection['findOneAndUpdate']>

src/model.ts

@@ -131,10 +131,11 @@ export interface Model<TSchema extends BaseSchema, TOptions extends SchemaOption
     options?: UpdateOptions
   ) => Promise<UpdateResult>;
 
-  upsert: (
+  upsert: <TProjection extends Projection<TSchema> | undefined>(
     filter: PaprFilter<TSchema>,
-    update: PaprUpdateFilter<TSchema>
-  ) => Promise<WithId<TSchema>>;
+    update: PaprUpdateFilter<TSchema>,
+    options?: Omit<FindOneAndUpdateOptions, 'projection' | 'upsert'> & { projection?: TProjection }
+  ) => Promise<ProjectionType<TSchema, TProjection>>;
 }
 
 /* eslint-disable @typescript-eslint/ban-types */
@@ -1032,6 +1033,7 @@ export function build<TSchema extends BaseSchema, TOptions extends SchemaOptions
    *
    * @param filter {PaprFilter<TSchema>}
    * @param update {PaprUpdateFilter<TSchema>}
+   * @param [options] {FindOneAndUpdateOptions}
    *
    * @returns {Promise<TSchema>}
    *
@@ -1040,19 +1042,29 @@ export function build<TSchema extends BaseSchema, TOptions extends SchemaOptions
    *   { firstName: 'John', lastName: 'Wick' },
    *   { $set: { age: 40 } }
    * );
+   *
+   * const userProjected = await User.upsert(
+   *   { firstName: 'John', lastName: 'Wick' },
+   *   { $set: { age: 40 } },
+   *   { projection: { lastName: 1 } }
+   * );
+   * userProjected.firstName; // TypeScript error
+   * userProjected.lastName; // valid
    */
-  model.upsert = async function upsert(
+  model.upsert = async function upsert<TProjection extends Projection<TSchema> | undefined>(
     filter: PaprFilter<TSchema>,
-    update: PaprUpdateFilter<TSchema>
-  ): Promise<WithId<TSchema>> {
+    update: PaprUpdateFilter<TSchema>,
+    options?: Omit<FindOneAndUpdateOptions, 'projection' | 'upsert'> & { projection?: TProjection }
+  ): Promise<ProjectionType<TSchema, TProjection>> {
     const item = await model.findOneAndUpdate(filter, update, {
+      ...options,
       upsert: true,
     });
 
     if (!item) {
       throw new Error('upsert failed');
     }
 
-    return item as unknown as WithId<TSchema>;
+    return item;
   };
 }