Release v4.1.0: cleanup and AggregateQueryModel fix

AggregateQueryModel no longer inherits GridifyQueryModel, removing
Page/PageSize/OrderBy from OpenAPI spec. Removed obsolete
ColumnDistinctValueQueryModel and its ColumnDistinctValuesAsync overload.
Renamed convertor to converter in FilterMapper.AddMap. Converted
MappingModel to record. Changed mapper store to FrozenDictionary for
thread safety. Bumped Gridify.EntityFramework from 2.17.2 to 2.19.0.
Added CLAUDE.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: HaikAsatryan

CLAUDE.md

@@ -0,0 +1,42 @@
+# Pandatech.GridifyExtensions - Claude Guide
+
+## What is this?
+
+A .NET NuGet library extending [Gridify](https://github.com/alirezanet/Gridify) with streamlined filtering, ordering,
+pagination, aggregation, and column distinct value queries for EF Core. Used by all PandaTech backend projects.
+
+## Architecture
+
+- Single library project: `src/GridifyExtensions/`
+- All extension methods live in `QueryableExtensions.cs`
+- `FilterMapper<T>` extends Gridify's `GridifyMapper<T>` with default ordering, encrypted columns, and fluent API
+- Mapper instances are discovered via reflection at startup (`AddGridify()`) and stored in a `FrozenDictionary`
+- `WebApplicationBuilderExtensions.cs` handles registration and Gridify global config
+
+## Key Files
+
+- `Extensions/QueryableExtensions.cs` - core extension methods (filtering, paging, distinct, aggregation)
+- `Extensions/WebApplicationBuilderExtensions.cs` - DI registration and mapper discovery
+- `Models/FilterMapper.cs` - base mapper class with default ordering and encrypted column tracking
+- `Models/GridifyQueryModel.cs` - paged query model (inherits Gridify's GridifyQuery)
+- `Models/GridifyCursoredQueryModel.cs` - cursor-based query model (standalone, not inheriting GridifyQuery)
+- `Models/AggregateQueryModel.cs` - aggregation model (standalone: Filter + PropertyName + AggregateType)
+- `Models/ColumnDistinctValueCursoredQueryModel.cs` - distinct value query (extends GridifyCursoredQueryModel)
+- `Operators/FlagOperator.cs` - custom `#hasFlag` bitwise operator
+
+## Code Patterns
+
+- `GridifyQueryModel` inherits from Gridify's `GridifyQuery` and overrides properties for validation
+- `GridifyCursoredQueryModel` and `AggregateQueryModel` are standalone (no Gridify base) with internal
+  `ToGridifyQueryModel()` for interop with Gridify's filtering
+- Encrypted columns tracked via `HashSet<string>` in FilterMapper; decryption happens client-side via `Func<byte[], string>`
+- String distinct values use smart ordering: nulls first, exact match, length, alphabetical
+- `PagedResponse<T>` and `CursoredResponse<T>` are records
+
+## Build
+
+```bash
+dotnet build src/GridifyExtensions/GridifyExtensions.csproj
+```
+
+Targets: net8.0, net9.0, net10.0

src/GridifyExtensions/Extensions/QueryableExtensions.cs

@@ -1,4 +1,5 @@
-using System.Collections;
+using System.Collections;
+using System.Collections.Frozen;
 using System.Linq.Expressions;
 using System.Text.RegularExpressions;
 using Gridify;
@@ -15,7 +16,7 @@ namespace GridifyExtensions.Extensions;
 /// </summary>
 public static class QueryableExtensions
 {
-   internal static Dictionary<Type, object> EntityGridifyMapperByType = [];
+   internal static FrozenDictionary<Type, object> EntityGridifyMapperByType = FrozenDictionary<Type, object>.Empty;
 
    // ---------- Core helpers ----------
    private static FilterMapper<TEntity> RequireMapper<TEntity>()
@@ -172,85 +173,6 @@ public static Task<CursoredResponse<TEntity>> FilterOrderAndGetCursoredAsync<TEn
                   .FilterOrderAndGetCursoredAsync(model, x => x, ct);
    }
 
-   /// <summary>
-   /// Get distinct values for a column (obsolete - use cursored version).
-   /// </summary>
-   [Obsolete("Use ColumnDistinctValueCursoredQueryModel instead.")]
-   public static async Task<PagedResponse<object>> ColumnDistinctValuesAsync<TEntity>(this IQueryable<TEntity> query,
-      ColumnDistinctValueQueryModel model,
-      Func<byte[], string>? decryptor = null,
-      CancellationToken ct = default)
-      where TEntity : class
-   {
-      var mapper = RequireMapper<TEntity>();
-
-      if (!mapper.IsEncrypted(model.PropertyName))
-      {
-         var result = await query
-                            .ApplyFiltering(model, mapper)
-                            .ApplySelect(model.PropertyName, mapper)
-                            .Distinct()
-                            .OrderBy(x => x)
-                            .GetPagedAsync(model, ct);
-         return result;
-      }
-
-      var encryptedQuery = query
-                           .ApplyFiltering(model, mapper)
-                           .ApplySelect(model.PropertyName, mapper);
-
-      if (string.IsNullOrWhiteSpace(model.Filter))
-      {
-         bool hasNullLike;
-         try
-         {
-            // ReSharper disable once ConditionIsAlwaysTrueOrFalseAccordingToNullableAPIContract
-            hasNullLike = await encryptedQuery.AnyAsync(x => x == null, ct);
-         }
-         catch (Exception ex) when (ex is InvalidOperationException or NotSupportedException)
-         {
-            hasNullLike = true;
-         }
-
-         return hasNullLike ? new PagedResponse<object>([null!], 1, 1, 1) : new PagedResponse<object>([], 1, 1, 0);
-      }
-
-      var selected = await encryptedQuery.FirstOrDefaultAsync(ct);
-      switch (selected)
-      {
-         case null:
-         case byte[] { Length: 0 }:
-            return new PagedResponse<object>([null!], 1, 1, 1);
-         case byte[] sb:
-            return decryptor == null
-               ? throw new KeyNotFoundException("Decryptor is required for encrypted properties.")
-               : new PagedResponse<object>([decryptor(sb)], 1, 1, 1);
-      }
-
-      if (selected is not IEnumerable<byte[]> seq)
-      {
-         throw new InvalidCastException("Encrypted selector did not return a byte[] or IEnumerable<byte[]> value.");
-      }
-
-      var ng = ((IEnumerable)seq).GetEnumerator();
-      using var ng1 = ng as IDisposable;
-
-      if (!ng.MoveNext())
-      {
-         return new PagedResponse<object>([null!], 1, 1, 1);
-      }
-
-      var firstObj = ng.Current;
-      if (firstObj is not byte[] first || first.Length == 0)
-      {
-         return new PagedResponse<object>([null!], 1, 1, 1);
-      }
-
-      return decryptor == null
-         ? throw new KeyNotFoundException("Decryptor is required for encrypted properties.")
-         : new PagedResponse<object>([decryptor(first)], 1, 1, 1);
-   }
-
    /// <summary>
    /// Get distinct values for a column with cursor pagination.
    /// </summary>
@@ -290,7 +212,7 @@ public static async Task<PagedResponse<object>> ColumnDistinctValuesAsync<TEntit
                              .ToListAsync(ct);
 
             return new CursoredResponse<object?>(data.Cast<object?>()
-                                                     .ToList(),
+                                                      .ToList(),
                model.PageSize);
          }
 
@@ -369,7 +291,7 @@ public static async Task<object> AggregateAsync<TEntity>(this IQueryable<TEntity
       where TEntity : class
    {
       var mapper = RequireMapper<TEntity>();
-      var filtered = query.ApplyFiltering(model, mapper)
+      var filtered = query.ApplyFiltering(model.ToGridifyQueryModel(), mapper)
                           .ApplySelect(model.PropertyName, mapper);
 
       return model.AggregateType switch
@@ -392,19 +314,19 @@ public static IEnumerable<MappingModel> GetMappings<TEntity>()
       var mapper = EntityGridifyMapperByType[typeof(TEntity)] as FilterMapper<TEntity>;
 
       return mapper!.GetCurrentMaps()
-                    .Select(x => new MappingModel
-                    {
-                       Name = x.From,
-                       Type = x.To.Body switch
+                    .Select(x => new MappingModel(
+                       x.From,
+                       x.To.Body switch
                        {
                           UnaryExpression ue => ue.Operand.Type.Name,
                           MethodCallExpression mc => (mc.Arguments.LastOrDefault() as LambdaExpression)?.ReturnType.Name
                                                      ?? x.To.Body.Type.Name,
                           _ => x.To.Body.Type.Name
-                       }
-                    });
+                       }));
    }
 
+   // ---------- Private helpers ----------
+
    private static Expression<Func<TEntity, string?>> EfStringSelector<TEntity>(string propertyName)
       where TEntity : class
    {
@@ -499,4 +421,4 @@ private static bool IsStringColumn<TEntity>(IQueryable<TEntity> query, FilterMap
       return infra.Instance.GetService<ICurrentDbContext>()
                   ?.Context;
    }
-}
+}

