[tcgc] add functions to help with override story by iscai-msft · Pull Request #3995 · Azure/typespec-azure

iscai-msft · 2026-03-02T21:45:19Z

No description provided.

…cgc/addReplaceDecorator

…arate file - Move replaceParameter from decorators.tsp to new lib/functions.tsp - Add replaceResponse function to replace operation return types - Add addParameter function to add parameters to operations - Add tests for all three functions (23 total tests) - Add documentation page for functions (experimental) - Update reference index to link to functions documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

pkg-pr-new · 2026-03-02T21:48:54Z

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/typespec-client-generator-core@3995

commit: 008298e

azure-sdk · 2026-03-02T21:50:27Z

All changed packages have been documented.

✅ @azure-tools/typespec-client-generator-core

Show changes

`@azure-tools/typespec-client-generator-core` - feature ✏️

Add experimental extern functions for operation transformations:,> - replaceParameter: Replace or remove a parameter in an operation,> - addParameter: Add a new parameter to an operation,> - reorderParameters: Reorder parameters of an operation according to a specified order,> ,> These functions enable composable transformations that work with @@override to customize method signatures in client SDKs.

azure-sdk · 2026-03-02T22:00:38Z

You can try these changes here

🛝 Playground	🌐 Website

- Use createClientCustomizationInput and createSdkContextForTester pattern - Verify method parameters, optionality, types - Verify operation-to-method parameter mappings (correspondingMethodParams) - Test scoped overrides (Python vs C#) - Remove complex nested namespace tests that hit TCGC edge cases Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

@OverRide

- Remove functions.md from tcgc reference section - Add comprehensive @OverRide section to 04method.mdx - Document transformation functions (replaceParameter, addParameter, replaceResponse) - Add multi-language examples with ClientTabs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…cgc/addReplaceDecorator

tadelesh

Several high level concerns:

In what scenario we need to add a parameter in client level? How should the added parameter be used in the client code? There will be no mapping for it on wire.
Shall we only allow to remove the optional parameter? Is there any other limitation we should add?
Same concern for replace. I don't think any replacement could work here.

iscai-msft · 2026-03-18T20:05:06Z

Several high level concerns:

In what scenario we need to add a parameter in client level? How should the added parameter be used in the client code? There will be no mapping for it on wire.

Shall we only allow to remove the optional parameter? Is there any other limitation we should add?

Same concern for replace. I don't think any replacement could work here.

Here I'm relying on the validation from @override for everything, bc these functions can't be used as anything except when passed as input to @override, so I don't think we need to add a bunch of new validations on top of @override

tadelesh

Generally LGTM. In ARM, we have a brown field frequent user scenario: adjust parameter order to prevent SDK breaking change. Is it possible to add a function to help with that requirement?

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

…ceDecorator

…cgc/addReplaceDecorator

…sft/typespec-azure into tcgc/addReplaceDecorator

Copilot

Pull request overview

Adds experimental TypeSpec extern functions to enable composable @@override-based method signature customization in generated client SDKs, along with docs and tests.

Changes:

Introduces replaceParameter, addParameter, and reorderParameters extern functions and exports them via $functions.
Adds diagnostics and Vitest coverage for the new transformation functions.
Documents @@override usage patterns and transformation chaining in the client library generation how-to.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
website/src/content/docs/docs/howtos/Generate client libraries/04method.mdx	Adds documentation for `@@override` and the new transformation functions.
packages/typespec-client-generator-core/tsconfig.build.json	Excludes additional test filename patterns from build compilation.
packages/typespec-client-generator-core/test/functions/replace-parameter.test.ts	Adds tests for `replaceParameter` behavior and scoped overrides.
packages/typespec-client-generator-core/test/functions/reorder-parameters.test.ts	Adds tests for `reorderParameters`, chaining, and diagnostics.
packages/typespec-client-generator-core/test/functions/add-parameter.test.ts	Adds tests for `addParameter`, chaining, and scoped overrides.
packages/typespec-client-generator-core/src/tsp-index.ts	Exports implementations via `$functions` for TypeSpec extern function binding.
packages/typespec-client-generator-core/src/lib.ts	Adds new diagnostics for replace/reorder parameter validation.
packages/typespec-client-generator-core/src/index.ts	Exports `$functions` in addition to `$decorators`.
packages/typespec-client-generator-core/src/functions.ts	Implements the three operation transformation functions.
packages/typespec-client-generator-core/lib/main.tsp	Imports the new `functions.tsp` into the library surface.
packages/typespec-client-generator-core/lib/functions.tsp	Declares the extern function signatures and docs in TypeSpec.
packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts-test.ts	Adds compile-time export/signature checks for `$functions`.
packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts	Extends generated defs with function implementation types.
.chronus/changes/tcgc-addReplaceDecorator-2026-2-2-16-3-32.md	Adds changelog entry for the new experimental extern functions.

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

website/src/content/docs/docs/howtos/Generate client libraries/04method.mdx

…/04method.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…sft/typespec-azure into tcgc/addReplaceDecorator

tadelesh · 2026-03-23T02:53:28Z

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

+ * This function creates a new operation with the specified parameter replaced,
+ * enabling composable transformations without mutating the original operation.
+ *
+ * Note: Parameter removal (using `void` as replacement) is not supported when used with `@@override`.


If I recalled correctly, we do have a case to remove optional parameter for key vault? See playground.

…cgc/addReplaceDecorator

iscai-msft and others added 6 commits April 30, 2025 16:17

link out to mock api and scenario docs

af6f2b1

implement functions and update docs

073e0ba

revert pnpm lock commit

7ad7cef

Merge branch 'main' of https://github.com/Azure/typespec-azure into t…

21e7792

…cgc/addReplaceDecorator

add changeset

baf6f08

iscai-msft requested review from bterlson, joheredi, lmazuel, m-nash, markcowl, srnagar and timotheeguerin as code owners March 2, 2026 21:45

microsoft-github-policy-service bot added the lib:tcgc Issues for @azure-tools/typespec-client-generator-core library label Mar 2, 2026

format and lint

dfdde40

iscai-msft and others added 4 commits March 2, 2026 17:19

Apply formatting

c0fa279

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge branch 'main' of https://github.com/Azure/typespec-azure into t…

f7f263c

…cgc/addReplaceDecorator

microsoft-github-policy-service bot added the meta:website TypeSpec.io updates label Mar 17, 2026

tadelesh reviewed Mar 18, 2026

View reviewed changes

Merge branch 'main' into tcgc/addReplaceDecorator

1c9e664

tadelesh reviewed Mar 19, 2026

View reviewed changes

packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts Outdated Show resolved Hide resolved

iscai-msft added 2 commits March 19, 2026 11:17

remove replaceResponse and add reorderParameters

59096fa

Merge https://github.com/iscai-msft/typespec-azure into tcgc/addRepla…

b6d087d

…ceDecorator

iscai-msft added 3 commits March 19, 2026 11:21

Merge branch 'main' of https://github.com/Azure/typespec-azure into t…

aaa9f37

…cgc/addReplaceDecorator

Merge branch 'tcgc/addReplaceDecorator' of https://github.com/iscai-m…

192e15e

…sft/typespec-azure into tcgc/addReplaceDecorator

remove as any setting

a78f6d6

iscai-msft requested a review from tadelesh March 19, 2026 19:18

lint

210f9ad

tadelesh requested a review from Copilot March 20, 2026 03:18

Copilot AI reviewed Mar 20, 2026

View reviewed changes

tadelesh and others added 5 commits March 20, 2026 12:04

Update website/src/content/docs/docs/howtos/Generate client libraries…

be6f632

…/04method.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

address copilot comments

03dd24f

Merge branch 'tcgc/addReplaceDecorator' of https://github.com/iscai-m…

529431e

…sft/typespec-azure into tcgc/addReplaceDecorator

update doc to remove removal

c1c05b9

format

adb7485

tadelesh reviewed Mar 23, 2026

View reviewed changes

iscai-msft added 2 commits March 23, 2026 15:11

Merge branch 'main' of https://github.com/Azure/typespec-azure into t…

f23a7e8

…cgc/addReplaceDecorator

add back remove parameter

008298e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[tcgc] add functions to help with override story#3995

[tcgc] add functions to help with override story#3995
iscai-msft wants to merge 25 commits intoAzure:mainfrom
iscai-msft:tcgc/addReplaceDecorator

iscai-msft commented Mar 2, 2026

Uh oh!

pkg-pr-new bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

azure-sdk commented Mar 2, 2026 •

edited

Loading

`@azure-tools/typespec-client-generator-core` - feature ✏️

Uh oh!

azure-sdk commented Mar 2, 2026 •

edited

Loading

Uh oh!

tadelesh left a comment

Uh oh!

iscai-msft commented Mar 18, 2026

Uh oh!

tadelesh left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tadelesh Mar 23, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

iscai-msft commented Mar 2, 2026

Uh oh!

pkg-pr-new bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azure-sdk commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

@azure-tools/typespec-client-generator-core - feature ✏️

Uh oh!

azure-sdk commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tadelesh left a comment

Choose a reason for hiding this comment

Uh oh!

iscai-msft commented Mar 18, 2026

Uh oh!

tadelesh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tadelesh Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pkg-pr-new bot commented Mar 2, 2026 •

edited

Loading

azure-sdk commented Mar 2, 2026 •

edited

Loading

`@azure-tools/typespec-client-generator-core` - feature ✏️

azure-sdk commented Mar 2, 2026 •

edited

Loading

tadelesh Mar 23, 2026 •

edited

Loading