@azure-tools/typespec-ts 0.14.0 → 0.15.0

package/src/modular/emitModels.ts

@@ -1,7 +1,9 @@
 import { Project, SourceFile } from "ts-morph";
 import { getType } from "./helpers/typeHelpers.js";
-import { ModularCodeModel, Type } from "./modularCodeModel.js";
+import { Client, ModularCodeModel, Type } from "./modularCodeModel.js";
 import * as path from "path";
+import { getDocsFromDescription } from "./helpers/docsHelpers.js";
+import { buildOperationOptions } from "./buildOperations.js";
 
 /**
  * This function creates the file containing all the models defined in TypeSpec
@@ -13,7 +15,7 @@ export function buildModels(
   subfolder: string = ""
 ): SourceFile {
   const modelsFile = project.createSourceFile(
-    path.join(`${srcPath}/src/`, subfolder, `models/models.ts`)
+    path.join(`${srcPath}/`, subfolder, `models/models.ts`)
   );
 
   // We are generating both models and enums here
@@ -48,7 +50,7 @@ export function buildModels(
         name: model.name!,
         isExported: true,
         docs: [
-          model.description ?? "",
+          ...getDocsFromDescription(model.description),
           // If it is a fixed enum we don't need to list the known values in the docs as the
           // output will be a literal union which is self documenting
           model.isFixed
@@ -68,7 +70,7 @@ export function buildModels(
       modelsFile.addInterface({
         name: model.name,
         isExported: true,
-        docs: [model.description ?? ""],
+        docs: getDocsFromDescription(model.description),
         properties: properties.map((p) => {
           const propertyMetadata = getType(p.type);
           let propertyTypeName = propertyMetadata.name;
@@ -82,7 +84,7 @@ export function buildModels(
           }
           return {
             name: `"${p.clientName}"`,
-            docs: [p.description],
+            docs: getDocsFromDescription(p.description),
             hasQuestionToken: p.optional,
             isReadonly: p.readonly,
             type: propertyTypeName
@@ -117,3 +119,43 @@ function isAzureCoreError(t: Type) {
     t.isCoreErrorType === true
   );
 }
+
+export function buildModelsOptions(
+  client: Client,
+  project: Project,
+  srcPath: string = "src",
+  subfolder: string = ""
+) {
+  const modelOptionsFile = project.createSourceFile(
+    `${srcPath}/${subfolder}/models/options.ts`,
+    undefined,
+    {
+      overwrite: true
+    }
+  );
+  for (const operationGroup of client.operationGroups) {
+    operationGroup.operations.forEach((o) => {
+      buildOperationOptions(o, modelOptionsFile);
+    });
+  }
+  modelOptionsFile.addImportDeclarations([
+    {
+      moduleSpecifier: "@azure-rest/core-client",
+      namedImports: ["OperationOptions"]
+    }
+  ]);
+
+  modelOptionsFile.fixMissingImports();
+  modelOptionsFile
+    .getImportDeclarations()
+    .filter((id) => {
+      return (
+        id.isModuleSpecifierRelative() &&
+        !id.getModuleSpecifierValue().endsWith(".js")
+      );
+    })
+    .map((id) => {
+      id.setModuleSpecifier(id.getModuleSpecifierValue() + ".js");
+      return id;
+    });
+}

package/src/modular/helpers/clientHelpers.ts

@@ -1,11 +1,13 @@
 import { OptionalKind, ParameterDeclarationStructure } from "ts-morph";
 import { Client } from "../modularCodeModel.js";
-import { getParameterType } from "./parameterHelpers.js";
+import { getType } from "./typeHelpers.js";
+import { getClientName } from "./namingHelpers.js";
 
 export function getClientParameters(
   client: Client
 ): OptionalKind<ParameterDeclarationStructure>[] {
-  const { name, parameters } = client;
+  const { parameters } = client;
+  const name = getClientName(client);
   const optionsParam = {
     name: "options",
     type: `${name}ClientOptions`,
@@ -22,7 +24,7 @@ export function getClientParameters(
       .map<OptionalKind<ParameterDeclarationStructure>>((p) => {
         return {
           name: p.clientName,
-          type: getParameterType(p)
+          type: getType(p.type).name
         };
       }),
     optionsParam

package/src/modular/helpers/docsHelpers.ts

@@ -0,0 +1,10 @@
+export function getFixmeForMultilineDocs(fixme: string[]): string[] {
+  return fixme.map((fixme) => ` @fixme ${fixme}`);
+}
+
+export function getDocsFromDescription(description?: string): string[] {
+  if (!description || description.trim().length === 0) {
+    return [];
+  }
+  return [description];
+}

package/src/modular/helpers/operationHelpers.ts

@@ -6,6 +6,7 @@ import {
 import { toPascalCase } from "../../utils/casingUtils.js";
 import {
   BodyParameter,
+  ModularCodeModel,
   Operation,
   Parameter,
   Property,
@@ -20,7 +21,10 @@ import {
   normalizeName
 } from "@azure-tools/rlc-common";
 import { getOperationName } from "./namingHelpers.js";
-import { getFixmeForMultilineDocs } from "./fixmeHelpers.js";
+import {
+  getFixmeForMultilineDocs,
+  getDocsFromDescription
+} from "./docsHelpers.js";
 
 function getRLCResponseType(rlcResponse?: OperationResponse) {
   if (!rlcResponse?.responses) {
@@ -41,11 +45,9 @@ function getRLCResponseType(rlcResponse?: OperationResponse) {
 
 export function getSendPrivateFunction(
   operation: Operation,
-  clientType: string
+  clientType: string,
+  importSet: Map<string, Set<string>>
 ): OptionalKind<FunctionDeclarationStructure> {
-  if (operation.name === "uploadTestFile") {
-    operation;
-  }
   const parameters = getOperationSignatureParameters(operation, clientType);
   const { name } = getOperationName(operation);
 
@@ -65,7 +67,8 @@ export function getSendPrivateFunction(
     `return context.path("${operationPath}", ${getPathParameters(
       operation
     )}).${operationMethod}({...operationOptionsToRequestParameters(options), ${getRequestParameters(
-      operation
+      operation,
+      importSet
     )}});`
   );
 
@@ -78,7 +81,8 @@ export function getSendPrivateFunction(
 export function getDeserializePrivateFunction(
   operation: Operation,
   needSubClient: boolean,
-  needUnexpectedHelper: boolean
+  needUnexpectedHelper: boolean,
+  importSet: Map<string, Set<string>>
 ): OptionalKind<FunctionDeclarationStructure> {
   const { name } = getOperationName(operation);
 
@@ -126,12 +130,21 @@ export function getDeserializePrivateFunction(
     statements.push(`return result.body`);
   } else if (response?.type?.elementType) {
     statements.push(
-      `return ${deserializeResponseValue(response.type, "result.body")}`
+      `return ${deserializeResponseValue(
+        response.type,
+        "result.body",
+        importSet,
+        response.type.nullable !== undefined ? !response.type.nullable : false
+      )}`
     );
   } else if (response?.type?.properties) {
     statements.push(
       `return {`,
-      getResponseMapping(response.type.properties ?? []).join(","),
+      getResponseMapping(
+        response.type.properties ?? [],
+        "result.body",
+        importSet
+      ).join(","),
       `}`
     );
   } else if (returnType.type === "void") {
@@ -223,7 +236,10 @@ export function getOperationFunction(
 
   const { name, fixme = [] } = getOperationName(operation);
   const functionStatement: OptionalKind<FunctionDeclarationStructure> = {
-    docs: [operation.description, ...getFixmeForMultilineDocs(fixme)],
+    docs: [
+      ...getDocsFromDescription(operation.description),
+      ...getFixmeForMultilineDocs(fixme)
+    ],
     isAsync: true,
     isExported: true,
     name: normalizeName(operation.name, NameType.Operation, true),
@@ -255,7 +271,10 @@ export function getOperationOptionsName(operation: Operation) {
  * RLC internally. This will translate High Level parameters into the RLC ones.
  * Figuring out what goes in headers, body, path and qsp.
  */
