Common.QueryKit 1.0.8

Common.QueryKit

Lightweight • EF Core–safe • Dynamic query composition library
Build powerful, fully SQL‑translatable filters, sorting & paging on IQueryable<T>.

Designed for enterprise‑grade ASP.NET Core applications:
ERP Systems • School Management • Admin Panels • Reporting APIs

✨ Highlights

• 100% SQL‑translatable (no client‑side evaluation)
• Supports nested properties
  ("Class.GradeLevel", "Address.City.Country")
• Strongly‑typed FilterOperator enum (no magic strings)
• Multiple IN filters (IDs, enums, GUIDs, numbers)
• Dedicated CONTAINS filters (safe string search)
• Multi‑column sorting with direction control
• Range filtering (Between), null‑safe comparisons
• Property whitelisting for API security
• Clean and predictable pagination
• Explicit count‑safe API (no paging leakage)
• Minimal footprint, high performance

📦 Installation

dotnet add package Common.QueryKit

🚀 Quick Start

var request = new QueryRequest
{
    Filters =
    [
        new() 
        { 
            Property = "BirthDate",
            Operator = FilterOperator.Between,
            From = new DateTime(2000, 1, 1),
            To   = new DateTime(2010, 12, 31)
        }
    ],

    IdFilters =
    {
        ["Status"] = new object[] { "Active", "Pending" },
        ["RoleId"] = new object[] 
        { 
            Guid.Parse("7bfa0c12-9a44-4d7e-b6a4-3fcd98c7d219")
        }
    },

    ContainsFilters =
    {
        ["FullName"] = "john",
        ["Email"] = "@gmail"
    },

    Sorts =
    [
        new() { Property = "Class.Name" },
        new() { Property = "CreatedAt", Descending = true }
    ],

    Page = 1,
    PageSize = 25
};

📥 Fetch paged data

var students = await dbContext.Students
    .Apply(request)
    .ToListAsync();

🔢 Fetch total count (safe – no paging)

var totalCount = await dbContext.Students
    .ApplyForCount(request)
    .CountAsync();

🔧 Filter Operators

FilterOperator enum

public enum FilterOperator
{
    Equals,
    Contains,
    StartsWith,
    EndsWith,
    GreaterThan,
    LessThan,
    Between,
    In
}

📚 Operator Reference

🧠 Filter Design Philosophy

✔ IN Filters

Used for IDs, GUIDs, enums, numeric sets.

InFilters =
{
    ["Id"] = new object[] { 1, 2, 3 },
    ["UserId"] = new object[] 
    { 
        "550e8400-e29b-41d4-a716-446655440000"
    }
}

GUID strings are automatically normalized for EF Core compatibility.

✔ CONTAINS Filters

Used only for strings.
Never overloaded. Never guessed.

ContainsFilters =
{
    ["Name"] = "ali",
    ["Email"] = "@company.com"
}

This guarantees:

• Clean SQL translation
• No accidental full table scans
• Predictable intent

🛡️ Property Whitelisting (Strongly Recommended)

Prevent unsafe or unauthorized filtering.

var allowed = new PropertyWhitelist(
    "Id",
    "FullName",
    "Email",
    "BirthDate",
    "Class.Name",
    "Class.GradeLevel",
    "CreatedAt"
);

var students = dbContext.Students
    .Apply(request, allowed)
    .ToList();

⚙️ Requirements

• .NET 8.0+
• Entity Framework Core 8.0+

❤️ License

MIT License

Created by Muammar Siddiqui
Innovador Solutions

Common.QueryKit
Explicit. Safe. Fast.
Built for developers who care about correctness.