@azure-tools/rlc-common 1.0.0-beta.1

package/src/buildClientDefinitions.ts

@@ -0,0 +1,231 @@
+// 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());
+}

package/src/buildIndexFile.ts

@@ -0,0 +1,172 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project, SourceFile } from "ts-morph";
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import {
+  hasInputModels,
+  hasOutputModels,
+  hasPagingOperations,
+  hasPollingOperations,
+  hasUnexpectedHelper
+} from "./helpers/operationHelpers.js";
+import { RLCModel } from "./interfaces.js";
+import * as path from "path";
+
+export function buildIndexFile(model: RLCModel) {
+  const multiClient = Boolean(model.options?.multiClient),
+    batch = model.options?.batch;
+  const project = new Project();
+  const { srcPath } = model;
+  const filePath = path.join(srcPath, `index.ts`);
+  const indexFile = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+
+  if (!multiClient || !batch || batch?.length === 1) {
+    // if we are generate single client package for RLC
+    generateRLCIndex(indexFile, model);
+  } else {
+    generateRLCIndexForMultiClient(indexFile, model);
+  }
+  return {
+    path: filePath,
+    content: indexFile.getFullText()
+  };
+}
+
+// to generate a index.ts for each single module inside the multi client RLC package
+function generateRLCIndexForMultiClient(file: SourceFile, model: RLCModel) {
+  const clientName = model.libraryName;
+  const createClientFuncName = `createClient`;
+  const moduleName = normalizeName(clientName, NameType.File);
+
+  file.addImportDeclaration({
+    namespaceImport: "Parameters",
+    moduleSpecifier: "./parameters"
+  });
+
+  file.addImportDeclaration({
+    namespaceImport: "Responses",
+    moduleSpecifier: "./responses"
+  });
+
+  file.addImportDeclaration({
+    namespaceImport: "Client",
+    moduleSpecifier: "./clientDefinitions"
+  });
+
+  const exports = ["Parameters", "Responses", "Client"];
+  if (hasInputModels(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "Models",
+      moduleSpecifier: "./models"
+    });
+    exports.push("Models");
+  }
+
+  if (hasOutputModels(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "OutputModels",
+      moduleSpecifier: "./outputModels"
+    });
+    exports.push("OutputModels");
+  }
+
+  if (hasPagingOperations(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "PaginateHelper",
+      moduleSpecifier: "./paginateHelper"
+    });
+    exports.push("PaginateHelper");
+  }
+
+  if (hasPollingOperations(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "PollingHelper",
+      moduleSpecifier: "./pollingHelper"
+    });
+    exports.push("PollingHelper");
+  }
+
+  file.addExportDeclarations([
+    {
+      moduleSpecifier: `./${moduleName}`,
+      namedExports: [`${createClientFuncName}`]
+    },
+    {
+      namedExports: [...exports]
+    }
+  ]);
+}
+
+function generateRLCIndex(file: SourceFile, model: RLCModel) {
+  const clientName = model.libraryName;
+  const createClientFuncName = `${clientName}`;
+  const moduleName = normalizeName(clientName, NameType.File);
+
+  file.addImportDeclaration({
+    moduleSpecifier: `./${moduleName}`,
+    defaultImport: createClientFuncName
+  });
+
+  file.addExportDeclarations([
+    {
+      moduleSpecifier: `./${moduleName}`
+    },
+    {
+      moduleSpecifier: "./parameters"
+    },
+    {
+      moduleSpecifier: "./responses"
+    },
+    {
+      moduleSpecifier: "./clientDefinitions"
+    }
+  ]);
+
+  if (hasUnexpectedHelper(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "./isUnexpected"
+      }
+    ]);
+  }
+
+  if (hasInputModels(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "./models"
+      }
+    ]);
+  }
+
+  if (hasOutputModels(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "./outputModels"
+      }
+    ]);
+  }
+
+  if (hasPagingOperations(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "./paginateHelper"
+      }
+    ]);
+  }
+
+  if (hasPollingOperations(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "./pollingHelper"
+      }
+    ]);
+  }
+
+  file.addExportAssignment({
+    expression: createClientFuncName,
+    isExportEquals: false
+  });
+}

package/src/buildIsUnexpectedHelper.ts

