[tcgc] add @clientInitialization decorator

.chronus/changes/add_client_initialization-2024-7-19-14-44-30.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+add `@clientInitialization` decorator

docs/libraries/typespec-client-generator-core/reference/decorators.md

@@ -201,6 +201,45 @@ interface MyInterface {}
 interface MyInterface {}
 ```
 
+### `@clientInitialization` {#@Azure.ClientGenerator.Core.clientInitialization}
+
+Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
+
+```typespec
+@Azure.ClientGenerator.Core.clientInitialization(options: Model, scope?: valueof string)
+```
+
+#### Target
+
+`Namespace | Interface`
+
+#### Parameters
+
+| Name    | Type             | Description                                                                                                   |
+| ------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| options | `Model`          |                                                                                                               |
+| scope   | `valueof string` | The language scope you want this decorator to apply to. If not specified, will apply to all language emitters |
+
+#### Examples
+
+```typespec
+// main.tsp
+namespace MyService;
+
+op upload(blobName: string): void;
+op download(blobName: string): void;
+
+// client.tsp
+namespace MyCustomizations;
+model MyServiceClientOptions {
+  blobName: string;
+}
+
+@@clientInitialization(MyService, MyServiceClientOptions)
+// The generated client will have `blobName` on it. We will also
+// elevate the existing `blobName` parameter to the client level.
+```
+
 ### `@clientName` {#@Azure.ClientGenerator.Core.clientName}
 
 Changes the name of a method, parameter, property, or model generated in the client SDK

docs/libraries/typespec-client-generator-core/reference/index.mdx

@@ -41,6 +41,7 @@ npm install --save-peer @azure-tools/typespec-client-generator-core
 
 - [`@access`](./decorators.md#@Azure.ClientGenerator.Core.access)
 - [`@client`](./decorators.md#@Azure.ClientGenerator.Core.client)
+- [`@clientInitialization`](./decorators.md#@Azure.ClientGenerator.Core.clientInitialization)
 - [`@clientName`](./decorators.md#@Azure.ClientGenerator.Core.clientName)
 - [`@convenientAPI`](./decorators.md#@Azure.ClientGenerator.Core.convenientAPI)
 - [`@flattenProperty`](./decorators.md#@Azure.ClientGenerator.Core.flattenProperty)

packages/typespec-client-generator-core/README.md

@@ -14,6 +14,7 @@ npm install @azure-tools/typespec-client-generator-core
 
 - [`@access`](#@access)
 - [`@client`](#@client)
+- [`@clientInitialization`](#@clientinitialization)
 - [`@clientName`](#@clientname)
 - [`@convenientAPI`](#@convenientapi)
 - [`@flattenProperty`](#@flattenproperty)
@@ -216,6 +217,45 @@ interface MyInterface {}
 interface MyInterface {}
 ```
 
+#### `@clientInitialization`
+
+Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
+
+```typespec
+@Azure.ClientGenerator.Core.clientInitialization(options: Model, scope?: valueof string)
+```
+
+##### Target
+
+`Namespace | Interface`
+
+##### Parameters
+
+| Name    | Type             | Description                                                                                                   |
+| ------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| options | `Model`          |                                                                                                               |
+| scope   | `valueof string` | The language scope you want this decorator to apply to. If not specified, will apply to all language emitters |
+
+##### Examples
+
+```typespec
+// main.tsp
+namespace MyService;
+
+op upload(blobName: string): void;
+op download(blobName: string): void;
+
+// client.tsp
+namespace MyCustomizations;
+model MyServiceClientOptions {
+  blobName: string;
+}
+
+@@clientInitialization(MyService, MyServiceClientOptions)
+// The generated client will have `blobName` on it. We will also
+// elevate the existing `blobName` parameter to the client level.
+```
+
 #### `@clientName`
 
 Changes the name of a method, parameter, property, or model generated in the client SDK

packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts

@@ -433,6 +433,36 @@ export type UseSystemTextJsonConverterDecorator = (
   scope?: string
 ) => void;
 
