Skip to content

Commit 1a77b3c

Browse files
deyaaeldeendeyaaeldeen
authored
[core-paging] Use a TS v3.4-friendly iterator protocol (Azure#19507)
* [core-paging] Use a TS v3.4-friendly iterator protocol * update sample to check intellisense experience * update samples with type checks for customer experience * address feedback and convert sample to tests
1 parent 36e90e4 commit 1a77b3c

16 files changed

+424
-5
lines changed

‎sdk/core/core-paging/package.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,5 +98,13 @@
9898
"rimraf": "^3.0.0",
9999
"rollup": "^1.16.3",
100100
"typescript": "~4.2.0"
101+
},
102+
"//sampleConfiguration": {
103+
"skipFolder": true,
104+
"disableDocsMs": true,
105+
"productName": "Azure SDK Core",
106+
"productSlugs": [
107+
"azure"
108+
]
101109
}
102110
}

‎sdk/core/core-paging/review/core-paging.api.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ export function getPagedAsyncIterator<TElement, TPage = TElement[], TPageSetting
1111
export interface PagedAsyncIterableIterator<T, PageT = T[], PageSettingsT = PageSettings> {
1212
[Symbol.asyncIterator](): PagedAsyncIterableIterator<T, PageT, PageSettingsT>;
1313
byPage: (settings?: PageSettingsT) => AsyncIterableIterator<PageT>;
14-
next(): Promise<IteratorResult<T, T>>;
14+
next(): Promise<IteratorResult<T>>;
1515
}
1616

1717
// @public
@@ -30,7 +30,6 @@ export interface PageSettings {
3030
maxPageSize?: number;
3131
}
3232

33-
3433
// (No @packageDocumentation comment for this package)
3534

