@azure-tools/typespec-ts 0.11.0 → 0.12.0-alpha.20230501.1

package/src/modular/helpers/operationHelpers.ts

@@ -0,0 +1,418 @@
+import {
+  FunctionDeclarationStructure,
+  OptionalKind,
+  ParameterDeclarationStructure
+} from "ts-morph";
+import { toPascalCase } from "../../casingUtils.js";
+import {
+  BodyParameter,
+  Operation,
+  Parameter,
+  Property,
+  Type
+} from "../modularCodeModel.js";
+import { buildType } from "./typeHelpers.js";
+
+/**
+ * This operation builds and returns the function declaration for an operation.
+ */
+export function getOperationFunction(
+  operation: Operation
+): OptionalKind<FunctionDeclarationStructure> {
+  const optionsType = getOperationOptionsName(operation);
+  // Extract required parameters
+  let parameters: OptionalKind<ParameterDeclarationStructure>[] = [];
+
+  if (operation.bodyParameter?.type.type === "model") {
+    parameters = (operation.bodyParameter?.type.properties ?? [])
+      .filter((p) => !p.optional)
+      .map((p) => buildType(p.clientName, p.type));
+  } else if (operation.bodyParameter?.type.type === "list") {
+    const bodyArray = operation.bodyParameter;
+    parameters.push(buildType(bodyArray.clientName, bodyArray.type));
+  }
+
+  parameters = parameters.concat(
+    operation.parameters
+      .filter(
+        (p) =>
+          p.implementation === "Method" &&
+          p.type.type !== "constant" &&
+          p.clientDefaultValue === undefined &&
+          !p.optional
+      )
+      .map((p) => buildType(p.clientName, p.type))
+  );
+
+  // Add context as the first parameter
+  parameters.unshift({ name: "context", type: "Client" });
+
+  // Add the options parameter
+  parameters.push({
+    name: "options",
+    type: optionsType,
+    initializer: "{ requestOptions: {} }"
+  });
+
+  // TODO: Support operation overloads
+  const response = operation.responses[0]!;
+  const returnType =
+    response?.type?.type === "model"
+      ? buildType(response.type.name, response.type)
+      : { name: "", type: "void" };
+
+  const functionStatement: OptionalKind<FunctionDeclarationStructure> = {
+    docs: [operation.description],
+    isAsync: true,
+    isExported: true,
+    name: operation.name,
+    parameters,
+    returnType: `Promise<${returnType.type}>`
+  };
+
+  const operationPath = operation.url;
+  const operationMethod = operation.method.toLowerCase();
+
+  const statements: string[] = [];
+  statements.push(
+    `const result = await context.path("${operationPath}", ${getPathParameters(
+      operation
+    )}).${operationMethod}({${getRequestParameters(operation)}});`
+  );
+
+  statements.push(`if(isUnexpected(result)){`, "throw result.body", "}");
+
+  if (!response?.type?.properties) {
+    statements.push(`return;`);
+  } else {
+    statements.push(
+      `return {`,
+      getResponseMapping(response.type.properties ?? []).join(","),
+      `}`
+    );
+  }
+  return {
+    ...functionStatement,
+    statements
+  };
+}
+
+export function getOperationOptionsName(operation: Operation) {
+  return `${toPascalCase(operation.groupName)}${toPascalCase(
+    operation.name
+  )}Options`;
+}
+
+/**
+ * This function build the request parameters that we will provide to the
+ * 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 {
+  if (!operation.parameters) {
+    return "";
+  }
+
+  const operationParameters = operation.parameters.filter(
+    (p) => p.implementation !== "Client" && !isContentType(p)
+  );
+
+  const contentTypeParameter = operation.parameters.find(isContentType);
+
+  const parametersImplementation: Record<
+    "header" | "query" | "body",
+    string[]
+  > = {
+    header: [],
+    query: [],
+    body: []
+  };
+
+  for (const param of operationParameters) {
+    if (param.location === "header" || param.location === "query") {
+      parametersImplementation[param.location].push(getParameterMap(param));
+    }
+  }
+
+  let paramStr = "";
+
+  if (contentTypeParameter) {
+    paramStr = `${getContentTypeValue(contentTypeParameter)},`;
+  }
+
+  if (parametersImplementation.header.length) {
+    paramStr = `${paramStr}\nheaders: {${parametersImplementation.header.join(
+      ",\n"
+    )}, ...options.requestOptions?.headers},`;
+  }
+
+  if (parametersImplementation.query.length) {
+    paramStr = `${paramStr}\nqueryParameters: {${parametersImplementation.query.join(
+      ",\n"
+    )}},`;
+  }
+
+  paramStr = `${paramStr}${buildBodyParameter(operation.bodyParameter)}`;
+
+  return paramStr;
+}
+
+function buildBodyParameter(bodyParameter: BodyParameter | undefined) {
+  if (!bodyParameter) {
+    return "";
+  }
+
+  if (bodyParameter.type.type === "model") {
+    const bodyParts: string[] = [];
+    for (const param of bodyParameter?.type.properties?.filter(
+      (p) => !p.readonly
+    ) ?? []) {
+      bodyParts.push(getParameterMap(param));
+    }
+
+    if (bodyParameter && bodyParameter.type.properties) {
+      return `\nbody: {${bodyParts.join(",\n")}},`;
+    }
+  }
+
+  if (bodyParameter.type.type === "list") {
+    return `\nbody: ${bodyParameter.clientName},`;
+  }
+
+  return "";
+}
+
+/**
+ * This function helps with renames, translating client names to rest api names
+ */
+function getParameterMap(param: Parameter | Property) {
+  if (isConstant(param)) {
+    return getConstantValue(param);
+  }
+
+  if (isOptionalWithouDefault(param)) {
+    return getOptionalWithoutDefault(param);
+  }
+
+  if (isOptionalWithDefault(param)) {
+    return getOptionalWithDefault(param);
+  }
+
+  if (isRequired(param)) {
+    return getRequired(param);
+  }
+
+  throw new Error(`Parameter ${param.clientName} is not supported`);
+}
+
+function isContentType(param: Parameter): boolean {
+  return (
+    param.location === "header" &&
+    param.restApiName.toLowerCase() === "content-type"
+  );
+}
+
+function getContentTypeValue(param: Parameter | Property) {
+  const defaultValue =
+    param.clientDefaultValue ?? param.type.clientDefaultValue;
+
+  if (!defaultValue) {
+    throw new Error(
+      `Constant ${param.clientName} does not have a default value`
+    );
+  }
+
+  if (defaultValue) {
+    return `contentType: (options.${param.clientName} as any) ?? "${defaultValue}"`;
+  } else {
+    return `contentType: options.${param.clientName}`;
+  }
+}
+
+type RequiredType = (Parameter | Property) & {
+  type: { optional: false | undefined; value: string };
+};
+
+function isRequired(param: Parameter | Property): param is RequiredType {
+  return !param.optional;
+}
+
+function getRequired(param: RequiredType) {
+  return `"${param.restApiName}": ${param.clientName}`;
+}
+
+type ConstantType = (Parameter | Property) & {
+  type: { type: "constant"; value: string };
+};
+
+function getConstantValue(param: ConstantType) {
+  const defaultValue =
+    param.clientDefaultValue ?? param.type.clientDefaultValue;
+
+  if (!defaultValue) {
+    throw new Error(
+      `Constant ${param.clientName} does not have a default value`
+    );
+  }
+
+  return `"${param.restApiName}": "${defaultValue}"`;
+}
+
+function isConstant(param: Parameter | Property): param is ConstantType {
+  return (
+    param.type.type === "constant" && param.clientDefaultValue !== undefined
+  );
+}
+
+type OptionalWithoutDefaultType = (Parameter | Property) & {
+  type: { optional: true; clientDefaultValue: never };
+};
+function isOptionalWithouDefault(
+  param: Parameter | Property
+): param is OptionalWithoutDefaultType {
+  return Boolean(param.optional && !param.clientDefaultValue);
+}
+function getOptionalWithoutDefault(param: OptionalWithoutDefaultType) {
+  return `...(options.${param.clientName} && {"${param.restApiName}": options.${param.clientName}})`;
+}
+
+type OptionalWithDefaultType = (Parameter | Property) & {
+  type: { optional: true; clientDefaultValue: string };
+};
+function isOptionalWithDefault(
+  param: Parameter | Property
+): param is OptionalWithDefaultType {
+  return Boolean(param.clientDefaultValue);
+}
+
+function getOptionalWithDefault(param: OptionalWithDefaultType) {
+  return `"${param.restApiName}": options.${
+    param.clientName
+  } ?? ${getQuotedValue(param)}`;
+}
+
+function getQuotedValue(param: OptionalWithDefaultType) {
+  if (param.type.type === "string") {
+    return `"${param.clientDefaultValue}"`;
+  } else {
+    return param.clientDefaultValue;
+  }
+}
+
+/**
+ * Builds the assignment for when a property or parameter has a default value
+ */
+function getDefaultValue(param: Parameter | Property) {
+  return (param.clientDefaultValue ?? param.type.clientDefaultValue) !==
+    undefined
+    ? `${param.optional ? "??" : ""} "${
+        param.clientDefaultValue ?? param.type.clientDefaultValue
+      }"`
+    : "";
+}
+
+/**
+ * Extracts the path parameters
+ */
+function getPathParameters(operation: Operation) {
+  if (!operation.parameters) {
+    return "";
+  }
+
+  let pathParams = "";
+  for (const param of operation.parameters) {
+    if (param.location === "path") {
+      if (!param.optional) {
+        pathParams = `${pathParams} ${param.clientName},`;
+        continue;
+      }
+
+      const defaultValue = getDefaultValue(param);
+
+      pathParams = `${pathParams}, options.${param.clientName}`;
+
+      if (defaultValue) {
+        pathParams = ` ?? "${defaultValue}"`;
+      }
+      pathParams = `${pathParams},`;
+    }
+  }
+
+  return pathParams;
+}
+
+/**
+ * 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(
+  properties: Property[],
+  propertyPath: string = "result.body"
+) {
+  const props: string[] = [];
+  for (const property of properties) {
+    // TODO: Do we need to also add headers in the result type?
+    if (property.type.type === "model") {
+      props.push(
+        `"${property.restApiName}": ${
+          !property.optional
+            ? ""
+            : `!${propertyPath}.${property.clientName} ? undefined :`
+        } {${getResponseMapping(
+          property.type.properties ?? [],
+          `${propertyPath}.${property.restApiName}${
+            property.optional ? "?" : ""
+          }`
+        )}}`
+      );
+    } else {
+      const dot = propertyPath.endsWith("?") ? "." : "";
+      const restValue = `${
+        propertyPath ? `${propertyPath}${dot}` : `${dot}`
+      }["${property.restApiName}"]`;
+      props.push(
+        `"${property.clientName}": ${deserializeResponseValue(
+          property.type,
+          restValue
+        )}`
+      );
+    }
+  }
+
+  return props;
+}
+
+/**
+ * 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 deserializeResponseValue(type: Type, restValue: string): string {
+  switch (type.type) {
+    case "datetime":
+      return `new Date(${restValue} ?? "")`;
+    case "list":
+      if (type.elementType?.type === "model") {
+        return `(${restValue} ?? []).map(p => ({${getResponseMapping(
+          type.elementType?.properties ?? [],
+          "p"
+        )}}))`;
+      } else if (
+        type.elementType?.properties?.some((p) => needsDeserialize(p.type))
+      ) {
+        return `(${restValue} ?? []).map(p => ${deserializeResponseValue(
+          type.elementType!,
+          "p"
+        )})`;
+      } else {
+        return restValue;
+      }
+
+    default:
+      return restValue;
+  }
+}
+
+function needsDeserialize(type?: Type) {
+  return type?.type === "datetime" || type?.type === "model";
+}

package/src/modular/helpers/parameterHelpers.ts

@@ -0,0 +1,17 @@
+import { Parameter } from "../modularCodeModel.js";
+
+const parameterTypeMap: Record<string, string> = {
+  Key: "AzureKeyCredential",
+  OAuth2: "TokenCredential"
+};
+
+export function getParameterType(param: Parameter): string {
+  switch (param.type.type) {
+    case "combined":
+      if (!param.type.types) throw new Error("Combined type without types");
+      return param.type.types.map((p) => parameterTypeMap[p.type]).join(" | ");
+
+    default:
+      return parameterTypeMap[param.type.type] ?? param.type.type;
+  }
+}

package/src/modular/helpers/typeHelpers.ts

@@ -0,0 +1,106 @@
+import { Type } from "../modularCodeModel.js";
+
+export interface TypeMetadata {
+  name: string;
+  originModule?: string;
+  isRelative?: boolean;
+  modifier?: "Array";
+}
+
+export function getType(type: Type): TypeMetadata {
+  switch (type.type) {
+    case "Key":
+      return {
+        name: "AzureKeyCredential",
+        originModule: "@azure/core-auth",
+        isRelative: false
+      };
+    case "boolean":
+      return { name: "boolean" };
+    case "constant": {
+      let typeName: string = type.value ?? "undefined";
+      if (type.valueType?.type === "string") {
+        typeName = type.value ? `"${type.value}"` : "undefined";
+      }
+      return { name: typeName };
+    }
+    case "datetime":
+      return { name: "Date" };
+    case "enum":
+      if (!type.name) {
+        throw new Error("Unable to process enum without name");
+      }
+      return { name: type.name, originModule: "models.js" };
+    case "float":
+    case "integer":
+      return { name: "number" };
+    case "byte-array":
+      return { name: "string" };
+    case "list":
+      if (!type.elementType) {
+        throw new Error("Unable to process Array with no elementType");
+      }
+      return {
+        name: getType(type.elementType).name,
+        modifier: "Array",
+        originModule:
+          type.elementType?.type === "model" ? "models.js" : undefined
+      };
+    case "model":
+      if (!type.name) {
+        throw new Error("Unable to process model without name");
+      }
+      return { name: type.name, originModule: "models.js" };
+    case "string":
+    case "duration":
+      return { name: "string" };
+    case "combined": {
+      if (!type.types) {
+        throw new Error("Unable to process combined without combinedTypes");
+      }
+      const name = type.types
+        .map((t) => {
+          const sdkType = getTypeName(getType(t));
+          return `${sdkType}`;
+        })
+        .join(" | ");
+      return { name };
+    }
+    case "dict":
+      if (!type.elementType) {
+        throw new Error("Unable to process dict without elemetType info");
+      }
+      return {
+        name: `Record<string, ${getTypeName(getType(type.elementType))}>`
+      };
+    default:
+      throw new Error(`Unsupported type ${type.type}`);
+  }
+}
+
+function getTypeName(typeMetadata: TypeMetadata) {
+  let typeName = typeMetadata.name;
+  if (typeMetadata.modifier === "Array") {
+    typeName = `${typeName}[]`;
+  }
+  return typeName;
+}
+
+/**
+ * Gets the Typescript representation of a TypeSpec type
+ */
+export function buildType(
+  clientName: string | undefined,
+  type: Type | undefined
+) {
+  if (!type) {
+    throw new Error("Type should be defined");
+  }
+
+  const typeMetadata = getType(type);
+  let typeName = typeMetadata.name;
+  if (typeMetadata.modifier === "Array") {
+    typeName = `${typeName}[]`;
+  }
+  return { name: clientName ?? "", type: typeName };
+}

