@azure-tools/typespec-ts 0.56.0-dev.13 → 0.56.0-dev.15

package/src/modular/build-root-index.ts

@@ -1,4 +1,7 @@
-import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import type {
+  SdkClientType,
+  SdkServiceOperation,
+} from "@azure-tools/typespec-client-generator-core";
 import { joinPaths, NoTarget } from "@typespec/compiler";
 import { Project, SourceFile, StructureKind } from "ts-morph";
 import { useContext } from "../context-manager.js";
@@ -12,19 +15,15 @@ import {
 } from "../framework/source-file-batch.js";
 import { reportDiagnostic } from "../lib.js";
 import { getClientModuleInfo } from "../utils/client-utils.js";
-import { SdkContext } from "../utils/interfaces.js";
+import type { SdkContext } from "../utils/interfaces.js";
 import { NameType, normalizeName } from "../utils/name-utils.js";
 import { getMethodHierarchiesMap } from "../utils/operation-util.js";
 import { partitionAndEmitExports } from "./build-subpath-index.js";
+import { AzureCoreDependencies } from "./external-dependencies.js";
 import { getClassicalClientName } from "./helpers/naming-helpers.js";
 import { isLroOnlyOperation } from "./helpers/operation-helpers.js";
-import { ModularEmitterOptions } from "./interfaces.js";
-import {
-  CloudSettingHelpers,
-  MultipartHelpers,
-  PagingHelpers,
-  PlatformTypeHelpers,
-} from "./static-helpers-metadata.js";
+import type { ModularEmitterOptions } from "./interfaces.js";
+import { CloudSettingHelpers, MultipartHelpers, PagingHelpers } from "./static-helpers-metadata.js";
 
 export function buildRootIndex(
   context: SdkContext,
@@ -179,7 +178,7 @@ function exportFileContentsType(context: SdkContext, rootIndexFile: SourceFile)
       rootIndexFile,
       [
         resolveReference(MultipartHelpers.FileContents),
-        resolveReference(PlatformTypeHelpers.NodeReadableStream),
+        resolveReference(AzureCoreDependencies["NodeReadableStream"]),
       ],
       true,
     );

package/src/modular/build-subpath-index.ts

@@ -1,6 +1,9 @@
-import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import type {
+  SdkClientType,
+  SdkServiceOperation,
+} from "@azure-tools/typespec-client-generator-core";
 import { joinPaths } from "@typespec/compiler";
-import { ModularEmitterOptions } from "./interfaces.js";
+import type { ModularEmitterOptions } from "./interfaces.js";
 
 import { Node, SourceFile, StructureKind } from "ts-morph";
 import { useContext } from "../context-manager.js";

package/src/modular/emit-logger-file.ts

@@ -1,5 +1,5 @@
 import { useContext } from "../context-manager.js";