+/**
+ * Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
+ *
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @example
+ * ```typespec
+ * // main.tsp
+ * namespace MyService;
+ *
+ * op upload(blobName: string): void;
+ * op download(blobName: string): void;
+ *
+ * // client.tsp
+ * namespace MyCustomizations;
+ * model MyServiceClientOptions {
+ *   blobName: string;
+ * }
+ *
+ * @@clientInitialization(MyService, MyServiceClientOptions)
+ * // The generated client will have `blobName` on it. We will also
+ * // elevate the existing `blobName` parameter to the client level.
+ * ```
+ */
+export type ClientInitializationDecorator = (
+  context: DecoratorContext,
+  target: Namespace | Interface,
+  options: Model,
+  scope?: string
+) => void;
+
 export type AzureClientGeneratorCoreDecorators = {
   clientName: ClientNameDecorator;
   convenientAPI: ConvenientAPIDecorator;
@@ -444,4 +474,5 @@ export type AzureClientGeneratorCoreDecorators = {
   flattenProperty: FlattenPropertyDecorator;
   override: OverrideDecorator;
   useSystemTextJsonConverter: UseSystemTextJsonConverterDecorator;
+  clientInitialization: ClientInitializationDecorator;
 };

packages/typespec-client-generator-core/lib/decorators.tsp

@@ -419,3 +419,32 @@ extern dec override(original: Operation, override: Operation, scope?: valueof st
  * ```
  */
 extern dec useSystemTextJsonConverter(target: Model, scope?: valueof string);
+
+/**
+ * Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ *
+ * @example
+ * ```typespec
+ * // main.tsp
+ * namespace MyService;
+ *
+ * op upload(blobName: string): void;
+ * op download(blobName: string): void;
+ *
+ * // client.tsp
+ * namespace MyCustomizations;
+ * model MyServiceClientOptions {
+ *   blobName: string;
+ * }
+ *
+ * @@clientInitialization(MyService, MyServiceClientOptions)
+ * // The generated client will have `blobName` on it. We will also
+ * // elevate the existing `blobName` parameter to the client level.
+ * ```
+ */
+extern dec clientInitialization(
+  target: Namespace | Interface,
+  options: Model,
+  scope?: valueof string
+);

packages/typespec-client-generator-core/src/decorators.ts

@@ -34,6 +34,7 @@ import { buildVersionProjections, getVersions } from "@typespec/versioning";
 import {
   AccessDecorator,
   ClientDecorator,
+  ClientInitializationDecorator,
   ClientNameDecorator,
   ConvenientAPIDecorator,
   FlattenPropertyDecorator,
@@ -50,6 +51,9 @@ import {
   SdkContext,
   SdkEmitterOptions,
   SdkHttpOperation,
+  SdkInitializationType,
+  SdkMethodParameter,
+  SdkModelPropertyType,
   SdkOperationGroup,
   SdkServiceOperation,
   TCGCContext,
@@ -86,13 +90,14 @@ function getScopedDecoratorData(
   return retval[AllScopes]; // in this case it applies to all languages
 }
 
-function listScopedDecoratorData(context: TCGCContext, key: symbol): any[] {
+function listScopedDecoratorData(context: {program: Program}, key: symbol, emitterName?: string): any[] {
+  const scope = emitterName || AllScopes;
   const retval = [...context.program.stateMap(key).values()];
   return retval
     .filter((targetEntry) => {
-      return targetEntry[context.emitterName] || targetEntry[AllScopes];
+      return targetEntry[scope] || targetEntry[AllScopes];
     })
-    .flatMap((targetEntry) => targetEntry[context.emitterName] ?? targetEntry[AllScopes]);
+    .flatMap((targetEntry) => targetEntry[scope] ?? targetEntry[AllScopes]);
 }
 
 function setScopedDecoratorData(
@@ -227,10 +232,10 @@ export function getClient(
   return undefined;
 }
 
-function hasExplicitClientOrOperationGroup(context: TCGCContext): boolean {
+function hasExplicitClientOrOperationGroup(context: {program: Program, emitterName?: string}): boolean {
   return (
-    listScopedDecoratorData(context, clientKey).length > 0 ||
-    listScopedDecoratorData(context, operationGroupKey).length > 0
+    listScopedDecoratorData(context, clientKey, context.emitterName).length > 0 ||
+    listScopedDecoratorData(context, operationGroupKey, context.emitterName).length > 0
   );
 }
 
@@ -304,7 +309,7 @@ function getClientsWithVersioning(context: TCGCContext, clients: SdkClient[]): S
 export function listClients(context: TCGCContext): SdkClient[] {
   if (context.__rawClients) return context.__rawClients;
 
-  const explicitClients = [...listScopedDecoratorData(context, clientKey)];
+  const explicitClients = [...listScopedDecoratorData(context, clientKey, context.emitterName)];
   if (explicitClients.length > 0) {
     context.__rawClients = getClientsWithVersioning(context, explicitClients);
     if (context.__rawClients.some((client) => isArm(client.service))) {
@@ -376,6 +381,17 @@ export const $operationGroup: OperationGroupDecorator = (
   );
 };
 
+function isOperationGroupWithNoExplicitDecorator(type: Namespace | Interface): boolean {
+  // if there is no explicit client, we will treat non-client namespaces and all interfaces as operation group
+  if (type.kind === "Interface" && !isTemplateDeclaration(type)) {
+    return true;
+  }
+  if (type.kind === "Namespace" && !type.decorators.some((t) => t.decorator.name === "$service")) {
+    return true;
+  }
+  return false;
+}
+
 /**
  * Check a namespace or interface is an operation group.
  * @param context TCGCContext
@@ -386,14 +402,7 @@ export function isOperationGroup(context: TCGCContext, type: Namespace | Interfa
   if (hasExplicitClientOrOperationGroup(context)) {
     return getScopedDecoratorData(context, operationGroupKey, type) !== undefined;
   }
-  // if there is no explicit client, we will treat non-client namespaces and all interfaces as operation group
-  if (type.kind === "Interface" && !isTemplateDeclaration(type)) {
-    return true;
-  }
-  if (type.kind === "Namespace" && !type.decorators.some((t) => t.decorator.name === "$service")) {
-    return true;
-  }
-  return false;
+  return isOperationGroupWithNoExplicitDecorator(type);
 }
 /**
  * Check an operation is in an operation group.
@@ -607,9 +616,9 @@ export function createTCGCContext(program: Program, emitterName: string): TCGCCo
     emitterName: diagnostics.pipe(parseEmitterName(program, emitterName)),
     diagnostics: diagnostics.diagnostics,
     originalProgram: program,
-    __namespaceToApiVersionParameter: new Map(),
+    __clientToParameters: new Map(),
     __tspTypeToApiVersions: new Map(),
-    __namespaceToApiVersionClientDefaultValue: new Map(),
+    __clientToApiVersionClientDefaultValue: new Map(),
     previewStringRegex: /-preview$/,
   };
 }
@@ -975,3 +984,52 @@ export const $useSystemTextJsonConverter: DecoratorFunction = (
   entity: Model,
   scope?: LanguageScopes
 ) => {};
+
+const clientInitializationKey = createStateSymbol("clientInitialization");
+
+function isOperationGroupNoScopeCheck(context: {program: Program}, target: Namespace | Interface): boolean {
+  if (hasExplicitClientOrOperationGroup(context)) {
+    return Boolean(context.program.stateMap(operationGroupKey).get(target));
+  }
+  return isOperationGroupWithNoExplicitDecorator(target);
+}
+
+export const $clientInitialization: ClientInitializationDecorator = (
+  context: DecoratorContext,
+  target: Namespace | Interface,
+  options: Model,
+  scope?: LanguageScopes
+) => {
+  if (isOperationGroupNoScopeCheck(context, target)) {
+    if (target.namespace && context.program.stateMap(clientInitializationKey).get(target.namespace) === options) {
+      setScopedDecoratorData(context, $override, clientInitializationKey, target, options, scope);
+    } else {
+      reportDiagnostic(context.program, {
+        code: "assigning-public-params-to-internal-client",
+        format: { name: target.name },
+        target: context.decoratorTarget,
+      });
+    }
+  }
+  setScopedDecoratorData(context, $override, clientInitializationKey, target, options, scope);
+};
+
+export function getClientInitialization(
+  context: TCGCContext,
+  entity: Namespace | Interface
+): SdkInitializationType | undefined {
+  const model = getScopedDecoratorData(context, clientInitializationKey, entity);
+  if (!model) return model;
+  const sdkModel = getSdkModel(context, model);
+  const initializationProps = sdkModel.properties.map(
+    (property: SdkModelPropertyType): SdkMethodParameter => {
+      property.onClient = true;
+      property.kind = "method";
+      return property as SdkMethodParameter;
+    }
+  );
+  return {
+    ...sdkModel,
+    properties: initializationProps,
+  };
+}