src/GridifyExtensions/Extensions/WebApplicationBuilderExtensions.cs

@@ -1,4 +1,5 @@
-using System.Reflection;
+using System.Collections.Frozen;
+using System.Reflection;
 using Gridify;
 using GridifyExtensions.Models;
 using GridifyExtensions.Operators;
@@ -39,6 +40,6 @@ private static void AddGridify(Assembly[] assemblies)
                                            .Select(x =>
                                               new KeyValuePair<Type, object>(x.BaseType!.GetGenericArguments()[0],
                                                  Activator.CreateInstance(x)!)))
-                   .ToDictionary(x => x.Key, x => x.Value);
+                   .ToFrozenDictionary(x => x.Key, x => x.Value);
    }
-}
+}

src/GridifyExtensions/GridifyExtensions.csproj

@@ -21,8 +21,8 @@
         <PackageIcon>pandatech.png</PackageIcon>
         <PackageReadmeFile>README.md</PackageReadmeFile>
 
-        <Version>4.0.2</Version>
-        <PackageReleaseNotes>Fixed aggregation rounding</PackageReleaseNotes>
+        <Version>4.1.0</Version>
+        <PackageReleaseNotes>AggregateQueryModel no longer inherits GridifyQueryModel, removing Page/PageSize/OrderBy from OpenAPI spec. Removed obsolete ColumnDistinctValueQueryModel and its ColumnDistinctValuesAsync overload. Renamed convertor to converter in FilterMapper.AddMap. Converted MappingModel to record. Changed mapper store to FrozenDictionary for thread safety.</PackageReleaseNotes>
 
         <!-- Build quality -->
         <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
