@azure-tools/rlc-common 0.11.0

package/src/buildIndexFile.ts

@@ -0,0 +1,202 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project, SourceFile } from "ts-morph";
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import {
+  hasInputModels,
+  hasMultiCollection,
+  hasOutputModels,
+  hasPagingOperations,
+  hasPipeCollection,
+  hasPollingOperations,
+  hasSsvCollection,
+  hasTsvCollection,
+  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");
+  }
+
+  if (
+    hasMultiCollection(model) ||
+    hasSsvCollection(model) ||
+    hasPipeCollection(model) ||
+    hasTsvCollection(model)
+  ) {
+    file.addImportDeclaration({
+      namespaceImport: "SerializeHelper",
+      moduleSpecifier: "./serializeHelper"
+    });
+    exports.push("SerializeHelper");
+  }
+
+  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"
+      }
+    ]);
+  }
+
+  if (
+    hasMultiCollection(model) ||
+    hasSsvCollection(model) ||
+    hasPipeCollection(model) ||
+    hasTsvCollection(model)
+  ) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "./serializeHelper"
+      }
+    ]);
+  }
+
+  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[]> = {};
+  const allResponseTypes: Set<string> = new Set();
+  const allErrorTypes: Set<string> = new Set();
+  const 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 = getParametrizedPathSuccess(method, url.pathname);"
+          : `return true;`,
+        `  }
+          return !pathDetails.includes(response.status);
+        `
+      ]
+    });
+    if (hasTemplate) {
+      isErrorHelper.addFunction({
+        isExported: false,
+        name: "getParametrizedPathSuccess",
+        parameters: [
+          {
+            name: "method",
+            type: "string"
+          },
+          {
+            name: "path",
+            type: "string"
+          }
+        ],
+        returnType: `string[]`,
+        statements: [
+          `
+          const pathParts = path.split("/");
+            
+          // Traverse list to match the longest candidate
+          // matchedLen: the length of candidate path
+          // matchedValue: the matched status code array
+          let matchedLen = -1,
+            matchedValue: string[] = [];
+          
+          // 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("/");
+        
+            // track if we have found a match to return the values found.
+            let found = true;
+            for (
+              let i = candidateParts.length - 1, j = pathParts.length - 1;
+              i >= 1 && j >= 1;
+              i--, j--
+            ) {
+              if (
+                candidateParts[i]?.startsWith("{") &&
+                candidateParts[i]?.indexOf("}") !== -1
+              ) {
+                const start = candidateParts[i]!.indexOf("}") + 1,
+                  end = candidateParts[i]?.length;
+                // If the current part of the candidate is a "template" part
+                // Try to use the suffix of pattern to match the path
+                // {guid} ==> $
+                // {guid}:export ==> :export$
+                const isMatched = new RegExp(
+                  \`\${candidateParts[i]?.slice(start, end)}\`
+                ).test(pathParts[j] || '');
+        
+                if (!isMatched) {
+                  found = false;
+                  break;
+                }
+                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[j]) {
+                found = false;
+                break;
+              }
+            }
+        
+            // We finished evaluating the current candidate parts
+            // Update the matched value if and only if we found the longer pattern
+            if (found && candidatePath.length > matchedLen) {
+              matchedLen = candidatePath.length;
+              matchedValue = value;
+            }
+          }
+        
+          return matchedValue;
+        `
+        ]
+      });
+
+      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) {
+  const 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);
+    }`;
+}