# `Magpie.Pager`
[🔗](https://github.com/alexcassol/magpie/blob/v0.3.1/lib/magpie/pager.ex#L1)

Turns Dropbox cursor-based pagination into a lazy `Stream`.

Many Dropbox endpoints return one page of results plus a `"cursor"` (and
usually a `"has_more"` flag), expecting you to call a `/continue` variant
until the listing is exhausted. `stream/3` hides that loop behind a regular
Elixir `Stream`, so consumers just use `Enum`/`Stream` functions and pages
are fetched on demand:

    client
    |> Magpie.Files.ListFolder.stream("/Photos")
    |> Stream.filter(&(&1[".tag"] == "file"))
    |> Enum.take(100)

Ready-made wrappers: `Magpie.Files.ListFolder.stream/2`,
`Magpie.Files.search_stream/3`, `Magpie.Sharing.list_folders_stream/2` and
`Magpie.FileRequests.stream/2`. For any other paginated endpoint, build
your own with `stream/3`.

Because a `Stream` cannot return an error tuple mid-enumeration, API
errors raise `Magpie.Error` while the stream is being consumed.

# `stream`

Builds a lazy `Stream` of items out of a paginated endpoint.

  * `first_fun` — zero-arity function that fetches the first page
  * `continue_fun` — one-arity function that takes a cursor and fetches
    the next page
  * `opts`:
    * `:items_key` — key holding the page's item list (default `"entries"`)
    * `:cursor_key` — key holding the cursor (default `"cursor"`)
    * `:has_more_key` — key flagging more pages (default `"has_more"`;
      when the key is absent, pagination continues while a cursor is
      present)

## Example

    Magpie.Pager.stream(
      fn -> Magpie.Files.ListFolder.list_folder(client, "/Photos") end,
      fn cursor -> Magpie.Files.ListFolder.list_folder_continue(client, cursor) end
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*