@azure-tools/rlc-common 1.0.0-beta.1

package/src/metadata/buildReadmeFile.ts

@@ -0,0 +1,231 @@
+import { RLCModel } from "../interfaces.js";
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { NameType, normalizeName } from "../helpers/nameUtils.js";
+
+const readmeTemplate = `# {{ clientDescriptiveName }} library for JavaScript
+
+{{ description }}
+
+{{#if azureArm}}
+**If you are not familiar with our REST client, please spend 5 minutes to take a look at {{#if serviceDocURL}}[the service's documentation]({{ serviceDocURL }}) and {{/if}}our [REST client docs](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/rest-clients.md) to use this library, the REST client provides a light-weighted & developer friendly way to call azure rest api
+{{else}}
+**Please rely heavily on {{#if serviceDocURL}}[the service's documentation]({{ serviceDocURL }}) and {{/if}}our [REST client docs](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/rest-clients.md) to use this library**
+{{/if}}
+
+Key links:
+
+{{#if packageSourceURL}}
+- [Source code]({{ packageSourceURL }})
+{{/if}}
+{{#if packageNPMURL}}
+- [Package (NPM)]({{ packageNPMURL }})
+{{/if}}
+{{#if apiRefURL}}
+- [API reference documentation]({{ apiRefURL }})
+{{/if}}
+{{#if serviceDocURL}}
+- [Product documentation]({{ serviceDocURL }})
+{{/if}}
+{{#if samplesURL}}
+- [Samples]({{ samplesURL }})
+{{/if}}
+
+## Getting started
+
+### Currently supported environments
+
+- Node.js version 14.x.x or higher
+
+### Prerequisites
+
+- You must have an [Azure subscription](https://azure.microsoft.com/free/){{#if dependencyLink}} and follow [these]({{ dependencyLink }}) instructions{{/if}} to use this package.
+
+### Install the \`{{ clientPackageName }}\` package
+
+Install the {{ clientDescriptiveName }} REST client library for JavaScript with \`npm\`:
+
+\`\`\`bash
+npm install {{ clientPackageName }}
+\`\`\`
+
+### Create and authenticate a \`{{ clientClassName }}\`
+
+To use an [Azure Active Directory (AAD) token credential](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#authenticating-with-a-pre-fetched-access-token),
+provide an instance of the desired credential type obtained from the
+[@azure/identity](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#credentials) library.
+
+To authenticate with AAD, you must first \`npm\` install [\`@azure/identity\`](https://www.npmjs.com/package/@azure/identity) {{#if dependencyLink}}and
+[{{dependencyDescription }}]({{ dependencyLink }}){{/if}}
+
+After setup, you can choose which type of [credential](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#credentials) from \`@azure/identity\` to use.
+As an example, [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential)
+can be used to authenticate the client.
+
+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
+
+## Troubleshooting
+
+### Logging
+
+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";
+
+setLogLevel("info");
+\`\`\`
+
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).
+`;
+
+/**
+ * Meta data information about the service, the package, and the client.
+ */
+interface Metadata {
+  /** The name of the service */
+  serviceName: string;
+  /** The name of the package */
+  clientPackageName: string;
+  /** The name of the client class */
+  clientClassName: string;
+  /** The URL of the repository the package lives in */
+  repoURL?: string;
+  /** The URL to the package directory in the repository */
+  packageSourceURL?: string;
+  /** The URL to the package's samples */
+  samplesURL?: string;
+  /** A descriptive name for the client extracted from the swagger */
+  clientDescriptiveName?: string;
+  /** A description for the service extracted from the swagger */
+  description?: string;
+  /** The URL to the package on npmjs.org */
+  packageNPMURL?: string;
+  /** The name of the project that lives in the repository */
+  projectName?: string;
+  /** whether the client accepts standard credentials */
+  addCredentials?: boolean;
+  /** The link to the identity package in the repository */
+  identityPackageURL?: string;
+  /** The URL for the service document */
+  serviceDocURL?: string;
+  /** The dependency info for this service */
+  dependencyDescription?: string;
+  dependencyLink?: string;
+  /** Indicates if the package is a multi-client */
+  hasMultiClients?: boolean;
+  /** The URL to the API reference */
+  apiRefURL?: string;
+  /** Check if the rp is management plane */
+  azureArm?: boolean;
+}
+
+export function buildReadmeFile(model: RLCModel) {
+  const generateMetadata = Boolean(model.options?.generateMetadata);
+  if (!generateMetadata) {
+    return;
+  }
+
+  const metadata = createMetadata(model) ?? {};
+  const readmeFileContents = hbs.compile(readmeTemplate, { noEscape: true });
+  return {
+    path: "README.md",
+    content: readmeFileContents(metadata)
+  };
+}
+
+/**
+ * Returns meta data information about the service, the package, and the client.
+ * @param codeModel - include the client details
+ * @returns inferred metadata about the service, the package, and the client
+ */
+function createMetadata(model: RLCModel): Metadata | undefined {
+  if (!model.options || !model.options.packageDetails) {
+    return;
+  }
+  // const packageDetails = model.options.packageDetails;
+  const {
+    packageDetails,
+    azureOutputDirectory,
+    productDocLink,
+    dependencyInfo,
+    multiClient,
+    batch,
+    serviceInfo
+  } = model.options;
+
+  const azureHuh =
+    packageDetails?.scopeName === "azure" ||
+    packageDetails?.scopeName === "azure-rest";
+  const repoURL = "https://github.com/Azure/azure-sdk-for-js";
+  const relativePackageSourcePath = azureOutputDirectory;
+  const packageSourceURL =
+    relativePackageSourcePath &&
+    repoURL &&
+    `${repoURL}/tree/main/${relativePackageSourcePath}`;
+
+  const clientPackageName = packageDetails?.name;
+  const clientClassName = getClientName(model);
+  const serviceName = getServiceName(model);
+  var apiRefUrlQueryParameter: string = "";
+  if (packageDetails?.version.includes("beta")) {
+    apiRefUrlQueryParameter = "?view=azure-node-preview";
+  }
+
+  return {
+    serviceName,
+    clientClassName,
+    clientPackageName: clientPackageName,
+    clientDescriptiveName: `${serviceName} REST client`,
+    description: serviceInfo?.description ?? packageDetails.description,
+    serviceDocURL: productDocLink,
+    packageSourceURL: packageSourceURL,
+    packageNPMURL: `https://www.npmjs.com/package/${clientPackageName}`,
+    samplesURL: packageSourceURL && `${packageSourceURL}/samples`,
+    apiRefURL: azureHuh
+      ? `https://docs.microsoft.com/javascript/api/${clientPackageName}${apiRefUrlQueryParameter}`
+      : undefined,
+    dependencyDescription: dependencyInfo?.description,
+    dependencyLink: dependencyInfo?.link,
+    hasMultiClients: multiClient && batch && batch.length > 1,
+    azureArm: Boolean(model.options.azureArm)
+  };
+}
+
+function getServiceName(model: RLCModel) {
+  const azureHuh =
+    model?.options?.packageDetails?.scopeName === "azure" ||
+    model?.options?.packageDetails?.scopeName === "azure-rest";
+  const libraryName = model.libraryName;
+  const serviceTitle = model.options?.serviceInfo?.title ?? model.libraryName;
+  const batch = model?.options?.batch,
+    packageDetails = model?.options?.packageDetails!;
+  let simpleServiceName =
+    batch && batch.length > 1
+      ? normalizeName(packageDetails.nameWithoutScope || "", NameType.Class)
+      : normalizeName(serviceTitle, NameType.Class);
+  simpleServiceName =
+    /**
+     * It is a required convention in Azure swaggers for their titles to end with
+     * "Client".
+     */
+    serviceTitle.match(/(.*) Client/)?.[1] ??
+    serviceTitle.match(/(.*)Client/)?.[1] ??
+    libraryName.match(/(.*)Client/)?.[1] ??
+    serviceTitle.match(/(.*) Service/)?.[1] ??
+    simpleServiceName;
+
+  return azureHuh
+    ? simpleServiceName.startsWith("Azure")
+      ? simpleServiceName
+      : `Azure ${simpleServiceName}`
+    : simpleServiceName;
+}
+
+function getClientName(model: RLCModel) {
+  const clientName = model.libraryName;
+  return clientName.endsWith("Client")
+    ? `${clientName}`
+    : `${clientName}Client`;
+}

