@azure-tools/typespec-ts 0.53.3 → 0.54.0

package/src/rlc-common/buildResponseTypes.ts

@@ -0,0 +1,203 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  PropertySignatureStructure,
+  StructureKind
+} from "ts-morph";
+import {
+  ResponseHeaderSchema,
+  ResponseMetadata,
+  RLCModel
+} from "./interfaces.js";
+import * as path from "path";
+import {
+  getImportModuleName,
+  getResponseBaseName,
+  getResponseTypeName
+} from "./helpers/nameConstructors.js";
+import { getImportSpecifier } from "./helpers/importsUtil.js";
+
+let hasErrorResponse = false;
+export function buildResponseTypes(model: RLCModel) {
+  const project = new Project();
+  const srcPath = model.srcPath;
+  const filePath = path.join(srcPath, `responses.ts`);
+  hasErrorResponse = false;
+  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 =
+        response.predefinedName ?? 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([
+      {
+        isTypeOnly: true,
+        namedImports: ["RawHttpHeaders"],
+        moduleSpecifier: getImportSpecifier(
+          "restPipeline",
+          model.importInfo.runtimeImports
+        )
+      }
+    ]);
+  }
+  const namedImports = ["HttpResponse"];
+  if (hasErrorResponse) {
+    namedImports.push("ErrorResponse");
+  }
+  responsesFile.addImportDeclarations([
+    {
+      isTypeOnly: true,
+      namedImports,
+      moduleSpecifier: getImportSpecifier(
+        "restClient",
+        model.importInfo.runtimeImports
+      )
+    }
+  ]);
+
+  if ((model.importInfo.internalImports.response?.importsSet?.size ?? 0) > 0) {
+    const modelNamedImports = Array.from(
+      model.importInfo.internalImports.response!.importsSet!
+    ).filter((modelName) => {
+      return !(modelName === "ErrorResponseOutput" && hasErrorResponse);
+    });
+    responsesFile.addImportDeclarations([
+      {
+        isTypeOnly: true,
+        namedImports: modelNamedImports,
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./outputModels`,
+            esModulesName: `./outputModels.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+  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: !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;
+    let type = response.body.type;
+    if (
+      response.body.type === "ErrorResponseOutput" &&
+      response.body.fromCore
+    ) {
+      type = "ErrorResponse";
+      hasErrorResponse = true;
+    }
+    responseProperties.push({
+      name: "body",
+      type,
+      kind: StructureKind.PropertySignature,
+      ...(description && { docs: [{ description }] })
+    });
+  }
+
+  if (headersInterfaceName) {
+    responseProperties.push({
+      name: "headers",
+      type: `RawHttpHeaders & ${headersInterfaceName}`,
+      kind: StructureKind.PropertySignature
+    });
+  }
+
+  return responseProperties;
+}

package/src/rlc-common/buildSamples.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel, RLCSampleGroup, File as RLCFile } from "./interfaces.js";
+import { sampleTemplate } from "./static/sampleTemplate.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import * as path from "path";
+
+// Build sample files for the model based on the sample groups
+export function buildSamples(model: RLCModel) {
+  if (!model.options || !model.options.packageDetails) {
+    return;
+  }
+  const sampleGroups: RLCSampleGroup[] | undefined = model.sampleGroups;
+  if (!sampleGroups || sampleGroups.length === 0) {
+    return;
+  }
+  const sampleFiles: RLCFile[] = [];
+  for (const sampleGroup of sampleGroups) {
+    const sampleGroupFileContents = hbs.compile(sampleTemplate, {
+      noEscape: true
+    });
+    const filePath = path.join("samples-dev", `${sampleGroup.filename}.ts`);
+    sampleFiles.push({
+      path: filePath,
+      content: sampleGroupFileContents(sampleGroup)
+    });
+  }
+  return sampleFiles;
+}

package/src/rlc-common/buildSchemaType.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project } from "ts-morph";
+import * as path from "path";
+import {
+  buildObjectAliases,
+  buildObjectInterfaces,
+  buildPolymorphicAliases
+} from "./buildObjectTypes.js";
+import { RLCModel, SchemaContext } from "./interfaces.js";
+import { getImportSpecifier } from "./helpers/importsUtil.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);
+
+  const objectAliases = buildObjectAliases(
+    model,
+    importedModels,
+    schemaContext
+  );
+
+  if (
+    objectTypeAliases.length ||
+    objectsDefinitions.length ||
+    objectAliases.length
+  ) {
+    const modelsFile = project.createSourceFile(filePath, undefined, {
+      overwrite: true
+    });
+
+    modelsFile.addInterfaces(objectsDefinitions);
+    modelsFile.addTypeAliases(objectTypeAliases);
+    modelsFile.addTypeAliases(objectAliases);
+    if (importedModels.size > 0) {
+      modelsFile.addImportDeclarations([
+        {
+          isTypeOnly: true,
+          namedImports: [...Array.from(importedModels || [])],
+          moduleSpecifier: getImportSpecifier(
+            "restClient",
+            model.importInfo.runtimeImports
+          )
+        }
+      ]);
+    }
+    return { path: filePath, content: modelsFile.getFullText() };
+  }
+  return undefined;
+}

