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

package/types/interfaces.d.ts

@@ -0,0 +1,186 @@
+export interface RLCModel {
+    libraryName: string;
+    srcPath: string;
+    paths: Paths;
+    options?: RLCOptions;
+    schemas: Schema[];
+    apiVersionParam?: Parameter;
+    parameters?: OperationParameter[];
+    responses?: OperationResponse[];
+    importSet?: Map<ImportKind, Set<string>>;
+    annotations?: AnnotationDetails;
+    urlInfo?: UrlInfo;
+}
+export interface UrlInfo {
+    endpoint?: string;
+    urlParameters?: PathParameter[];
+}
+export interface AnnotationDetails {
+    hasPaging?: boolean;
+    hasLongRunning?: boolean;
+    pageDetails?: PagingDetails;
+}
+export interface PagingDetails {
+    itemNames: string[];
+    nextLinkNames: string[];
+    isComplexPaging: boolean;
+}
+export declare type Methods = {
+    [key: string]: [OperationMethod];
+};
+export interface ResponseTypes {
+    success: string[];
+    error: string[];
+}
+export interface OperationMethod {
+    optionsName: string;
+    description: string;
+    hasOptionalOptions: boolean;
+    returnType: string;
+    successStatus: string[];
+    responseTypes: ResponseTypes;
+    operationName: string;
+    annotations?: OperationAnnotations;
+}
+export interface PathMetadata {
+    name: string;
+    pathParameters: PathParameter[];
+    methods: Methods;
+    operationGroupName: string;
+    description: string;
+}
+export declare type Paths = Record<string, PathMetadata>;
+export declare type PathParameter = {
+    name: string;
+    type: string;
+    description?: string;
+};
+export interface OperationAnnotations {
+    isLongRunning?: boolean;
+    isPageable?: boolean;
+}
+export interface RLCOptions {
+    includeShortcuts?: boolean;
+    multiClient?: boolean;
+    batch?: any[];
+    packageDetails?: PackageDetails;
+    addCredentials?: boolean;
+    credentialScopes?: string[];
+    credentialKeyHeaderName?: string;
+    generateMetadata?: boolean;
+    generateTest?: boolean;
+    generateSample?: boolean;
+    azureSdkForJs?: boolean;
+    azureOutputDirectory?: string;
+    isCadlTest?: boolean;
+    title?: string;
+    dependencyInfo?: DependencyInfo;
+    productDocLink?: string;
+    serviceInfo?: ServiceInfo;
+    azureArm?: boolean;
+}
+export interface ServiceInfo {
+    title?: string;
+    description?: string;
+}
+export interface DependencyInfo {
+    link: string;
+    description: string;
+}
+export declare enum ImportKind {
+    ResponseOutput = 0,
+    ParameterInput = 1
+}
+export interface File {
+    path: string;
+    content: string;
+}
+export declare enum SchemaContext {
+    /** Schema is used as an input to an operation. */
+    Input = "input",
+    /** Schema is used as an output from an operation. */
+    Output = "output",
+    /** Schema is used as an exception from an operation. */
+    Exception = "exception"
+}
+export interface Schema {
+    name: string;
+    type: string;
+    typeName?: string;
+    outputTypeName?: string;
+    description?: string;
+    required?: boolean;
+    default?: any;
+    readOnly?: boolean;
+    usage?: SchemaContext[];
+}
+export interface ObjectSchema extends Schema {
+    properties?: Record<string, Schema>;
+    discriminatorValue?: string;
+    discriminator?: Schema;
+    isPolyParent?: boolean;
+    children?: {
+        all?: ObjectSchema[];
+        immediate?: ObjectSchema[];
+    };
+    parents?: {
+        all?: ObjectSchema[];
+        immediate?: ObjectSchema[];
+    };
+}
+export interface DictionarySchema extends Schema {
+    valueTypeName?: string;
+    outputValueTypeName?: string;
+}
+export interface Property extends Schema {
+}
+export interface Parameter extends Schema {
+}
+export interface PackageDetails {
+    name: string;
+    scopeName?: string;
+    nameWithoutScope?: string;
+    description?: string;
+    version: string;
+}
+export interface OperationParameter {
+    operationGroup: string;
+    operationName: string;
+    /**
+     * An operation with multiple request parameters means that
+     * the operation can get different values for content-type and each value
+     * may have a different type associated to it.
+     */
+    parameters: ParameterMetadatas[];
+}
+export interface ParameterMetadatas {
+    parameters?: ParameterMetadata[];
+    body?: ParameterBodyMetadata;
+}
+export interface ParameterBodyMetadata {
+    isPartialBody?: boolean;
+    body?: ParameterBodySchema[];
+}
+export declare type ParameterBodySchema = Schema;
+export interface ParameterMetadata {
+    type: "query" | "path" | "header";
+    name: string;
+    param: Schema;
+}
+export interface OperationResponse {
+    operationGroup: string;
+    operationName: string;
+    responses: ResponseMetadata[];
+}
+export interface ResponseMetadata {
+    statusCode: string;
+    description?: string;
+    headers?: ResponseHeaderSchema[];
+    body?: ResponseBodySchema;
+}
+export declare type ResponseHeaderSchema = Schema;
+export declare type ResponseBodySchema = Schema;
+export declare type ContentBuilder = {
+    (model: RLCModel): File | undefined;
+    (model: RLCModel, hasSampleGenerated?: boolean): File | undefined;
+};

