[Core Rest] Add pagination helper for rest clients @azure-rest/core-c…

…lient-paging (Azure#15831) * Prototype paging helper function * Use paginate in farmbeats * Updates * Update farmbeats * Address PR feedback * Move paging to its own package * Use REST Error * Update types output * update home page * Explicit return RestError * Move paging to its own file and update changelog and versions
AzureSDKAutomation · Jun 24, 2021 · 23bb270 · 23bb270
1 parent 93d102b
commit 23bb270
Show file tree

Hide file tree

Showing 40 changed files with 1,146 additions and 58 deletions.
diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml
diff --git a/rush.json b/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",

diff --git a/sdk/agrifood/agrifood-farming-rest/CHANGELOG.md b/sdk/agrifood/agrifood-farming-rest/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## 1.0.0-beta.2 (Unreleased)
 
+### Features Added
+
+- Export pagination helper function. [#15831](https://github.com/Azure/azure-sdk-for-js/pull/15831)
 
 ## 1.0.0-beta.1 (2021-05-26)
 

diff --git a/sdk/agrifood/agrifood-farming-rest/package.json b/sdk/agrifood/agrifood-farming-rest/package.json
@@ -85,7 +85,8 @@
   "autoPublish": false,
   "dependencies": {
     "@azure/core-auth": "^1.3.0",
-    "@azure-rest/core-client": "1.0.0-beta.4",
+    "@azure-rest/core-client-paging": "1.0.0-beta.1",
+    "@azure-rest/core-client": "1.0.0-beta.5",
     "@azure/core-rest-pipeline": "^1.1.0",
     "@azure/logger": "^1.0.0",
     "tslib": "^2.2.0"

diff --git a/sdk/agrifood/agrifood-farming-rest/review/agrifood-farming.api.md b/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-rest/core-client-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;

diff --git a/sdk/agrifood/agrifood-farming-rest/samples-dev/listFarmers.ts b/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);
diff --git a/sdk/agrifood/agrifood-farming-rest/src/index.ts b/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 "./paging";
+
 export default FarmBeats;
diff --git a/sdk/agrifood/agrifood-farming-rest/src/paging.ts b/sdk/agrifood/agrifood-farming-rest/src/paging.ts
@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { paginateResponse, PagedAsyncIterableIterator } from "@azure-rest/core-client-paging";
+import { Client, PathUncheckedResponse } from "@azure-rest/core-client";
+
+/**
+ * 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);
+}
diff --git a/sdk/agrifood/agrifood-farming-rest/test/public/smoke.spec.ts b/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 () => {

diff --git a/sdk/confidentialledger/confidential-ledger-rest/package.json b/sdk/confidentialledger/confidential-ledger-rest/package.json
@@ -85,7 +85,7 @@
   "autoPublish": false,
   "dependencies": {
     "@azure/core-auth": "^1.3.0",
-    "@azure-rest/core-client": "1.0.0-beta.4",
+    "@azure-rest/core-client": "1.0.0-beta.5",
     "@azure/core-rest-pipeline": "^1.1.0",
     "@azure/logger": "^1.0.0",
     "tslib": "^2.2.0"

diff --git a/sdk/core/ci.yml b/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

diff --git a/sdk/core/core-client-paging-rest/CHANGELOG.md b/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.
diff --git a/sdk/core/core-client-paging-rest/LICENSE b/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.