[core] Improve documentation and implementation of Typekit, Mutator, and Realm

[witemple-msft]

• The experimental APIs are now documented with JSDoc that explains how to use the APIs.
• The relationship between Realm and Typekit has been clarified and strengthened. A Typekit is now strongly bound to a realm on creation.
• When using the default typekit, a default typekit realm is created for the current program if one does not exist already.
• RealmKit has been removed (this was previously only used to statefully set/get the realm used by the default typekit), now realm is a readonly property of the typekit.
• The default typekit $ has been merged with a function that gets a typekit bound to a specific realm ($(realm)) or bound to the default typekit realm of a specific program ($(program)) making it easier to work in specific program contexts (e.g. ProjectedProgram). The default typekit bound to a realm is cached in the Realm itself.
• Each Program now has a "default typekit realm" that is created as needed when a typekit for that program is requested.
• Additional typekit instances can still be created using createTypekit directly, bypassing the realm-caching behavior.
• Mutators now use a typekit bound to their mutation realm, so that types cloned by the mutator are created within the realm and not within the typekit's default realm. (Previously, the mutator realm was unused within the mutator itself, only passed to the mutator functions).
• The type of the mutator definition is now inferred from the definition of MutableType for accuracy. The previous definition was inaccurate and would fail to represent mutations of literal types correctly.
• Added a test that mutation of literal types works as expected.
• Worked out some module reference graph issues between defineKit and the typekit index that could sometimes lead to typekits being imported and invoked without the definitions of the typekit implementations being loaded.

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/compiler

Show changes

@typespec/compiler - feature ✏️

Experimental: Improve Realm, Mutator, and Typekit implementations.,> ,> This change strongly binds a Realm and Typekit together, and changes mutators so that new types are cloned within the,> mutator's realm. The default Typekit now creates a default typekit realm for the current program, and a Typekit can be,> easily created to work in a specific Program or Realm as needed.

[joheredi]

Thanks for taking the time to also do JSDocs, super helpful!

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs