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

joheredi · 2021-06-17T22:58:50Z

Paginate response is a helper function to handle pagination for the user. Given a response that contains a body with a link to the next page and an array with the current page of results, this helper returns a PagebleAsyncIterator that can be used to get all the items or page by page.

This helper is intended to be wrapped by generated code to provide more context, such as types and pagination options.

The following code snippet shows the user experience consuming a generated client that re-exposes the pagination function with extra context.

const client = TestClient("https://example.org", new DefaultAzureCredentials());

const response = await client.path("/foo").get();
const items = paginate(client, response);

for await (const item of items) {
  // Item would be strongly typed here
  console.log(item.name);
}

Here's how the generated SDK would consume and export this helper.

In order to provide better typings, the library that consumes paginateResponse can wrap it providing additional types. For example a code generator may consume and export in the following way

/**
 * This is the wrapper function that would be exposed. It is hiding the Pagination Options because it can be
 * obtained in the case of a generator from the Swagger definition or by a developer context knowledge in case of a
 * hand written library.
 */
export function paginate<TReturn extends PathUncheckedResponse>(
  client: Client,
  initialResponse: TReturn
): PagedAsyncIterableIterator<PaginateReturn<TReturn>, PaginateReturn<TReturn>[], {}> {
  return paginateResponse<PaginateReturn<TReturn>>(client, initialResponse, {
    // For example these values could come from the swagger
    itemName: "items",
    nextLinkName: "continuationLink",
  });
}

// Helper type to extract the type of an array
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 will be 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 stronly typed Iterator based on the response we get as second parameter
export type PaginateReturn<TResult> = TResult extends {
  body: { items: infer TPage };
}
  ? GetArrayType<TPage>
  : Array<unknown>;

Note: This work implements the standard pagination strategy supported by Autorest x-ms-pageable extension,

If a Service uses a non-standard pagination strategy. The SDK author would be able to implement it's own pagination helper in a similar way as we do here for paginateRequest and export a paginate function

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

sdk/core/core-client-rest/README.md

sdk/core/core-client-rest/package.json

sdk/core/core-client-rest/src/getClient.ts

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

ellismg · 2021-06-18T00:00:17Z