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

package/src/buildParameterTypes.ts

@@ -0,0 +1,435 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  InterfaceDeclarationStructure,
+  Project,
+  PropertySignatureStructure,
+  SourceFile,
+  StructureKind
+} from "ts-morph";
+import * as path from "path";
+import {
+  ImportKind,
+  ParameterMetadata,
+  ParameterMetadatas,
+  RLCModel,
+  Schema
+} from "./interfaces.js";
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import {
+  getParameterBaseName,
+  getParameterTypeName
+} from "./helpers/nameConstructors.js";
+
+export function buildParameterTypes(model: RLCModel) {
+  const project = new Project();
+  const srcPath = model.srcPath;
+  const filePath = path.join(srcPath, `parameters.ts`);
+  const parametersFile = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+  let hasHeaders = false;
+
+  if (!model.parameters) {
+    return;
+  }
+  for (const requestParameter of model.parameters) {
+    const baseParameterName = getParameterBaseName(
+      requestParameter.operationGroup,
+      requestParameter.operationName
+    );
+    const requestCount = requestParameter?.parameters?.length ?? 0;
+    const topParamName = getParameterTypeName(baseParameterName);
+    const subParamNames: string[] = [];
+
+    // We need to loop the requests. An operation with multiple requests means that
+    // the operation can get different values for content-type and each value may
+    // have a different type associated to it.
+    for (let i = 0; i < requestCount; i++) {
+      const parameter = requestParameter.parameters[i];
+      const internalReferences = new Set<string>();
+      // In case we have more than one request to model we need to add a suffix to differentiate
+      const nameSuffix = i > 0 ? `${i}` : "";
+      const parameterInterfaceName =
+        requestCount > 1
+          ? `${baseParameterName}RequestParameters${nameSuffix}`
+          : topParamName;
+      const queryParameterDefinitions = buildQueryParameterDefinition(
+        parameter,
+        baseParameterName,
+        internalReferences,
+        i
+      );
+      const pathParameterDefinitions = buildPathParameterDefinitions(
+        parameter,
+        baseParameterName,
+        parametersFile,
+        internalReferences,
+        i
+      );
+
+      const headerParameterDefinitions = buildHeaderParameterDefinitions(
+        parameter,
+        baseParameterName,
+        parametersFile,
+        internalReferences,
+        i
+      );
+
+      const contentTypeParameterDefinition =
+        buildContentTypeParametersDefinition(
+          parameter,
+          baseParameterName,
+          internalReferences,
+          i
+        );
+
+      const bodyParameterDefinition = buildBodyParametersDefinition(
+        parameter,
+        baseParameterName,
+        internalReferences,
+        i
+      );
+
+      // Add interfaces for body and query parameters
+      parametersFile.addInterfaces([
+        ...(bodyParameterDefinition ?? []),
+        ...(queryParameterDefinitions ?? []),
+        ...(pathParameterDefinitions ? [pathParameterDefinitions] : []),
+        ...(headerParameterDefinitions ? [headerParameterDefinitions] : []),
+        ...(contentTypeParameterDefinition
+          ? [contentTypeParameterDefinition]
+          : [])
+      ]);
+
+      // Add Operation parameters type alias which is composed of the types we generated above
+      // plus the common type RequestParameters
+      parametersFile.addTypeAlias({
+        name: parameterInterfaceName,
+        isExported: true,
+        type: [...internalReferences, "RequestParameters"].join(" & ")
+      });
+
+      subParamNames.push(parameterInterfaceName);
+
+      if (headerParameterDefinitions !== undefined) {
+        hasHeaders = true;
+      }
+    }
+    // Add Operation parameters type alias which is composed of the types we generated above
+    // plus the common type RequestParameters
+    if (requestCount > 1) {
+      parametersFile.addTypeAlias({
+        name: topParamName,
+        isExported: true,
+        type: [...subParamNames].join(" | ")
+      });
+    }
+  }
+
+  if (hasHeaders) {
+    parametersFile.addImportDeclarations([
+      {
+        namedImports: ["RawHttpHeadersInput"],
+        moduleSpecifier: "@azure/core-rest-pipeline"
+      }
+    ]);
+  }
+  parametersFile.addImportDeclarations([
+    {
+      namedImports: ["RequestParameters"],
+      moduleSpecifier: "@azure-rest/core-client"
+    }
+  ]);
+  if (model.importSet?.has(ImportKind.ParameterInput)) {
+    parametersFile.addImportDeclarations([
+      {
+        namedImports: [
+          ...Array.from(model.importSet?.get(ImportKind.ParameterInput) || [])
+        ],
+        moduleSpecifier: "./models"
+      }
+    ]);
+  }
+  return { path: filePath, content: parametersFile.getFullText() };
+}
+
+function buildQueryParameterDefinition(
+  parameters: ParameterMetadatas,
+  baseName: string,
+  internalReferences: Set<string>,
+  requestIndex: number
+): InterfaceDeclarationStructure[] | undefined {
+  const queryParameters = (parameters?.parameters || []).filter(
+    (p) => p.type === "query"
+  );
+
+  if (!queryParameters.length) {
+    return undefined;
+  }
+
+  const nameSuffix = requestIndex > 0 ? `${requestIndex}` : "";
+  const queryParameterInterfaceName = `${baseName}QueryParam${nameSuffix}`;
+  const queryParameterPropertiesName = `${baseName}QueryParamProperties`;
+
+  // Get the property signature for each query parameter
+  const propertiesDefinition = queryParameters.map((qp) =>
+    getPropertyFromSchema(qp.param)
+  );
+
+  const hasRequiredParameters = propertiesDefinition.some(
+    (p) => !p.hasQuestionToken
+  );
+
+  const propertiesInterface: InterfaceDeclarationStructure = {
+    kind: StructureKind.Interface,
+    isExported: true,
+    name: queryParameterPropertiesName,
+    properties: propertiesDefinition
+  };
+
+  const parameterInterface: InterfaceDeclarationStructure = {
+    kind: StructureKind.Interface,
+    isExported: true,
+    name: queryParameterInterfaceName,
+    properties: [
+      {
+        name: "queryParameters",
+        type: queryParameterPropertiesName,
+        // Mark as optional if there are no required parameters
+        hasQuestionToken: !hasRequiredParameters
+      }
+    ]
+  };
+
+  // Mark the queryParameter interface for importing
+  internalReferences.add(queryParameterInterfaceName);
+
+  return [propertiesInterface, parameterInterface];
+}
+
+function getPropertyFromSchema(schema: Schema): PropertySignatureStructure {
+  const description = schema.description;
+  return {
+    name: schema.name,
+    ...(description && { docs: [{ description }] }),
+    type: schema.type,
+    hasQuestionToken: !Boolean(schema.required),
+    kind: StructureKind.PropertySignature
+  };
+}
+
+function buildPathParameterDefinitions(
+  parameters: ParameterMetadatas,
+  baseName: string,
+  parametersFile: SourceFile,
+  internalReferences: Set<string>,
+  requestIndex: number
+): InterfaceDeclarationStructure | undefined {
+  const pathParameters = (parameters.parameters || []).filter(
+    (p) => p.type === "path"
+  );
+  if (!pathParameters.length) {
+    return undefined;
+  }
+
+  const nameSuffix = requestIndex > 0 ? `${requestIndex}` : "";
+  const pathParameterInterfaceName = `${baseName}PathParam${nameSuffix}`;
+
+  const pathInterface = getPathInterfaceDefinition(pathParameters, baseName);
+
+  if (pathInterface) {
+    parametersFile.addInterface(pathInterface);
+  }
+
+  internalReferences.add(pathParameterInterfaceName);
+
+  return {
+    isExported: true,
+    kind: StructureKind.Interface,
+    name: pathParameterInterfaceName,
+    properties: [
+      {
+        name: "pathParameters",
+        type: `${baseName}PathParameters`,
+        kind: StructureKind.PropertySignature
+      }
+    ]
+  };
+}
+
+function getPathInterfaceDefinition(
+  pathParameters: ParameterMetadata[],
+  baseName: string
+): undefined | InterfaceDeclarationStructure {
+  const pathInterfaceName = `${baseName}PathParameters`;
+  return {
+    kind: StructureKind.Interface,
+    isExported: true,
+    name: pathInterfaceName,
+    properties: pathParameters.map((p: ParameterMetadata) =>
+      getPropertyFromSchema(p.param)
+    )
+  };
+}
+
+function buildHeaderParameterDefinitions(
+  parameters: ParameterMetadatas,
+  baseName: string,
+  parametersFile: SourceFile,
+  internalReferences: Set<string>,
+  requestIndex: number
+): InterfaceDeclarationStructure | undefined {
+  const headerParameters = (parameters.parameters || []).filter(
+    (p) => p.type === "header" && p.name !== "contentType"
+  );
+  if (!headerParameters.length) {
+    return undefined;
+  }
+
+  const nameSuffix = requestIndex > 0 ? `${requestIndex}` : "";
+  const headerParameterInterfaceName = `${baseName}HeaderParam${nameSuffix}`;
+
+  const headersInterface = getRequestHeaderInterfaceDefinition(
+    headerParameters,
+    baseName
+  );
+
+  if (headersInterface) {
+    parametersFile.addInterface(headersInterface);
+  }
+
+  internalReferences.add(headerParameterInterfaceName);
+
+  return {
+    isExported: true,
+    kind: StructureKind.Interface,
+    name: headerParameterInterfaceName,
+    properties: [
+      {
+        name: "headers",
+        type: `RawHttpHeadersInput & ${baseName}Headers`,
+        kind: StructureKind.PropertySignature
+      }
+    ]
+  };
+}
+
+function getRequestHeaderInterfaceDefinition(
+  headerParameters: ParameterMetadata[],
+  baseName: string
+): undefined | InterfaceDeclarationStructure {
+  const headersInterfaceName = `${baseName}Headers`;
+  return {
+    kind: StructureKind.Interface,
+    isExported: true,
+    name: headersInterfaceName,
+    properties: headerParameters.map((h: ParameterMetadata) =>
+      getPropertyFromSchema(h.param)
+    )
+  };
+}
+
+function buildContentTypeParametersDefinition(
+  parameters: ParameterMetadatas,
+  baseName: string,
+  internalReferences: Set<string>,
+  requestIndex: number
+): InterfaceDeclarationStructure | undefined {
+  const mediaTypeParameters = (parameters.parameters || []).filter(
+    (p) => p.type === "header" && p.name === "contentType"
+  );
+  if (!mediaTypeParameters.length) {
+    return undefined;
+  }
+
+  const nameSuffix = requestIndex > 0 ? `${requestIndex}` : "";
+  const mediaTypesParameterInterfaceName = `${baseName}MediaTypesParam${nameSuffix}`;
+
+  // Mark the queryParameter interface for importing
+  internalReferences.add(mediaTypesParameterInterfaceName);
+  const mediaParam = mediaTypeParameters[0].param;
+
+  return {
+    isExported: true,
+    kind: StructureKind.Interface,
+    name: mediaTypesParameterInterfaceName,
+    properties: [getPropertyFromSchema(mediaParam)]
+  };
+}
+
+function buildBodyParametersDefinition(
+  parameters: ParameterMetadatas,
+  baseName: string,
+  internalReferences: Set<string>,
+  requestIndex: number
+): InterfaceDeclarationStructure[] {
+  const bodyParameters = parameters.body;
+  if (
+    !bodyParameters ||
+    !bodyParameters?.body ||
+    !bodyParameters?.body.length
+  ) {
+    return [];
+  }
+
+  const nameSuffix = requestIndex > 0 ? `${requestIndex}` : "";
+  const bodyParameterInterfaceName = `${baseName}BodyParam${nameSuffix}`;
+  internalReferences.add(bodyParameterInterfaceName);
+
+  // In case of formData we'd get multiple properties in body marked as partialBody
+  if (bodyParameters.isPartialBody) {
+    let allOptionalParts = true;
+    const propertiesDefinitions: PropertySignatureStructure[] = [];
+    for (const param of bodyParameters.body) {
+      if (param.required) {
+        allOptionalParts = false;
+      }
+
+      propertiesDefinitions.push(getPropertyFromSchema(param));
+    }
+
+    const formBodyName = `${baseName}FormBody`;
+    const formBodyInterface: InterfaceDeclarationStructure = {
+      isExported: true,
+      kind: StructureKind.Interface,
+      name: formBodyName,
+      properties: propertiesDefinitions
+    };
+
+    return [
+      {
+        isExported: true,
+        kind: StructureKind.Interface,
+        name: bodyParameterInterfaceName,
+        properties: [
+          {
+            name: "body",
+            type: formBodyName,
+            hasQuestionToken: allOptionalParts
+          }
+        ]
+      },
+      formBodyInterface
+    ];
+  } else {
+    const bodySignature = getPropertyFromSchema(bodyParameters.body[0]);
+
+    return [
+      {
+        isExported: true,
+        kind: StructureKind.Interface,
+        name: bodyParameterInterfaceName,
+        properties: [
+          {
+            docs: bodySignature.docs,
+            name: "body",
+            type: bodySignature.type,
+            hasQuestionToken: bodySignature.hasQuestionToken
+          }
+        ]
+      }
+    ];
+  }
+}

