@azure-tools/typespec-ts 0.54.0 → 0.54.2

package/src/rlc-common/test/build-snippets.ts

@@ -0,0 +1,29 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import { getClientName } from "../helpers/name-constructors.js";
+import { RLCModel } from "../interfaces.js";
+import { snippetsContent } from "./template.js";
+
+export function buildSnippets(model: RLCModel, clientName?: string, azureSdkForJs?: boolean) {
+  const azureSdkForJsInfo = azureSdkForJs ? azureSdkForJs : model.options?.azureSdkForJs;
+  // to keep the same config for azure scope in buildReadmeFile.ts
+  if (
+    (model?.options?.packageDetails?.scopeName === "azure" ||
+      model?.options?.packageDetails?.scopeName === "azure-rest") &&
+    model.options.addCredentials &&
+    azureSdkForJsInfo
+  ) {
+    return {
+      path: "test/snippets.spec.ts",
+      content: hbs.compile(snippetsContent, { noEscape: true })({
+        clientClassName: clientName ? clientName : getClientName(model),
+        azureArm: model.options?.azureArm,
+        azureSdkForJs: azureSdkForJsInfo,
+        isModularLibrary: model.options.isModularLibrary,
+        hasSubscriptionId: model.options.hasSubscriptionId,
+      }),
+    };
+  }
+  return undefined;
+}

package/src/rlc-common/transform-sample-groups.ts

