Knowing when eachPage is on the last page

https://github.com/mapbox/mapbox-sdk-js/pull/272 added a little to the docs to illustrate the best current method for knowing whether your eachPage callback is on its last iteration.

There are a couple of other API options we could consider that might improve this use case:

• eachPage could call the callback with null, instead of a response, after it has exhausted the page list. (This is what the aws-sdk-js does.) This would be a breaking change, because it means every eachPage user would need to anticipate a null value for the response argument.

  request.eachPage((error, response, next) => {
    if (error) {
      // Handle error ...
    }
    if (!response) {
      // Do something after pages are exhausted ...
    }
    // Handle the response ...
    next();
  });
  

• eachPage could return a Promise that resolves when all the pages have been passed through the callback. This would not be a breaking change, because the current usage of eachPage would continue to work the same: it would just be a feature addition.

  request.eachPage((error, response, next) => {
    if (error) {
      // Handle error ...
    }    
    // Handle the response ...
    next();
  }).then(() => {
    // Do something after pages are exhausted ...
  }, /* This Promise would never reject. */);
  

I'm leaning towards the Promise, because it's not a breaking change and seems like the preferable API.

@andrewharvey @mapbox/frontend-platform do you agree, or can you anticipate any problems with eachPage returning a Promise?

Start by reviewing the current eachPage API and the documentation changes in pull request 272. Compare the proposed null-response and Promise options, then identify which behavior the maintainers want. Done requires an agreed API direction and corresponding implementation and documentation scope, but this issue does not yet provide that decision.