Merged PR 8171: Refactored the Result and also added functional exten…

…sions + Documentation + nuget updates
BridgingIT-GmbH · Oct 29, 2024 · 8aa6b68 · 8aa6b68
1 parent 8912ff1
commit 8aa6b68
Show file tree

Hide file tree

Showing 233 changed files with 14,540 additions and 2,261 deletions.
diff --git a/BridgingIT.DevKit.sln b/BridgingIT.DevKit.sln
@@ -331,6 +331,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "WeatherForecast.EndToEndTes
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Domain.CodeGen", "src\Domain.CodeGen\Domain.CodeGen.csproj", "{6AE1B48F-144D-4179-8C6D-4C6E7AF7D655}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Common.Results", "src\Common.Results\Common.Results.csproj", "{39918CB1-7AFD-4A93-8A4C-6A04B70AD13D}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -701,6 +703,10 @@ Global
 		{6AE1B48F-144D-4179-8C6D-4C6E7AF7D655}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{6AE1B48F-144D-4179-8C6D-4C6E7AF7D655}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{6AE1B48F-144D-4179-8C6D-4C6E7AF7D655}.Release|Any CPU.Build.0 = Release|Any CPU
+		{39918CB1-7AFD-4A93-8A4C-6A04B70AD13D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{39918CB1-7AFD-4A93-8A4C-6A04B70AD13D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{39918CB1-7AFD-4A93-8A4C-6A04B70AD13D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{39918CB1-7AFD-4A93-8A4C-6A04B70AD13D}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -826,6 +832,7 @@ Global
 		{C4B99049-B2E5-4DF1-B962-EE8D1E8DF01A} = {93C61A82-E3AB-41A5-AC73-413F5B7B5548}
 		{5F24F274-B83C-4947-A878-B02C81061876} = {D2F9AF42-30B2-475B-807B-73BD00EAA795}
 		{6AE1B48F-144D-4179-8C6D-4C6E7AF7D655} = {4C01229A-6BA1-4185-BF3E-E4D1E58B82F9}
+		{39918CB1-7AFD-4A93-8A4C-6A04B70AD13D} = {862110B7-95CF-40ED-8DF8-F6E4FC3A5900}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {71C09054-DA91-4896-83AE-024F259D5330}

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -25,7 +25,7 @@
     <PackageVersion Include="BenchmarkDotNet" Version="0.14.0" />
     <PackageVersion Include="Bogus" Version="35.6.1" />
     <PackageVersion Include="Dapper" Version="2.1.44" />
-    <PackageVersion Include="DotPulsar" Version="3.3.2" />
+    <PackageVersion Include="DotPulsar" Version="3.4.0" />
     <PackageVersion Include="Dumpify" Version="0.6.6" />
     <PackageVersion Include="Ensure.That" Version="10.1.0" />
     <PackageVersion Include="FluentAssertions.Web" Version="1.5.0" />
@@ -47,7 +47,7 @@
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.10" />
     <PackageVersion Include="Microsoft.AspNetCore.SignalR.Client" Version="8.0.10" />
     <PackageVersion Include="Microsoft.Azure.AppConfiguration.AspNetCore" Version="8.0.0" />
-    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.44.1" />
+    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.45.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.11.0" />
     <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.2.2" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.10" />
@@ -81,7 +81,7 @@
     <PackageVersion Include="Microsoft.Playwright" Version="1.48.0" />
     <PackageVersion Include="Microsoft.Playwright.NUnit" Version="1.48.0" />
     <PackageVersion Include="MinVer" Version="6.0.0" />
-    <PackageVersion Include="MudBlazor" Version="7.13.0" />
+    <PackageVersion Include="MudBlazor" Version="7.14.0" />
     <PackageVersion Include="NBuilder" Version="6.1.0" />
     <PackageVersion Include="NSubstitute" Version="5.1.0" />
     <PackageVersion Include="NSwag.ApiDescription.Client" Version="14.1.0" />

diff --git a/docs/features-filtering.md b/docs/features-filtering.md
@@ -14,7 +14,8 @@
 * [Complex Filter Examples](#complex-filter-examples)
 * [Appendix A: Angular Usage Guide](#appendix-a-angular-usage-guide)
 * [Appendix B: Flow Diagram](#appendix-b-flow-diagram)
-* [Appendix C: Disclaimer](#appendix-c-disclaimer)
+* [Appendix C: Filter Model Builder](#appendix-c-filter-model-builder)
+* [Appendix D: Disclaimer](#appendix-c-disclaimer)
 
 <!-- TOC -->
 
@@ -27,9 +28,9 @@
 
 ```mermaid
 graph LR
-    R[Client Request]-->|filter|E[Endpoint]-->|filter|Q[QueryHandler]-->|filter|P[Repository]
+    R[Client Request]-->|filter|E[API Endpoint]-->|filter|Q[QueryHandler or Service]-->|filter|P[Repository]
     P-->|query|D[(Database)]
-    P-.->|PagedResult|R
+    P-.->|Result_IEnumerable_T|R
 ```
 
 ### Challenges
@@ -56,41 +57,48 @@ graph LR
 > The Filtering feature solves these challenges by providing:
 
 1. **Unified Query Interface**
-  - Single, consistent way to express complex queries
-  - Works across different entity types
-  - Supports both simple and complex filtering scenarios
-  - No need to create custom endpoints for each query scenario╬
+
+- Single, consistent way to express complex queries
+- Works across different entity types
+- Supports both simple and complex filtering scenarios
+- No need to create custom endpoints for each query scenario╬
 
 2. **Type-Safe Implementation**
-  - Strongly-typed models for both client and server (Swagger)
-  - Compile-time validation of filter structures
-  - Clear contract between frontend and backend (FilterModel)
+
+- Strongly-typed models for both client and server (Swagger)
+- Compile-time validation of filter structures
+- Clear contract between frontend and backend (FilterModel)
 
 3. **Flexible Architecture**
-  - Extensible design for more custom filter types [TODO]
-  - Support for additional domain-specific specifications
-  - Easy integration with existing repositories (FindOptions)
+
+- Extensible design for more custom filter types [TODO]
+- Support for additional domain-specific specifications
+- Easy integration with existing repositories (FindOptions)
 
 4. **Performance Optimization**
-  - Built-in pagination support
-  - Efficient query building (Expressions)
-  - Optimized database access through specifications
+
+- Built-in pagination support
+- Efficient query building (Expressions)
+- Optimized database access through specifications
 
 ### Use Cases
 
 1. **Data Grids, Tables and Lists**
-  - Dynamic column filtering
-  - Multi-column sorting
-  - Server-side pagination
+
+- Dynamic column filtering
+- Multi-column sorting
+- Server-side pagination
 
 2. **Search Interfaces**
-  - Full-text search across multiple fields
-  - Combined filters (date ranges, categories, status)
-  - Related entity filtering
+
+- Full-text search across multiple fields
+- Combined filters (date ranges, categories, status)
+- Related entity filtering
 
 3. **Lookup lists**
-  - Dynamic data loading for select components
-  - Type-ahead/autocomplete requests
+
+- Dynamic data loading for select components
+- Type-ahead/autocomplete requests
 
 ## Request Flow Diagram
 
@@ -397,24 +405,28 @@ The following considerations apply to HTTP POST requests:
 ## Best Practices
 
 1. **Request Method Selection**
-  - Use GET for simple queries and basic filtering
-  - Use POST for complex filters or when URL length might be an issue
-  - Consider using POST when sending sensitive filter data
+
+- Use GET for simple queries and basic filtering
+- Use POST for complex filters or when URL length might be an issue
+- Consider using POST when sending sensitive filter data
 
 2. **Performance Considerations**
-  - Keep page sizes reasonable (recommended: 10-50 items)
-  - Use includes selectively to prevent excessive data loading
-  - Consider adding indexes for commonly filtered fields
+
+- Keep page sizes reasonable (recommended: 10-50 items)
+- Use includes selectively to prevent excessive data loading
+- Consider adding indexes for commonly filtered fields
 
 3. **Error Handling**
-  - Always check the `success` property in responses
-  - Handle error messages appropriately in your client application
-  - Log error details for debugging purposes
+
+- Always check the `success` property in responses
+- Handle error messages appropriately in your client application
+- Log error details for debugging purposes
 
 4. **Security**
-  - Validate all filter inputs server-side
-  - Implement appropriate rate limiting
-  - Consider adding pagination limits to prevent DOS attacks
+
+- Validate all filter inputs server-side
+- Implement appropriate rate limiting
+- Consider adding pagination limits to prevent DOS attacks
 
 # Standard Filter Operators
 
@@ -1578,7 +1590,35 @@ graph TD
     H -->|PagedResult| I[Response]
 ```
 
-# Appendix C: Disclaimer
+# Appendix C: Filter Model Builder
+
+> Build a Filter Model using Fluent C# syntax.
+
+Can be used in a Blazor or server side environment to construct complex filters.
+
+```csharp
+var filterModel = FilterModelBuilder.For<PersonStub>()
+      .SetPaging(2, PageSize.Large) // Fluent paging setup
+      .AddFilter(p => p.Age, FilterOperator.GreaterThan, 25) // Age > 25
+      .AddFilter(p => p.FirstName, FilterOperator.Contains, "A") // FirstName contains "A"
+      .AddFilter(p => p.Locations,
+          FilterOperator.Any, b => b
+              .AddFilter(loc => loc.City, FilterOperator.Equal, "Berlin")
+              .AddFilter(loc => loc.PostalCode, FilterOperator.StartsWith, "100")) // Any location with City = New York or ZipCode starts with "100"
+      .AddCustomFilter(FilterCustomType.FullTextSearch)
+      .AddParameter("searchTerm", "John")
+      .AddParameter("fields", new[] { "FirstName", "LastName" }).Done()
+      .AddOrdering(p => p.LastName, OrderDirection.Descending) // Order by LastName Descending
+      .AddOrdering(p => p.FirstName, OrderDirection.Ascending) // Then order by FirstName Ascending
+      .AddInclude(p => p.Locations)
+      .Build();
+
+filterModel.Page.ShouldBe(2);
+filterModel.PageSize.ShouldBe((int)PageSize.Large);
+// etc.
+```
+
+# Appendix D: Disclaimer
 
 > This Filtering feature described here is designed to provide a pragmatic, flexible filtering
 > solution for