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

package/src/buildTopLevelIndexFile.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { NameType, normalizeName } from "./helpers/nameUtils.js";
+import { RLCModel } from "./interfaces.js";
+import { Project } from "ts-morph";
+
+const batchOutputFolder: [string, string, string][] = [];
+
+export function buildTopLevelIndex(model: RLCModel) {
+  if (!model.options) {
+    return undefined;
+  }
+  const project = new Project();
+  const { srcPath } = model;
+  const { multiClient, batch } = model.options;
+  if (srcPath) {
+    const clientName = model.libraryName;
+    const moduleName = normalizeName(clientName, NameType.File);
+    const relativePath = srcPath.replace("/src", "");
+    batchOutputFolder.push([relativePath, clientName, moduleName]);
+  }
+  if (
+    multiClient &&
+    batch &&
+    batch.length > 1 &&
+    batchOutputFolder.length === batch.length
+  ) {
+    const indexFile = project.createSourceFile("index.ts", undefined, {
+      overwrite: true
+    });
+    const allModules: string[] = [];
+    batchOutputFolder.forEach((item) => {
+      indexFile.addImportDeclaration({
+        namespaceImport: item[1],
+        moduleSpecifier: `${item[0]}`
+      });
+      allModules.push(item[1]);
+    });
+    indexFile.addExportDeclaration({
+      namedExports: [...allModules]
+    });
+    // TODO handle multi-client path issue in cald
+    return { path: "", content: indexFile.getFullText() };
+  }
+}

package/src/helpers/nameConstructors.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { NameType, normalizeName } from "./nameUtils.js";
+
+/**
+ * Get the response type name by baseName or operatioName & statusCode
+ * @param baseResponseName
+ */
+export function getResponseTypeName(baseResponseName: string): string;
+export function getResponseTypeName(
+  operationGroup: string,
+  operationName: string,
+  statusCode: string
+): string;
+export function getResponseTypeName(
+  baseNameOrOperationGroup: string,
+  operationName?: string,
+  statusCode?: string
+): string {
+  if (Boolean(operationName)) {
+    baseNameOrOperationGroup = getResponseBaseName(
+      baseNameOrOperationGroup,
+      operationName!,
+      statusCode || ""
+    );
+  }
+  return normalizeName(
+    `${baseNameOrOperationGroup}Response`,
+    NameType.Interface
+  );
+}
+
+/**
+ * The prefix of all response types
+ * @param operationGroup operation group name e.g string_PutEmpty
+ * @param operationName operation name D e.g string_PutEmpty
+ * @param statusCode 2XX, 4XX, 5XX, default etc.
+ * @returns normolized base name e.g StringPutEmpty200
+ */
+export function getResponseBaseName(
+  operationGroup: string,
+  operationName: string,
+  statusCode: string
+) {
+  return normalizeName(
+    `${operationGroup}_${operationName}_${statusCode}`,
+    NameType.Interface
+  );
+}
+
+/**
+ * The prefix of all parameter relevant types
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns
+ */
+export function getParameterBaseName(
+  operationGroup: string,
+  operationName: string
+) {
+  return normalizeName(
+    `${operationGroup}_${operationName}`,
+    NameType.Interface
+  );
+}
+
+/**
+ * Get the top-layer parameter name
+ * @param operationGroup operation group name
+ * @param operationName is composed with operationGroup and operationID e.g string_PutEmpty
+ * @returns top-layer parameter name e.g StringPutEmptParameters
+ */
+export function getParameterTypeName(baseName: string): string;
+export function getParameterTypeName(
+  operationGroup: string,
+  operationName: string
+): string;
+export function getParameterTypeName(
+  baseNameOrOperationGroup: string,
+  operationName?: string
+) {
+  if (Boolean(operationName)) {
+    baseNameOrOperationGroup = getParameterBaseName(
+      baseNameOrOperationGroup,
+      operationName!
+    );
+  }
+
+  return normalizeName(
+    `${baseNameOrOperationGroup}_Parameters`,
+    NameType.Interface
+  );
+}

