v3.25.1

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Represents the **NuGet** versions.
 
+## v3.25.1
+- *Fixed:* Extend `QueryFilterFieldConfigBase` to include `AsNullable()` to specifiy whether the field supports `null`.
+- *Fixed:* Extend `QueryFilterFieldConfigBase` to include `WithResultWriter()` to specify a function to override the corresponding LINQ statement result writing.
+- *Fixed:* Adjusted the fluent-style method-chaining interface to improve usability (and consistency).
+
 ## v3.25.0
 - *Enhancement:* Added new `CoreEx.Data` project/package to encapsulate all generic data-related capabilities, specifically the new `QueryFilterParser` and `QueryOrderByParser` classes. These enable a limited, explicitly supported, dynamic capability to `$filter` and `$orderby` an underlying query _similar_ to _OData_. This is **not** intended to be a replacement for the full capabilities of OData, GraphQL, etc. but to offer basic dynamic flexibility where needed.
   - Added `IQueryable<T>.Where()` and `IQueryable<T>.OrderBy` extension method that will use the aforementioned parsers configured within the new `QueryArgsConfig` and `QueryArgs` and apply leveraging `System.Linq.Dynamic.Core`.

Common.targets

@@ -1,6 +1,6 @@
 <Project>
 	<PropertyGroup>
-		<Version>3.25.0</Version>
+		<Version>3.25.1</Version>
 		<LangVersion>preview</LangVersion>
 		<Authors>Avanade</Authors>
 		<Company>Avanade</Company>

samples/My.Hr/My.Hr.Business/Services/EmployeeService.cs

@@ -6,8 +6,8 @@ public class EmployeeService : IEmployeeService
 {
     private static readonly QueryArgsConfig _queryConfig = QueryArgsConfig.Create()
         .WithFilter(filter => filter
-            .AddField<string>("LastName", c => c.Operators(QueryFilterTokenKind.AllStringOperators).UseUpperCase())
-            .AddField<string>("FirstName", c => c.Operators(QueryFilterTokenKind.AllStringOperators).UseUpperCase())
+            .AddField<string>("LastName", c => c.WithOperators(QueryFilterOperator.AllStringOperators).WithUpperCase())
+            .AddField<string>("FirstName", c => c.WithOperators(QueryFilterOperator.AllStringOperators).WithUpperCase())
             .AddField<DateTime>("StartDate")
             .AddField<DateTime>("TerminationDate")
             .AddField<string>(nameof(Employee.Gender), c => c.WithValue(v =>

src/CoreEx.Data/Querying/Expressions/IQueryFilterFieldStatementExpression.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Avanade. Licensed under the MIT License. See https://github.com/Avanade/CoreEx
+
+namespace CoreEx.Data.Querying.Expressions
+{
+    /// <summary>
+    /// Identifies a query filter statement expression.
+    /// </summary>
+    public interface IQueryFilterFieldStatementExpression 
+    {
+        /// <summary>
+        /// Gets the field <see cref="IQueryFilterFieldConfig"/>.
+        /// </summary>
+        IQueryFilterFieldConfig FieldConfig { get; }
+
+        /// <summary>
+        /// Gets the field <see cref="QueryFilterToken"/>.
+        /// </summary>
+        QueryFilterToken Field { get; }
+    }
+}

src/CoreEx.Data/Querying/Expressions/QueryFilterCloseParenthesisExpression.cs

@@ -17,8 +17,5 @@ public sealed class QueryFilterCloseParenthesisExpression(QueryFilterParser pars
 
         /// <inheritdoc/>
         public override void WriteToResult(QueryFilterParserResult result) => result.FilterBuilder.Append(_syntax.ToLinq(Filter));
-
-        /// <inheritdoc/>
-        protected override IQueryFilterFieldConfig? GetFieldConfig() => null;
     }
 }

src/CoreEx.Data/Querying/Expressions/QueryFilterExpressionBase.cs

@@ -65,12 +65,6 @@ public void AddToken(QueryFilterToken token)
         /// <param name="token">The <see cref="QueryFilterToken"/>.</param>
         protected abstract void AddToken(int index, QueryFilterToken token);
 
-        /// <summary>
-        /// Gets the underlying <see cref="IQueryFilterFieldConfig"/> used in the expression.
-        /// </summary>
-        /// <returns>The field <see cref="IQueryFilterFieldConfig"/> where applicable; otherwise, <see langword="null"/>.</returns>
-        protected abstract IQueryFilterFieldConfig? GetFieldConfig();
-
         /// <summary>
         /// Converts the query filter expression into the corresponding dynamic LINQ appending to the <paramref name="result"/>.
         /// </summary>

src/CoreEx.Data/Querying/Expressions/QueryFilterLogicalExpression.cs

@@ -50,8 +50,5 @@ public override void WriteToResult(QueryFilterParserResult result)
             if (_not.Kind != QueryFilterTokenKind.Unspecified)
                 result.Append(_not.ToLinq(Filter));
         }
-
-        /// <inheritdoc/>
-        protected override IQueryFilterFieldConfig? GetFieldConfig() => null;
     }
 }

