@azure-tools/typespec-ts 0.55.0-dev.6 → 0.55.0-dev.7

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

@@ -0,0 +1,460 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { joinPaths } from "@typespec/compiler";
+import {
+  InterfaceDeclarationStructure,
+  Project,
+  PropertySignatureStructure,
+  SourceFile,
+  StructureKind,
+} from "ts-morph";
+import { getObjectInterfaceDeclaration } from "./build-object-types.js";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import { getParameterBaseName, getParameterTypeName } from "./helpers/name-constructors.js";
+import { getGeneratedWrapperTypes } from "./helpers/operation-helpers.js";
+import {
+  ObjectSchema,
+  ParameterMetadata,
+  ParameterMetadatas,
+  RLCModel,
+  Schema,
+  SchemaContext,
+} from "./interfaces.js";
+
+export function buildParameterTypes(model: RLCModel) {
+  const project = new Project({ useInMemoryFileSystem: true });
+  const srcPath = model.srcPath;
+  const filePath = joinPaths(srcPath, `parameters.ts`);
+  const partialBodyTypeNames = new Set<string>();
+  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];
+      if (!parameter) {
+        continue;
+      }
+      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);
+
+      const headerParameterDefinitions = buildHeaderParameterDefinitions(
+        parameter,
+        baseParameterName,
+        parametersFile,
+        internalReferences,
+        i,
+      );
+
+      const contentTypeParameterDefinition = buildContentTypeParametersDefinition(
+        parameter,
+        baseParameterName,
+        internalReferences,
+        i,
+      );
+
+      const bodyParameterDefinition = buildBodyParametersDefinition(
+        parameter,
+        baseParameterName,
+        internalReferences,
+        i,
+      );
+
+      const bodyTypeAlias = buildBodyTypeAlias(parameter, partialBodyTypeNames);
+      if (bodyTypeAlias) {
+        parametersFile.addTypeAlias(bodyTypeAlias);
+      }
+
+      // Add interfaces for body and query parameters
+      parametersFile.addInterfaces([
+        ...(bodyParameterDefinition ?? []),
+        ...(queryParameterDefinitions ?? []),
+        ...(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([
+      {
+        isTypeOnly: true,
+        namedImports: ["RawHttpHeadersInput"],
+        moduleSpecifier: getImportSpecifier("restPipeline", model.importInfo.runtimeImports),
+      },
+    ]);
+  }
+  parametersFile.addImportDeclarations([
+    {
+      isTypeOnly: true,
+      namedImports: ["RequestParameters"],
+      moduleSpecifier: getImportSpecifier("restClient", model.importInfo.runtimeImports),
+    },
+  ]);
+  if ((model.importInfo.internalImports?.parameter?.importsSet?.size ?? 0) > 0) {
+    parametersFile.addImportDeclarations([
+      {
+        isTypeOnly: true,
+        namedImports: Array.from(model.importInfo.internalImports.parameter.importsSet!),
+        moduleSpecifier: `./models.js`,
+      },
+    ]);
+  }
+  // Add NodeReadableStream import if binary types are used in parameters.
+  // 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 (parametersFile.getFullText().includes("NodeReadableStream")) {
+    parametersFile.addImportDeclarations([
+      {
+        isTypeOnly: true,
+        namedImports: ["NodeReadableStream"],
+        moduleSpecifier: "#platform/platform-types",
+      },
+    ]);
+  }
+  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));
+  // Get wrapper types for query parameters
+  const wrapperTypesDefinition = getGeneratedWrapperTypes(queryParameters).map((wrapObj) => {
+    return getObjectInterfaceDeclaration(
+      wrapObj.name,
+      wrapObj,
+      [SchemaContext.Input],
+      new Set<string>(),
+    );
+  });
+
+  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 [...wrapperTypesDefinition, propertiesInterface, parameterInterface];
+}
+
+function getPropertyFromSchema(schema: Schema): PropertySignatureStructure {
+  const description = schema.description;
+  return {
+    name: schema.name,
+    ...(description && { docs: [{ description }] }),
+    type: schema.type,
+    hasQuestionToken: !schema.required,
+    kind: StructureKind.PropertySignature,
+  };
+}
+
+function buildPathParameterDefinitions(
+  parameters: ParameterMetadatas,
+): InterfaceDeclarationStructure[] | undefined {
+  const pathParameters = (parameters.parameters || []).filter((p) => p.type === "path");
+  if (!pathParameters.length) {
+    return undefined;
+  }
+  const allDefinitions: InterfaceDeclarationStructure[] = [];
+
+  // we only need to build the wrapper types if the path parameters are objects
+  const wrapperTypesDefinition = getGeneratedWrapperTypes(pathParameters).map((wrap) => {
+    return getObjectInterfaceDeclaration(wrap.name, wrap, [SchemaContext.Input], new Set<string>());
+  });
+  allDefinitions.push(...wrapperTypesDefinition);
+  return allDefinitions;
+}
+
+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);
+
+  let isOptional = true;
+  if (headersInterface) {
+    parametersFile.addInterface(headersInterface);
+    isOptional = !(headersInterface.properties || []).some(
+      (prop) => prop.hasQuestionToken === false,
+    );
+  }
+
+  internalReferences.add(headerParameterInterfaceName);
+
+  return {
+    isExported: true,
+    kind: StructureKind.Interface,
+    name: headerParameterInterfaceName,
+    properties: [
+      {
+        name: "headers",
+        type: `RawHttpHeadersInput & ${baseName}Headers`,
+        kind: StructureKind.PropertySignature,
+        hasQuestionToken: isOptional,
+      },
+    ],
+  };
+}
+
+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 firstMediaType = mediaTypeParameters[0];
+  if (!firstMediaType) {
+    return undefined;
+  }
+  const mediaParam = firstMediaType.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 firstBody = bodyParameters.body[0];
+    if (!firstBody) {
+      return [];
+    }
+    const bodySignature = getPropertyFromSchema(firstBody);
+
+    return [
+      {
+        isExported: true,
+        kind: StructureKind.Interface,
+        name: bodyParameterInterfaceName,
+        properties: [
+          {
+            docs: bodySignature.docs,
+            name: "body",
+            type: bodySignature.type,
+            hasQuestionToken: bodySignature.hasQuestionToken,
+          },
+        ],
+      },
+    ];
+  }
+}
+
+export function buildBodyTypeAlias(
+  parameters: ParameterMetadatas,
+  partialBodyTypeNames: Set<string>,
+) {
+  const bodyParameters = parameters.body;
+  if (!bodyParameters || !bodyParameters?.body || !bodyParameters?.body.length) {
+    return undefined;
+  }
+  const schema = bodyParameters.body[0] as ObjectSchema;
+  const headerParameters = (parameters.parameters || []).filter(
+    (p) => p.type === "header" && p.name === "contentType",
+  );
+  if (!headerParameters.length || headerParameters.length > 1) {
+    return undefined;
+  }
+
+  const firstHeader = headerParameters[0];
+  if (!firstHeader) {
+    return undefined;
+  }
+  const contentType = firstHeader.param.type;
+  const description = `${schema.description}`;
+  const typeName = `${schema.typeName}ResourceMergeAndPatch`;
+  if (partialBodyTypeNames.has(typeName)) {
+    return null;
+  } else {
+    partialBodyTypeNames.add(typeName);
+  }
+  if (contentType.includes("application/merge-patch+json")) {
+    const type = `Partial<${schema.typeName}>`;
+    return {
+      // kind: StructureKind.TypeAlias,
+      ...(description && { docs: [{ description }] }),
+      name: `${typeName}`,
+      type,
+      isExported: true,
+    };
+  }
+  return undefined;
+}

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

