CSHARP-5672: Support sorting by value in PushEach operation

src/MongoDB.Driver/IndexKeysDefinitionBuilder.cs

@@ -487,20 +487,7 @@ public override BsonDocument Render(RenderArgs<TDocument> args)
         {
             var renderedField = _field.Render(args);
 
-            BsonValue value;
-            switch (_direction)
-            {
-                case SortDirection.Ascending:
-                    value = 1;
-                    break;
-                case SortDirection.Descending:
-                    value = -1;
-                    break;
-                default:
-                    throw new InvalidOperationException("Unknown value for " + typeof(SortDirection) + ".");
-            }
-
-            return new BsonDocument(renderedField.FieldName, value);
+            return new BsonDocument(renderedField.FieldName, _direction.Render());
         }
     }
 

src/MongoDB.Driver/SortDefinition.cs

@@ -47,6 +47,9 @@ public abstract class SortDefinition<TDocument>
         /// <returns>A <see cref="BsonDocument"/>.</returns>
         public abstract BsonDocument Render(RenderArgs<TDocument> args);
 
+        // TODO: remove this and refactor Render to return a BsonValue in 4.0
+        internal virtual BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => Render(args);
+
         /// <summary>
         /// Performs an implicit conversion from <see cref="BsonDocument"/> to <see cref="SortDefinition{TDocument}"/>.
         /// </summary>

src/MongoDB.Driver/SortDefinitionBuilder.cs

@@ -131,7 +131,18 @@ public static SortDefinition<TDocument> MetaTextScore<TDocument>(this SortDefini
     public sealed class SortDefinitionBuilder<TDocument>
     {
         /// <summary>
-        /// Creates an ascending sort.
+        /// Creates an ascending sort on a value rather than on a field of a document. For example, "$sort : 1".
+        /// This is used when sorting primitive values like strings or numbers, but can also be used to sort whole documents.
+        /// </summary>
+        /// <returns>A value ascending sort.</returns>
+        public SortDefinition<TDocument> Ascending()
+        {
+            return new ValueDirectionalSortDefinition<TDocument>(SortDirection.Ascending);
+        }
+
+        /// <summary>
+        /// Creates an ascending sort based on a specific field within the document. For example, "$sort : { field : 1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>An ascending sort.</returns>
@@ -141,7 +152,8 @@ public SortDefinition<TDocument> Ascending(FieldDefinition<TDocument> field)
         }
 
         /// <summary>
-        /// Creates an ascending sort.
+        /// Creates an ascending sort based on a specific field within the document. For example, "$sort : { field : 1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>An ascending sort.</returns>
@@ -171,7 +183,18 @@ public SortDefinition<TDocument> Combine(IEnumerable<SortDefinition<TDocument>>
         }
 
         /// <summary>
-        /// Creates a descending sort.
+        /// Creates a descending sort on a value rather than on a field of a document. For example, "$sort : -1".
+        /// This is used when sorting primitive values like strings or numbers, but can also be used to sort whole documents.
+        /// </summary>
+        /// <returns>A value descending sort.</returns>
+        public SortDefinition<TDocument> Descending()
+        {
+            return new ValueDirectionalSortDefinition<TDocument>(SortDirection.Descending);
+        }
+
+        /// <summary>
+        /// Creates a descending sort based on a specific field within the document. For example, "$sort: { field: -1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>A descending sort.</returns>
@@ -181,7 +204,8 @@ public SortDefinition<TDocument> Descending(FieldDefinition<TDocument> field)
         }
 
         /// <summary>
-        /// Creates a descending sort.
+        /// Creates a descending sort based on a specific field within the document. For example, "$sort: { field: -1 }".
+        /// This is used when values are documents, and you want to sort by a particular field's value.
         /// </summary>
         /// <param name="field">The field.</param>
         /// <returns>A descending sort.</returns>
@@ -232,6 +256,11 @@ internal sealed class CombinedSortDefinition<TDocument> : SortDefinition<TDocume
         public CombinedSortDefinition(IEnumerable<SortDefinition<TDocument>> sorts)
         {
             _sorts = Ensure.IsNotNull(sorts, nameof(sorts)).ToList();
+
+            if (_sorts.Any(sort => sort is ValueDirectionalSortDefinition<TDocument>))
+            {
+                throw new InvalidOperationException("Value-based sort cannot be combined with other sorts. When sorting by the entire element value, no other sorting criteria can be applied.");
+            }
         }
 
         public override BsonDocument Render(RenderArgs<TDocument> args)