package/src/helpers/nameUtils.ts

@@ -0,0 +1,227 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export interface ReservedName {
+  name: string;
+  reservedFor: NameType[];
+}
+
+export enum NameType {
+  Class,
+  File,
+  Interface,
+  Property,
+  Parameter,
+  Operation,
+  OperationGroup
+}
+
+const Newable = [NameType.Class, NameType.Interface, NameType.OperationGroup];
+
+const ReservedModelNames: ReservedName[] = [
+  { name: "any", reservedFor: [NameType.Parameter] },
+  { name: "as", reservedFor: [NameType.Parameter] },
+  { name: "boolean", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "break", reservedFor: [NameType.Parameter] },
+  { name: "case", reservedFor: [NameType.Parameter] },
+  { name: "catch", reservedFor: [NameType.Parameter] },
+  { name: "class", reservedFor: [NameType.Parameter] },
+  { name: "const", reservedFor: [NameType.Parameter] },
+  { name: "constructor", reservedFor: [NameType.Parameter] },
+  { name: "continue", reservedFor: [NameType.Parameter] },
+  { name: "date", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "debugger", reservedFor: [NameType.Parameter] },
+  { name: "declare", reservedFor: [NameType.Parameter] },
+  { name: "default", reservedFor: [NameType.Parameter] },
+  { name: "delete", reservedFor: [NameType.Parameter] },
+  { name: "do", reservedFor: [NameType.Parameter] },
+  { name: "else", reservedFor: [NameType.Parameter] },
+  { name: "enum", reservedFor: [NameType.Parameter] },
+  { name: "error", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "export", reservedFor: [NameType.Parameter] },
+  { name: "extends", reservedFor: [NameType.Parameter] },
+  { name: "false", reservedFor: [NameType.Parameter] },
+  { name: "finally", reservedFor: [NameType.Parameter] },
+  { name: "for", reservedFor: [NameType.Parameter] },
+  { name: "from", reservedFor: [NameType.Parameter] },
+  { name: "function", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "get", reservedFor: [NameType.Parameter] },
+  { name: "if", reservedFor: [NameType.Parameter] },
+  { name: "implements", reservedFor: [NameType.Parameter] },
+  { name: "import", reservedFor: [NameType.Parameter] },
+  { name: "in", reservedFor: [NameType.Parameter] },
+  { name: "instanceof", reservedFor: [NameType.Parameter] },
+  { name: "interface", reservedFor: [NameType.Parameter] },
+  { name: "let", reservedFor: [NameType.Parameter] },
+  { name: "module", reservedFor: [NameType.Parameter] },
+  { name: "new", reservedFor: [NameType.Parameter] },
+  { name: "null", reservedFor: [NameType.Parameter] },
+  { name: "number", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "of", reservedFor: [NameType.Parameter] },
+  { name: "package", reservedFor: [NameType.Parameter] },
+  { name: "private", reservedFor: [NameType.Parameter] },
+  { name: "protected", reservedFor: [NameType.Parameter] },
+  { name: "public", reservedFor: [NameType.Parameter] },
+  { name: "requestoptions", reservedFor: [NameType.Parameter] },
+  { name: "require", reservedFor: [NameType.Parameter] },
+  { name: "return", reservedFor: [NameType.Parameter] },
+  { name: "set", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "static", reservedFor: [NameType.Parameter] },
+  { name: "string", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "super", reservedFor: [NameType.Parameter] },
+  { name: "switch", reservedFor: [NameType.Parameter] },
+  { name: "symbol", reservedFor: [NameType.Parameter, ...Newable] },
+  { name: "this", reservedFor: [NameType.Parameter] },
+  { name: "throw", reservedFor: [NameType.Parameter] },
+  { name: "true", reservedFor: [NameType.Parameter] },
+  { name: "try", reservedFor: [NameType.Parameter] },
+  { name: "type", reservedFor: [NameType.Parameter] },
+  { name: "typeof", reservedFor: [NameType.Parameter] },
+  { name: "var", reservedFor: [NameType.Parameter] },
+  { name: "void", reservedFor: [NameType.Parameter] },
+  { name: "while", reservedFor: [NameType.Parameter] },
+  { name: "with", reservedFor: [NameType.Parameter] },
+  { name: "yield", reservedFor: [NameType.Parameter] },
+  { name: "arguments", reservedFor: [NameType.Parameter] }
+];
+
+export enum CasingConvention {
+  Pascal,
+  Camel
+}
+
+export function guardReservedNames(
+  name: string,
+  nameType: NameType,
+  customReservedNames: ReservedName[] = []
+): string {
+  const suffix = getSuffix(nameType);
+  return [...ReservedModelNames, ...customReservedNames]
+    .filter((r) => r.reservedFor.includes(nameType))
+    .find((r) => r.name === name.toLowerCase())
+    ? `${name}${suffix}`
+    : name;
+}
+
+function getSuffix(nameType?: NameType) {
+  switch (nameType) {
+    case NameType.File:
+    case NameType.Operation:
+    case NameType.Property:
+      return "";
+    case NameType.OperationGroup:
+      return "Operations";
+    case NameType.Parameter:
+      return "Param";
+    case NameType.Class:
+    case NameType.Interface:
+    default:
+      return "Model";
+  }
+}
+
+export function normalizeName(
+  name: string,
+  nameType: NameType,
+  shouldGuard?: boolean,
+  customReservedNames: ReservedName[] = [],
+  casingOverride?: CasingConvention
+): string {
+  if (name.startsWith("$DO_NOT_NORMALIZE$")) {
+    return name.replace("$DO_NOT_NORMALIZE$", "");
+  }
+  const casingConvention = casingOverride ?? getCasingConvention(nameType);
+  const sanitizedName = sanitizeName(name);
+  const parts = getNameParts(sanitizedName);
+  const [firstPart, ...otherParts] = parts;
+  const normalizedFirstPart = toCasing(firstPart, casingConvention);
+  const normalizedParts = (otherParts || [])
+    .map((part) =>
+      part === "null" ? part : toCasing(part, CasingConvention.Pascal)
+    )
+    .join("");
+
+  const normalized = checkBeginning(`${normalizedFirstPart}${normalizedParts}`);
+  return shouldGuard
+    ? guardReservedNames(normalized, nameType, customReservedNames)
+    : normalized;
+}
+
+function checkBeginning(name: string): string {
+  if (name.startsWith("@")) {
+    return name.substring(1);
+  }
+  return name;
+}
+
+function sanitizeName(name: string): string {
+  // Remove \, " and ' from name string
+  return name.replace(/["'\\]+/g, "");
+}
+
+export function getModelsName(title: string): string {
+  const spaceRemovedTitle = title.replace(/ /g, "");
+  return `${spaceRemovedTitle.replace("Client", "")}Models`;
+}
+
+export function getMappersName(title: string): string {
+  const spaceRemovedTitle = title.replace(/ /g, "");
+  return `${spaceRemovedTitle.replace("Client", "")}Mappers`;
+}
+
+function getCasingConvention(nameType: NameType) {
+  switch (nameType) {
+    case NameType.Class:
+    case NameType.Interface:
+    case NameType.OperationGroup:
+      return CasingConvention.Pascal;
+    case NameType.File:
+    case NameType.Property:
+    case NameType.Operation:
+    case NameType.Parameter:
+      return CasingConvention.Camel;
+  }
+}
+
+/**
+ * TODO: Improve this function to handle cases such as TEST -> test. Current basic implementation
+ * results in TEST -> test or Test (depending on the CasingConvention). We should switch to relay
+ * on Modeler four namer for this once it is stable
+ */
+function toCasing(str: string, casing: CasingConvention): string {
+  let value = str;
+  if (value === value.toUpperCase()) {
+    value = str.toLowerCase();
+  }
+
+  const firstChar =
+    casing === CasingConvention.Pascal
+      ? value.charAt(0).toUpperCase()
+      : value.charAt(0).toLocaleLowerCase();
+  return `${firstChar}${value.substring(1)}`;
+}
+
+function getNameParts(name: string) {
+  let parts = name.split(/[-._ ]+/);
+
+  return parts.length > 0 ? parts : [name];
+}
+
+export function pascalCase(str: string) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export function camelCase(
+  str: string,
+  options: { uppercaseThreshold?: number } = {}
+) {
+  const { uppercaseThreshold = 4 } = options;
+  const thresholdRegex = new RegExp(
+    `^(?<![A-Z])[A-Z]{1,${uppercaseThreshold}}(?![A-Z])`
+  );
+  if (!thresholdRegex.test(str)) {
+    return str;
+  }
+
+  return str.charAt(0).toLocaleLowerCase() + str.slice(1);
+}

package/src/helpers/operationHelpers.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  MethodSignatureStructure,
+  OptionalKind,
+  ParameterDeclarationStructure
+} from "ts-morph";
+import {
+  Methods,
+  ObjectSchema,
+  PathParameter,
+  RLCModel,
+  SchemaContext
+} from "../interfaces.js";
+import { pascalCase } from "./nameUtils.js";
+import { isObjectSchema } from "./schemaHelpers.js";
+
+export function buildMethodDefinitions(
+  methods: Methods,
+  pathParams: PathParameter[] = []
+): OptionalKind<MethodSignatureStructure>[] {
+  const methodDefinitions: OptionalKind<MethodSignatureStructure>[] = [];
+  for (const key of Object.keys(methods)) {
+    const verbMethods = methods[key];
+
+    for (const method of verbMethods) {
+      const description = method.description;
+      let areAllOptional = method.hasOptionalOptions;
+
+      methodDefinitions.push({
+        name: key,
+        ...(description && { docs: [{ description }] }),
+        parameters: [
+          ...getPathParamDefinitions(pathParams),
+          {
+            name: "options",
+            hasQuestionToken: areAllOptional,
+            type: pascalCase(method.optionsName)
+          }
+        ],
+        returnType: `StreamableMethod<${method.returnType}>`
+      });
+    }
+  }
+
+  return methodDefinitions;
+}
+
+export function getPathParamDefinitions(
+  pathParams: PathParameter[]
+): OptionalKind<ParameterDeclarationStructure>[] {
+  return pathParams.map(({ name, type, description }) => {
+    return {
+      name,
+      type,
+      description
+    };
+  });
+}
+
+export function hasPagingOperations(model: RLCModel) {
+  return Boolean(model.annotations?.hasPaging);
+}
+
+export function hasPollingOperations(model: RLCModel) {
+  return Boolean(model.annotations?.hasLongRunning);
+}
+
+export function hasUnexpectedHelper(model: RLCModel) {
+  const pathDictionary = model.paths;
+  for (const details of Object.values(pathDictionary)) {
+    for (const methodDetails of Object.values(details.methods)) {
+      const successTypes = methodDetails[0].responseTypes.success;
+      const errorTypes = methodDetails[0].responseTypes.error;
+
+      if (successTypes.length > 0 && errorTypes.length > 0 && !!errorTypes[0]) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function hasInputModels(model: RLCModel) {
+  return hasSchemaContextObject(model, [SchemaContext.Input]);
+}
+export function hasOutputModels(model: RLCModel) {
+  return hasSchemaContextObject(model, [
+    SchemaContext.Output,
+    SchemaContext.Exception
+  ]);
+}
+
+function hasSchemaContextObject(model: RLCModel, schemaUsage: SchemaContext[]) {
+  const objectSchemas: ObjectSchema[] = (model.schemas ?? []).filter(
+    (o) =>
+      isObjectSchema(o) &&
+      (o as ObjectSchema).usage?.some((u) => schemaUsage.includes(u))
+  );
+
+  return objectSchemas.length > 0;
+}

package/src/helpers/schemaHelpers.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Schema } from "../interfaces.js";
+
+export function isDictionarySchema(schema: Schema) {
+  if (schema.type === "dictionary") {
+    return true;
+  }
+  return false;
+}
+
+export function isObjectSchema(schema: Schema) {
+  if (schema.type === "object") {
+    return true;
+  }
+  return false;
+}
+
+export function isConstantSchema(schema: Schema) {
+  if (schema.type === "constant") {
+    return true;
+  }
+  return false;
+}

package/src/helpers/shortcutMethods.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  OptionalKind,
+  MethodSignatureStructure,
+  InterfaceDeclarationStructure
+} from "ts-morph";
+import { PathMetadata, Paths } from "../interfaces.js";
+import { buildMethodDefinitions } from "./operationHelpers.js";
+import { NameType, normalizeName } from "./nameUtils.js";
+
+export function generateMethodShortcuts(
+  paths: Paths
+): OptionalKind<InterfaceDeclarationStructure>[] {
+  let keys: Record<string, OptionalKind<MethodSignatureStructure>[]> = {};
+  for (const path in paths) {
+    const groupName = paths[path].operationGroupName;
+    const definitions = buildOperationDefinitions(paths[path]);
+    if (!keys[groupName]) {
+      keys[groupName] = definitions;
+    } else {
+      keys[groupName] = [...keys[groupName], ...definitions];
+    }
+  }
+
+  const interfaces: OptionalKind<InterfaceDeclarationStructure>[] = [];
+
+  for (const interfaceName in keys) {
+    const methods = keys[interfaceName];
+    interfaces.push({
+      name: `${interfaceName}Operations`,
+      methods: methods,
+      isExported: true,
+      docs: [`Contains operations for ${interfaceName} operations`]
+    });
+  }
+
+  return interfaces;
+}
+
+function buildOperationDefinitions(
+  path: PathMetadata
+): OptionalKind<MethodSignatureStructure>[] {
+  let ops: OptionalKind<MethodSignatureStructure>[] = [];
+
+  for (const verb in path.methods) {
+    const methods = path.methods[verb];
+    for (const method of methods) {
+      const name = normalizeName(method.operationName, NameType.Property);
+      const pathParams = path.pathParameters;
+      const methodDefinitions = buildMethodDefinitions(
+        { [name]: [method] },
+        pathParams
+      );
+      ops = [...ops, ...methodDefinitions];
+    }
+  }
+  return ops;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+export * from "./interfaces.js";
+export * from "./buildClientDefinitions.js";
+export * from "./buildSchemaType.js";
+export * from "./buildClient.js";
+export * from "./helpers/nameConstructors.js";
+export * from "./buildResponseTypes.js";
+export * from "./helpers/shortcutMethods.js";
+export * from "./helpers/nameUtils.js";
+export * from "./buildParameterTypes.js";
+export * from "./buildIsUnexpectedHelper.js";
+export * from "./buildTopLevelIndexFile.js";
+export * from "./buildIndexFile.js";
+export * from "./buildPaginateHelper.js";
+export * from "./buildPollingHelper.js";
+export * from "./test/buildKarmaConfig.js";
+export * from "./test/buildEnvFile.js";
+export * from "./test/buildRecordedClient.js";
+export * from "./test/buildSampleTest.js";
+export * from "./metadata/buildReadmeFile.js";
+export * from "./metadata/buildApiExtractorConfig.js";
+export * from "./metadata/buildPackageFile.js";
+export * from "./metadata/buildRollupConfig.js";
+export * from "./metadata/buildTsConfig.js";
+export * from "./metadata/buildESLintConfig.js";
+export * from "./metadata/buildLicenseFile.js";