[Core Rest] Add pagination helper for rest clients @azure-rest/core-client-paging

rush.json

@@ -436,6 +436,11 @@
       "projectFolder": "sdk/core/core-client-rest",
       "versionPolicyName": "core"
     },
+    {
+      "packageName": "@azure-rest/core-client-paging",
+      "projectFolder": "sdk/core/core-client-paging-rest",
+      "versionPolicyName": "core"
+    },
     {
       "packageName": "@azure/core-asynciterator-polyfill",
       "projectFolder": "sdk/core/core-asynciterator-polyfill",

sdk/agrifood/agrifood-farming-rest/package.json

@@ -85,7 +85,9 @@
   "autoPublish": false,
   "dependencies": {
     "@azure/core-auth": "^1.3.0",
+    "@azure-rest/core-client-paging": "1.0.0-beta.1",
     "@azure-rest/core-client": "1.0.0-beta.4",
+    "@azure/core-paging": "^1.1.1",
     "@azure/core-rest-pipeline": "^1.1.0",
     "@azure/logger": "^1.0.0",
     "tslib": "^2.2.0"

sdk/agrifood/agrifood-farming-rest/review/agrifood-farming.api.md

@@ -7,6 +7,8 @@
 import { Client } from '@azure-rest/core-client';
 import { ClientOptions } from '@azure-rest/core-client';
 import { HttpResponse } from '@azure-rest/core-client';
+import { PagedAsyncIterableIterator } from '@azure/core-paging';
+import { PathUncheckedResponse } from '@azure-rest/core-client';
 import { RequestParameters } from '@azure-rest/core-client';
 import { TokenCredential } from '@azure/core-auth';
 
@@ -1921,6 +1923,9 @@ export type GeoJsonObject = Polygon | MultiPolygon | Point;
 // @public (undocumented)
 export type GeoJsonObjectType = "Point" | "Polygon" | "MultiPolygon";
 
+// @public
+export type GetArrayType<T> = T extends Array<infer TData> ? TData : never;
+
 // @public (undocumented)
 export interface HarvestData {
     area?: Measure;
@@ -2589,6 +2594,16 @@ export interface OAuthTokensListQueryParamProperties {
     minLastModifiedDateTime?: Date;
 }
 
+// @public
+export function paginate<TReturn extends PathUncheckedResponse>(client: Client, initialResponse: TReturn): PagedAsyncIterableIterator<PaginateReturn<TReturn>, PaginateReturn<TReturn>[]>;
+
+// @public
+export type PaginateReturn<TResult> = TResult extends {
+    body: {
+        value?: infer TPage;
+    };
+} ? GetArrayType<TPage> : Array<unknown>;
+
 // @public (undocumented)
 export interface Paths1LxjoxzFarmersFarmeridAttachmentsAttachmentidPatchRequestbodyContentMultipartFormDataSchema {
     createdDateTime?: string;

sdk/agrifood/agrifood-farming-rest/samples-dev/listFarmers.ts

@@ -8,7 +8,7 @@
  * @azsdk-weight 20
  */
 
-import FarmBeats, { Farmer } from "@azure-rest/agrifood-farming";
+import FarmBeats, { paginate } from "@azure-rest/agrifood-farming";
 import { DefaultAzureCredential } from "@azure/identity";
 import dotenv from "dotenv";
 
@@ -18,34 +18,18 @@ const endpoint = process.env["FARMBEATS_ENDPOINT"] || "";
 
 async function main() {
   const farming = FarmBeats(endpoint, new DefaultAzureCredential());
+  const response = await farming.path("/farmers").get();
 
-  const result = await farming.path("/farmers").get();
-
-  if (result.status !== "200") {
-    throw result.body.error?.message;
+  if (response.status !== "200") {
+    throw response.body.error || new Error(`Unexpected status code ${response.status}`);
   }
 
-  let farmers: Farmer[] = result.body.value ?? [];
-  let skipToken = result.body.skipToken;
-
-  // Farmer results may be paginated. In case there are more than one page of farmers
-  // the service would return a skipToken that can be used for subsequent request to get
-  // the next page of farmers. Here we'll keep calling until the service stops returning a
-  // skip token which means that there are no more pages.
-  while (skipToken) {
-    const page = await farming.path("/farmers").get({ queryParameters: { $skipToken: skipToken } });
-    if (page.status !== "200") {
-      throw page.body.error;
-    }
-
-    farmers.concat(page.body.value ?? []);
-    skipToken = page.body.skipToken;
-  }
+  const farmers = paginate(farming, response);
 
   // Lof each farmer id
-  farmers.forEach((farmer) => {
+  for await (const farmer of farmers) {
     console.log(farmer.id);
-  });
+  }
 }
 
 main().catch(console.error);

sdk/agrifood/agrifood-farming-rest/src/farmBeats.ts

@@ -306,8 +306,10 @@ import {
   WeatherCreateDataDeleteJob202Response,
   WeatherCreateDataDeleteJobdefaultResponse,
 } from "./responses";
-import { getClient, ClientOptions, Client } from "@azure-rest/core-client";
+import { getClient, ClientOptions, Client, PathUncheckedResponse } from "@azure-rest/core-client";
 import { TokenCredential } from "@azure/core-auth";
+import { PagedAsyncIterableIterator } from "@azure/core-paging";
+import { paginateResponse } from "@azure-rest/core-client-paging";
 
 export interface ApplicationDataListByFarmerId {
   /** Returns a paginated list of application data resources under a particular farm. */
@@ -1110,6 +1112,37 @@ export type FarmBeatsRestClient = Client & {
   path: Routes;
 };
 
+/**
+ * Helper type to extract the type of an array
+ */
+export type GetArrayType<T> = T extends Array<infer TData> ? TData : never;
+
+/**
+ * Helper type to infer the Type of the paged elements from the response type
+ * This type is generated based on the swagger information for x-ms-pageable
+ * specifically on the itemName property which indicates the property of the response
+ * where the page items are found. The default value is `value`.
+ * This type will allow us to provide strongly typed Iterator based on the response we get as second parameter
+ */
+export type PaginateReturn<TResult> = TResult extends {
+  body: { value?: infer TPage };
+}
+  ? GetArrayType<TPage>
+  : Array<unknown>;
+
+/**
+ * This is the wrapper function that would be exposed. It is hiding the Pagination Options because it can be
+ * obtained from the swagger
+ * @param client - Client to use for sending the next page requests
+ * @param initialResponse - Initial response containing the nextLink and current page of elements
+ * @returns - PagedAsyncIterableIterator to iterate the elements
+ */
+export function paginate<TReturn extends PathUncheckedResponse>(
+  client: Client,
+  initialResponse: TReturn
+): PagedAsyncIterableIterator<PaginateReturn<TReturn>, PaginateReturn<TReturn>[]> {
+  return paginateResponse<PaginateReturn<TReturn>>(client, initialResponse);
+}
 export default function FarmBeats(
   Endpoint: string,
   credentials: TokenCredential,

sdk/agrifood/agrifood-farming-rest/src/index.ts

@@ -8,4 +8,6 @@ export * from "./models";
 export * from "./parameters";
 export * from "./responses";
 
+export { paginate, PaginateReturn, GetArrayType } from "./farmBeats";
+
 export default FarmBeats;

sdk/agrifood/agrifood-farming-rest/test/public/smoke.spec.ts

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
-import { FarmBeatsRestClient } from "../../src";
+import { FarmBeatsRestClient, Farmer, paginate } from "../../src";
 import { Recorder } from "@azure/test-utils-recorder";
 
 import { assert } from "chai";
@@ -29,7 +29,14 @@ describe("List farmers", () => {
       assert.fail(`GET "/farmers" failed with ${result.status}`);
     }
 
-    assert.isDefined(result.body.value?.length);
+    const farmers = paginate(client, result);
+
+    let lastFarmer: Farmer | undefined = undefined;
+    for await (const farmer of farmers) {
+      lastFarmer = farmer;
+    }
+
+    assert.isDefined(lastFarmer);
   });
 
   it("should create a farmer", async () => {

sdk/core/ci.yml

@@ -48,6 +48,8 @@ extends:
         safeName: azurecoreclient
       - name: azure-rest-core-client
         safeName: azurerestcoreclient
+      - name: azure-rest-core-client-paging
+        safeName: azurerestcoreclientpaging
       - name: azure-core-crypto
         safeName: azurecorecrypto
       - name: azure-core-http

sdk/core/core-client-paging-rest/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+## 1.0.0-beta.1 (UNRELEASED)
+
+- First release of package, see README.md for details.

sdk/core/core-client-paging-rest/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.