Paging

public sealed class SearchProducts : PagedQuery<ProductSummary>
{
    public string? Term { get; init; }
    public Guid? CategoryId { get; init; }
}

public Task<Page<ProductSummary>> HandleAsync(SearchProducts query, CancellationToken ct)
{
    var filtered = products;

    if (!string.IsNullOrWhiteSpace(query.Term))
    {
        var term = query.Term.Trim();
        filtered = filtered.Where(p => p.Sku.Contains(term) || p.Name.Contains(term));
    }

    if (query.CategoryId is { } categoryId)
    {
        filtered = filtered.Where(p => p.Category!.ExternalId == categoryId);
    }

    return filtered
        .OrderBy(p => p.Sku)                    // always order before paging
        .Select(p => new ProductSummary(p.ExternalId, p.Sku, p.Price, p.Category!.Name))
        .ToPageAsync(query.Request, ct);
}

public readonly struct PageRequest
{
    public const int DefaultSize = 20;
    public const int MaxSize = 200;
    public const int MaxNumber = 100_000;

    public int Number { get; }   // 1..MaxNumber
    public int Size { get; }     // 1..MaxSize
    public int Skip => (Number - 1) * Size;
}

public sealed class Page<T>
{
    public IReadOnlyList<T> Items { get; }
    public long TotalCount { get; }     // the total, unpaged
    public int Number { get; }
    public int Size { get; }

    public int TotalPages { get; }      // derived
    public bool HasPrevious { get; }
    public bool HasNext { get; }

    public Page<TOut> Map<TOut>(Func<T, TOut> selector);
    public static Page<T> Empty(int number = 1, int size = PageRequest.DefaultSize);
}

{
  "items": [
    { "id": "01a0e09d-4067-720d-9c5e-a9a99d3e3bef", "sku": "MART-01", "price": 59.9 },
    { "id": "01a0e09d-42a9-7848-9f00-79ce46395796", "sku": "REG-01", "price": 19.5 }
  ],
  "totalCount": 3,
  "number": 1,
  "size": 2,
  "totalPages": 2,
  "hasPrevious": false,
  "hasNext": true
}

var page = await products
    .OrderBy(p => p.Sku)
    .Select(p => new ProductRow(p.ExternalId, p.Sku, p.Price))
    .ToPageAsync(query.Request, ct);

return page.Map(row => new ProductSummary(
    row.Id,
    row.Sku,
    row.Price.ToString("C", culture)));   // impossible in the database

// page / pageSize / total: none of those names is ours, and that is fine. Keeping the
// foreign shape in one type makes the adaptation a single, visible step — and makes a
// field they rename a one-file change.
public sealed record SupplierCatalogPage(
    [property: JsonPropertyName("page")] int PageNumber,
    int PageSize,
    int Total,
    IReadOnlyList<SupplierCatalogOffer>? Items)
{
    // "items": null is a body they are free to send. The nullable stays on the wire type.
    [JsonIgnore] public IReadOnlyList<SupplierCatalogOffer> Offers => Items ?? [];

    // Page<T> refuses a negative total, and it is right to: that failure is theirs.
    [JsonIgnore] public long TotalCount => Math.Max(Total, 0);
}

public async Task<Page<SupplierOfferSummary>> HandleAsync(
    SearchSupplierOffers query,
    CancellationToken ct)
{
    // 1. The clamped values are what go on the wire. ?page=0&size=99999 is normalised
    //    before this process asks anybody else for it — and a remote service is where an
    //    unclamped page size hurts most, because it is somebody else's database.
    var request = query.Request;
    var remote = await catalog.FetchOffersAsync(query.Term, request.Number, request.Size, ct);

    // 2. Their envelope becomes ours. The total is theirs; the size is whichever of the two
    //    describes the rows actually in hand (see the warning below).
    var size = remote.PageSize > 0 && remote.PageSize < request.Size ? remote.PageSize : request.Size;
    var page = new Page<SupplierCatalogOffer>(remote.Offers, remote.TotalCount, request.Number, size);

    // 3. Enrich from the local database, querying only the keys on THIS page: a page of 20
    //    rows costs one query over 20 keys — never a scan, and never one query per row.
    var skus = page.Items.Select(o => o.Sku).Distinct().ToArray();
    var stocked = (await products
            .Where(p => skus.Contains(p.Sku))
            .Select(p => new StockedProduct(p.Sku, p.ExternalId, p.Price))
            .ToListAsync(ct))
        .ToDictionary(p => p.Sku, StringComparer.Ordinal);

    // 4. Map rewrites the items and leaves TotalCount, Number and Size alone. That is what
    //    "the same paging" means: the projection never gets to touch those numbers.
    return page.Map(offer =>
    {
        var local = stocked.GetValueOrDefault(offer.Sku);
        return new SupplierOfferSummary(
            offer.Sku, offer.Name, offer.UnitCost, offer.Currency,
            LeadTime(offer.LeadTimeDays), local?.Id, local?.Price);
    });
}

app.MapGet("/products", (
    [AsParameters] SearchProductsRequest request,
    IMediator mediator,
    CancellationToken ct) =>
    mediator.FetchAsync(
        new SearchProducts
        {
            Number = request.Page ?? 1,
            Size = request.Size ?? PageRequest.DefaultSize,
            Term = request.Term,
            CategoryId = request.CategoryId,
        },
        ct));

internal sealed record SearchProductsRequest(int? Page, int? Size, string? Term, Guid? CategoryId);

var page = await orders
    .Where(o => o.CustomerId == customerId)
    .OrderByDescending(o => o.PlacedOn)
    .Select(o => new OrderRow(o.ExternalId, o.Total))
    .ToPageAsync(number: 2, size: 25, ct);

public sealed class ActivityFeed : CursorQuery<ActivityRow>;

public Task<CursorPage<ActivityRow>> HandleAsync(ActivityFeed query, CancellationToken ct) =>
    entries
        .Select(e => new ActivityRow(e.Id, e.Kind, e.Summary))
        // The key is the ordering: unique and indexed. Do not order beforehand.
        .ToCursorPageAsync(e => e.Id, query.Request, descending: true, ct);

{
  "items": [ { "id": 812, "kind": "product-repriced", "summary": "…" } ],
  "nextCursor": "ODEx",
  "hasNext": true,
  "size": 20
}