-function getRequestParameters(operation: Operation): string {
+function getRequestParameters(
+  operation: Operation,
+  importSet: Map<string, Set<string>>
+): string {
   if (!operation.parameters) {
     return "";
   }
@@ -277,7 +296,9 @@ function getRequestParameters(operation: Operation): string {
 
   for (const param of operationParameters) {
     if (param.location === "header" || param.location === "query") {
-      parametersImplementation[param.location].push(getParameterMap(param));
+      parametersImplementation[param.location].push(
+        getParameterMap(param, importSet)
+      );
     }
   }
 
@@ -299,30 +320,60 @@ function getRequestParameters(operation: Operation): string {
     )}},`;
   }
 
-  paramStr = `${paramStr}${buildBodyParameter(operation.bodyParameter)}`;
+  paramStr = `${paramStr}${buildBodyParameter(
+    operation.bodyParameter,
+    importSet
+  )}`;
 
   return paramStr;
 }
 
-function buildBodyParameter(bodyParameter: BodyParameter | undefined) {
+function buildBodyParameter(
+  bodyParameter: BodyParameter | undefined,
+  importSet: Map<string, Set<string>>
+) {
   if (!bodyParameter) {
     return "";
   }
 
   if (bodyParameter.type.type === "model") {
     const bodyParts: string[] = [];
+    let hasSerializeBody = false;
     for (const param of bodyParameter?.type.properties?.filter(
       (p) => !p.readonly
     ) ?? []) {
-      bodyParts.push(getParameterMap(param));
+      if (param.type.type === "model" && isRequired(param)) {
+        hasSerializeBody = true;
+        bodyParts.push(
+          ...getRequestModelMapping(param.type, param.clientName, importSet)
+        );
+      } else {
+        bodyParts.push(getParameterMap(param, importSet));
+      }
     }
 
     if (bodyParameter && bodyParameter.type.properties) {
-      return `\nbody: {${bodyParts.join(",\n")}},`;
+      if (hasSerializeBody) {
+        return `\nbody: {"${bodyParameter.restApiName}": {${bodyParts.join(
+          ",\n"
+        )}}},`;
+      } else {
+        return `\nbody: {${bodyParts.join(",\n")}},`;
+      }
     }
   }
 
   if (bodyParameter.type.type === "list") {
+    if (bodyParameter.type.elementType?.type === "model") {
+      const bodyParts = getRequestModelMapping(
+        bodyParameter.type.elementType,
+        "p",
+        importSet
+      );
+      return `\nbody: (${bodyParameter.clientName} ?? []).map((p) => { return {
+        ${bodyParts.join(", ")}
+      };}),`;
+    }
     return `\nbody: ${bodyParameter.clientName},`;
   }
 
@@ -336,21 +387,24 @@ function buildBodyParameter(bodyParameter: BodyParameter | undefined) {
 /**
  * This function helps with renames, translating client names to rest api names
  */
-function getParameterMap(param: Parameter | Property) {
+function getParameterMap(
+  param: Parameter | Property,
+  importSet: Map<string, Set<string>>
+): string {
   if (isConstant(param)) {
     return getConstantValue(param);
   }
 
   if (isOptionalWithouDefault(param)) {
-    return getOptionalWithoutDefault(param);
+    return getOptionalWithoutDefault(param, importSet);
   }
 
   if (isOptionalWithDefault(param)) {
-    return getOptionalWithDefault(param);
+    return getOptionalWithDefault(param, importSet);
   }
 
   if (isRequired(param)) {
-    return getRequired(param);
+    return getRequired(param, importSet);
   }
 
   throw new Error(`Parameter ${param.clientName} is not supported`);
@@ -388,7 +442,14 @@ function isRequired(param: Parameter | Property): param is RequiredType {
   return !param.optional;
 }
 
-function getRequired(param: RequiredType) {
+function getRequired(param: RequiredType, importSet: Map<string, Set<string>>) {
+  if (param.type.type === "model") {
+    return `"${param.restApiName}": ${getRequestModelMapping(
+      param.type,
+      param.clientName,
+      importSet
+    ).join(",")}`;
+  }
   return `"${param.restApiName}": ${param.clientName}`;
 }
 
@@ -423,7 +484,17 @@ function isOptionalWithouDefault(
 ): param is OptionalWithoutDefaultType {
   return Boolean(param.optional && !param.clientDefaultValue);
 }
-function getOptionalWithoutDefault(param: OptionalWithoutDefaultType) {
+function getOptionalWithoutDefault(
+  param: OptionalWithoutDefaultType,
+  importSet: Map<string, Set<string>>
+) {
+  if (param.type.type === "model") {
+    return `"${param.restApiName}": {${getRequestModelMapping(
+      param.type,
+      "options?." + param.clientName + "?",
+      importSet
+    ).join(", ")}}`;
+  }
   return `"${param.restApiName}": options?.${param.clientName}`;
 }
 
@@ -436,7 +507,17 @@ function isOptionalWithDefault(
   return Boolean(param.clientDefaultValue);
 }
 
-function getOptionalWithDefault(param: OptionalWithDefaultType) {
+function getOptionalWithDefault(
+  param: OptionalWithDefaultType,
+  importSet: Map<string, Set<string>>
+) {
+  if (param.type.type === "model") {
+    return `"${param.restApiName}": {${getRequestModelMapping(
+      param.type,
+      "options?." + param.clientName,
+      importSet
+    ).join(", ")}} ?? ${getQuotedValue(param)}`;
+  }
   return `"${param.restApiName}": options.${
     param.clientName
   } ?? ${getQuotedValue(param)}`;
@@ -500,29 +581,94 @@ function getNullableCheck(name: string, type: Type) {
 
   return `${name} === null ? null :`;
 }
+
+/**
+ *
+ * This function helps translating an HLC request to RLC request,
+ * extracting properties from body and headers and building the RLC response object
+ */
+function getRequestModelMapping(
+  modelPropertyType: Type,
+  propertyPath: string = "body",
+  importSet: Map<string, Set<string>>
+) {
+  if (!modelPropertyType.properties || !modelPropertyType.properties) {
+    return [];
+  }
+  const props: string[] = [];
+  const properties: Property[] = modelPropertyType.properties;
+  for (const property of properties) {
+    if (property.readonly) {
+      continue;
+    }
+    const propertyFullName = `${propertyPath}.${property.restApiName}`;
+    if (property.type.type === "model") {
+      let definition;
+      if (property.type.isCoreErrorType) {
+        definition = `"${property.restApiName}": ${getNullableCheck(
+          propertyFullName,
+          property.type
+        )} ${
+          !property.optional ? "" : `!${propertyFullName} ? undefined :`
+        } ${propertyFullName}`;
+      } else {
+        definition = `"${property.restApiName}": ${getNullableCheck(
+          propertyFullName,
+          property.type
+        )} ${
+          !property.optional ? "" : `!${propertyFullName} ? undefined :`
+        } {${getRequestModelMapping(
+          property.type,
+          `${propertyPath}.${property.restApiName}${
+            property.optional ? "?" : ""
+          }`,
+          importSet
+        )}}`;
+      }
+
+      props.push(definition);
+    } else {
+      const dot = propertyPath.endsWith("?") ? "." : "";
+      const restValue = `${
+        propertyPath ? `${propertyPath}${dot}` : `${dot}`
+      }["${property.clientName}"]`;
+      props.push(
+        `"${property.restApiName}": ${serializeRequestValue(
+          property.type,
+          restValue,
+          importSet
+        )}`
+      );
+    }
+  }
+
+  return props;
+}
+
 /**
  * This function helps translating an RLC response to an HLC response,
  * extracting properties from body and headers and building the HLC response object
  */
-function getResponseMapping(
+export function getResponseMapping(
   properties: Property[],
-  propertyPath: string = "result.body"
+  propertyPath: string = "result.body",
+  importSet: Map<string, Set<string>>
 ) {
   const props: string[] = [];
   for (const property of properties) {
     // TODO: Do we need to also add headers in the result type?
-    const propertyFullName = `${propertyPath}.${property.clientName}`;
+    const propertyFullName = `${propertyPath}.${property.restApiName}`;
     if (property.type.type === "model") {
       let definition;
       if (property.type.isCoreErrorType) {
-        definition = `"${property.restApiName}": ${getNullableCheck(
+        definition = `"${property.clientName}": ${getNullableCheck(
           propertyFullName,
           property.type
         )} ${
           !property.optional ? "" : `!${propertyFullName} ? undefined :`
         } ${propertyFullName}`;
       } else {
-        definition = `"${property.restApiName}": ${getNullableCheck(
+        definition = `"${property.clientName}": ${getNullableCheck(
           propertyFullName,
           property.type
         )} ${
@@ -531,7 +677,8 @@ function getResponseMapping(
           property.type.properties ?? [],
           `${propertyPath}.${property.restApiName}${
             property.optional ? "?" : ""
-          }`
+          }`,
+          importSet
         )}}`;
       }
 
@@ -544,7 +691,9 @@ function getResponseMapping(
       props.push(
         `"${property.clientName}": ${deserializeResponseValue(
           property.type,
-          restValue
+          restValue,
+          importSet,
+          property.optional !== undefined ? !property.optional : false
         )}`
       );
     }
@@ -558,29 +707,100 @@ function getResponseMapping(
  * We need to drill down into Array elements to make sure that the element type is
  * deserialized correctly
  */
-function deserializeResponseValue(type: Type, restValue: string): string {
+function deserializeResponseValue(
+  type: Type,
+  restValue: string,
+  importSet: Map<string, Set<string>>,
+  required: boolean
+): string {
+  const coreUtilSet = importSet.get("@azure/core-util");
   switch (type.type) {
     case "datetime":
-      return `new Date(${restValue} ?? "")`;
-    case "byte-array":
-      return `Buffer.from(${restValue} ?? "")`;
+      return required
+        ? `new Date(${restValue})`
+        : `${restValue} !== undefined? new Date(${restValue}): undefined`;
+    case "combined":
+      return `${restValue} as any`;
     case "list":
       if (type.elementType?.type === "model") {
         return `(${restValue} ?? []).map(p => ({${getResponseMapping(
           type.elementType?.properties ?? [],
-          "p"
+          "p",
+          importSet
         )}}))`;
       } else if (
         type.elementType?.properties?.some((p) => needsDeserialize(p.type))
       ) {
         return `(${restValue} ?? []).map(p => ${deserializeResponseValue(
           type.elementType!,
-          "p"
+          "p",
+          importSet,
+          required
         )})`;
       } else {
         return restValue;
       }
+    case "byte-array":
+      if (!coreUtilSet) {
+        importSet.set(
+          "@azure/core-util",
+          new Set<string>().add("stringToUint8Array")
+        );
+      } else {
+        coreUtilSet.add("stringToUint8Array");
+      }
+      return `typeof ${restValue} === 'string'
+      ? stringToUint8Array(${restValue}, "${type.format ?? "base64"}")
+      : ${restValue}`;
+    default:
+      return restValue;
+  }
+}
 
+/**
+ * This function helps converting strings into JS complex types recursively.
+ * We need to drill down into Array elements to make sure that the element type is
+ * deserialized correctly
+ */
+function serializeRequestValue(
+  type: Type,
+  restValue: string,
+  importSet: Map<string, Set<string>> = new Map<string, Set<string>>()
+): string {
+  const coreUtilSet = importSet.get("@azure/core-util");
+  switch (type.type) {
+    case "datetime":
+      return `${restValue} !== undefined ? new Date(${restValue}): undefined`;
+    case "list":
+      if (type.elementType?.type === "model") {
+        return `(${restValue} ?? []).map(p => ({${getResponseMapping(
+          type.elementType?.properties ?? [],
+          "p",
+          importSet
+        )}}))`;
+      } else if (
+        type.elementType?.properties?.some((p) => needsDeserialize(p.type))
+      ) {
+        return `(${restValue} ?? []).map(p => ${serializeRequestValue(
+          type.elementType!,
+          "p",
+          importSet
+        )})`;
+      } else {
+        return restValue;
+      }
+    case "byte-array":
+      if (!coreUtilSet) {
+        importSet.set(
+          "@azure/core-util",
+          new Set<string>().add("uint8ArrayToString")
+        );
+      } else {
+        coreUtilSet.add("uint8ArrayToString");
+      }
+      return `${restValue} !== undefined ? uint8ArrayToString(${restValue}, "${
+        type.format ?? "base64"
+      }"): undefined`;
     default:
       return restValue;
   }
@@ -589,3 +809,24 @@ function deserializeResponseValue(type: Type, restValue: string): string {
 function needsDeserialize(type?: Type) {
   return type?.type === "datetime" || type?.type === "model";
 }
+
+export function hasLROOperation(codeModel: ModularCodeModel) {
+  return (codeModel.clients ?? []).some((c) =>
+    (c.operationGroups ?? []).some((og) =>
+      (og.operations ?? []).some(
+        (op) => op.discriminator === "lro" || op.discriminator === "lropaging"
+      )
+    )
+  );
+}
+
+export function hasPagingOperation(codeModel: ModularCodeModel) {
+  return (codeModel.clients ?? []).some((c) =>
+    (c.operationGroups ?? []).some((og) =>
+      (og.operations ?? []).some(
+        (op) =>
+          op.discriminator === "paging" || op.discriminator === "lropaging"
+      )
+    )
+  );
+}

package/src/modular/helpers/typeHelpers.ts

@@ -23,6 +23,12 @@ export function getType(type: Type): TypeMetadata {
         originModule: "@azure/core-auth",
         isRelative: false
       };
+    case "OAuth2":
+      return {
+        name: "TokenCredential",
+        originModule: "@azure/core-auth",
+        isRelative: false
+      };
     case "boolean":
       return { name: getNullableType(type.type, type) };
     case "constant": {