package/src/modular/interfaces.ts

@@ -0,0 +1,10 @@
+import { OptionalKind, ParameterDeclarationStructure } from "ts-morph";
+import { Parameter } from "./modularCodeModel.js";
+
+export interface ClientDetails {
+  name: string;
+  params?: OptionalKind<ParameterDeclarationStructure>[];
+  description: string;
+  baseUrl?: string;
+  credentialsParam?: Parameter;
+}

package/src/modular/modularCodeModel.ts

@@ -0,0 +1,151 @@
+import { RLCOptions } from "@azure-tools/rlc-common";
+
+export interface ModularCodeModel {
+  options: RLCOptions;
+  namespace?: string;
+  subnamespaceToClients?: any;
+  clients: Client[];
+  types: Type[];
+}
+
+export interface Header {
+  type: Type;
+  restApiName: string;
+}
+
+export interface Property {
+  clientDefaultValue?: any;
+  clientName: string;
+  restApiName: string;
+  type: Type;
+  optional?: boolean;
+  description: string;
+  readonly?: boolean;
+}
+
+export interface BodyParameter {
+  contentTypes: string[];
+  type: Type;
+  restApiName: string;
+  location: "body";
+  optional: boolean;
+  description: string;
+  clientName: string;
+  inOverload: boolean;
+  defaultContentType: string;
+}
+
+export interface OperationGroup {
+  className: string;
+  propertyName: string;
+  operations: Operation[];
+}
+export interface Policy {
+  type: string;
+  key: string;
+}
+
+export interface XmlMetadata {}
+export interface EnumValue {
+  name: string;
+  value: string;
+  description: string;
+}
+export interface Type {
+  name?: string;
+  description?: string;
+  type:
+    | "string"
+    | "Key"
+    | "OAuth2"
+    | "constant"
+    | "model"
+    | "list"
+    | "byte-array"
+    | "datetime"
+    | "float"
+    | "duration"
+    | "enum"
+    | "integer"
+    | "float"
+    | "boolean"
+    | "dict"
+    | "combined";
+  policy?: Policy;
+  apiVersions?: any[];
+  clientDefaultValue?: any;
+  value?: string;
+  values?: EnumValue[];
+  isFixed?: boolean;
+  valueType?: Type;
+  elementType?: Type;
+  xmlMetadata?: XmlMetadata;
+  format?: string;
+  properties?: Property[];
+  types?: Type[];
+}
+
+export interface Client {
+  name: string;
+  description: string;
+  parameters: Parameter[];
+  operationGroups: OperationGroup[];
+  url: string;
+  apiVersions: any[];
+}
+
+export type ParameterLocation =
+  | "endpointPath"
+  | "header"
+  | "query"
+  | "path"
+  | "other";
+
+export interface Parameter {
+  optional: boolean;
+  description: string;
+  clientName: string;
+  inOverload: boolean;
+  restApiName: string;
+  location: ParameterLocation;
+  type: Type;
+  implementation: string;
+  skipUrlEncoding?: boolean;
+  clientDefaultValue?: string | null;
+  in_docstring?: boolean;
+  checkClientInput?: boolean;
+  delimiter?: any;
+  explode?: boolean;
+  groupedBy?: any;
+  inDocstring?: boolean;
+  inOverriden?: boolean;
+  isApiVersion?: boolean;
+}
+
+export interface Response {
+  headers: Header[];
+  statusCodes: (number | "default")[];
+  discriminator: string;
+  type: Type;
+  addedOn?: string;
+}
+
+export interface Operation {
+  name: string;
+  description: string;
+  summary: string;
+  url: string;
+  method: string;
+  parameters: Parameter[];
+  bodyParameter?: BodyParameter;
+  responses: Response[];
+  exceptions: Response[];
+  groupName: string;
+  discriminator: string;
+  isOverload: boolean;
+  overloads: any[];
+  apiVersions: any[];
+  itemName?: string;
+  continuationTokenName?: string;
+  addedOn?: string;
+}