@@ -0,0 +1,240 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Paths, RLCModel } from "./interfaces.js";
+import * as path from "path";
+import {
+  FunctionDeclarationOverloadStructure,
+  OptionalKind,
+  Project,
+  VariableDeclarationKind
+} from "ts-morph";
+import { hasUnexpectedHelper } from "./helpers/operationHelpers.js";
+export function buildIsUnexpectedHelper(model: RLCModel) {
+  if (!hasUnexpectedHelper(model)) {
+    return;
+  }
+  const project = new Project();
+  const srcPath = model.srcPath;
+  const filePath = path.join(srcPath, `isUnexpected.ts`);
+  const isErrorHelper = project.createSourceFile(filePath, undefined, {
+    overwrite: true
+  });
+
+  let map: Record<string, string[]> = {};
+  let allResponseTypes: Set<string> = new Set();
+  let allErrorTypes: Set<string> = new Set();
+  let overloads: OptionalKind<FunctionDeclarationOverloadStructure>[] = [];
+  const pathDictionary = model.paths;
+
+  for (const [path, details] of Object.entries(pathDictionary)) {
+    for (const [methodName, methodDetails] of Object.entries(details.methods)) {
+      const originalMethod = methodName.toUpperCase();
+      const operation = `${originalMethod} ${path}`;
+      const success = methodDetails[0].successStatus;
+      map = { ...map, ...{ [operation]: success } };
+
+      // LROs may call the same path but with GET
+      // to get the operation status.
+      if (
+        methodDetails[0].annotations?.isLongRunning &&
+        originalMethod !== "GET"
+      ) {
+        const operation = `GET ${path}`;
+        const success =
+          (pathDictionary[path].methods["get"] &&
+            pathDictionary[path].methods["get"][0]?.successStatus) ??
+          methodDetails[0].successStatus;
+        map = { ...map, ...{ [operation]: success } };
+      }
+
+      const successTypes = methodDetails[0].responseTypes.success;
+      const errorTypes = methodDetails[0].responseTypes.error;
+
+      if (!successTypes.length || !errorTypes.length || !errorTypes[0]) {
+        continue;
+      }
+
+      successTypes.forEach((t) => allResponseTypes.add(t));
+      errorTypes.forEach((t) => {
+        allResponseTypes.add(t);
+        allErrorTypes.add(t);
+      });
+
+      overloads.push({
+        isExported: true,
+        parameters: [
+          {
+            name: "response",
+            type: [...successTypes, ...errorTypes].join(" | ")
+          }
+        ],
+        returnType: `response is ${errorTypes[0]}`
+      });
+    }
+  }
+  isErrorHelper.addImportDeclaration({
+    namedImports: [...allResponseTypes],
+    moduleSpecifier: "./responses"
+  });
+
+  isErrorHelper.addVariableStatement({
+    declarations: [
+      {
+        name: "responseMap",
+        initializer: JSON.stringify(map),
+        type: "Record<string, string[]>"
+      }
+    ],
+    declarationKind: VariableDeclarationKind.Const
+  });
+
+  if (allErrorTypes.size) {
+    const hasTemplate = hasParametrizedPath(pathDictionary);
+    isErrorHelper.addFunction({
+      overloads,
+      isExported: true,
+      name: "isUnexpected",
+      parameters: [
+        {
+          name: "response",
+          type: [...allResponseTypes].join(" | ")
+        }
+      ],
+      returnType: `response is ${[...allErrorTypes].join(" | ")}`,
+      statements: [
+        `
+          const lroOriginal = response.headers["x-ms-original-url"];
+          const url = new URL(lroOriginal ?? response.request.url);
+          const method = response.request.method;
+          ${
+            hasTemplate ? "let" : "const"
+          } pathDetails = responseMap[\`\${method} \${url.pathname}\`];
+          if (!pathDetails) {`,
+        hasTemplate
+          ? "pathDetails = geParametrizedPathSuccess(method, url.pathname);"
+          : `return true;`,
+        `  }
+          return !pathDetails.includes(response.status);
+        `
+      ]
+    });
+    if (hasTemplate) {
+      isErrorHelper.addFunction({
+        isExported: false,
+        name: "geParametrizedPathSuccess",
+        parameters: [
+          {
+            name: "method",
+            type: "string"
+          },
+          {
+            name: "path",
+            type: "string"
+          }
+        ],
+        returnType: `string[]`,
+        statements: [
+          `
+        const pathParts = path.split("/");
+
+        // Iterate the responseMap to find a match
+        for (const [key, value] of Object.entries(responseMap)) {
+          // Extracting the path from the map key which is in format
+          // GET /path/foo
+          if (!key.startsWith(method)) {
+            continue;
+          }
+          const candidatePath = getPathFromMapKey(key);
+          // Get each part of the url path
+          const candidateParts = candidatePath.split("/");
+      
+          // If the candidate and actual paths don't match in size
+          // we move on to the next candidate path
+          if (
+            candidateParts.length === pathParts.length &&
+            hasParametrizedPath(key)
+          ) {
+            // track if we have found a match to return the values found.
+            let found = true;
+            for (let i = 0; i < candidateParts.length; i++) {
+              if (
+                candidateParts[i]?.startsWith("{") &&
+                candidateParts[i]?.endsWith("}")
+              ) {
+                // If the current part of the candidate is a "template" part
+                // it is a match with the actual path part on hand
+                // skip as the parameterized part can match anything
+                continue;
+              }
+      
+              // If the candidate part is not a template and
+              // the parts don't match mark the candidate as not found
+              // to move on with the next candidate path.
+              if (candidateParts[i] !== pathParts[i]) {
+                found = false;
+                break;
+              }
+            }
+      
+            // We finished evaluating the current candidate parts
+            // if all parts matched we return the success values form
+            // the path mapping.
+            if (found) {
+              return value;
+            }
+          }
+        }
+      
+        // No match was found, return an empty array.
+        return [];
+        `
+        ]
+      });
+
+      isErrorHelper.addFunction({
+        isExported: false,
+        name: "hasParametrizedPath",
+        parameters: [
+          {
+            name: "path",
+            type: "string"
+          }
+        ],
+        returnType: `boolean`,
+        statements: [`return path.includes("/{");`]
+      });
+
+      isErrorHelper.addFunction({
+        isExported: false,
+        name: "getPathFromMapKey",
+        parameters: [
+          {
+            name: "mapKey",
+            type: "string"
+          }
+        ],
+        returnType: `string`,
+        statements: [
+          `const pathStart = mapKey.indexOf("/");
+         return mapKey.slice(pathStart);`
+        ]
+      });
+    }
+  }
+
+  return {
+    path: filePath,
+    content: isErrorHelper.getFullText()
+  };
+}
+
+function hasParametrizedPath(pathDictionary: Paths): boolean {
+  for (const [path] of Object.entries(pathDictionary)) {
+    if (path.includes("/{") && path.includes("}")) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/buildMethodShortcuts.ts

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  CasingConvention,
+  NameType,
+  normalizeName,
+  ReservedName
+} from "./helpers/nameUtils.js";
+import { Paths, PathParameter, PathMetadata } from "./interfaces.js";
+
+export const REST_CLIENT_RESERVED: ReservedName[] = [
+  { name: "path", reservedFor: [NameType.Property, NameType.OperationGroup] },
+  {
+    name: "pathUnchecked",
+    reservedFor: [NameType.Property, NameType.OperationGroup]
+  },
+  {
+    name: "pipeline",
+    reservedFor: [NameType.Property, NameType.OperationGroup]
+  }
+];
+
+export function buildMethodShortcutImplementation(paths: Paths) {
+  let keys: Record<string, string[]> = {};
+  for (const path of Object.keys(paths)) {
+    const groupName = normalizeName(
+      paths[path].operationGroupName,
+      NameType.OperationGroup,
+      true,
+      REST_CLIENT_RESERVED,
+      CasingConvention.Camel
+    );
+
+    if (keys[groupName]) {
+      keys[groupName].push(...buildOperationDeclarations(path, paths[path]));
+    } else {
+      keys[groupName] = buildOperationDeclarations(path, paths[path]);
+    }
+  }
+  return keys;
+}
+
+function buildOperationDeclarations(path: string, pathMetadata: PathMetadata) {
+  let ops: string[] = [];
+  for (const method of Object.keys(pathMetadata.methods)) {
+    for (const op of pathMetadata.methods[method]) {
+      const pathParams = pathMetadata?.pathParameters;
+      const name = normalizeName(op.operationName, NameType.Property);
+      const methodDefinitions = generateOperationDeclaration(
+        path,
+        name,
+        method,
+        pathParams
+      );
+      ops = [...ops, methodDefinitions];
+    }
+  }
+
+  return ops;
+}
+
+function generateOperationDeclaration(
+  path: string,
+  operationName: string,
+  method: string,
+  pathParams: PathParameter[] = []
+): string {
+  const pathParamNames = `${
+    pathParams.length > 0 ? `${pathParams.map((p) => p.name)},` : ""
+  }`;
+  return `"${operationName}": (${pathParamNames} options) => {
+      return client.path("${path}", ${pathParamNames}).${method}(options);
+    }`;
+}