@azure-tools/typespec-ts 0.55.0-dev.1 → 0.55.0-dev.2

package/src/rlc-common/build-response-types.ts

@@ -0,0 +1,180 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as path from "path";
+import {
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  PropertySignatureStructure,
+  StructureKind,
+} from "ts-morph";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import {
+  getImportModuleName,
+  getResponseBaseName,
+  getResponseTypeName,
+} from "./helpers/name-constructors.js";
+import { ResponseHeaderSchema, ResponseMetadata, RLCModel } from "./interfaces.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/build-samples.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { File as RLCFile, RLCModel, RLCSampleGroup } from "./interfaces.js";
+import { sampleTemplate } from "./static/sample-template.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/build-schema-type.ts

@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as path from "path";
+import { Project } from "ts-morph";
+import {
+  buildObjectAliases,
+  buildObjectInterfaces,
+  buildPolymorphicAliases,
+} from "./build-object-types.js";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import { getImportModuleName } from "./helpers/name-constructors.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);
+
+  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),
+        },
+      ]);
+    }
+    // Add NodeReadableStream import if binary types are used in models.
+    // platform-types.ts is generated directly under src/ (no static-helpers/
+    // subdirectory) to match the RLC design where all output lives in src/.
+    // The platform-types static helper resolves NodeReadableStream to
+    // NodeJS.ReadableStream on Node and `never` on browser/react-native, so the
+    // union arm drops out naturally in non-Node builds.
+    if (modelsFile.getFullText().includes("NodeReadableStream")) {
+      const platformTypesModuleSpecifier = model.options?.azureSdkForJs
+        ? "#platform/platform-types"
+        : getImportModuleName(
+            {
+              cjsName: `./platform-types`,
+              esModulesName: `./platform-types.js`,
+            },
+            model,
+          );
+      modelsFile.addImportDeclarations([
+        {
+          isTypeOnly: true,
+          namedImports: ["NodeReadableStream"],
+          moduleSpecifier: platformTypesModuleSpecifier,
+        },
+      ]);
+    }
+    return { path: filePath, content: modelsFile.getFullText() };
+  }
+  return undefined;
+}

package/src/rlc-common/build-serialize-helper.ts

@@ -0,0 +1,49 @@
+import * as path from "path";
+import { RLCModel } from "./interfaces.js";
+// 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/operation-helpers.js";
+import {
+  buildCsvCollectionContent,
+  buildMultiCollectionContent,
+  buildPipeCollectionContent,
+  buildSsvCollectionContent,
+  buildTsvCollectionContent,
+} from "./static/serialize-helper.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/build-top-level-index-file.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as path from "path";
+import { Project } from "ts-morph";
+import { getImportModuleName } from "./helpers/name-constructors.js";
+import { NameType, normalizeName } from "./helpers/name-utils.js";
+import { getRelativePartFromSrcPath } from "./helpers/path-utils.js";
+import { RLCModel } from "./interfaces.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/name-constructors.ts

@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel } from "../interfaces.js";
+import { NameType, normalizeName } from "./name-utils.js";
+
+/**
+ * Get the response type name by baseName or operatioName & statusCode
+ * @param baseResponseName
+ */
+export function getResponseTypeName(baseResponseName: string): string;
+export function getResponseTypeName(
+  operationGroup: string,
+  operationName: string,
+  statusCode: string,
+): string;
+export function getResponseTypeName(
+  baseNameOrOperationGroup: string,
+  operationName?: string,
+  statusCode?: string,
+): string {
+  if (operationName) {
+    baseNameOrOperationGroup = getResponseBaseName(
+      baseNameOrOperationGroup,
+      operationName!,
+      statusCode || "",
+    );
+  }
+  return normalizeName(`${baseNameOrOperationGroup}Response`, NameType.Interface);
+}
+
+export function getLroLogicalResponseName(operationGroup: string, operationName: string) {
+  return normalizeName(`${operationGroup}_${operationName}_Logical_Response`, NameType.Interface);
+}
+
+/**
+ * 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 function getResponseBaseName(
+  operationGroup: string,
+  operationName: string,
+  statusCode: string,
+) {
+  return normalizeName(
+    `${operationGroup}_${normalizeName(operationName, NameType.Interface, true)}_${statusCode}`,
+    NameType.Interface,
+  );
+}
+
+/**
+ * The prefix of all parameter relevant types
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns
+ */
+export function getParameterBaseName(operationGroup: string, operationName: string) {
+  return normalizeName(`${operationGroup}_${operationName}`, NameType.Interface);
+}
+
+/**
+ * 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 function getParameterTypeName(baseName: string): string;
+export function getParameterTypeName(operationGroup: string, operationName: string): string;
+export function getParameterTypeName(baseNameOrOperationGroup: string, operationName?: string) {
+  if (operationName) {
+    baseNameOrOperationGroup = getParameterBaseName(baseNameOrOperationGroup, operationName!);
+  }
+
+  return normalizeName(`${baseNameOrOperationGroup}_Parameters`, NameType.Interface);
+}
+
+export interface ModuleName {
+  esModulesName: string;
+  cjsName: string;
+}
+/**
+ * This is a helper function that gets the right import module depending on the type of
+ * library being generated
+ */
+export function getImportModuleName(name: ModuleName, codeModel: RLCModel) {
+  if (codeModel.options?.moduleKind === "cjs") {
+    return name.cjsName;
+  }
+  return name.esModulesName;
+}
+
+export function getClientName(model: RLCModel) {
+  const clientName = model.libraryName;
+  const clientInterfaceName = model.options?.isModularLibrary
+    ? model.libraryName
+    : clientName.endsWith("Client")
+      ? `${clientName}`
+      : `${clientName}Client`;
+
+  return clientInterfaceName;
+}
+
+export function getMultipartPartTypeName(schemaName: string, partName: string) {
+  const name = normalizeName(partName, NameType.Interface);
+  const bodyParamName = normalizeName(schemaName, NameType.Interface);
+
+  return normalizeName(`${bodyParamName}_${name}_PartDescriptor`, NameType.Interface);
+}

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

