@azure-tools/typespec-ts 0.54.1 → 0.54.2

package/src/modular/serialization/serialize-utils.ts

@@ -0,0 +1,217 @@
+import {
+  SdkModelPropertyType,
+  SdkModelType,
+  SdkType,
+} from "@azure-tools/typespec-client-generator-core";
+import { getAllAncestors } from "../helpers/operation-helpers.js";
+import { getDirectSubtypes } from "../helpers/type-helpers.js";
+
+/**
+ * Get all discriminated values for a given model type and given discriminator property.
+ * @param type The model type to get discriminated values from.
+ * @param discriminatorProperty The discriminator property to use for filtering.
+ * @returns An array of all discriminated values.
+ */
+export function getAllDiscriminatedValues(
+  type: SdkModelType,
+  discriminatorProperty?: SdkModelPropertyType,
+) {
+  if (!type.discriminatorValue) {
+    return [];
+  }
+  const values: string[] = [];
+  const children = [type];
+  while (children.length > 0) {
+    const model = children.shift()!;
+    // skip if no discriminator value
+    if (!model.discriminatorValue) {
+      continue;
+    }
+    // Check if this model is a subtype of the given discriminator property
+    if (
+      !!discriminatorProperty &&
+      model.baseModel?.discriminatorProperty?.name === discriminatorProperty?.name
+    ) {
+      values.push(model.discriminatorValue);
+      if (model.discriminatorProperty?.name === discriminatorProperty.name) {
+        // Traverse subtypes also if they have the same discriminator property
+        children.push(...getDirectSubtypes(model));
+      }
+    }
+  }
+
+  return values;
+}
+
+export function isSupportedSerializeType(type: SdkType): boolean {
+  return (
+    type.kind === "model" || type.kind === "dict" || type.kind === "array" || type.kind === "union"
+  );
+}
+
+/**
+ *
+ * In general, we have two kinds of basic special union variants.
+ * 1. datetime type
+ * 2. bytes type
+ * If we consider model type, we have the following three type.
+ * 3. model with property of datetime type.
+ * 4. model with property of binary array type.
+ * 5. model that has different property name between rest layer and modular layer.
+ * 6. nested model i.e. model with property that is a model with one of the above three conditions.
+ * If we consider array type, with all the above 6 types as the element types.
+ */
+const specialVariantMap = new Map<SdkType, boolean>();
+export function isSpecialUnionVariant(
+  t: SdkType & { isNonExhaustive?: boolean },
+  variantStack: SdkType[] = [],
+): boolean {
+  if (variantStack.length <= 0) {
+    variantStack.push(t);
+  }
+  const ancestors = getAllAncestors(t);
+  if (specialVariantMap.has(t)) {
+    variantStack.pop();
+    return specialVariantMap.get(t) ?? false;
+  }
+
+  if (
+    t.kind === "utcDateTime" ||
+    t.kind === "plainDate" ||
+    t.kind === "bytes" ||
+    (t.kind === "model" &&
+      t.properties
+        ?.filter((p) => {
+          return !(
+            variantStack.includes(p.type) ||
+            ancestors.includes(p.type) ||
+            (p.type.kind === "array" &&
+              p.type.valueType &&
+              (variantStack.includes(p.type.valueType) || ancestors.includes(p.type.valueType)))
+          );
+        })
+        ?.some(
+          (p) =>
+            (p.kind === "property" && p.name !== p.serializationOptions.json?.name) ||
+            isSpecialUnionVariant(p.type, [...variantStack, p.type]),
+        )) ||
+    isPolymorphicUnion(t) ||
+    (t.kind === "array" &&
+      t.valueType &&
+      !variantStack.includes(t.valueType) &&
+      !ancestors.includes(t.valueType) &&
+      isSpecialUnionVariant(t.valueType, [...variantStack, t.valueType])) ||
+    (t.kind === "union" &&
+      t.variantTypes
+        ?.filter((p) => {
+          return !(variantStack.includes(p) || ancestors.includes(p));
+        })
+        ?.some((p) => {
+          return isSpecialUnionVariant(p, [...variantStack, p]);
+        })) ||
+    (t.kind === "enum" && !(t.isFixed || t.isNonExhaustive))
+  ) {
+    specialVariantMap.set(t, true);
+    variantStack.pop();
+    return true;
+  }
+  variantStack.pop();
+  specialVariantMap.set(t, false);
+  return false;
+}
+
+export function isNormalUnion(t: SdkType): boolean {
+  return (
+    t.kind === "union" &&
+    !(
+      t.variantTypes?.some((p) => {
+        return isSpecialUnionVariant(p);
+      }) ?? false
+    )
+  );
+}
+
+export function isDiscriminatedUnion(
+  type: SdkType,
+): type is SdkModelType & { discriminatorProperty: SdkType } {
+  if (!type) {
+    return false;
+  }
+  return Boolean(
+    type?.kind === "model" && type.discriminatorProperty && type.discriminatedSubtypes,
+  );
+}
+
+export function isSpecialHandledUnion(t: SdkType & { isNonExhaustive?: boolean }): boolean {
+  return isDiscriminatedUnion(t!) || isPolymorphicUnion(t);
+}
+
+const polymorphicUnionMap = new Map<SdkType, boolean>();
+export function isPolymorphicUnion(t: SdkType): boolean {
+  if (polymorphicUnionMap.has(t)) {
+    return polymorphicUnionMap.get(t) ?? false;
+  }
+  const ancestors = getAllAncestors(t);
+  if (
+    t.kind === "model" &&
+    t.discriminatedSubtypes &&
+    Object.values(t.discriminatedSubtypes)
+      ?.filter((p) => {
+        return !ancestors.includes(p);
+      })
+      ?.some((p) => {
+        return isSpecialUnionVariant(p);
+      })
+  ) {
+    polymorphicUnionMap.set(t, true);
+    return true;
+  }
+  polymorphicUnionMap.set(t, false);
+  return false;
+}
+
+export interface ModelSerializeOptions {
+  nameOnly: boolean;
+  skipDiscriminatedUnionSuffix: boolean;
+  // Indicates if the serializer is being built for a property that is flattened.
+  flatten?: {
+    baseModel: SdkModelType;
+    property: SdkModelPropertyType;
+  };
+  // Indicates if any overrides should be applied when building the serializer/deserializer.
+  overrides?: ModelOverrideOptions;
+  // Predefined name to use for the serializer/deserializer instead of generating one.
+  predefinedName?: string;
+}
+
+// Options for overriding model information during serialization/deserialization.
+export interface ModelOverrideOptions {
+  // If true, all properties will be treated as optional during serialization/deserialization.
+  allOptional?: boolean;
+
+  // The <Property, Client_Name> map for any renamed properties.
+  // Mainly because the original client name has collision with other property names during flattening.
+  propertyRenames?: Map<SdkModelPropertyType, string>;
+
+  // If true (default), enable flattening for nested flatten properties when generating samples.
+  // When false, nested flatten properties are not further flattened to match the TypeScript interface structure.
+  enableFlatten?: boolean;
+}
+
+export function getPropertyWithOverrides(
+  property: SdkModelPropertyType,
+  overrides?: ModelOverrideOptions,
+): SdkModelPropertyType {
+  if (!overrides) {
+    return property;
+  }
+  let updatedProperty = property;
+  if (overrides.allOptional) {
+    updatedProperty = { ...updatedProperty, optional: true };
+  }
+  const renamedClientName = overrides.propertyRenames?.get(property);
+  if (renamedClientName) {
+    updatedProperty = { ...updatedProperty, name: renamedClientName };
+  }
+  return updatedProperty;
+}

