feat(NODE-6290): add sort support to updateOne and replaceOne (#4515)

Author: nbbeeken

src/bulk/common.ts

@@ -19,6 +19,7 @@ import { makeUpdateStatement, UpdateOperation, type UpdateStatement } from '../o
 import type { Server } from '../sdam/server';
 import type { Topology } from '../sdam/topology';
 import type { ClientSession } from '../sessions';
+import { type Sort } from '../sort';
 import { type TimeoutContext } from '../timeout';
 import {
   applyRetryableWrites,
@@ -68,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>;
@@ -78,11 +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;
+  /** 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:
@@ -98,6 +101,8 @@ export interface UpdateOneModel<TSchema extends Document = Document> {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
+  /** Specifies the sort order for the documents matched by the filter. */
+  sort?: Sort;
 }
 
 /** @public */

src/collection.ts

@@ -87,6 +87,7 @@ import {
 } from './operations/update';
 import { ReadConcern, type ReadConcernLike } from './read_concern';
 import { ReadPreference, type ReadPreferenceLike } from './read_preference';
+import { type Sort } from './sort';
 import {
   DEFAULT_PK_FACTORY,
   MongoDBCollectionNamespace,
@@ -365,7 +366,7 @@ export class Collection<TSchema extends Document = Document> {
   async updateOne(
     filter: Filter<TSchema>,
     update: UpdateFilter<TSchema> | Document[],
-    options?: UpdateOptions
+    options?: UpdateOptions & { sort?: Sort }
   ): Promise<UpdateResult<TSchema>> {
     return await executeOperation(
       this.client,

src/operations/client_bulk_write/command_builder.ts

@@ -3,6 +3,7 @@ import { DocumentSequence } from '../../cmap/commands';
 import { MongoAPIError, MongoInvalidArgumentError } from '../../error';
 import { type PkFactory } from '../../mongo_client';
 import type { Filter, OptionalId, UpdateFilter, WithoutId } from '../../mongo_types';
+import { formatSort, type SortForCmd } from '../../sort';
 import { DEFAULT_PK_FACTORY, hasAtomicOperators } from '../../utils';
 import { type CollationOptions } from '../command';
 import { type Hint } from '../operation';
@@ -327,6 +328,7 @@ export interface ClientUpdateOperation {
   upsert?: boolean;
   arrayFilters?: Document[];
   collation?: CollationOptions;
+  sort?: SortForCmd;
 }
 
 /**
@@ -398,6 +400,9 @@ function createUpdateOperation(
   if (model.collation) {
     document.collation = model.collation;
   }
+  if (!multi && 'sort' in model && model.sort != null) {
+    document.sort = formatSort(model.sort);
+  }
   return document;
 }
 
@@ -410,6 +415,7 @@ export interface ClientReplaceOneOperation {
   hint?: Hint;
   upsert?: boolean;
   collation?: CollationOptions;
+  sort?: SortForCmd;
 }
 
 /**
@@ -443,6 +449,9 @@ export const buildReplaceOneOperation = (
   if (model.collation) {
     document.collation = model.collation;
   }
+  if (model.sort != null) {
+    document.sort = formatSort(model.sort);
+  }
   return document;
 };
 

src/operations/client_bulk_write/common.ts

@@ -2,6 +2,7 @@ import { type Document } from '../../bson';
 import type { Filter, OptionalId, UpdateFilter, WithoutId } from '../../mongo_types';
 import type { CollationOptions, CommandOperationOptions } from '../../operations/command';
 import type { Hint } from '../../operations/operation';
+import { type Sort } from '../../sort';
 
 /** @public */
 export interface ClientBulkWriteOptions extends CommandOperationOptions {
@@ -89,6 +90,8 @@ export interface ClientReplaceOneModel<TSchema> extends ClientWriteModel {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
+  /** Specifies the sort order for the documents matched by the filter. */
+  sort?: Sort;
 }
 
 /** @public */
@@ -113,6 +116,8 @@ export interface ClientUpdateOneModel<TSchema> extends ClientWriteModel {
   hint?: Hint;
   /** When true, creates a new document if no document matches the query. */
   upsert?: boolean;
+  /** Specifies the sort order for the documents matched by the filter. */
+  sort?: Sort;
 }
 
 /** @public */

src/operations/update.ts

@@ -4,6 +4,7 @@ import { MongoCompatibilityError, MongoInvalidArgumentError, MongoServerError }
 import type { InferIdType, TODO_NODE_3286 } from '../mongo_types';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
+import { formatSort, type Sort, type SortForCmd } from '../sort';
 import { type TimeoutContext } from '../timeout';
 import { hasAtomicOperators, type MongoDBNamespace } from '../utils';
 import { type CollationOptions, CommandOperation, type CommandOperationOptions } from './command';
@@ -58,6 +59,8 @@ export interface UpdateStatement {
   arrayFilters?: Document[];
   /** A document or string that specifies the index to use to support the query predicate. */
   hint?: Hint;
+  /** Specifies the sort order for the documents matched by the filter. */
+  sort?: SortForCmd;
 }
 
 /**
@@ -214,6 +217,8 @@ 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;
+  /** Specifies the sort order for the documents matched by the filter. */
+  sort?: Sort;
 }
 
 /** @internal */
@@ -259,7 +264,7 @@ export class ReplaceOneOperation extends UpdateOperation {
 export function makeUpdateStatement(
   filter: Document,
   update: Document | Document[],
-  options: UpdateOptions & { multi?: boolean }
+  options: UpdateOptions & { multi?: boolean } & { sort?: Sort }
 ): UpdateStatement {
   if (filter == null || typeof filter !== 'object') {
     throw new MongoInvalidArgumentError('Selector must be a valid JavaScript object');
@@ -290,6 +295,10 @@ export function makeUpdateStatement(
     op.collation = options.collation;
   }
 
+  if (!options.multi && options.sort != null) {
+    op.sort = formatSort(options.sort);
+  }
+
   return op;
 }
 

src/sort.ts

@@ -8,24 +8,24 @@ export type SortDirection =
   | 'desc'
   | 'ascending'
   | 'descending'
-  | { $meta: string };
+  | { readonly $meta: string };
 
 /** @public */
 export type Sort =
   | string
-  | Exclude<SortDirection, { $meta: string }>
-  | string[]
-  | { [key: string]: SortDirection }
-  | Map<string, SortDirection>
-  | [string, SortDirection][]
-  | [string, SortDirection];
+  | Exclude<SortDirection, { readonly $meta: string }>
+  | ReadonlyArray<string>
+  | { readonly [key: string]: SortDirection }
+  | ReadonlyMap<string, SortDirection>
+  | ReadonlyArray<readonly [string, SortDirection]>
+  | readonly [string, SortDirection];
 
 /** Below stricter types were created for sort that correspond with type that the cmd takes  */
 
-/** @internal */
+/** @public */
 export type SortDirectionForCmd = 1 | -1 | { $meta: string };
 
-/** @internal */
+/** @public */
 export type SortForCmd = Map<string, SortDirectionForCmd>;
 
 /** @internal */
@@ -55,7 +55,7 @@ function isMeta(t: SortDirection): t is { $meta: string } {
 }
 
 /** @internal */
-function isPair(t: Sort): t is [string, SortDirection] {
+function isPair(t: Sort): t is readonly [string, SortDirection] {
   if (Array.isArray(t) && t.length === 2) {
     try {
       prepareDirection(t[1]);
@@ -67,33 +67,37 @@ function isPair(t: Sort): t is [string, SortDirection] {
   return false;
 }
 
-function isDeep(t: Sort): t is [string, SortDirection][] {
+function isDeep(t: Sort): t is ReadonlyArray<readonly [string, SortDirection]> {
   return Array.isArray(t) && Array.isArray(t[0]);
 }
 
-function isMap(t: Sort): t is Map<string, SortDirection> {
+function isMap(t: Sort): t is ReadonlyMap<string, SortDirection> {
   return t instanceof Map && t.size > 0;
 }
 
+function isReadonlyArray<T>(value: any): value is readonly T[] {
+  return Array.isArray(value);
+}
+
 /** @internal */
-function pairToMap(v: [string, SortDirection]): SortForCmd {
+function pairToMap(v: readonly [string, SortDirection]): SortForCmd {
   return new Map([[`${v[0]}`, prepareDirection([v[1]])]]);
 }
 
 /** @internal */
-function deepToMap(t: [string, SortDirection][]): SortForCmd {
+function deepToMap(t: ReadonlyArray<readonly [string, SortDirection]>): SortForCmd {
   const sortEntries: SortPairForCmd[] = t.map(([k, v]) => [`${k}`, prepareDirection(v)]);
   return new Map(sortEntries);
 }
 
 /** @internal */
-function stringsToMap(t: string[]): SortForCmd {
+function stringsToMap(t: ReadonlyArray<string>): SortForCmd {
   const sortEntries: SortPairForCmd[] = t.map(key => [`${key}`, 1]);
   return new Map(sortEntries);
 }
 
 /** @internal */
-function objectToMap(t: { [key: string]: SortDirection }): SortForCmd {
+function objectToMap(t: { readonly [key: string]: SortDirection }): SortForCmd {
   const sortEntries: SortPairForCmd[] = Object.entries(t).map(([k, v]) => [
     `${k}`,
     prepareDirection(v)
@@ -102,7 +106,7 @@ function objectToMap(t: { [key: string]: SortDirection }): SortForCmd {
 }
 
 /** @internal */
-function mapToMap(t: Map<string, SortDirection>): SortForCmd {
+function mapToMap(t: ReadonlyMap<string, SortDirection>): SortForCmd {
   const sortEntries: SortPairForCmd[] = Array.from(t).map(([k, v]) => [
     `${k}`,
     prepareDirection(v)
@@ -116,17 +120,22 @@ export function formatSort(
   direction?: SortDirection
 ): SortForCmd | undefined {
   if (sort == null) return undefined;
-  if (typeof sort === 'string') return new Map([[sort, prepareDirection(direction)]]);
+
+  if (typeof sort === 'string') return new Map([[sort, prepareDirection(direction)]]); // 'fieldName'
+
   if (typeof sort !== 'object') {
     throw new MongoInvalidArgumentError(
       `Invalid sort format: ${JSON.stringify(sort)} Sort must be a valid object`
     );
   }
-  if (!Array.isArray(sort)) {
-    return isMap(sort) ? mapToMap(sort) : Object.keys(sort).length ? objectToMap(sort) : undefined;
+
+  if (!isReadonlyArray(sort)) {
+    if (isMap(sort)) return mapToMap(sort); // Map<fieldName, SortDirection>
+    if (Object.keys(sort).length) return objectToMap(sort); // { [fieldName: string]: SortDirection }
+    return undefined;
   }
   if (!sort.length) return undefined;
-  if (isDeep(sort)) return deepToMap(sort);
-  if (isPair(sort)) return pairToMap(sort);
-  return stringsToMap(sort);
+  if (isDeep(sort)) return deepToMap(sort); // [ [fieldName, sortDir], [fieldName, sortDir] ... ]
+  if (isPair(sort)) return pairToMap(sort); // [ fieldName, sortDir ]
+  return stringsToMap(sort); // [ fieldName, fieldName ]
 }

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