package/src/rlc-common/buildSerializeHelper.ts

@@ -0,0 +1,49 @@
+import { RLCModel } from "./interfaces.js";
+import * as path from "path";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import {
+  hasCsvCollection,
+  hasMultiCollection,
+  hasPipeCollection,
+  hasSsvCollection,
+  hasTsvCollection
+} from "./helpers/operationHelpers.js";
+import {
+  buildCsvCollectionContent,
+  buildMultiCollectionContent,
+  buildPipeCollectionContent,
+  buildSsvCollectionContent,
+  buildTsvCollectionContent
+} from "./static/serializeHelper.js";
+
+export function buildSerializeHelper(model: RLCModel) {
+  let serializeHelperContent = "";
+  if (hasMultiCollection(model)) {
+    serializeHelperContent += "\n" + buildMultiCollectionContent;
+  }
+  if (hasPipeCollection(model)) {
+    serializeHelperContent += "\n" + buildPipeCollectionContent;
+  }
+  if (hasSsvCollection(model)) {
+    serializeHelperContent += "\n" + buildSsvCollectionContent;
+  }
+  if (hasTsvCollection(model)) {
+    serializeHelperContent += "\n" + buildTsvCollectionContent;
+  }
+  if (hasCsvCollection(model)) {
+    serializeHelperContent += "\n" + buildCsvCollectionContent;
+  }
+  if (serializeHelperContent !== "") {
+    const readmeFileContents = hbs.compile(serializeHelperContent, {
+      noEscape: true
+    });
+    const { srcPath } = model;
+    return {
+      path: path.join(srcPath, "serializeHelper.ts"),
+      content: readmeFileContents({})
+    };
+  }
+  return undefined;
+}

package/src/rlc-common/buildTopLevelIndexFile.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import { RLCModel } from "./interfaces.js";
+import { Project } from "ts-morph";
+import * as path from "path";
+import { getRelativePartFromSrcPath } from "./helpers/pathUtils.js";
+import { getImportModuleName } from "./helpers/nameConstructors.js";
+
+const batchOutputFolder: [string, string, string][] = [];
+
+export function buildTopLevelIndex(model: RLCModel) {
+  if (!model.options) {
+    return undefined;
+  }
+  const project = new Project();
+  const { srcPath } = model;
+  const { multiClient } = model.options;
+  const batch = model.options.batch;
+  if (srcPath) {
+    const clientName = model.libraryName;
+    const moduleName = normalizeName(clientName, NameType.File);
+    const relativePath =
+      "./" +
+      getRelativePartFromSrcPath(srcPath, model.options.isModularLibrary);
+    batchOutputFolder.push([relativePath, clientName, moduleName]);
+  }
+  if (
+    multiClient &&
+    batch &&
+    batch.length > 1 &&
+    batchOutputFolder.length === batch.length
+  ) {
+    const indexFile = project.createSourceFile("index.ts", undefined, {
+      overwrite: true
+    });
+    const allModules: string[] = [];
+    batchOutputFolder.forEach((item) => {
+      indexFile.addImportDeclaration({
+        isTypeOnly: true,
+        namespaceImport: item[1],
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `${item[0]}`,
+            esModulesName: `${item[0]}/index.js`
+          },
+          model
+        )
+      });
+      allModules.push(item[1]);
+    });
+    indexFile.addExportDeclaration({
+      namedExports: [...allModules]
+    });
+    const content = indexFile.getFullText();
+    const filePath = path.join(
+      srcPath.substring(0, srcPath.lastIndexOf("src") + 4),
+      model.options.isModularLibrary ? "rest" : "",
+      `index.ts`
+    );
+    return { path: filePath, content };
+  }
+  return undefined;
+}

