@azure-tools/typespec-ts 0.49.0 → 0.49.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.49.0",
+  "version": "0.49.1",
   "description": "An experimental TypeSpec emitter for TypeScript RLC",
   "main": "dist/src/index.js",
   "type": "module",
@@ -18,15 +18,15 @@
   "license": "MIT",
   "devDependencies": {
     "@azure-rest/core-client": "^2.3.1",
-    "@typespec/http-specs": "0.1.0-alpha.32-dev.1",
-    "@typespec/spector": "0.1.0-alpha.23-dev.1",
+    "@typespec/http-specs": "0.1.0-alpha.33-dev.0",
+    "@typespec/spector": "0.1.0-alpha.24-dev.0",
     "@typespec/spec-api": "0.1.0-alpha.13-dev.0",
-    "@typespec/tspd": "0.73.3",
-    "@azure-tools/azure-http-specs": "0.1.0-alpha.37-dev.1",
-    "@azure-tools/typespec-autorest": "^0.64.0",
-    "@azure-tools/typespec-azure-core": "^0.64.0",
-    "@azure-tools/typespec-azure-resource-manager": "^0.64.0",
-    "@azure-tools/typespec-client-generator-core": "^0.64.4",
+    "@typespec/tspd": "0.74.0",
+    "@azure-tools/azure-http-specs": "0.1.0-alpha.38-dev.2",
+    "@azure-tools/typespec-autorest": "^0.65.0",
+    "@azure-tools/typespec-azure-core": "^0.65.0",
+    "@azure-tools/typespec-azure-resource-manager": "^0.65.0",
+    "@azure-tools/typespec-client-generator-core": "^0.65.1",
     "@azure/abort-controller": "^2.1.2",
     "@azure/core-auth": "^1.6.0",
     "@azure/core-lro": "^3.1.0",
@@ -40,12 +40,12 @@
     "@types/mocha": "^10.0.6",
     "@typescript-eslint/eslint-plugin": "^8.28.0",
     "@typescript-eslint/parser": "^8.28.0",
-    "@typespec/compiler": "^1.8.0",
-    "@typespec/http": "^1.8.0",
-    "@typespec/openapi": "^1.8.0",
-    "@typespec/rest": "^0.78.0",
+    "@typespec/compiler": "^1.9.0",
+    "@typespec/http": "^1.9.0",
+    "@typespec/openapi": "^1.9.0",
+    "@typespec/rest": "^0.79.0",
     "@typespec/ts-http-runtime": "^0.1.0",
-    "@typespec/versioning": "^0.78.0",
+    "@typespec/versioning": "^0.79.0",
     "chai": "^4.3.6",
     "chalk": "^4.0.0",
     "cross-env": "^7.0.3",
@@ -64,16 +64,16 @@
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {
-    "@azure-tools/typespec-azure-core": "^0.64.0",
-    "@azure-tools/typespec-client-generator-core": "^0.64.4",
-    "@typespec/compiler": "^1.8.0",
-    "@typespec/http": "^1.8.0",
-    "@typespec/rest": "^0.78.0",
-    "@typespec/versioning": "^0.78.0",
-    "@typespec/xml": "^0.78.0"
+    "@azure-tools/typespec-azure-core": "^0.65.0",
+    "@azure-tools/typespec-client-generator-core": "^0.65.1",
+    "@typespec/compiler": "^1.9.0",
+    "@typespec/http": "^1.9.0",
+    "@typespec/rest": "^0.79.0",
+    "@typespec/versioning": "^0.79.0",
+    "@typespec/xml": "^0.79.0"
   },
   "dependencies": {
-    "@azure-tools/rlc-common": "^0.49.0",
+    "@azure-tools/rlc-common": "^0.49.1",
     "fast-xml-parser": "^4.5.0",
     "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",

package/src/framework/hooks/binder.ts

@@ -15,6 +15,7 @@ import {
 } from "../load-static-helpers.js";
 import path from "path/posix";
 import { normalizePath } from "@typespec/compiler";
+import { generateLocallyUniqueName } from "../../modular/helpers/namingHelpers.js";
 
 export interface DeclarationInfo {
   name: string;
@@ -96,7 +97,7 @@ class BinderImp implements Binder {
   ): string {
     const existingNamesInFile =
       this.symbolsBySourceFile.get(sourceFile) ?? new Set<string>();
-    return this.generateLocallyUniqueName(name, existingNamesInFile);
+    return generateLocallyUniqueName(name, existingNamesInFile);
   }
 
   /**
@@ -113,33 +114,22 @@ class BinderImp implements Binder {
       .flatMap((i) => i.namedImports as ImportSpecifierStructure[])
       .map((i) => i.alias ?? i.name);
 
+    // Also check actual imports already added to the source file (e.g., manual imports)
+    const actualImports = sourceFile
+      .getImportDeclarations()
+      .flatMap((imp) => imp.getNamedImports())
+      .map(
+        (namedImp) => namedImp.getAliasNode()?.getText() ?? namedImp.getName()
+      );
+
     const existingDeclarations =
       this.symbolsBySourceFile.get(sourceFile) ?? new Set<string>();
-    return this.generateLocallyUniqueName(
+    return generateLocallyUniqueName(
       name,
-      new Set([...existingImports, ...existingDeclarations])
+      new Set([...existingImports, ...actualImports, ...existingDeclarations])
     );
   }
 
-  /**
-   * Generates a locally unique name within a set of existing names.
-   * @param name - The base name.
-   * @param existingNames - A set of names already in use.
-   * @returns A unique name not present in the existing names set.
-   */
-  private generateLocallyUniqueName(
-    name: string,
-    existingNames: Set<string>
-  ): string {
-    let uniqueName = name;
-    let counter = 1;
-    while (existingNames.has(uniqueName)) {
-      uniqueName = `${name}_${counter}`;
-      counter++;
-    }
-    return uniqueName;
-  }
-
   /**
    * Resolves a reference to a declaration.
    *  If a declaration is not ready yet, a placeholder is added to the source file.

package/src/index.ts

@@ -82,6 +82,7 @@ import { buildRestorePoller } from "./modular/buildRestorePoller.js";
 import { buildSubpathIndexFile } from "./modular/buildSubpathIndex.js";
 import {
   createSdkContext,
+  listAllServiceNamespaces,
   SdkClientType,
   SdkServiceOperation
 } from "@azure-tools/typespec-client-generator-core";
@@ -90,7 +91,11 @@ import { emitLoggerFile } from "./modular/emitLoggerFile.js";
 import { emitTypes } from "./modular/emitModels.js";
 import { existsSync } from "fs";
 import { getModuleExports } from "./modular/buildProjectFiles.js";
-import { getClientHierarchyMap, getRLCClients } from "./utils/clientUtils.js";
+import {
+  getClientHierarchyMap,
+  getRLCClients,
+  getModularClientOptions
+} from "./utils/clientUtils.js";
 import { join } from "path";
 import { loadStaticHelpers } from "./framework/load-static-helpers.js";
 import { packageUsesXmlSerialization } from "./modular/serialization/buildXmlSerializerFunction.js";
@@ -192,6 +197,7 @@ export async function $onEmit(context: EmitContext) {
     const generationPathDetail: GenerationDirDetail =
       await calculateGenerationDir();
     dpgContext.generationPathDetail = generationPathDetail;
+    dpgContext.allServiceNamespaces = listAllServiceNamespaces(dpgContext);
     const options: RLCOptions = transformRLCOptions(emitterOptions, dpgContext);
     emitterOptions["is-modular-library"] = options.isModularLibrary;
     emitterOptions["generate-sample"] = options.generateSample;
@@ -261,9 +267,7 @@ export async function $onEmit(context: EmitContext) {
     for (const client of clients) {
       const rlcModels = await transformRLCModel(client, dpgContext);
       rlcCodeModels.push(rlcModels);
-      const serviceName = Array.isArray(client.service)
-        ? (client.service[0]?.name ?? "Unknown")
-        : client.service.name;
+      const serviceName = client.services[0]?.name ?? "Unknown";
       serviceNameToRlcModelsMap.set(serviceName, rlcModels);
       needUnexpectedHelper.set(
         getClientName(rlcModels),
@@ -317,7 +321,6 @@ export async function $onEmit(context: EmitContext) {
       }
     );
 
-    const isMultiClients = dpgContext.sdkPackage.clients.length > 1;
     emitTypes(dpgContext, { sourceRoot: modularSourcesRoot });
     buildSubpathIndexFile(modularEmitterOptions, "models", undefined, {
       recursive: true
@@ -351,7 +354,9 @@ export async function $onEmit(context: EmitContext) {
         exportIndex: true,
         interfaceOnly: true
       });
-      if (isMultiClients) {
+      const { subfolder } = getModularClientOptions(subClient);
+      // Generate index file for clients with subfolders (multi-client scenarios and nested clients)
+      if (subfolder) {
         buildSubClientIndexFile(dpgContext, subClient, modularEmitterOptions);
       }
       buildRootIndex(
@@ -395,14 +400,16 @@ export async function $onEmit(context: EmitContext) {
   }
 
   function buildMetadataJson() {
-    const apiVersion = dpgContext.sdkPackage.metadata.apiVersion;
+    const apiVersions = dpgContext.sdkPackage.metadata.apiVersions;
     const emitterVersion = getTypespecTsVersion(context);
-    if (apiVersion === undefined && emitterVersion === undefined) {
+    if (apiVersions === undefined && emitterVersion === undefined) {
       return;
     }
     const content: Metadata = {};
-    if (apiVersion !== undefined) {
-      content.apiVersion = apiVersion;
+    if (apiVersions !== undefined && apiVersions.size > 0) {
+      // Use the first/latest API version if multiple are available
+      const firstVersion = Array.from(apiVersions.values())[0];
+      content.apiVersion = firstVersion;
     }
     if (emitterVersion !== undefined) {
       content.emitterVersion = emitterVersion;

package/src/lib.ts

@@ -15,6 +15,13 @@ import {
 import { Options } from "prettier";
 
 export interface EmitterOptions {
+  /**
+   * Indicates whether to include response headers in the generated response type for modular operations.
+   * When set to true, modular operation responses with model or void bodies will have their headers
+   * represented as properties on the response type. Other SDK styles and response shapes are not
+   * currently affected by this option.
+   */
+  "include-headers-in-response"?: boolean;
   "include-shortcuts"?: boolean;
   "multi-client"?: boolean;
   batch?: any[];
@@ -71,12 +78,19 @@ export interface EmitterOptions {
   "default-value-object"?: boolean;
   //TODO should remove this after finish the release tool test
   "should-use-pnpm-dep"?: boolean;
+  "ignore-nullable-on-optional"?: boolean;
 }
 
 export const RLCOptionsSchema: JSONSchemaType<EmitterOptions> = {
   type: "object",
   additionalProperties: true,
   properties: {
+    "include-headers-in-response": {
+      type: "boolean",
+      nullable: true,
+      description:
+        "This option is used to indicate whether to include response headers in the generated response type. When set to true, the generated response type will include response headers as properties."
+    },
     "include-shortcuts": {
       type: "boolean",
       nullable: true,
@@ -343,6 +357,12 @@ export const RLCOptionsSchema: JSONSchemaType<EmitterOptions> = {
       type: "boolean",
       nullable: true,
       description: "Internal option for test."
+    },
+    "ignore-nullable-on-optional": {
+      type: "boolean",
+      nullable: true,
+      description:
+        "If an optional property is also marked as nullable, it will be treated as just optional. Defaults to `true` for Azure services."
     }
   },
   required: []

package/src/modular/buildOperations.ts

@@ -7,6 +7,7 @@ import {
 } from "ts-morph";
 import {
   getDeserializePrivateFunction,
+  getDeserializeHeadersPrivateFunction,
   getExpectedStatuses,
   getOperationFunction,
   getOperationOptionsName,
@@ -85,16 +86,23 @@ export function buildOperationFiles(
       const sendOperationDeclaration = getSendPrivateFunction(
         dpgContext,
         [prefixes, op],
-        clientType
+        clientType,
+        client
       );
       const deserializeOperationDeclaration = getDeserializePrivateFunction(
         dpgContext,
         op
       );
-      operationGroupFile.addFunctions([
+      const deserializeHeadersDeclaration =
+        getDeserializeHeadersPrivateFunction(dpgContext, op);
+      const functionsToAdd = [
         sendOperationDeclaration,
         deserializeOperationDeclaration
-      ]);
+      ];
+      if (deserializeHeadersDeclaration) {
+        functionsToAdd.push(deserializeHeadersDeclaration);
+      }
+      operationGroupFile.addFunctions(functionsToAdd);
       addDeclaration(
         operationGroupFile,
         operationDeclaration,
@@ -191,7 +199,7 @@ export function buildOperationOptions(
         return {
           docs: getDocsFromDescription(p.doc),
           hasQuestionToken: true,
-          type: getTypeExpression(context, p.type),
+          type: getTypeExpression(context, p.type, { isOptional: true }),
           name: normalizeName(p.name, NameType.Parameter)
         };
       })

package/src/modular/buildProjectFiles.ts

@@ -35,23 +35,26 @@ function buildExportsForMultiClient(
     delete packageInfo.exports["./api"];
   }
   if (emitterOptions.options.hierarchyClient) {
-    for (const flattenedClient of clientMap) {
-      const { subfolder } = getModularClientOptions(flattenedClient);
-      const client = flattenedClient[1];
-      const methodMap = getMethodHierarchiesMap(context, client);
-      for (const [prefixKey, _] of methodMap) {
-        const prefixes = prefixKey.split("/");
-        if (prefixKey === "") {
-          continue;
+    // TODO: support api subpath exports for multi-service. Skip for now. https://github.com/Azure/autorest.typescript/issues/3717
+    if (!emitterOptions.options.isMultiService) {
+      for (const flattenedClient of clientMap) {
+        const { subfolder } = getModularClientOptions(flattenedClient);
+        const client = flattenedClient[1];
+        const methodMap = getMethodHierarchiesMap(context, client);
+        for (const [prefixKey, _] of methodMap) {
+          const prefixes = prefixKey.split("/");
+          if (prefixKey === "") {
+            continue;
+          }
+          const subApiPath = `api/${getClassicalLayerPrefix(
+            prefixes,
+            NameType.File,
+            "/"
+          )}`;
+          packageInfo.exports[
+            `./${subfolder ? subfolder + "/" : ""}${subApiPath}`
+          ] = `src/${subfolder ? subfolder + "/" : ""}${subApiPath}/index.ts`;
         }
-        const subApiPath = `api/${getClassicalLayerPrefix(
-          prefixes,
-          NameType.File,
-          "/"
-        )}`;
-        packageInfo.exports[
-          `./${subfolder ? subfolder + "/" : ""}${subApiPath}`
-        ] = `src/${subfolder ? subfolder + "/" : ""}${subApiPath}/index.ts`;
       }
     }
     delete packageInfo.exports["./models"];

package/src/modular/emitModels.ts

@@ -35,7 +35,8 @@ import {
 } from "@azure-tools/typespec-client-generator-core";
 import {
   getExternalModel,
-  getModelExpression
+  getModelExpression,
+  getMultipartFileTypeExpression
 } from "./type-expressions/get-model-expression.js";
 
 import { SdkContext } from "../utils/interfaces.js";
@@ -51,6 +52,8 @@ import {
 import {
   buildXmlModelSerializer,
   buildXmlModelDeserializer,
+  buildXmlObjectModelSerializer,
+  buildXmlObjectModelDeserializer,
   hasXmlSerialization
 } from "./serialization/buildXmlSerializerFunction.js";
 import path from "path";
@@ -75,8 +78,6 @@ import {
   flattenPropertyModelMap,
   getAllOperationsFromClient
 } from "../framework/hooks/sdkTypes.js";
-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";
@@ -216,6 +217,10 @@ function emitType(context: SdkContext, type: SdkType, sourceFile: SourceFile) {
       return;
     }
     const apiVersionEnumOnly = type.usage === UsageFlags.ApiVersionEnum;
+    // Skip known api version enums for multi-service scenarios as users are not allowed to set api versions
+    if (apiVersionEnumOnly && context.rlcOptions?.isMultiService) {
+      return;
+    }
     const inputUsage = (type.usage & UsageFlags.Input) === UsageFlags.Input;
     const outputUsage = (type.usage & UsageFlags.Output) === UsageFlags.Output;
     const exceptionUsage =
@@ -266,6 +271,10 @@ function emitType(context: SdkContext, type: SdkType, sourceFile: SourceFile) {
 }
 
 export function getApiVersionEnum(context: SdkContext) {
+  // Skip api version enum for multi-service scenarios since each service may have different versions
+  if (context.rlcOptions?.isMultiService) {
+    return;
+  }
   const apiVersionEnum = context.sdkPackage.enums.find(
     (e) => e.usage === UsageFlags.ApiVersionEnum
   );
@@ -293,9 +302,6 @@ export function getModelNamespaces(
   context: SdkContext,
   model: SdkType
 ): string[] {
-  const deepestNamespace = getNamespaceFullName(
-    listAllServiceNamespaces(context)[0]!
-  );
   if (
     model.kind === "model" ||
     model.kind === "enum" ||
@@ -312,6 +318,14 @@ export function getModelNamespaces(
       return [];
     }
     const segments = model.namespace.split(".");
+    // Keep full namespace segments if multiple services are present because there isn't a root namespace to trim
+    if (context.rlcOptions?.isMultiService) {
+      return segments;
+    }
+
+    const allServiceNamespaces =
+      context.allServiceNamespaces ?? listAllServiceNamespaces(context);
+    const deepestNamespace = getNamespaceFullName(allServiceNamespaces[0]!);
     const rootNamespace = deepestNamespace.split(".") ?? [];
     if (segments.length > rootNamespace.length) {
       while (segments[0] === rootNamespace[0]) {
@@ -371,6 +385,14 @@ function addSerializationFunctions(
   if (typeOrProperty.kind === "model" && hasXmlSerialization(typeOrProperty)) {
     const xmlSerializerRefKey = refkey(typeOrProperty, "xmlSerializer");
     const xmlDeserializerRefKey = refkey(typeOrProperty, "xmlDeserializer");
+    const xmlObjectSerializerRefKey = refkey(
+      typeOrProperty,
+      "xmlObjectSerializer"
+    );
+    const xmlObjectDeserializerRefKey = refkey(
+      typeOrProperty,
+      "xmlObjectDeserializer"
+    );
 
     const xmlSerializationFunction = buildXmlModelSerializer(
       context,
@@ -385,6 +407,24 @@ function addSerializationFunctions(
       addDeclaration(sourceFile, xmlSerializationFunction, xmlSerializerRefKey);
     }
 
+    // Also generate XML object serializer for nested object serialization
+    const xmlObjectSerializationFunction = buildXmlObjectModelSerializer(
+      context,
+      typeOrProperty,
+      options
+    );
+    if (
+      xmlObjectSerializationFunction &&
+      typeof xmlObjectSerializationFunction !== "string" &&
+      xmlObjectSerializationFunction.name
+    ) {
+      addDeclaration(
+        sourceFile,
+        xmlObjectSerializationFunction,
+        xmlObjectSerializerRefKey
+      );
+    }
+
     const xmlDeserializationFunction = buildXmlModelDeserializer(
       context,
       typeOrProperty,
@@ -401,6 +441,24 @@ function addSerializationFunctions(
         xmlDeserializerRefKey
       );
     }
+
+    // Also generate XML object deserializer for nested object deserialization
+    const xmlObjectDeserializationFunction = buildXmlObjectModelDeserializer(
+      context,
+      typeOrProperty,
+      options
+    );
+    if (
+      xmlObjectDeserializationFunction &&
+      typeof xmlObjectDeserializationFunction !== "string" &&
+      xmlObjectDeserializationFunction.name
+    ) {
+      addDeclaration(
+        sourceFile,
+        xmlObjectDeserializationFunction,
+        xmlObjectDeserializerRefKey
+      );
+    }
   }
 }
 
@@ -777,45 +835,15 @@ function buildModelProperty(
       .join(" | ");
   }
   // eslint-disable-next-line
-  else if (property.kind === "property" && property.isMultipartFileInput) {
-    // eslint-disable-next-line
-    const multipartOptions = property.multipartOptions;
-    typeExpression = "{";
-    typeExpression += `contents: ${resolveReference(MultipartHelpers.FileContents)};`;
-
-    const isContentTypeOptional =
-      multipartOptions?.contentType === undefined ||
-      multipartOptions.contentType.optional ||
-      multipartOptions.defaultContentTypes.length > 0;
-    const isFilenameOptional =
-      multipartOptions?.filename === undefined ||
-      multipartOptions.filename.optional;
-
-    const contentTypeType = multipartOptions?.contentType
-      ? getTypeExpression(context, multipartOptions.contentType.type)
-      : "string";
-    const filenameType = multipartOptions?.filename
-      ? getTypeExpression(context, multipartOptions.filename.type)
-      : "string";
-
-    typeExpression += `contentType${isContentTypeOptional ? "?" : ""}: ${contentTypeType};`;
-    typeExpression += `filename${isFilenameOptional ? "?" : ""}: ${filenameType};`;
-
-    typeExpression += "}";
-
-    if (isContentTypeOptional && isFilenameOptional) {
-      // Allow passing content directly if both filename and content type are optional
-      typeExpression = `(${resolveReference(MultipartHelpers.FileContents)}) | ${typeExpression}`;
-    } else {
-      // If either one is required, still accept File at the top level since it requires a filename
-      typeExpression = `File | ${typeExpression}`;
-    }
-
-    if (property.type.kind === "array") {
-      typeExpression = `Array<${typeExpression}>`;
-    }
+  else if (
+    property.kind === "property" &&
+    property.serializationOptions.multipart?.isFilePart
+  ) {
+    typeExpression = getMultipartFileTypeExpression(context, property);
   } else {
-    typeExpression = getTypeExpression(context, property.type);
+    typeExpression = getTypeExpression(context, property.type, {
+      isOptional: property.optional
+    });
   }
 
   const propertyStructure: PropertySignatureStructure = {

package/src/modular/emitSamples.ts

@@ -11,7 +11,9 @@ import {
   SdkHttpParameterExampleValue,
   SdkServiceOperation,
   SdkExampleValue,
-  SdkClientInitializationType
+  SdkClientInitializationType,
+  SdkModelPropertyType,
+  isReadOnly
 } from "@azure-tools/typespec-client-generator-core";
 import {
   isAzurePackage,
@@ -449,6 +451,10 @@ function prepareExampleParameters(
         if (!propExample) {
           continue;
         }
+        // Skip readonly properties as they cannot be set by users
+        if (isReadOnly(prop as SdkModelPropertyType)) {
+          continue;
+        }
         result.push(
           prepareExampleValue(
             dpgContext,
@@ -597,6 +603,10 @@ function getParameterValue(
         if (propValue === undefined || propValue === null) {
           continue;
         }
+        // Skip readonly properties as they cannot be set by users
+        if (property && isReadOnly(property as SdkModelPropertyType)) {
+          continue;
+        }
         let propRetValue;
 
         if (

package/src/modular/helpers/clientHelpers.ts

@@ -105,6 +105,9 @@ export function getClientParameters(
   const skipMethodParam = (p: SdkParameter) => p.kind !== "method";
   const armSpecific = (p: SdkParameter) =>
     !(p.kind === "endpoint" && dpgContext.arm);
+  // Skip apiVersion parameter when it's multi-service (each service has its own default apiVersion)
+  const skipApiVersionOnMultiService = (p: SdkParameter) =>
+    !(dpgContext.rlcOptions?.isMultiService && p.isApiVersionParam);
   const filters = [
     options.requiredOnly ? isRequired : undefined,
     dpgContext.rlcOptions?.addCredentials === false
@@ -112,7 +115,8 @@ export function getClientParameters(
       : undefined,
     options.optionalOnly ? isOptional : undefined,
     options.onClientOnly ? skipMethodParam : undefined,
-    options.skipArmSpecific ? undefined : armSpecific
+    options.skipArmSpecific ? undefined : armSpecific,
+    skipApiVersionOnMultiService
   ];
   const params = clientParams.filter((p) =>
     filters.every((filter) => !filter || filter(p))

package/src/modular/helpers/namingHelpers.ts

@@ -73,3 +73,22 @@ export function getClassicalLayerPrefix(
 export function isDefined<T>(thing: T | undefined | null): thing is T {
   return typeof thing !== "undefined" && thing !== null;
 }
+
+/**
+ * Generates a locally unique name within a set of existing names.
+ * @param name - The base name.
+ * @param existingNames - A set of names already in use.
+ * @returns A unique name not present in the existing names set.
+ */
+export function generateLocallyUniqueName(
+  name: string,
+  existingNames: Set<string>
+): string {
+  let uniqueName = name;
+  let counter = 1;
+  while (existingNames.has(uniqueName)) {
+    uniqueName = `${name}_${counter}`;
+    counter++;
+  }
+  return uniqueName;
+}