DodoPayments.Page (dodo_payments v0.1.0)

Copy Markdown View Source

Explicit pagination for Dodo Payments list operations.

Start with the first page returned by a resource function. Use next/1 when request boundaries matter, or opt into a lazy bounded traversal with pages/2 or stream/2.

{:ok, first} = DodoPayments.Products.list(client, %{page_number: 0})

with {:ok, second} <- DodoPayments.Page.next(first) do
  second.items
end

first
|> DodoPayments.Page.stream(max_pages: 20)
|> Enum.take(100)

Automatic traversal is deliberately guarded. It detects repeated iterators or page numbers and defaults to at most 1,000 pages. Page structs retain a private fetch closure containing client/request state; consume them during the request workflow and persist only application data, never the page struct itself.

Summary

Functions

Returns the items held by a page.

Fetches exactly one next page, or returns :done.

Lazily enumerates pages, including the supplied first page.

Lazily enumerates items across pages.

Types

next_result(item)

@type next_result(item) :: {:ok, t(item)} | :done | {:error, Exception.t()}

t(item)

Functions

items(map)

@spec items(t(item)) :: [item] when item: term()

Returns the items held by a page.

next(page)

@spec next(t(item)) :: next_result(item) when item: term()

Fetches exactly one next page, or returns :done.

pages(first_page, opts \\ [])

@spec pages(
  t(item),
  keyword()
) :: Enumerable.t()
when item: term()

Lazily enumerates pages, including the supplied first page.

Options:

  • :max_pages - positive traversal limit, default 1_000

Fetch failures and broken pagination invariants raise TraversalError while the stream is consumed. No further HTTP request occurs after a consumer halts the stream.

stream(first_page, opts \\ [])

@spec stream(
  t(item),
  keyword()
) :: Enumerable.t()
when item: term()

Lazily enumerates items across pages.

It accepts the :max_pages option from pages/2 plus :max_items (default :infinity). The item limit is a safety ceiling and raises when more items are requested; normal early termination such as Enum.take/2 remains lazy.