@@ -0,0 +1,80 @@
+import { joinPaths } from "@typespec/compiler";
+import { OPERATION_LRO_HIGH_PRIORITY, 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 { hasPollingOperations } from "./helpers/operation-helpers.js";
+import { pollingContent } from "./static/polling-content.js";
+
+interface LroDetail {
+  clientOverload?: boolean;
+  overloadMap?: ResponseMap[];
+  importedResponses?: string[];
+}
+
+interface ResponseMap {
+  initialResponses: string;
+  finalResponses: string;
+  precedence?: number;
+}
+
+export function buildPollingHelper(model: RLCModel) {
+  if (!hasPollingOperations(model)) {
+    return;
+  }
+
+  const lroDetail: LroDetail = buildLroHelperDetail(model);
+  const readmeFileContents = hbs.compile(pollingContent, { noEscape: true });
+  const { srcPath } = model;
+  return {
+    path: joinPaths(srcPath, "pollingHelper.ts"),
+    content: readmeFileContents(lroDetail),
+  };
+}
+
+function buildLroHelperDetail(model: RLCModel): LroDetail {
+  if (!model.helperDetails?.clientLroOverload) {
+    return {
+      clientOverload: false,
+    };
+  }
+  const mapDetail = [];
+  const pathDictionary = model.paths;
+  const responses = new Set<string>();
+  for (const details of Object.values(pathDictionary)) {
+    for (const methodDetails of Object.values(details.methods)) {
+      const firstMethod = methodDetails[0];
+      if (!firstMethod) {
+        continue;
+      }
+      const lroDetail = firstMethod.operationHelperDetail?.lroDetails;
+      if (lroDetail?.isLongRunning) {
+        const initialResponses = firstMethod.responseTypes.success.concat(
+          firstMethod.responseTypes.error,
+        );
+
+        const finalResponse = lroDetail.logicalResponseTypes?.success.concat(
+          firstMethod.responseTypes.error,
+        );
+
+        if (initialResponses && finalResponse) {
+          initialResponses.forEach((n) => responses.add(n));
+          finalResponse.forEach((n) => responses.add(n));
+          mapDetail!.push({
+            initialResponses: initialResponses.join("|"),
+            finalResponses: finalResponse.join("|"),
+            precedence: lroDetail.precedence ?? OPERATION_LRO_HIGH_PRIORITY,
+          });
+        }
+      }
+    }
+  }
+
+  // Sorted by the precedence
+  mapDetail.sort((d1, d2) => d1.precedence - d2.precedence);
+  return {
+    clientOverload: responses.size > 0 && mapDetail.length > 0,
+    importedResponses: Array.from(responses),
+    overloadMap: mapDetail,
+  };
+}

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

@@ -0,0 +1,170 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { joinPaths } from "@typespec/compiler";
+import {
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  PropertySignatureStructure,
+  StructureKind,
+} from "ts-morph";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import { 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({ useInMemoryFileSystem: true });
+  const srcPath = model.srcPath;
+  const filePath = joinPaths(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: `./outputModels.js`,
+      },
+    ]);
+  }
+  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;
+}