package/src/modular/type-expressions/get-credential-expression.ts

@@ -1,5 +1,5 @@
 import { SdkCredentialType } from "@azure-tools/typespec-client-generator-core";
-import { useDependencies } from "../../framework/hooks/useDependencies.js";
+import { useDependencies } from "../../framework/hooks/use-dependencies.js";
 import { resolveReference } from "../../framework/reference.js";
 
 export function getCredentialExpression(type: SdkCredentialType): string {

package/src/modular/type-expressions/get-model-expression.ts

@@ -9,7 +9,7 @@ import {
   SdkModelType,
   SdkServiceResponseHeader,
 } from "@azure-tools/typespec-client-generator-core";
-import { useContext } from "../../contextManager.js";
+import { useContext } from "../../context-manager.js";
 import { resolveReference } from "../../framework/reference.js";
 import { refkey } from "../../framework/refkey.js";
 import { SdkContext } from "../../utils/interfaces.js";

package/src/rlc-common/build-client-definitions.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as path from "path";
+import {
+  CallSignatureDeclarationStructure,
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  Project,
+  SourceFile,
+  StructureKind,
+  Writers,
+} from "ts-morph";
+
+import { REST_CLIENT_RESERVED } from "./build-method-shortcuts.js";
+import { getImportSpecifier } from "./helpers/imports-util.js";
+import { getClientName, getImportModuleName } from "./helpers/name-constructors.js";
+import { CasingConvention, NameType, normalizeName, pascalCase } from "./helpers/name-utils.js";
+import {
+  buildMethodDefinitions,
+  getGeneratedWrapperTypes,
+  getPathParamDefinitions,
+} from "./helpers/operation-helpers.js";
+import { generateMethodShortcuts } from "./helpers/shortcut-methods.js";
+import { PathMetadata, Paths, RLCModel } from "./interfaces.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, "\\}")
+          .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());
+}