src/CoreEx.Data/Querying/Expressions/QueryFilterOpenParenthesisExpression.cs

@@ -17,8 +17,5 @@ public sealed class QueryFilterOpenParenthesisExpression(QueryFilterParser parse
 
         /// <inheritdoc/>
         public override void WriteToResult(QueryFilterParserResult result) => result.Append(_syntax.ToLinq(Filter));
-
-        /// <inheritdoc/>
-        protected override IQueryFilterFieldConfig? GetFieldConfig() => null;
     }
 }

src/CoreEx.Data/Querying/Expressions/QueryFilterOperatorExpression.cs

@@ -1,23 +1,25 @@
 // Copyright (c) Avanade. Licensed under the MIT License. See https://github.com/Avanade/CoreEx
 
+using System;
 using System.Collections.Generic;
 
 namespace CoreEx.Data.Querying.Expressions
 {
     /// <summary>
-    /// Represents a query filter <see cref="QueryFilterTokenKind.Operator"/> expression.
+    /// Represents a query filter <see cref="QueryFilterTokenKind.ComparisonOperators"/> expression.
     /// </summary>
     /// <param name="parser">The <see cref="QueryFilterParser"/>.</param>
     /// <param name="filter">The originating query filter.</param>
     /// <param name="field">The field <see cref="QueryFilterToken"/>.</param>
-    public sealed class QueryFilterOperatorExpression(QueryFilterParser parser, string filter, QueryFilterToken field) : QueryFilterExpressionBase(parser, filter, field)
+    public sealed class QueryFilterOperatorExpression(QueryFilterParser parser, string filter, QueryFilterToken field) : QueryFilterExpressionBase(parser, filter, field), IQueryFilterFieldStatementExpression
     {
+        private IQueryFilterFieldConfig? _fieldConfig;
         private bool _isComplete;
 
         /// <summary>
         /// Gets the field <see cref="IQueryFilterFieldConfig"/>.
         /// </summary>
-        public IQueryFilterFieldConfig? FieldConfig { get; private set; }
+        public IQueryFilterFieldConfig FieldConfig => _fieldConfig ?? throw new InvalidOperationException($"{nameof(FieldConfig)} must be set before it can be accessed.");
 
         /// <summary>
         /// Gets the field <see cref="QueryFilterToken"/>.
@@ -38,7 +40,7 @@ public sealed class QueryFilterOperatorExpression(QueryFilterParser parser, stri
         public override bool IsComplete => _isComplete;
 
         /// <inheritdoc/>
-        public override bool CanAddToken(QueryFilterToken token) => !_isComplete || TokenCount == 1 && QueryFilterTokenKind.Operator.HasFlag(token.Kind);
+        public override bool CanAddToken(QueryFilterToken token) => !_isComplete || TokenCount == 1 && QueryFilterTokenKind.ComparisonOperators.HasFlag(token.Kind);
 
         /// <inheritdoc/>
         protected override void AddToken(int index, QueryFilterToken token)
@@ -47,15 +49,16 @@ protected override void AddToken(int index, QueryFilterToken token)
             {
                 case 0:
                     Field = token;
-                    FieldConfig = Parser.GetFieldConfig(Field, Filter);
+                    _fieldConfig = Parser.GetFieldConfig(Field, Filter);
                     _isComplete = FieldConfig.IsTypeBoolean;
                     break;
 
                 case 1:
                     if (!QueryFilterTokenKind.AllStringOperators.HasFlag(token.Kind))
                         throw new QueryFilterParserException($"Field '{Field.GetRawToken(Filter).ToString()}' does not support '{token.GetRawToken(Filter).ToString()}' as an operator.");
 
-                    if (!FieldConfig!.SupportedKinds.HasFlag(token.Kind))
+                    var op = (QueryFilterOperator)(int)token.Kind; 
+                    if (!FieldConfig.Operators.HasFlag(op))
                         throw new QueryFilterParserException($"Field '{Field.GetRawToken(Filter).ToString()}' does not support the '{token.GetRawToken(Filter).ToString()}' operator.");
 
                     _isComplete = false;
@@ -71,10 +74,10 @@ protected override void AddToken(int index, QueryFilterToken token)
                         break;
                     }
 
-                    if (token.Kind == QueryFilterTokenKind.Null && !QueryFilterTokenKind.EqualityOperator.HasFlag(Operator.Kind))
+                    if (token.Kind == QueryFilterTokenKind.Null && !QueryFilterTokenKind.EqualityOperators.HasFlag(Operator.Kind))
                         throw new QueryFilterParserException($"Field '{Field.GetRawToken(Filter).ToString()}' constant must not be null for an '{Operator.GetRawToken(Filter).ToString()}' operator.");
 
-                    FieldConfig!.ValidateConstant(Field, token, Filter);
+                    FieldConfig.ValidateConstant(Field, token, Filter);
                     Constants.Add(token);
                     _isComplete = true;
                     break;
@@ -91,7 +94,7 @@ protected override void AddToken(int index, QueryFilterToken token)
                         if (token.Kind == QueryFilterTokenKind.Null)
                             throw new QueryFilterParserException($"Field '{Field.GetRawToken(Filter).ToString()}' constant must not be null for an '{Operator.GetRawToken(Filter).ToString()}' operator.");
 
-                        FieldConfig!.ValidateConstant(Field, token, Filter);
+                        FieldConfig.ValidateConstant(Field, token, Filter);
                         Constants.Add(token);
                     }
                     else
@@ -113,19 +116,24 @@ protected override void AddToken(int index, QueryFilterToken token)
             }
         }
 
