@azure-tools/typespec-ts 0.54.1 → 0.54.2

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

@@ -0,0 +1,554 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as path from "path";
+import {
+  InterfaceDeclarationStructure,
+  Project,
+  PropertySignatureStructure,
+  SourceFile,
+  StructureKind,
+} from "ts-morph";
+import { getObjectInterfaceDeclaration } from "./build-object-types.js";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import {
+  getImportModuleName,
+  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();
+  const srcPath = model.srcPath;
+  const filePath = path.join(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(
+        model,
+        parameter,
+        baseParameterName,
+        internalReferences,
+        i,
+      );
+      const pathParameterDefinitions = buildPathParameterDefinitions(
+        model,
+        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,
+      );
+
+      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: getImportModuleName(
+          {
+            cjsName: `./models`,
+            esModulesName: `./models.js`,
+          },
+          model,
+        ),
+      },
+    ]);
+  }
+  // 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")) {
+    const platformTypesModuleSpecifier = model.options?.azureSdkForJs
+      ? "#platform/platform-types"
+      : getImportModuleName(
+          {
+            cjsName: `./platform-types`,
+            esModulesName: `./platform-types.js`,
+          },
+          model,
+        );
+    parametersFile.addImportDeclarations([
+      {
+        isTypeOnly: true,
+        namedImports: ["NodeReadableStream"],
+        moduleSpecifier: platformTypesModuleSpecifier,
+      },
+    ]);
+  }
+  return { path: filePath, content: parametersFile.getFullText() };
+}
+
+function buildQueryParameterDefinition(
+  model: RLCModel,
+  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(
+      model,
+      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(
+  model: RLCModel,
+  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 allDefinitions: InterfaceDeclarationStructure[] = [];
+
+  buildClientPathParameters();
+  buildMethodWrapParameters();
+  return allDefinitions;
+  function buildClientPathParameters() {
+    // we only have client-level path parameters if the source is from swagger
+    if (model.options?.sourceFrom === "TypeSpec") {
+      return;
+    }
+    const clientPathParams = pathParameters.length > 0 ? pathParameters : [];
+    const nameSuffix = requestIndex > 0 ? `${requestIndex}` : "";
+    const pathParameterInterfaceName = `${baseName}PathParam${nameSuffix}`;
+
+    const pathInterface = getPathInterfaceDefinition(clientPathParams, baseName);
+
+    if (pathInterface) {
+      parametersFile.addInterface(pathInterface);
+    }
+
+    internalReferences.add(pathParameterInterfaceName);
+
+    allDefinitions.push({
+      isExported: true,
+      kind: StructureKind.Interface,
+      name: pathParameterInterfaceName,
+      properties: [
+        {
+          name: "pathParameters",
+          type: `${baseName}PathParameters`,
+          kind: StructureKind.PropertySignature,
+        },
+      ],
+    });
+  }
+
+  function buildMethodWrapParameters() {
+    if (model.options?.sourceFrom === "Swagger") {
+      return;
+    }
+    // we only have method-level path parameters if the source is from typespec
+    const methodPathParams = pathParameters.length > 0 ? pathParameters : [];
+
+    // we only need to build the wrapper types if the path parameters are objects
+    const wrapperTypesDefinition = getGeneratedWrapperTypes(methodPathParams).map((wrap) => {
+      return getObjectInterfaceDeclaration(
+        model,
+        wrap.name,
+        wrap,
+        [SchemaContext.Input],
+        new Set<string>(),
+      );
+    });
+    allDefinitions.push(...wrapperTypesDefinition);
+  }
+}
+
+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);
+
+  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,83 @@
+import * as path from "path";
+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[];
+  isEsm?: boolean;
+}
+
+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: path.join(srcPath, "pollingHelper.ts"),
+    content: readmeFileContents(lroDetail),
+  };
+}
+
+function buildLroHelperDetail(model: RLCModel): LroDetail {
+  if (!model.helperDetails?.clientLroOverload) {
+    return {
+      clientOverload: false,
+      isEsm: model.options?.moduleKind === "esm",
+    };
+  }
+  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,
+    isEsm: model.options?.moduleKind === "esm",
+  };
+}