Common.QueryKit 1.0.1

Common.QueryKit

Common.QueryKit is a lightweight, EF Core–safe query composition library for dynamic filtering, sorting, and paging built on top of IQueryable.

It is designed for enterprise-grade ASP.NET Core applications where:

• Queries must remain SQL-translatable
• Performance and index usage matter
• Dynamic LINQ and string-based hacks are avoided

Ideal for ERP systems, School Management Systems, Admin Panels, and Reporting APIs.

✨ Core Features (Detailed)

✅ EF Core SQL–Translatable Expressions

All queries are built using expression trees, ensuring:

• Full SQL translation by EF Core
• No client-side evaluation
• Database indexes remain effective

✅ Nested Property Filtering

Filter using navigation properties via dot notation.

Property = "Class.Name"

EF Core automatically translates navigation access into proper SQL joins.

Example:

new FilterRule
{
    Property = "Class.Name",
    Operator = FilterOperator.Contains,
    Value = "Grade"
}

✅ Multi-Column Sorting

Supports multiple sorting rules with preserved order.

options.Sorts.Add(new SortRule { Property = "Class.Name" });
options.Sorts.Add(new SortRule { Property = "CreatedDate", Descending = true });

Equivalent SQL:

ORDER BY Class.Name ASC, CreatedDate DESC

✅ Strongly-Typed Filter Operators

Filter behavior is defined using an enum, ensuring clarity and safety.

FilterOperator.Contains
FilterOperator.Equals
FilterOperator.Between

✅ Range Filters (Between)

Perfect for date and numeric ranges.

new FilterRule
{
    Property = "CreatedDate",
    Operator = FilterOperator.Between,
    From = DateTime.Today.AddDays(-30),
    To = DateTime.Today
}

✅ Null-Safe Comparisons

Safely compare nullable fields.

new FilterRule
{
    Property = "DeletedDate",
    Operator = FilterOperator.Equals,
    Value = null
}

✅ Allowed Property Whitelist (Security)

Restrict filtering and sorting to approved fields.

var whitelist = new PropertyWhitelist(new[]
{
    "Name",
    "Class.Name",
    "CreatedDate"
});

Prevents:

• Invalid property access
• Accidental data exposure
• User-driven property injection

✅ Pagination Helpers

Clean and predictable paging.

query.PageBy(page: 2, size: 25);

Produces SQL OFFSET/FETCH pagination.

📦 Installation

dotnet add package Common.QueryKit

🚀 Quick Start

Entity Example

public class Student
{
    public string Name { get; set; }
    public Class Class { get; set; }
    public DateTime CreatedDate { get; set; }
}

Build Query Options

var options = new QueryOptions
{
    Page = 1,
    PageSize = 20
};

options.Filters.Add(new FilterRule
{
    Property = "Class.Name",
    Operator = FilterOperator.Contains,
    Value = "Grade"
});

options.Sorts.Add(new SortRule
{
    Property = "CreatedDate",
    Descending = true
});

Apply to IQueryable

var result = db.Students
    .ApplyFilters(options.Filters)
    .ApplySorting(options.Sorts)
    .PageBy(options.Page, options.PageSize)
    .ToList();

🔎 Supported Filter Operators

🧠 Design Philosophy

• Expressions over strings
• SQL first, not in-memory
• Explicit over implicit
• Predictable performance
• Small, composable API

🧩 When to Use

✅ Recommended

• Generic list screens
• Admin dashboards
• Search APIs
• Reporting modules

❌ Avoid

• Complex domain logic
• Aggregate-heavy queries

📌 Requirements

• .NET 10
• Entity Framework Core

🧑‍💻 Author

Muammar Siddiqui
Innovador Solutions

📄 License

MIT License