+        /// <summary>
+        /// Gets the converted <see cref="Constants"/> value using the specified <paramref name="index"/>.
+        /// </summary>
+        /// <param name="index">The <see cref="Constants"/> index.</param>
+        /// <returns>The converted value.</returns>
+        public object GetConstantValue(int index) => Constants[index].GetConvertedValue(Operator, Field, FieldConfig, Filter);
+
         /// <inheritdoc/>
         public override void WriteToResult(QueryFilterParserResult result)
         {
-            result.Fields.Add(FieldConfig!.Field);
-
-            if (Operator.Kind != QueryFilterTokenKind.In && (Constants.Count == 0 || Constants[0].Kind != QueryFilterTokenKind.Null) && FieldConfig!.IsCheckForNotNull)
+            if (Operator.Kind != QueryFilterTokenKind.In && (Constants.Count == 0 || Constants[0].Kind != QueryFilterTokenKind.Null) && FieldConfig.IsCheckForNotNull)
             {
                 result.Append("(");
                 result.FilterBuilder.Append(FieldConfig.Model);
                 result.FilterBuilder.Append(" != null && ");
             }
 
-            result.Append(FieldConfig!.Model);
+            result.Append(FieldConfig.Model);
 
             if (Constants.Count > 0)
             {
@@ -144,25 +152,22 @@ public override void WriteToResult(QueryFilterParserResult result)
                         if (i > 0)
                             result.FilterBuilder.Append(", ");
 
-                        result.AppendValue(Constants[i].GetConvertedValue(Operator, Field, FieldConfig, Filter));
+                        result.AppendValue(GetConstantValue(i));
                     }
 
                     result.FilterBuilder.Append(')');
                 }
                 else
                 {
                     if (Constants[0].Kind == QueryFilterTokenKind.Value || Constants[0].Kind == QueryFilterTokenKind.Literal)
-                        result.AppendValue(Constants[0].GetConvertedValue(Operator, Field, FieldConfig, Filter));
+                        result.AppendValue(GetConstantValue(0));
                     else
                         result.FilterBuilder.Append(Constants[0].ToLinq(Filter));
                 }
             }
 
