@azure-tools/typespec-ts 0.50.0 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.50.0",
+  "version": "0.50.1",
   "description": "An experimental TypeSpec emitter for TypeScript RLC",
   "main": "dist/src/index.js",
   "type": "module",
@@ -73,7 +73,7 @@
     "@typespec/xml": "^0.79.0"
   },
   "dependencies": {
-    "@azure-tools/rlc-common": "^0.50.0",
+    "@azure-tools/rlc-common": "^0.50.1",
     "fast-xml-parser": "^4.5.0",
     "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",

package/src/index.ts

@@ -18,6 +18,7 @@ import {
   PollingHelpers,
   SerializationHelpers,
   SimplePollerHelpers,
+  StorageCompatHelpers,
   UrlTemplateHelpers,
   XmlHelpers
 } from "./modular/static-helpers-metadata.js";
@@ -37,6 +38,7 @@ import {
   buildPollingHelper,
   buildPaginateHelper as buildRLCPaginateHelper,
   buildReadmeFile,
+  hasClientNameChanged,
   updateReadmeFile,
   buildRecordedClientFile,
   buildResponseTypes,
@@ -51,6 +53,7 @@ import {
   buildTestNodeTsConfig,
   buildTestMainTsConfig,
   buildVitestConfig,
+  buildWarpConfig,
   getClientName,
   hasUnexpectedHelper,
   isAzurePackage,
@@ -105,6 +108,7 @@ import { transformRLCModel } from "./transform/transform.js";
 import { transformRLCOptions } from "./transform/transfromRLCOptions.js";
 import { emitSamples } from "./modular/emitSamples.js";
 import { generateCrossLanguageDefinitionFile } from "./utils/crossLanguageDef.js";
+import { getClassicalClientName } from "./modular/helpers/namingHelpers.js";
 
 export * from "./lib.js";
 
@@ -143,7 +147,8 @@ export async function $onEmit(context: EmitContext) {
       ...UrlTemplateHelpers,
       ...MultipartHelpers,
       ...CloudSettingHelpers,
-      ...XmlHelpers
+      ...XmlHelpers,
+      ...(rlcOptions.enableStorageCompat ? StorageCompatHelpers : {})
     },
     {
       sourcesDir: dpgContext.generationPathDetail?.modularSourcesDir,
@@ -391,7 +396,7 @@ export async function $onEmit(context: EmitContext) {
   }
 
   interface Metadata {
-    apiVersion?: string;
+    apiVersions?: Record<string, string>;
     emitterVersion?: string;
     crossLanguageDefinitions?: {
       CrossLanguagePackageId: string;
@@ -407,9 +412,7 @@ export async function $onEmit(context: EmitContext) {
     }
     const content: Metadata = {};
     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;
+      content.apiVersions = Object.fromEntries(apiVersions);
     }
     if (emitterVersion !== undefined) {
       content.emitterVersion = emitterVersion;
@@ -443,6 +446,11 @@ export async function $onEmit(context: EmitContext) {
       "README.md"
     );
     const hasReadmeFile = await existsSync(existingReadmeFilePath);
+    const existingWarpConfigFilePath = join(
+      dpgContext.generationPathDetail?.metadataDir ?? "",
+      "warp.config.yml"
+    );
+    const hasWarpConfigFile = await existsSync(existingWarpConfigFilePath);
     const shouldGenerateMetadata =
       option.generateMetadata === true || !hasPackageFile;
     const existingTestFolderPath = join(
@@ -517,6 +525,12 @@ export async function $onEmit(context: EmitContext) {
       commonBuilders.push((model) =>
         buildPackageFile(model, modularPackageInfo)
       );
+      // Generate warp.config.yml for Azure monorepo ESM packages (only if it doesn't exist)
+      if (option.azureSdkForJs && !hasWarpConfigFile) {
+        commonBuilders.push((model) =>
+          buildWarpConfig(model, modularPackageInfo)
+        );
+      }
       commonBuilders.push(buildTsConfig);
       if (option.azureSdkForJs) {
         commonBuilders.push(buildTsSrcConfig);
@@ -553,30 +567,65 @@ export async function $onEmit(context: EmitContext) {
         }
       }
     } else if (hasPackageFile) {
-      // update existing package.json file with correct dependencies
+      const updateBuilders = [];
       let modularPackageInfo = {};
+
+      // update existing package.json file with correct dependencies
       if (option.isModularLibrary) {
         modularPackageInfo = {
-          exports: getModuleExports(context, modularEmitterOptions)
+          exports: getModuleExports(context, modularEmitterOptions),
+          clientContextPaths: getRelativeContextPaths(
+            context,
+            modularEmitterOptions
+          )
         };
+        updateBuilders.push((model: RLCModel) =>
+          updatePackageFile(model, existingPackageFilePath, modularPackageInfo)
+        );
+      }
+
+      // Generate warp.config.yml for Azure monorepo packages (only if it doesn't exist)
+      if (option.azureSdkForJs && !hasWarpConfigFile) {
+        updateBuilders.push((model: RLCModel) =>
+          buildWarpConfig(model, modularPackageInfo)
+        );
       }
-      await emitContentByBuilder(
-        program,
-        (model) =>
-          updatePackageFile(model, existingPackageFilePath, modularPackageInfo),
-        rlcClient,
-        dpgContext.generationPathDetail?.metadataDir
-      );
 
-      // update existing README.md file if it exists
+      // If the client name changed, regenerate the README and snippets completely;
+      // otherwise update only the API reference link in-place.
       if (hasReadmeFile) {
-        await emitContentByBuilder(
-          program,
-          (model) => updateReadmeFile(model, existingReadmeFilePath),
+        const clientNameChanged = hasClientNameChanged(
           rlcClient,
-          dpgContext.generationPathDetail?.metadataDir
+          existingReadmeFilePath
         );
+        updateBuilders.push(
+          clientNameChanged
+            ? buildReadmeFile
+            : (model: RLCModel) =>
+                updateReadmeFile(model, existingReadmeFilePath)
+        );
+
+        // Regenerate snippets.spec.ts only when the client name changed
+        if (clientNameChanged && option.azureSdkForJs) {
+          for (const subClient of dpgContext.sdkPackage.clients) {
+            updateBuilders.push((model: RLCModel) =>
+              buildSnippets(
+                model,
+                getClassicalClientName(subClient),
+                option.azureSdkForJs
+              )
+            );
+          }
+        }
       }
+
+      // update metadata relevant files
+      await emitContentByBuilder(
+        program,
+        updateBuilders,
+        rlcClient,
+        dpgContext.generationPathDetail?.metadataDir
+      );
     }
     if (isAzureFlavor) {
       await emitContentByBuilder(

package/src/lib.ts

@@ -79,6 +79,12 @@ export interface EmitterOptions {
   //TODO should remove this after finish the release tool test
   "should-use-pnpm-dep"?: boolean;
   "ignore-nullable-on-optional"?: boolean;
+  /**
+   * When enabled, every regular (non-LRO, non-paging) operation return type is augmented with a
+   * `_response` property containing `rawResponse`, `parsedBody`, and `parsedHeaders`.
+   * Defaults to `false`.
+   */
+  "enable-storage-compat"?: boolean;
 }
 
 export const RLCOptionsSchema: JSONSchemaType<EmitterOptions> = {
@@ -363,6 +369,12 @@ export const RLCOptionsSchema: JSONSchemaType<EmitterOptions> = {
       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."
+    },
+    "enable-storage-compat": {
+      type: "boolean",
+      nullable: true,
+      description:
+        "When enabled, every regular (non-LRO, non-paging) operation return type is augmented with a `_response` property containing `rawResponse` (PathUncheckedResponse), `parsedBody`, and `parsedHeaders`. Defaults to `false`."
     }
   },
   required: []

package/src/modular/buildRootIndex.ts

@@ -20,6 +20,7 @@ import { reportDiagnostic } from "../lib.js";
 import { NoTarget } from "@typespec/compiler";
 import { isLroOnlyOperation } from "./helpers/operationHelpers.js";
 import { SdkContext } from "../utils/interfaces.js";
+import { partitionAndEmitExports } from "./buildSubpathIndex.js";
 
 export function buildRootIndex(
   context: SdkContext,
@@ -111,10 +112,15 @@ function exportModels(
 
 function exportAzureCloudTypes(context: SdkContext, rootIndexFile: SourceFile) {
   if (context.arm) {
+    // AzureClouds is an enum (runtime value), AzureSupportedClouds is a type alias
     addExportsToRootIndexFile(rootIndexFile, [
-      resolveReference(CloudSettingHelpers.AzureClouds),
-      resolveReference(CloudSettingHelpers.AzureSupportedClouds)
+      resolveReference(CloudSettingHelpers.AzureClouds)
     ]);
+    addExportsToRootIndexFile(
+      rootIndexFile,
+      [resolveReference(CloudSettingHelpers.AzureSupportedClouds)],
+      true
+    );
   }
 }
 
@@ -126,11 +132,15 @@ function exportPagingTypes(context: SdkContext, rootIndexFile: SourceFile) {
     return;
   }
 
-  addExportsToRootIndexFile(rootIndexFile, [
-    resolveReference(PagingHelpers.PageSettings),
-    resolveReference(PagingHelpers.ContinuablePage),
-    resolveReference(PagingHelpers.PagedAsyncIterableIterator)
-  ]);
+  addExportsToRootIndexFile(
+    rootIndexFile,
+    [
+      resolveReference(PagingHelpers.PageSettings),
+      resolveReference(PagingHelpers.ContinuablePage),
+      resolveReference(PagingHelpers.PagedAsyncIterableIterator)
+    ],
+    true
+  );
 }
 
 function hasPaging(context: SdkContext): boolean {
@@ -159,9 +169,11 @@ function exportFileContentsType(
       )
     )
   ) {
-    addExportsToRootIndexFile(rootIndexFile, [
-      resolveReference(MultipartHelpers.FileContents)
-    ]);
+    addExportsToRootIndexFile(
+      rootIndexFile,
+      [resolveReference(MultipartHelpers.FileContents)],
+      true
+    );
   }
 }
 
@@ -186,12 +198,14 @@ function getNewNamedExports(
 
 function addExportsToRootIndexFile(
   rootIndexFile: SourceFile,
-  namedExports: string[]
+  namedExports: string[],
+  isTypeOnly: boolean = false
 ) {
   const existingExports = getExistingExports(rootIndexFile);
   const newNamedExports = getNewNamedExports(namedExports, existingExports);
   if (newNamedExports.length > 0) {
     rootIndexFile.addExportDeclaration({
+      isTypeOnly,
       namedExports: newNamedExports
     });
   }
@@ -227,6 +241,7 @@ function exportSimplePollerLike(
     isTopLevel && subfolder && subfolder !== "" ? subfolder + "/" : ""
   }static-helpers/simplePollerHelpers.js`;
   indexFile.addExportDeclaration({
+    isTypeOnly: true,
     moduleSpecifier,
     namedExports: ["SimplePollerLike"]
   });
@@ -248,22 +263,14 @@ function exportRestoreHelpers(
   if (!helperFile) {
     return;
   }
-  const exported = [...indexFile.getExportedDeclarations().keys()];
-  const namedExports = [...helperFile.getExportedDeclarations().keys()].map(
-    (helper) => {
-      if (exported.indexOf(helper) > -1) {
-        return `${helper} as ${clientName}${helper}`;
-      }
-      return helper;
-    }
-  );
+  const exported = new Set(indexFile.getExportedDeclarations().keys());
+  const allEntries = [...helperFile.getExportedDeclarations().entries()];
   const moduleSpecifier = `./${
     isTopLevel && subfolder && subfolder !== "" ? subfolder + "/" : ""
   }restorePollerHelpers.js`;
-  indexFile.addExportDeclaration({
-    moduleSpecifier,
-    namedExports
-  });
+  const renamer = (name: string) =>
+    exported.has(name) ? `${name} as ${clientName}${name}` : name;
+  partitionAndEmitExports(indexFile, moduleSpecifier, allEntries, renamer);
 }
 
 function exportClassicalClient(
@@ -341,55 +348,52 @@ function exportModules(
       continue;
     }
 
-    const exported = [...indexFile.getExportedDeclarations().keys()];
+    const exported = new Set(indexFile.getExportedDeclarations().keys());
     const serializerOrDeserializerRegex = /.*(Serializer|Deserializer)(_\d+)?$/;
-    const namedExports = [...modelsFile.getExportedDeclarations().entries()]
-      .filter((exDeclaration) => {
-        if (exDeclaration[0].startsWith("_")) {
+    const filteredEntries = [
+      ...modelsFile.getExportedDeclarations().entries()
+    ].filter((exDeclaration) => {
+      if (exDeclaration[0].startsWith("_")) {
+        return false;
+      }
+      return exDeclaration[1].some((ex) => {
+        if (
+          options.interfaceOnly &&
+          ex.getKindName() !== "InterfaceDeclaration"
+        ) {
           return false;
         }
-        return exDeclaration[1].some((ex) => {
-          if (
-            options.interfaceOnly &&
-            ex.getKindName() !== "InterfaceDeclaration"
-          ) {
-            return false;
-          }
-          if (
-            moduleName === "models" &&
-            ex.getKindName() === "FunctionDeclaration" &&
-            serializerOrDeserializerRegex.test(exDeclaration[0])
-          ) {
-            return false;
-          }
-          if (
-            options.interfaceOnly &&
-            options.isTopLevel &&
-            exDeclaration[0].endsWith("Context")
-          ) {
-            return false;
-          }
-
-          return true;
-        });
-      })
-      .map((exDeclaration) => {
-        if (exported.indexOf(exDeclaration[0]) > -1) {
-          return `${exDeclaration[0]} as ${clientName}${exDeclaration[0]}`;
+        if (
+          moduleName === "models" &&
+          ex.getKindName() === "FunctionDeclaration" &&
+          serializerOrDeserializerRegex.test(exDeclaration[0])
+        ) {
+          return false;
+        }
+        if (
+          options.interfaceOnly &&
+          options.isTopLevel &&
+          exDeclaration[0].endsWith("Context")
+        ) {
+          return false;
         }
-        return exDeclaration[0];
+
+        return true;
       });
+    });
     const moduleSpecifier = `.${modelsFile
       .getFilePath()
       .replace(indexFile.getDirectoryPath(), "")
       .replace(/\\/g, "/")
       .replace(".ts", "")}.js`;
-    if (namedExports.length > 0) {
-      indexFile.addExportDeclaration({
-        moduleSpecifier,
-        namedExports
-      });
-    }
+    const renamer = (name: string) =>
+      exported.has(name) ? `${name} as ${clientName}${name}` : name;
+    partitionAndEmitExports(
+      indexFile,
+      moduleSpecifier,
+      filteredEntries,
+      renamer
+    );
   }
 }
 

package/src/modular/buildSubpathIndex.ts

@@ -7,6 +7,7 @@ import { ModularEmitterOptions } from "./interfaces.js";
 import { join } from "path";
 import { getModularClientOptions } from "../utils/clientUtils.js";
 import { useContext } from "../contextManager.js";
+import { Node, SourceFile } from "ts-morph";
 
 export interface buildSubpathIndexFileOptions {
   exportIndex?: boolean;
@@ -85,50 +86,90 @@ export function buildSubpathIndexFile(
         continue;
       }
 
-      let namedExports: string[] = [...file.getExportedDeclarations().entries()]
-        .filter((exDeclaration) => {
-          if (exDeclaration[0].startsWith("_")) {
+      let filteredDeclarations = [
+        ...file.getExportedDeclarations().entries()
+      ].filter((exDeclaration) => {
+        if (exDeclaration[0].startsWith("_")) {
+          return false;
+        }
+        return exDeclaration[1].some((ex) => {
+          if (
+            options.interfaceOnly &&
+            ex.getKindName() !== "InterfaceDeclaration"
+          ) {
             return false;
           }
-          return exDeclaration[1].some((ex) => {
-            if (
-              options.interfaceOnly &&
-              ex.getKindName() !== "InterfaceDeclaration"
-            ) {
-              return false;
-            }
 
-            // skip exporting serializers for models
-            if (
-              subpath === "models" &&
-              ex.getKindName() === "FunctionDeclaration" &&
-              serializerOrDeserializerRegex.test(exDeclaration[0])
-            ) {
-              return false;
-            }
+          // skip exporting serializers for models
+          if (
+            subpath === "models" &&
+            ex.getKindName() === "FunctionDeclaration" &&
+            serializerOrDeserializerRegex.test(exDeclaration[0])
+          ) {
+            return false;
+          }
 
-            return true;
-          });
-        })
-        .map((exDeclaration) => {
-          return exDeclaration[0];
+          return true;
         });
+      });
       // Skip to export PagedResult and BuildPagedAsyncIteratorOptions
       if (filePath.endsWith("pagingTypes.ts")) {
-        namedExports = namedExports.filter(
-          (ex) =>
-            !["PagedResult", "BuildPagedAsyncIteratorOptions"].includes(ex)
+        filteredDeclarations = filteredDeclarations.filter(
+          ([name]) =>
+            !["PagedResult", "BuildPagedAsyncIteratorOptions"].includes(name)
         );
       }
-      if (namedExports.length > 0) {
-        indexFile.addExportDeclaration({
-          moduleSpecifier: `.${filePath
-            .replace(indexFile.getDirectoryPath(), "")
-            .replace(/\\/g, "/")
-            .replace(".ts", "")}.js`,
-          namedExports
-        });
+      if (filteredDeclarations.length > 0) {
+        const moduleSpecifier = `.${filePath
+          .replace(indexFile.getDirectoryPath(), "")
+          .replace(/\\/g, "/")
+          .replace(".ts", "")}.js`;
+        partitionAndEmitExports(
+          indexFile,
+          moduleSpecifier,
+          filteredDeclarations
+        );
       }
     }
   }
 }
+
+export function isTypeOnlyNode(node: Node): boolean {
+  const kind = node.getKindName();
+  return kind === "InterfaceDeclaration" || kind === "TypeAliasDeclaration";
+}
+
+/**
+ * Partition declaration entries into type-only and value exports in a single pass,
+ * then emit both export declarations on the index file.
+ */
+export function partitionAndEmitExports(
+  indexFile: SourceFile,
+  moduleSpecifier: string,
+  entries: [string, Node[]][],
+  mapName: (name: string) => string = (n) => n
+): void {
+  const typeOnlyExports: string[] = [];
+  const valueExports: string[] = [];
+  for (const [name, decls] of entries) {
+    const mapped = mapName(name);
+    if (decls.every(isTypeOnlyNode)) {
+      typeOnlyExports.push(mapped);
+    } else {
+      valueExports.push(mapped);
+    }
+  }
+  if (typeOnlyExports.length > 0) {
+    indexFile.addExportDeclaration({
+      isTypeOnly: true,
+      moduleSpecifier,
+      namedExports: typeOnlyExports
+    });
+  }
+  if (valueExports.length > 0) {
+    indexFile.addExportDeclaration({
+      moduleSpecifier,
+      namedExports: valueExports
+    });
+  }
+}