package/src/metadata/buildRollupConfig.ts

@@ -0,0 +1,147 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+export function buildRollupConfig(model: RLCModel) {
+  const generateMetadata = Boolean(model.options?.generateMetadata),
+    azureSdkForJs = Boolean(model.options?.azureSdkForJs);
+  // when it's generating rlc codes, only generate rollup config in codegen test
+  if (!generateMetadata || azureSdkForJs) {
+    return;
+  }
+
+  const project = new Project();
+  const filePath = "rollup.config.js";
+  const rollupFile = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+
+  rollupFile.addStatements(
+    `import nodeResolve from "@rollup/plugin-node-resolve";
+    import cjs from "@rollup/plugin-commonjs";
+    import sourcemaps from "rollup-plugin-sourcemaps";
+    import multiEntry from "@rollup/plugin-multi-entry";
+    import json from "@rollup/plugin-json";
+    
+    import nodeBuiltins from "builtin-modules";
+    
+    // #region Warning Handler
+    
+    /**
+     * A function that can determine whether a rollup warning should be ignored. If
+     * the function returns \`true\`, then the warning will not be displayed.
+     */
+    
+    function ignoreNiseSinonEval(warning) {
+      return (
+        warning.code === "EVAL" &&
+        (warning.id && ((warning.id.includes("node_modules/nise")) ||
+          warning.id.includes("node_modules/sinon")) === true)
+      );
+    }
+    
+    function ignoreChaiCircularDependency(warning) {
+      return (
+        warning.code === "CIRCULAR_DEPENDENCY" &&
+        (warning.importer && warning.importer.includes("node_modules/chai") === true)
+      );
+    }
+    
+    const warningInhibitors = [
+      ignoreChaiCircularDependency,
+      ignoreNiseSinonEval
+    ];
+    
+    /**
+     * Construct a warning handler for the shared rollup configuration
+     * that ignores certain warnings that are not relevant to testing.
+     */
+    function makeOnWarnForTesting() {
+      return (warning, warn) => {
+        // If every inhibitor returns false (i.e. no inhibitors), then show the warning
+        if (warningInhibitors.every(inhib => !inhib(warning))) {
+          warn(warning);
+        }
+      };
+    }
+    
+    // #endregion
+    
+    function makeBrowserTestConfig() {
+      const config = {
+        input: {
+          include: ["dist-esm/test/**/*.spec.js"],
+          exclude: ["dist-esm/test/**/node/**"]
+        },
+        output: {
+          file: \`dist-test/index.browser.js\`,
+          format: "umd",
+          sourcemap: true
+        },
+        preserveSymlinks: false,
+        plugins: [
+          multiEntry({ exports: false }),
+          nodeResolve({
+            mainFields: ["module", "browser"]
+          }),
+          cjs(),
+          json(),
+          sourcemaps()
+          //viz({ filename: "dist-test/browser-stats.html", sourcemap: true })
+        ],
+        onwarn: makeOnWarnForTesting(),
+        // Disable tree-shaking of test code.  In rollup-plugin-node-resolve@5.0.0,
+        // rollup started respecting the "sideEffects" field in package.json.  Since
+        // our package.json sets "sideEffects=false", this also applies to test
+        // code, which causes all tests to be removed by tree-shaking.
+        treeshake: false
+      };
+    
+      return config;
+    }
+    
+    const defaultConfigurationOptions = {
+      disableBrowserBundle: false
+    };
+    
+    export function makeConfig(
+      pkg,
+      options
+    ) {
+      options = {
+        ...defaultConfigurationOptions,
+        ...(options || {})
+      };
+    
+      const baseConfig = {
+        // Use the package's module field if it has one
+        input: pkg["module"] || "dist-esm/src/index.js",
+        external: [
+          ...nodeBuiltins,
+          ...Object.keys(pkg.dependencies),
+          ...Object.keys(pkg.devDependencies)
+        ],
+        output: { file: "dist/index.js", format: "cjs", sourcemap: true },
+        preserveSymlinks: false,
+        plugins: [sourcemaps(), nodeResolve()]
+      };
+    
+      const config = [baseConfig];
+    
+      if (!options.disableBrowserBundle) {
+        config.push(makeBrowserTestConfig());
+      }
+    
+      return config;
+    }
+    
+    export default makeConfig(require("./package.json"));`
+  );
+
+  return {
+    path: filePath,
+    content: rollupFile.getFullText()
+  };
+}

