Superfilter 1.0.1

Superfilter

Superfilter is a lightweight C# library for applying dynamic filtering and sorting on IQueryable sources. It maps textual filter criteria to strongly typed expressions, making it easy to expose flexible query capabilities in web APIs or other data-driven applications.

🎯 Framework Support: .NET 8.0 and .NET 9.0

Features

• 🚀 Fluent IQueryable Extensions - Natural integration with LINQ queries
• 📄 Pagination Support - Built-in pagination with IHasPagination interface
• Map filter keys to entity properties with lambda selectors and type inference
• Supports nested navigation properties (e.g., x => x.Car.Brand.Name)
• Validates required filters with configurable error handling
• Built‑in operators: Equals, LessThan, GreaterThan, StartsWith, Contains, IsEqualToYear, IsEqualToYearAndMonth, IsEqualToFullDate
• Integrated sorting functionality
• Works seamlessly with Entity Framework and LINQ-to-Objects
• Type-safe expression building with proper type inference
• IntelliSense support with compile-time type checking

Getting Started

🚀 Fluent IQueryable Extensions

using Superfilter;

// In a controller or service method
[HttpPost("search")]
public async Task<IActionResult> SearchUsers([FromBody] UserSearchRequest request)
{
    // Apply filters using fluent IQueryable extensions
    var result = await _context.Users
        .WithSuperfilter()                               // Start fluent configuration
        .MapProperty(u => u.Id)                          // IntelliSense support
        .MapProperty(u => u.Car.Brand.Name)              // Navigation properties work naturally
        .MapProperty("name", u => u.Name)                // Explicit key usage
        .MapRequiredProperty(u => u.MoneyAmount)         // Require this property to be included in filters
        .WithFilters(request.Filters)                    // Apply dynamic filters - returns filtered IQueryable
        .ToListAsync();
    
    return Ok(result);
}

With Sorting

// Apply both filters and sorting
var result = await _context.Users
    .WithSuperfilter()
    .MapProperty(u => u.Name)
    .MapProperty(u => u.Age)
    .MapProperty(u => u.MoneyAmount)
    .WithFilters(request.Filters)                        // Apply filters
    .ApplySorting(request.Sorts)                         // Apply sorting
    .ToListAsync();

With Pagination

// Using IHasPagination interface for pagination support
public class UserSearchRequest : IHasPagination, IHasFilters
{
    public int PageNumber { get; set; } = 1;
    public int PageSize { get; set; } = 10;
    public List<FilterCriterion> Filters { get; set; } = new();
}

// Apply filters with pagination
[HttpPost("search")]
public async Task<IActionResult> SearchUsers([FromBody] UserSearchRequest request)
{
    var query = _context.Users
        .WithSuperfilter()
        .MapProperty(u => u.Name)
        .MapProperty(u => u.Age)
        .WithFilters(request.Filters);

    // Apply pagination using Skip and Take
    var skip = (request.PageNumber - 1) * request.PageSize;
    var result = await query
        .Skip(skip)
        .Take(request.PageSize)
        .ToListAsync();
    
    return Ok(result);
}

API Reference

Core Extension Methods

Property Mapping Examples

// MapProperty handles all types automatically with type inference
var result = _context.Users
    .WithSuperfilter()
    .MapProperty(u => u.Name)                    // string - auto key: "User.Name"
    .MapProperty(u => u.Id)                      // int - auto key: "User.Id"
    .MapProperty(u => u.BornDate)                // DateTime? - auto key: "User.BornDate"
    .MapProperty(u => u.MoneyAmount)             // int - auto key: "User.MoneyAmount"
    .MapProperty(u => u.IsActive)                // bool - auto key: "User.IsActive"
    .MapProperty(u => u.Car.Brand.Name)          // nested string - auto key: "User.Car.Brand.Name"
    .MapProperty("customKey", u => u.Email)      // explicit key
    .WithFilters(request.Filters)
    .ToList();

Error Handling

// Configure error handling strategy
var result = _context.Users
    .WithSuperfilter()
    .WithErrorStrategy(OnErrorStrategy.Ignore)   // Or OnErrorStrategy.ThrowException
    .MapProperty(u => u.Name)
    .WithFilters(request.Filters)
    .ToList();

Static Filters

// Add static filters (applied in addition to dynamic filters)
var result = _context.Users
    .WithSuperfilter()
    .MapProperty(u => u.Name)
    .MapProperty(u => u.IsActive)
    .AddStaticFilter("User.IsActive", Operator.Equals, "true")  // Always filter active users
    .WithFilters(request.Filters)                               // Plus dynamic filters from client
    .ToList();

Supported Operators

Note on Property Mapping

The MapProperty method is available in two forms:

1. MapProperty(key, selector) - Explicit key definition for the property mapping
2. MapProperty(selector) - Auto-generated key based on property path

Security Note: When using auto-generated keys (MapProperty(selector)), consider whether exposing your data model schema to the frontend is acceptable for your use case. This approach might reveal internal details of your data model structure.

Benchmarks show better results with Superfilter

<img width="1006" height="251" alt="image" src="https://github.com/user-attachments/assets/0dc5d072-72f1-4734-b32c-c132ffab9c02" />

Installation

dotnet add package Superfilter --version 1.0.1

Links

• 📦 NuGet Package - Install from NuGet.org
• 🐙 GitHub Repository - Source code and issues
• 📖 Ibradev.fr/Superfilter - Project's page

Project Structure

Superfilter/
├── SuperFilter/           # Core library implementation
│   ├── Extensions/        # IQueryable extensions
│   ├── Constants/         # Operator definitions
│   └── ExpressionBuilders/# Type-specific expression builders
├── Database/              # EF Core context and domain models
└── Tests/                 # Comprehensive test suite

Running Tests

# Run all tests
dotnet test

# Run tests with detailed output
dotnet test --verbosity normal

# Exclude PostgreSQL integration tests (require Docker)
dotnet test --filter "FullyQualifiedName!~PostgreSqlIntegrationTests"

Key Benefits

• ✅ Fluent Integration with existing IQueryable workflows
• ✅ Type Safety with compile-time checking and IntelliSense support
• ✅ Zero Configuration - works out of the box with sensible defaults
• ✅ Natural Navigation Properties support without complex setup
• ✅ Flexible Filtering - combine static and dynamic filters seamlessly
• ✅ Entity Framework Ready - optimized for EF Core query generation

License

This project is licensed under the MIT License.