TreasuryPrime.Page (TreasuryPrime v1.0.0)

Copy Markdown View Source

A single page of results from a list/* call, plus everything needed to fetch subsequent pages.

Treasury Prime returns list results in the shape {"data": [...], "page_next": "https://.../resource?page_cursor=..."}, where page_next is nil once you've reached the last page. This struct wraps that response and gives you two ways to consume it:

Manually, one page at a time

{:ok, page} = TreasuryPrime.Ach.list(client, %{status: "pending"})
page.data       #=> [%TreasuryPrime.Ach{...}, ...]

{:ok, next_page} = TreasuryPrime.Page.next(page)

Automatically, as a lazy Stream over every item across every page

client
|> TreasuryPrime.Ach.list!(%{status: "pending"})
|> TreasuryPrime.Page.stream()
|> Stream.filter(&(&1.amount == "100.00"))
|> Enum.take(10)

stream/1 fetches each subsequent page lazily as the stream is consumed, so it's safe to use with Enum.take/2, Stream.filter/2, early breaks via Enum.find/2, etc. without pulling the entire (potentially huge) result set into memory or making API calls you don't need.

Summary

Types

t()

Functions

all(page)

Eagerly collects every item across every page into a single list.

next(page)

Fetches the next page, if any. Returns {:ok, nil} (not an error!) when page is already the last page.

next!(page)

Like next/1, but raises on error.

stream(page)

Returns a lazy Stream of every item across every page, starting from page (inclusive). Pages are fetched on demand: the next page is only requested once the stream consumer has actually exhausted the current one (so Enum.take/2, Enum.find/2, etc. never trigger an HTTP call for a page they end up not needing).

Types

t()

@type t() :: %TreasuryPrime.Page{
  cast_fun: (map() -> struct()),
  client: TreasuryPrime.Client.t(),
  data: [struct()],
  page_next: String.t() | nil
}

Functions

all(page)

@spec all(t()) :: [struct()]

Eagerly collects every item across every page into a single list.

Use with care on large datasets — prefer stream/1 combined with Stream.take/2/Enum.find/2/etc. when you don't need everything.

next(page)

@spec next(t()) :: {:ok, t() | nil} | {:error, TreasuryPrime.Error.t()}

Fetches the next page, if any. Returns {:ok, nil} (not an error!) when page is already the last page.

next!(page)

@spec next!(t()) :: t() | nil

Like next/1, but raises on error.

stream(page)

@spec stream(t()) :: Enumerable.t()

Returns a lazy Stream of every item across every page, starting from page (inclusive). Pages are fetched on demand: the next page is only requested once the stream consumer has actually exhausted the current one (so Enum.take/2, Enum.find/2, etc. never trigger an HTTP call for a page they end up not needing).

Raises a TreasuryPrime.Error (inside the stream) if a subsequent page fails to load.