@autorest/typescript 6.0.0-beta.7 → 6.0.0-rc.1

package/README.md

@@ -53,9 +53,9 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 ## Autorest Typescript Plugin Configuration
 
 ```yaml
-version: 3.4.5
+version: 3.6.6
 use-extension:
-  "@autorest/modelerfour": "4.19.3"
+  "@autorest/modelerfour": "4.23.5"
 
 modelerfour:
   # this runs a pre-namer step to clean up names
@@ -68,7 +68,17 @@ modelerfour:
   always-create-content-type-parameter: true
   # enables parameter grouping via x-ms-parameter-grouping
   group-parameters: true
+  # Enable older inconsistent behavior that an enum with a single value would become a constant by default.
+  seal-single-value-enum-by-default: true
+  legacy-request-body: true
 
+typescript-scope/emitter:
+  input-artifact: typescript-files
+
+output-artifact: typescript-files
+```
+
+```yaml !$(generate-sample)
 pipeline:
   typescript: # <- name of plugin
     input: modelerfour/identity
@@ -78,10 +88,37 @@ pipeline:
     input: typescript
     scope: typescript-scope/emitter
 
-typescript-scope/emitter:
-  input-artifact: typescript-files
+```
+
+```yaml $(generate-sample)
+use-extension:
+  "@autorest/testmodeler": "2.2.5"
+
+try-require:
+    - ./readme.test.md
+    - ./readme.tests.md
+
+testmodeler:
+  split-parents-value: false
+
+include-x-ms-examples-original-file: true
+modelerfour:
+  include-x-ms-examples-original-file: true
+
+pipeline:
+  test-modeler:
+    input: modelerfour/identity
+    # scope : output-scope
+  test-modeler/identity:
+    input: test-modeler
+  typescript:
+    input: test-modeler/identity
+    output-artifact: typescript-files
+
+  typescript/emitter:
+    input: typescript
+    scope: typescript-scope/emitter
 
-output-artifact: typescript-files
 ```
 
 ### REST Client Generator overrides

package/dist/{src/generators/static/README.md.hbs → hlcREADME.md.hbs}

