Paged results

[joriente]

Hello,
I was wondering about how results are returned from the API
We have a need to return paged results from our data source and I thought that a consistent result object would be ideal and wanted to get some thoughts on my solution. In the application project i created a couple of extension methods

public static class QueryableExtensions
{
    public static Task<PaginatedResult<TDestination>> ToPaginatedListAsync<TDestination>(this IQueryable<TDestination> queryable, int pageNumber, int pageSize, CancellationToken ct) where TDestination : class
        => PaginatedResult<TDestination>.CreateAsync(queryable.AsNoTracking(), pageNumber, pageSize, ct);

    public static Task<ListResult<TDestination>> ToFullListAsync<TDestination>(this IQueryable<TDestination> queryable, CancellationToken ct) where TDestination : class
        => ListResult<TDestination>.CreateAsync(queryable.AsNoTracking());

    public static Task<Result<TDestination>> ToItemAsync<TDestination>(this TDestination item, CancellationToken ct) where TDestination : class
        => Result<TDestination>.SuccessAsync(item);
}

The 3 result objects with the paged results being this class

public class PaginatedResult<T> : Result<T>
{
    public PaginatedResult() { }
    public new IReadOnlyList<T> Data { get; set; }
    public int PageNumber { get; set; }
    public int TotalPages { get; set; }
    public int TotalCount { get; set; }
    public int PageSize { get; set; }

    public PaginatedResult(bool succeeded, IReadOnlyList<T> data, List<string> messages, int count = 0, int pageNumber = 1, int pageSize = 10)
    {
        PageNumber = pageNumber;
        TotalPages = (int)Math.Ceiling(count / (double)pageSize);
        TotalCount = count;
        Data = data;
        Messages = messages;
        Succeeded = succeeded;
        PageSize = pageSize;
    }

    public bool HasPreviousPage => PageNumber > 1;
    public bool HasNextPage => PageNumber < TotalPages;

    public static async Task<PaginatedResult<T>> CreateAsync(IQueryable<T> source, int pageNumber, int pageSize, CancellationToken ct)
    {
        var succeeded = true;
        var data = new List<T>();
        var messages = new List<string>();
        var count = 0;
        try
        {
            count = await source.CountAsync(ct);
            data = await source.Skip((pageNumber - 1) * pageSize).Take(pageSize).ToListAsync(ct);
        }
        catch (Exception ex)
        {
            messages.Add(ex.Message);
            succeeded = false;
        }

        return new PaginatedResult<T>(succeeded, data, messages, count, pageNumber, pageSize);
    }
}

My query looks like this

public record GetPagedHeroQuery : IRequest<PaginatedResult<PagedHeroDto>>
{
    public int PageNumber { get; init; } = 1;
    public int PageSize { get; init; } = 10;
}


public sealed class GetPagedHeroesQueryHandler(
    IMapper mapper,
    IApplicationDbContext dbContext) : IRequestHandler<GetPagedHeroQuery, PaginatedResult<PagedHeroDto>>
{
    public async Task<PaginatedResult<PagedHeroDto>> Handle(
        GetPagedHeroQuery request,
        CancellationToken cancellationToken)
    {
        return await dbContext.Heroes
            .ProjectTo<PagedHeroDto>(mapper.ConfigurationProvider)
            .ToPaginatedListAsync(request.PageNumber, request.PageSize, cancellationToken).ConfigureAwait(false);
    }
}

The other 2 results are for a full list and a single item but very similar in returned fields

The api call is

group
    .MapGet("/paged", (ISender sender, [AsParameters] GetPagedHeroQuery request, CancellationToken ct)
        => sender.Send(request, ct))
    .WithName("GetPagedHero")
    .ProducesGet<PaginatedResult<PagedHeroDto>>();

and results are like

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "…",
      "alias": "…",
      "powerLevel": 1,
      "powers": [
        {
          "name": "…",
          "powerLevel": 1
        }
      ]
    }
  ],
  "pageNumber": 1,
  "totalPages": 1,
  "totalCount": 1,
  "pageSize": 1,
  "hasPreviousPage": true,
  "hasNextPage": true,
  "messages": [
    "…"
  ],
  "succeeded": true,
  "exception": {
    "targetSite": null,
    "message": "…",
    "data": {},
    "innerException": {
      "targetSite": null,
      "message": "…",
      "data": {},
      "innerException": {
        "targetSite": null,
        "message": "…",
        "data": {},
        "innerException": {
          "targetSite": null,
          "message": "…",
          "data": {},
          "innerException": {
            "targetSite": null,
            "message": "…",
            "data": {},
            "innerException": "[Circular Reference]",
            "helpLink": "…",
            "source": "…",
            "hResult": 1,
            "stackTrace": "…"
          },
          "helpLink": "…",
          "source": "…",
          "hResult": 1,
          "stackTrace": "…"
        },
        "helpLink": "…",
        "source": "…",
        "hResult": 1,
        "stackTrace": "…"
      },
      "helpLink": "…",
      "source": "…",
      "hResult": 1,
      "stackTrace": "…"
    },
    "helpLink": "…",
    "source": "…",
    "hResult": 1,
    "stackTrace": "…"
  }
}

I have not integrated ErrorOr yet into my results. I would just like to get others thoughts on results especially paged ones
TIA
John Oriente

[joriente]

As i thought it thru, i made some changes. Now I return only the list of items for the page and use x-pagination response header to return the paging info

 group
     .MapGet("/paged", async (ISender sender, [AsParameters] GetPagedInstitutionsForAdminQuery request, HttpContext context, CancellationToken ct) =>
     {
         var results = await sender.Send(request, ct);
         var metadata = new
         {
             results.TotalPages,
             results.PageSize,
             results.PageNumber,
             results.TotalCount,
             results.HasNextPage,
             results.HasPreviousPage,
         };

         context.Response.Headers["X-Pagination"] = JsonSerializer.Serialize(metadata);
         return TypedResults.Ok(results.Data);

     })
     .WithName("GetPagedInstitutions")
     .ProducesGet<List<GetPagedInstitutionsForAdminDto>>();