[Experimental] Add Typekit for @typespec/http

[joheredi]

This PR includes:

• Consolidating the format used to define Typekits
• Adding @typespec/compiler/experimental/typekit sub export
• Adding @typespec/http/experimental/typekit sub export and implementation

Note: experimental/typekit subpaths were added for improved UX. The typekit import has a side effect which is augmenting existing typekit so having it within its own export isolates the side effect and makes it easier consumers to migrate once it becomes stable into @typespec/compiler/typekit and @typespec/http/typekit respectively

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/http

Show changes

@typespec/compiler - feature ✏️

Add Experimental Typekit helpers for @typespec/http

@typespec/http - feature ✏️

Add Experimental Typekit helpers for @typespec/http

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs	🛝 VSCode Extension

[witemple-msft]

What does a library consumer need to do to activate the new typekit functionality? I am a little weirded out that there doesn't seem to be any import from experimental/typekit from the HTTP library in the tests, so are these new typekits activated automatically on any import of @typespec/http? i also don't see the experimental export path from the HTTP library, only the compiler core.

I think this change is righteous, just want to make sure we have the consumption pattern nailed down for these experimental APIs.

I also worry a little bit about discoverability and how someone is meant to know that import "@typespec/http/experimental/typekit"; ought to be required for its side effects alone to make these extensions available. In the compiler core, you actually have to import $ from the side-effecting path, but here there won't be anything to import, you'll just import nothing from the module and it'll change the behavior of $. Do I have all this right?

[joheredi]

What does a library consumer need to do to activate the new typekit functionality? I am a little weirded out that there doesn't seem to be any import from experimental/typekit from the HTTP library in the tests, so are these new typekits activated automatically on any import of @typespec/http? i also don't see the experimental export path from the HTTP library, only the compiler core.

I think this change is righteous, just want to make sure we have the consumption pattern nailed down for these experimental APIs.

I also worry a little bit about discoverability and how someone is meant to know that import "@typespec/http/experimental/typekit"; ought to be required for its side effects alone to make these extensions available. In the compiler core, you actually have to import $ from the side-effecting path, but here there won't be anything to import, you'll just import nothing from the module and it'll change the behavior of $. Do I have all this right?

I missed adding the export for @typespec/http/experimental/typekit, fixed it.

Outside of @typespec/http, users need to explicitly import "@typespec/http/experimental/typekit" for the side effect to apply. Within @typespec/http, the augmentation is globally available because TypeScript integrates augmentations into the package's type space during compilation.

And yes, you are right, the import "@typespec/http/experimental/typekit" is purely for its side effect of augmenting types, and nothing needs to be imported explicitly from the module for the behavior to take effect.

The concern about discoverability is valid—it's something we should address. Perhaps we can do it through the documentation or provide a more explicit activation path. I am open to suggestions if you have any thoughts on how we can better streamline this!

[joheredi]

@witemple-msft I dug deeper because the runtime side effects being available without explicitly loading the module was bugging me. It turns out createTestHost is the reason—it loads all modules in the library's packageRoot when HttpTestLibrary is registered. Without HttpTestLibrary, the module isn’t loaded, and the side effects are unavailable. Let me know if this clears things up!

I will add an explicit import to avoid confusion down the road

Incomplete review

[witemple-msft]

The concern about discoverability is valid—it's something we should address. Perhaps we can do it through the documentation or provide a more explicit activation path. I am open to suggestions if you have any thoughts on how we can better streamline this!

I don't think we need to ponder this too much. When TypeKit is stabilized and then these specific extensions are stabilized, it will presumably be registered by any use of the HTTP library and that will be a good story.

[witemple-msft]

This very virtuous addition looks great to me and I can't wait to try it in http-server-js and give some practical feedback on the API and add more extensions that we might need.