@@ -0,0 +1,407 @@
+import { getClientName } from "./helpers/name-constructors.js";
+import { NameType, camelCase, normalizeName } from "./helpers/name-utils.js";
+import { isAzurePackage } from "./helpers/package-util.js";
+import { buildSchemaObjectMap } from "./helpers/schema-helpers.js";
+import { generateParameterTypeValue } from "./helpers/value-generation-util.js";
+import {
+  OperationMethod,
+  OperationParameter,
+  PathMetadata,
+  Paths,
+  RLCModel,
+  RLCSampleDetail,
+  RLCSampleGroup,
+  SampleParameter,
+  SampleParameters,
+  Schema,
+} from "./interfaces.js";
+
+/**
+ * Transform the sample data based RLC detail e.g path, operations & schemas
+ * @param model RLC detail
+ * @param allowMockValue allow to mock value if not exist, currently we always generate mock value
+ * @returns Generated sample data or undefined if not support to generate
+ */
+export function transformSampleGroups(model: RLCModel, allowMockValue = true) {
+  if (model.options?.multiClient || model.options?.isModularLibrary) {
+    // Not support to generate if multiple clients
+    // Not support to generate if modular libraries
+    return;
+  }
+  if ((model.sampleGroups && model.sampleGroups.length > 0) || !allowMockValue) {
+    // Skip to transform if already has sample data
+    // Skip to transform if not allow to mock value
+    return;
+  }
+  const rlcSampleGroups: RLCSampleGroup[] = [];
+  // Get all paths
+  const paths: Paths = model.paths;
+  const clientName = getClientName(model);
+  const clientInterfaceName = clientName.endsWith("Client")
+    ? `${clientName}`
+    : `${clientName}Client`;
+  const defaultFactoryName = normalizeName(
+    camelCase(`create ${clientInterfaceName}`),
+    NameType.Method,
+  );
+  const packageName = model.options?.packageDetails?.name ?? "";
+  const methodParameterMap = buildMethodParamMap(model);
+  const schemaObjectMap = buildSchemaObjectMap(model);
+  for (const path in paths) {
+    const pathDetails = paths[path];
+    if (!pathDetails) {
+      continue;
+    }
+    const methods = pathDetails.methods;
+    for (const method in methods) {
+      const importedDict: Record<string, Set<string>> = {};
+      const methodArray = methods[method];
+      if (!methodArray || methodArray.length === 0) {
+        continue;
+      }
+      const detail = methodArray[0];
+      if (!detail) {
+        continue;
+      }
+      const operatonConcante = getOperationConcate(
+        detail.operationName,
+        pathDetails.operationGroupName,
+        model.options?.sourceFrom,
+      );
+      const operationPrefix = normalizeName(
+        camelCase(transformSpecialLetterToSpace(operatonConcante)),
+        NameType.Operation,
+      );
+      const sampleGroup: RLCSampleGroup = {
+        filename: `${operationPrefix}Sample`,
+        defaultFactoryName,
+        clientPackageName: packageName,
+        samples: [],
+      };
+
+      // initialize the sample
+      const sample: RLCSampleDetail = {
+        description: `call operation ${detail.operationName}`,
+        name: `${operationPrefix}Sample`,
+        path,
+        defaultFactoryName,
+        clientParamAssignments: [],
+        pathParamAssignments: [],
+        methodParamAssignments: [],
+        clientParamNames: "",
+        pathParamNames: "",
+        methodParamNames: "",
+        method,
+        isLRO: detail.operationHelperDetail?.lroDetails?.isLongRunning ?? false,
+        isPaging: detail.operationHelperDetail?.isPaging ?? false,
+        useLegacyLro: false,
+      };
+      // client-level, path-level and method-level parameter preparation
+      const parameters: SampleParameters = {
+        client: convertClientLevelParameters(model, importedDict, schemaObjectMap),
+        path: convertPathLevelParameters(pathDetails, path, schemaObjectMap),
+        method: convertMethodLevelParameters(
+          methodArray,
+          schemaObjectMap,
+          methodParameterMap.get(operatonConcante),
+        ),
+      };
+      // enrich parameter details
+      enrichParameterInSample(sample, parameters);
+      // enrich LRO and pagination info
+      enrichLROAndPagingInSample(detail, importedDict, packageName);
+      sampleGroup.samples.push(sample);
+      rlcSampleGroups.push(sampleGroup);
+      enrichImportedString(sampleGroup, importedDict, defaultFactoryName, packageName);
+    }
+  }
+  return rlcSampleGroups;
+}
+
+function enrichLROAndPagingInSample(
+  operation: OperationMethod,
+  importedDict: Record<string, Set<string>>,
+  packageName: string,
+) {
+  const isLRO = operation.operationHelperDetail?.lroDetails?.isLongRunning ?? false,
+    isPaging = operation.operationHelperDetail?.isPaging ?? false;
+  if (isPaging) {
+    if (isLRO) {
+      // TODO: report warning this is not supported
+    }
+    addValueInImportedDict(packageName, "paginate", importedDict);
+  } else if (isLRO) {
+    addValueInImportedDict(packageName, "getLongRunningPoller", importedDict);
+  }
+}
+
+function transformSpecialLetterToSpace(str: string) {
+  if (!str) {
+    return str;
+  }
+  return str
+    .replace(/_/g, " ")
+    .replace(/\//g, " Or ")
+    .replace(/,|\.|\(|\)/g, " ")
+    .replace("'s ", " ");
+}
+
+function enrichImportedString(
+  sampleGroup: RLCSampleGroup,
+  importedDict: Record<string, Set<string>>,
+  defaultFactoryName: string,
+  packageName: string,
+) {
+  const importedTypes: string[] = [];
+  if (!importedDict[packageName] || importedDict[packageName].size === 0) {
+    importedTypes.push(`import ${defaultFactoryName} from "${packageName}";`);
+  }
+  for (const key in importedDict) {
+    const importedSet = importedDict[key];
+    if (!importedSet) {
+      continue;
+    }
+    const values = Array.from(importedSet).join(", ");
+    const hasDefaultFactory = key === packageName ? `${defaultFactoryName},` : "";
+    importedTypes.push(`import ${hasDefaultFactory} { ${values} } from "${key}";`);
+  }
+  sampleGroup.importedTypes = importedTypes;
+}
+
+function enrichParameterInSample(sample: RLCSampleDetail, parameters: SampleParameters) {
+  sample.clientParamAssignments = getAssignmentStrArray(parameters.client);
+  sample.clientParamNames = getContactParameterNames(parameters.client);
+  sample.pathParamAssignments = getAssignmentStrArray(parameters.path);
+  sample.pathParamNames = getContactParameterNames(parameters.path);
+  // Directly apply the inline option value as method parameter
+  sample.methodParamNames = parameters.method.length > 0 ? (parameters.method[0]?.value ?? "") : "";
+}
+
+function getAssignmentStrArray(parameters: SampleParameter[]) {
+  return parameters.filter((p) => !!p.assignment).map((p) => p.assignment!);
+}
+
+function getContactParameterNames(parameters: SampleParameter[]) {
+  return parameters
+    .filter((p) => p.name != null)
+    .map((p) => p.name!)
+    .join(",");
+}
+
+function convertClientLevelParameters(
+  model: RLCModel,
+  importedDict: Record<string, Set<string>>,
+  schemaMap: Map<string, Schema>,
+): SampleParameter[] {
+  if (!model.options) {
+    return [];
+  }
+  const clientParams: SampleParameter[] = [];
+  const urlParameters = model?.urlInfo?.urlParameters?.filter(
+    // Do not include parameters with constant values in the signature, these should go in the options bag
+    (p) => p.value === undefined,
+  );
+  const {
+    addCredentials,
+    credentialScopes,
+    credentialKeyHeaderName,
+    customHttpAuthHeaderName,
+    flavor,
+  } = model.options;
+  const hasUrlParameter = !!urlParameters,
+    hasCredentials =
+      addCredentials && (credentialScopes || credentialKeyHeaderName || customHttpAuthHeaderName);
+
+  if (hasUrlParameter) {
+    // convert the host parameters in url
+    const clientParamAssignments = urlParameters.map((urlParameter) => {
+      const urlValue = generateParameterTypeValue(urlParameter.type, urlParameter.name, schemaMap);
+      const normalizedName = normalizeName(urlParameter.name, NameType.Parameter);
+      return {
+        name: normalizedName,
+        assignment: `const ${normalizedName} = ` + urlValue + `;`,
+      };
+    });
+
+    clientParams.push(...clientParamAssignments);
+  }
+  if (hasCredentials) {
+    // Currently only support token credential
+    const apiKeyCredentialPackage = isAzurePackage(model)
+      ? "@azure/core-auth"
+      : "@typespec/ts-http-runtime";
+    const tokenCredentialPackage = isAzurePackage(model)
+      ? "@azure/identity"
+      : "@typespec/ts-http-runtime";
+    if (credentialKeyHeaderName && isAzurePackage(model)) {
+      clientParams.push({
+        name: "credential",
+        assignment: `const credential = new AzureKeyCredential("{Your API key}");`,
+      });
+      addValueInImportedDict(apiKeyCredentialPackage, "AzureKeyCredential", importedDict);
+    } else if ((credentialKeyHeaderName && flavor !== "azure") || customHttpAuthHeaderName) {
+      clientParams.push({
+        name: "credential",
+        assignment: `const credential = { key: "{Your API key}"};`,
+      });
+    } else if (isAzurePackage(model)) {
+      clientParams.push({
+        name: "credential",
+        assignment: "const credential = new DefaultAzureCredential();",
+      });
+      addValueInImportedDict(tokenCredentialPackage, "DefaultAzureCredential", importedDict);
+    } else {
+      clientParams.push({
+        name: "credential",
+        assignment: `const credential = {getToken: () => Promise.resolve({ token: "{Your token}", expiresOnTimestamp: 0 })};`,
+      });
+    }
+  }
+  return clientParams;
+}
+
+function convertPathLevelParameters(
+  pathDetail: PathMetadata,
+  path: string,
+  schemaMap: Map<string, Schema>,
+): SampleParameter[] {
+  const pathItself = {
+    name: `"${path}"`,
+  };
+  const pathParams = (pathDetail || []).pathParameters.map((p) => {
+    const pathParam: SampleParameter = {
+      name: normalizeName(p.name, NameType.Parameter),
+    };
+    const value = generateParameterTypeValue(p.type, p.name, schemaMap);
+    pathParam.assignment = `const ${pathParam.name} =` + value + `;`;
+    return pathParam;
+  });
+  return [pathItself].concat(pathParams);
+}
+
+function convertMethodLevelParameters(
+  methods: OperationMethod[],
+  schemaMap: Map<string, Schema>,
+  operationParameter?: OperationParameter,
+): SampleParameter[] {
+  if (
+    !methods ||
+    methods.length === 0 ||
+    !operationParameter ||
+    operationParameter.parameters.length === 0
+  ) {
+    return [];
+  }
+  const rawMethodParams = operationParameter.parameters;
+  const method = methods[0];
+  const requestParameter = rawMethodParams[0];
+  if (!method || !requestParameter) {
+    return [];
+  }
+  const hasInputParams = !!rawMethodParams && rawMethodParams.length > 0,
+    requireParam = !method.hasOptionalOptions;
+  if (!hasInputParams && !requireParam) {
+    return [];
+  }
+
+  const allSideAssignments = [],
+    querySideAssignments: string[] = [],
+    headerSideAssignments: string[] = [];
+  if (
+    !!requestParameter.body &&
+    requestParameter.body &&
+    requestParameter.body.body &&
+    requestParameter.body.body?.length > 0
+  ) {
+    const body = requestParameter.body.body[0];
+    if (body) {
+      const bodyTypeName = body.typeName ?? body.type;
+      if (bodyTypeName !== "string" && body.oriSchema) {
+        schemaMap.set(bodyTypeName, body.oriSchema);
+      }
+      allSideAssignments.push(
+        ` body: ` + generateParameterTypeValue(bodyTypeName, "body", schemaMap),
+      );
+    }
+  }
+
+  requestParameter.parameters
+    ?.filter((p) => p.type === "query")
+    .forEach((p) => {
+      const name = `${p.name}`;
+      querySideAssignments.push(
+        `${name}: ` + generateParameterTypeValue(p.param.type, name, schemaMap),
+      );
+    });
+
+  if (querySideAssignments.length > 0) {
+    allSideAssignments.push(` queryParameters: { ` + querySideAssignments.join(", ") + `}`);
+  }
+  requestParameter.parameters
+    ?.filter((p) => p.type === "header")
+    .filter((p) => p.name.toLowerCase() !== "contenttype")
+    .forEach((p) => {
+      const name = `${p.name}`;
+      headerSideAssignments.push(
+        `${name}: ` + generateParameterTypeValue(p.param.type, name, schemaMap),
+      );
+    });
+  if (headerSideAssignments.length > 0) {
+    allSideAssignments.push(` headers: { ` + headerSideAssignments.join(", ") + `}`);
+  }
+  const contentType = requestParameter.parameters
+    ?.filter((p) => p.type === "header")
+    .filter((p) => p.name.toLowerCase() === "contenttype");
+  const firstContentType = contentType?.[0];
+  if (firstContentType) {
+    allSideAssignments.push(
+      ` ${firstContentType.name}: ` +
+        generateParameterTypeValue(firstContentType.param.type, firstContentType.name, schemaMap),
+    );
+  }
+  let value: string;
+  if (allSideAssignments.length > 0) {
+    value = `{ ` + allSideAssignments.join(", ") + `}`;
+  } else {
+    return [];
+  }
+
+  const optionParam: SampleParameter = {
+    name: "options",
+    assignment: `const options =` + value + `;`,
+    value,
+  };
+  return [optionParam];
+}
+
+function addValueInImportedDict(
+  key: string,
+  val: string,
+  importedDict: Record<string, Set<string>>,
+) {
+  if (!importedDict[key]) {
+    importedDict[key] = new Set<string>();
+  }
+  importedDict[key].add(val);
+}
+
+function buildMethodParamMap(model: RLCModel): Map<string, OperationParameter> {
+  const map = new Map<string, OperationParameter>();
+  (model.parameters ?? []).forEach((p) => {
+    const operatonConcante = getOperationConcate(
+      p.operationName,
+      p.operationGroup,
+      model.options?.sourceFrom,
+    );
+    map.set(operatonConcante, p);
+  });
+  return map;
+}
+
+function getOperationConcate(opName: string, opGroup: string, sourceFrom?: string) {
+  return sourceFrom === "Swagger"
+    ? opGroup === "" || opGroup === "Client"
+      ? opName
+      : `${opGroup}${opName}`
+    : `${opGroup}_${opName}`;
+}

package/src/testing/index.ts

@@ -1,10 +1,7 @@
-import {
-  createTestLibrary,
-  findTestPackageRoot
-} from "@typespec/compiler/testing";
+import { createTestLibrary, findTestPackageRoot } from "@typespec/compiler/testing";
 
 export const TypespecTsTestLibrary = createTestLibrary({
   name: "@azure-tools/typespec-ts",
   // Set this to the absolute path to the root of the package. (e.g. in this case this file would be compiled to ./dist/src/testing/index.js)
-  packageRoot: await findTestPackageRoot(import.meta.url)
+  packageRoot: await findTestPackageRoot(import.meta.url),
 });

package/src/transform/transform-api-version-info.ts

@@ -0,0 +1,103 @@
+import {
+  getHttpOperationWithCache,
+  isApiVersion,
+  SdkClient,
+} from "@azure-tools/typespec-client-generator-core";
+import {
+  ApiVersionInfo,
+  ApiVersionPosition,
+  extractDefinedPosition,
+  extractPathApiVersion,
+  SchemaContext,
+  UrlInfo,
+} from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getDefaultApiVersionString, getSchemaForType, trimUsage } from "../utils/model-utils.js";
+
+export function transformApiVersionInfo(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  urlInfo?: UrlInfo,
+): ApiVersionInfo | undefined {
+  const queryVersionDetail = getOperationApiVersion(client, dpgContext);
+  const pathVersionDetail = extractPathApiVersion(urlInfo);
+  const isCrossedVersion =
+    queryVersionDetail || pathVersionDetail
+      ? Boolean(pathVersionDetail?.isCrossedVersion || queryVersionDetail?.isCrossedVersion)
+      : undefined;
+  const defaultValue =
+    (pathVersionDetail || queryVersionDetail) && !isCrossedVersion
+      ? (getDefaultApiVersionString(dpgContext) ??
+        pathVersionDetail?.defaultValue ??
+        queryVersionDetail?.defaultValue)
+      : undefined;
+
+  if (pathVersionDetail && queryVersionDetail) {
+    return pathVersionDetail;
+  }
+  if (pathVersionDetail && !queryVersionDetail) {
+    dpgContext.hasApiVersionInClient = true;
+  }
+  return {
+    definedPosition: extractDefinedPosition(queryVersionDetail, pathVersionDetail),
+    isCrossedVersion,
+    defaultValue,
+    required: pathVersionDetail?.required ?? queryVersionDetail?.required,
+  };
+}
+
+export function getOperationApiVersion(
+  client: SdkClient,
+  dpgContext: SdkContext,
+): ApiVersionInfo | undefined {
+  const apiVersionTypes = new Set<string>();
+  const locations = new Set<ApiVersionPosition>();
+  const required = new Set<boolean>();
+  dpgContext.hasApiVersionInClient = true;
+  let hasApiVersionInOperation: boolean;
+  for (const op of listOperationsUnderRLCClient(client)) {
+    hasApiVersionInOperation = false;
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    const params = route.parameters.parameters.filter(
+      (p) => (p.type === "query" || p.type === "path") && isApiVersion(dpgContext, p.param),
+    );
+    params.map((p) => {
+      const type = getSchemaForType(dpgContext, p.param.type, {
+        usage: [SchemaContext.Exception, SchemaContext.Input],
+        needRef: false,
+        relevantProperty: p.param,
+      });
+      required.add(!p.param.optional);
+      if (p.type === "query" || p.type === "path") {
+        locations.add(p.type);
+      }
+      const typeString = JSON.stringify(trimUsage(type));
+      apiVersionTypes.add(typeString);
+    });
+    if (apiVersionTypes.size > 1 || !dpgContext.hasApiVersionInClient) {
+      break;
+    }
+    if (params.length === 1) {
+      hasApiVersionInOperation = true;
+    }
+    if (!hasApiVersionInOperation) {
+      dpgContext.hasApiVersionInClient = false;
+    }
+  }
+  // If no api-version parameter defined return directly
+  if (apiVersionTypes.size === 0 || !dpgContext.hasApiVersionInClient) {
+    return;
+  }
+  const detail: ApiVersionInfo = {
+    definedPosition: locations.size > 1 ? "duplicate" : locations.values().next().value,
+    isCrossedVersion: apiVersionTypes.size > 1,
+    defaultValue: undefined, // We won't prompt the query versions into client one
+    required: required.values().next().value,
+  };
+  return detail;
+}