package/src/buildPollingHelper.ts

@@ -0,0 +1,18 @@
+import { RLCModel } from "./interfaces.js";
+import * as path from "path";
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { hasPollingOperations } from "./helpers/operationHelpers.js";
+import { pollingContent } from "./static/pollingContent.js";
+
+export function buildPollingHelper(model: RLCModel) {
+  if (!hasPollingOperations(model)) {
+    return;
+  }
+  const readmeFileContents = hbs.compile(pollingContent, { noEscape: true });
+  const { srcPath } = model;
+  return {
+    path: path.join(srcPath, "pollingHelper.ts"),
+    content: readmeFileContents({})
+  };
+}

package/src/buildResponseTypes.ts

@@ -0,0 +1,169 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  PropertySignatureStructure,
+  StructureKind
+} from "ts-morph";
+import {
+  ImportKind,
+  ResponseHeaderSchema,
+  ResponseMetadata,
+  RLCModel
+} from "./interfaces.js";
+import * as path from "path";
+import {
+  getResponseBaseName,
+  getResponseTypeName
+} from "./helpers/nameConstructors.js";
+
+export function buildResponseTypes(model: RLCModel) {
+  const project = new Project();
+  const srcPath = model.srcPath;
+  const filePath = path.join(srcPath, `responses.ts`);
+  const responsesFile = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+  // Set used to track down which models need to be imported
+  // Track if we need to import RawHttpHeaders
+  let hasHeaders = false;
+  if (!model.responses) {
+    return;
+  }
+  for (const operationResponse of model.responses) {
+    for (const response of operationResponse.responses) {
+      // Building the response type base name
+      const baseResponseName = getResponseBaseName(
+        operationResponse.operationGroup,
+        operationResponse.operationName,
+        response.statusCode
+      );
+
+      // Build the response header
+      const headersInterface: InterfaceDeclarationStructure | undefined =
+        getResponseHeaderInterfaceDefinition(response, baseResponseName);
+      if (headersInterface) {
+        hasHeaders = true;
+        responsesFile.addInterface(headersInterface);
+      }
+
+      // Get the information to build the Response Interface
+      const responseTypeName = getResponseTypeName(baseResponseName);
+      const responseProperties = getResponseInterfaceProperties(
+        response,
+        headersInterface?.name
+      );
+
+      const responseInterfaceDefinition: OptionalKind<InterfaceDeclarationStructure> =
+        {
+          name: responseTypeName,
+          properties: responseProperties,
+          isExported: true,
+          extends: ["HttpResponse"]
+        };
+
+      // Only add a description if one was provided in the Swagger
+      // otherwise skip to avoid having empty TSDoc lines
+      if (response.description) {
+        responseInterfaceDefinition.docs = [
+          { description: response.description }
+        ];
+      }
+
+      // Add the response interface to the responses file
+      responsesFile.addInterface(responseInterfaceDefinition);
+    }
+  }
+
+  if (hasHeaders) {
+    responsesFile.addImportDeclarations([
+      {
+        namedImports: ["RawHttpHeaders"],
+        moduleSpecifier: "@azure/core-rest-pipeline"
+      }
+    ]);
+  }
+  responsesFile.addImportDeclarations([
+    {
+      namedImports: ["HttpResponse"],
+      moduleSpecifier: "@azure-rest/core-client"
+    }
+  ]);
+
+  if (model.importSet?.has(ImportKind.ResponseOutput)) {
+    responsesFile.addImportDeclarations([
+      {
+        namedImports: [
+          ...Array.from(model.importSet.get(ImportKind.ResponseOutput) || [])
+        ],
+        moduleSpecifier: "./outputModels"
+      }
+    ]);
+  }
+  return { path: filePath, content: responsesFile.getFullText() };
+}
+
+function getResponseHeaderInterfaceDefinition(
+  response: ResponseMetadata,
+  baseName: string
+): undefined | InterfaceDeclarationStructure {
+  // Check if there are any required headers
+  if (!response.headers) {
+    return;
+  }
+  const headersInterfaceName = `${baseName}Headers`;
+  return {
+    kind: StructureKind.Interface,
+    isExported: true,
+    name: headersInterfaceName,
+    properties: response?.headers.map((h: ResponseHeaderSchema) => {
+      const description = h.description;
+      return {
+        name: h.name,
+        ...(description && { docs: [{ description }] }),
+        type: h.type,
+        hasQuestionToken: !Boolean(h.required)
+      };
+    })
+  };
+}
+
+/**
+ * Gets the properties that need to be part of the response interface
+ */
+function getResponseInterfaceProperties(
+  response: ResponseMetadata,
+  headersInterfaceName?: string
+) {
+  const statusCode = response.statusCode;
+  const responseProperties: PropertySignatureStructure[] = [
+    {
+      name: "status",
+      type: statusCode === "default" ? `string` : `"${statusCode}"`,
+      kind: StructureKind.PropertySignature
+    }
+  ];
+
+  if (response.body) {
+    const description = response.body.description;
+    responseProperties.push({
+      name: "body",
+      type: response.body.type,
+      kind: StructureKind.PropertySignature,
+      ...(description && { docs: [{ description }] })
+    });
+  }
+
+  if (headersInterfaceName) {
+    responseProperties.push({
+      name: "headers",
+      type: `RawHttpHeaders & ${headersInterfaceName}`,
+      kind: StructureKind.PropertySignature
+    });
+  }
+
+  return responseProperties;
+}

