Added BsonRefId<T> to allow explicit DbRefs in LINQ expressions (#2741)

* Add Contributor Covenant Code of Conduct

This document outlines the Code of Conduct for community members, detailing pledges, standards of behavior, enforcement responsibilities, and consequences for violations.

* Update README with new build status and badges

Updated build status badge and added pre-release badge.

* Added BsonRefId<T> to allow explicit DbRefs in LINQ expressions

* Applied code review suggestions

* Applied suggestion from code review

* Make IsDbRef backward compatible + add guards

* Undo unintended markdown change

---------

Co-authored-by: Jonas Kamsker <11245306+JKamsker@users.noreply.github.com>

Author: rklfss

LiteDB.Tests/Mapper/LinqBsonExpression_Tests.cs

@@ -83,6 +83,22 @@ public class Order
 
             [BsonRef("users")]
             public List<User> Users { get; set; }
+
+            [BsonRef("products")]
+            public Product[] Products { get; set; }
+        }
+
+        public class OrderCustomer : Customer
+        {
+            // Just used to test derived types serialization in BsonRefId tests
+        }
+
+        public class OrderMissingDbRefCollectionName
+        {
+            [BsonId]
+            public int Id { get; set; }
+
+            public Product Product { get; set; }
         }
 
         public class Account
@@ -524,6 +540,79 @@ public void Linq_InvocationExpression()
             //the right expr of exprMerged uses @ (instead of $) because the rootParameter is different for exprLeft and exprRight
         }
 
+        [Fact]
+        public void Linq_MemberInit_DbRef()
+        {
+            var p1Id = ObjectId.NewObjectId();
+            var p2Id = ObjectId.NewObjectId();
+
+            TestExpr<Order>(
+                x => new Order
+                {
+                    OrderNumber = 1,
+                    Customer = new BsonRefId<OrderCustomer>(10),
+                    Users = new List<User>
+                    {
+                        new BsonRefId<User>(101),
+                        new BsonRefId<User>(x.Users[0].Id + 100),
+                    },
+                    Products = new Product[]
+                    {
+                        new BsonRefId<Product>(p1Id),
+                        new BsonRefId<Product>(p2Id),
+                    },
+                },
+                @"{
+                    _id: @p0,
+                    Customer: { $id: @p1, $ref: @p2, $type: @p3 },
+                    Users:[
+                        { $id: @p4, $ref: @p5 },
+                        { $id: ($.Users[0].$id + @p6), $ref: @p7 }
+                    ],
+                    Products: [
+                        { $id: @p8, $ref: @p9 },
+                        { $id: @p10, $ref: @p11 }
+                    ]
+                }",
+                [
+                    1,
+                    10,
+                    "customers",
+                    DefaultTypeNameBinder.Instance.GetName(typeof(OrderCustomer)),
+                    101,
+                    "users",
+                    100,
+                    "users",
+                    p1Id,
+                    "products",
+                    p2Id,
+                    "products",
+                ]);
+        }
+
+        [Fact]
+        public void Linq_MemberInit_DbRef_Throws_When_CollectionName_Is_Missing()
+        {
+            var mapper = new BsonMapper();
+
+            mapper.ResolveMember = (type, _, member) =>
+            {
+                if (type == typeof(OrderMissingDbRefCollectionName) && member.MemberName == nameof(OrderMissingDbRefCollectionName.Product))
+                {
+                    member.IsDbRef = true;
+                }
+            };
+
+            mapper.Invoking(x => x.GetExpression<OrderMissingDbRefCollectionName, object>(o => new OrderMissingDbRefCollectionName
+                {
+                    Id = 1,
+                    Product = new BsonRefId<Product>(ObjectId.NewObjectId())
+                }))
+                .Should()
+                .Throw<NotSupportedException>()
+                .WithMessage("*DbRef collection name*");
+        }
+
         #region Test helper
 
         /// <summary>
@@ -582,4 +671,4 @@ private void TestException<T, TException>(Func<Expression<Func<T, object>>> fn)
 
         #endregion
     }
-}
+}

LiteDB/Client/Mapper/BsonMapper.Serialize.cs

@@ -188,7 +188,7 @@ private BsonDocument SerializeObject(Type type, object obj, int depth)
             // adding _type only where property Type is not same as object instance type
             if (type != t)
             {
-                doc["_type"] = new BsonValue(_typeNameBinder.GetName(t));
+                doc["_type"] = SerializeTypeName(t);
             }
 
             foreach (var member in entity.Members.Where(x => x.Getter != null))
@@ -211,5 +211,13 @@ private BsonDocument SerializeObject(Type type, object obj, int depth)
 
             return doc;
         }