package/src/transform/transform-helper-function-details.ts

@@ -0,0 +1,88 @@
+import { getHttpOperationWithCache, SdkClient } from "@azure-tools/typespec-client-generator-core";
+import { HelperFunctionDetails, PackageFlavor } from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getCollectionFormat } from "../utils/model-utils.js";
+import {
+  extractPageDetails,
+  getSpecialSerializeInfo,
+  hasPagingOperations,
+  hasPollingOperations,
+} from "../utils/operation-util.js";
+
+export function transformHelperFunctionDetails(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  flavor?: PackageFlavor,
+): HelperFunctionDetails {
+  const serializeInfo = extractSpecialSerializeInfo(client, dpgContext);
+  // Disable paging and long running for non-Azure clients.
+  if (flavor !== "azure") {
+    return {
+      hasLongRunning: false,
+      hasPaging: false,
+      ...serializeInfo,
+    };
+  }
+
+  const annotationDetails = {
+    hasLongRunning: hasPollingOperations(client, dpgContext),
+  };
+  const details = extractClientPageDetails(client, dpgContext);
+  return {
+    ...(details ?? {}),
+    ...annotationDetails,
+    ...serializeInfo,
+  };
+}
+
+function extractClientPageDetails(client: SdkClient, dpgContext: SdkContext) {
+  const program = dpgContext.program;
+  if (!hasPagingOperations(client, dpgContext)) {
+    return;
+  }
+  const nextLinks = new Set<string>(["nextLink"]);
+  const itemNames = new Set<string>(["value"]);
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    const pagedDetail = extractPageDetails(program, route);
+    if (pagedDetail) {
+      pagedDetail.itemNames.forEach((name) => itemNames.add(name));
+      pagedDetail.nextLinkNames.forEach((name) => nextLinks.add(name));
+    }
+  }
+  // If there are more than one options for nextLink and item names we need to generate a
+  // more complex pagination helper.
+  return {
+    hasPaging: true,
+    pageDetails: {
+      itemNames: [...itemNames],
+      nextLinkNames: [...nextLinks],
+      isComplexPaging: nextLinks.size > 1 || itemNames.size > 1,
+    },
+  };
+}
+
+function extractSpecialSerializeInfo(client: SdkClient, dpgContext: SdkContext) {
+  let hasMultiCollection = false;
+  let hasCsvCollection = false;
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    route.parameters.parameters.forEach((parameter) => {
+      const format = getCollectionFormat(dpgContext, parameter as any);
+      const serializeInfo = getSpecialSerializeInfo(dpgContext, parameter.type, format!);
+      hasMultiCollection = hasMultiCollection
+        ? hasMultiCollection
+        : serializeInfo.hasMultiCollection;
+      hasCsvCollection = hasCsvCollection ? hasCsvCollection : serializeInfo.hasCsvCollection;
+    });
+  }
+  return {
+    hasMultiCollection,
+    hasCsvCollection,
+  };
+}