package/src/rlc-common/helpers/apiVersionUtil.ts

@@ -0,0 +1,53 @@
+import { ApiVersionInfo, ApiVersionPosition, UrlInfo } from "../interfaces.js";
+
+/**
+ * Extract the path api-version detail from UrlInfo, return undefined if no valid api-version parameter
+ * @param urlInfo UrlInfo detail
+ * @returns path api-version detail
+ */
+export function extractPathApiVersion(
+  urlInfo?: UrlInfo
+): ApiVersionInfo | undefined {
+  if (!urlInfo) {
+    return;
+  }
+  const param = urlInfo.urlParameters?.filter(
+    (p) =>
+      p.name.toLowerCase() === "api-version" ||
+      p.name.toLowerCase() === "apiversion"
+  );
+  if (!param || param?.length < 1) {
+    return;
+  }
+  const detail: ApiVersionInfo = {
+    definedPosition: "path",
+    isCrossedVersion: Boolean(param?.length > 1),
+    defaultValue:
+      param.length === 1 ? (param[0]?.value as string | undefined) : undefined,
+    required: true
+  };
+  return detail;
+}
+
+/**
+ * Extract the final position value from api-version in query and path defined.
+ * it could be in either the url or the operation level,
+ * and in operation level, it could be either path or query.
+ * @param operationApiVersion api-version detail in both query and path
+ * @param urlVersionDetail api-version detail in parameterized host
+ * @returns calculated combined position info
+ */
+export function extractDefinedPosition(
+  operationApiVersion?: ApiVersionInfo,
+  urlVersionDetail?: ApiVersionInfo
+): ApiVersionPosition {
+  let pos: ApiVersionPosition = "none";
+  if (operationApiVersion && urlVersionDetail) {
+    pos = "duplicate";
+  } else if (operationApiVersion?.definedPosition) {
+    pos = operationApiVersion.definedPosition!;
+  } else if (urlVersionDetail) {
+    pos = "baseurl";
+  }
+  return pos;
+}

package/src/rlc-common/helpers/importsUtil.ts

