Repository navigation
docs(http-canonicalization): Add JSDoc for shape-specific and options APIs [skip chg] - #12242
Closed
Timothee Guerin (timotheeguerin) wants to merge 2 commits into
Closed
Timothee Guerin (timotheeguerin) wants to merge 2 commits into
Timothee Guerin (timotheeguerin) wants to merge 2 commits into
Conversation
commit: |
29 of 30 tasks
|
You can try these changes here
|
Timothee Guerin (timotheeguerin)
marked this pull request as ready for review
October 16, 2026 13:44
Timothee Guerin (timotheeguerin)
requested review from
catalinaperalta,
iscai-msft,
Laurent Mazuel (lmazuel) and
Mark Cowlishaw (markcowl)
as code owners
October 16, 2026 13:44
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only, with no unresolved correctness issues identified.
0 open findings
What changed in this PR
Documents HTTP canonicalization APIs for #12228 without changing API signatures or runtime behavior.
Changes:
- Clarifies cache boundaries, option defaults, and predicate lifetime.
- Documents shape construction and language/wire projections.
- Explains union guard ordering and ambiguity failures.
| File | Description |
|---|---|
| packages/http-canonicalization/src/union.ts | Documents variant guards and ordered test plans. |
| packages/http-canonicalization/src/union-variant.ts | Clarifies variant construction and caching. |
| packages/http-canonicalization/src/scalar.ts | Documents codec selection and projections. |
| packages/http-canonicalization/src/options.ts | Explains defaults, cache keys, and naming hooks. |
| packages/http-canonicalization/src/model.ts | Documents polymorphism and projection naming. |
| packages/http-canonicalization/src/model-property.ts | Clarifies property codecs and transformations. |
| packages/http-canonicalization/src/literal.ts | Documents literal caching and projections. |
| packages/http-canonicalization/src/intrinsic.ts | Clarifies intrinsic construction semantics. |
| packages/http-canonicalization/src/http-canonicalization.ts | Documents engine reuse, predicates, and shared contracts. |
| packages/http-canonicalization/src/http-canonicalization-classes.ts | Explains dispatch and canonicalization types. |
| packages/http-canonicalization/src/enum.ts | Documents enum construction and member traversal. |
| packages/http-canonicalization/src/enum-member.ts | Clarifies enum-member leaf behavior. |
🧠 Review effort: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Member
Author
Timothee Guerin (timotheeguerin)
added a commit
that referenced
this pull request
Oct 16, 2026
…2230) Canonicalization consumers need to understand how codecs, operations, canonical shapes, and options fit together and which discriminants narrow returned metadata. Document the public canonicalization APIs as one package reference, including ownership, selection rules, and supported shapes. Keep useful shared narrowing explanations without repetitive literal-field comments; behavior is unchanged. Consolidates [12235](#12235), [12242](#12242). Tracked in #12228.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Consumers cannot safely reuse canonicalizations or generate union guards without knowing their cache boundaries, option defaults, and ordering rules. Identity codecs also do not imply unchanged language or wire shapes.
Document the shared engine and projection contracts, shape construction hooks, and ordered union test plans, including ambiguity failures. Make defaults and retained naming-policy behavior explicit, and explain predicate cache lifetime without changing any API or runtime behavior.
Tracked in #12228.