@azure-tools/rlc-common 0.11.0

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}}
+`;

package/src/static/pollingContent.ts

@@ -0,0 +1,94 @@
+export const pollingContent = `
+import { Client, HttpResponse } from "@azure-rest/core-client";
+{{#if useLegacyLro}}
+import {
+  LongRunningOperation,
+  LroEngine,
+  LroEngineOptions,
+  LroResponse,
+  PollerLike,
+  PollOperationState
+} from "@azure/core-lro";
+{{else}}
+import {
+  CreateHttpPollerOptions,
+  LongRunningOperation,
+  LroResponse,
+  OperationState,
+  SimplePollerLike,
+  createHttpPoller
+} from "@azure/core-lro";
+{{/if}}
+/**
+ * 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 {{#unless useLegacyLro}}async {{/unless}}function getLongRunningPoller<TResult extends HttpResponse>(
+  client: Client,
+  initialResponse: TResult,
+  {{#if useLegacyLro}}
+  options: LroEngineOptions<TResult, PollOperationState<TResult>> = {}
+  ): PollerLike<PollOperationState<TResult>, TResult> {
+    {{else}}
+    options: CreateHttpPollerOptions<TResult, OperationState<TResult>> = {}
+    ): Promise<SimplePollerLike<OperationState<TResult>, TResult>> {
+    {{/if}}  
+    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;
+    }
+  };
+
+  {{#if useLegacyLro}}
+  return new LroEngine(poller, options);
+  {{else}}
+  options.resolveOnUnsuccessful = options.resolveOnUnsuccessful ?? true;
+  return await createHttpPoller(poller, options);
+  {{/if}}
+}
+
+/**
+ * Converts a Rest Client response to a response that the LRO implementation understands
+ * @param response - a rest client http response
+ * @returns - An LRO response that the LRO implementation understands
+ */
+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/src/static/serializeHelper.ts

@@ -0,0 +1,29 @@
+export const buildMultiCollectionContent = `
+export function buildMultiCollection(
+  queryParameters: string[],
+  parameterName: string
+) {
+  return queryParameters
+    .map((item, index) => {
+      if (index === 0) {
+        return item;
+      }
+      return \`\${parameterName}=\${item}\`;
+    })
+    .join("&");
+}`;
+
+export const buildPipeCollectionContent = `
+export function buildPipeCollection(queryParameters: string[]): string {
+  return queryParameters.join("|");
+}`;
+
+export const buildSsvCollectionContent = `
+export function buildSsvCollection(queryParameters: string[]): string {
+  return queryParameters.join(" ");
+}`;
+
+export const buildTsvCollectionContent = `
+export function buildTsvCollection(queryParameters: string[]) {
+  return queryParameters.join("\\t");
+}`;

package/src/test/buildEnvFile.ts

@@ -0,0 +1,26 @@
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { envContent } from "./template.js";
+import { RLCModel } from "../interfaces.js";
+
+export function buildEnvFile(model: RLCModel) {
+  const generateTest = Boolean(model.options?.generateTest);
+  if (!generateTest) {
+    return;
+  }
+  return {
+    path: "test/public/utils/env.ts",
+    content: hbs.compile(envContent, { noEscape: true })({})
+  };
+}
+
+export function buildEnvBrowserFile(model: RLCModel) {
+  const generateTest = Boolean(model.options?.generateTest);
+  if (!generateTest) {
+    return;
+  }
+  return {
+    path: "test/public/utils/env.browser.ts",
+    content: hbs.compile("", { noEscape: true })({})
+  };
+}

package/src/test/buildKarmaConfig.ts

@@ -0,0 +1,15 @@
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { karmaConfig } from "./template.js";
+
+export function buildKarmaConfigFile(model: RLCModel) {
+  const generateTest = Boolean(model.options?.generateTest);
+  if (!generateTest) {
+    return;
+  }
+  return {
+    path: "karma.conf.js",
+    content: hbs.compile(karmaConfig, { noEscape: true })({})
+  };
+}

package/src/test/buildRecordedClient.ts

@@ -0,0 +1,18 @@
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { RLCModel } from "../interfaces.js";
+import { recordedClientContent } from "./template.js";
+
+export function buildRecordedClientFile(model: RLCModel) {
+  const generateTest = Boolean(model.options?.generateTest);
+  if (!generateTest) {
+    return;
+  }
+  const recordedClientFileContents = hbs.compile(recordedClientContent, {
+    noEscape: true
+  });
+  return {
+    path: "test/public/utils/recordedClient.ts",
+    content: recordedClientFileContents({})
+  };
+}

package/src/test/buildSampleTest.ts

@@ -0,0 +1,15 @@
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { sampleTestContent } from "./template.js";
+import { RLCModel } from "../interfaces.js";
+
+export function buildSampleTest(model: RLCModel) {
+  const generateTest = Boolean(model.options?.generateTest);
+  if (!generateTest) {
+    return;
+  }
+  return {
+    path: "test/public/sampleTest.spec.ts",
+    content: hbs.compile(sampleTestContent, { noEscape: true })({})
+  };
+}