@azure-tools/typespec-ts 0.44.0 → 0.44.1-alpha.20250926.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.44.0",
+  "version": "0.44.1-alpha.20250926.2",
   "description": "An experimental TypeSpec emitter for TypeScript RLC",
   "main": "dist/src/index.js",
   "type": "module",
@@ -22,11 +22,11 @@
     "@typespec/spector": "0.1.0-alpha.19-dev.0",
     "@typespec/spec-api": "0.1.0-alpha.10-dev.0",
     "@typespec/tspd": "0.72.1",
-    "@azure-tools/azure-http-specs": "0.1.0-alpha.29-dev.0",
-    "@azure-tools/typespec-autorest": "^0.60.0",
-    "@azure-tools/typespec-azure-core": "^0.60.0",
-    "@azure-tools/typespec-azure-resource-manager": "^0.60.0",
-    "@azure-tools/typespec-client-generator-core": "^0.60.0",
+    "@azure-tools/azure-http-specs": "0.1.0-alpha.30-dev.5",
+    "@azure-tools/typespec-autorest": "0.61.0-dev.1",
+    "@azure-tools/typespec-azure-core": "0.61.0-dev.6",
+    "@azure-tools/typespec-azure-resource-manager": "^0.60.1",
+    "@azure-tools/typespec-client-generator-core": "0.61.0-dev.10",
     "@azure/abort-controller": "^2.1.2",
     "@azure/core-auth": "^1.6.0",
     "@azure/core-lro": "^3.1.0",
