Improve documentation for nextPage() fuctions

[patrickarlt]

Description

We should update the docs for the various method that support nextPage() function. This means:

• Anything returning (ISearchResults](https://developers.arcgis.com/arcgis-rest-js/api-reference/arcgis-rest-portal/ISearchResult/) so searchItems(), searchGroups(), searchUsers()
• findPlacesNearPoint() and findPlacesNearExtent()
• Add nextPage() support to queryFeatures() https://developers.arcgis.com/arcgis-rest-js/api-reference/arcgis-rest-feature-service/IQueryFeaturesResponse/

We should also document the pattern to paginate thorough resuts to get all results which generally looks like this:

function async getAllResults (response) {
 let allItems = lastResponse.results;

  // Keep getting the next page until there are no more pages.
  while (lastResponse.nextPage) {
    lastResponse = await lastResponse.nextPage();
    allItems = allItems.concat(lastResponse.results);
  }

  return allItems;
}

const allResults = await searchItems(options).then(getAllResults)

Link to page

No response

[mustafaazad03]

Hey @patrickarlt, I want to understand this codebase more for that I would love to went through the documentation and contribution in docs is a best way I think. so can I work on it if it is not done.

Thank you

[patrickarlt]

Hi @mustafaazad03 I would love a PR for this. There are a few places that you could contribute too:

• Adding some TypeDoc comments above https://github.com/Esri/arcgis-rest-js/blob/main/packages/arcgis-rest-portal/src/util/search.ts#L50 to indicate that calling this function will return a new Promise with the next page of results and that this function doesn't exist if you are on the last page of results. It also would be worth adding the code block I have above as an example so people have a quick reference for how to get all the results.
• Similar docs could also be added to https://github.com/Esri/arcgis-rest-js/blob/main/packages/arcgis-rest-places/src/findPlacesNearPoint.ts#L26 and https://github.com/Esri/arcgis-rest-js/blob/main/packages/arcgis-rest-places/src/findPlacesWithinExtent.ts#L33
• Final thing would be adding next page support to the queryFeatures() function to add a nextPage() function if there is another page of results to get. to determine if there sianother page of results there will be an exceededTransferLimit property which will be true like in https://p3eplmys2rvchkjx.svcs.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/ACS_Marital_Status_Boundaries/FeatureServer/2/query?f=json&where=1=1&returnGeometry=false when there is another page of results. Then you can repeat the request using the resultRecordCount and resultOffset parameters to get the next page of features.

The third option could be done separately if you want since it is more complex.