+
+        /// <summary>
+        /// Returns the name of the given type for serialization (type discriminator).
+        /// </summary>
+        internal BsonValue SerializeTypeName(Type type)
+        {
+            return new BsonValue(_typeNameBinder.GetName(type));
+        }
     }
-}
+}

LiteDB/Client/Mapper/BsonMapper.cs

@@ -227,22 +227,22 @@ public BsonMapper UseLowerCaseDelimiter(char delimiter = '_')
         /// </summary>
         internal static void RegisterDbRef(BsonMapper mapper, MemberMapper member, ITypeNameBinder typeNameBinder, string collection)
         {
-            member.IsDbRef = true;
+            member.DbRefCollectionName = collection;
 
             if (member.IsEnumerable)
             {
-                RegisterDbRefList(mapper, member, typeNameBinder, collection);
+                RegisterDbRefList(mapper, member, typeNameBinder);
             }
             else
             {
-                RegisterDbRefItem(mapper, member, typeNameBinder, collection);
+                RegisterDbRefItem(mapper, member, typeNameBinder);
             }
         }
 
         /// <summary>
         /// Register a property as a DbRef - implement a custom Serialize/Deserialize actions to convert entity to $id, $ref only
         /// </summary>
-        private static void RegisterDbRefItem(BsonMapper mapper, MemberMapper member, ITypeNameBinder typeNameBinder, string collection)
+        private static void RegisterDbRefItem(BsonMapper mapper, MemberMapper member, ITypeNameBinder typeNameBinder)
         {
             // get entity
             var entity = mapper.GetEntityMapper(member.DataType);
@@ -263,12 +263,12 @@ private static void RegisterDbRefItem(BsonMapper mapper, MemberMapper member, IT
                 var bsonDocument = new BsonDocument
                 {
                     ["$id"] = m.Serialize(id.GetType(), id, 0),
-                    ["$ref"] = collection
+                    ["$ref"] = member.DbRefCollectionName
                 };
 
                 if (member.DataType != obj.GetType())
                 {
-                    bsonDocument["$type"] = typeNameBinder.GetName(obj.GetType());
+                    bsonDocument["$type"] = mapper.SerializeTypeName(obj.GetType());
                 }
 
                 return bsonDocument;
@@ -311,7 +311,7 @@ private static void RegisterDbRefItem(BsonMapper mapper, MemberMapper member, IT
         /// <summary>
         /// Register a property as a DbRefList - implement a custom Serialize/Deserialize actions to convert entity to $id, $ref only
         /// </summary>
-        private static void RegisterDbRefList(BsonMapper mapper, MemberMapper member, ITypeNameBinder typeNameBinder, string collection)
+        private static void RegisterDbRefList(BsonMapper mapper, MemberMapper member, ITypeNameBinder typeNameBinder)
         {
             // get entity from list item type
             var entity = mapper.GetEntityMapper(member.UnderlyingType);
@@ -334,12 +334,12 @@ private static void RegisterDbRefList(BsonMapper mapper, MemberMapper member, IT
                     var bsonDocument = new BsonDocument
                     {
                         ["$id"] = m.Serialize(id.GetType(), id, 0),
-                        ["$ref"] = collection
+                        ["$ref"] = member.DbRefCollectionName
                     };
 
                     if (member.UnderlyingType != item.GetType())
                     {
-                        bsonDocument["$type"] = typeNameBinder.GetName(item.GetType());
+                        bsonDocument["$type"] = mapper.SerializeTypeName(item.GetType());
                     }
 
                     result.Add(bsonDocument);
@@ -402,4 +402,4 @@ private static void RegisterDbRefList(BsonMapper mapper, MemberMapper member, IT
 
         #endregion
     }
-}
+}

LiteDB/Client/Mapper/BsonRefId.cs

@@ -0,0 +1,33 @@
+using System;
+
+namespace LiteDB;
+
+/// <summary>
+/// Helper to assign the ID of a DbRef property (see <see cref="BsonRefAttribute"/>) in expression trees.
+/// </summary>
+/// <typeparam name="T">The type of the referenced entity.</typeparam>
+/// <example><code>
+/// db.GetCollection&lt;A&gt;()
+///   .UpdateMany(
+///     x => new A
+///     {
+///       Id = x.Id,
+///       Bref = new BsonRefId&lt;B&gt;(100),
+///     },
+///     x => x.Id == 11);
+/// </code></example>
+public sealed class BsonRefId<T>
+{
+    /// <summary>
+    /// Assigns the ID of the referenced entity of type <typeparamref name="T"/>.
+    /// </summary>
+    /// <param name="id">The ID to assign.</param>
+    public BsonRefId(BsonValue id)
+    {
+    }
+
+    public static implicit operator T(BsonRefId<T> _)
+    {
+        throw new NotSupportedException("The type BsonRefId<T> can only be used in LiteDB LINQ expressions.");
+    }
+}