@@ -272,20 +301,25 @@ public override BsonDocument Render(RenderArgs<TDocument> args)
         {
             var renderedField = _field.Render(args);
 
-            BsonValue value;
-            switch (_direction)
-            {
-                case SortDirection.Ascending:
-                    value = 1;
-                    break;
-                case SortDirection.Descending:
-                    value = -1;
-                    break;
-                default:
-                    throw new InvalidOperationException("Unknown value for " + typeof(SortDirection) + ".");
-            }
+            return new BsonDocument(renderedField.FieldName, _direction.Render());
+        }
+    }
 
-            return new BsonDocument(renderedField.FieldName, value);
+    internal sealed class ValueDirectionalSortDefinition<TDocument> : SortDefinition<TDocument>
+    {
+        private readonly SortDirection _direction;
+
+        public ValueDirectionalSortDefinition(SortDirection direction)
+        {
+            _direction = direction;
+        }
+
+        public override BsonDocument Render(RenderArgs<TDocument> args)
+        {
+            throw new InvalidOperationException(
+                "Value-based sort cannot be rendered as a document. You might be trying to use a value-based sort where a field-based sort is expected.");
         }
+
+        internal override BsonValue RenderAsBsonValue(RenderArgs<TDocument> args) => _direction.Render();
     }
 }

src/MongoDB.Driver/SortDirectionExtensions.cs

@@ -0,0 +1,31 @@
+/* Copyright 2010-present MongoDB Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+using System;
+using MongoDB.Bson;
+
+namespace MongoDB.Driver
+{
+    internal static class SortDirectionExtensions
+    {
+        internal static BsonValue Render(this SortDirection direction) =>
+            direction switch
+            {
+                SortDirection.Ascending => 1,
+                SortDirection.Descending => -1,
+                _ => throw new InvalidOperationException($"Invalid sort direction: {direction}.")
+            };
+    }
+}

src/MongoDB.Driver/UpdateDefinitionBuilder.cs

@@ -1685,7 +1685,7 @@ public override BsonValue Render(RenderArgs<TDocument> args)
 
             if (_sort != null)
             {
-                document["$push"][renderedField.FieldName]["$sort"] = _sort.Render(args.WithNewDocumentType((IBsonSerializer<TItem>)itemSerializer));
+                document["$push"][renderedField.FieldName]["$sort"] = _sort.RenderAsBsonValue(args.WithNewDocumentType((IBsonSerializer<TItem>)itemSerializer));
             }
 
             return document;

tests/MongoDB.Driver.Tests/SortDefinitionBuilderTests.cs

@@ -13,6 +13,7 @@
 * limitations under the License.
 */
 
+using System;
 using FluentAssertions;
 using MongoDB.Bson;
 using MongoDB.Bson.Serialization;
@@ -31,6 +32,14 @@ public void Ascending()
             Assert(subject.Ascending("a"), "{a: 1}");
         }
 
+        [Fact]
+        public void Ascending_value()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            Assert(subject.Ascending(), "1");
+        }
+
         [Fact]
         public void Ascending_Typed()
         {
@@ -40,6 +49,16 @@ public void Ascending_Typed()
             Assert(subject.Ascending("FirstName"), "{fn: 1}");
         }
 
+        [Fact]
+        public void Calling_render_on_value_based_sort_should_throw()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            var exception = Record.Exception(() => subject.Ascending().Render(new RenderArgs<BsonDocument>()));
+
+            exception.Should().BeOfType<InvalidOperationException>();
+        }
+
         [Fact]
         public void Combine()
         {
@@ -76,6 +95,16 @@ public void Combine_with_repeated_fields_using_extension_methods()
             Assert(sort, "{b: -1, a: -1}");
         }
 
+        [Fact]
+        public void Combine_with_value_based_sort_and_additional_sort_should_throw()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            var exception = Record.Exception(() => subject.Ascending().Descending("b"));
+
+            exception.Should().BeOfType<InvalidOperationException>();
+        }
+
         [Fact]
         public void Descending()
         {
@@ -84,6 +113,14 @@ public void Descending()
             Assert(subject.Descending("a"), "{a: -1}");
         }
 
+        [Fact]
+        public void Descending_value()
+        {
+            var subject = CreateSubject<BsonDocument>();
+
+            Assert(subject.Descending(), "-1");
+        }
+
         [Fact]
         public void Descending_Typed()
         {
@@ -120,7 +157,7 @@ public void MetaTextScore()
         private void Assert<TDocument>(SortDefinition<TDocument> sort, string expectedJson)
         {
             var documentSerializer = BsonSerializer.SerializerRegistry.GetSerializer<TDocument>();
-            var renderedSort = sort.Render(new(documentSerializer, BsonSerializer.SerializerRegistry));
+            var renderedSort = sort.RenderAsBsonValue(new(documentSerializer, BsonSerializer.SerializerRegistry));
 
             renderedSort.Should().Be(expectedJson);
         }