@azure-tools/typespec-ts 0.54.0 → 0.54.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/api-version-util.ts

@@ -0,0 +1,48 @@
+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/imports-util.ts

@@ -0,0 +1,184 @@
+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);
+}