feat(decorator): add @flattenProperty

common/changes/@azure-tools/typespec-client-generator-core/tcgc-flatten-property_2024-01-08-09-09.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@azure-tools/typespec-client-generator-core",
+      "comment": "feat(decorator): add `@flattenProperty`",
+      "type": "none"
+    }
+  ],
+  "packageName": "@azure-tools/typespec-client-generator-core"
+}

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

@@ -172,6 +172,34 @@ model ModelToExclude {
 }
 ```
 
+### `@flattenProperty` {#@Azure.ClientGenerator.Core.flattenProperty}
+
+Set whether a model property should be flattened or not.
+
+```typespec
+@Azure.ClientGenerator.Core.flattenProperty(scope?: valueof string)
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+
+| Name  | Type                    | Description                                                                                                   |
+| ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
+| scope | `valueof scalar string` | The language scope you want this decorator to apply to. If not specified, will apply to all language emitters |
+
+#### Examples
+
+```typespec
+model Foo {
+  @flattenProperty
+  prop: Bar;
+}
+model Bar {}
+```
+
 ### `@include` {#@Azure.ClientGenerator.Core.include}
 
 Whether to include a model in generation for specific languages. By default we generate

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

@@ -44,6 +44,7 @@ npm install --save-peer @azure-tools/typespec-client-generator-core
 - [`@clientFormat`](./decorators.md#@Azure.ClientGenerator.Core.clientFormat)
 - [`@convenientAPI`](./decorators.md#@Azure.ClientGenerator.Core.convenientAPI)
 - [`@exclude`](./decorators.md#@Azure.ClientGenerator.Core.exclude)
+- [`@flattenProperty`](./decorators.md#@Azure.ClientGenerator.Core.flattenProperty)
 - [`@include`](./decorators.md#@Azure.ClientGenerator.Core.include)
 - [`@internal`](./decorators.md#@Azure.ClientGenerator.Core.internal)
 - [`@operationGroup`](./decorators.md#@Azure.ClientGenerator.Core.operationGroup)

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

@@ -17,6 +17,7 @@ npm install @azure-tools/typespec-client-generator-core
 - [`@clientFormat`](#@clientformat)
 - [`@convenientAPI`](#@convenientapi)
 - [`@exclude`](#@exclude)
+- [`@flattenProperty`](#@flattenproperty)
 - [`@include`](#@include)
 - [`@internal`](#@internal)
 - [`@operationGroup`](#@operationgroup)
@@ -187,6 +188,34 @@ model ModelToExclude {
 }
 ```
 
+#### `@flattenProperty`
+
+Set whether a model property should be flattened or not.
+
+```typespec
+@Azure.ClientGenerator.Core.flattenProperty(scope?: valueof string)
+```
+
+##### Target
+
+`ModelProperty`
+
+##### Parameters
+
+| Name  | Type                    | Description                                                                                                   |
+| ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
+| scope | `valueof scalar string` | The language scope you want this decorator to apply to. If not specified, will apply to all language emitters |
+
+##### Examples
+
+```typespec
+model Foo {
+  @flattenProperty
+  prop: Bar;
+}
+model Bar {}
+```
+
 #### `@include`
 
 Whether to include a model in generation for specific languages. By default we generate

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

@@ -194,3 +194,20 @@ enum Access {
  * ```
  */
 extern dec access(target: Model | Operation | Enum, value: EnumMember, scope?: valueof string);
+
+/**
+ * Set whether a model property should be flattened or not.
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ *
+ * @example
+ * ```typespec
+ * model Foo {
+ *    @flattenProperty
+ *    prop: Bar;
+ * }
+ * model Bar {
+ * }
+ * ```
+ */
+#deprecated "@flattenProperty decorator is not recommended to use."
+extern dec flattenProperty(target: ModelProperty, scope?: valueof string);

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

@@ -771,3 +771,27 @@ export function getAccess(
     ? getSdkModel(context, entity).access
     : getSdkEnum(context, entity).access;
 }
+
+const flattenPropertyKey = createStateSymbol("flattenPropertyKey");
+/**
+ * Whether a model property should be flattened.
+ *
+ * @param context DecoratorContext
+ * @param target ModelProperty to mark as flattened
+ * @param scope Names of the projection (e.g. "python", "csharp", "java", "javascript")
+ * @deprecated This decorator is not recommended to use.
+ */
+export function $flattenProperty(context: DecoratorContext, target: ModelProperty, scope?: string) {
+  setScopedDecoratorData(context, $flattenProperty, flattenPropertyKey, target, true, scope); // eslint-disable-line deprecation/deprecation
+}
+
+/**
+ * Whether a model property should be flattened or not.
+ *
+ * @param context SdkContext
+ * @param target ModelProperty that we want to check whether it should be flattened or not
+ * @returns whether the model property should be flattened or not
+ */
+export function shouldFlattenProperty(context: SdkContext, target: ModelProperty): boolean {
+  return getScopedDecoratorData(context, flattenPropertyKey, target) ?? false;
+}

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

@@ -1,6 +1,14 @@
-import { Enum, Interface, Model, Namespace, Operation, UsageFlags } from "@typespec/compiler";
+import {
+  Enum,
+  Interface,
+  Model,
+  ModelProperty,
+  Namespace,
+  Operation,
+  UsageFlags,
+} from "@typespec/compiler";
 import { expectDiagnostics } from "@typespec/compiler/testing";
-import { deepStrictEqual, ok, strictEqual } from "assert";
+import { deepStrictEqual, notStrictEqual, ok, strictEqual } from "assert";
 import { beforeEach, describe, it } from "vitest";
 import {
   getAccess,
@@ -10,6 +18,7 @@ import {
   listClients,
   listOperationGroups,
   listOperationsInOperationGroup,
+  shouldFlattenProperty,
   shouldGenerateConvenient,
   shouldGenerateProtocol,
 } from "../src/decorators.js";
@@ -2197,4 +2206,102 @@ describe("typespec-client-generator-core: decorators", () => {
       strictEqual(getUsage(runner.context, Dog), UsageFlags.Output);
     });
   });
+
+  describe("@flattenProperty", () => {
+    it("marks a model property to be flattened with suppression of deprecation warning", async () => {
+      const { Model1 } = (await runner.compile(`
+        @service({})
+        @test namespace MyService {
+          @test
+          model Model1{
+            #suppress "deprecated" "@flattenProperty decorator is not recommended to use."
+            @flattenProperty
+            child: Model2;
+          }
+
+          @test
+          model Model2{}
+
+          @test
+          @route("/func1")
+          op func1(@body body: Model1): void;
+        }
+      `)) as { Model1: Model };
+
+      const childProperty = Model1.properties.get("child");
+      notStrictEqual(childProperty, undefined);
+      strictEqual(shouldFlattenProperty(runner.context, childProperty as ModelProperty), true);
+    });
+
+    it("doesn't mark a un-flattened model property", async () => {
+      const { Model1 } = (await runner.compile(`
+        @service({})
+        @test namespace MyService {
+          @test
+          model Model1{
+            child: Model2;
+          }
+
+          @test
+          model Model2{}
+
+          @test
+          @route("/func1")
+          op func1(@body body: Model1): void;
+        }
+      `)) as { Model1: Model };
+
+      const childProperty = Model1.properties.get("child");
+      notStrictEqual(childProperty, undefined);
+      strictEqual(shouldFlattenProperty(runner.context, childProperty as ModelProperty), false);
+    });
+
+    it("throws deprecation warning if not suppressed", async () => {
+      const diagnostics = await runner.diagnose(`
+        @service({})
+        @test namespace MyService {
+          @test
+          model Model1{
+            @flattenProperty
+            child: Model2;
+          }
+
+          @test
+          model Model2{}
+
+          @test
+          @route("/func1")
+          op func1(@body body: Model1): void;
+        }
+      `);
+
+      expectDiagnostics(diagnostics, {
+        code: "deprecated",
+      });
+    });
+
+    it("throws error when used on other targets", async () => {
+      const diagnostics = await runner.diagnose(`
+        @service({})
+        @test namespace MyService {
+          @test
+          @flattenProperty
+          model Model1{
+            child: Model2;
+          }
+
+          @test
+          model Model2{}
+
+          @test
+          @route("/func1")
+          op func1(@body body: Model1): void;
+        }
+      `);
+
+      expectDiagnostics(diagnostics, {
+        code: "decorator-wrong-target",
+      });
+    });
+  });
 });