@azure-tools/rlc-common 0.11.0

package/src/buildClient.ts

@@ -0,0 +1,353 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  StatementStructures,
+  StructureKind,
+  VariableDeclarationKind,
+  VariableStatementStructure,
+  WriterFunction
+} from "ts-morph";
+import * as path from "path";
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import { isConstantSchema } from "./helpers/schemaHelpers.js";
+import { buildMethodShortcutImplementation } from "./buildMethodShortcuts.js";
+import { RLCModel, Schema, File, PathParameter } from "./interfaces.js";
+
+function getClientOptionsInterface(
+  clientName: string,
+  optionalUrlParameters?: PathParameter[]
+): OptionalKind<InterfaceDeclarationStructure> | undefined {
+  if (!optionalUrlParameters || optionalUrlParameters.length === 0) {
+    return undefined;
+  }
+
+  const properties = optionalUrlParameters.map((param) => {
+    return {
+      name: param.name,
+      type: param.type,
+      hasQuestionToken: true
+    };
+  });
+
+  return {
+    name: `${clientName}Options`,
+    extends: ["ClientOptions"],
+    isExported: true,
+    properties
+  };
+}
+
+export function buildClient(model: RLCModel): File | undefined {
+  const name = normalizeName(model.libraryName, NameType.File);
+  const { srcPath } = model;
+  const project = new Project();
+  const filePath = path.join(srcPath, `${name}.ts`);
+  const clientFile = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+
+  // Get all paths
+  const clientName = model.libraryName;
+  const clientInterfaceName = clientName.endsWith("Client")
+    ? `${clientName}`
+    : `${clientName}Client`;
+
+  normalizeUrlInfo(model);
+  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 optionalUrlParameters = model?.urlInfo?.urlParameters?.filter(
+    // Do not include parameters with constant values in the signature, these should go in the options bag
+    (p) => Boolean(p.value)
+  );
+
+  const clientOptionsInterface = getClientOptionsInterface(
+    clientInterfaceName,
+    optionalUrlParameters
+  );
+
+  if (clientOptionsInterface) {
+    clientFile.addInterface(clientOptionsInterface);
+  }
+
+  if (!model.options) {
+    return undefined;
+  }
+  const { multiClient, batch } = model.options;
+  const { addCredentials, credentialScopes, credentialKeyHeaderName } =
+    model.options;
+  const credentialTypes =
+    credentialScopes && credentialScopes.length > 0 ? ["TokenCredential"] : [];
+
+  if (credentialKeyHeaderName) {
+    credentialTypes.push("KeyCredential");
+  }
+
+  const commonClientParams = [
+    ...(urlParameters ?? []),
+    ...(addCredentials === false ||
+    !isSecurityInfoDefined(credentialScopes, credentialKeyHeaderName)
+      ? []
+      : [
+          {
+            name: "credentials",
+            type: credentialTypes.join(" | "),
+            description: `uniquely identify client credential`
+          }
+        ])
+  ];
+
+  const allClientParams = [
+    ...commonClientParams,
+    {
+      name: "options",
+      type: `${clientOptionsInterface?.name ?? "ClientOptions"} = {}`,
+      description: "the parameter for all optional parameters"
+    }
+  ];
+  const functionStatement = {
+    isExported: true,
+    name: `createClient`,
+    parameters: allClientParams,
+    docs: [
+      {
+        description:
+          `Initialize a new instance of \`${clientInterfaceName}\` \n` +
+          allClientParams
+            .map((param) => {
+              return `@param ${param.name} type: ${param.type
+                .split("=")[0]
+                .split(" ")
+                .join("")}, ${
+                param.description ?? "The parameter " + param.name
+              }`;
+            })
+            .join("\n")
+      }
+    ],
+    returnType: clientInterfaceName,
+    isDefaultExport: false,
+    statements: getClientFactoryBody(model, clientInterfaceName)
+  };
+
+  if (!multiClient || !batch || batch.length === 1) {
+    functionStatement.isDefaultExport = true;
+  }
+  clientFile.addFunction(functionStatement);
+
+  clientFile.addImportDeclarations([
+    {
+      namedImports: ["getClient", "ClientOptions"],
+      moduleSpecifier: "@azure-rest/core-client"
+    }
+  ]);
+
+  if (
+    addCredentials &&
+    isSecurityInfoDefined(credentialScopes, credentialKeyHeaderName)
+  ) {
+    clientFile.addImportDeclarations([
+      {
+        namedImports: credentialTypes,
+        moduleSpecifier: "@azure/core-auth"
+      }
+    ]);
+  }
+  clientFile.addImportDeclarations([
+    {
+      namedImports: [`${clientInterfaceName}`],
+      moduleSpecifier: "./clientDefinitions"
+    }
+  ]);
+  return { path: filePath, content: clientFile.getFullText() };
+}
+
+function isSecurityInfoDefined(
+  credentialScopes?: string[],
+  credentialKeyHeaderName?: string
+) {
+  return (
+    (credentialScopes && credentialScopes.length > 0) || credentialKeyHeaderName
+  );
+}
+
+function getClientFactoryBody(
+  model: RLCModel,
+  clientTypeName: string
+): string | WriterFunction | (string | WriterFunction | StatementStructures)[] {
+  if (!model.options || !model.options.packageDetails || !model.urlInfo) {
+    return "";
+  }
+  const { includeShortcuts, packageDetails } = model.options;
+  let clientPackageName = packageDetails.nameWithoutScope ?? "";
+  const packageVersion = packageDetails.version;
+  const { endpoint, urlParameters } = model.urlInfo;
+
+  const optionalUrlParameters: string[] = [];
+
+  for (const param of urlParameters ?? []) {
+    if (param.value) {
+      const value =
+        typeof param.value === "string" ? `"${param.value}"` : param.value;
+      optionalUrlParameters.push(
+        `const ${param.name} = options.${param.name} ?? ${value}`
+      );
+    }
+  }
+
+  let baseUrl: string;
+  if (urlParameters && endpoint) {
+    let parsedEndpoint = endpoint;
+    urlParameters.forEach((urlParameter) => {
+      parsedEndpoint = parsedEndpoint.replace(
+        `{${urlParameter.name}}`,
+        `\${${urlParameter.name}}`
+      );
+    });
+
+    baseUrl = `options.baseUrl ?? \`${parsedEndpoint}\``;
+  } else {
+    baseUrl = `options.baseUrl ?? "${endpoint}"`;
+  }
+
+  const apiVersion = getApiVersionInQueryParam(model);
+  let apiVersionStatement: string = "";
+  if (apiVersion) {
+    apiVersionStatement = `options.apiVersion = options.apiVersion ?? "${apiVersion}"`;
+  }
+
+  if (!clientPackageName.endsWith("-rest")) {
+    clientPackageName = clientPackageName + "-rest";
+  }
+  const userAgentInfoStatement =
+    "const userAgentInfo = `azsdk-js-" +
+    clientPackageName +
+    "/" +
+    packageVersion +
+    "`;";
+  const userAgentPrefix =
+    "options.userAgentOptions && options.userAgentOptions.userAgentPrefix ? `${options.userAgentOptions.userAgentPrefix} ${userAgentInfo}`: `${userAgentInfo}`;";
+  const userAgentStatement: VariableStatementStructure = {
+    kind: StructureKind.VariableStatement,
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [{ name: "userAgentPrefix", initializer: userAgentPrefix }]
+  };
+
+  const userAgentOptionsStatement = `options = {
+      ...options,
+      userAgentOptions: {
+        userAgentPrefix
+      }
+    }`;
+
+  const baseUrlStatement: VariableStatementStructure = {
+    kind: StructureKind.VariableStatement,
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [{ name: "baseUrl", initializer: baseUrl }]
+  };
+
+  const { credentialScopes, credentialKeyHeaderName } = model.options;
+
+  const scopesString =
+    credentialScopes && credentialScopes.length
+      ? credentialScopes.map((cs) => `"${cs}"`).join(", ")
+      : "";
+  const scopes = scopesString ? `scopes: [${scopesString}],` : "";
+
+  const apiKeyHeaderName = credentialKeyHeaderName
+    ? `apiKeyHeaderName: "${credentialKeyHeaderName}",`
+    : "";
+
+  const credentials =
+    scopes || apiKeyHeaderName
+      ? `options = {
+        ...options,
+        credentials: {
+          ${scopes}
+          ${apiKeyHeaderName}
+        },
+      }`
+      : "";
+
+  const getClient = `const client = getClient(
+        baseUrl, ${credentials ? "credentials," : ""} options
+      ) as ${clientTypeName};
+      `;
+
+  let returnStatement = `return client;`;
+
+  if (includeShortcuts) {
+    const shortcutImplementations = buildMethodShortcutImplementation(
+      model.paths
+    );
+    const shortcutBody = Object.keys(shortcutImplementations).map((key) => {
+      // If the operation group has an empty name, it means its operations are client
+      // level operations so we need to spread the definitions. Otherwise they are
+      // within an operation group so we add them as key: value
+      return `${
+        key && key !== "client" ? `"${key}":` : "..."
+      } {${shortcutImplementations[key].join()}}`;
+    });
+    returnStatement = `return { ...client, ${shortcutBody.join()} };`;
+  }
+
+  return [
+    ...optionalUrlParameters,
+    baseUrlStatement,
+    apiVersionStatement,
+    credentials,
+    userAgentInfoStatement,
+    userAgentStatement,
+    userAgentOptionsStatement,
+    getClient,
+    returnStatement
+  ];
+}
+
+function getApiVersionInQueryParam(model: RLCModel): string | undefined {
+  if (!model.apiVersionInQueryParam) {
+    return undefined;
+  }
+
+  if (
+    model.apiVersionInQueryParam &&
+    isConstantSchema(model.apiVersionInQueryParam as Schema)
+  ) {
+    return model.apiVersionInQueryParam.default;
+  }
+
+  return undefined;
+}
+
+function normalizeUrlInfo(model: RLCModel) {
+  if (
+    !model ||
+    !model.urlInfo ||
+    !model.urlInfo.endpoint ||
+    !model.urlInfo.urlParameters ||
+    model.urlInfo.urlParameters.length === 0
+  ) {
+    return;
+  }
+
+  let parsedEndpoint = model.urlInfo.endpoint;
+  const urlParameters = model.urlInfo.urlParameters;
+  urlParameters.forEach((urlParameter) => {
+    const name = urlParameter.name;
+    const normalizedName = normalizeName(name, NameType.Parameter);
+    if (name !== normalizedName) {
+      urlParameter.name = normalizedName;
+      parsedEndpoint = parsedEndpoint.replace(
+        `{${name}}`,
+        `{${normalizedName}}`
+      );
+    }
+  });
+  model.urlInfo.endpoint = parsedEndpoint;
+}