-            if (Operator.Kind != QueryFilterTokenKind.In && (Constants.Count == 0 || Constants[0].Kind != QueryFilterTokenKind.Null) && FieldConfig!.IsCheckForNotNull)
+            if (Operator.Kind != QueryFilterTokenKind.In && (Constants.Count == 0 || Constants[0].Kind != QueryFilterTokenKind.Null) && FieldConfig.IsCheckForNotNull)
                 result.FilterBuilder.Append(')');
         }
-
-        /// <inheritdoc/>
-        protected override IQueryFilterFieldConfig? GetFieldConfig() => FieldConfig;
     }
 }

src/CoreEx.Data/Querying/Expressions/QueryFilterStringFunctionExpression.cs

@@ -1,15 +1,18 @@
 // Copyright (c) Avanade. Licensed under the MIT License. See https://github.com/Avanade/CoreEx
 
+using System;
+
 namespace CoreEx.Data.Querying.Expressions
 {
     /// <summary>
-    /// Represents a query filter <see cref="QueryFilterTokenKind.StringFunction"/> expression.
+    /// Represents a query filter <see cref="QueryFilterTokenKind.StringFunctions"/> expression.
     /// </summary>
     /// <param name="parser">The <see cref="QueryFilterParser"/>.</param>
     /// <param name="filter">The originating query filter.</param>
     /// <param name="function">The function <see cref="QueryFilterOperatorExpression"/></param>
-    public sealed class QueryFilterStringFunctionExpression(QueryFilterParser parser, string filter, QueryFilterToken function) : QueryFilterExpressionBase(parser, filter, function)
+    public sealed class QueryFilterStringFunctionExpression(QueryFilterParser parser, string filter, QueryFilterToken function) : QueryFilterExpressionBase(parser, filter, function), IQueryFilterFieldStatementExpression
     {
+        private IQueryFilterFieldConfig? _fieldConfig;
         private bool _isComplete;
 
         /// <summary>
@@ -20,7 +23,7 @@ public sealed class QueryFilterStringFunctionExpression(QueryFilterParser parser
         /// <summary>
         /// Gets the <see cref="IQueryFilterFieldConfig"/>.
         /// </summary>
-        public IQueryFilterFieldConfig? FieldConfig { get; private set; }
+        public IQueryFilterFieldConfig FieldConfig => _fieldConfig ?? throw new InvalidOperationException($"{nameof(FieldConfig)} must be set before it can be accessed.");
 
         /// <summary>
         /// Gets the field <see cref="QueryFilterToken"/>.
@@ -55,9 +58,10 @@ protected override void AddToken(int index, QueryFilterToken token)
 
                 case 2:
                     Field = token;
-                    FieldConfig = Parser.GetFieldConfig(Field, Filter);
+                    _fieldConfig = Parser.GetFieldConfig(Field, Filter);
 
-                    if (!FieldConfig!.SupportedKinds.HasFlag(Function.Kind))
+                    var op = (QueryFilterOperator)(int)Function.Kind;
+                    if (!FieldConfig.Operators.HasFlag(op))
                         throw new QueryFilterParserException($"Field '{Field.GetRawToken(Filter).ToString()}' does not support the '{Function.GetRawToken(Filter).ToString()}' function.");
 
                     break;
@@ -72,7 +76,7 @@ protected override void AddToken(int index, QueryFilterToken token)
                     if (token.Kind == QueryFilterTokenKind.Null)
                         throw new QueryFilterParserException($"A '{Function.GetRawToken(Filter).ToString()}' function references a null constant which is not supported.");
 
-                    FieldConfig!.ValidateConstant(Field, token, Filter);
+                    FieldConfig.ValidateConstant(Field, token, Filter);
                     Constant = token;
                     break;
 
@@ -85,12 +89,16 @@ protected override void AddToken(int index, QueryFilterToken token)
             }
         }
 
+        /// <summary>
+        /// Gets the converted <see cref="Constant"/> value.
+        /// </summary>
+        /// <returns>The converted value.</returns>
+        public object GetConstantValue() => Constant!.GetConvertedValue(Function, Field, FieldConfig, Filter);
+
         /// <inheritdoc/>
         public override void WriteToResult(QueryFilterParserResult result)
         {
-            result.Fields.Add(FieldConfig!.Field);
-
-            if (FieldConfig!.IsCheckForNotNull)
+            if (FieldConfig.IsCheckForNotNull)
             {
                 result.Append('(');
                 result.FilterBuilder.Append(FieldConfig.Model);
@@ -107,11 +115,8 @@ public override void WriteToResult(QueryFilterParserResult result)
             result.AppendValue(Constant.GetConvertedValue(Function, Field, FieldConfig, Filter));
             result.FilterBuilder.Append(')');
 
-            if (FieldConfig!.IsCheckForNotNull)
+            if (FieldConfig.IsCheckForNotNull)
                 result.FilterBuilder.Append(')');
         }
-
-        /// <inheritdoc/>
-        protected override IQueryFilterFieldConfig? GetFieldConfig() => FieldConfig;
     }
 }

