DRIVERS-2822 Add sort option to updateOne (#1644)

Author: qingyang-hu

source/crud/bulk-write.md

@@ -90,6 +90,14 @@ class UpdateOneModel implements WriteModel {
      * value is false.
      */
     upsert: Optional<Boolean>;
+
+    /**
+     * Specify which document the operation updates if the query matches multiple
+     * documents. The first document matched by the sort order will be updated.
+     *
+     * This option is only sent if the caller explicitly provides a value.
+     */
+    sort: Optional<Document>;
 }
 
 class UpdateManyModel implements WriteModel {
@@ -167,6 +175,14 @@ class ReplaceOneModel implements WriteModel {
      * value is false.
      */
     upsert: Optional<Boolean>;
+
+    /**
+     * Specify which document the operation replaces if the query matches multiple
+     * documents. The first document matched by the sort order will be replaced.
+     *
+     * This option is only sent if the caller explicitly provides a value.
+     */
+    sort: Optional<Document>;
 }
 
 class DeleteOneModel implements WriteModel {
@@ -909,6 +925,8 @@ batch-splitting to standardize implementations across drivers and simplify batch
 
 ## **Changelog**
 
+- 2024-10-01: Add sort option to `replaceOne` and `updateOne`.
+
 - 2024-09-30: Define more options for modeling summary vs. verbose results.
 
 - 2024-09-25: Add `collation` field to `update` document and clarify usage of `updateMods`.

source/crud/crud.md

@@ -1049,7 +1049,6 @@ class UpdateOptions {
    */
   upsert: Optional<Boolean>;
 
-
   /**
    * Map of parameter names and values. Values must be constant or closed
    * expressions that do not reference document fields. Parameters can then be
@@ -1071,6 +1070,18 @@ class UpdateOptions {
    * and providing one will result in a server-side error.
    */
   comment: Optional<any>;
+
+  /**
+   * Specify which document the operation updates if the query matches multiple
+   * documents. The first document matched by the sort order will be updated.
+   *
+   * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   * The server will report an error if the caller explicitly provides a value with updateMany().
+   * This option is only supported by servers >= 8.0. Older servers will report an error for using this option.
+   *
+   * @see https://www.mongodb.com/docs/manual/reference/command/update/
+   */
+  sort: Optional<Document>;
 }
 
 class ReplaceOptions {
@@ -1139,6 +1150,17 @@ class ReplaceOptions {
    * and providing one will result in a server-side error.
    */
   comment: Optional<any>;
+
+  /**
+   * Specify which document the operation replaces if the query matches multiple
+   * documents. The first document matched by the sort order will be replaced.
+   *
+   * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   * This option is only supported by servers >= 8.0. Older servers will report an error for using this option.
+   *
+   * @see https://www.mongodb.com/docs/manual/reference/command/update/
+   */
+  sort: Optional<Document>;
 }
 
 class DeleteOptions {
@@ -1319,6 +1341,17 @@ class ReplaceOneModel implements WriteModel {
    */
   hint: Optional<(String | Document)>;
 
+  /**
+   * Specify which document the operation replaces if the query matches multiple
+   * documents. The first document matched by the sort order will be replaced.
+   *
+   * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   * This option is only supported by servers >= 8.0. Older servers will report an error for using this option.
+   *
+   * @see https://www.mongodb.com/docs/manual/reference/command/update/
+   */
+  sort: Optional<Document>;
+
   /**
    * When true, creates a new document if no document matches the query.
    *
@@ -1381,6 +1414,17 @@ class UpdateOneModel implements WriteModel {
    */
   hint: Optional<(String | Document)>;
 
+  /**
+   * Specify which document the operation updates if the query matches multiple
+   * documents. The first document matched by the sort order will be updated.
+   *
+   * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   * This option is only supported by servers >= 8.0. Older servers will report an error for using this option.
+   *
+   * @see https://www.mongodb.com/docs/manual/reference/command/update/
+   */
+  sort: Optional<Document>;
+
   /**
    * When true, creates a new document if no document matches the query.
    *
@@ -2430,6 +2474,8 @@ aforementioned allowance in the SemVer spec.
 
 ## Changelog
 
+- 2024-10-01: Add sort option to `replaceOne` and `updateOne`.
+
 - 2024-09-12: Specify that explain helpers support maxTimeMS.
 
 - 2024-02-20: Migrated from reStructuredText to Markdown.