Mutator and HTTP Canonicalization updates

[bterlson]

Having used these tools for a reasonably complete REST emitter, the following fixes and improvements have been implemented:

Mutator framework

General

• Fix mutations not handling linkage to parent types (e.g. model property -> model).
• Remove mutation subgraph, nodes are now unique per (type, key) pair.
• Remove reference mutations, use a distinct key for references if needed.
• Added various SimpleMutations and SimpleMutationEngine for doing mutations of the graph where only one mutated type is needed per source type.

Mutation Nodes

• Connections are now built lazily. Nodes get a startXEdge method which returns a HalfEdge that can be connected to the mutation node for that type. This is necessary because we can't know what node we're going to connect to in advance (since it depends on the eventual mutationKey we'll calculate for it, see below). The only exception to this is when connecting to member types which refer back to the member container - connecting the container to a member will connect the member to the container.

Mutations

• Mutations are now abstract classes.
• Mutations have a new protocol - a static method mutationInfo is called which returns a unique mutationKey for that mutation (along with other information if needed). If the mutationKey has been seen before, the previous one is returned. Otherwise, the appropriate Mutation is constructed passing along the mutationInfo.
• mutationInfo can also return a Mutation, in which case it is used directly. Useful for constructing a Mutation view "as if" the type graph looked a different way.
• Mutations have methods to create MutationHalfEdge types for connected type which can be passed along to the engine's mutate method. When we figure out what Mutation to use based on the mutationKey we calculate, it is connected by calling setTail.

HTTP Canonicalization

General

• Fix canonicalization of merge patch models.
• Remove metadata properties from wire types.
• Added a new method subgraphMatchesPredicate to HttpCanonicalizer and HttpCanonicalization classes. This is a cycle safe way to see if the subgraph rooted at a particular canonicalization all have a certain property.
• Various fixes and improvements to union variant discrimination tests
• Normalize @Discriminator models on base type to a union of their subtypes when appropriate.
• Add support for "extensible union" pattern
• Add support for requests/responses multiple content types
• Apply getEffectiveModel to all models.

Codecs

• Codecs have a new protocol - the detect method has been removed, codec instances have encode which either returns null or EncodingInfo if it encodes the given type.
• Codecs now operate on types rather than http canonicalizations (making them more general purpose)
• Codecs can be configured by constructing them with various options. CoerceToFloat64 codec has options for whether to encode int64,decimal, etc.
• Added a Rename codec to rename the language type for types which have friendlyName, or have language-specific case conventions that differ from the API.

Emitter framework

• Add an SCCSet class which incrementally calculates strongly connected components from types added to it and updates reactive arrays with the topologically ordered types and components.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/microsoft/typespec/@typespec/emitter-framework@9141

npm i https://pkg.pr.new/microsoft/typespec/@typespec/http@9141

npm i https://pkg.pr.new/microsoft/typespec/@typespec/http-canonicalization@9141

npm i https://pkg.pr.new/microsoft/typespec/@typespec/mutator-framework@9141

commit: dd730a3

[github-actions]

All changed packages have been documented.

• ✅ @typespec/emitter-framework
• ✅ @typespec/http-canonicalization
• ✅ @typespec/mutator-framework

Show changes

@typespec/http-canonicalization - breaking ✏️

Many other bug fixes, removals, and additions as described in this pull request: #9141

@typespec/mutator-framework - breaking ✏️

Many other bug fixes, removals, and additions as described in this pull request: #9141

@typespec/emitter-framework - feature ✏️

Add an SCCSet class which incrementally calculates strongly connected components from types added to it and updates reactive arrays with the topologically ordered types and components.

@typespec/mutator-framework - breaking ✏️

Fix mutations not handling linkage to parent types (e.g. model property -> model). Remove mutation subgraph, nodes are now unique per (type, key) pair. Remove reference mutations, use a distinct key for references if needed.

@typespec/http-canonicalization - fix ✏️

Fix canonicalization of merge patch models.

@typespec/http-canonicalization - fix ✏️

Remove metadata properties from wire types.

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension