@azure-tools/typespec-ts 0.55.0-dev.6 → 0.55.0-dev.8

package/src/rlc-common/build-samples.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { File as RLCFile, RLCModel, RLCSampleGroup } from "./interfaces.js";
+import { sampleTemplate } from "./static/sample-template.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import { joinPaths } from "@typespec/compiler";
+import hbs from "handlebars";
+
+// Build sample files for the model based on the sample groups
+export function buildSamples(model: RLCModel) {
+  if (!model.options || !model.options.packageDetails) {
+    return;
+  }
+  const sampleGroups: RLCSampleGroup[] | undefined = model.sampleGroups;
+  if (!sampleGroups || sampleGroups.length === 0) {
+    return;
+  }
+  const sampleFiles: RLCFile[] = [];
+  for (const sampleGroup of sampleGroups) {
+    const sampleGroupFileContents = hbs.compile(sampleTemplate, {
+      noEscape: true,
+    });
+    const filePath = joinPaths("samples-dev", `${sampleGroup.filename}.ts`);
+    sampleFiles.push({
+      path: filePath,
+      content: sampleGroupFileContents(sampleGroup),
+    });
+  }
+  return sampleFiles;
+}

package/src/rlc-common/build-schema-type.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { joinPaths } from "@typespec/compiler";
+import { Project } from "ts-morph";
+import {
+  buildObjectAliases,
+  buildObjectInterfaces,
+  buildPolymorphicAliases,
+} from "./build-object-types.js";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import { RLCModel, SchemaContext } from "./interfaces.js";
+
+/**
+ * Generates types to represent schema definitions in the swagger
+ */
+export function buildSchemaTypes(model: RLCModel) {
+  const { srcPath } = model;
+  const project = new Project({ useInMemoryFileSystem: true });
+  let filePath = joinPaths(srcPath, `models.ts`);
+  const inputModelFile = generateModelFiles(model, project, filePath, [SchemaContext.Input]);
+  filePath = joinPaths(srcPath, `outputModels.ts`);
+  const outputModelFile = generateModelFiles(model, project, filePath, [
+    SchemaContext.Output,
+    SchemaContext.Exception,
+  ]);
+  return { inputModelFile, outputModelFile };
+}
+
+export function generateModelFiles(
+  model: RLCModel,
+  project: Project,
+  filePath: string,
+  schemaContext: SchemaContext[],
+) {
+  // Track models that need to be imported
+  const importedModels = new Set<string>();
+  const objectsDefinitions = buildObjectInterfaces(model, importedModels, schemaContext);
+
+  const objectTypeAliases = buildPolymorphicAliases(model, schemaContext);
+
+  const objectAliases = buildObjectAliases(model, importedModels, schemaContext);
+
+  if (objectTypeAliases.length || objectsDefinitions.length || objectAliases.length) {
+    const modelsFile = project.createSourceFile(filePath, undefined, {
+      overwrite: true,
+    });
+
+    modelsFile.addInterfaces(objectsDefinitions);
+    modelsFile.addTypeAliases(objectTypeAliases);
+    modelsFile.addTypeAliases(objectAliases);
+    if (importedModels.size > 0) {
+      modelsFile.addImportDeclarations([
+        {
+          isTypeOnly: true,
+          namedImports: [...Array.from(importedModels || [])],
+          moduleSpecifier: getImportSpecifier("restClient", model.importInfo.runtimeImports),
+        },
+      ]);
+    }
+    // Add NodeReadableStream import if binary types are used in models.
+    // platform-types.ts is generated directly under src/ (no static-helpers/
+    // subdirectory) to match the RLC design where all output lives in src/.
+    // The platform-types static helper resolves NodeReadableStream to
+    // NodeJS.ReadableStream on Node and `never` on browser/react-native, so the
+    // union arm drops out naturally in non-Node builds.
+    if (modelsFile.getFullText().includes("NodeReadableStream")) {
+      modelsFile.addImportDeclarations([
+        {
+          isTypeOnly: true,
+          namedImports: ["NodeReadableStream"],
+          moduleSpecifier: "#platform/platform-types",
+        },
+      ]);
+    }
+    return { path: filePath, content: modelsFile.getFullText() };
+  }
+  return undefined;
+}

package/src/rlc-common/build-serialize-helper.ts

@@ -0,0 +1,49 @@
+import { joinPaths } from "@typespec/compiler";
+import { RLCModel } from "./interfaces.js";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: to fix the handlebars issue
+import hbs from "handlebars";
+import {
+  hasCsvCollection,
+  hasMultiCollection,
+  hasPipeCollection,
+  hasSsvCollection,
+  hasTsvCollection,
+} from "./helpers/operation-helpers.js";
+import {
+  buildCsvCollectionContent,
+  buildMultiCollectionContent,
+  buildPipeCollectionContent,
+  buildSsvCollectionContent,
+  buildTsvCollectionContent,
+} from "./static/serialize-helper.js";
+
+export function buildSerializeHelper(model: RLCModel) {
+  let serializeHelperContent = "";
+  if (hasMultiCollection(model)) {
+    serializeHelperContent += "\n" + buildMultiCollectionContent;
+  }
+  if (hasPipeCollection(model)) {
+    serializeHelperContent += "\n" + buildPipeCollectionContent;
+  }
+  if (hasSsvCollection(model)) {
+    serializeHelperContent += "\n" + buildSsvCollectionContent;
+  }
+  if (hasTsvCollection(model)) {
+    serializeHelperContent += "\n" + buildTsvCollectionContent;
+  }
+  if (hasCsvCollection(model)) {
+    serializeHelperContent += "\n" + buildCsvCollectionContent;
+  }
+  if (serializeHelperContent !== "") {
+    const readmeFileContents = hbs.compile(serializeHelperContent, {
+      noEscape: true,
+    });
+    const { srcPath } = model;
+    return {
+      path: joinPaths(srcPath, "serializeHelper.ts"),
+      content: readmeFileContents({}),
+    };
+  }
+  return undefined;
+}

package/src/rlc-common/build-top-level-index-file.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { joinPaths } from "@typespec/compiler";
+import { Project } from "ts-morph";
+import { NameType, normalizeName } from "./helpers/name-utils.js";
+import { getRelativePartFromSrcPath } from "./helpers/path-utils.js";
+import { RLCModel } from "./interfaces.js";
+
+const batchOutputFolder: [string, string, string][] = [];
+
+export function buildTopLevelIndex(model: RLCModel) {
+  if (!model.options) {
+    return undefined;
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const { srcPath } = model;
+  const { multiClient } = model.options;
+  const batch = model.options.batch;
+  if (srcPath) {
+    const clientName = model.libraryName;
+    const moduleName = normalizeName(clientName, NameType.File);
+    const relativePath = "./" + getRelativePartFromSrcPath(srcPath, model.options.isModularLibrary);
+    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({
+        isTypeOnly: true,
+        namespaceImport: item[1],
+        moduleSpecifier: `${item[0]}/index.js`,
+      });
+      allModules.push(item[1]);
+    });
+    indexFile.addExportDeclaration({
+      namedExports: [...allModules],
+    });
+    const content = indexFile.getFullText();
+    const filePath = joinPaths(
+      srcPath.substring(0, srcPath.lastIndexOf("src") + 4),
+      model.options.isModularLibrary ? "rest" : "",
+      `index.ts`,
+    );
+    return { path: filePath, content };
+  }
+  return undefined;
+}

package/src/rlc-common/helpers/imports-util.ts