src/CoreEx.Data/Querying/QueryFilterToken.cs → src/CoreEx.Data/Querying/Expressions/QueryFilterToken.cs

@@ -2,7 +2,7 @@
 
 using System;
 
-namespace CoreEx.Data.Querying
+namespace CoreEx.Data.Querying.Expressions
 {
     /// <summary>
     /// Represents a <see cref="QueryFilterParser"/> token.

src/CoreEx.Data/Querying/QueryFilterTokenKind.cs → src/CoreEx.Data/Querying/Expressions/QueryFilterTokenKind.cs

@@ -2,7 +2,7 @@
 
 using System;
 
-namespace CoreEx.Data.Querying
+namespace CoreEx.Data.Querying.Expressions
 {
     /// <summary>
     /// Provides the <see cref="QueryFilterToken"/> kind.
@@ -128,12 +128,12 @@ public enum QueryFilterTokenKind
         /// <summary>
         /// An expression operator token.
         /// </summary>
-        Operator = Equal | NotEqual | GreaterThan | GreaterThanOrEqual | LessThan | LessThanOrEqual | In,
+        ComparisonOperators = Equal | NotEqual | GreaterThan | GreaterThanOrEqual | LessThan | LessThanOrEqual | In,
 
         /// <summary>
         /// An expression equality operator token.
         /// </summary>
-        EqualityOperator = Equal | NotEqual | In,
+        EqualityOperators = Equal | NotEqual | In,
 
         /// <summary>
         /// An expression constant token.
@@ -153,11 +153,11 @@ public enum QueryFilterTokenKind
         /// <summary>
         /// A string oriented function-based operator.
         /// </summary>
-        StringFunction = StartsWith | EndsWith | Contains,
+        StringFunctions = StartsWith | EndsWith | Contains,
 
         /// <summary>
         /// All string oriented operators.
         /// </summary>
-        AllStringOperators = Operator | StringFunction
+        AllStringOperators = ComparisonOperators | StringFunctions
     }
 }