3635
```

‎sdk/core/core-paging/sample.env

Whitespace-only changes.

‎sdk/core/core-paging/samples-dev/getPagedAsyncIteratorSample.ts

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Copyright (c) Microsoft Corporation.
2+
// Licensed under the MIT License.
3+
4+
/**
5+
* This sample builds a simple paging operation using getPagedAsyncIterator
6+
*
7+
* @summary builds a simple paging operation using getPagedAsyncIterator
8+
* @azsdk-weight 40
9+
*/
10+
11+
import { getPagedAsyncIterator, PagedResult, PageSettings } from "@azure/core-paging";
12+
13+
export async function main() {
14+
const totalElementsCount = 100;
15+
const collection = Array.from(Array(totalElementsCount), (_, i) => i + 1);
16+
const pagedResult: PagedResult<number[], PageSettings, number> = {
17+
firstPageLink: 0,
18+
async getPage(pageLink, maxPageSize) {
19+
const top = maxPageSize || 5;
20+
if (pageLink < collection.length) {
21+
return Promise.resolve({
22+
page: collection.slice(pageLink, Math.min(pageLink + top, collection.length)),
23+
nextPageLink: top < collection.length - pageLink ? pageLink + top : undefined,
24+
});
25+
} else {
26+
throw new Error("should not get here");
27+
}
28+
},
29+
};
30+
31+
const iterator = getPagedAsyncIterator(pagedResult);
32+
33+
for await (const page of iterator.byPage({ maxPageSize: 5 })) {
34+
for (const element of page) {
35+
console.log(`Received element: ${element}`);
36+
}
37+
}
38+
}
39+
40+
main().catch((err) => {
41+
console.error("The sample encountered an error:", err);
42+
});

‎sdk/core/core-paging/samples/v1/javascript/README.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Azure SDK Core client library samples for JavaScript
2+
3+
These sample programs show how to use the JavaScript client libraries for Azure SDK Core in some common scenarios.
4+
5+
| **File Name** | **Description** |
6+
| ------------------------------------------------------------- | ------------------------------------------------------------ |
7+
| [getPagedAsyncIteratorSample.js][getpagedasynciteratorsample] | builds a simple paging operation using getPagedAsyncIterator |
8+
9+
## Prerequisites
10+
11+
The sample programs are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/).
12+
13+
You need [an Azure subscription][freesub] to run these sample programs.
14+
15+
Samples retrieve credentials to access the service endpoint from environment variables. Alternatively, edit the source code to include the appropriate credentials. See each individual sample for details on which environment variables/credentials it requires to function.
16+
17+
Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package].
18+
19+
## Setup
20+
21+
To run the samples using the published version of the package:
22+
23+
1. Install the dependencies using `npm`:
24+
25+
```bash
26+
npm install
27+
```
28+
29+
2. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically.
30+
31+
3. Run whichever samples you like (note that some samples may require additional setup, see the table above):
32+
33+
```bash
34+
node getPagedAsyncIteratorSample.js
35+
```
36+
37+
Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform):
38+
39+
```bash
40+
npx cross-env node getPagedAsyncIteratorSample.js
41+
```
42+
43+
## Next Steps
44+
45+
Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients.
46+
47+
[getpagedasynciteratorsample]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-paging/samples/v1/javascript/getPagedAsyncIteratorSample.js
48+
[apiref]: https://docs.microsoft.com/javascript/api/@azure/core-paging
49+
[freesub]: https://azure.microsoft.com/free/
50+
[package]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-paging/README.md

‎sdk/core/core-paging/samples/v1/javascript/getPagedAsyncIteratorSample.js

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Copyright (c) Microsoft Corporation.
2+
// Licensed under the MIT License.
3+
4+
/**
5+
* This sample builds a simple paging operation using getPagedAsyncIterator
6+
*
7+
* @summary builds a simple paging operation using getPagedAsyncIterator
8+
*/
9+
10+
const { getPagedAsyncIterator } = require("@azure/core-paging");
11+
12+
async function main() {
13+
const totalElementsCount = 100;
14+
const collection = Array.from(Array(totalElementsCount), (_, i) => i + 1);
15+
const pagedResult = {
16+
firstPageLink: 0,
17+
async getPage(pageLink, maxPageSize) {
18+
const top = maxPageSize || 5;
19+
if (pageLink < collection.length) {
20+
return Promise.resolve({
21+
page: collection.slice(pageLink, Math.min(pageLink + top, collection.length)),
22+
nextPageLink: top < collection.length - pageLink ? pageLink + top : undefined,
23+
});
24+
} else {
25+
throw new Error("should not get here");
26+
}
27+
},
28+
};
29+
30+
const iterator = getPagedAsyncIterator(pagedResult);
31+
32+
for await (const page of iterator.byPage({ maxPageSize: 5 })) {
33+
for (const element of page) {
34+
console.log(`Received element: ${element}`);
35+
}
36+
}
37+
}
38+
39+
main().catch((err) => {
40+
console.error("The sample encountered an error:", err);
41+
});
42+
43+
module.exports = { main };

‎sdk/core/core-paging/samples/v1/javascript/package.json

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "azure-core-paging-samples-js",
3+
"private": true,
4+
"version": "1.0.0",
5+
"description": "Azure SDK Core client library samples for JavaScript",
6+
"engines": {
7+
"node": ">=12.0.0"
8+
},
9+
"repository": {
10+
"type": "git",
11+
"url": "git+https://github.com/Azure/azure-sdk-for-js.git",
12+
"directory": "sdk/core/core-paging"
13+
},
14+
"keywords": [
15+
"microsoft",
16+
"clientruntime",
17+
"azure",
18+
"cloud"
19+
],
20+
"author": "Microsoft Corporation",
21+
"license": "MIT",
22+
"bugs": {
23+
"url": "https://github.com/Azure/azure-sdk-for-js/issues"
24+
},
25+
"homepage": "https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-paging",
26+
"dependencies": {
27+
"@azure/core-paging": "latest",
28+
"dotenv": "latest"
29+
}
30+
}

‎sdk/core/core-paging/samples/v1/javascript/sample.env

Whitespace-only changes.

‎sdk/core/core-paging/samples/v1/typescript/README.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Azure SDK Core client library samples for TypeScript
2+
3+
These sample programs show how to use the TypeScript client libraries for Azure SDK Core in some common scenarios.
4+
5+
| **File Name** | **Description** |
6+
| ------------------------------------------------------------- | ------------------------------------------------------------ |
7+
| [getPagedAsyncIteratorSample.ts][getpagedasynciteratorsample] | builds a simple paging operation using getPagedAsyncIterator |
8+
9+
## Prerequisites
10+
11+
The sample programs are compatible with [LTS versions of Node.js](https://nodejs.org/about/releases/).
12+
13+
Before running the samples in Node, they must be compiled to JavaScript using the TypeScript compiler. For more information on TypeScript, see the [TypeScript documentation][typescript]. Install the TypeScript compiler using:
14+
15+
```bash
16+
npm install -g typescript
17+
```
18+
19+
You need [an Azure subscription][freesub] to run these sample programs.
20+
21+
Samples retrieve credentials to access the service endpoint from environment variables. Alternatively, edit the source code to include the appropriate credentials. See each individual sample for details on which environment variables/credentials it requires to function.
22+
23+
Adapting the samples to run in the browser may require some additional consideration. For details, please see the [package README][package].
24+
25+
## Setup
26+
27+
To run the samples using the published version of the package:
28+
29+
1. Install the dependencies using `npm`:
30+
31+
```bash
32+
npm install
33+
```
34+
35+
2. Compile the samples:
36+
37+
```bash
38+
npm run build
39+
```
40+
41+
3. Edit the file `sample.env`, adding the correct credentials to access the Azure service and run the samples. Then rename the file from `sample.env` to just `.env`. The sample programs will read this file automatically.
42+
43+
4. Run whichever samples you like (note that some samples may require additional setup, see the table above):
44+
45+
```bash
46+
node dist/getPagedAsyncIteratorSample.js
47+
```
48+
49+
Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform):
50+
51+
```bash
52+
npx cross-env node dist/getPagedAsyncIteratorSample.js
53+
```
54+
55+
## Next Steps
56+
57+
Take a look at our [API Documentation][apiref] for more information about the APIs that are available in the clients.
58+
59+
[getpagedasynciteratorsample]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-paging/samples/v1/typescript/src/getPagedAsyncIteratorSample.ts
60+
[apiref]: https://docs.microsoft.com/javascript/api/@azure/core-paging
61+
[freesub]: https://azure.microsoft.com/free/
62+
[package]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-paging/README.md
63+
[typescript]: https://www.typescriptlang.org/docs/home.html

‎sdk/core/core-paging/samples/v1/typescript/package.json

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"name": "azure-core-paging-samples-ts",
3+
"private": true,
4+
"version": "1.0.0",
5+
"description": "Azure SDK Core client library samples for TypeScript",
6+
"engines": {
7+
"node": ">=12.0.0"
8+
},
9+
"scripts": {
10+
"build": "tsc",
11+
"prebuild": "rimraf dist/"
12+
},
13+
"repository": {
14+
"type": "git",
15+
"url": "git+https://github.com/Azure/azure-sdk-for-js.git",
16+
"directory": "sdk/core/core-paging"
17+
},
18+
"keywords": [
19+
"microsoft",
20+
"clientruntime",
21+
"azure",
22+
"cloud"
23+
],
24+
"author": "Microsoft Corporation",
25+
"license": "MIT",
26+
"bugs": {
27+
"url": "https://github.com/Azure/azure-sdk-for-js/issues"
28+
},
29+
"homepage": "https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-paging",
30+
"dependencies": {
31+
"@azure/core-paging": "latest",
32+
"dotenv": "latest"
33+
},
34+
"devDependencies": {
35+
"@types/node": "^12.0.0",
36+
"typescript": "~4.4.0",
37+
"rimraf": "latest"
38+
}
39+
}

0 commit comments

Comments
 (0)