Pager (Pager v1.0.0)

View Source

Provides pagination functionality for Ecto queries.

This module offers a simple way to paginate Ecto query results with automatic handling of page boundaries, flexible parameter types, and consistent return structure.

Summary

Types

Pagination result containing pagination metadata and list of items.

Functions

Paginates an Ecto query with flexible parameter handling.

Types

page_result()

@type page_result() :: %{
  has_next: boolean(),
  has_prev: boolean(),
  prev_page: integer(),
  page: integer(),
  next_page: integer(),
  first: integer(),
  last: integer(),
  count: integer(),
  list: [any()]
}

Pagination result containing pagination metadata and list of items.

Fields:

  • has_next - Indicates if there are more pages after the current one
  • has_prev - Indicates if there are pages before the current one
  • prev_page - Previous page number
  • page - Current page number
  • next_page - Next page number
  • first - Index of first item on current page
  • last - Index of last item on current page
  • count - Total number of items across all pages
  • list - List of results/items on the current page

Functions

page(query, repo, page, per_page)

@spec page(
  Ecto.Query.t(),
  Ecto.Repo.t(),
  integer() | binary() | nil,
  integer() | binary() | nil
) ::
  page_result()

Paginates an Ecto query with flexible parameter handling.

Parameters

  • query - An Ecto query to paginate
  • repo - The Ecto repo to execute the query
  • page - Page number (integer or string, defaults to 1)
  • per_page - Items per page (integer or string, defaults to 50)

Examples

iex> alias Pager.{User, Repo}
iex> query = from(u in User)
iex> result = Pager.page(query, Repo, 1, 20)
iex> Map.drop(result, [:list])
%{count: 0, first: 1, has_next: false, has_prev: false, last: 0, next_page: 2, page: 1, prev_page: 0}

# String parameters (e.g. from Phoenix params)
iex> alias Pager.{User, Repo}
iex> query = from(u in User)
iex> result = Pager.page(query, Repo, "2", "10")
iex> Map.drop(result, [:list])
%{count: 0, first: 11, has_next: false, has_prev: true, last: 0, next_page: 3, page: 2, prev_page: 1}

# With defaults
iex> alias Pager.{User, Repo}
iex> query = from(u in User)
iex> result = Pager.page(query, Repo, nil, 50)
iex> Map.drop(result, [:list])
%{count: 0, first: 1, has_next: false, has_prev: false, last: 0, next_page: 2, page: 1, prev_page: 0}