PaginationEx.Core (PaginationEx v0.1.0)

Core pagination functionality for Ecto queries.

This module provides the main pagination functionality for Ecto queries, including:

  • Paginating query results with customizable page size
  • Calculating total entries and pages
  • Grouping results for bulk retrieval
  • Handling various query types (simple, grouped, distinct)

The pagination result is a struct containing entries, metadata about the pagination, and the original query.

Summary

Types

t()

Functions

in_groups(query, params \\ %{})

Retrieves all entries in groups of specified size.

new(query, params, opts \\ [])

Creates a new paginated result for the given query.

Types

t()

@type t() :: %PaginationEx.Core{
  entries: [any()],
  page_number: pos_integer(),
  pages: non_neg_integer(),
  per_page: pos_integer(),
  query: Ecto.Query.t(),
  total_entries: integer()
}

Functions

in_groups(query, params \\ %{})

@spec in_groups(Ecto.Queryable.t(), map()) :: [any()]

Retrieves all entries in groups of specified size.

This function fetches all records matching the query in batches, combining them into a single list. Useful for retrieving large datasets efficiently without loading everything at once.

Parameters

  • query - The Ecto query to paginate
  • params - Map of pagination parameters (optional)
    • "per_group" - Number of items per group (defaults to config or 1000)
    • "total" - Optional pre-calculated total count

Returns

  • List of all entries matching the query

Examples 

iex> PaginationEx.Core.in_groups(Post, %{"per_group" => "100"})
[%Post{}, %Post{}, ...]

new(query, params, opts \\ [])

@spec new(Ecto.Queryable.t(), map(), keyword()) :: t()

Creates a new paginated result for the given query.

This function returns a pagination struct containing the entries for the requested page, along with metadata about the pagination such as total entries, page count, etc.

Parameters

  • query - The Ecto query to paginate
  • params - Map of pagination parameters
    • "page" - Page number to fetch (defaults to 1)
    • "per_page" - Number of items per page (defaults to 30)
    • "total" - Optional pre-calculated total count
  • opts - Options passed to Repo.all/2 (optional)

Returns

  • A PaginationEx.Core struct containing:
    • entries - The paginated query results
    • total_entries - Total count of matching records
    • page_number - Current page number
    • per_page - Number of items per page
    • pages - Total number of pages
    • query - The original query

Examples 

iex> PaginationEx.Core.new(Post, %{"page" => "2", "per_page" => "10"})
%PaginationEx.Core{
  entries: [%Post{}, %Post{}, ...],
  total_entries: 59,
  page_number: 2,
  per_page: 10,
  pages: 6,
  query: #Ecto.Query<...>
}