Generic lazy pagination helper for Discord API endpoints.

Builds a Stream.resource/3 that fetches pages on demand, yielding items one at a time with O(page_size) memory. The stream halts automatically when Discord returns an empty or incomplete page, or when an error occurs.

Example

EDA.Paginator.stream(
  fetch: fn cursor ->
    EDA.API.Ban.list(guild_id, limit: 1000, after: cursor)
  end,
  cursor_key: ["user", "id"],
  direction: :after,
  per_page: 1000
)
|> Stream.take(50)
|> Enum.to_list()

Options

• :fetch (required) — (cursor | nil -> {:ok, [item]} | {:error, term()}). Receives nil on the first call, then the extracted cursor for subsequent pages.

• :cursor_key — How to extract the cursor from each item. Accepts:
  • a string key (e.g. "id") — uses item["id"]
  • a list of string keys (e.g. ["user", "id"]) — uses get_in/2
  • a function (item -> cursor) — arbitrary extraction Defaults to "id".
• :direction — :before or :after. Defaults to :before.
• :per_page — Page size, used to detect incomplete (final) pages. Defaults to 100.
• :initial_cursor — Starting cursor value. Defaults to nil.