PK.EntityFramework.Extensions.GetItems 1.0.4

PK.EntityFramework.Extensions.GetItems

A simple, expressive way to paginate, filter, and sort data in Entity Framework. Works great with APIs and directly in your business logic.

Installation

dotnet add package PK.EntityFramework.Extensions.GetItems

Quick Start

// Define your filterable properties
public enum BookPropertyNames { Name, PublishedOn, AuthorName }

// Map enum values to property paths
static string[] PropertyNameMapper(BookPropertyNames field) => field switch
{
    BookPropertyNames.Name => [nameof(Book.Name)],
    BookPropertyNames.PublishedOn => [nameof(Book.PublishedOn)],
    BookPropertyNames.AuthorName => [nameof(Book.Author), nameof(Author.Name)],
    _ => throw new ArgumentOutOfRangeException()
};

// Create a request
var request = new BaseGetItemsRequest<BookPropertyNames, Guid>
{
    Page = 1,
    Count = 10,
    Filters = [
        new() { Field = BookPropertyNames.Name, Operator = FilterOperatorEnum.Contains, Value = "Great" }
    ],
    Sort = [
        new() { Field = BookPropertyNames.PublishedOn, Order = OrderByEnum.Descending }
    ]
};

// Execute with IDbContextFactory
var result = await dbContextFactory.GetItems(
    ctx => ctx.Books.AsQueryable(),
    request,
    b => b.Id,
    PropertyNameMapper
);

// Or directly on IQueryable (Cheap/None pagination modes only)
var result = await dbContext.Books.GetItems(request, b => b.Id, PropertyNameMapper);

// result.Items, result.TotalCount, result.Page, result.TotalPages

Features

• Pagination — Three modes: Expensive (full count), Cheap (has next page), None
• Filtering — Rich operators with AND/OR logic and nested filters
• Sorting — Multi-level sorting on any property
• ID filtering — Include/exclude specific IDs with Ids and ExceptIds
• Nested properties — Filter/sort through relationships
• Type-safe — Enum-based property names, compile-time checking
• Query debugging — Inspect generated expression trees

Pagination Modes

var options = new GetItemsOptions
{
    PaginationHandling = PaginationHandlingEnum.Cheap // default
};

Note: Expensive mode requires IDbContextFactory. Use Cheap or None with direct IQueryable extensions.

Filter Operators

Request Options

var request = new BaseGetItemsRequest<PropertyEnum, Guid>
{
    // Pagination
    Page = 1,
    Count = 25,
    Skip = 0,              // Additional skip offset

    // ID filtering
    Ids = [guid1, guid2],       // Include only these IDs
    ExceptIds = [guid3],        // Exclude these IDs

    // Filters and sorting
    Filters = [...],
    Sort = [...],

    // Optimization: pass cached total to skip COUNT query
    TotalCount = cachedTotal
};

Property Mapping

Map enum values to property paths, including nested properties:

public static string[] PropertyNameMapper(BookPropertyNames field) => field switch
{
    BookPropertyNames.Name => [nameof(Book.Name)],
    BookPropertyNames.PublishedOn => [nameof(Book.PublishedOn)],
    BookPropertyNames.AuthorName => [nameof(Book.Author), nameof(Author.Name)],
    _ => throw new ArgumentOutOfRangeException()
};

Response

public class PaginatedData<T>
{
    public T[] Items { get; }
    public int Page { get; }
    public int Count { get; }
    public long? TotalCount { get; }      // Expensive mode only
    public int? TotalPages { get; }       // Expensive mode only
    public bool? HasNextPage { get; }     // Cheap mode only
    public string? QueryDebugView { get; } // When DebugQuery = true
}

Query Debugging

Enable debug mode to inspect the generated expression:

var options = new GetItemsOptions { DebugQuery = true };
var result = await factory.GetItems(ctx => ctx.Books, request, b => b.Id, mapper, options);

Console.WriteLine(result.QueryDebugView);
// Output:
// DbSet<Book>()
//     .Where(b => b.Name.Contains("Great"))
//     .OrderByDescending(b => b.PublishedOn)

Example Project

Check out EntityFramework.Extensions.GetItems.Example for a complete working API.

cd Source/EntityFramework.Extensions.GetItems.Example
dotnet run
# Open http://localhost:5000/scalar/v1

License

MIT