ExToolkit.Ecto.Paginator (ExToolkit v0.12.4)

View Source

Provides functionality for paginating Ecto queries. It offers a simple and flexible way to paginate large result sets, supporting both default and custom pagination options.

Usage

To use this paginator in your module, you call use ExToolkit.Ecto.Paginator.

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app
  use ExToolkit.Ecto.Paginator
end

The default page size is 25 but you can override it by passing a page_size.

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app
  use ExToolkit.Ecto.Paginator, page_size: 30
end

Use without macros

If you wish to avoid use of macros or you wish to use a different name for the pagination function you can define your own function like so:

defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app

  def my_paginate_function(queryable, page, opts \\ [], repo_opts \\ []) do
    defaults = [page_size: 12] # Default options of your choice here
    opts = Keyword.merge(defaults, opts)
    ExToolkit.Ecto.Paginator.paginate(queryable, __MODULE__, page, opts, repo_opts)
  end
end

Summary

Functions

Paginates an Ecto query and returns a map with pagination metadata.

Types

option()

@type option() :: {:page_size, non_neg_integer()}

options()

@type options() :: [option()]

page()

@type page() :: %{
  data: [any()],
  current_page: non_neg_integer(),
  total_pages: non_neg_integer(),
  total_count: non_neg_integer(),
  has_next_page: boolean(),
  has_prev_page: boolean(),
  is_first_page: boolean(),
  is_last_page: boolean()
}

page(elem)

@type page(elem) :: %{
  data: [elem],
  current_page: non_neg_integer(),
  total_pages: non_neg_integer(),
  total_count: non_neg_integer(),
  has_next_page: boolean(),
  has_prev_page: boolean(),
  is_first_page: boolean(),
  is_last_page: boolean()
}

Functions

paginate(queryable, repo, page, opts \\ [], repo_opts \\ [])

@spec paginate(Ecto.Queryable.t(), Ecto.Repo.t(), pos_integer(), options(), keyword()) ::
  page()

Paginates an Ecto query and returns a map with pagination metadata.

Arguments

  • queryable: The Ecto queryable (e.g., Repo.all(User)).
  • repo: The repository to execute the query.
  • page: The page number to fetch (starts at 1).
  • opts: A keyword list of options, including the :page_size option (default is 25).
  • repo_opts: Ecto-specific options, see ecto docs to learn about all available options.

Returns

A map containing the following keys:

  • :data - The list of items for the current page.
  • :current_page - The current page number.
  • :total_count - The total number of items in the query.
  • :total_pages - The total number of pages based on the page size.
  • :has_next_page - Whether there is a next page.
  • :has_prev_page - Whether there is a previous page.
  • :is_first_page - Whether the current page is the first page.
  • :is_last_page - Whether the current page is the last page.