@@ -0,0 +1,172 @@
+import { SourceFile } from "ts-morph";
+import { ImportType, Imports } from "../interfaces.js";
+
+/**
+ * Build the common imports for generated SDK. Azure Core packages are always used.
+ * @returns
+ */
+export function buildRuntimeImports(): Imports {
+  return {
+    restClient: {
+      type: "restClient",
+      specifier: "@azure-rest/core-client",
+      version: "^2.0.0",
+    },
+    coreAuth: {
+      type: "coreAuth",
+      specifier: "@azure/core-auth",
+      version: "^1.6.0",
+    },
+    restPipeline: {
+      type: "restPipeline",
+      specifier: "@azure/core-rest-pipeline",
+      version: "^1.14.0",
+    },
+    coreUtil: {
+      type: "coreUtil",
+      specifier: "@azure/core-util",
+      version: "^1.4.0",
+    },
+    coreLogger: {
+      type: "coreLogger",
+      specifier: "@azure/logger",
+      version: "^1.0.4",
+    },
+    azureEslintPlugin: {
+      type: "azureEslintPlugin",
+      specifier: "@azure/eslint-plugin-azure-sdk",
+      version: "^3.0.0",
+    },
+    azureTestRecorder: {
+      type: "azureTestRecorder",
+      specifier: "@azure-tools/test-recorder",
+      version: "^3.0.0",
+    },
+    azureCoreLro: {
+      type: "azureCoreLro",
+      specifier: "@azure/core-lro",
+    },
+  } as Imports;
+}
+
+/**
+ * Initialize the inner imports for parameter and response, the import set would be used for referred models
+ * @returns
+ */
+export function initInternalImports(): Imports {
+  return {
+    parameter: {
+      type: "parameter",
+      importsSet: new Set<string>(),
+    },
+    response: {
+      type: "response",
+      importsSet: new Set<string>(),
+    },
+    rlcIndex: {
+      type: "rlcIndex",
+      importsSet: new Set<string>(),
+    },
+    modularModel: {
+      type: "modularModel",
+      importsSet: new Set<string>(),
+    },
+    rlcClientFactory: {
+      type: "rlcClientFactory",
+      importsSet: new Set<string>(),
+    },
+    rlcClientDefinition: {
+      type: "rlcClientDefinition",
+      importsSet: new Set<string>(),
+    },
+    serializerHelpers: {
+      type: "serializerHelpers",
+      importsSet: new Set<string>(),
+    },
+  } as Imports;
+}
+
+export function getImportSpecifier(
+  importType: ImportType,
+  imports?: Imports,
+  includeFallback = true,
+): string {
+  imports = imports ?? ({} as Imports);
+  const defaultPackageMap: Record<ImportType, string> = {
+    restClient: "@azure-rest/core-client",
+    coreAuth: "@azure/core-auth",
+    restPipeline: "@azure/core-rest-pipeline",
+    coreUtil: "@azure/core-util",
+    coreLogger: "@azure/logger",
+    azureCoreLro: "@azure/core-lro",
+  } as any;
+  if (!includeFallback) {
+    return imports[importType]?.specifier ?? "";
+  }
+  return (
+    (imports[importType] ?? imports.commonFallback)?.specifier ??
+    defaultPackageMap[importType] ??
+    ""
+  );
+}
+
+export function addImportToSpecifier(
+  importType: ImportType,
+  runtimeImports: Imports,
+  importedName: string,
+): void {
+  const specifier = getImportSpecifier(importType, runtimeImports);
+  const importSet = runtimeImports[importType]?.importsSet;
+  if (!importSet) {
+    runtimeImports[importType] = {
+      type: importType,
+      specifier,
+      importsSet: new Set<string>().add(importedName),
+    };
+  } else {
+    importSet.add(importedName);
+  }
+}
+
+export function clearImportSets(runtimeImports: Imports): void {
+  for (const importType of Object.values(runtimeImports)) {
+    importType.importsSet?.clear();
+  }
+}
+
+export function addImportsToFiles(
+  runtimeImports: Imports,
+  file: SourceFile,
+  internalSpecifierMap?: Record<string, string>,
+): void {
+  Object.values(runtimeImports)
+    .filter((importType) => {
+      return importType.importsSet?.size;
+    })
+    .forEach((importType) => {
+      const specifier = internalSpecifierMap?.[importType.type] ?? importType.specifier!;
+      let hasModifier = false;
+      if (!specifier) {
+        return;
+      }
+      file
+        .getImportDeclarations()
+        .filter((importDeclaration) => {
+          return importDeclaration.getModuleSpecifierValue() === specifier;
+        })
+        .forEach((importDeclaration) => {
+          hasModifier = true;
+          importDeclaration.addNamedImports([...importType.importsSet!.values()]);
+        });
+
+      if (!hasModifier) {
+        file.addImportDeclaration({
+          isTypeOnly: true,
+          moduleSpecifier: specifier,
+          namedImports: [...importType.importsSet!.values()],
+        });
+        return;
+      }
+    });
+  clearImportSets(runtimeImports);
+}

