Paginação

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)                    // sempre ordene antes de paginar
        .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; }     // total sem paginação
    public int Number { get; }
    public int Size { get; }

    public int TotalPages { get; }      // derivado
    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)));   // impossível no banco

// page / pageSize / total: nenhum desses nomes é nosso, e está tudo bem. Manter a forma
// estrangeira em um tipo só faz a adaptação ser um passo único e visível — e faz um campo
// que eles renomeiem ser mudança em um arquivo.
public sealed record SupplierCatalogPage(
    [property: JsonPropertyName("page")] int PageNumber,
    int PageSize,
    int Total,
    IReadOnlyList<SupplierCatalogOffer>? Items)
{
    // "items": null é um corpo que eles podem mandar. O nullable fica no tipo de fio.
    [JsonIgnore] public IReadOnlyList<SupplierCatalogOffer> Offers => Items ?? [];

    // Page<T> recusa total negativo, e tem razão: essa falha é deles.
    [JsonIgnore] public long TotalCount => Math.Max(Total, 0);
}

public async Task<Page<SupplierOfferSummary>> HandleAsync(
    SearchSupplierOffers query,
    CancellationToken ct)
{
    // 1. Os valores já com clamp são os que vão no fio. ?page=0&size=99999 é normalizado
    //    antes deste processo pedir isso a qualquer outro — e serviço remoto é onde um
    //    tamanho de página sem limite dói mais, porque o banco é de outra pessoa.
    var request = query.Request;
    var remote = await catalog.FetchOffersAsync(query.Term, request.Number, request.Size, ct);

    // 2. O envelope deles vira o nosso. O total é deles; o tamanho é aquele dos dois que
    //    descreve as linhas que de fato chegaram (veja o aviso abaixo).
    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. Enriquece com o banco local, consultando só as chaves DESTA página: uma página de
    //    20 linhas custa uma query sobre 20 chaves — nunca um scan, nunca uma query por linha.
    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. O Map reescreve os itens e não toca em TotalCount, Number e Size. É isso que "a
    //    mesma paginação" quer dizer: a projeção nunca chega nesses números.
    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))
        // A chave é a ordem: única e indexada. Não ordene antes.
        .ToCursorPageAsync(e => e.Id, query.Request, descending: true, ct);

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