@@ -24,12 +24,15 @@ This package contains an isomorphic SDK (runs both in Node.js and in browsers) f
 - [LTS versions of Node.js](https://nodejs.org/about/releases/)
 - Latest versions of Safari, Chrome, Edge and Firefox.
 
+See our [support policy](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md) for more details.
+
 {{#if azure}}
 ### Prerequisites
 
 - An [Azure subscription][azure_sub].
 {{/if}}
 
+{{#if isReleasablePackage}}
 ### Install the `{{ clientPackageName }}` package
 
 Install the {{ clientDescriptiveName }} library for JavaScript with `npm`:
@@ -37,6 +40,7 @@ Install the {{ clientDescriptiveName }} library for JavaScript with `npm`:
 ```bash
 npm install {{ clientPackageName }}
 ```
+{{/if}}
 
 {{#if azure}}
 {{#if addCredentials}}
@@ -45,23 +49,55 @@ npm install {{ clientPackageName }}
 To create a client object to access the {{ serviceName }} API, you will need the `endpoint` of your {{ serviceName }} resource and a `credential`. The {{ clientDescriptiveName }} can use Azure Active Directory credentials to authenticate.
 You can find the endpoint for your {{ serviceName }} resource in the [Azure Portal][azure_portal].
 
-#### Using an Azure Active Directory Credential
+You can authenticate with Azure Active Directory using a credential from the [@azure/identity][azure_identity] library or [an existing AAD Token](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/samples/AzureIdentityExamples.md#authenticating-with-a-pre-fetched-access-token).
 
-You can authenticate with Azure Active Directory using the [Azure Identity library][azure_identity]. To use the [DefaultAzureCredential][defaultazurecredential] provider shown below, or other credential providers provided with the Azure SDK, please install the `@azure/identity` package:
+To use the [DefaultAzureCredential][defaultazurecredential] provider shown below, or other credential providers provided with the Azure SDK, please install the `@azure/identity` package:
 
 ```bash
 npm install @azure/identity
 ```
 
-You will also need to register a new AAD application and grant access to {{ serviceName}} by assigning the suitable role to your service principal (note: roles such as `"Owner"` will not grant the necessary permissions).
+You will also need to **register a new AAD application and grant access to {{ serviceName}}** by assigning the suitable role to your service principal (note: roles such as `"Owner"` will not grant the necessary permissions).
 Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`.
 
+For more information about how to create an Azure AD Application check out [this guide](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal).
+
+{{#if azureArm}}
 ```javascript
 const { {{ clientClassName }} } = require("{{ clientPackageName }}");
 const { DefaultAzureCredential } = require("@azure/identity");
+// For client-side applications running in the browser, use InteractiveBrowserCredential instead of DefaultAzureCredential. See https://aka.ms/azsdk/js/identity/examples for more details.
+
+const subscriptionId = "00000000-0000-0000-0000-000000000000";
+const client = new {{ clientClassName }}(new DefaultAzureCredential(), subscriptionId);
+
+// For client-side applications running in the browser, use this code instead:
+// const credential = new InteractiveBrowserCredential({
+//   tenantId: "<YOUR_TENANT_ID>",
+//   clientId: "<YOUR_CLIENT_ID>"
+// });
+// const client = new {{ clientClassName }}(credential, subscriptionId);
+```
+{{else}}
+```javascript
+const { {{ clientClassName }} } = require("{{ clientPackageName }}");
+const { DefaultAzureCredential } = require("@azure/identity");
+// For client-side applications running in the browser, use InteractiveBrowserCredential instead of DefaultAzureCredential. See https://aka.ms/azsdk/js/identity/examples for more details.
+
 const client = new {{ clientClassName }}("<endpoint>", new DefaultAzureCredential());
+// For client-side applications running in the browser, use this code instead:
+// const credential = new InteractiveBrowserCredential({
+//   tenantId: "<YOUR_TENANT_ID>",
+//   clientId: "<YOUR_CLIENT_ID>"
+// });
+// const client = new {{ clientClassName }}("<endpoint>", credential);
 ```
+{{/if}}
 {{/if}}{{/if}}
+
+### JavaScript Bundle
+To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our [bundling documentation](https://aka.ms/AzureSDKBundling).
+
 ## Key concepts
 
 ### {{ clientClassName }}
@@ -76,11 +112,11 @@ const client = new {{ clientClassName }}("<endpoint>", new DefaultAzureCredentia
 Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
 
 ```javascript
-import { setLogLevel } from "@azure/logger";
+const { setLogLevel } = require("@azure/logger");
 setLogLevel("info");
 ```
 
-For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs]({{ repoURL }}/tree/master/sdk/core/logger).
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs]({{ repoURL }}/tree/main/sdk/core/logger).
 
 {{#if samplesURL}}
 ## Next steps

package/dist/hlcSamples.ts.hbs

@@ -0,0 +1,49 @@
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import {
+{{#if importedTypes.length }}
+  {{#each importedTypes}}
+  {{this}},
+  {{/each}}
+{{/if}}
+  {{clientClassName}}, 
+} from "{{clientPackageName}}";
+import { DefaultAzureCredential } from "@azure/identity";
+
+{{#each samples}}
+/**
+ * This sample demonstrates how to {{this.operationDescription}}
+ *
+ * @summary {{this.operationDescription}}
+ * x-ms-original-file: {{this.originalFileLocation}}
+ */
+async function {{this.sampleFunctionName}}() {
+  {{#each this.clientParamAssignments}}
+  {{this}}
+  {{/each}}
+  {{#each this.methodParamAssignments}}
+  {{this}}
+  {{/each}}
+  const credential = new DefaultAzureCredential();
+  const client = new {{this.clientClassName}}({{this.clientParameterNames}});
+  {{#if this.isPaging}}
+  const resArray = new Array();
+  for await (let item of client{{#unless this.isTopLevel}}.{{this.operationGroupName}}{{/unless}}.{{this.operationName}}({{this.methodParameterNames}})){
+    resArray.push(item);
+  }
+  console.log(resArray);
+  {{else}}  
+  const result = await client
+    {{#unless this.isTopLevel}}
+    .{{this.operationGroupName}}
+    {{/unless}}
+    .{{this.operationName}}({{this.methodParameterNames}});
+  console.log(result);
+  
+  {{/if}}
+}
+
+{{this.sampleFunctionName}}().catch(console.error);
+
+{{/each}}

package/dist/karma.conf.js.hbs

@@ -0,0 +1,126 @@
+// https://github.com/karma-runner/karma-chrome-launcher
+process.env.CHROME_BIN = require("puppeteer").executablePath();
+require("dotenv").config();
+const { relativeRecordingsPath } = require("@azure-tools/test-recorder");
+process.env.RECORDINGS_RELATIVE_PATH = relativeRecordingsPath();
+
+module.exports = function (config) {
+  config.set({
+    // base path that will be used to resolve all patterns (eg. files, exclude)
+    basePath: "./",
+
+    // frameworks to use
+    // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
+    frameworks: ["source-map-support", "mocha"],
+
+    plugins: [
+      "karma-mocha",
+      "karma-mocha-reporter",
+      "karma-chrome-launcher",
+      "karma-edge-launcher",
+      "karma-firefox-launcher",
+      "karma-ie-launcher",
+      "karma-env-preprocessor",
+      "karma-coverage",
+      "karma-sourcemap-loader",
+      "karma-junit-reporter",
+      "karma-source-map-support",
+    ],
+
+    // list of files / patterns to load in the browser
+    files: [
+      "dist-test/index.browser.js",
+      { pattern: "dist-test/index.browser.js.map", type: "html", included: false, served: true },
+    ],
+
+    // list of files / patterns to exclude
+    exclude: [],
+
+    // preprocess matching files before serving them to the browser
+    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
+    preprocessors: {
+      "**/*.js": ["sourcemap", "env"],
+      // IMPORTANT: COMMENT following line if you want to debug in your browsers!!
+      // Preprocess source file to calculate code coverage, however this will make source file unreadable
+      // "dist-test/index.js": ["coverage"]
+    },
+
+    envPreprocessor: [
+      "TEST_MODE",
+      "ENDPOINT",
+      "AZURE_CLIENT_SECRET",
+      "AZURE_CLIENT_ID",
+      "AZURE_TENANT_ID",
+      "SUBSCRIPTION_ID",
+    ],
+
+    // test results reporter to use
+    // possible values: 'dots', 'progress'
+    // available reporters: https://npmjs.org/browse/keyword/karma-reporter
+    reporters: ["mocha", "coverage", "junit"],
+
+    coverageReporter: {
+      // specify a common output directory
+      dir: "coverage-browser/",
+      reporters: [
+        { type: "json", subdir: ".", file: "coverage.json" },
+        { type: "lcovonly", subdir: ".", file: "lcov.info" },
+        { type: "html", subdir: "html" },
+        { type: "cobertura", subdir: ".", file: "cobertura-coverage.xml" },
+      ],
+    },
+
+    junitReporter: {
+      outputDir: "", // results will be saved as $outputDir/$browserName.xml
+      outputFile: "test-results.browser.xml", // if included, results will be saved as $outputDir/$browserName/$outputFile
+      suite: "", // suite will become the package name attribute in xml testsuite element
+      useBrowserName: false, // add browser name to report and classes names
+      nameFormatter: undefined, // function (browser, result) to customize the name attribute in xml testcase element
+      classNameFormatter: undefined, // function (browser, result) to customize the classname attribute in xml testcase element
+      properties: {}, // key value pair of properties to add to the <properties> section of the report
+    },
+
+    // web server port
+    port: 9876,
+
+    // enable / disable colors in the output (reporters and logs)
+    colors: true,
+
+    // level of logging
+    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG
+    logLevel: config.LOG_INFO,
+
+    // enable / disable watching file and executing tests whenever any file changes
+    autoWatch: false,
+
+    // --no-sandbox allows our tests to run in Linux without having to change the system.
+    // --disable-web-security allows us to authenticate from the browser without having to write tests using interactive auth, which would be far more complex.
+    browsers: ["ChromeHeadlessNoSandbox"],
+    customLaunchers: {
+      ChromeHeadlessNoSandbox: {
+        base: "ChromeHeadless",
+        flags: ["--no-sandbox", "--disable-web-security"],
+      },
+    },
+
+    // Continuous Integration mode
+    // if true, Karma captures browsers, runs the tests and exits
+    singleRun: false,
+
+    // Concurrency level
+    // how many browser should be started simultaneous
+    concurrency: 1,
+
+    browserNoActivityTimeout: 60000000,
+    browserDisconnectTimeout: 10000,
+    browserDisconnectTolerance: 3,
+
+    client: {
+      mocha: {
+        // change Karma's debug.html to the mocha web reporter
+        reporter: "html",
+        timeout: "600000",
+      },
+    },
+  });
+};

package/dist/paginateHelper.ts.hbs

@@ -0,0 +1,208 @@
+import {
+  getPagedAsyncIterator,
+  PagedAsyncIterableIterator,
+  PagedResult
+} from "@azure/core-paging";
+import {
+  Client,
+  createRestError,
+  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;
+
+/**
+ * The type of a custom function that defines how to get a page and a link to the next one if any.
+ */
+export type GetPage<TPage> = (
+  pageLink: string,
+  maxPageSize?: number
+) => Promise<{
+  page: TPage;
+  nextPageLink?: string;
+}>;
+
+/**
+ * Options for the paging helper
+ */
+export interface PagingOptions<TResponse> {
+  /**
+   * Custom function to extract pagination details for crating the PagedAsyncIterableIterator
+  */
+  customGetPage?: GetPage<PaginateReturn<TResponse>[]>
+}
+
+/**
+ * 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  {{#each itemNames}}
+  {
+ 
+  body: { {{this}}?: infer TPage } 
+  
+} {{#if @last }}{{else}} | {{/if}}
+{{/each}}
+  ? GetArrayType<TPage>
+  : Array<unknown>;
+
+/**
+ * Helper to paginate results from an initial response that follows the specification of Autorest `x-ms-pageable` extension
+ * @param client - Client to use for sending the next page requests
+ * @param initialResponse - Initial response containing the nextLink and current page of elements
+ * @param customGetPage - Optional - Function to define how to extract the page and next link to be used to paginate the results
+ * @returns - PagedAsyncIterableIterator to iterate the elements
+ */
+export function paginate<TResponse extends PathUncheckedResponse>(
+  client: Client,
+  initialResponse: TResponse,
+  options: PagingOptions<TResponse> = {}
+): PagedAsyncIterableIterator<PaginateReturn<TResponse>> {
+  // Extract element type from initial response
+  type TElement = PaginateReturn<TResponse>;
+  let firstRun = true;
+  {{#if isComplexPaging}}
+  // We need to check the response for success before trying to inspect it looking for
+  // the properties to use for nextLink and itemName
+  checkPagingRequest(initialResponse);
+  const { itemName, nextLinkName } = getPaginationProperties(initialResponse);
+  {{else}}
+  const itemName = {{ quoteWrap itemNames }};
+  const nextLinkName = {{quoteWrap nextLinkNames}};
+  {{/if}}
+  const { customGetPage } = options;
+  const pagedResult: PagedResult<TElement[]> = {
+    firstPageLink: "",
+    getPage:
+      typeof customGetPage === "function"
+        ? customGetPage
+        : async (pageLink: string) => {
+            const result = firstRun
+              ? initialResponse
+              : await client.pathUnchecked(pageLink).get();
+            firstRun = false;
+            checkPagingRequest(result);
+            const nextLink = getNextLink(result.body, nextLinkName);
+            const values = getElements<TElement>(result.body, itemName);
+            return {
+              page: values,
+              nextPageLink: nextLink
+            };
+          }
+  };
+
+  return getPagedAsyncIterator(pagedResult);
+}
+
+/**
+ * Gets for the value of nextLink in the body
+ */
+function getNextLink(body: unknown, nextLinkName?: string): string | undefined {
+   if (!nextLinkName) {
+    return undefined;
+  }
+
+  const nextLink = (body as Record<string, unknown>)[nextLinkName];
+
+  if (typeof nextLink !== "string" && typeof nextLink !== "undefined") {
+    throw new Error(
+      `Body Property ${nextLinkName} should be a string or undefined`
+    );
+  }
+
+  return nextLink;
+}
+
+/**
+ * Gets the elements of the current request in the body.
+ */
+function getElements<T = unknown>(body: unknown, itemName: string): T[] {
+  const value = (body as Record<string, unknown>)[itemName] as T[];
+
+  // value has to be an array according to the x-ms-pageable extension.
+  // The fact that this must be an array is used above to calculate the
+  // type of elements in the page in PaginateReturn
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `Couldn't paginate response\n Body doesn't contain an array property with name: ${itemName}`
+    );
+  }
+
+  return value ?? [];
+}
+
+/**
+ * Checks if a request failed
+ */
+function checkPagingRequest(response: PathUncheckedResponse): void {
+  const Http2xxStatusCodes = [
+    "200",
+    "201",
+    "202",
+    "203",
+    "204",
+    "205",
+    "206",
+    "207",
+    "208",
+    "226"
+  ];
+  if (!Http2xxStatusCodes.includes(response.status)) {
+    throw createRestError(
+      `Pagination failed with unexpected statusCode ${response.status}`,
+      response
+    );
+  }
+}
+
+{{#if isComplexPaging}}
+/**
+ * Extracts the itemName and nextLinkName from the initial response to use them for pagination
+ */
+function getPaginationProperties(initialResponse: PathUncheckedResponse) {
+  // Build a set with the passed custom nextLinkNames
+  const nextLinkNames = new Set([{{ quoteWrap nextLinkNames }}]);
+
+  // Build a set with the passed custom set of itemNames
+  const itemNames = new Set([{{ quoteWrap itemNames }}]);
+
+  let nextLinkName: string | undefined;
+  let itemName: string | undefined;
+
+  for (const name of nextLinkNames) {
+    const nextLink = (initialResponse.body as Record<string, unknown>)[
+      name
+    ] as string;
+    if (nextLink) {
+      nextLinkName = name;
+      break;
+    }
+  }
+
+  for (const name of itemNames) {
+    const item = (initialResponse.body as Record<string, unknown>)[
+      name
+    ] as string;
+    if (item) {
+      itemName = name;
+      break;
+    }
+  }
+
+  if (!itemName) {
+    throw new Error(
+      `Couldn't paginate response\n Body doesn't contain an array property with name: ${[
+        ...itemNames
+      ].join(" OR ")}`
+    );
+  }
+
+  return { itemName, nextLinkName };
+}
+{{/if}}

package/dist/pollingHelper.ts.hbs

@@ -0,0 +1,72 @@
+import { Client, HttpResponse } from "@azure-rest/core-client";
+import {
+  LongRunningOperation,
+  LroEngine,
+  LroEngineOptions,
+  LroResponse,
+  PollerLike,
+  PollOperationState
+} from "@azure/core-lro";
+
+/**
+ * Helper function that builds a Poller object to help polling a long running operation.
+ * @param client - Client to use for sending the request to get additional pages.
+ * @param initialResponse - The initial response.
+ * @param options - Options to set a resume state or custom polling interval.
+ * @returns - A poller object to poll for operation state updates and eventually get the final response.
+ */
+export function getLongRunningPoller<TResult extends HttpResponse>(
+  client: Client,
+  initialResponse: TResult,
+  options: LroEngineOptions<TResult, PollOperationState<TResult>> = {}
+): PollerLike<PollOperationState<TResult>, TResult> {
+  const poller: LongRunningOperation<TResult> = {
+    requestMethod: initialResponse.request.method,
+    requestPath: initialResponse.request.url,
+    sendInitialRequest: async () => {
+      // In the case of Rest Clients we are building the LRO poller object from a response that's the reason
+      // we are not triggering the initial request here, just extracting the information from the
+      // response we were provided.
+      return getLroResponse(initialResponse);
+    },
+    sendPollRequest: async path => {
+      // This is the callback that is going to be called to poll the service
+      // to get the latest status. We use the client provided and the polling path
+      // which is an opaque URL provided by caller, the service sends this in one of the following headers: operation-location, azure-asyncoperation or location
+      // depending on the lro pattern that the service implements. If non is provided we default to the initial path.
+      const response = await client
+        .pathUnchecked(path ?? initialResponse.request.url)
+        .get();
+      const lroResponse = getLroResponse(response as TResult);
+      lroResponse.rawResponse.headers["x-ms-original-url"] =
+        initialResponse.request.url;
+      return lroResponse;
+    }
+  };
+
+  return new LroEngine(poller, options);
+}
+
+/**
+ * Converts a Rest Client response to a response that the LRO engine knows about
+ * @param response - a rest client http response
+ * @returns - An LRO response that the LRO engine can work with
+ */
+function getLroResponse<TResult extends HttpResponse>(
+  response: TResult
+): LroResponse<TResult> {
+  if (Number.isNaN(response.status)) {
+    throw new TypeError(
+      `Status code of the response is not a number. Value: ${response.status}`
+    );
+  }
+
+  return {
+    flatResponse: response,
+    rawResponse: {
+      ...response,
+      statusCode: Number.parseInt(response.status),
+      body: response.body
+    }
+  };
+}

package/dist/rlcEnv.ts.hbs

@@ -0,0 +1,3 @@
+import * as dotenv from "dotenv";
+
+dotenv.config();