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

package/src/static/pollingContent.ts

@@ -0,0 +1,74 @@
+export const pollingContent = `
+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/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 })({})
+  };
+}

package/src/test/template.ts

@@ -0,0 +1,192 @@
+export const envContent = `
+import * as dotenv from "dotenv";
+
+dotenv.config();
+`;
+
+export const envBrowserContent = `
+import * as dotenv from "dotenv";
+
+dotenv.config();
+`;
+
+export const karmaConfig = `
+// 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",
+      },
+    },
+  });
+};
+`;
+
+export const recordedClientContent = `
+import { Context } from "mocha";
+import { Recorder, RecorderStartOptions } from "@azure-tools/test-recorder";
+import "./env";
+
+const envSetupForPlayback: Record<string, string> = {
+  ENDPOINT: "https://endpoint",
+  AZURE_CLIENT_ID: "azure_client_id",
+  AZURE_CLIENT_SECRET: "azure_client_secret",
+  AZURE_TENANT_ID: "88888888-8888-8888-8888-888888888888",
+  SUBSCRIPTION_ID: "azure_subscription_id"
+};
+
+const recorderEnvSetup: RecorderStartOptions = {
+  envSetupForPlayback
+};
+
+/**
+* creates the recorder and reads the environment variables from the \`.env\` file.
+* Should be called first in the test suite to make sure environment variables are
+* read before they are being used.
+*/
+export async function createRecorder(context: Context): Promise<Recorder> {
+  const recorder = new Recorder(context.currentTest);
+  await recorder.start(recorderEnvSetup);
+  return recorder;
+}
+`;
+
+export const sampleTestContent = `
+import { Recorder } from "@azure-tools/test-recorder";
+import { assert } from "chai";
+import { createRecorder } from "./utils/recordedClient";
+import { Context } from "mocha";
+
+describe("My test", () => {
+  let recorder: Recorder;
+
+  beforeEach(async function(this: Context) {
+    recorder = await createRecorder(this);
+  });
+
+  afterEach(async function() {
+    await recorder.stop();
+  });
+
+  it("sample test", async function() {
+    assert.equal(1, 1);
+  });
+});
+`;

package/tsconfig-cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig-common.json",
+  "compilerOptions": {
+    "sourceMap": true,
+    "module": "commonjs",
+    "outDir": "dist/",
+    "target": "es2015"
+  }
+}

package/tsconfig-common.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "./types",
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+    /* Type Checking */
+    "strict": true /* Enable all strict type-checking options. */,
+    "skipLibCheck": true
+  },
+  "compileOnSave": false,
+  "exclude": ["node_modules", "dist"],
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig-common.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "outDir": "dist-esm/",
+    "target": "esnext",
+    "moduleResolution": "node",
+    "sourceMap": true
+  },
+  "ts-node": {
+    "esm": true
+  }
+}

package/types/buildClient.d.ts

@@ -0,0 +1,2 @@
+import { RLCModel, File } from "./interfaces.js";
+export declare function buildClient(model: RLCModel): File | undefined;

package/types/buildClientDefinitions.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildClientDefinitions(model: RLCModel): {
+    path: string;
+    content: string;
+};

package/types/buildIndexFile.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildIndexFile(model: RLCModel): {
+    path: string;
+    content: string;
+};

package/types/buildIsUnexpectedHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildIsUnexpectedHelper(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildMethodShortcuts.d.ts

@@ -0,0 +1,4 @@
+import { ReservedName } from "./helpers/nameUtils.js";
+import { Paths } from "./interfaces.js";
+export declare const REST_CLIENT_RESERVED: ReservedName[];
+export declare function buildMethodShortcutImplementation(paths: Paths): Record<string, string[]>;

package/types/buildObjectTypes.d.ts

@@ -0,0 +1,14 @@
+import { InterfaceDeclarationStructure, PropertySignatureStructure, TypeAliasDeclarationStructure } from "ts-morph";
+import { Parameter, Property, RLCModel, SchemaContext } from "./interfaces.js";
+/**
+ * Generates interfaces for ObjectSchemas
+ */
+export declare function buildObjectInterfaces(model: RLCModel, importedModels: Set<string>, schemaUsage: SchemaContext[]): InterfaceDeclarationStructure[];
+export declare function buildPolymorphicAliases(model: RLCModel, schemaUsage: SchemaContext[]): TypeAliasDeclarationStructure[];
+/**
+ * Builds a Typescript property or parameter signature
+ * @param property - Property or parameter to get the Typescript signature for
+ * @param importedModels - Set to track the models that need to be imported
+ * @returns a PropertySignatureStructure for the property.
+ */
+export declare function getPropertySignature(property: Property | Parameter, schemaUsage: SchemaContext[], importedModels?: Set<string>): PropertySignatureStructure;

package/types/buildPaginateHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildPaginateHelper(model: RLCModel): {
+    path: string;
+    content: any;
+} | undefined;

package/types/buildParameterTypes.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildParameterTypes(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildPollingHelper.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildPollingHelper(model: RLCModel): {
+    path: string;
+    content: any;
+} | undefined;

package/types/buildResponseTypes.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildResponseTypes(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildSchemaType.d.ts

@@ -0,0 +1,19 @@
+import { Project } from "ts-morph";
+import { RLCModel, SchemaContext } from "./interfaces.js";
+/**
+ * Generates types to represent schema definitions in the swagger
+ */
+export declare function buildSchemaTypes(model: RLCModel): {
+    inputModelFile: {
+        path: string;
+        content: string;
+    } | undefined;
+    outputModelFile: {
+        path: string;
+        content: string;
+    } | undefined;
+};
+export declare function generateModelFiles(model: RLCModel, project: Project, filePath: string, schemaContext: SchemaContext[]): {
+    path: string;
+    content: string;
+} | undefined;

package/types/buildTopLevelIndexFile.d.ts

@@ -0,0 +1,5 @@
+import { RLCModel } from "./interfaces.js";
+export declare function buildTopLevelIndex(model: RLCModel): {
+    path: string;
+    content: string;
+} | undefined;

package/types/helpers/nameConstructors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Get the response type name by baseName or operatioName & statusCode
+ * @param baseResponseName
+ */
+export declare function getResponseTypeName(baseResponseName: string): string;
+export declare function getResponseTypeName(operationGroup: string, operationName: string, statusCode: string): string;
+/**
+ * The prefix of all response types
+ * @param operationGroup operation group name e.g string_PutEmpty
+ * @param operationName operation name D e.g string_PutEmpty
+ * @param statusCode 2XX, 4XX, 5XX, default etc.
+ * @returns normolized base name e.g StringPutEmpty200
+ */
+export declare function getResponseBaseName(operationGroup: string, operationName: string, statusCode: string): string;
+/**
+ * The prefix of all parameter relevant types
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns
+ */
+export declare function getParameterBaseName(operationGroup: string, operationName: string): string;
+/**
+ * Get the top-layer parameter name
+ * @param operationGroup operation group name
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns top-layer parameter name e.g StringPutEmptParameters
+ */
+export declare function getParameterTypeName(baseName: string): string;
+export declare function getParameterTypeName(operationGroup: string, operationName: string): string;

package/types/helpers/nameUtils.d.ts

@@ -0,0 +1,25 @@
+export interface ReservedName {
+    name: string;
+    reservedFor: NameType[];
+}
+export declare enum NameType {
+    Class = 0,
+    File = 1,
+    Interface = 2,
+    Property = 3,
+    Parameter = 4,
+    Operation = 5,
+    OperationGroup = 6
+}
+export declare enum CasingConvention {
+    Pascal = 0,
+    Camel = 1
+}
+export declare function guardReservedNames(name: string, nameType: NameType, customReservedNames?: ReservedName[]): string;
+export declare function normalizeName(name: string, nameType: NameType, shouldGuard?: boolean, customReservedNames?: ReservedName[], casingOverride?: CasingConvention): string;
+export declare function getModelsName(title: string): string;
+export declare function getMappersName(title: string): string;
+export declare function pascalCase(str: string): string;
+export declare function camelCase(str: string, options?: {
+    uppercaseThreshold?: number;
+}): string;

package/types/helpers/operationHelpers.d.ts

@@ -0,0 +1,9 @@
+import { MethodSignatureStructure, OptionalKind, ParameterDeclarationStructure } from "ts-morph";
+import { Methods, PathParameter, RLCModel } from "../interfaces.js";
+export declare function buildMethodDefinitions(methods: Methods, pathParams?: PathParameter[]): OptionalKind<MethodSignatureStructure>[];
+export declare function getPathParamDefinitions(pathParams: PathParameter[]): OptionalKind<ParameterDeclarationStructure>[];
+export declare function hasPagingOperations(model: RLCModel): boolean;
+export declare function hasPollingOperations(model: RLCModel): boolean;
+export declare function hasUnexpectedHelper(model: RLCModel): boolean;
+export declare function hasInputModels(model: RLCModel): boolean;
+export declare function hasOutputModels(model: RLCModel): boolean;

package/types/helpers/schemaHelpers.d.ts

@@ -0,0 +1,4 @@
+import { Schema } from "../interfaces.js";
+export declare function isDictionarySchema(schema: Schema): boolean;
+export declare function isObjectSchema(schema: Schema): boolean;
+export declare function isConstantSchema(schema: Schema): boolean;

package/types/helpers/shortcutMethods.d.ts

@@ -0,0 +1,3 @@
+import { OptionalKind, InterfaceDeclarationStructure } from "ts-morph";
+import { Paths } from "../interfaces.js";
+export declare function generateMethodShortcuts(paths: Paths): OptionalKind<InterfaceDeclarationStructure>[];

package/types/index.d.ts

@@ -0,0 +1,25 @@
+export * from "./interfaces.js";
+export * from "./buildClientDefinitions.js";
+export * from "./buildSchemaType.js";
+export * from "./buildClient.js";
+export * from "./helpers/nameConstructors.js";
+export * from "./buildResponseTypes.js";
+export * from "./helpers/shortcutMethods.js";
+export * from "./helpers/nameUtils.js";
+export * from "./buildParameterTypes.js";
+export * from "./buildIsUnexpectedHelper.js";
+export * from "./buildTopLevelIndexFile.js";
+export * from "./buildIndexFile.js";
+export * from "./buildPaginateHelper.js";
+export * from "./buildPollingHelper.js";
+export * from "./test/buildKarmaConfig.js";
+export * from "./test/buildEnvFile.js";
+export * from "./test/buildRecordedClient.js";
+export * from "./test/buildSampleTest.js";
+export * from "./metadata/buildReadmeFile.js";
+export * from "./metadata/buildApiExtractorConfig.js";
+export * from "./metadata/buildPackageFile.js";
+export * from "./metadata/buildRollupConfig.js";
+export * from "./metadata/buildTsConfig.js";
+export * from "./metadata/buildESLintConfig.js";
+export * from "./metadata/buildLicenseFile.js";