@azure-tools/typespec-ts 0.53.3 → 0.54.0

package/src/rlc-common/buildClientDefinitions.ts

@@ -0,0 +1,278 @@
+// 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,
+  getGeneratedWrapperTypes,
+  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";
+import {
+  getClientName,
+  getImportModuleName
+} from "./helpers/nameConstructors.js";
+import { getImportSpecifier } from "./helpers/importsUtil.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 clientInterfaceName = getClientName(model);
+  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({
+      isTypeOnly: true,
+      namedImports: [...options.importedParameters],
+      moduleSpecifier: getImportModuleName(
+        { cjsName: "./parameters", esModulesName: "./parameters.js" },
+        model
+      )
+    });
+  }
+
+  if (options.importedResponses.size) {
+    clientDefinitionsFile.addImportDeclaration({
+      isTypeOnly: true,
+      namedImports: [...options.importedResponses],
+      moduleSpecifier: getImportModuleName(
+        { cjsName: "./responses", esModulesName: "./responses.js" },
+        model
+      )
+    });
+  }
+
+  if (
+    (model.importInfo.internalImports.rlcClientDefinition.importsSet?.size ??
+      0) > 0
+  ) {
+    clientDefinitionsFile.addImportDeclaration({
+      isTypeOnly: true,
+      namedImports: Array.from(
+        model.importInfo.internalImports.rlcClientDefinition.importsSet!
+      ),
+      moduleSpecifier: getImportModuleName(
+        { cjsName: "./models", esModulesName: "./models.js" },
+        model
+      )
+    });
+  }
+
+  options.clientImports.add("Client");
+  options.clientImports.add("StreamableMethod");
+  clientDefinitionsFile.addImportDeclarations([
+    {
+      isTypeOnly: true,
+      namedImports: [...options.clientImports],
+      moduleSpecifier: getImportSpecifier(
+        "restClient",
+        model.importInfo.runtimeImports
+      )
+    }
+  ]);
+
+  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)) {
+    const pathMetadata = paths[key];
+    if (!pathMetadata) {
+      continue;
+    }
+    for (const verb of Object.keys(pathMetadata.methods)) {
+      const methods = pathMetadata.methods[verb];
+      if (!methods) {
+        continue;
+      }
+      for (const method of methods) {
+        options.importedParameters.add(method.optionsName);
+        method.returnType
+          .split(" | ")
+          .forEach((item) => options.importedResponses.add(item));
+      }
+    }
+    generatePathFirstRouteMethodsDefinition(
+      pathMetadata,
+      operationGroupCount,
+      sourcefile
+    );
+    const pathParams = pathMetadata.pathParameters;
+    getGeneratedWrapperTypes(pathParams).forEach((p) =>
+      options.importedParameters.add(p.name ?? p.type)
+    );
+    signatures.push({
+      docs: [
+        `Resource for '${key
+          .replace(/}/g, "\\}")
+          .replace(
+            /{/g,
+            "\\{"
+          )}' has methods for the following verbs: ${Object.keys(
+          pathMetadata.methods
+        ).join(", ")}`
+      ],
+      parameters: [
+        { name: "path", type: `"${key}"` },
+        ...getPathParamDefinitions(pathParams)
+      ],
+      returnType: getOperationReturnTypeName(
+        pathMetadata,
+        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 normalizeName(
+      `${pascalCase(operationGroupName)}${pascalCase(name)}`,
+      NameType.Interface
+    );
+  }
+
+  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/rlc-common/buildIndexFile.ts

@@ -0,0 +1,344 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Project, SourceFile } from "ts-morph";
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import {
+  hasCsvCollection,
+  hasInputModels,
+  hasMultiCollection,
+  hasOutputModels,
+  hasPagingOperations,
+  hasPipeCollection,
+  hasPollingOperations,
+  hasSsvCollection,
+  hasTsvCollection,
+  hasUnexpectedHelper
+} from "./helpers/operationHelpers.js";
+import { isAzurePackage } from "./helpers/packageUtil.js";
+import { RLCModel } from "./interfaces.js";
+import * as path from "path";
+import { getImportModuleName } from "./helpers/nameConstructors.js";
+
+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: getImportModuleName(
+      { cjsName: "./parameters", esModulesName: "./parameters.js" },
+      model
+    )
+  });
+
+  file.addImportDeclaration({
+    namespaceImport: "Responses",
+    moduleSpecifier: getImportModuleName(
+      { cjsName: "./responses", esModulesName: "./responses.js" },
+      model
+    )
+  });
+
+  file.addImportDeclaration({
+    namespaceImport: "Client",
+    moduleSpecifier: getImportModuleName(
+      {
+        cjsName: "./clientDefinitions",
+        esModulesName: "./clientDefinitions.js"
+      },
+      model
+    )
+  });
+
+  const exports = ["Parameters", "Responses", "Client"];
+  if (hasInputModels(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "Models",
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: "./models",
+          esModulesName: "./models.js"
+        },
+        model
+      )
+    });
+    exports.push("Models");
+  }
+
+  if (hasOutputModels(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "OutputModels",
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: "./outputModels",
+          esModulesName: "./outputModels.js"
+        },
+        model
+      )
+    });
+    exports.push("OutputModels");
+  }
+
+  if (hasPagingOperations(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "PaginateHelper",
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: "./paginateHelper",
+          esModulesName: "./paginateHelper.js"
+        },
+        model
+      )
+    });
+    exports.push("PaginateHelper");
+  }
+
+  if (hasUnexpectedHelper(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "UnexpectedHelper",
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: "./isUnexpected",
+          esModulesName: "./isUnexpected.js"
+        },
+        model
+      )
+    });
+    exports.push("UnexpectedHelper");
+  }
+
+  if (hasPollingOperations(model)) {
+    file.addImportDeclaration({
+      namespaceImport: "PollingHelper",
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: "./pollingHelper",
+          esModulesName: "./pollingHelper.js"
+        },
+        model
+      )
+    });
+    exports.push("PollingHelper");
+  }
+
+  if (
+    hasMultiCollection(model) ||
+    hasSsvCollection(model) ||
+    hasPipeCollection(model) ||
+    hasTsvCollection(model) ||
+    hasCsvCollection(model)
+  ) {
+    file.addImportDeclaration({
+      namespaceImport: "SerializeHelper",
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: "./serializeHelper",
+          esModulesName: "./serializeHelper.js"
+        },
+        model
+      )
+    });
+    exports.push("SerializeHelper");
+  }
+
+  file.addExportDeclarations([
+    {
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: `./${moduleName}`,
+          esModulesName: `./${moduleName}.js`
+        },
+        model
+      ),
+      namedExports: [`${createClientFuncName}`, `${clientName}ClientOptions`]
+    },
+    {
+      namedExports: [...exports]
+    }
+  ]);
+}
+
+function generateRLCIndex(file: SourceFile, model: RLCModel) {
+  const clientName = model.libraryName;
+  const createClientFuncName = `${clientName}`;
+  const moduleName = normalizeName(clientName, NameType.File);
+
+  file.addImportDeclaration({
+    moduleSpecifier: getImportModuleName(
+      {
+        cjsName: `./${moduleName}`,
+        esModulesName: `./${moduleName}.js`
+      },
+      model
+    ),
+    defaultImport: createClientFuncName
+  });
+
+  file.addExportDeclarations([
+    {
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: `./${moduleName}`,
+          esModulesName: `./${moduleName}.js`
+        },
+        model
+      )
+    },
+    {
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: `./parameters`,
+          esModulesName: `./parameters.js`
+        },
+        model
+      )
+    },
+    {
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: `./responses`,
+          esModulesName: `./responses.js`
+        },
+        model
+      )
+    },
+    {
+      moduleSpecifier: getImportModuleName(
+        {
+          cjsName: `./clientDefinitions`,
+          esModulesName: `./clientDefinitions.js`
+        },
+        model
+      )
+    }
+  ]);
+
+  if (hasUnexpectedHelper(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./isUnexpected`,
+            esModulesName: `./isUnexpected.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+
+  if (hasInputModels(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./models`,
+            esModulesName: `./models.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+
+  if (hasOutputModels(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./outputModels`,
+            esModulesName: `./outputModels.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+
+  if (hasPagingOperations(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./paginateHelper`,
+            esModulesName: `./paginateHelper.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+
+  if (hasPollingOperations(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./pollingHelper`,
+            esModulesName: `./pollingHelper.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+
+  if (
+    hasMultiCollection(model) ||
+    hasSsvCollection(model) ||
+    hasPipeCollection(model) ||
+    hasTsvCollection(model) ||
+    hasCsvCollection(model)
+  ) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: getImportModuleName(
+          {
+            cjsName: `./serializeHelper`,
+            esModulesName: `./serializeHelper.js`
+          },
+          model
+        )
+      }
+    ]);
+  }
+
+  if (isAzurePackage(model)) {
+    file.addExportDeclarations([
+      {
+        moduleSpecifier: "@azure/core-rest-pipeline",
+        namedExports: ["RestError", "isRestError"]
+      }
+    ]);
+  }
+
+  file.addExportAssignment({
+    expression: createClientFuncName,
+    isExportEquals: false
+  });
+}