Update PagingIterator

[jlawton]

Issue 🔗

PagingIterator is a pain to use when writing apps.

Goals ⚽

• Change PagingIterator.next to return pages, which will simplify usage for most apps.
• Return PagingIterator directly from the API, as it now requests the first page itself.

Implementation Details 🚧

• Removed the buffer internal to the iterator and simplified the logic.
• There are no longer 2 places where failure can be reported. Construction no longer fails.
• There are no longer 2 places which parse pages. Construction doesn't parse a page.
• Hide nextPage from consumers, though there may be a good reason to expose something like it.

Testing Details 🔍

Tests currently fail to build on my machine, but that is true on master, so it is not due to my changes.

[jlawton]

@sujaygarlanka Interested in feedback on this alternative API.

[theli]

I have felt recently how painful it is to use PagingIterator in listItems call and will take another route by calling API endpoint directly.
It looks like there has not been any progress since October on this issue. Is it still in plans to do?

[jlawton]

@theli I made this contribution as a proposal. Is this an interface you'd be happy with? I know the team wouldn't want to have repeated incompatible changes, and I can push for a decision on this especially if it meets your use case as well as mine.

[theli]

I have not reviewed thoroughly the pull request but it looks like it fixes biggest pain point which is async execution of .next method of the PagingIterator.
Another complexity was not having the number of items returned makes it difficult to know when iterator has reached the end of list. It seems like the .failure result was supposed to serve the purpose to indicate end of list, however it works only when there is one page of results returned by the API (enforced by "limit" request param). When API response contains marker to nextpage results, there is no .failure.