package/types/metadata/buildApiExtractorConfig.d.ts

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

package/types/metadata/buildESLintConfig.d.ts

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

package/types/metadata/buildLicenseFile.d.ts

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

package/types/metadata/buildPackageFile.d.ts

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

package/types/metadata/buildReadmeFile.d.ts

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

package/types/metadata/buildRollupConfig.d.ts

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

package/types/metadata/buildTsConfig.d.ts

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

package/types/static/paginateContent.d.ts

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

package/types/static/pollingContent.d.ts

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

package/types/test/buildEnvFile.d.ts

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

package/types/test/buildKarmaConfig.d.ts

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

package/types/test/buildRecordedClient.d.ts

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

package/types/test/buildSampleTest.d.ts

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

package/types/test/template.d.ts

@@ -0,0 +1,5 @@
+export declare const envContent = "\nimport * as dotenv from \"dotenv\";\n\ndotenv.config();\n";
+export declare const envBrowserContent = "\nimport * as dotenv from \"dotenv\";\n\ndotenv.config();\n";
+export declare const karmaConfig = "\n// https://github.com/karma-runner/karma-chrome-launcher\nprocess.env.CHROME_BIN = require(\"puppeteer\").executablePath();\nrequire(\"dotenv\").config();\nconst { relativeRecordingsPath } = require(\"@azure-tools/test-recorder\");\nprocess.env.RECORDINGS_RELATIVE_PATH = relativeRecordingsPath();\n\nmodule.exports = function (config) {\n  config.set({\n    // base path that will be used to resolve all patterns (eg. files, exclude)\n    basePath: \"./\",\n\n    // frameworks to use\n    // available frameworks: https://npmjs.org/browse/keyword/karma-adapter\n    frameworks: [\"source-map-support\", \"mocha\"],\n\n    plugins: [\n      \"karma-mocha\",\n      \"karma-mocha-reporter\",\n      \"karma-chrome-launcher\",\n      \"karma-edge-launcher\",\n      \"karma-firefox-launcher\",\n      \"karma-ie-launcher\",\n      \"karma-env-preprocessor\",\n      \"karma-coverage\",\n      \"karma-sourcemap-loader\",\n      \"karma-junit-reporter\",\n      \"karma-source-map-support\",\n    ],\n\n    // list of files / patterns to load in the browser\n    files: [\n      \"dist-test/index.browser.js\",\n      { pattern: \"dist-test/index.browser.js.map\", type: \"html\", included: false, served: true },\n    ],\n\n    // list of files / patterns to exclude\n    exclude: [],\n\n    // preprocess matching files before serving them to the browser\n    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor\n    preprocessors: {\n      \"**/*.js\": [\"sourcemap\", \"env\"],\n      // IMPORTANT: COMMENT following line if you want to debug in your browsers!!\n      // Preprocess source file to calculate code coverage, however this will make source file unreadable\n      // \"dist-test/index.js\": [\"coverage\"]\n    },\n\n    envPreprocessor: [\n      \"TEST_MODE\",\n      \"ENDPOINT\",\n      \"AZURE_CLIENT_SECRET\",\n      \"AZURE_CLIENT_ID\",\n      \"AZURE_TENANT_ID\",\n      \"SUBSCRIPTION_ID\",\n    ],\n\n    // test results reporter to use\n    // possible values: 'dots', 'progress'\n    // available reporters: https://npmjs.org/browse/keyword/karma-reporter\n    reporters: [\"mocha\", \"coverage\", \"junit\"],\n\n    coverageReporter: {\n      // specify a common output directory\n      dir: \"coverage-browser/\",\n      reporters: [\n        { type: \"json\", subdir: \".\", file: \"coverage.json\" },\n        { type: \"lcovonly\", subdir: \".\", file: \"lcov.info\" },\n        { type: \"html\", subdir: \"html\" },\n        { type: \"cobertura\", subdir: \".\", file: \"cobertura-coverage.xml\" },\n      ],\n    },\n\n    junitReporter: {\n      outputDir: \"\", // results will be saved as $outputDir/$browserName.xml\n      outputFile: \"test-results.browser.xml\", // if included, results will be saved as $outputDir/$browserName/$outputFile\n      suite: \"\", // suite will become the package name attribute in xml testsuite element\n      useBrowserName: false, // add browser name to report and classes names\n      nameFormatter: undefined, // function (browser, result) to customize the name attribute in xml testcase element\n      classNameFormatter: undefined, // function (browser, result) to customize the classname attribute in xml testcase element\n      properties: {}, // key value pair of properties to add to the <properties> section of the report\n    },\n\n    // web server port\n    port: 9876,\n\n    // enable / disable colors in the output (reporters and logs)\n    colors: true,\n\n    // level of logging\n    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG\n    logLevel: config.LOG_INFO,\n\n    // enable / disable watching file and executing tests whenever any file changes\n    autoWatch: false,\n\n    // --no-sandbox allows our tests to run in Linux without having to change the system.\n    // --disable-web-security allows us to authenticate from the browser without having to write tests using interactive auth, which would be far more complex.\n    browsers: [\"ChromeHeadlessNoSandbox\"],\n    customLaunchers: {\n      ChromeHeadlessNoSandbox: {\n        base: \"ChromeHeadless\",\n        flags: [\"--no-sandbox\", \"--disable-web-security\"],\n      },\n    },\n\n    // Continuous Integration mode\n    // if true, Karma captures browsers, runs the tests and exits\n    singleRun: false,\n\n    // Concurrency level\n    // how many browser should be started simultaneous\n    concurrency: 1,\n\n    browserNoActivityTimeout: 60000000,\n    browserDisconnectTimeout: 10000,\n    browserDisconnectTolerance: 3,\n\n    client: {\n      mocha: {\n        // change Karma's debug.html to the mocha web reporter\n        reporter: \"html\",\n        timeout: \"600000\",\n      },\n    },\n  });\n};\n";
+export declare const recordedClientContent = "\nimport { Context } from \"mocha\";\nimport { Recorder, RecorderStartOptions } from \"@azure-tools/test-recorder\";\nimport \"./env\";\n\nconst envSetupForPlayback: Record<string, string> = {\n  ENDPOINT: \"https://endpoint\",\n  AZURE_CLIENT_ID: \"azure_client_id\",\n  AZURE_CLIENT_SECRET: \"azure_client_secret\",\n  AZURE_TENANT_ID: \"88888888-8888-8888-8888-888888888888\",\n  SUBSCRIPTION_ID: \"azure_subscription_id\"\n};\n\nconst recorderEnvSetup: RecorderStartOptions = {\n  envSetupForPlayback\n};\n\n/**\n* creates the recorder and reads the environment variables from the `.env` file.\n* Should be called first in the test suite to make sure environment variables are\n* read before they are being used.\n*/\nexport async function createRecorder(context: Context): Promise<Recorder> {\n  const recorder = new Recorder(context.currentTest);\n  await recorder.start(recorderEnvSetup);\n  return recorder;\n}\n";
+export declare const sampleTestContent = "\nimport { Recorder } from \"@azure-tools/test-recorder\";\nimport { assert } from \"chai\";\nimport { createRecorder } from \"./utils/recordedClient\";\nimport { Context } from \"mocha\";\n\ndescribe(\"My test\", () => {\n  let recorder: Recorder;\n\n  beforeEach(async function(this: Context) {\n    recorder = await createRecorder(this);\n  });\n\n  afterEach(async function() {\n    await recorder.stop();\n  });\n\n  it(\"sample test\", async function() {\n    assert.equal(1, 1);\n  });\n});\n";