Dkd.Infra.Filter 1.9.0

Dkd.Infra.Filter

پکیج فیلتر پویای JSON — تبدیل فیلترهای پیچیده‌ی JSON (خروجی کتابخانه‌ی فرانت‌اند) به Expression و اعمال آن‌ها روی IQueryable قبل از صفحه‌بندی (Paging). پشتیبانی از عملگرهای متنوع، گروه‌های تو در تو (AND/OR) و اعتبارسنجی امنیتی فیلدها.

• TargetFramework: net8.0
• نسخه‌ی فعلی: 1.8.1
• لایسنس: MIT
• Namespace اصلی: Dkd.Infra.Filter

معرفی

این پکیج برای صفحه‌بندی‌های پویا (Dynamic Paging) طراحی شده است؛ جایی که کاربر فرانت‌اند می‌خواهد فیلترهای دلخواه بسازد. قرارداد JSON دقیقاً همان خروجی پکیج فرانت‌اند @dkd/filter (UniversalFilter) است.

مزایا:

1. قدرت‌مندی: عملگرهای contains، between، >، <، isempty و …
2. گروه‌بندی: گروه‌های تو در تو با AND/OR (بازگشتی).
3. امنیت: امکان محدودکردن فیلدهای مجاز (allowedFields).
4. سادگی: با یک متد ApplyJsonFilter همه‌چیز انجام می‌شود.

امکانات اصلی

• اعتبارسنجی JSON فیلتر با FilterJsonValidator (ساختار، عملگرها و مقادیر).
• ساخت Expression با FilterExpressionBuilder (با Reflection و تبدیل خودکار نوع).
• اعمال روی IQueryable با QueryableFilterExtensions (ApplyJsonFilter / ApplyFilter).
• پشتیبانی از مسیر نقطه‌ای (a.b.c) برای پراپرتی‌های تو در تو.
• خطای فارسی با BusinessException (HTTP 400) هنگام ورودی نامعتبر.
• فیلتر خالی/null: بدون تغییر کوئری.

قرارداد JSON

{
  "combinator": "AND",
  "rules": [
    { "field": "name", "operator": "contains", "value": "علی" },
    { "field": "salary", "operator": "between", "value": 2000, "valueTo": 4000 },
    { "combinator": "OR", "rules": [ { "field": "status", "operator": "=", "value": true } ] }
  ]
}

سمانتیک تاریخ بر اساس «روز» است (مطابق فرانت‌اند): = → بازه [روز, روز+۱) | < → قبل از روز | > → از روز بعد | between → [از, تا+۱).

ساختار پروژه

Dkd.Infra.Filter/
├── FilterOperator.cs                       # enum عملگرها + Parse از رشته JSON
├── Dtos/FilterGroupDto.cs                  # قرارداد JSON (گروه + آیتم بازگشتی)
├── Validation/FilterJsonValidator.cs       # اعتبارسنجی ساختار، عملگر و مقادیر
├── Expressions/FilterExpressionBuilder.cs  # ساخت Expression tree
└── Extensions/QueryableFilterExtensions.cs # ApplyJsonFilter / ApplyFilter

کلاس‌های کلیدی

روش استفاده

using Dkd.Infra.Filter.Extensions;

public async Task<ServiceResult<PageModelDto<UserDto>>> GetPagedAsync(
    UserSearchPagedDto search, CancellationToken ct = default)
{
    var query = _db.Users.AsNoTracking()
        .ApplyJsonFilter(search.Filter);            // اعتبارسنجی + اعمال فیلتر

    var total = await query.CountAsync(ct);
    var items = await query
        .OrderBy(x => x.Id)
        .Skip(search.SkipRows())
        .Take(search.PageSize)
        .ToListAsync(ct);

    return ServiceResult(new PageModelDto<UserDto>(search.PageIndex, search.PageSize, total, items));
}

محدود کردن فیلدهای مجاز (اختیاری — امنیت):

query.ApplyJsonFilter(search.Filter, allowedFields: ["id", "name", "account", "status"]);

وابستگی‌ها

• Dkd.Infra.Core (برای BusinessException و JsonHelper)
• System.Text.Json
• بدون پکیج خارجی جدید.

اطلاعات تکمیلی

• ورژن: 1.8.1
• پیشوند پکیج: Dkd.Infra