tests and docs

Author: nbbeeken

src/bulk/common.ts

@@ -69,7 +69,7 @@ export interface DeleteManyModel<TSchema extends Document = Document> {
 
 /** @public */
 export interface ReplaceOneModel<TSchema extends Document = Document> {
-  /** The filter to limit the replaced document. */
+  /** The filter that specifies which document to replace. In the case of multiple matches, the first document matched is replaced. */
   filter: Filter<TSchema>;
   /** The document with which to replace the matched document. */
   replacement: WithoutId<TSchema>;
@@ -79,13 +79,13 @@ export interface ReplaceOneModel<TSchema extends Document = Document> {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
-  /** if the filter matches more than one document the first one matched by the sort order will be updated */
+  /** Specifies the sort order for the documents matched by the filter. */
   sort?: Sort;
 }
 
 /** @public */
 export interface UpdateOneModel<TSchema extends Document = Document> {
-  /** The filter to limit the updated documents. */
+  /** The filter that specifies which document to update. In the case of multiple matches, the first document matched is updated. */
   filter: Filter<TSchema>;
   /**
    * The modifications to apply. The value can be either:
@@ -101,7 +101,7 @@ export interface UpdateOneModel<TSchema extends Document = Document> {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
-  /** if the filter matches more than one document the first one matched by the sort order will be updated */
+  /** Specifies the sort order for the documents matched by the filter. */
   sort?: Sort;
 }
 

src/operations/client_bulk_write/common.ts

@@ -90,7 +90,7 @@ export interface ClientReplaceOneModel<TSchema> extends ClientWriteModel {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
-  /** if the filter matches more than one document the first one matched by the sort order will be updated */
+  /** Specifies the sort order for the documents matched by the filter. */
   sort?: Sort;
 }
 
@@ -116,7 +116,7 @@ export interface ClientUpdateOneModel<TSchema> extends ClientWriteModel {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
-  /** if the filter matches more than one document the first one matched by the sort order will be updated */
+  /** Specifies the sort order for the documents matched by the filter. */
   sort?: Sort;
 }
 

src/operations/update.ts

@@ -59,7 +59,7 @@ export interface UpdateStatement {
   arrayFilters?: Document[];
   /** A document or string that specifies the index to use to support the query predicate. */
   hint?: Hint;
-  /** if the filter matches more than one document the first one matched by the sort order will be updated */
+  /** Specifies the sort order for the documents matched by the filter. */
   sort?: SortForCmd;
 }
 
@@ -217,7 +217,7 @@ export interface ReplaceOptions extends CommandOperationOptions {
   upsert?: boolean;
   /** Map of parameter names and values that can be accessed using $$var (requires MongoDB 5.0). */
   let?: Document;
-  /** if the filter matches more than one document the first one matched by the sort order will be updated */
+  /** Specifies the sort order for the documents matched by the filter. */
   sort?: Sort;
 }
 

test/integration/crud/client_bulk_write.test.ts

@@ -396,4 +396,39 @@ describe('Client Bulk Write', function () {
       });
     });
   });
+
+  describe('sort support', () => {
+    describe(
+      'updateMany does not support sort option',
+      { requires: { mongodb: '>=8.0' } },
+      function () {
+        const commands: CommandStartedEvent[] = [];
+
+        beforeEach(async function () {
+          client = this.configuration.newClient({}, { monitorCommands: true });
+
+          client.on('commandStarted', filterForCommands('bulkWrite', commands));
+          await client.connect();
+        });
+
+        it('should not include sort field in the command', async function () {
+          await client.bulkWrite([
+            {
+              name: 'updateMany',
+              namespace: 'foo.bar',
+              filter: { age: { $lte: 5 } },
+              update: { $set: { puppy: true } },
+              // @ts-expect-error: sort is not supported in updateMany
+              sort: { age: 1 } // This sort option should be ignored
+            }
+          ]);
+
+          expect(commands).to.have.lengthOf(1);
+          const [updateCommand] = commands;
+          expect(updateCommand.commandName).to.equal('bulkWrite');
+          expect(updateCommand.command.ops[0]).to.not.have.property('sort');
+        });
+      }
+    );
+  });
 });

test/integration/crud/crud_api.test.ts

@@ -6,6 +6,7 @@ import { finished } from 'stream/promises';
 import {
   Collection,
   CommandFailedEvent,
+  type CommandStartedEvent,
   CommandSucceededEvent,
   MongoBulkWriteError,
   type MongoClient,
@@ -1152,4 +1153,53 @@ describe('CRUD API', function () {
       });
     }
   });
+
+  describe('sort support', function () {
+    let client: MongoClient;
+    let events: Array<CommandStartedEvent>;
+    let collection: Collection;
+
+    beforeEach(async function () {
+      client = this.configuration.newClient({ monitorCommands: true });
+      events = [];
+      client.on('commandStarted', commandStarted =>
+        commandStarted.commandName === 'update' ? events.push(commandStarted) : null
+      );
+
+      collection = client.db('updateManyTest').collection('updateManyTest');
+      await collection.drop().catch(() => null);
+      await collection.insertMany([{ a: 1 }, { a: 2 }]);
+    });
+
+    afterEach(async function () {
+      await collection.drop().catch(() => null);
+      await client.close();
+    });
+
+    describe('collection.updateMany()', () => {
+      it('does not attach a sort property if one is specified', async function () {
+        // @ts-expect-error: sort is not supported
+        await collection.updateMany({ a: { $gte: 1 } }, { $set: { b: 1 } }, { sort: { a: 1 } });
+
+        expect(events).to.have.lengthOf(1);
+        const [updateEvent] = events;
+        expect(updateEvent.commandName).to.equal('update');
+        expect(updateEvent.command.updates[0]).to.not.have.property('sort');
+      });
+    });
+
+    describe('collection.bulkWrite([{updateMany}])', () => {
+      it('does not attach a sort property if one is specified', async function () {
+        await collection.bulkWrite([
+          // @ts-expect-error: sort is not supported
+          { updateMany: { filter: { a: { $gte: 1 } }, update: { $set: { b: 1 } }, sort: { a: 1 } } }
+        ]);
+
+        expect(events).to.have.lengthOf(1);
+        const [updateEvent] = events;
+        expect(updateEvent.commandName).to.equal('update');
+        expect(updateEvent.command.updates[0]).to.not.have.property('sort');
+      });
+    });
+  });
 });

test/types/sort.test-d.ts

@@ -8,6 +8,19 @@ import {
   type Sort
 } from '../mongodb';
 
+const sortFieldName: Sort = 'a';
+const sortFieldNameObject: Sort = { a: 1, b: -1 };
+const sortFieldNameList: Sort = ['a', 'b'];
+const sortFieldNameTuple: Sort = ['a', 1];
+const sortFieldNameTuples: Sort = [
+  ['a', 1],
+  ['b', -1]
+];
+const sortFieldNameMap: Sort = new Map([
+  ['a', 1],
+  ['b', -1]
+]);
+
 const sorts = [
   // field names
   'a',