@azure-tools/typespec-ts 0.55.0-dev.9 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.55.0-dev.9",
+  "version": "0.55.0",
   "description": "An experimental TypeSpec emitter for TypeScript",
   "main": "dist/src/index.js",
   "type": "module",
@@ -18,15 +18,6 @@
   "license": "MIT",
   "devDependencies": {
     "@azure-rest/core-client": "^2.3.1",
-    "@typespec/http-specs": "^0.1.0-alpha.38 || >=0.1.0-alpha.39-dev <0.1.0-alpha.39",
-    "@typespec/spector": "^0.1.0-alpha.25 || >=0.1.0-alpha.26-dev <0.1.0-alpha.26",
-    "@typespec/spec-api": "^0.1.0-alpha.14 || >=0.1.0-alpha.15-dev <0.1.0-alpha.15",
-    "@typespec/tspd": "^0.75.0 || >=0.76.0-dev <0.76.0",
-    "@azure-tools/azure-http-specs": "^0.1.0-alpha.42 || >=0.1.0-alpha.43-dev <0.1.0-alpha.43",
-    "@azure-tools/typespec-autorest": "^0.69.1 || >=0.70.0-dev <0.70.0",
-    "@azure-tools/typespec-azure-core": "^0.69.0 || >=0.70.0-dev <0.70.0",
-    "@azure-tools/typespec-azure-resource-manager": "^0.69.1 || >=0.70.0-dev <0.70.0",
-    "@azure-tools/typespec-client-generator-core": "^0.69.0 || >=0.70.0-dev <0.70.0",
     "@azure/abort-controller": "^2.1.2",
     "@azure/core-auth": "^1.6.0",
     "@azure/core-lro": "^3.1.0",
@@ -34,13 +25,7 @@
     "@azure/core-rest-pipeline": "^1.14.0",
     "@azure/core-util": "^1.4.0",
     "@azure/logger": "^1.0.4",
-    "@typespec/compiler": "^1.13.0",
-    "@typespec/http": "^1.13.0",
-    "@typespec/openapi": "^1.13.0",
-    "@typespec/rest": "^0.83.0 || >=0.84.0-dev <0.84.0",
-    "@typespec/versioning": "^0.83.0 || >=0.84.0-dev <0.84.0",
-    "@typespec/xml": "^0.83.0 || >=0.84.0-dev <0.84.0",
-    "@typespec/ts-http-runtime": "0.3.5",
+    "@typespec/ts-http-runtime": "0.3.6",
     "cross-env": "^10.1.0",
     "mkdirp": "^3.0.1",
     "npm-run-all": "~4.1.5",
@@ -49,17 +34,31 @@
     "vite": "^8.0.8",
     "@vitest/coverage-v8": "^4.1.3",
     "@microsoft/api-extractor": "^7.58.1",
-    "tsx": "^4.21.0",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "@typespec/http-specs": "^0.1.0-alpha.38",
+    "@typespec/spector": "^0.1.0-alpha.25",
+    "@typespec/spec-api": "^0.1.0-alpha.14",
+    "@azure-tools/azure-http-specs": "^0.1.0-alpha.42",
+    "@azure-tools/typespec-autorest": "^0.69.1",
+    "@typespec/tspd": "^0.75.0",
+    "@azure-tools/typespec-azure-core": "^0.69.0",
+    "@azure-tools/typespec-azure-resource-manager": "^0.69.1",
+    "@azure-tools/typespec-client-generator-core": "^0.69.1",
+    "@typespec/compiler": "^1.13.0",
+    "@typespec/openapi": "^1.13.0",
+    "@typespec/rest": "^0.83.0",
+    "@typespec/versioning": "^0.83.0",
+    "@typespec/xml": "^0.83.0",
+    "@typespec/http": "^1.13.0"
   },
   "peerDependencies": {
-    "@azure-tools/typespec-azure-core": "^0.69.0 || >=0.70.0-dev <0.70.0",
-    "@azure-tools/typespec-client-generator-core": "^0.69.0 || >=0.70.0-dev <0.70.0",
-    "@typespec/compiler": "^1.13.0",
+    "@azure-tools/typespec-azure-core": "^0.69.0",
     "@typespec/http": "^1.13.0",
-    "@typespec/rest": "^0.83.0 || >=0.84.0-dev <0.84.0",
-    "@typespec/versioning": "^0.83.0 || >=0.84.0-dev <0.84.0",
-    "@typespec/xml": "^0.83.0 || >=0.84.0-dev <0.84.0"
+    "@typespec/compiler": "^1.13.0",
+    "@azure-tools/typespec-client-generator-core": "^0.69.1",
+    "@typespec/rest": "^0.83.0",
+    "@typespec/versioning": "^0.83.0",
+    "@typespec/xml": "^0.83.0"
   },
   "dependencies": {
     "fast-xml-parser": "^5.7.0",
@@ -93,23 +92,26 @@
     "test:azure": "npm run test-next && npm run copy:typespec && npm run integration-test-ci:azure-modular",
     "lint": "eslint . --ext .ts --max-warnings=0",
     "lint:fix": "eslint . --fix --ext .ts",
-    "check:tree": "tsx ./test/commands/check-clean-tree.ts",
+    "check:tree": "node ./test/commands/check-clean-tree.ts",
     "test:ts:e2e": "npm run copy:typespec && npm run integration-test-ci:azure-modular",
     "integration-test-ci": "npm-run-all copy:typespec integration-test-ci:azure-modular",
     "integration-test-ci:sequential": "npm-run-all --serial copy:typespec integration-test-ci:azure-modular",
     "integration-test-ci:azure-modular": "npm-run-all --silent -p start-test-server:azure-modular --race generate-and-run:azure-modular",
     "start-test-server": "mkdirp -p coverage && npx tsp-spector serve ./node_modules/@typespec/http-specs/specs  --coverageFile ./coverage/spector-coverage-typescript.json",
     "start-test-server:azure-modular": "mkdirp -p coverage && npx tsp-spector serve ./node_modules/@azure-tools/azure-http-specs/specs ./node_modules/@typespec/http-specs/specs --port 3002  --coverageFile ./coverage/spector-coverage-typescript-modular-azure.json",
-    "copy:typespec": "rm -rf temp && mkdirp -p temp/specs && mkdirp -p temp/assets && cp -r ./node_modules/@typespec/http-specs/specs/* ./temp/specs && cp -r ./node_modules/@azure-tools/azure-http-specs/specs/* ./temp/specs && cp -r ./test/integration/typespec/* ./temp/specs && cp -r ./node_modules/@typespec/http-specs/assets/* ./temp/assets",
-    "generate-and-run:azure-modular": "npm run generate-tsp-only:azure-modular && npm run integration-test:alone:azure-modular && npm run stop-test-server -- -p 3002",
+    "copy:typespec": "node ./test/commands/copy-typespec.ts",
+    "generate-and-run:azure-modular": "npm run generate-tsp-only:azure-modular:client && npm-run-all -p integration-test:alone:azure-modular generate-tsp-only:azure-modular:declarations && npm run stop-test-server -- -p 3002",
     "generate-tsp-only": "npm run generate-tsp-only:azure-modular",
-    "generate-tsp-only:azure-modular": "npx tsx ./test/commands/gen-spector.js --tag=azure-modular",
+    "generate-tsp-only:azure-modular": "node ./test/commands/gen-spector.js",
+    "generate-tsp-only:azure-modular:client": "node ./test/commands/gen-spector.js --phase=client",
+    "generate-tsp-only:azure-modular:declarations": "node ./test/commands/gen-spector.js --phase=declarations",
     "regen-test-baselines": "npm run generate-tsp-only",
     "integration-test:alone": "npm run integration-test:alone:azure-modular",
     "integration-test:alone:azure-modular": "vitest run --project integration-azure-modular",
     "stop-test-server": "npx tsp-spector server stop",
     "unit-test": "npm run unit-test:modular",
-    "unit-test:modular": "cross-env NODE_OPTIONS=--max-old-space-size=8192 vitest run --project unit-modular",
+    "unit-test:modular": "cross-env NODE_OPTIONS=--max-old-space-size=1024 vitest run --project unit-modular",
+    "gen:scenario-suites": "node ./test/commands/gen-scenario-suites.ts",
     "regen-docs": "npm run build && tspd doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/typespec-ts/reference --skip-js"
   }
 }

