@azure-tools/typespec-ts 0.46.1 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "description": "An experimental TypeSpec emitter for TypeScript RLC",
   "main": "dist/src/index.js",
   "type": "module",
@@ -18,14 +18,14 @@
   "license": "MIT",
   "devDependencies": {
     "@azure-rest/core-client": "^2.3.1",
-    "@typespec/http-specs": "0.1.0-alpha.29-dev.2",
-    "@typespec/spector": "0.1.0-alpha.21-dev.1",
-    "@typespec/spec-api": "0.1.0-alpha.11-dev.0",
+    "@typespec/http-specs": "0.1.0-alpha.29-dev.5",
+    "@typespec/spector": "0.1.0-alpha.21-dev.3",
+    "@typespec/spec-api": "0.1.0-alpha.11-dev.1",
     "@typespec/tspd": "0.73.1",
-    "@azure-tools/azure-http-specs": "0.1.0-alpha.33-dev.0",
+    "@azure-tools/azure-http-specs": "0.1.0-alpha.33-dev.4",
     "@azure-tools/typespec-autorest": "^0.62.0",
     "@azure-tools/typespec-azure-core": "^0.62.0",
-    "@azure-tools/typespec-azure-resource-manager": "^0.62.0",
+    "@azure-tools/typespec-azure-resource-manager": "^0.62.1",
     "@azure-tools/typespec-client-generator-core": "^0.62.0",
     "@azure/abort-controller": "^2.1.2",
     "@azure/core-auth": "^1.6.0",
@@ -38,7 +38,6 @@
     "@types/fs-extra": "^9.0.13",
     "@types/lodash": "^4.17.4",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^18.0.0",
     "@typescript-eslint/eslint-plugin": "^8.28.0",
     "@typescript-eslint/parser": "^8.28.0",
     "@typespec/compiler": "^1.6.0",
@@ -51,14 +50,11 @@
     "chalk": "^4.0.0",
     "cross-env": "^7.0.3",
     "eslint-plugin-require-extensions": "0.1.3",
-    "eslint": "^8.9.0",
     "mkdirp": "^3.0.1",
     "mocha": "^10.4.0",
     "npm-run-all": "~4.1.5",
     "prettier": "^3.3.3",
-    "rimraf": "^5.0.0",
     "ts-node": "~10.9.1",
-    "typescript": "~5.8.2",
     "vitest": "~1.6.0",
     "@vitest/coverage-v8": "~1.6.0",
     "@vitest/coverage-istanbul": "~1.6.0",
@@ -77,7 +73,7 @@
     "@typespec/xml": "^0.76.0"
   },
   "dependencies": {
-    "@azure-tools/rlc-common": "^0.46.1",
+    "@azure-tools/rlc-common": "^0.47.0",
     "fs-extra": "^11.1.0",
     "lodash": "^4.17.21",
     "prettier": "^3.3.3",

package/src/framework/hooks/sdkTypes.ts

@@ -2,6 +2,8 @@ import { Operation, Type, getNamespaceFullName } from "@typespec/compiler";
 import {
   SdkClientType,
   SdkHttpOperation,
+  SdkModelPropertyType,
+  SdkModelType,
   SdkServiceMethod,
   SdkType,
   getClientType
@@ -10,12 +12,27 @@ import { provideContext, useContext } from "../../contextManager.js";
 
 import { visitPackageTypes } from "../../modular/emitModels.js";
 import { SdkContext } from "../../utils/interfaces.js";
+import {
+  getAllAncestors,
+  getAllProperties
+} from "../../modular/helpers/operationHelpers.js";
+import { normalizeModelPropertyName } from "../../modular/type-expressions/get-type-expression.js";
+import { reportDiagnostic } from "../../lib.js";
+import { NameType, normalizeName } from "@azure-tools/rlc-common";
 
 export const emitQueue: Set<SdkType> = new Set<SdkType>();
+export const flattenPropertyModelMap: Map<SdkModelPropertyType, SdkModelType> =
+  new Map<SdkModelPropertyType, SdkModelType>();
 
 export interface SdkTypeContext {
   operations: Map<Type, SdkServiceMethod<SdkHttpOperation>>;
   types: Map<Type, SdkType>;
+  flattenProperties: Map<SdkModelPropertyType, SdkFlattenPropertyContext>;
+}
+
+export interface SdkFlattenPropertyContext {
+  baseModel: SdkModelType;
+  conflictMap?: Map<SdkModelPropertyType, string>;
 }
 
 export function useSdkTypes() {
@@ -56,11 +73,20 @@ export function useSdkTypes() {
 
 export function provideSdkTypes(context: SdkContext) {
   const { sdkPackage } = context;
-  const sdkTypesContext = {
+  const sdkTypesContext: SdkTypeContext = {
     operations: new Map<Type, SdkServiceMethod<SdkHttpOperation>>(),
-    types: new Map<Type, SdkType>()
+    types: new Map<Type, SdkType>(),
+    flattenProperties: new Map<
+      SdkModelPropertyType,
+      SdkFlattenPropertyContext
+    >()
   };
   visitPackageTypes(context);
+  enrichFlattenProperties(
+    context,
+    sdkTypesContext.flattenProperties,
+    flattenPropertyModelMap
+  );
   for (const sdkModel of emitQueue) {
     switch (sdkModel.kind) {
       case "model":
@@ -126,6 +152,80 @@ export function provideSdkTypes(context: SdkContext) {
   provideContext("sdkTypes", sdkTypesContext);
 }
 
+// Enrich flatten properties with their base models and conflict maps
+function enrichFlattenProperties(
+  context: SdkContext,
+  propertyContextMap: Map<SdkModelPropertyType, SdkFlattenPropertyContext>,
+  propertyModelMap: Map<SdkModelPropertyType, SdkModelType>
+) {
+  // Build a map of base model to its existing properties excluding flatten properties
+  // To check for conflicts later
+  const baseModelProperties = new Map<SdkModelType, Set<string>>();
+  propertyModelMap.forEach((baseModel, _) => {
+    if (!baseModelProperties.has(baseModel)) {
+      const propertiesExcludedFlatten = getAllProperties(
+        context,
+        baseModel,
+        getAllAncestors(baseModel)
+      )
+        .filter((p) => p.flatten === false || p.flatten === undefined)
+        .map((p) => normalizeModelPropertyName(context, p));
+      baseModelProperties.set(
+        baseModel,
+        new Set<string>(propertiesExcludedFlatten)
+      );
+    }
+  });
+  for (const [flattenProperty, baseModel] of propertyModelMap) {
+    const flattenContext: SdkFlattenPropertyContext = {
+      baseModel: baseModel
+    };
+    propertyContextMap.set(flattenProperty, flattenContext);
+    const existingProperties = baseModelProperties.get(baseModel)!;
+    const conflictMap = new Map<SdkModelPropertyType, string>();
+    const flattenModel = flattenProperty.type;
+
+    if (flattenModel.kind !== "model") {
+      continue;
+    }
+    if (baseModelProperties.has(flattenModel)) {
+      // If the flatten model is also a base model of other flatten properties, which means it has multiple consecutive flatten operations
+      // Since we cannot handle the flatten transition, report warning and skip it for now
+      reportDiagnostic(context.program, {
+        code: "unsupported-flatten-transition",
+        format: {
+          propertyName: flattenProperty.name,
+          modelName: baseModel.name
+        },
+        target: flattenProperty.__raw!
+      });
+    }
+    const allFlattenProperties = getAllProperties(
+      context,
+      flattenModel,
+      getAllAncestors(flattenModel)
+    );
+    for (const flattenChildProperty of allFlattenProperties) {
+      let childPropertyName = normalizeModelPropertyName(
+        context,
+        flattenChildProperty
+      );
+      if (existingProperties.has(childPropertyName)) {
+        childPropertyName = normalizeName(
+          `${childPropertyName}_${flattenProperty.name}_${childPropertyName}`,
+          NameType.Property
+        );
+        conflictMap.set(flattenChildProperty, childPropertyName);
+      }
+      existingProperties.add(childPropertyName);
+    }
+    if (conflictMap.size === 0) {
+      continue;
+    }
+    flattenContext.conflictMap = conflictMap;
+  }
+}
+
 export function getAllOperationsFromClient(
   client: SdkClientType<SdkHttpOperation>
 ) {

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   PagingHelpers,
   PollingHelpers,
   SerializationHelpers,
+  SimplePollerHelpers,
   UrlTemplateHelpers
 } from "./modular/static-helpers-metadata.js";
 import {
@@ -131,6 +132,7 @@ export async function $onEmit(context: EmitContext) {
       ...SerializationHelpers,
       ...PagingHelpers,
       ...PollingHelpers,
+      ...SimplePollerHelpers,
       ...UrlTemplateHelpers,
       ...MultipartHelpers,
       ...CloudSettingHelpers

package/src/lib.ts

@@ -60,6 +60,7 @@ export interface EmitterOptions {
   "enable-model-namespace"?: boolean;
   "hierarchy-client"?: boolean;
   "compatibility-mode"?: boolean;
+  "compatibility-lro"?: boolean;
   "experimental-extensible-enums"?: boolean;
   "clear-output-folder"?: boolean;
   "ignore-property-name-normalize"?: boolean;
@@ -281,6 +282,12 @@ export const RLCOptionsSchema: JSONSchemaType<EmitterOptions> = {
       description:
         "Whether to affect the generation of the additional property feature for the Modular client. Defaults to `false`."
     },
+    "compatibility-lro": {
+      type: "boolean",
+      nullable: true,
+      description:
+        "[deprecated] Whether to generate the legacy LRO interface. When `true`, we will generate legacy beginXXX and beginXXXAndWait LRO methods."
+    },
     "experimental-extensible-enums": {
       type: "boolean",
       nullable: true,
@@ -542,6 +549,12 @@ const libDef = {
         default: paramMessage`The parameter name ${"parameterName"} has conflicts with others and please use @clientName to rename it.`
       }
     },
+    "unsupported-flatten-transition": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`The property "${"propertyName"}" in "${"modelName"}" has multiple consecutive flatten operations. Flatten transitions are not supported so consecutive transitions will be ignored.`
+      }
+    },
     "unsupported-parameter-type": {
       severity: "error",
       messages: {
@@ -589,6 +602,12 @@ const libDef = {
       messages: {
         default: paramMessage`Error traversing directory ${"directory"}: ${"error"}`
       }
+    },
+    "detected-model-name-conflict": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`Model name conflict detected: "${"modelName"}" exists in multiple namespaces: ${"namespaces"}. Please use @clientName to rename them.`
+      }
     }
   },
   emitter: {
@@ -604,7 +623,7 @@ export const prettierTypeScriptOptions: Options = {
   arrowParens: "always",
   bracketSpacing: true,
   endOfLine: "lf",
-  printWidth: 80,
+  printWidth: 100,
   semi: true,
   singleQuote: false,
   tabWidth: 2

package/src/modular/buildClassicalClient.ts

@@ -31,9 +31,14 @@ import {
   SdkServiceMethod,
   SdkServiceOperation
 } from "@azure-tools/typespec-client-generator-core";
-import { getMethodHierarchiesMap } from "../utils/operationUtil.js";
+import {
+  getMethodHierarchiesMap,
+  isTenantLevelOperation
+} from "../utils/operationUtil.js";
 import { useContext } from "../contextManager.js";
 import { refkey } from "../framework/refkey.js";
+import { SimplePollerHelpers } from "./static-helpers-metadata.js";
+import { AzurePollingDependencies } from "./external-dependencies.js";
 
 export function buildClassicalClient(
   dpgContext: SdkContext,
@@ -117,11 +122,28 @@ export function buildClassicalClient(
     });
   }
 
-  // TODO: We may need to generate constructor overloads at some point. Here we'd do that.
-  const constructor = clientClass.addConstructor({
-    docs: getDocsFromDescription(client.doc),
-    parameters: classicalParams
-  });
+  // Check if constructor overloads for subscriptionId is needed
+  const hasSubscriptionIdParam = classicalParams.some(
+    (param) => param.name.toLowerCase() === "subscriptionid"
+  );
+  const shouldSubscriptionIdOptional =
+    dpgContext.arm &&
+    hasSubscriptionIdParam &&
+    hasTenantLevelOperations(client, dpgContext);
+
+  let constructor;
+  if (shouldSubscriptionIdOptional) {
+    constructor = generateConstructorWithOverloads(
+      clientClass,
+      classicalParams,
+      client
+    );
+  } else {
+    constructor = clientClass.addConstructor({
+      docs: getDocsFromDescription(client.doc),
+      parameters: classicalParams
+    });
+  }
 
   const paramNames = (contextParams ?? [])
     .map((p) => p.name)
@@ -132,6 +154,11 @@ export function buildClassicalClient(
           emitterOptions,
           "azsdk-js-client"
         )}}`;
+      } else if (
+        x.toLowerCase() === "subscriptionid" &&
+        shouldSubscriptionIdOptional
+      ) {
+        return `subscriptionId ?? ""`;
       } else {
         return x;
       }
@@ -204,24 +231,69 @@ function generateMethod(
   context: SdkContext,
   clientType: string,
   method: [string[], SdkServiceMethod<SdkServiceOperation>]
-) {
-  const declarations = getOperationFunction(context, method, clientType);
-  const result: MethodDeclarationStructure = {
-    docs: declarations.docs,
-    name: declarations.propertyName ?? declarations.name ?? "FIXME",
+): MethodDeclarationStructure[] {
+  const res: MethodDeclarationStructure[] = [];
+  const declaration = getOperationFunction(context, method, clientType);
+  const methodName = declaration.propertyName ?? declaration.name ?? "FIXME";
+  const methodParams =
+    declaration.parameters?.filter((p) => p.name !== "context") ?? [];
+  const declarationRefKey = resolveReference(refkey(method[1], "api"));
+  const methodParamStr = [
+    "this._client",
+    ...methodParams.map((p) => p.name)
+  ].join(", ");
+
+  res.push({
+    docs: declaration.docs,
+    name: methodName,
     kind: StructureKind.Method,
-    returnType: declarations.returnType,
-    parameters: declarations.parameters?.filter((p) => p.name !== "context"),
-    statements: `return ${resolveReference(refkey(method[1], "api"))}(${[
-      "this._client",
-      ...[
-        declarations.parameters
-          ?.map((p) => p.name)
-          .filter((p) => p !== "context")
-      ]
-    ].join(",")})`
-  };
-  return result;
+    returnType: declaration.returnType,
+    parameters: methodParams,
+    statements: `return ${declarationRefKey}(${methodParamStr})`
+  });
+
+  // add LRO helper methods if applicable
+  if (context.rlcOptions?.compatibilityLro && declaration?.isLro) {
+    const operationStateReference = resolveReference(
+      AzurePollingDependencies.OperationState
+    );
+    const simplePollerLikeReference = resolveReference(
+      SimplePollerHelpers.SimplePollerLike
+    );
+    const getSimplePollerReference = resolveReference(
+      SimplePollerHelpers.getSimplePoller
+    );
+    const returnType = declaration?.lroFinalReturnType ?? "void";
+    const beginName = normalizeName(`begin_${methodName}`, NameType.Method);
+    const beginAndWaitName = normalizeName(
+      `${beginName}_andWait`,
+      NameType.Method
+    );
+    // add begin method
+    res.push({
+      isAsync: true,
+      docs: [`@deprecated use ${methodName} instead`],
+      name: beginName,
+      kind: StructureKind.Method,
+      returnType: `Promise<${simplePollerLikeReference}<${operationStateReference}<${returnType}>, ${returnType}>>`,
+      parameters: methodParams,
+      statements: `const poller = ${declarationRefKey}(${methodParamStr});
+                  await poller.submitted();
+                  return ${getSimplePollerReference}(poller);`
+    });
+    // add begin and wait method
+    res.push({
+      isAsync: true,
+      docs: [`@deprecated use ${methodName} instead`],
+      name: beginAndWaitName,
+      kind: StructureKind.Method,
+      returnType: `Promise<${returnType}>`,
+      parameters: methodParams,
+      statements: `return await ${declarationRefKey}(${methodParamStr});`
+    });
+  }
+
+  return res;
 }
 function buildClientOperationGroups(
   clientMap: [string[], SdkClientType<SdkServiceOperation>],
@@ -240,8 +312,8 @@ function buildClientOperationGroups(
     const layer = 0;
     if (prefixKey === "") {
       operations.forEach((op) => {
-        const method = generateMethod(dpgContext, clientType, [prefixes, op]);
-        clientClass.addMethod(method);
+        const methods = generateMethod(dpgContext, clientType, [prefixes, op]);
+        clientClass.addMethods(methods);
       });
     } else {
       // The `rawGroupName` is used to any places where we need normalized name twice so we need to keep the raw as PascalCase.
@@ -323,3 +395,88 @@ function addChildClient(
     )`
   );
 }
+
+function hasTenantLevelOperations(
+  client: SdkClientType<SdkServiceOperation>,
+  dpgContext: SdkContext
+): boolean {
+  const methodMap = getMethodHierarchiesMap(dpgContext, client);
+
+  for (const [_, operations] of methodMap) {
+    for (const op of operations) {
+      if (isTenantLevelOperation(op, client)) {
+        // Found a tenant-level operation
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function generateConstructorWithOverloads(
+  clientClass: ClassDeclaration,
+  classicalParams: any[],
+  client: SdkClientType<SdkServiceOperation>
+) {
+  const filteredParams = classicalParams.filter(
+    (p) =>
+      p.name.toLowerCase() !== "subscriptionid" &&
+      p.name.toLowerCase() !== "options"
+  );
+
+  const clientConstructor = clientClass.addConstructor({
+    docs: getDocsFromDescription(client.doc),
+    parameters: [
+      ...filteredParams,
+      {
+        name: "subscriptionIdOrOptions",
+        type: `string | ${getClassicalClientName(client)}OptionalParams`,
+        hasQuestionToken: true
+      },
+      {
+        name: "options",
+        type: `${getClassicalClientName(client)}OptionalParams`,
+        hasQuestionToken: true
+      }
+    ]
+  });
+
+  clientConstructor.addOverload({
+    parameters: [
+      ...filteredParams,
+      {
+        name: "options",
+        type: `${getClassicalClientName(client)}OptionalParams`,
+        hasQuestionToken: true
+      }
+    ]
+  });
+
+  clientConstructor.addOverload({
+    parameters: [
+      ...filteredParams,
+      ...classicalParams.filter(
+        (p) => p.name.toLowerCase() === "subscriptionid"
+      ),
+      {
+        name: "options",
+        type: `${getClassicalClientName(client)}OptionalParams`,
+        hasQuestionToken: true
+      }
+    ]
+  });
+
+  clientConstructor.addStatements([
+    `let subscriptionId: string | undefined;`,
+    ``,
+    `if (typeof subscriptionIdOrOptions === "string") {`,
+    `  subscriptionId = subscriptionIdOrOptions;`,
+    `} else if (typeof subscriptionIdOrOptions === "object") {`,
+    `  options = subscriptionIdOrOptions;`,
+    `}`,
+    `options = options ?? {};`
+  ]);
+
+  return clientConstructor;
+}

package/src/modular/buildRootIndex.ts

@@ -10,7 +10,6 @@ import {
 } from "./static-helpers-metadata.js";
 import {
   SdkClientType,
-  SdkContext,
   SdkServiceOperation
 } from "@azure-tools/typespec-client-generator-core";
 import { getModularClientOptions } from "../utils/clientUtils.js";
@@ -19,6 +18,8 @@ import { join } from "path/posix";
 import { useContext } from "../contextManager.js";
 import { reportDiagnostic } from "../lib.js";
 import { NoTarget } from "@typespec/compiler";
+import { isLroOnlyOperation } from "./helpers/operationHelpers.js";
+import { SdkContext } from "../utils/interfaces.js";
 
 export function buildRootIndex(
   context: SdkContext,
@@ -55,6 +56,14 @@ export function buildRootIndex(
   }
 
   exportClassicalClient(client, rootIndexFile, subfolder ?? "");
+  exportSimplePollerLike(
+    context,
+    clientMap,
+    rootIndexFile,
+    project,
+    srcPath,
+    subfolder
+  );
   exportRestoreHelpers(
     rootIndexFile,
     project,
@@ -188,6 +197,41 @@ function addExportsToRootIndexFile(
   }
 }
 
+function exportSimplePollerLike(
+  context: SdkContext,
+  clientMap: [string[], SdkClientType<SdkServiceOperation>],
+  indexFile: SourceFile,
+  project: Project,
+  srcPath: string,
+  subfolder: string = "",
+  isTopLevel: boolean = false
+) {
+  const [_, client] = clientMap;
+
+  const methodMap = getMethodHierarchiesMap(context, client);
+  const hasLro = Array.from(methodMap.values()).some((operations) => {
+    return operations.some(isLroOnlyOperation);
+  });
+  if (!hasLro || context.rlcOptions?.compatibilityLro !== true) {
+    return;
+  }
+  const helperFile = project.getSourceFile(
+    `${srcPath}/${
+      subfolder && subfolder !== "" ? subfolder + "/" : ""
+    }static-helpers/simplePollerHelpers.ts`
+  );
+  if (!helperFile) {
+    return;
+  }
+  const moduleSpecifier = `./${
+    isTopLevel && subfolder && subfolder !== "" ? subfolder + "/" : ""
+  }static-helpers/simplePollerHelpers.js`;
+  indexFile.addExportDeclaration({
+    moduleSpecifier,
+    namedExports: ["SimplePollerLike"]
+  });
+}
+
 function exportRestoreHelpers(
   indexFile: SourceFile,
   project: Project,
@@ -381,6 +425,14 @@ export function buildSubClientIndexFile(
   }
 
   exportClassicalClient(client, subClientIndexFile, subfolder ?? "", true);
+  exportSimplePollerLike(
+    context,
+    clientMap,
+    subClientIndexFile,
+    project,
+    srcPath,
+    subfolder
+  );
   exportRestoreHelpers(
     subClientIndexFile,
     project,