@@ -0,0 +1,187 @@
+import { SourceFile } from "ts-morph";
+import { ImportType, Imports, PackageFlavor } from "../interfaces.js";
+
+/**
+ * Build the common imports for generated SDK
+ * @param flavor flavor of SDK to generate, if any. When set to "azure", Azure Core packages will be used. When unset, the generic `ts-http-runtime` package will be used.
+ * @returns
+ */
+export function buildRuntimeImports(flavor?: PackageFlavor): Imports {
+  if (flavor === "azure") {
+    return {
+      restClient: {
+        type: "restClient",
+        specifier: "@azure-rest/core-client",
+        version: "^2.0.0"
+      },
+      coreAuth: {
+        type: "coreAuth",
+        specifier: "@azure/core-auth",
+        version: "^1.6.0"
+      },
+      restPipeline: {
+        type: "restPipeline",
+        specifier: "@azure/core-rest-pipeline",
+        version: "^1.14.0"
+      },
+      coreUtil: {
+        type: "coreUtil",
+        specifier: "@azure/core-util",
+        version: "^1.4.0"
+      },
+      coreLogger: {
+        type: "coreLogger",
+        specifier: "@azure/logger",
+        version: "^1.0.4"
+      },
+      azureEslintPlugin: {
+        type: "azureEslintPlugin",
+        specifier: "@azure/eslint-plugin-azure-sdk",
+        version: "^3.0.0"
+      },
+      azureTestRecorder: {
+        type: "azureTestRecorder",
+        specifier: "@azure-tools/test-recorder",
+        version: "^3.0.0"
+      },
+      azureCoreLro: {
+        type: "azureCoreLro",
+        specifier: "@azure/core-lro"
+      }
+    } as Imports;
+  } else {
+    // In non-azure branded scope we only have one dependency that is ts-http-runtime
+    return {
+      commonFallback: {
+        type: "commonFallback",
+        specifier: "@typespec/ts-http-runtime",
+        version: "0.1.0"
+      }
+    } as Imports;
+  }
+}
+
+/**
+ * Initialize the inner imports for parameter and response, the import set would be used for referred models
+ * @returns
+ */
+export function initInternalImports(): Imports {
+  return {
+    parameter: {
+      type: "parameter",
+      importsSet: new Set<string>()
+    },
+    response: {
+      type: "response",
+      importsSet: new Set<string>()
+    },
+    rlcIndex: {
+      type: "rlcIndex",
+      importsSet: new Set<string>()
+    },
+    modularModel: {
+      type: "modularModel",
+      importsSet: new Set<string>()
+    },
+    rlcClientFactory: {
+      type: "rlcClientFactory",
+      importsSet: new Set<string>()
+    },
+    rlcClientDefinition: {
+      type: "rlcClientDefinition",
+      importsSet: new Set<string>()
+    },
+    serializerHelpers: {
+      type: "serializerHelpers",
+      importsSet: new Set<string>()
+    }
+  } as Imports;
+}
+
+export function getImportSpecifier(
+  importType: ImportType,
+  imports?: Imports,
+  includeFallback = true
+): string {
+  imports = imports ?? ({} as Imports);
+  const defaultPackageMap: Record<ImportType, string> = {
+    restClient: "@azure-rest/core-client",
+    coreAuth: "@azure/core-auth",
+    restPipeline: "@azure/core-rest-pipeline",
+    coreUtil: "@azure/core-util",
+    coreLogger: "@azure/logger",
+    azureCoreLro: "@azure/core-lro"
+  } as any;
+  if (!includeFallback) {
+    return imports[importType]?.specifier ?? "";
+  }
+  return (
+    (imports[importType] ?? imports.commonFallback)?.specifier ??
+    defaultPackageMap[importType] ??
+    ""
+  );
+}
+
+export function addImportToSpecifier(
+  importType: ImportType,
+  runtimeImports: Imports,
+  importedName: string
+): void {
+  const specifier = getImportSpecifier(importType, runtimeImports);
+  const importSet = runtimeImports[importType]?.importsSet;
+  if (!importSet) {
+    runtimeImports[importType] = {
+      type: importType,
+      specifier,
+      importsSet: new Set<string>().add(importedName)
+    };
+  } else {
+    importSet.add(importedName);
+  }
+}
+
+export function clearImportSets(runtimeImports: Imports): void {
+  for (const importType of Object.values(runtimeImports)) {
+    importType.importsSet?.clear();
+  }
+}
+
+export function addImportsToFiles(
+  runtimeImports: Imports,
+  file: SourceFile,
+  internalSpecifierMap?: Record<string, string>
+): void {
+  Object.values(runtimeImports)
+    .filter((importType) => {
+      return importType.importsSet?.size;
+    })
+    .forEach((importType) => {
+      const specifier =
+        internalSpecifierMap?.[importType.type] ?? importType.specifier!;
+      let hasModifier = false;
+      if (!specifier) {
+        return;
+      }
+      file
+        .getImportDeclarations()
+        .filter((importDeclaration) => {
+          return importDeclaration.getModuleSpecifierValue() === specifier;
+        })
+        .forEach((importDeclaration) => {
+          hasModifier = true;
+          importDeclaration.addNamedImports([
+            ...importType.importsSet!.values()
+          ]);
+        });
+
+      if (!hasModifier) {
+        file.addImportDeclaration({
+          isTypeOnly: true,
+          moduleSpecifier: specifier,
+          namedImports: [...importType.importsSet!.values()]
+        });
+        return;
+      }
+    });
+  clearImportSets(runtimeImports);
+}