feat: Add findCursor model method (plexinc#454)

This returns the mongodb `FindCursor` allowing users to handle iteration
however they please in their applications without loading all results
into memory at once.

Author: joshuat

docs/api/model.md

@@ -260,6 +260,33 @@ userProjected.firstName; // TypeScript error
 userProjected.lastName; // valid
 ```
 
+## `findCursor`
+
+Calls the MongoDB [`find()`](https://mongodb.github.io/node-mongodb-native/5.0/classes/Collection.html#find) method and returns the cursor.
+
+Useful when you want to process many records without loading them all into
+memory at once.
+
+**Parameters:**
+
+| Name      | Type                   | Attribute |
+| --------- | ---------------------- | --------- |
+| `filter`  | `PaprFilter<TSchema>`  | required  |
+| `options` | `FindOptions<TSchema>` | optional  |
+
+**Example:**
+
+```ts
+const cursor = await User.findCursor(
+  { active: true, email: { $exists: true } },
+  { projection: { email: 1 } }
+);
+
+for await (const user of cursor) {
+  await notify(user.email);
+}
+```
+
 ## `findOne`
 
 Calls the MongoDB [`findOne()`](https://mongodb.github.io/node-mongodb-native/5.0/classes/Collection.html#findOne) method.

src/__tests__/model.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, jest, test } from '@jest/globals';
-import { Collection, MongoError, ObjectId } from 'mongodb';
+import { Collection, FindCursor, MongoError, ObjectId } from 'mongodb';
 import { expectType } from 'ts-expect';
 import { Hooks } from '../hooks';
 import { abstract, build, Model } from '../model';
@@ -902,6 +902,37 @@ describe('model', () => {
     });
   });
 
+  describe('findCursor', () => {
+    test('default', async () => {
+      const cursor = await simpleModel.findCursor({});
+
+      expectType<FindCursor<SimpleDocument>>(cursor);
+    });
+
+    test('with projection', async () => {
+      const cursor = await simpleModel.findCursor(
+        {},
+        {
+          projection: {
+            ...projection,
+            'nested.direct': 1,
+          },
+        }
+      );
+
+      expectType<
+        FindCursor<{
+          _id: ObjectId;
+          foo: string;
+          ham?: Date;
+          nested?: {
+            direct: string;
+          };
+        }>
+      >(cursor);
+    });
+  });
+
   describe('findById', () => {
     test('default', async () => {
       const result = await simpleModel.findById('123456789012345678901234');

src/model.ts

@@ -10,6 +10,7 @@ import type {
   DeleteResult,
   DistinctOptions,
   Filter,
+  FindCursor,
   FindOneAndDeleteOptions,
   FindOneAndUpdateOptions,
   FindOptions,
@@ -86,6 +87,11 @@ export interface Model<TSchema extends BaseSchema, TOptions extends SchemaOption
     options?: Omit<FindOptions<TSchema>, 'projection'> & { projection?: TProjection }
   ) => Promise<ProjectionType<TSchema, TProjection> | null>;
 
+  findCursor: <TProjection extends Projection<TSchema> | undefined>(
+    filter: PaprFilter<TSchema>,
+    options?: Omit<FindOptions<TSchema>, 'projection'> & { projection?: TProjection }
+  ) => Promise<FindCursor<ProjectionType<TSchema, TProjection>>>;
+
   findOne: <TProjection extends Projection<TSchema> | undefined>(
     filter: PaprFilter<TSchema>,
     options?: Omit<FindOptions<TSchema>, 'projection'> & { projection?: TProjection }
@@ -158,6 +164,7 @@ export function abstract<TSchema extends BaseSchema, TOptions extends SchemaOpti
     deleteOne: abstractMethod,
     find: abstractMethod,
     findById: abstractMethod,
+    findCursor: abstractMethod,
     findOne: abstractMethod,
     findOneAndDelete: abstractMethod,
     findOneAndUpdate: abstractMethod,
@@ -668,6 +675,40 @@ export function build<TSchema extends BaseSchema, TOptions extends SchemaOptions
     }
   );
 
+  /**
+   * @description
+   * Calls the MongoDB [`find()`](https://mongodb.github.io/node-mongodb-native/5.0/classes/Collection.html#find) method and returns the cursor.
+   *
+   * Useful when you want to process many records without loading them all into
+   * memory at once.
+   *
+   * @param filter {PaprFilter<TSchema>}
+   * @param [options] {FindOptions<TSchema>}
+   *
+   * @example
+   * const cursor = await User.findCursor(
+   *   { active: true, email: { $exists: true } },
+   *   { projection: { email: 1 } }
+   * )
+   *
+   * for await (const user of cursor) {
+   *   await notify(user.email);
+   * }
+   */
+  model.findCursor = wrap(model, async function findCursor<
+    TProjection extends Projection<TSchema> | undefined
+  >(filter: PaprFilter<TSchema>, options?: Omit<FindOptions<TSchema>, 'projection'> & { projection?: TProjection }): Promise<
+    FindCursor<ProjectionType<TSchema, TProjection>>
+  > {
+    return model.collection.find(
+      filter as Filter<TSchema>,
+      {
+        ...model.defaultOptions,
+        ...options,
+      } as FindOptions<TSchema>
+    ) as FindCursor<ProjectionType<TSchema, TProjection>>;
+  });
+
   /**
    * @description
    * Calls the MongoDB [`findOne()`](https://mongodb.github.io/node-mongodb-native/5.0/classes/Collection.html#findOne) method.