package/src/buildSchemaType.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import * as path from "path";
+import {
+  buildObjectInterfaces,
+  buildPolymorphicAliases
+} from "./buildObjectTypes.js";
+import { RLCModel, SchemaContext } from "./interfaces.js";
+
+/**
+ * Generates types to represent schema definitions in the swagger
+ */
+export function buildSchemaTypes(model: RLCModel) {
+  const { srcPath } = model;
+  const project = new Project();
+  let filePath = path.join(srcPath, `models.ts`);
+  const inputModelFile = generateModelFiles(model, project, filePath, [
+    SchemaContext.Input
+  ]);
+  filePath = path.join(srcPath, `outputModels.ts`);
+  const outputModelFile = generateModelFiles(model, project, filePath, [
+    SchemaContext.Output,
+    SchemaContext.Exception
+  ]);
+  return { inputModelFile, outputModelFile };
+}
+
+export function generateModelFiles(
+  model: RLCModel,
+  project: Project,
+  filePath: string,
+  schemaContext: SchemaContext[]
+) {
+  // Track models that need to be imported
+  const importedModels = new Set<string>();
+
+  const objectsDefinitions = buildObjectInterfaces(
+    model,
+    importedModels,
+    schemaContext
+  );
+  const objectTypeAliases = buildPolymorphicAliases(model, schemaContext);
+
+  if (objectTypeAliases.length || objectsDefinitions.length) {
+    const modelsFile = project.createSourceFile(filePath, undefined, {
+      overwrite: true
+    });
+
+    modelsFile.addInterfaces(objectsDefinitions);
+    modelsFile.addTypeAliases(objectTypeAliases);
+    return { path: filePath, content: modelsFile.getFullText() };
+  }
+  return undefined;
+}