@@ -69,7 +69,7 @@
   },
   "peerDependencies": {
     "@azure-tools/typespec-azure-core": "^0.60.0",
-    "@azure-tools/typespec-client-generator-core": "^0.60.0",
+    "@azure-tools/typespec-client-generator-core": "0.61.0-dev.10",
     "@typespec/compiler": "^1.4.0",
     "@typespec/http": "^1.4.0",
     "@typespec/rest": "^0.74.0",
@@ -77,7 +77,7 @@
     "@typespec/xml": "^0.74.0"
   },
   "dependencies": {
-    "@azure-tools/rlc-common": "^0.44.0",
+    "@azure-tools/rlc-common": "0.44.1-alpha.20250926.2",
     "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",
     "prettier": "^3.3.3",

package/src/index.ts

@@ -93,6 +93,7 @@ import { provideSdkTypes } from "./framework/hooks/sdkTypes.js";
 import { transformRLCModel } from "./transform/transform.js";
 import { transformRLCOptions } from "./transform/transfromRLCOptions.js";
 import { emitSamples } from "./modular/emitSamples.js";
+import { generateCrossLanguageDefinitionFile } from "./utils/crossLanguageDef.js";
 
 export * from "./lib.js";
 
@@ -374,9 +375,14 @@ export async function $onEmit(context: EmitContext) {
     console.timeEnd("onEmit: generate files");
     console.timeEnd("onEmit: generate modular sources");
   }
+
   interface Metadata {
     apiVersion?: string;
     emitterVersion?: string;
+    crossLanguageDefinitions?: {
+      CrossLanguagePackageId: string;
+      CrossLanguageDefinitionId: Record<string, string>;
+    };
   }
 
   function buildMetadataJson() {
@@ -392,11 +398,16 @@ export async function $onEmit(context: EmitContext) {
     if (emitterVersion !== undefined) {
       content.emitterVersion = emitterVersion;
     }
+    if (dpgContext.rlcOptions?.isModularLibrary) {
+      content.crossLanguageDefinitions =
+        generateCrossLanguageDefinitionFile(dpgContext);
+    }
     return {
       path: "metadata.json",
       content: JSON.stringify(content, null, 2)
     };
   }
+
   async function generateMetadataAndTest(context: SdkContext) {
     const project = useContext("outputProject");
     if (rlcCodeModels.length === 0 || !rlcCodeModels[0]) {

package/src/modular/emitModels.ts

@@ -51,7 +51,10 @@ import {
   isAzureCoreLroType
 } from "../utils/modelUtils.js";
 import { isExtensibleEnum } from "./type-expressions/get-enum-expression.js";
-import { isDiscriminatedUnion } from "./serialization/serializeUtils.js";
+import {
+  getAllDiscriminatedValues,
+  isDiscriminatedUnion
+} from "./serialization/serializeUtils.js";
 import { reportDiagnostic } from "../lib.js";
 import { getNamespaceFullName, NoTarget } from "@typespec/compiler";
 import {
@@ -66,6 +69,7 @@ import { resolveReference } from "../framework/reference.js";
 import { MultipartHelpers } from "./static-helpers-metadata.js";
 import { getAllAncestors } from "./helpers/operationHelpers.js";
 import { getAllProperties } from "./helpers/operationHelpers.js";
+import { getDirectSubtypes } from "./helpers/typeHelpers.js";
 
 type InterfaceStructure = OptionalKind<InterfaceDeclarationStructure> & {
   extends?: string[];
@@ -458,6 +462,9 @@ function emitEnumMember(
 
   if (member.doc) {
     memberStructure.docs = [member.doc];
+  } else {
+    // Provide default documentation using the enum value when no explicit doc exists
+    memberStructure.docs = [String(member.value)];
   }
 
   return memberStructure;
@@ -474,7 +481,7 @@ function buildModelInterface(
     properties: type.properties
       .filter((p) => !isMetadata(context.program, p.__raw!))
       .map((p) => {
-        return buildModelProperty(context, p);
+        return buildModelProperty(context, p, type);
       })
   } as InterfaceStructure;
 
@@ -621,17 +628,16 @@ export function normalizeModelName(
 }
 
 function buildModelPolymorphicType(context: SdkContext, type: SdkModelType) {
-  if (!type.discriminatedSubtypes) {
+  // Only include direct subtypes in this union
+  const directSubtypes = getDirectSubtypes(type);
+  if (directSubtypes.length === 0) {
     return undefined;
   }
-
-  const discriminatedSubtypes = Object.values(type.discriminatedSubtypes);
-
   const typeDeclaration: TypeAliasDeclarationStructure = {
     kind: StructureKind.TypeAlias,
     name: `${normalizeName(type.name, NameType.Interface)}Union`,
     isExported: true,
-    type: discriminatedSubtypes
+    type: directSubtypes
       .filter((p) => {
         return (
           p.usage !== undefined &&
@@ -652,7 +658,8 @@ function buildModelPolymorphicType(context: SdkContext, type: SdkModelType) {
 
 function buildModelProperty(
   context: SdkContext,
-  property: SdkModelPropertyType
+  property: SdkModelPropertyType,
+  model: SdkModelType
 ): PropertySignatureStructure {
   const normalizedPropName = normalizeModelPropertyName(context, property);
   if (
@@ -670,8 +677,18 @@ function buildModelProperty(
   }
 
   let typeExpression: string;
+  const allDiscriminatorValues = getAllDiscriminatedValues(model, property);
+
+  // We need refine the discriminator property if
+  // 1. it is discriminated union
+  // 2. it has other discriminator values except itself
+  if (isDiscriminatedUnion(model) && allDiscriminatorValues.length > 1) {
+    typeExpression = allDiscriminatorValues
+      .map((value) => `"${value}"`)
+      .join(" | ");
+  }
   // eslint-disable-next-line
-  if (property.kind === "property" && property.isMultipartFileInput) {
+  else if (property.kind === "property" && property.isMultipartFileInput) {
     // eslint-disable-next-line
     const multipartOptions = property.multipartOptions;
     typeExpression = "{";

package/src/modular/helpers/operationHelpers.ts

@@ -1051,15 +1051,21 @@ function getQueryParameters(
 
   for (const param of operationParameters) {
     if (param.kind === "query") {
-      parametersImplementation[param.kind].push({
-        paramMap: getParameterMap(dpgContext, {
-          ...param,
-          // TODO: remember to remove this hack once compiler gives us a name
-          // https://github.com/microsoft/typespec/issues/6743
-          serializedName: getUriTemplateQueryParamName(param.serializedName)
-        }),
-        param
-      });
+      // Check if this parameter still exists in the corresponding method params (after override)
+      if (
+        param.correspondingMethodParams &&
+        param.correspondingMethodParams.length > 0
+      ) {
+        parametersImplementation[param.kind].push({
+          paramMap: getParameterMap(dpgContext, {
+            ...param,
+            // TODO: remember to remove this hack once compiler gives us a name
+            // https://github.com/microsoft/typespec/issues/6743
+            serializedName: getUriTemplateQueryParamName(param.serializedName)
+          }),
+          param
+        });
+      }
     }
   }
 

package/src/modular/helpers/typeHelpers.ts

@@ -4,9 +4,20 @@ import {
   SdkCredentialParameter,
   SdkEndpointParameter,
   SdkMethodParameter,
+  SdkModelType,
   SdkType
 } from "@azure-tools/typespec-client-generator-core";
 
+export function getDirectSubtypes(type: SdkModelType) {
+  if (!type.discriminatedSubtypes) {
+    return [];
+  }
+  // Filter out subtypes that extend from other discriminated subtypes (hierarchical inheritance)
+  return Object.values(type.discriminatedSubtypes).filter(
+    (subtype) => subtype.baseModel === type
+  );
+}
+
 export function getAdditionalPropertiesType(
   type: SdkType | undefined
 ): SdkType | undefined {

package/src/modular/serialization/buildDeserializerFunction.ts

@@ -20,6 +20,7 @@ import {
 import { NameType, normalizeName } from "@azure-tools/rlc-common";
 import { isAzureCoreErrorType } from "../../utils/modelUtils.js";
 import {
+  getAllDiscriminatedValues,
   isDiscriminatedUnion,
   isSupportedSerializeType,
   ModelSerializeOptions
@@ -27,7 +28,10 @@ import {
 import { SerializationHelpers } from "../static-helpers-metadata.js";
 import { refkey } from "../../framework/refkey.js";
 import { resolveReference } from "../../framework/reference.js";
-import { getAdditionalPropertiesType } from "../helpers/typeHelpers.js";
+import {
+  getAdditionalPropertiesType,
+  getDirectSubtypes
+} from "../helpers/typeHelpers.js";
 
 export function buildModelDeserializer(
   context: SdkContext,
@@ -208,8 +212,8 @@ function buildDiscriminatedUnionDeserializer(
     NameType.Operation,
     true
   )}Deserializer`;
-  for (const key in type.discriminatedSubtypes) {
-    const subType = type.discriminatedSubtypes[key]!;
+  const directSubtypes = getDirectSubtypes(type);
+  for (const subType of directSubtypes) {
     if (
       !subType.usage ||
       (subType.usage !== undefined &&
@@ -217,7 +221,11 @@ function buildDiscriminatedUnionDeserializer(
     ) {
       continue;
     }
-    const discriminatedValue = subType.discriminatorValue!;
+    // get all discriminated values that is linked by this discriminator property
+    const discriminatedValues = getAllDiscriminatedValues(
+      subType,
+      type.discriminatorProperty
+    );
     const union = subType.discriminatedSubtypes ? "Union" : "";
     const subTypeName = `${normalizeName(subType.name, NameType.Interface, true)}${union}`;
     const subtypeDeserializerName = normalizeName(
@@ -226,8 +234,9 @@ function buildDiscriminatedUnionDeserializer(
       true
     );
 
+    const caseLabels = discriminatedValues.map((value) => `case "${value}":`);
     cases.push(`
-      case "${discriminatedValue}":
+      ${caseLabels.join("\n")}
         return ${subtypeDeserializerName}(item as ${subTypeName});
     `);
   }

package/src/modular/serialization/buildSerializerFunction.ts

@@ -22,6 +22,7 @@ import {
 import { NameType, normalizeName } from "@azure-tools/rlc-common";
 import { isAzureCoreErrorType } from "../../utils/modelUtils.js";
 import {
+  getAllDiscriminatedValues,
   isDiscriminatedUnion,
   isSupportedSerializeType,
   ModelSerializeOptions
@@ -33,7 +34,10 @@ import {
 import { resolveReference } from "../../framework/reference.js";
 import { isOrExtendsHttpFile } from "@typespec/http";
 import { refkey } from "../../framework/refkey.js";
-import { getAdditionalPropertiesType } from "../helpers/typeHelpers.js";
+import {
+  getAdditionalPropertiesType,
+  getDirectSubtypes
+} from "../helpers/typeHelpers.js";
 
 export function buildModelSerializer(
   context: SdkContext,
@@ -215,8 +219,8 @@ function buildDiscriminatedUnionSerializer(
     NameType.Operation,
     true
   )}Serializer`;
-  for (const key in type.discriminatedSubtypes) {
-    const subType = type.discriminatedSubtypes[key]!;
+  const directSubtypes = getDirectSubtypes(type);
+  for (const subType of directSubtypes) {
     if (
       !subType.usage ||
       (subType.usage !== undefined &&
@@ -224,7 +228,11 @@ function buildDiscriminatedUnionSerializer(
     ) {
       continue;
     }
-    const discriminatedValue = subType.discriminatorValue!;
+    // get all discriminated values that is linked by this discriminator property
+    const discriminatedValues = getAllDiscriminatedValues(
+      subType,
+      type.discriminatorProperty
+    );
     const union = subType.discriminatedSubtypes ? "Union" : "";
     const subTypeName = `${normalizeName(subType.name, NameType.Interface, true)}${union}`;
     const subtypeSerializerName = normalizeName(
@@ -233,8 +241,9 @@ function buildDiscriminatedUnionSerializer(
       true
     );
 
+    const caseLabels = discriminatedValues.map((value) => `case "${value}":`);
     cases.push(`
-      case "${discriminatedValue}":
+      ${caseLabels.join("\n")}
         return ${subtypeSerializerName}(item as ${subTypeName});
     `);
   }

package/src/modular/serialization/serializeUtils.ts

@@ -1,8 +1,48 @@
 import { getAllAncestors } from "../helpers/operationHelpers.js";
 import {
+  SdkModelPropertyType,
   SdkModelType,
   SdkType
 } from "@azure-tools/typespec-client-generator-core";
+import { getDirectSubtypes } from "../helpers/typeHelpers.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 (

package/src/transform/transformApiVersionInfo.ts

@@ -75,7 +75,8 @@ export function getOperationApiVersion(
     }
     const params = route.parameters.parameters.filter(
       (p) =>
-        (p.type === "query" || p.type === "path") && isApiVersion(dpgContext, p)
+        (p.type === "query" || p.type === "path") &&
+        isApiVersion(dpgContext, p.param)
     );
     params.map((p) => {
       const type = getSchemaForType(dpgContext, p.param.type, {

package/src/transform/transformParameters.ts

@@ -225,7 +225,7 @@ function transformQueryParameters(
     (p) =>
       p.type === "query" &&
       !(
-        isApiVersion(dpgContext, p) &&
+        isApiVersion(dpgContext, p.param) &&
         options.apiVersionInfo?.definedPosition === "query"
       )
   );

package/src/transform/transformPaths.ts

@@ -167,7 +167,7 @@ function hasRequiredOptions(
 
   const containsRequiredNonBodyParam = routeParameters.parameters
     .filter((parameter) => ["query", "header"].includes(parameter.type))
-    .filter((parameter) => !isApiVersion(dpgContext, parameter))
+    .filter((parameter) => !isApiVersion(dpgContext, parameter.param))
     .filter((parameter) => !!parameter.param)
     .some((parameter) => parameter.param.optional === false);
   return isRequiredBodyParam || containsRequiredNonBodyParam;

package/src/utils/crossLanguageDef.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { SdkContext } from "./interfaces.js";
+import { transformModularEmitterOptions } from "../modular/buildModularOptions.js";
+import { getMethodHierarchiesMap } from "./operationUtil.js";
+import { NameType, normalizeName } from "@azure-tools/rlc-common";
+
+export function generateCrossLanguageDefinitionFile(dpgContext: SdkContext): {
+  CrossLanguagePackageId: string;
+  CrossLanguageDefinitionId: Record<string, string>;
+} {
+  const modularSourcesRoot =
+    dpgContext.generationPathDetail?.modularSourcesDir ?? "src";
+  const emitterOptions = transformModularEmitterOptions(
+    dpgContext,
+    modularSourcesRoot,
+    {
+      casing: "camel"
+    }
+  );
+  const packageName =
+    emitterOptions.options?.packageDetails?.name ?? "package-name";
+  const CrossLanguageDefinitionId: Record<string, string> = {};
+
+  for (const model of dpgContext.sdkPackage.models) {
+    CrossLanguageDefinitionId[`${packageName}!${model.name}:interface`] =
+      model.crossLanguageDefinitionId;
+  }
+  for (const enm of dpgContext.sdkPackage.enums) {
+    CrossLanguageDefinitionId[`${packageName}!Known${enm.name}:enum`] =
+      enm.crossLanguageDefinitionId;
+  }
+  for (const union of dpgContext.sdkPackage.unions) {
+    CrossLanguageDefinitionId[`${packageName}!${union.name}:type`] =
+      union.crossLanguageDefinitionId;
+  }
+
+  for (const subClient of dpgContext.sdkPackage.clients) {
+    const clientName =
+      emitterOptions.options?.typespecTitleMap?.[subClient.name] ??
+      subClient.name;
+    const methodMap = getMethodHierarchiesMap(dpgContext, subClient);
+    for (const [prefixKey, operations] of methodMap) {
+      const prefixes = prefixKey.split("/");
+      if (prefixKey === "") {
+        for (const operation of operations) {
+          const { name } = operation;
+          const operationName = `${packageName}!${clientName}#${name}:member(1)`;
+          CrossLanguageDefinitionId[operationName] =
+            operation.crossLanguageDefinitionId;
+        }
+      } else {
+        // e,g., @azure/ai-client!ConnectionsOperations#getConnectionWithSecrets:member": "Azure.AI.Projects.Connections.getConnectionWithSecrets"
+        const rawGroupName = normalizeName(
+          prefixes[0] ?? "",
+          NameType.Interface
+        );
+        const propertyType = `${normalizeName(
+          rawGroupName,
+          NameType.OperationGroup
+        )}Operations`;
+        for (const operation of operations) {
+          const { name } = operation;
+          const operationName = `${packageName}!${propertyType}#${name}:member`;
+          CrossLanguageDefinitionId[operationName] =
+            operation.crossLanguageDefinitionId;
+        }
+      }
+    }
+  }
+
+  return {
+    CrossLanguagePackageId: dpgContext.sdkPackage.crossLanguagePackageId,
+    CrossLanguageDefinitionId
+  };
+}

package/src/utils/modelUtils.ts

@@ -79,10 +79,7 @@ import {
   getWireName,
   isApiVersion
 } from "@azure-tools/typespec-client-generator-core";
-import {
-  getPagedResult,
-  getUnionAsEnum
-} from "@azure-tools/typespec-azure-core";
+import { getUnionAsEnum } from "@azure-tools/typespec-azure-core";
 
 import { getModelNamespaceName } from "./namespaceUtils.js";
 import { reportDiagnostic } from "../lib.js";
@@ -924,7 +921,7 @@ function getModelName(dpgContext: SdkContext, model: Model) {
   // 4. check if this is a model with template arguments
   let name = model.name;
   if (model.templateMapper?.args) {
-    const isPage = getPagedResult(program, model);
+    // const isPage = getPagedResult(program, model);
     const templateTypeNames = model.templateMapper.args
       .map((arg) => (arg.entityKind === "Indeterminate" ? arg.type : arg))
       .map((arg: any) => {
@@ -944,10 +941,7 @@ function getModelName(dpgContext: SdkContext, model: Model) {
       })
       .filter((arg) => arg !== "")
       .join(" ");
-    name = normalizeName(
-      isPage ? `${templateTypeNames} List` : `${name} ${templateTypeNames}`,
-      NameType.Interface
-    );
+    name = normalizeName(`${name} ${templateTypeNames}`, NameType.Interface);
   }
   let fullNamespacePrefix = getModelNamespaceName(dpgContext, model.namespace!)
     .map((nsName) => {

package/src/utils/operationUtil.ts

@@ -13,11 +13,7 @@ import {
   ResponseMetadata,
   ResponseTypes
 } from "@azure-tools/rlc-common";
-import {
-  getLroMetadata,
-  getPagedResult,
-  PagedResultMetadata
-} from "@azure-tools/typespec-azure-core";
+import { getLroMetadata } from "@azure-tools/typespec-azure-core";
 import {
   getHttpOperationWithCache,
   getWireName,
@@ -34,7 +30,6 @@ import {
 } from "@azure-tools/typespec-client-generator-core";
 import {
   isList,
-  Model,
   ModelProperty,
   NoTarget,
   Operation,
@@ -392,19 +387,6 @@ export function extractPageDetails(
       nextLinkNames: [nextLinkNames],
       itemNames: [itemNames]
     };
-  } else {
-    // TODO: remember to remove this once Azure Paging is removed.
-    for (const response of operation.responses) {
-      const paged = extractPagedMetadataNested(program, response.type as Model);
-      if (paged) {
-        const nextLinkName = parseNextLinkName(paged) ?? "nextLink";
-        const itemName = parseItemName(paged) ?? "value";
-        return {
-          nextLinkNames: [nextLinkName],
-          itemNames: [itemName]
-        };
-      }
-    }
   }
   return undefined;
 }
@@ -470,36 +452,6 @@ export function hasPagingOperations(client: SdkClient, dpgContext: SdkContext) {
   return false;
 }
 
-export function extractPagedMetadataNested(
-  program: Program,
-  type: Model
-): PagedResultMetadata | undefined {
-  // This only works for `is Page<T>` not `extends Page<T>`.
-  let paged = getPagedResult(program, type);
-  if (paged) {
-    return paged;
-  }
-  if (type.baseModel) {
-    paged = getPagedResult(program, type.baseModel);
-  }
-  if (paged) {
-    return paged;
-  }
-  const templateArguments = type.templateMapper?.args;
-  if (templateArguments) {
-    for (const argument of templateArguments) {
-      const modelArgument = argument as Model;
-      if (modelArgument) {
-        paged = extractPagedMetadataNested(program, modelArgument);
-        if (paged) {
-          return paged;
-        }
-      }
-    }
-  }
-  return paged;
-}
-
 export function hasCollectionFormatInfo(
   paramType: string,
   paramFormat: string
@@ -626,17 +578,6 @@ export function isIgnoredHeaderParam(param: HttpOperationParameter) {
   );
 }
 
-export function parseNextLinkName(
-  paged: PagedResultMetadata
-): string | undefined {
-  return paged.nextLinkProperty?.name;
-}
-
-export function parseItemName(paged: PagedResultMetadata): string | undefined {
-  // TODO: support the nested item names
-  return (paged.itemsSegments ?? [])[0];
-}
-
 export type ServiceOperation = SdkServiceMethod<SdkHttpOperation> & {
   oriName?: string;
 };