@@ -0,0 +1,138 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { MethodSignatureStructure, OptionalKind, ParameterDeclarationStructure } from "ts-morph";
+import {
+  Methods,
+  ObjectSchema,
+  ParameterMetadata,
+  PathParameter,
+  RLCModel,
+  Schema,
+  SchemaContext,
+} from "../interfaces.js";
+import { NameType, normalizeName, pascalCase } from "./name-utils.js";
+import { isObjectSchema } from "./schema-helpers.js";
+
+export function buildMethodDefinitions(
+  methods: Methods,
+  pathParams: PathParameter[] = [],
+): OptionalKind<MethodSignatureStructure>[] {
+  const methodDefinitions: OptionalKind<MethodSignatureStructure>[] = [];
+  for (const key of Object.keys(methods)) {
+    const verbMethods = methods[key];
+    if (!verbMethods) {
+      continue;
+    }
+    for (const method of verbMethods) {
+      const description = method.description;
+      const areAllOptional = method.hasOptionalOptions;
+
+      methodDefinitions.push({
+        name: key,
+        ...(description && { docs: [{ description }] }),
+        parameters: [
+          ...getPathParamDefinitions(pathParams),
+          {
+            name: "options",
+            hasQuestionToken: areAllOptional,
+            type: pascalCase(method.optionsName),
+          },
+        ],
+        returnType: `StreamableMethod<${method.returnType}>`,
+      });
+    }
+  }
+
+  return methodDefinitions;
+}
+
+export function getPathParamDefinitions(
+  pathParams: PathParameter[],
+): OptionalKind<ParameterDeclarationStructure>[] {
+  return pathParams.map(({ name, type, description }) => {
+    return {
+      name: normalizeName(name, NameType.Parameter),
+      type,
+      description,
+    };
+  });
+}
+
+export function hasPagingOperations(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasPaging);
+}
+
+export function hasPollingOperations(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasLongRunning);
+}
+
+export function hasMultiCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasMultiCollection);
+}
+
+export function hasPipeCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasPipeCollection);
+}
+
+export function hasSsvCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasSsvCollection);
+}
+
+export function hasTsvCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasTsvCollection);
+}
+
+export function hasCsvCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasCsvCollection);
+}
+
+export function hasUnexpectedHelper(model: RLCModel) {
+  const pathDictionary = model.paths;
+  for (const details of Object.values(pathDictionary)) {
+    for (const methodDetails of Object.values(details.methods)) {
+      const firstMethod = methodDetails[0];
+      if (!firstMethod) {
+        continue;
+      }
+      const successTypes = firstMethod.responseTypes.success;
+      const errorTypes = firstMethod.responseTypes.error;
+
+      if (successTypes.length > 0 && errorTypes.length > 0 && !!errorTypes[0]) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function hasInputModels(model: RLCModel) {
+  return hasSchemaContextObject(model, [SchemaContext.Input]);
+}
+export function hasOutputModels(model: RLCModel) {
+  return hasSchemaContextObject(model, [SchemaContext.Output, SchemaContext.Exception]);
+}
+
+function hasSchemaContextObject(model: RLCModel, schemaUsage: SchemaContext[]) {
+  const objectSchemas: ObjectSchema[] = (model.schemas ?? []).filter(
+    (o) => isObjectSchema(o) && (o as ObjectSchema).usage?.some((u) => schemaUsage.includes(u)),
+  );
+
+  return objectSchemas.length > 0;
+}
+
+export function getGeneratedWrapperTypes(params: ParameterMetadata[] | PathParameter[]): Schema[] {
+  const wrapperTypes = params
+    .map((qp) => (isParameterMetadata(qp) ? qp.param.wrapperType : qp.wrapperType))
+    .filter((v) => v !== undefined);
+  const wrapperFromObjects = wrapperTypes.filter((wrap) => wrap.type === "object");
+  const wrapperFromUnions = wrapperTypes
+    .filter((wrap) => wrap.type === "union")
+    .flatMap((wrapperType) => wrapperType?.enum ?? [])
+    .filter((v) => v.type === "object");
+  return [...wrapperFromUnions, ...wrapperFromObjects];
+}
+
+function isParameterMetadata(param: ParameterMetadata | PathParameter): param is ParameterMetadata {
+  return (param as any).param !== undefined;
+}