LatticeStripe.List (LatticeStripe v0.2.0)

Represents a paginated list of Stripe objects.

Stripe returns two kinds of paginated collections:

Cursor-based lists — standard list endpoints (e.g., /v1/customers). Use starting_after / ending_before to page through results.
Search results — search endpoints (e.g., /v1/customers/search). Use next_page token to page through results. Note: search endpoints have eventual consistency — newly created objects may not appear immediately.

Accessing Items

Use list.data to access items on the current page:

{:ok, resp} = LatticeStripe.Client.request(client, req)
resp.data.data  # list of decoded maps for this page

LatticeStripe.List does NOT implement Enumerable — Enum.map(list, ...) would mislead callers into thinking they are consuming all pages when they only see page 1. Use list.data for the current page. Use stream!/2 or stream/2 to lazily consume all pages.

Streaming All Pages

Use stream!/2 when you have a client and request and want all matching items:

req = %LatticeStripe.Request{method: :get, path: "/v1/customers", params: %{"limit" => "100"}}
client
|> LatticeStripe.List.stream!(req)
|> Stream.take(200)
|> Enum.to_list()

Use stream/2 when you already have a list from a prior request and want the rest:

{:ok, %Response{data: list}} = Client.request(client, req)
list
|> LatticeStripe.List.stream(client)
|> Enum.each(&process_item/1)

Memory Warning

When consuming an entire stream with no limit, you load all matching objects into memory. Use Stream.take(N) to limit results and avoid unexpected memory usage.

Summary

Types

t()

A paginated Stripe list response.

Functions

from_json(decoded, params \\ %{}, opts \\ [])

Builds a %List{} struct from decoded Stripe JSON.

stream(list, client)

Creates a lazy stream from an existing %List{}, re-emitting its items then fetching remaining pages.

stream!(client, req)

Creates a lazy stream that auto-paginates through all items matching the request.

Types

t()

@type t() :: %LatticeStripe.List{
  _first_id: String.t() | nil,
  _last_id: String.t() | nil,
  _opts: keyword(),
  _params: map(),
  data: [map()],
  extra: map(),
  has_more: boolean(),
  next_page: String.t() | nil,
  object: String.t(),
  total_count: non_neg_integer() | nil,
  url: String.t() | nil
}

A paginated Stripe list response.

Returned by LatticeStripe.Client.request/2 for list and search endpoints. Access items with list.data; check list.has_more to determine if more pages exist.

Use stream!/2 or stream/2 to lazily consume all pages instead of manually paginating.

data - Items on the current page (list of decoded maps or typed structs)
has_more - Whether more pages are available
url - The URL for this list (used for cursor-based next-page construction)
total_count - Total item count (only set on some endpoints)
next_page - Page token for search pagination (set when object is "search_result")
object - Either "list" or "search_result"
extra - Any unknown fields from the Stripe response
_params / _opts - Stored for internal pagination; not for direct use
_first_id / _last_id - Stored cursor IDs; not for direct use

Functions

from_json(decoded, params \\ %{}, opts \\ [])

@spec from_json(map(), map(), keyword()) :: t()

Builds a %List{} struct from decoded Stripe JSON.

Optionally stores the original request params and opts in _params and _opts so streaming functions can reconstruct subsequent page requests.

Also computes _first_id and _last_id from data items for cursor-based pagination — these are used by streaming functions to build next-page requests after the data buffer has been fully consumed.

Examples

List.from_json(%{"object" => "list", "data" => [...], "has_more" => true, "url" => "/v1/customers"})

List.from_json(decoded, %{limit: 10}, [stripe_account: "acct_123"])

stream(list, client)

@spec stream(t(), LatticeStripe.Client.t()) :: Enumerable.t()

Creates a lazy stream from an existing %List{}, re-emitting its items then fetching remaining pages.

The stream includes items already present in the list, followed by items from subsequent pages (if has_more is true).

Raises LatticeStripe.Error if any subsequent page fetch fails.

Example

{:ok, %Response{data: list}} = Client.request(client, req)
# Process first page manually, then stream the rest:
list
|> LatticeStripe.List.stream(client)
|> Enum.each(&process_customer/1)

stream!(client, req)

@spec stream!(LatticeStripe.Client.t(), LatticeStripe.Request.t()) :: Enumerable.t()

Creates a lazy stream that auto-paginates through all items matching the request.

Makes the initial API call, then lazily fetches subsequent pages as the stream is consumed. Emits individual items (flattened from pages), not page structs.

Raises LatticeStripe.Error if any page fetch fails (after retries are exhausted).

Example

req = %LatticeStripe.Request{method: :get, path: "/v1/customers", params: %{"limit" => "100"}}
client
|> LatticeStripe.List.stream!(req)
|> Stream.take(50)
|> Enum.to_list()

Memory Warning

Without Stream.take/2, the stream will fetch ALL matching objects. For large collections, always limit with Stream.take/2.