Add support for keyed filters in EntityFilter

Author: pwelter34

docs/guide/queries/filters.md

@@ -143,6 +143,9 @@ public class EntityFilter
     [JsonPropertyName("name")]
     public string? Name { get; set; }
 
+    [JsonPropertyName("key")]
+    public string? Key { get; set; }
+
     [JsonPropertyName("value")]
     public object? Value { get; set; }
 
@@ -165,6 +168,10 @@ public class EntityFilter
 
 The name of the field or property to filter on. This should match the property name of the entity being queried.
 
+#### Key
+
+An optional key used to select a value from a dictionary-like or keyed field. When specified, the filter targets the value for the key within the field instead of the field itself.
+
 #### Operator
 
 The operator to use for the filter. Use the `FilterOperators` enum for type safety:
@@ -227,6 +234,18 @@ var filter = new EntityFilter
 };
 ```
 
+#### Dictionary Key Filter
+
+```csharp
+var filter = new EntityFilter
+{
+    Name = "Attributes",
+    Key = "Status",
+    Operator = FilterOperators.Equal,
+    Value = "Active"
+};
+```
+
 #### String Operations
 
 ```csharp

src/Arbiter.CommandQuery/Converters/EntityFilterConverter.cs

@@ -11,6 +11,7 @@ namespace Arbiter.CommandQuery.Converters;
 public sealed class EntityFilterConverter : JsonConverter<EntityFilter>
 {
     private static readonly JsonEncodedText Name = JsonEncodedText.Encode("name");
+    private static readonly JsonEncodedText Key = JsonEncodedText.Encode("key");
     private static readonly JsonEncodedText Value = JsonEncodedText.Encode("value");
     private static readonly JsonEncodedText Operator = JsonEncodedText.Encode("operator");
     private static readonly JsonEncodedText Logic = JsonEncodedText.Encode("logic");
@@ -44,6 +45,10 @@ private static void ReadValue(ref Utf8JsonReader reader, EntityFilter value, Jso
         {
             value.Name = propertyValue;
         }
+        else if (TryReadStringProperty(ref reader, Key, out propertyValue))
+        {
+            value.Key = propertyValue;
+        }
         else if (TryReadObjectProperty(ref reader, Value, out var objectValue))
         {
             value.Value = objectValue;
@@ -214,6 +219,9 @@ private static void WriteEntityFilter(Utf8JsonWriter writer, EntityFilter value,
         if (!string.IsNullOrEmpty(value.Name))
             writer.WriteString(Name, value.Name);
 
+        if (!string.IsNullOrEmpty(value.Key))
+            writer.WriteString(Key, value.Key);
+
         if (value.Operator.HasValue)
             writer.WriteString(Operator, value.Operator.Value.ToString());
 

src/Arbiter.CommandQuery/Queries/EntityFilter.cs

@@ -54,6 +54,15 @@ public partial class EntityFilter
     [JsonPropertyName("name")]
     public string? Name { get; set; }
 
+    /// <summary>
+    /// Gets or sets the optional key used when filtering a keyed value within the field or property.
+    /// </summary>
+    /// <value>
+    /// The optional key used to select a value from a keyed or dictionary-like field.
+    /// </value>
+    [JsonPropertyName("key")]
+    public string? Key { get; set; }
+
     /// <summary>
     /// Gets or sets the value to filter on.
     /// </summary>

src/Arbiter.CommandQuery/Queries/EntityFilterBuilder.cs

@@ -142,6 +142,19 @@ public static EntitySort CreateSort(string field, SortDirections? direction = nu
     public static EntityFilter CreateFilter(string field, object? value, FilterOperators? @operator = null)
         => new() { Name = field, Value = value, Operator = @operator };
 
+    /// <summary>
+    /// Creates a filter for the specified keyed field, value, and operator.
+    /// </summary>
+    /// <param name="field">The name of the field or property to filter on. Cannot be <see langword="null"/> or empty.</param>
+    /// <param name="key">The key used to select a value from the field or property. Cannot be <see langword="null"/> or empty.</param>
+    /// <param name="value">The value to filter against. Can be <see langword="null"/> depending on the operator used.</param>
+    /// <param name="operator">The comparison operator to use for filtering. If <see langword="null"/>, uses the default operator (Equal).</param>
+    /// <returns>
+    /// An <see cref="EntityFilter"/> instance configured with the specified field, key, value, and operator.
+    /// </returns>
+    public static EntityFilter CreateFilter(string field, string key, object? value, FilterOperators? @operator = null)
+        => new() { Name = field, Key = key, Value = value, Operator = @operator };
+
     /// <summary>
     /// Creates a filter group for the specified filters using the AND logic operator.
     /// </summary>

src/Arbiter.CommandQuery/Queries/LinqExpressionBuilder.cs

@@ -185,10 +185,9 @@ private static void WriteStringFilter(StringBuilder builder, List<object?> param
         if (string.IsNullOrWhiteSpace(filter.Name))
             return;
 
-        int index = parameters.Count;
-
-        var field = filter.Name;
+        var field = GetFieldExpression(parameters, filter);
         var value = filter.Value;
+        int index = parameters.Count;
 
         var method = filter.Operator switch
         {
@@ -239,10 +238,9 @@ private static void WriteStandardFilter(StringBuilder builder, List<object?> par
         if (string.IsNullOrWhiteSpace(filter.Name))
             return;
 
-        int index = parameters.Count;
-
-        var field = filter.Name;
+        var field = GetFieldExpression(parameters, filter);
         var value = filter.Value;
+        int index = parameters.Count;
 
         var comparison = filter.Operator switch
         {
@@ -277,10 +275,7 @@ private static void WriteNullFilter(StringBuilder builder, List<object?> paramet
         if (string.IsNullOrWhiteSpace(filter.Name))
             return;
 
-        int index = parameters.Count;
-
-        var field = filter.Name;
-        var value = filter.Value;
+        var field = GetFieldExpression(parameters, filter);
 
         var comparison = filter.Operator switch
         {
@@ -321,21 +316,32 @@ private static void WriteInFilter(StringBuilder builder, List<object?> parameter
         if (string.IsNullOrWhiteSpace(filter.Name))
             return;
 
-        int index = parameters.Count;
-
-        var field = filter.Name;
+        var field = GetFieldExpression(parameters, filter, qualifyWithIt: true);
         var value = filter.Value;
+        int index = parameters.Count;
 
         var negation = filter.Operator == FilterOperators.NotIn;
         if (negation)
             builder.Append('!');
 
         builder
-            .Append("it.")
             .Append(field)
             .Append(" in @")
             .Append(index);
 
         parameters.Add(value);
     }
+
+    private static string GetFieldExpression(List<object?> parameters, EntityFilter filter, bool qualifyWithIt = false)
+    {
+        var field = qualifyWithIt ? $"it.{filter.Name}" : filter.Name!;
+
+        if (string.IsNullOrWhiteSpace(filter.Key))
+            return field;
+
+        int index = parameters.Count;
+        parameters.Add(filter.Key);
+
+        return $"{field}[@{index}]";
+    }
 }

test/Arbiter.CommandQuery.Tests/Extensions/QueryExtensionsTests.cs

@@ -439,4 +439,58 @@ public void FilterInvalidName()
         act.Should().Throw<ParseException>();
     }
 
+    [Test]
+    public void FilterKeyNormal()
+    {
+        var fruits = Fruit.Data();
+        fruits.Should().NotBeEmpty();
+
+        var list = fruits
+            .AsQueryable()
+            .Filter(new EntityFilter { Name = "Tags", Key = "color", Value = "red" })
+            .ToList();
+
+        list.Should().NotBeEmpty();
+        list.Count.Should().Be(3);
+        list.Should().AllSatisfy(f => f.Tags!["color"].Should().Be("red"));
+    }
+
+    [Test]
+    public void FilterKeyContains()
+    {
+        var fruits = Fruit.Data();
+        fruits.Should().NotBeEmpty();
+
+        var list = fruits
+            .AsQueryable()
+            .Filter(new EntityFilter { Name = "Tags", Key = "season", Operator = FilterOperators.Contains, Value = "sum" })
+            .ToList();
+
+        list.Should().NotBeEmpty();
+        list.Count.Should().Be(4);
+    }
+
+    [Test]
+    public void FilterKeyLogicalOr()
+    {
+        var fruits = Fruit.Data();
+        fruits.Should().NotBeEmpty();
+
+        var list = fruits
+            .AsQueryable()
+            .Filter(new EntityFilter
+            {
+                Logic = FilterLogic.Or,
+                Filters = new List<EntityFilter>
+                {
+                    new EntityFilter { Name = "Tags", Key = "color", Value = "blue" },
+                    new EntityFilter { Name = "Tags", Key = "color", Value = "purple" }
+                }
+            })
+            .ToList();
+
+        list.Should().NotBeEmpty();
+        list.Count.Should().Be(2);
+    }
+
 }

test/Arbiter.CommandQuery.Tests/MessagePackSerializationTests.cs

@@ -29,6 +29,30 @@ public void EntityFilterRoundTripSerialization()
         deserialized.Value.Should().Be(filter.Value);
     }
 
+    [Test]
+    public void EntityFilterWithKeyRoundTripSerialization()
+    {
+        // Arrange - create a filter for a keyed value
+        var filter = new EntityFilter
+        {
+            Name = "Attributes",
+            Key = "Status",
+            Operator = FilterOperators.Equal,
+            Value = "Active"
+        };
+
+        // Act - serialize and deserialize
+        var bytes = MessagePackSerializer.Serialize(filter, MessagePackDefaults.DefaultSerializerOptions);
+        var deserialized = MessagePackSerializer.Deserialize<EntityFilter>(bytes, MessagePackDefaults.DefaultSerializerOptions);
+
+        // Assert
+        deserialized.Should().NotBeNull();
+        deserialized.Name.Should().Be(filter.Name);
+        deserialized.Key.Should().Be(filter.Key);
+        deserialized.Operator.Should().Be(filter.Operator);
+        deserialized.Value.Should().Be(filter.Value);
+    }
+
     [Test]
     public void EntityFilterGroupRoundTripSerialization()
     {

test/Arbiter.CommandQuery.Tests/Models/Fruit.cs

@@ -8,25 +8,87 @@ public class Fruit
 
     public int Rank { get; set; }
 
+    public Dictionary<string, string>? Tags { get; set; }
+
     public override string ToString()
     {
         return $"{nameof(Name)}: {Name}, {nameof(Rank)}: {Rank}";
     }
 
     public static List<Fruit> Data()
     {
-        return new List<Fruit>
-        {
-            new Fruit{ Id = new Guid("3a1ec4ee-239c-41e5-b934-fbe4ce8113df"), Name = "Pear", Rank = 1 },
-            new Fruit{ Id = new Guid("1109c1a7-65e3-4006-9611-c359f3d1f086"), Name = "Pineapple", Rank = 4 },
-            new Fruit{ Id = new Guid("0d830fec-e023-438f-bcf6-1b3cba1245e6"), Name = "Peach", Rank = 2 },
-            new Fruit{ Id = new Guid("bb7aa825-bdbb-4cda-9c12-131c13e02bea"), Name = "Apple", Rank = 3 },
-            new Fruit{ Id = new Guid("5fef330b-6f30-461d-95e2-d526b4669e76"), Name = "Grape", Rank = 5 },
-            new Fruit{ Id = new Guid("50611bc9-dac8-4552-b556-f252b1cff0d3"), Name = "Orange", Rank = 6},
-            new Fruit{ Id = new Guid("5f467286-e321-44df-8a27-2c52a5ceed64"), Name = "Strawberry", Rank = 7 },
-            new Fruit{ Id = new Guid("ef628e60-500a-4663-8b06-548b0f5857de"), Name = "Blueberry", Rank = 7 },
-            new Fruit{ Id = new Guid("dc0a7dc7-40de-430d-a8fc-e17370c2a773"), Name = "Banana", Rank = 8 },
-            new Fruit{ Id = new Guid("98620233-75c5-4213-966c-9c6bfcf9e8d5"), Name = "Raspberry", Rank = 7 }
-        };
+        return
+        [
+            new Fruit
+            {
+                Id = new("3a1ec4ee-239c-41e5-b934-fbe4ce8113df"),
+                Name = "Pear",
+                Rank = 1,
+                Tags = new() { ["color"] = "green", ["season"] = "fall" }
+            },
+            new Fruit
+            {
+                Id = new("1109c1a7-65e3-4006-9611-c359f3d1f086"),
+                Name = "Pineapple",
+                Rank = 4,
+                Tags = new() { ["color"] = "yellow", ["season"] = "summer" }
+            },
+            new Fruit
+            {
+                Id = new("0d830fec-e023-438f-bcf6-1b3cba1245e6"),
+                Name = "Peach",
+                Rank = 2,
+                Tags = new() { ["color"] = "orange", ["season"] = "summer" }
+            },
+            new Fruit
+            {
+                Id = new("bb7aa825-bdbb-4cda-9c12-131c13e02bea"),
+                Name = "Apple",
+                Rank = 3,
+                Tags = new() { ["color"] = "red", ["season"] = "fall" }
+            },
+            new Fruit
+            {
+                Id = new("5fef330b-6f30-461d-95e2-d526b4669e76"),
+                Name = "Grape",
+                Rank = 5,
+                Tags = new() { ["color"] = "purple", ["season"] = "fall" }
+            },
+            new Fruit
+            {
+                Id = new("50611bc9-dac8-4552-b556-f252b1cff0d3"),
+                Name = "Orange",
+                Rank = 6,
+                Tags = new() { ["color"] = "orange", ["season"] = "winter" }
+            },
+            new Fruit
+            {
+                Id = new("5f467286-e321-44df-8a27-2c52a5ceed64"),
+                Name = "Strawberry",
+                Rank = 7,
+                Tags = new() { ["color"] = "red", ["season"] = "spring" }
+            },
+            new Fruit
+            {
+                Id = new("ef628e60-500a-4663-8b06-548b0f5857de"),
+                Name = "Blueberry",
+                Rank = 7,
+                Tags = new() { ["color"] = "blue", ["season"] = "summer" }
+            },
+            new Fruit
+            {
+                Id = new("dc0a7dc7-40de-430d-a8fc-e17370c2a773"),
+                Name = "Banana",
+                Rank = 8,
+                Tags = new() { ["color"] = "yellow", ["season"] = "all" }
+            },
+            new Fruit
+            {
+                Id = new("98620233-75c5-4213-966c-9c6bfcf9e8d5"),
+                Name = "Raspberry",
+                Rank = 7,
+                Tags = new() { ["color"] = "red", ["season"] = "summer" }
+            }
+        ];
     }
 }