@@ -50,7 +50,7 @@
     </ItemGroup>
 
     <ItemGroup>
-        <PackageReference Include="Gridify.EntityFramework" Version="2.17.2" />
+        <PackageReference Include="Gridify.EntityFramework" Version="2.19.0" />
         <PackageReference Include="Pandatech.Analyzers" Version="[2.1.0]" PrivateAssets="all" />
         <PackageReference Include="SonarAnalyzer.CSharp" Version="[10.19.0.132793]">
             <PrivateAssets>all</PrivateAssets>

src/GridifyExtensions/Models/AggregateQueryModel.cs

@@ -1,9 +1,21 @@
-using GridifyExtensions.Enums;
+using GridifyExtensions.Enums;
 
 namespace GridifyExtensions.Models;
 
-public class AggregateQueryModel : GridifyQueryModel
+public class AggregateQueryModel
 {
+   public string? Filter { get; set; }
    public required string PropertyName { get; set; }
    public required AggregateType AggregateType { get; set; }
-}
+
+   internal GridifyQueryModel ToGridifyQueryModel()
+   {
+      return new GridifyQueryModel
+      {
+         Page = 1,
+         PageSize = 1,
+         OrderBy = null,
+         Filter = Filter
+      };
+   }
+}

src/GridifyExtensions/Models/ColumnDistinctValueCursoredQueryModel.cs

@@ -1,6 +1,6 @@
-namespace GridifyExtensions.Models;
+namespace GridifyExtensions.Models;
 
 public class ColumnDistinctValueCursoredQueryModel : GridifyCursoredQueryModel
 {
    public required string PropertyName { get; set; }
-}
+}

src/GridifyExtensions/Models/ColumnDistinctValueQueryModel.cs

@@ -50,7 +50,7 @@ public IOrderThenBy AddDefaultOrderByDescending(string column)
 
    public IGridifyMapper<T> AddMap(string from,
       Expression<Func<T, object?>> to,
-      Func<string, object>? convertor = null,
+      Func<string, object>? converter = null,
       bool overrideIfExists = true,
       bool isEncrypted = false)
    {
@@ -59,13 +59,12 @@ public IGridifyMapper<T> AddMap(string from,
          _encryptedColumns.Add(from);
       }
 
-
-      return base.AddMap(from, to, convertor, overrideIfExists);
+      return base.AddMap(from, to, converter, overrideIfExists);
    }
 
    public IGridifyMapper<T> AddMap(string from,
       Expression<Func<T, int, object?>> to,
-      Func<string, object>? convertor = null,
+      Func<string, object>? converter = null,
       bool overrideIfExists = true,
       bool isEncrypted = false)
    {
@@ -74,7 +73,6 @@ public IGridifyMapper<T> AddMap(string from,
          _encryptedColumns.Add(from);
       }
 
-
-      return base.AddMap(from, to, convertor, overrideIfExists);
+      return base.AddMap(from, to, converter, overrideIfExists);
    }
 }

src/GridifyExtensions/Models/FilterMapper.cs

@@ -1,7 +1,3 @@
-namespace GridifyExtensions.Models;
+namespace GridifyExtensions.Models;
 
-public class MappingModel
-{
-   public string Name { get; set; } = string.Empty;
-   public string? Type { get; set; } = string.Empty;
-}
+public record MappingModel(string Name, string? Type);

src/GridifyExtensions/Models/MappingModel.cs

@@ -9,9 +9,9 @@
 
     <ItemGroup>
         <PackageReference Include="EFCore.NamingConventions" Version="10.0.1" />
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.2" />
-        <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.0"/>
-        <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.0"/>
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.5" />
+        <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1" />
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.7" />
     </ItemGroup>
 
     <ItemGroup>