Braintrust.Pagination (Braintrust v0.1.0)

View Source

Cursor-based pagination for Braintrust API list endpoints.

Provides both lazy Stream-based iteration and eager list functions for paginating through API results.

Uses Elixir Streams for memory-efficient, lazy evaluation:

# Define a fetch function that calls the API
fetch_fn = fn opts ->
  Braintrust.Client.get(client, "/v1/project", params: opts)
end

# Stream through results
Braintrust.Pagination.stream(fetch_fn, limit: 100)
|> Stream.take(500)
|> Enum.to_list()

Eager list (fetches all pages)

Braintrust.Pagination.list(fetch_fn, limit: 100)

Duplicate filtering

For fetch endpoints that may return duplicate items across pages:

Braintrust.Pagination.stream(fetch_fn, unique_by: :id)

Summary

Types

fetch_fn()
item()

Functions

list(fetch_fn, opts \\ [])

Fetches all pages and returns a list of all items.

stream(fetch_fn, opts \\ [])

Creates a Stream that lazily paginates through API results.

Types

fetch_fn()

@type fetch_fn() :: (keyword() -> {:ok, map()} | {:error, Braintrust.Error.t()})

item()

@type item() :: map()

Functions

list(fetch_fn, opts \\ [])

@spec list(
  fetch_fn(),
  keyword()
) :: {:ok, [item()]} | {:error, Braintrust.Error.t()}

Fetches all pages and returns a list of all items.

This is a convenience function that eagerly consumes the entire paginated result set. For large datasets, prefer stream/2.

Options

Same as stream/2.

Examples

iex> fetch_fn = fn _opts -> {:ok, %{"objects" => [%{"id" => "1"}]}} end
iex> Braintrust.Pagination.list(fetch_fn)
{:ok, [%{"id" => "1"}]}

stream(fetch_fn, opts \\ [])

@spec stream(
  fetch_fn(),
  keyword()
) :: Enumerable.t()

Creates a Stream that lazily paginates through API results.

The stream fetches pages on-demand as items are consumed, making it memory-efficient for large result sets.

Options

  • :limit - Number of items per page (default: 100)
  • :starting_after - Cursor to start pagination from
  • :unique_by - Key to use for duplicate filtering (e.g., :id)

Examples

iex> fetch_fn = fn opts -> {:ok, %{"objects" => [%{"id" => "1"}]}} end
iex> Braintrust.Pagination.stream(fetch_fn) |> Enum.take(1)
[%{"id" => "1"}]