-import { ModularEmitterOptions } from "./interfaces.js";
+import type { ModularEmitterOptions } from "./interfaces.js";
 
 export function emitLoggerFile(emitterOptions: ModularEmitterOptions, srcPath: string = "src") {
   const project = useContext("outputProject");

package/src/modular/emit-models-options.ts

@@ -1,11 +1,14 @@
 import { joinPaths } from "@typespec/compiler";
 
-import { ModularEmitterOptions } from "./interfaces.js";
+import type { ModularEmitterOptions } from "./interfaces.js";
 
-import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import type {
+  SdkClientType,
+  SdkServiceOperation,
+} from "@azure-tools/typespec-client-generator-core";
 import { useContext } from "../context-manager.js";
 import { getClientModuleInfo } from "../utils/client-utils.js";
-import { SdkContext } from "../utils/interfaces.js";
+import type { SdkContext } from "../utils/interfaces.js";
 import { NameType, normalizeName } from "../utils/name-utils.js";
 import { getMethodHierarchiesMap } from "../utils/operation-util.js";
 import { buildOperationOptions } from "./build-operations.js";

package/src/modular/emit-models.ts

@@ -2,31 +2,31 @@ import {
   isPagedResultModel,
   isReadOnly,
   listAllServiceNamespaces,
-  SdkArrayType,
-  SdkClientType,
-  SdkDictionaryType,
-  SdkEnumType,
-  SdkEnumValueType,
-  SdkHttpOperation,
-  SdkMethod,
-  SdkModelPropertyType,
-  SdkModelType,
-  SdkNullableType,
-  SdkServiceMethod,
-  SdkServiceOperation,
-  SdkType,
-  SdkUnionType,
+  type SdkArrayType,
+  type SdkClientType,
+  type SdkDictionaryType,
+  type SdkEnumType,
+  type SdkEnumValueType,
+  type SdkHttpOperation,
+  type SdkMethod,
+  type SdkModelPropertyType,
+  type SdkModelType,
+  type SdkNullableType,
+  type SdkServiceMethod,
+  type SdkServiceOperation,
+  type SdkType,
+  type SdkUnionType,
   UsageFlags,
 } from "@azure-tools/typespec-client-generator-core";
 import {
-  EnumDeclarationStructure,
-  EnumMemberStructure,
-  InterfaceDeclarationStructure,
-  OptionalKind,
-  PropertySignatureStructure,
+  type EnumDeclarationStructure,
+  type EnumMemberStructure,
+  type InterfaceDeclarationStructure,
+  type OptionalKind,
+  type PropertySignatureStructure,
   SourceFile,
   StructureKind,
-  TypeAliasDeclarationStructure,
+  type TypeAliasDeclarationStructure,
 } from "ts-morph";
 // import { isKey } from "@typespec/compiler";
 import {
@@ -49,7 +49,7 @@ import { refkey } from "../framework/refkey.js";
 import { beginSourceFileBatch, flushSourceFileBatch } from "../framework/source-file-batch.js";
 import { reportDiagnostic } from "../lib.js";
 import { getClientHierarchyMap } from "../utils/client-utils.js";
-import { SdkContext } from "../utils/interfaces.js";
+import type { SdkContext } from "../utils/interfaces.js";
 import { isAzureCoreErrorType } from "../utils/model-utils.js";
 import { fixLeadingNumber, NameType, normalizeName } from "../utils/name-utils.js";
 import { getMethodHierarchiesMap } from "../utils/operation-util.js";
@@ -95,12 +95,7 @@ type InterfaceStructure = OptionalKind<InterfaceDeclarationStructure> & {
 function isGenerableType(
   type: SdkType,
 ): type is
-  | SdkModelType
-  | SdkEnumType
-  | SdkUnionType
-  | SdkDictionaryType
-  | SdkArrayType
-  | SdkNullableType {
+  SdkModelType | SdkEnumType | SdkUnionType | SdkDictionaryType | SdkArrayType | SdkNullableType {
   return (
     type.kind === "model" ||
     type.kind === "enum" ||
@@ -808,12 +803,7 @@ export function getAdditionalPropertiesName(context: SdkContext, model: SdkModel
 export function normalizeModelName(
   context: SdkContext,
   type:
-    | SdkModelType
-    | SdkEnumType
-    | SdkUnionType
-    | SdkArrayType
-    | SdkDictionaryType
-    | SdkNullableType,
+    SdkModelType | SdkEnumType | SdkUnionType | SdkArrayType | SdkDictionaryType | SdkNullableType,
   nameType: NameType = NameType.Interface,
   skipPolymorphicUnionSuffix = false,
   rawModelName?: boolean,

package/src/modular/emit-samples.ts

@@ -1,27 +1,27 @@
 import {
   isReadOnly,
-  SdkClientInitializationType,
-  SdkClientType,
-  SdkExampleValue,
-  SdkHttpOperationExample,
-  SdkHttpParameterExampleValue,
-  SdkModelPropertyType,
-  SdkServiceOperation,
+  type SdkClientInitializationType,
+  type SdkClientType,
+  type SdkExampleValue,
+  type SdkHttpOperationExample,
+  type SdkHttpParameterExampleValue,
+  type SdkModelPropertyType,
+  type SdkServiceOperation,
 } from "@azure-tools/typespec-client-generator-core";
 import { joinPaths, NoTarget } from "@typespec/compiler";
-import { FunctionDeclarationStructure, SourceFile, StructureKind } from "ts-morph";
+import { type FunctionDeclarationStructure, SourceFile, StructureKind } from "ts-morph";
 import { useContext } from "../context-manager.js";
 import { resolveReference } from "../framework/reference.js";
 import { reportDiagnostic } from "../index.js";
 import { AzureIdentityDependencies } from "../modular/external-dependencies.js";
 import { getSubscriptionId } from "../transform/transform-client-options.js";
 import { hasKeyCredential, hasTokenCredential } from "../utils/credential-utils.js";
-import { SdkContext } from "../utils/interfaces.js";
+import type { SdkContext } from "../utils/interfaces.js";
 import { NameType, normalizeName } from "../utils/name-utils.js";
 import {
   getMethodHierarchiesMap,
   isTenantLevelOperation,
-  ServiceOperation,
+  type ServiceOperation,
 } from "../utils/operation-util.js";
 import {
   getClientParameterName,
@@ -32,7 +32,7 @@ import {
 import { getClassicalClientName } from "./helpers/naming-helpers.js";
 import { getOperationFunction } from "./helpers/operation-helpers.js";
 import { buildPropertyNameMapper, isSpreadBodyParameter } from "./helpers/type-helpers.js";
-import { ModelOverrideOptions } from "./serialization/serialize-utils.js";
+import type { ModelOverrideOptions } from "./serialization/serialize-utils.js";
 
 /**
  * Interfaces for samples generations

package/src/modular/emit-tests.ts

@@ -1,13 +1,13 @@
 import { type CompilerHost, joinPaths } from "@typespec/compiler";
 import { SourceFile } from "ts-morph";
 import { resolveReference } from "../framework/reference.js";
-import { SdkContext } from "../utils/interfaces.js";
+import type { SdkContext } from "../utils/interfaces.js";
 import { NameType, normalizeName } from "../utils/name-utils.js";
-import { ServiceOperation } from "../utils/operation-util.js";
+import type { ServiceOperation } from "../utils/operation-util.js";
 import { AzureTestDependencies } from "./external-dependencies.js";
 import {
   buildParameterValueMap,
-  ClientEmitOptions,
+  type ClientEmitOptions,
   createSourceFile,
   generateMethodCall,
   generateResponseAssertions,

package/src/modular/external-dependencies.ts

@@ -1,4 +1,4 @@
-import { CoreDependencies } from "../framework/dependency.js";
+import type { CoreDependencies } from "../framework/dependency.js";
 
 export const DefaultCoreDependencies: CoreDependencies = {
   Client: {
@@ -207,6 +207,16 @@ export const AzureCoreDependencies: CoreDependencies = {
     name: "ErrorResponse",
     module: "@azure-rest/core-client",
   },
+  getBinaryStreamResponse: {
+    kind: "externalDependency",
+    module: "@azure-rest/core-client",
+    name: "getBinaryStreamResponse",
+  },
+  NodeReadableStream: {
+    kind: "externalDependency",
+    module: "@azure/core-rest-pipeline",
+    name: "NodeReadableStream",
+  },
 };
 
 export const AzureIdentityDependencies = {

package/src/modular/helpers/classical-operation-helpers.ts

@@ -1,9 +1,12 @@
-import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import type {
+  SdkClientType,
+  SdkServiceOperation,
+} from "@azure-tools/typespec-client-generator-core";
 import {
-  FunctionDeclarationStructure,
-  InterfaceDeclarationStructure,
-  OptionalKind,
-  PropertySignatureStructure,
+  type FunctionDeclarationStructure,
+  type InterfaceDeclarationStructure,
+  type OptionalKind,
+  type PropertySignatureStructure,
   SourceFile,
   StructureKind,
 } from "ts-morph";
@@ -11,9 +14,9 @@ import { addDeclaration } from "../../framework/declaration.js";
 import { resolveReference } from "../../framework/reference.js";
 import { refkey } from "../../framework/refkey.js";
 import { getClientModuleInfo } from "../../utils/client-utils.js";
-import { SdkContext } from "../../utils/interfaces.js";
+import type { SdkContext } from "../../utils/interfaces.js";
 import { NameType, normalizeName } from "../../utils/name-utils.js";
-import { ServiceOperation } from "../../utils/operation-util.js";
+import type { ServiceOperation } from "../../utils/operation-util.js";
 import { AzurePollingDependencies } from "../external-dependencies.js";
 import { PagingHelpers, SimplePollerHelpers } from "../static-helpers-metadata.js";
 import { getClassicalLayerPrefix } from "./naming-helpers.js";

package/src/modular/helpers/client-helpers.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   SdkClientType,
   SdkCredentialParameter,
   SdkEndpointParameter,
@@ -6,11 +6,16 @@ import {
   SdkMethodParameter,
   SdkServiceOperation,
 } from "@azure-tools/typespec-client-generator-core";
-import { OptionalKind, ParameterDeclarationStructure, StatementedNode } from "ts-morph";
-import { ModularEmitterOptions } from "../interfaces.js";
+import {
+  Node,
+  type OptionalKind,
+  type ParameterDeclarationStructure,
+  StatementedNode,
+} from "ts-morph";
+import type { ModularEmitterOptions } from "../interfaces.js";
 
 import { resolveReference } from "../../framework/reference.js";
-import { SdkContext } from "../../utils/interfaces.js";
+import type { SdkContext } from "../../utils/interfaces.js";
 import { NameType, normalizeName } from "../../utils/name-utils.js";
 import { CloudSettingHelpers } from "../static-helpers-metadata.js";
 import { getTypeExpression } from "../type-expressions/get-type-expression.js";
@@ -27,10 +32,7 @@ interface ClientParameterOptions {
 }
 
 type SdkParameter =
-  | SdkMethodParameter
-  | SdkEndpointParameter
-  | SdkCredentialParameter
-  | SdkHttpParameter;
+  SdkMethodParameter | SdkEndpointParameter | SdkCredentialParameter | SdkHttpParameter;
 
 export function hasDefaultValue(p: SdkParameter) {
   if (p.clientDefaultValue || p.__raw?.defaultValue || p.type.kind === "constant") {
@@ -236,7 +238,7 @@ export function buildGetClientEndpointParam(
  * @returns - an expression representing the options to be passed in to getClient
  */
 export function buildGetClientOptionsParam(
-  context: StatementedNode,
+  context: StatementedNode & Node,
   emitterOptions: ModularEmitterOptions,
   endpointParam: string,
   apiVersionParamName?: string,
@@ -319,23 +321,38 @@ function buildLoggingOptions(): string | undefined {
  * Core telemetry policy: https://azure.github.io/azure-sdk/general_azurecore.html#telemetry-policy
  */
 export function buildUserAgentOptions(
-  context: StatementedNode,
+  context: StatementedNode & Node,
   emitterOptions: ModularEmitterOptions,
 ): string {
   const userAgentStatements = [];
   const prefixFromOptions = "const prefixFromOptions = options?.userAgentOptions?.userAgentPrefix;";
   userAgentStatements.push(prefixFromOptions);
 
+  const packageName = emitterOptions.options.packageDetails?.name;
   const clientPackageName =
-    emitterOptions.options.packageDetails?.nameWithoutScope ??
-    emitterOptions.options.packageDetails?.name ??
-    "";
-  const packageVersion = emitterOptions.options.packageDetails?.version ?? "";
-
-  const userAgentInfoStatement =
-    packageVersion && clientPackageName
-      ? "const userAgentInfo = `azsdk-js-" + clientPackageName + "/" + packageVersion + "`;"
-      : "";
+    emitterOptions.options.packageDetails?.nameWithoutScope ?? packageName ?? "";
+
+  // The version is read from the generated package.json at runtime rather than
+  // hardcoded here: once the package is generated, its version is owned by
+  // package.json. We import it via the package's own "./package.json" export so
+  // the specifier is identical in `src` and the built `dist` output.
+  let userAgentInfoStatement = "";
+  if (clientPackageName && packageName) {
+    const packageJsonModule = `${packageName}/package.json`;
+    const sourceFile = context.getSourceFile();
+    const hasPackageJsonImport = sourceFile
+      .getImportDeclarations()
+      .some((declaration) => declaration.getModuleSpecifierValue() === packageJsonModule);
+    if (!hasPackageJsonImport) {
+      sourceFile.addImportDeclaration({
+        defaultImport: "pkgJson",
+        moduleSpecifier: packageJsonModule,
+        attributes: [{ name: "type", value: "json" }],
+      });
+    }
+    userAgentInfoStatement =
+      "const userAgentInfo = `azsdk-js-" + clientPackageName + "/${pkgJson.version}`;";
+  }
 
   if (!userAgentInfoStatement) {
     // Without package name/version we cannot build a meaningful telemetry token,

package/src/modular/helpers/client-option-helpers.ts

@@ -1,4 +1,4 @@
-import { DecoratedType, SdkModelType } from "@azure-tools/typespec-client-generator-core";
+import type { DecoratedType, SdkModelType } from "@azure-tools/typespec-client-generator-core";
 
 /**
  * Represents a header-to-property mapping from @clientOption("header", ...).

package/src/modular/helpers/example-value-helpers.ts

@@ -1,12 +1,12 @@
 import {
   isReadOnly,
-  SdkClientInitializationType,
-  SdkClientType,
-  SdkExampleValue,
-  SdkHttpOperationExample,
-  SdkHttpParameterExampleValue,
-  SdkModelPropertyType,
-  SdkServiceOperation,
+  type SdkClientInitializationType,
+  type SdkClientType,
+  type SdkExampleValue,
+  type SdkHttpOperationExample,
+  type SdkHttpParameterExampleValue,
+  type SdkModelPropertyType,
+  type SdkServiceOperation,
 } from "@azure-tools/typespec-client-generator-core";
 import { joinPaths } from "@typespec/compiler";
 import { SourceFile } from "ts-morph";
@@ -14,9 +14,9 @@ import { useContext } from "../../context-manager.js";
 import { resolveReference } from "../../framework/reference.js";
 import { getSubscriptionId } from "../../transform/transform-client-options.js";
 import { hasKeyCredential, hasTokenCredential } from "../../utils/credential-utils.js";
-import { SdkContext } from "../../utils/interfaces.js";
+import type { SdkContext } from "../../utils/interfaces.js";
 import { NameType, normalizeName } from "../../utils/name-utils.js";
-import { getMethodHierarchiesMap, ServiceOperation } from "../../utils/operation-util.js";
+import { getMethodHierarchiesMap, type ServiceOperation } from "../../utils/operation-util.js";
 import { AzureIdentityDependencies, AzureTestDependencies } from "../external-dependencies.js";
 import { getClientParametersDeclaration } from "./client-helpers.js";
 import { getClassicalClientName } from "./naming-helpers.js";

package/src/modular/helpers/naming-helpers.ts

@@ -1,7 +1,12 @@
-import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
-import { SdkContext } from "../../utils/interfaces.js";
+import {
+  getClientNameOverride,
+  type SdkClientType,
+  type SdkServiceOperation,
+} from "@azure-tools/typespec-client-generator-core";
+import pluralize from "pluralize";
+import type { SdkContext } from "../../utils/interfaces.js";
 import { NameType, normalizeName, ReservedModelNames } from "../../utils/name-utils.js";
-import { ServiceOperation } from "../../utils/operation-util.js";
+import type { ServiceOperation } from "../../utils/operation-util.js";
 
 export function getClientName(client: SdkClientType<SdkServiceOperation>): string {
   return client.name.replace(/Client$/, "");
@@ -12,19 +17,47 @@ export function getClassicalClientName(client: SdkClientType<SdkServiceOperation
 }
 
 export interface GuardedName {
+  /** The name used for the generated API-layer function (e.g. `deleteConversation`). */
   name: string;
+  /** The name used for the public method exposed on clients and operation groups. */
+  propertyName: string;
   fixme?: string[];
 }
 
 export function getOperationName(
   operation: ServiceOperation,
   dpgContext?: SdkContext,
+  prefixes: string[] = [],
 ): GuardedName {
-  const norm = normalizeName(operation.name, NameType.Method, true);
+  const name = normalizeName(operation.name, NameType.Method, true);
+  const propertyName = normalizeName(operation.name, NameType.Property);
   const isDataplane = dpgContext !== undefined && !dpgContext.emitterOptions?.azureArm;
-  if (isReservedName(operation.name, NameType.Method) && isDataplane) {
+  // An explicit `@clientName` override is an intentional naming choice by the user, so we
+  // honor it verbatim and skip the reserved-word disambiguation (and its `@fixme`). The
+  // public method keeps the reserved word (e.g. `delete`), while the generated API-layer
+  // function stays guarded (e.g. `$delete`) because a reserved word is not a valid function
+  // binding in JavaScript.
+  const hasClientNameOverride =
+    dpgContext !== undefined &&
+    operation.__raw !== undefined &&
+    getClientNameOverride(dpgContext, operation.__raw) !== undefined;
+  if (isReservedName(operation.name, NameType.Method) && isDataplane && !hasClientNameOverride) {
+    const suffix = getReservedNameGroupSuffix(prefixes);
+    if (suffix) {
+      // Disambiguate the reserved word by suffixing the singularized operation group
+      // name, e.g. `delete` in the `Conversations` group becomes `deleteConversation`.
+      const disambiguated = normalizeName(`${operation.name}_${suffix}`, NameType.Method);
+      return {
+        name: disambiguated,
+        propertyName: disambiguated,
+      };
+    }
+    // There is no operation group to disambiguate the reserved word with (e.g. a top-level
+    // operation), so keep the guarded name (e.g. `$delete`) and surface a fixme asking the
+    // user to override the generated name.
     return {
-      name: norm,
+      name,
+      propertyName,
       fixme: [
         `${operation.name} is a reserved word that cannot be used as an operation name. 
         Please add @clientName("clientName") or @clientName("<JS-Specific-Name>", "javascript") 
@@ -33,10 +66,25 @@ export function getOperationName(
     };
   }
   return {
-    name: norm,
+    name,
+    propertyName,
   };
 }
 
+/**
+ * Builds the suffix used to disambiguate a reserved-word operation name from the
+ * operation group it belongs to. The innermost operation group name is singularized
+ * so that, for example, the `Conversations` group yields `Conversation`.
+ */
+function getReservedNameGroupSuffix(prefixes: string[]): string | undefined {
+  const groups = prefixes.filter((prefix) => prefix && prefix.length > 0);
+  const innermostGroup = groups[groups.length - 1];
+  if (!innermostGroup) {
+    return undefined;
+  }
+  return pluralize.singular(normalizeName(innermostGroup, NameType.Interface));
+}
+
 export function isReservedName(name: string, nameType: NameType): boolean {
   return ReservedModelNames.some(
     (reservedName) =>