package/src/rlc-common/helpers/name-constructors.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { RLCModel } from "../interfaces.js";
+import { NameType, normalizeName } from "./name-utils.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 (operationName) {
+    baseNameOrOperationGroup = getResponseBaseName(
+      baseNameOrOperationGroup,
+      operationName!,
+      statusCode || "",
+    );
+  }
+  return normalizeName(`${baseNameOrOperationGroup}Response`, NameType.Interface);
+}
+
+export function getLroLogicalResponseName(operationGroup: string, operationName: string) {
+  return normalizeName(`${operationGroup}_${operationName}_Logical_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}_${normalizeName(operationName, NameType.Interface, true)}_${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 (operationName) {
+    baseNameOrOperationGroup = getParameterBaseName(baseNameOrOperationGroup, operationName!);
+  }
+
+  return normalizeName(`${baseNameOrOperationGroup}_Parameters`, NameType.Interface);
+}
+
+export function getClientName(model: RLCModel) {
+  const clientName = model.libraryName;
+  const clientInterfaceName = model.options?.isModularLibrary
+    ? model.libraryName
+    : clientName.endsWith("Client")
+      ? `${clientName}`
+      : `${clientName}Client`;
+
+  return clientInterfaceName;
+}
+
+export function getMultipartPartTypeName(schemaName: string, partName: string) {
+  const name = normalizeName(partName, NameType.Interface);
+  const bodyParamName = normalizeName(schemaName, NameType.Interface);
+
+  return normalizeName(`${bodyParamName}_${name}_PartDescriptor`, NameType.Interface);
+}

package/src/rlc-common/helpers/operation-helpers.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { MethodSignatureStructure, OptionalKind, ParameterDeclarationStructure } from "ts-morph";
+import {
+  Methods,
+  ObjectSchema,
+  ParameterMetadata,
+  PathParameter,
+  RLCModel,
+  Schema,
+  SchemaContext,
+} from "../interfaces.js";
+import { NameType, normalizeName, pascalCase } from "./name-utils.js";
+import { isObjectSchema } from "./schema-helpers.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];
+    if (!verbMethods) {
+      continue;
+    }
+    for (const method of verbMethods) {
+      const description = method.description;
+      const 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: normalizeName(name, NameType.Parameter),
+      type,
+      description,
+    };
+  });
+}
+
+export function hasPagingOperations(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasPaging);
+}
+
+export function hasPollingOperations(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasLongRunning);
+}
+
+export function hasMultiCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasMultiCollection);
+}
+
+export function hasPipeCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasPipeCollection);
+}
+
+export function hasSsvCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasSsvCollection);
+}
+
+export function hasTsvCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasTsvCollection);
+}
+
+export function hasCsvCollection(model: RLCModel) {
+  return Boolean(model.helperDetails?.hasCsvCollection);
+}
+
+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 firstMethod = methodDetails[0];
+      if (!firstMethod) {
+        continue;
+      }
+      const successTypes = firstMethod.responseTypes.success;
+      const errorTypes = firstMethod.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;
+}
+
+export function getGeneratedWrapperTypes(params: ParameterMetadata[] | PathParameter[]): Schema[] {
+  const wrapperTypes = params
+    .map((qp) => (isParameterMetadata(qp) ? qp.param.wrapperType : qp.wrapperType))
+    .filter((v) => v !== undefined);
+  const wrapperFromObjects = wrapperTypes.filter((wrap) => wrap.type === "object");
+  const wrapperFromUnions = wrapperTypes
+    .filter((wrap) => wrap.type === "union")
+    .flatMap((wrapperType) => wrapperType?.enum ?? [])
+    .filter((v) => v.type === "object");
+  return [...wrapperFromUnions, ...wrapperFromObjects];
+}
+
+function isParameterMetadata(param: ParameterMetadata | PathParameter): param is ParameterMetadata {
+  return (param as any).param !== undefined;
+}

package/src/rlc-common/helpers/path-utils.ts

@@ -0,0 +1,8 @@
+export function getRelativePartFromSrcPath(srcPath: string, isModularLibrary: boolean = false) {
+  const sep = "/";
+  let relativePart = srcPath.substring(srcPath.indexOf(sep + "src") + 4);
+  if (isModularLibrary) {
+    relativePart = relativePart.substring(srcPath.indexOf(sep + "rest"), +5);
+  }
+  return relativePart.startsWith(sep) ? relativePart.substring(1) : relativePart;
+}

package/src/rlc-common/helpers/shortcut-methods.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { InterfaceDeclarationStructure, MethodSignatureStructure, OptionalKind } from "ts-morph";
+import { PathMetadata, Paths } from "../interfaces.js";
+import { NameType, normalizeName } from "./name-utils.js";
+import { buildMethodDefinitions } from "./operation-helpers.js";
+
+export function generateMethodShortcuts(
+  paths: Paths,
+): OptionalKind<InterfaceDeclarationStructure>[] {
+  const keys: Record<string, OptionalKind<MethodSignatureStructure>[]> = {};
+  for (const path in paths) {
+    const pathMetadata = paths[path];
+    if (!pathMetadata) {
+      continue;
+    }
+    const groupName = pathMetadata.operationGroupName;
+    const definitions = buildOperationDefinitions(pathMetadata);
+    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];
+    if (!methods) {
+      continue;
+    }
+    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;
+}