package/src/buildClientDefinitions.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  CallSignatureDeclarationStructure,
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  SourceFile,
+  StructureKind,
+  Writers
+} from "ts-morph";
+import * as path from "path";
+
+import {
+  buildMethodDefinitions,
+  getPathParamDefinitions
+} from "./helpers/operationHelpers.js";
+import { PathMetadata, Paths, RLCModel } from "./interfaces.js";
+import { generateMethodShortcuts } from "./helpers/shortcutMethods.js";
+import { REST_CLIENT_RESERVED } from "./buildMethodShortcuts.js";
+import {
+  CasingConvention,
+  NameType,
+  normalizeName
+} from "./helpers/nameUtils.js";
+import { pascalCase } from "./helpers/nameUtils.js";
+
+export function buildClientDefinitions(model: RLCModel) {
+  const options = {
+    importedParameters: new Set<string>(),
+    importedResponses: new Set<string>(),
+    clientImports: new Set<string>()
+  };
+  const project = new Project();
+  const srcPath = model.srcPath;
+  const filePath = path.join(srcPath, `clientDefinitions.ts`);
+  const clientDefinitionsFile = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+
+  // Get all paths
+  const pathDictionary = model.paths;
+  let shortcuts: OptionalKind<InterfaceDeclarationStructure>[] = [];
+  // There may be operations without an operation group, those shortcut
+  // methods need to be handled differently.
+  let shortcutsInOperationGroup: { name: string; type: string }[] = [];
+
+  if (model.options?.includeShortcuts) {
+    shortcuts = generateMethodShortcuts(model.paths);
+    clientDefinitionsFile.addInterfaces(shortcuts);
+    shortcutsInOperationGroup = shortcuts
+      .filter((s) => s.name !== "ClientOperations")
+      .map((s) => getShortcutName(s.name));
+  }
+
+  clientDefinitionsFile.addInterface({
+    name: "Routes",
+    isExported: true,
+    callSignatures: getPathFirstRoutesInterfaceDefinition(
+      pathDictionary,
+      clientDefinitionsFile,
+      options
+    )
+  });
+
+  const clientName = model.libraryName;
+
+  const clientInterfaceName = clientName.endsWith("Client")
+    ? `${clientName}`
+    : `${clientName}Client`;
+
+  clientDefinitionsFile.addTypeAlias({
+    isExported: true,
+    name: clientInterfaceName,
+    type: Writers.intersectionType(
+      "Client",
+      Writers.objectType({
+        properties: [
+          { name: "path", type: "Routes" },
+          ...shortcutsInOperationGroup
+        ]
+      }),
+      // If the length of shortcuts in operation group and all shortcutsInOperationGroup
+      // is the same, then we don't have any operations at the client level
+      // Otherwise we need to make the client interface name an union with the
+      // definition of all client level shortcut methods
+      ...(shortcutsInOperationGroup.length !== shortcuts.length
+        ? [`ClientOperations`]
+        : [])
+    )
+  });
+
+  if (options.importedParameters.size) {
+    clientDefinitionsFile.addImportDeclaration({
+      namedImports: [...options.importedParameters],
+      moduleSpecifier: "./parameters"
+    });
+  }
+
+  if (options.importedResponses.size) {
+    clientDefinitionsFile.addImportDeclaration({
+      namedImports: [...options.importedResponses],
+      moduleSpecifier: "./responses"
+    });
+  }
+
+  options.clientImports.add("Client");
+  options.clientImports.add("StreamableMethod");
+  clientDefinitionsFile.addImportDeclarations([
+    {
+      namedImports: [...options.clientImports],
+      moduleSpecifier: "@azure-rest/core-client"
+    }
+  ]);
+
+  return { path: filePath, content: clientDefinitionsFile.getFullText() };
+}
+
+function getPathFirstRoutesInterfaceDefinition(
+  paths: Paths,
+  sourcefile: SourceFile,
+  options: {
+    importedParameters: Set<string>;
+    importedResponses: Set<string>;
+    clientImports: Set<string>;
+  }
+): CallSignatureDeclarationStructure[] {
+  const operationGroupCount = getOperationGroupCount(paths);
+
+  const signatures: CallSignatureDeclarationStructure[] = [];
+  for (const key of Object.keys(paths)) {
+    for (const verb of Object.keys(paths[key].methods)) {
+      for (const method of paths[key].methods[verb]) {
+        options.importedParameters.add(method.optionsName);
+        method.returnType
+          .split(" | ")
+          .forEach((item) => options.importedResponses.add(item));
+      }
+    }
+    generatePathFirstRouteMethodsDefinition(
+      paths[key],
+      operationGroupCount,
+      sourcefile
+    );
+    const pathParams = paths[key].pathParameters;
+    signatures.push({
+      docs: [
+        `Resource for '${key
+          .replace(/}/g, "\\}")
+          .replace(
+            /{/g,
+            "\\{"
+          )}' has methods for the following verbs: ${Object.keys(
+          paths[key].methods
+        ).join(", ")}`
+      ],
+      parameters: [
+        { name: "path", type: `"${key}"` },
+        ...getPathParamDefinitions(pathParams)
+      ],
+      returnType: getOperationReturnTypeName(
+        paths[key],
+        getOperationGroupCount(paths)
+      ),
+      kind: StructureKind.CallSignature
+    });
+  }
+  return signatures;
+}
+
+function getOperationGroupCount(paths: Paths) {
+  const operationGroups = Object.keys(paths)
+    .map((p) => paths[p].operationGroupName)
+    .filter((p) => p && p !== "Client");
+  const uniqueNames = new Set(operationGroups);
+
+  return uniqueNames.size;
+}
+
+function getOperationReturnTypeName(
+  { operationGroupName, name }: PathMetadata,
+  operationGroupCount: number
+) {
+  if (
+    operationGroupCount > 1 &&
+    operationGroupName &&
+    operationGroupName !== "Client"
+  ) {
+    return `${pascalCase(operationGroupName)}${pascalCase(name)}`;
+  }
+
+  return pascalCase(name);
+}
+
+function generatePathFirstRouteMethodsDefinition(
+  path: PathMetadata,
+  operationGroupCount: number,
+  file: SourceFile
+): void {
+  const methodDefinitions = buildMethodDefinitions(path.methods);
+  const interfaceDef = {
+    methods: methodDefinitions,
+    name: getOperationReturnTypeName(path, operationGroupCount),
+    isExported: true
+  };
+  file.addInterface(interfaceDef);
+}
+
+function getShortcutName(interfaceName: string) {
+  const endIndex = shouldKeepSuffix(interfaceName)
+    ? undefined
+    : interfaceName.length - "Operations".length;
+  const clientProperty = normalizeName(
+    interfaceName.substring(0, endIndex),
+    NameType.OperationGroup,
+    true,
+    REST_CLIENT_RESERVED,
+    CasingConvention.Camel
+  );
+
+  return {
+    name: clientProperty,
+    type: interfaceName
+  };
+}
+
+function shouldKeepSuffix(name: string) {
+  const reservedNames = [
+    "pipelineOperations",
+    "pathOperations",
+    "pathUncheckedOperations"
+  ];
+  return reservedNames.some((r) => r.toLowerCase() === name.toLowerCase());
+}