@azure-tools/typespec-ts 0.53.3 → 0.54.0

package/src/rlc-common/transformSampleGroups.ts

@@ -0,0 +1,458 @@
+import { generateParameterTypeValue } from "./helpers/valueGenerationUtil.js";
+import { getClientName } from "./helpers/nameConstructors.js";
+import { normalizeName, NameType, camelCase } from "./helpers/nameUtils.js";
+import { buildSchemaObjectMap } from "./helpers/schemaHelpers.js";
+import {
+  RLCModel,
+  RLCSampleGroup,
+  Paths,
+  OperationMethod,
+  RLCSampleDetail,
+  SampleParameters,
+  SampleParameter,
+  Schema,
+  PathMetadata,
+  OperationParameter
+} from "./interfaces.js";
+import { isAzurePackage } from "./helpers/packageUtil.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/transform/transform.ts

@@ -17,7 +17,7 @@ import {
   SchemaContext,
   transformSampleGroups,
   UrlInfo
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import { SdkClient } from "@azure-tools/typespec-client-generator-core";
 import { getDoc } from "@typespec/compiler";
 import { getServers } from "@typespec/http";

package/src/transform/transformApiVersionInfo.ts

@@ -5,7 +5,7 @@ import {
   extractPathApiVersion,
   SchemaContext,
   UrlInfo
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import {
   getHttpOperationWithCache,
   isApiVersion,

package/src/transform/transformHelperFunctionDetails.ts

@@ -1,4 +1,4 @@
-import { HelperFunctionDetails, PackageFlavor } from "@azure-tools/rlc-common";
+import { HelperFunctionDetails, PackageFlavor } from "../rlc-common/index.js";
 import {
   getHttpOperationWithCache,
   SdkClient

package/src/transform/transformParameters.ts

@@ -10,7 +10,7 @@ import {
   ParameterMetadata,
   Schema,
   SchemaContext
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import {
   HttpOperation,
   HttpOperationParameter,

package/src/transform/transformPaths.ts

@@ -10,7 +10,7 @@ import {
   SchemaContext,
   getParameterTypeName,
   getResponseTypeName
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import {
   SdkClient,
   getHttpOperationWithCache,

package/src/transform/transformResponses.ts

@@ -9,7 +9,7 @@ import {
   ResponseMetadata,
   Schema,
   SchemaContext
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import {
   getHttpOperationWithCache,
   SdkClient

package/src/transform/transformSchemas.ts

@@ -17,7 +17,7 @@ import {
   trimUsage
 } from "../utils/modelUtils.js";
 
-import { SchemaContext } from "@azure-tools/rlc-common";
+import { SchemaContext } from "../rlc-common/index.js";
 import { SdkContext } from "../utils/interfaces.js";
 import { useContext } from "../contextManager.js";
 import { listOperationsUnderRLCClient } from "../utils/clientUtils.js";

package/src/transform/transformTelemetryInfo.ts

@@ -1,4 +1,4 @@
-import { TelemetryInfo } from "@azure-tools/rlc-common";
+import { TelemetryInfo } from "../rlc-common/index.js";
 import {
   getHttpOperationWithCache,
   SdkClient,

package/src/transform/transfromRLCOptions.ts

@@ -6,7 +6,7 @@ import {
   PackageFlavor,
   RLCOptions,
   ServiceInfo
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import { getHttpOperationWithCache } from "@azure-tools/typespec-client-generator-core";
 import { getDoc, NoTarget, Program } from "@typespec/compiler";
 import { getAuthentication } from "@typespec/http";
@@ -95,7 +95,6 @@ function extractRLCOptions(
   const enableStorageCompat = emitterOptions["enable-storage-compat"] === true;
   const treatUnknownAsRecord =
     emitterOptions["treat-unknown-as-record"] === true;
-  const headAsBoolean = emitterOptions["head-as-boolean"] === true;
   const typespecTitleMap = emitterOptions["typespec-title-map"];
   const generateReactNativeTarget =
     emitterOptions["generate-react-native-target"] === true;
@@ -145,7 +144,6 @@ function extractRLCOptions(
     isMultiService,
     enableStorageCompat,
     treatUnknownAsRecord,
-    headAsBoolean,
     generateReactNativeTarget
   };
 }

package/src/utils/clientUtils.ts

@@ -16,7 +16,7 @@ import {
 } from "@typespec/compiler";
 import { SdkContext } from "./interfaces.js";
 import { ModularClientOptions } from "../modular/interfaces.js";
-import { NameType, normalizeName } from "@azure-tools/rlc-common";
+import { NameType, normalizeName } from "../rlc-common/index.js";
 
 export function getRLCClients(
   dpgContext: SdkContext,

package/src/utils/crossLanguageDef.ts

@@ -4,7 +4,7 @@
 import { SdkContext } from "./interfaces.js";
 import { transformModularEmitterOptions } from "../modular/buildModularOptions.js";
 import { getMethodHierarchiesMap } from "./operationUtil.js";
-import { NameType, normalizeName } from "@azure-tools/rlc-common";
+import { NameType, normalizeName } from "../rlc-common/index.js";
 import { UsageFlags } from "@azure-tools/typespec-client-generator-core";
 
 export function generateCrossLanguageDefinitionFile(dpgContext: SdkContext): {

package/src/utils/emitUtil.ts

@@ -4,7 +4,7 @@ import {
   File,
   isAzurePackage,
   RLCModel
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import { CompilerHost, Program, NoTarget } from "@typespec/compiler";
 import { dirname, join } from "path";
 import { format } from "prettier";

package/src/utils/interfaces.ts

@@ -1,4 +1,4 @@
-import { RLCOptions, SchemaContext } from "@azure-tools/rlc-common";
+import { RLCOptions, SchemaContext } from "../rlc-common/index.js";
 import { SdkContext as TCGCSdkContext } from "@azure-tools/typespec-client-generator-core";
 import { ModelProperty, Namespace } from "@typespec/compiler";
 import { KnownMediaType } from "./mediaTypes.js";

package/src/utils/modelUtils.ts

@@ -10,7 +10,7 @@ import {
   SchemaContext,
   isArraySchema,
   normalizeName
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import {
   Discriminator,
   EncodeData,

package/src/utils/operationUtil.ts

@@ -12,7 +12,7 @@ import {
   Paths,
   ResponseMetadata,
   ResponseTypes
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import { getLroMetadata } from "@azure-tools/typespec-azure-core";
 import {
   getDisablePageable,

package/src/utils/parameterUtils.ts

@@ -3,7 +3,7 @@ import {
   normalizeName,
   Schema,
   SchemaContext
-} from "@azure-tools/rlc-common";
+} from "../rlc-common/index.js";
 import { HttpOperationParameter } from "@typespec/http";
 import { getTypeName, isArrayType, isObjectOrDictType } from "./modelUtils.js";
 import { SdkContext } from "./interfaces.js";

package/LICENSE

@@ -1,21 +0,0 @@
-    MIT License
-
-    Copyright (c) Microsoft Corporation.
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE