@spec collect_all((String.t() | nil ->
               {:ok, [term()], String.t() | nil} | {:error, term()})) :: [
  term()
]

Collects an entire paginated resource into a single list. Use with care on large collections.

@spec stream((String.t() | nil ->
          {:ok, [term()], String.t() | nil} | {:error, term()})) ::
  Enumerable.t()

Builds a lazy Stream of individual items across all pages of a paginated Synctera list endpoint.

fetch_page is called with nil for the first page, then with each successive next_page_token until one returns nil. It must return {:ok, items, next_page_token} or {:error, reason}.

Example

Synctera.Pagination.stream(fn page_token ->
  with {:ok, page} <- Synctera.Persons.list_persons(client, page_token: page_token) do
    {:ok, page["persons"], page["next_page_token"]}
  end
end)
|> Stream.each(&IO.inspect/1)
|> Stream.run()