@azure-tools/typespec-ts 0.46.1 → 0.47.0-alpha.20251208.1

package/src/modular/buildRootIndex.ts

@@ -10,7 +10,6 @@ import {
 } from "./static-helpers-metadata.js";
 import {
   SdkClientType,
-  SdkContext,
   SdkServiceOperation
 } from "@azure-tools/typespec-client-generator-core";
 import { getModularClientOptions } from "../utils/clientUtils.js";
@@ -19,6 +18,8 @@ import { join } from "path/posix";
 import { useContext } from "../contextManager.js";
 import { reportDiagnostic } from "../lib.js";
 import { NoTarget } from "@typespec/compiler";
+import { isLroOnlyOperation } from "./helpers/operationHelpers.js";
+import { SdkContext } from "../utils/interfaces.js";
 
 export function buildRootIndex(
   context: SdkContext,
@@ -55,6 +56,14 @@ export function buildRootIndex(
   }
 
   exportClassicalClient(client, rootIndexFile, subfolder ?? "");
+  exportSimplePollerLike(
+    context,
+    clientMap,
+    rootIndexFile,
+    project,
+    srcPath,
+    subfolder
+  );
   exportRestoreHelpers(
     rootIndexFile,
     project,
@@ -188,6 +197,41 @@ function addExportsToRootIndexFile(
   }
 }
 
+function exportSimplePollerLike(
+  context: SdkContext,
+  clientMap: [string[], SdkClientType<SdkServiceOperation>],
+  indexFile: SourceFile,
+  project: Project,
+  srcPath: string,
+  subfolder: string = "",
+  isTopLevel: boolean = false
+) {
+  const [_, client] = clientMap;
+
+  const methodMap = getMethodHierarchiesMap(context, client);
+  const hasLro = Array.from(methodMap.values()).some((operations) => {
+    return operations.some(isLroOnlyOperation);
+  });
+  if (!hasLro || context.rlcOptions?.compatibilityLro !== true) {
+    return;
+  }
+  const helperFile = project.getSourceFile(
+    `${srcPath}/${
+      subfolder && subfolder !== "" ? subfolder + "/" : ""
+    }static-helpers/simplePollerHelpers.ts`
+  );
+  if (!helperFile) {
+    return;
+  }
+  const moduleSpecifier = `./${
+    isTopLevel && subfolder && subfolder !== "" ? subfolder + "/" : ""
+  }static-helpers/simplePollerHelpers.js`;
+  indexFile.addExportDeclaration({
+    moduleSpecifier,
+    namedExports: ["SimplePollerLike"]
+  });
+}
+
 function exportRestoreHelpers(
   indexFile: SourceFile,
   project: Project,
@@ -381,6 +425,14 @@ export function buildSubClientIndexFile(
   }
 
   exportClassicalClient(client, subClientIndexFile, subfolder ?? "", true);
+  exportSimplePollerLike(
+    context,
+    clientMap,
+    subClientIndexFile,
+    project,
+    srcPath,
+    subfolder
+  );
   exportRestoreHelpers(
     subClientIndexFile,
     project,

package/src/modular/emitModels.ts

@@ -40,8 +40,14 @@ import {
 
 import { SdkContext } from "../utils/interfaces.js";
 import { addDeclaration } from "../framework/declaration.js";
-import { buildModelDeserializer } from "./serialization/buildDeserializerFunction.js";
-import { buildModelSerializer } from "./serialization/buildSerializerFunction.js";
+import {
+  buildModelDeserializer,
+  buildPropertyDeserializer
+} from "./serialization/buildDeserializerFunction.js";
+import {
+  buildModelSerializer,
+  buildPropertySerializer
+} from "./serialization/buildSerializerFunction.js";
 import path from "path";
 import { refkey } from "../framework/refkey.js";
 import { useContext } from "../contextManager.js";
@@ -50,6 +56,7 @@ import { isAzureCoreErrorType } from "../utils/modelUtils.js";
 import { isExtensibleEnum } from "./type-expressions/get-enum-expression.js";
 import {
   getAllDiscriminatedValues,
+  getPropertyWithOverrides,
   isDiscriminatedUnion
 } from "./serialization/serializeUtils.js";
 import { reportDiagnostic } from "../lib.js";
@@ -60,6 +67,7 @@ import {
 } from "./type-expressions/get-type-expression.js";
 import {
   emitQueue,
+  flattenPropertyModelMap,
   getAllOperationsFromClient
 } from "../framework/hooks/sdkTypes.js";
 import { resolveReference } from "../framework/reference.js";
@@ -122,6 +130,14 @@ export function emitTypes(
     emitType(context, type, sourceFile);
   }
 
+  // Emit serialization/deserialization functions for flattened properties
+  for (const [property, _] of flattenPropertyModelMap) {
+    const namespaces = getModelNamespaces(context, property.type);
+    const filepath = getModelsPath(sourceRoot, namespaces);
+    sourceFile = outputProject.getSourceFile(filepath);
+    addSerializationFunctions(context, property, sourceFile!);
+  }
+
   const modelFiles = outputProject.getSourceFiles(
     sourceRoot + "/models/**/*.ts"
   );
@@ -310,36 +326,38 @@ export function getModelNamespaces(
 
 function addSerializationFunctions(
   context: SdkContext,
-  type: SdkType,
+  typeOrProperty: SdkType | SdkModelPropertyType,
   sourceFile: SourceFile,
-  skipDiscriminatedUnion = false
+  skipDiscriminatedUnionSuffix = false
 ) {
-  const serializationFunction = buildModelSerializer(
-    context,
-    type,
-    skipDiscriminatedUnion
-  );
+  const options = {
+    nameOnly: false,
+    skipDiscriminatedUnionSuffix
+  };
+  const serializationFunction =
+    typeOrProperty.kind === "property"
+      ? buildPropertySerializer(context, typeOrProperty, options)
+      : buildModelSerializer(context, typeOrProperty, options);
 
-  const serializerRefkey = refkey(type, "serializer");
-  const deserailizerRefKey = refkey(type, "deserializer");
+  const serializerRefKey = refkey(typeOrProperty, "serializer");
+  const deserializerRefKey = refkey(typeOrProperty, "deserializer");
   if (
     serializationFunction &&
     typeof serializationFunction !== "string" &&
     serializationFunction.name
   ) {
-    addDeclaration(sourceFile, serializationFunction, serializerRefkey);
+    addDeclaration(sourceFile, serializationFunction, serializerRefKey);
   }
-  const deserializationFunction = buildModelDeserializer(
-    context,
-    type,
-    skipDiscriminatedUnion
-  );
+  const deserializationFunction =
+    typeOrProperty.kind === "property"
+      ? buildPropertyDeserializer(context, typeOrProperty, options)
+      : buildModelDeserializer(context, typeOrProperty, options);
   if (
     deserializationFunction &&
     typeof deserializationFunction !== "string" &&
     deserializationFunction.name
   ) {
-    addDeclaration(sourceFile, deserializationFunction, deserailizerRefKey);
+    addDeclaration(sourceFile, deserializationFunction, deserializerRefKey);
   }
 }
 
@@ -474,16 +492,47 @@ function buildModelInterface(
   context: SdkContext,
   type: SdkModelType
 ): InterfaceDeclarationStructure {
+  const flattenPropertySet = new Set<SdkModelPropertyType>();
   const interfaceStructure = {
     kind: StructureKind.Interface,
     name: normalizeModelName(context, type, NameType.Interface, true),
     isExported: true,
     properties: type.properties
       .filter((p) => !isMetadata(context.program, p.__raw!))
+      .filter((p) => {
+        // filter out the flatten property to be processed later
+        if (p.flatten) {
+          flattenPropertySet.add(p);
+          return false;
+        }
+        return true;
+      })
       .map((p) => {
         return buildModelProperty(context, p, type);
       })
   } as InterfaceStructure;
+  for (const flatten of flattenPropertySet.keys()) {
+    if (flatten.type?.kind !== "model" || !flatten.type.properties) {
+      continue;
+    }
+    const conflictMap =
+      useContext("sdkTypes").flattenProperties.get(flatten)?.conflictMap;
+    const allProperties = getAllProperties(
+      context,
+      flatten.type,
+      getAllAncestors(flatten.type)
+    ).filter((p) => !isMetadata(context.program, p.__raw!));
+    interfaceStructure.properties!.push(
+      ...allProperties.map((p) => {
+        // when the flattened property is optional, all its child properties should be optional too
+        const property = getPropertyWithOverrides(p, {
+          allOptional: flatten.optional,
+          propertyRenames: conflictMap
+        });
+        return buildModelProperty(context, property, type);
+      })
+    );
+  }
 
   if (type.baseModel) {
     const parentReference = getModelExpression(context, type.baseModel, {
@@ -635,7 +684,7 @@ function buildModelPolymorphicType(context: SdkContext, type: SdkModelType) {
   }
   const typeDeclaration: TypeAliasDeclarationStructure = {
     kind: StructureKind.TypeAlias,
-    name: `${normalizeName(type.name, NameType.Interface)}Union`,
+    name: `${normalizeModelName(context, type, NameType.Interface, true)}Union`,
     isExported: true,
     type: directSubtypes
       .filter((p) => {
@@ -747,6 +796,7 @@ function buildModelProperty(
 export function visitPackageTypes(context: SdkContext) {
   const { sdkPackage } = context;
   emitQueue.clear();
+  flattenPropertyModelMap.clear();
   // Add all models in the package to the emit queue
   for (const model of sdkPackage.models) {
     visitType(context, model);
@@ -852,6 +902,9 @@ function visitType(context: SdkContext, type: SdkType | undefined) {
       if (!emitQueue.has(property.type)) {
         visitType(context, property.type);
       }
+      if (property.flatten && property.type.kind === "model") {
+        flattenPropertyModelMap.set(property, type);
+      }
     }
     if (type.discriminatedSubtypes) {
       for (const subType of Object.values(type.discriminatedSubtypes)) {

package/src/modular/emitSamples.ts

@@ -34,11 +34,13 @@ import {
 } from "../utils/credentialUtils.js";
 import {
   getMethodHierarchiesMap,
+  isTenantLevelOperation,
   ServiceOperation
 } from "../utils/operationUtil.js";
 import { getSubscriptionId } from "../transform/transfromRLCOptions.js";
 import { getClientParametersDeclaration } from "./helpers/clientHelpers.js";
 import { getOperationFunction } from "./helpers/operationHelpers.js";
+import { ModelOverrideOptions } from "./serialization/serializeUtils.js";
 
 /**
  * Interfaces for samples generations
@@ -272,6 +274,7 @@ function buildParameterValueMap(example: SdkHttpOperationExample) {
 }
 
 function prepareExampleValue(
+  context: SdkContext,
   name: string,
   value: SdkExampleValue | string,
   isOptional?: boolean,
@@ -279,7 +282,8 @@ function prepareExampleValue(
 ): ExampleValue {
   return {
     name: normalizeName(name, NameType.Parameter),
-    value: typeof value === "string" ? value : getParameterValue(value),
+    value:
+      typeof value === "string" ? value : getParameterValue(context, value),
     isOptional: Boolean(isOptional),
     onClient: Boolean(onClient)
   };
@@ -327,7 +331,8 @@ function prepareExampleParameters(
     result.push(credentialExampleValue);
   }
 
-  let subscriptionIdValue = `"00000000-0000-0000-0000-00000000000"`;
+  let subscriptionIdValue = `"00000000-0000-0000-0000-000000000000"`;
+  let isSubscriptionIdAdded = false;
   // required parameters
   for (const param of method.operation.parameters) {
     if (
@@ -339,6 +344,26 @@ function prepareExampleParameters(
     }
 
     const exampleValue = parameterMap[param.serializedName];
+
+    // Handle subscriptionId parameter separately for ARM clients
+    // Add it as long as it's the parameter of the method, even no example provided
+    if (param.name.toLowerCase() === "subscriptionid" && dpgContext.arm) {
+      isSubscriptionIdAdded = true;
+      if (exampleValue && exampleValue.value) {
+        subscriptionIdValue = getParameterValue(dpgContext, exampleValue.value);
+      }
+      result.push(
+        prepareExampleValue(
+          dpgContext,
+          param.name,
+          subscriptionIdValue,
+          param.optional,
+          param.onClient
+        )
+      );
+      continue;
+    }
+
     if (!exampleValue || !exampleValue.value) {
       // report diagnostic if required parameter is missing
       reportDiagnostic(dpgContext.program, {
@@ -352,16 +377,9 @@ function prepareExampleParameters(
       continue;
     }
 
-    if (
-      param.name.toLowerCase() === "subscriptionid" &&
-      dpgContext.arm &&
-      exampleValue
-    ) {
-      subscriptionIdValue = getParameterValue(exampleValue.value);
-      continue;
-    }
     result.push(
       prepareExampleValue(
+        dpgContext,
         exampleValue.parameter.name,
         exampleValue.value,
         param.optional,
@@ -369,12 +387,26 @@ function prepareExampleParameters(
       )
     );
   }
-  // add subscriptionId for ARM clients if ARM clients need it
-  if (dpgContext.arm && getSubscriptionId(dpgContext)) {
+
+  // If client-level subscriptionId is needed on the client for this method, then add it
+  // For example, Operations_List
+  if (
+    dpgContext.arm &&
+    getSubscriptionId(dpgContext) &&
+    !isSubscriptionIdAdded &&
+    !isTenantLevelOperation(method, topLevelClient)
+  ) {
     result.push(
-      prepareExampleValue("subscriptionId", subscriptionIdValue, false, true)
+      prepareExampleValue(
+        dpgContext,
+        "subscriptionId",
+        subscriptionIdValue,
+        false,
+        true
+      )
     );
   }
+
   // required/optional body parameters
   const bodyParam = method.operation.bodyParam;
   const bodySerializeName = bodyParam?.serializedName;
@@ -392,6 +424,7 @@ function prepareExampleParameters(
         }
         result.push(
           prepareExampleValue(
+            dpgContext,
             prop.name,
             propExample,
             prop.optional,
@@ -402,6 +435,7 @@ function prepareExampleParameters(
     } else {
       result.push(
         prepareExampleValue(
+          dpgContext,
           bodyParam.name,
           bodyExample.value,
           bodyParam.optional,
@@ -422,6 +456,7 @@ function prepareExampleParameters(
     .forEach((param) => {
       result.push(
         prepareExampleValue(
+          dpgContext,
           param.parameter.name,
           param.value,
           true,
@@ -471,7 +506,13 @@ function getCredentialExampleValue(
   return undefined;
 }
 
-function getParameterValue(value: SdkExampleValue): string {
+function getParameterValue(
+  context: SdkContext,
+  value: SdkExampleValue,
+  options?: {
+    overrides?: ModelOverrideOptions;
+  }
+): string {
   let retValue = `{} as any`;
   switch (value.kind) {
     case "string": {
@@ -509,21 +550,43 @@ function getParameterValue(value: SdkExampleValue): string {
       break;
     case "dict":
     case "model": {
-      const mapper = buildPropertyNameMapper(value.type);
+      const mapper = buildPropertyNameMapper(
+        context,
+        value.type,
+        options?.overrides
+      );
       const values = [];
       const additionalPropertiesValue =
         value.kind === "model" ? (value.additionalPropertiesValue ?? {}) : {};
       for (const propName in {
         ...value.value
       }) {
+        let property;
+        if (value.type.kind === "model") {
+          property = value.type.properties.find((p) => p.name === propName);
+        }
         const propValue = value.value[propName];
         if (propValue === undefined || propValue === null) {
           continue;
         }
-        const propRetValue =
-          `"${mapper.get(propName) ?? propName}": ` +
-          getParameterValue(propValue);
-        values.push(propRetValue);
+        let propRetValue;
+
+        if (property?.flatten && property.type.kind === "model") {
+          const paramValue = getParameterValue(context, propValue, {
+            overrides: {
+              propertyRenames:
+                useContext("sdkTypes").flattenProperties.get(property)
+                  ?.conflictMap
+            }
+          });
+          propRetValue =
+            paramValue.length > 2 ? paramValue.slice(1, -1) : undefined;
+        } else {
+          propRetValue =
+            `"${mapper.get(propName) ?? propName}": ` +
+            getParameterValue(context, propValue);
+        }
+        if (propRetValue) values.push(propRetValue);
       }
       const additionalBags = [];
       for (const propName in {
@@ -535,7 +598,7 @@ function getParameterValue(value: SdkExampleValue): string {
         }
         const propRetValue =
           `"${mapper.get(propName) ?? propName}": ` +
-          getParameterValue(propValue);
+          getParameterValue(context, propValue);
         additionalBags.push(propRetValue);
       }
       if (additionalBags.length > 0) {
@@ -551,7 +614,9 @@ function getParameterValue(value: SdkExampleValue): string {
       break;
     }
     case "array": {
-      const valuesArr = value.value.map(getParameterValue);
+      const valuesArr = value.value.map((item) =>
+        getParameterValue(context, item)
+      );
       retValue = `[${valuesArr.join(", ")}]`;
       break;
     }

package/src/modular/helpers/classicalOperationHelpers.ts

@@ -19,6 +19,21 @@ import { ServiceOperation } from "../../utils/operationUtil.js";
 import { refkey } from "../../framework/refkey.js";
 import { resolveReference } from "../../framework/reference.js";
 import { addDeclaration } from "../../framework/declaration.js";
+import { SimplePollerHelpers } from "../static-helpers-metadata.js";
+import { AzurePollingDependencies } from "../external-dependencies.js";
+
+interface OperationDeclarationInfo {
+  // the operation function
+  declaration: OptionalKind<FunctionDeclarationStructure>;
+  // the original operation name
+  oriName: string | undefined;
+  // the refkey of the operation declaration
+  declarationRefKey: string | undefined;
+  // the default is false
+  isLro?: boolean;
+  // only set when isLro is true
+  lroFinalReturnType?: string;
+}
 
 export function getClassicalOperation(
   dpgContext: SdkContext,
@@ -51,27 +66,25 @@ export function getClassicalOperation(
     });
   }
 
-  const operationMap = new Map<
-    OptionalKind<FunctionDeclarationStructure>,
-    string | undefined
-  >();
-  const operationKeyMap = new Map<
+  const operationDeclarationMap = new Map<
     OptionalKind<FunctionDeclarationStructure>,
-    string | undefined
+    OperationDeclarationInfo | undefined
   >();
   const operationDeclarations: OptionalKind<FunctionDeclarationStructure>[] =
     operations.map((operation) => {
-      const declarations = getOperationFunction(
+      const declaration = getOperationFunction(
         dpgContext,
         [prefixes, operation],
         rlcClientName
       );
-      operationMap.set(declarations, operation.oriName);
-      operationKeyMap.set(
-        declarations,
-        resolveReference(refkey(operation, "api"))
-      );
-      return declarations;
+      operationDeclarationMap.set(declaration, {
+        declaration,
+        oriName: operation.oriName,
+        declarationRefKey: resolveReference(refkey(operation, "api")),
+        isLro: declaration.isLro,
+        lroFinalReturnType: declaration.lroFinalReturnType
+      });
+      return declaration;
     });
 
   const interfaceNamePrefix = getClassicalLayerPrefix(
@@ -111,24 +124,52 @@ export function getClassicalOperation(
     }
   } else {
     operationDeclarations.forEach((d) => {
+      const operationInfo = operationDeclarationMap.get(d);
+      const paramStr = d.parameters
+        ?.filter((p) => p.name !== "context")
+        .map(
+          (p) =>
+            p.name +
+            (p.type?.toString().endsWith("operationOptions__") ||
+            p.hasQuestionToken
+              ? "?"
+              : "") +
+            ": " +
+            p.type
+        )
+        .join(",");
+      // add the operation method signature
       properties.push({
         kind: StructureKind.PropertySignature,
         name: getClassicalMethodName(d),
-        type: `(${d.parameters
-          ?.filter((p) => p.name !== "context")
-          .map(
-            (p) =>
-              p.name +
-              (p.type?.toString().endsWith("operationOptions__") ||
-              p.hasQuestionToken
-                ? "?"
-                : "") +
-              ": " +
-              p.type
-          )
-          .join(",")}) => ${d.returnType}`,
+        type: `(${paramStr}) => ${d.returnType}`,
         docs: d.docs
       });
+      // add LRO helper methods if applicable
+      if (dpgContext.rlcOptions?.compatibilityLro && operationInfo?.isLro) {
+        const operationStateReference = resolveReference(
+          AzurePollingDependencies.OperationState
+        );
+        const simplePollerLikeReference = resolveReference(
+          SimplePollerHelpers.SimplePollerLike
+        );
+        const returnType = operationInfo?.lroFinalReturnType ?? "void";
+        const beginName = `begin_${getClassicalMethodName(d)}`;
+        const beginAndWaitName = `${beginName}_andWait`;
+
+        properties.push({
+          kind: StructureKind.PropertySignature,
+          name: `${normalizeName(beginName, NameType.Method)}`,
+          type: `(${paramStr}) => Promise<${simplePollerLikeReference}<${operationStateReference}<${returnType}>, ${returnType}>>`,
+          docs: [`@deprecated use ${getClassicalMethodName(d)} instead`]
+        });
+        properties.push({
+          kind: StructureKind.PropertySignature,
+          name: `${normalizeName(beginAndWaitName, NameType.Method)}`,
+          type: `(${paramStr}) => Promise<${returnType}>`,
+          docs: [`@deprecated use ${getClassicalMethodName(d)} instead`]
+        });
+      }
     });
   }
   if (existInterface) {
@@ -168,7 +209,8 @@ export function getClassicalOperation(
       statements: `return {
         ${operationDeclarations
           .map((d) => {
-            return `${getClassicalMethodName(d)}: (${d.parameters
+            const operationInfo = operationDeclarationMap.get(d);
+            const classicalParamStr = d.parameters
               ?.filter((p) => p.name !== "context")
               .map(
                 (p) =>
@@ -180,12 +222,52 @@ export function getClassicalOperation(
                   ": " +
                   p.type
               )
-              .join(",")}) => ${operationKeyMap.get(d)}(${[
+              .join(",");
+            const apiParamStr = [
               "context",
               ...[
                 d.parameters?.map((p) => p.name).filter((p) => p !== "context")
               ]
-            ].join(",")})`;
+            ].join(",");
+            const ret = [
+              `${getClassicalMethodName(d)}: (${classicalParamStr}) => ${operationInfo?.declarationRefKey}(${
+                apiParamStr
+              })`
+            ];
+            // add LRO helper methods if applicable
+            if (
+              dpgContext.rlcOptions?.compatibilityLro &&
+              operationInfo?.isLro
+            ) {
+              const getSimplePollerReference = resolveReference(
+                SimplePollerHelpers.getSimplePoller
+              );
+              const beginName = `begin_${getClassicalMethodName(d)}`;
+              const beginAndWaitName = `${beginName}_andWait`;
+              ret.push(
+                `${normalizeName(
+                  beginName,
+                  NameType.Method
+                )}: async (${classicalParamStr}) => {
+                  const poller = ${operationInfo?.declarationRefKey}(${
+                    apiParamStr
+                  });
+                  await poller.submitted();
+                  return ${getSimplePollerReference}(poller);
+                }`
+              );
+              ret.push(
+                `${normalizeName(
+                  beginAndWaitName,
+                  NameType.Method
+                )}: async (${classicalParamStr}) => {
+                  return await ${operationInfo?.declarationRefKey}(${
+                    apiParamStr
+                  });
+                }`
+              );
+            }
+            return ret.join(",");
           })
           .join(",")}
       }`
@@ -280,7 +362,7 @@ export function getClassicalOperation(
     }
   ) {
     return normalizeName(
-      operationMap.get(declaration) ??
+      operationDeclarationMap.get(declaration)?.oriName ??
         declaration.propertyName ??
         declaration.name ??
         "FIXME",