package/src/metadata/buildTsConfig.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import { RLCModel } from "../interfaces.js";
+
+const restLevelTsConfigInAzureSdkForJs: Record<string, any> = {
+  extends: "../../../tsconfig.package",
+  compilerOptions: {
+    outDir: "./dist-esm",
+    declarationDir: "./types"
+  },
+  include: ["src/**/*.ts"]
+};
+
+const restLevelTsConfigNotInAzureSdkForJs: Record<string, any> = {
+  compilerOptions: {
+    target: "ES2017",
+    module: "es6",
+    lib: [],
+    declaration: true,
+    declarationMap: true,
+    inlineSources: true,
+    sourceMap: true,
+    importHelpers: true,
+    strict: true,
+    alwaysStrict: true,
+    noUnusedLocals: true,
+    noUnusedParameters: true,
+    noImplicitReturns: true,
+    noFallthroughCasesInSwitch: true,
+    forceConsistentCasingInFileNames: true,
+    moduleResolution: "node",
+    allowSyntheticDefaultImports: true,
+    esModuleInterop: true,
+    outDir: "./dist-esm",
+    declarationDir: "./types"
+  },
+  include: ["./src/**/*.ts"]
+};
+
+export function buildTsConfig(model: RLCModel, hasSamplesGenerated = false) {
+  const generateMetadata = Boolean(model.options?.generateMetadata);
+  if (!generateMetadata) {
+    return;
+  }
+  const { generateTest, packageDetails, generateSample, azureSdkForJs } =
+    model.options || {};
+  const clientPackageName = packageDetails?.name ?? "";
+  const project = new Project();
+
+  const restLevelTsConfig = azureSdkForJs
+    ? restLevelTsConfigInAzureSdkForJs
+    : restLevelTsConfigNotInAzureSdkForJs;
+
+  if (generateTest) {
+    restLevelTsConfig.include.push("./test/**/*.ts");
+  }
+  if (generateSample && hasSamplesGenerated) {
+    restLevelTsConfig.include.push("samples-dev/**/*.ts");
+    restLevelTsConfig.compilerOptions["paths"] = {};
+    restLevelTsConfig.compilerOptions["paths"][clientPackageName] = [
+      "./src/index"
+    ];
+  }
+
+  const filePath = "tsconfig.json";
+  const configFile = project.createSourceFile(
+    filePath,
+    JSON.stringify(restLevelTsConfig),
+    {
+      overwrite: true
+    }
+  );
+  return {
+    path: filePath,
+    content: configFile.getFullText()
+  };
+}

package/src/static/paginateContent.ts

@@ -0,0 +1,210 @@
+export const paginateContent = `
+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}}
+`;