package/src/framework/hooks/sdk-types.ts

@@ -23,10 +23,11 @@ export const flattenPropertyModelMap: Map<SdkModelPropertyType, SdkModelType> =
   SdkModelType
 >();
 /**
- * Set of paged result models that are also used in non-paging operations.
+ * Set of paged result models that should keep their public name (no "_" prefix).
+ * This includes models used as non-paging method responses or as model properties.
  * Precomputed during visitPackageTypes for O(1) lookups in normalizeModelName.
  */
-export const pagedModelsUsedInNonPagingOps = new Set<SdkType>();
+export const pagedModelsKeptPublic = new Set<SdkType>();
 
 export interface SdkTypeContext {
   operations: Map<Type, SdkServiceMethod<SdkHttpOperation>>;

package/src/modular/build-classical-client.ts

@@ -290,8 +290,8 @@ function buildClientOperationGroups(
     } else {
       // The `rawGroupName` is used to any places where we need normalized name twice so we need to keep the raw as PascalCase.
       const rawGroupName = normalizeName(prefixes[0] ?? "", NameType.Interface);
-      const operationName = `_get${normalizeName(rawGroupName, NameType.OperationGroup)}Operations`;
-      const propertyType = `${normalizeName(rawGroupName, NameType.OperationGroup)}Operations`;
+      const operationName = `_get${rawGroupName}Operations`;
+      const propertyType = `${rawGroupName}Operations`;
       // The `groupName` is used to any places where we don't need normalized name again
       const groupName = normalizeName(rawGroupName, NameType.Property);
       const existProperty = clientClass.getProperties().filter((p) => {

package/src/modular/emit-models.ts

@@ -44,7 +44,7 @@ import {
   emitQueue,
   flattenPropertyModelMap,
   getAllOperationsFromClient,
-  pagedModelsUsedInNonPagingOps,
+  pagedModelsKeptPublic,
 } from "../framework/hooks/sdk-types.js";
 import { refkey } from "../framework/refkey.js";
 import { reportDiagnostic } from "../lib.js";
@@ -841,8 +841,7 @@ export function normalizeModelName(
   }
   const namespacePrefix = context.rlcOptions?.enableModelNamespace ? segments.join("") : "";
   const internalModelPrefix =
-    (isPagedResultModel(context, type) && !pagedModelsUsedInNonPagingOps.has(type)) ||
-    type.isGeneratedName
+    (isPagedResultModel(context, type) && !pagedModelsKeptPublic.has(type)) || type.isGeneratedName
       ? "_"
       : "";
   return `${internalModelPrefix}${normalizeName(namespacePrefix + type.name, nameType, true)}${unionSuffix}`;
@@ -932,7 +931,7 @@ export function visitPackageTypes(context: SdkContext) {
   const { sdkPackage } = context;
   emitQueue.clear();
   flattenPropertyModelMap.clear();
-  pagedModelsUsedInNonPagingOps.clear();
+  pagedModelsKeptPublic.clear();
   // Add all models in the package to the emit queue
   for (const model of sdkPackage.models) {
     visitType(context, model);
@@ -1015,7 +1014,19 @@ function trackPagedModelInNonPagingMethod(
   if (method.kind !== "basic" && method.kind !== "lro") return;
   const respType = method.response.type;
   if (respType && isPagedResultModel(context, respType)) {
-    pagedModelsUsedInNonPagingOps.add(respType);
+    pagedModelsKeptPublic.add(respType);
+  }
+}
+
+/**
+ * If a paged result model is used as a model property type, mark it so that
+ * normalizeModelName keeps it public (no "_" prefix).
+ */
+function trackPagedModelUsedAsProperty(context: SdkContext, type: SdkType): void {
+  // Unwrap array types to check the element type
+  const resolved = type.kind === "array" ? type.valueType : type;
+  if (resolved && isPagedResultModel(context, resolved)) {
+    pagedModelsKeptPublic.add(resolved);
   }
 }
 
@@ -1044,6 +1055,10 @@ function visitType(context: SdkContext, type: SdkType | undefined) {
       if (property.flatten && property.type.kind === "model") {
         flattenPropertyModelMap.set(property, type);
       }
+      // If a paged result model is used as a model property (not as a paging
+      // operation response), it must stay public (no "_" prefix) because users
+      // interact with it directly through the property.
+      trackPagedModelUsedAsProperty(context, property.type);
     }
     if (type.discriminatedSubtypes) {
       for (const subType of Object.values(type.discriminatedSubtypes)) {

package/src/modular/emit-samples.ts

@@ -316,12 +316,36 @@ function prepareExampleParameters(
 
   let subscriptionIdValue = `"00000000-0000-0000-0000-000000000000"`;
   let isSubscriptionIdAdded = false;
-  // required parameters
+
+  // Map each HTTP parameter to its method parameter via `methodParameterSegments`
+  // and place its example value at that path, yielding one argument per method
+  // parameter regardless of flat, nested, or grouped shape. Client- and
+  // body-carried roots are emitted by their own sections and skipped here.
+  const bodyParam = method.operation.bodyParam;
+  let bodyRootName: string | undefined;
+  if (
+    bodyParam &&
+    !isSpreadBodyParameter(bodyParam) &&
+    bodyParam.methodParameterSegments.length === 1 &&
+    bodyParam.methodParameterSegments[0] !== undefined &&
+    bodyParam.methodParameterSegments[0].length >= 1
+  ) {
+    bodyRootName = bodyParam.methodParameterSegments[0][0]!.name;
+  }
+
+  const methodArguments = new Map<
+    string,
+    { name: string; isOptional: boolean; value: ValueTreeNode | string }
+  >();
   for (const param of method.operation.parameters) {
-    if (param.optional === true || param.type.kind === "constant" || param.clientDefaultValue) {
+    if (param.type.kind === "constant" || param.clientDefaultValue) {
       continue;
     }
-
+    const path = param.methodParameterSegments[0];
+    if (path === undefined || path.length === 0) {
+      continue;
+    }
+    const root = path[0]!;
     const exampleValue = parameterMap[param.serializedName];
 
     // Handle subscriptionId parameter separately for ARM clients
@@ -343,28 +367,27 @@ function prepareExampleParameters(
       continue;
     }
 
+    // Roots emitted by the client and body sections.
+    if (root.onClient || (bodyRootName !== undefined && root.name === bodyRootName)) {
+      continue;
+    }
+
     if (!exampleValue || !exampleValue.value) {
       // report diagnostic if required parameter is missing
-      reportDiagnostic(dpgContext.program, {
-        code: "required-sample-parameter",
-        format: {
-          exampleName: method.oriName ?? method.name,
-          paramName: param.name,
-        },
-        target: NoTarget,
-      });
+      if (path.length === 1 && !param.optional) {
+        reportDiagnostic(dpgContext.program, {
+          code: "required-sample-parameter",
+          format: {
+            exampleName: method.oriName ?? method.name,
+            paramName: param.name,
+          },
+          target: NoTarget,
+        });
+      }
       continue;
     }
 
-    result.push(
-      prepareExampleValue(
-        dpgContext,
-        exampleValue.parameter.name,
-        exampleValue.value,
-        param.optional,
-        param.onClient,
-      ),
-    );
+    placeMethodArgument(methodArguments, path, getParameterValue(dpgContext, exampleValue.value));
   }
 
   // If client-level subscriptionId is needed on the client for this method, then add it
@@ -381,7 +404,6 @@ function prepareExampleParameters(
   }
 
   // required/optional body parameters
-  const bodyParam = method.operation.bodyParam;
   const bodySerializeName = bodyParam?.serializedName;
   const bodyExample = parameterMap[bodySerializeName ?? ""];
   if (bodyParam && bodyExample && bodyExample.value) {
@@ -441,28 +463,87 @@ function prepareExampleParameters(
       }
     }
   }
-  // optional parameters
-  method.operation.parameters
-    .filter(
-      (param) =>
-        param.optional === true && parameterMap[param.serializedName] && !param.clientDefaultValue,
-    )
-    .map((param) => parameterMap[param.serializedName]!)
-    .forEach((param) => {
-      result.push(
-        prepareExampleValue(
-          dpgContext,
-          param.parameter.name,
-          param.value,
-          true,
-          param.parameter.onClient,
-        ),
-      );
+  // Emit one argument per top-level method parameter. A normal parameter carries
+  // a scalar value; a parameter with nested leaves carries an object literal.
+  for (const arg of methodArguments.values()) {
+    result.push({
+      name: normalizeName(arg.name, NameType.Parameter, true),
+      value: serializeNestedValue(arg.value),
+      isOptional: arg.isOptional,
+      onClient: false,
     });
+  }
 
   return result;
 }
 
+/** A nested value tree: leaves are TypeScript value expressions, interior nodes are objects. */
+interface ValueTreeNode {
+  [key: string]: ValueTreeNode | string;
+}
+
+/**
+ * Records `leaf` for the method parameter addressed by `path`. `path[0]` is the
+ * top-level method parameter (the argument key); a single-segment path stores a
+ * scalar, a longer path stores the leaf inside a nested object merged with
+ * sibling leaves sharing the same root.
+ */
+function placeMethodArgument(
+  methodArguments: Map<
+    string,
+    { name: string; isOptional: boolean; value: ValueTreeNode | string }
+  >,
+  path: readonly { name: string; optional?: boolean }[],
+  leaf: string,
+): void {
+  const root = path[0]!;
+  let arg = methodArguments.get(root.name);
+  if (!arg) {
+    arg = { name: root.name, isOptional: Boolean(root.optional), value: {} };
+    methodArguments.set(root.name, arg);
+  }
+  if (path.length === 1) {
+    arg.value = leaf;
+    return;
+  }
+  if (typeof arg.value !== "object") {
+    arg.value = {};
+  }
+  setNestedValue(arg.value, path.slice(1), leaf);
+}
+
+/** Places `leaf` at `path` (segments after the root), creating intermediate objects as needed. */
+function setNestedValue(
+  root: ValueTreeNode,
+  path: readonly { name: string }[],
+  leaf: string,
+): void {
+  let node = root;
+  for (let i = 0; i < path.length; i++) {
+    const key = normalizeName(path[i]!.name, NameType.Property, true);
+    if (i === path.length - 1) {
+      node[key] = leaf;
+    } else {
+      const existing = node[key];
+      if (typeof existing !== "object" || existing === null) {
+        node[key] = {};
+      }
+      node = node[key] as ValueTreeNode;
+    }
+  }
+}
+
+/** Serializes a {@link ValueTreeNode} into a TypeScript object literal string. */
+function serializeNestedValue(node: ValueTreeNode | string): string {
+  if (typeof node === "string") {
+    return node;
+  }
+  const entries = Object.entries(node).map(
+    ([key, value]) => `${key}: ${serializeNestedValue(value)}`,
+  );
+  return `{ ${entries.join(", ")} }`;
+}
+
 function getCredentialExampleValue(
   _dpgContext: SdkContext,
   initialization: SdkClientInitializationType,

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

@@ -61,7 +61,7 @@ export function isSupportedSerializeType(type: SdkType): boolean {
  * 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>();
+const specialVariantMap = new WeakMap<SdkType, boolean>();
 export function isSpecialUnionVariant(
   t: SdkType & { isNonExhaustive?: boolean },
   variantStack: SdkType[] = [],
@@ -146,7 +146,7 @@ export function isSpecialHandledUnion(t: SdkType & { isNonExhaustive?: boolean }
   return isDiscriminatedUnion(t!) || isPolymorphicUnion(t);
 }
 
-const polymorphicUnionMap = new Map<SdkType, boolean>();
+const polymorphicUnionMap = new WeakMap<SdkType, boolean>();
 export function isPolymorphicUnion(t: SdkType): boolean {
   if (polymorphicUnionMap.has(t)) {
     return polymorphicUnionMap.get(t) ?? false;