Skip to content

feat(common): add TypeInfo converter hints - #2251

Merged
THardy98 merged 5 commits into
mainfrom
feat/ts-type-hints-mapper
Jul 31, 2026
Merged

feat(common): add TypeInfo converter hints#2251
THardy98 merged 5 commits into
mainfrom
feat/ts-type-hints-mapper

Conversation

@THardy98

@THardy98 THardy98 commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

What was changed

Extended TypeInfo<T, D> with an optional ConverterHint<D> and added optional hint parameters to payload-converter serialization methods. Payload converters may expose the experimental validateConverterHint method, and CompositePayloadConverter uses it to select or validate the converter that receives a hint.

The TypeInfo conversion helpers now forward hints after applying transfer conversion. This is PR 2 of the stack and depends on #2250; Nexus operation integration follows separately.

Why?

Transfer conversion is sufficient for formats such as JSON, but some payload converters require format-specific runtime information. Protobuf deserialization, for example, needs the message type in addition to the decoded bytes.

Conversions without a hint retain their existing best-effort behavior. This API is experimental and requires no rollout or manual steps.

Checklist

  1. Closes: N/A

  2. How was this tested: Common build and all 38 Common tests; focused JSON transfer conversion and Protobuf converter-hint coverage; ESLint; Prettier; and ts-prune.

  3. Any docs updates needed? No; documentation will accompany the completed experimental API.

@THardy98
THardy98 force-pushed the feat/ts-type-hints-converter branch from 88597d8 to 5e6d348 Compare July 23, 2026 17:06
@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from c1982de to 8c124a3 Compare July 23, 2026 17:06
@THardy98
THardy98 force-pushed the feat/ts-type-hints-converter branch from 5e6d348 to 12bc6f0 Compare July 23, 2026 17:29
@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from 8c124a3 to b7eb29b Compare July 23, 2026 17:29
@THardy98 THardy98 changed the title feat(common): apply TypeInfo mappings during conversion feat(common): add TypeInfo converter hints Jul 23, 2026
@THardy98
THardy98 force-pushed the feat/ts-type-hints-converter branch from 12bc6f0 to 0bb7594 Compare July 23, 2026 18:42
@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from b7eb29b to d655488 Compare July 23, 2026 18:42
@THardy98
THardy98 force-pushed the feat/ts-type-hints-converter branch 2 times, most recently from 9a79de3 to 77066f8 Compare July 23, 2026 19:06
@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from d655488 to f6577e8 Compare July 23, 2026 19:38
@THardy98
THardy98 force-pushed the feat/ts-type-hints-converter branch 2 times, most recently from 4d9d31e to 32f28fb Compare July 24, 2026 16:44
@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from f6577e8 to eb968c5 Compare July 24, 2026 16:47
@THardy98
THardy98 force-pushed the feat/ts-type-hints-converter branch 4 times, most recently from 06abf8c to 1907b99 Compare July 25, 2026 11:57
Base automatically changed from feat/ts-type-hints-converter to main July 30, 2026 16:28
@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from eb968c5 to 22e99c3 Compare July 30, 2026 16:47
@THardy98
THardy98 marked this pull request as ready for review July 30, 2026 16:48
@THardy98
THardy98 requested a review from a team as a code owner July 30, 2026 16:48
Comment thread packages/common/src/type-info.ts Outdated
@THardy98
THardy98 enabled auto-merge (squash) July 30, 2026 19:18

@chris-olszewski chris-olszewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice to have a test that exercises a TypeInfo with both a transfer type converter and a converter hint.

* @experimental
*/
export interface TypeInfo<T = unknown> {
export interface TypeInfo<T = unknown, D = T> {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should D be passed as a generic to TransferTypeConverter so the mapping function typings line up with the type hint?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I think so - i've added in the last commit.

* Converts a {@link Payload} back to a value.
*/
fromPayload<T>(payload: Payload, context?: SerializationContext): T;
fromPayload<T>(payload: Payload, context?: SerializationContext, hint?: ConverterHint): T;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we restrict converter hints to ones that are branded with the expected type? I can't think of a reason we would want to be more permissive here.

Suggested change
fromPayload<T>(payload: Payload, context?: SerializationContext, hint?: ConverterHint): T;
fromPayload<T>(payload: Payload, context?: SerializationContext, hint?: ConverterHint<T>): T;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup - added in last commit

@THardy98
THardy98 force-pushed the feat/ts-type-hints-mapper branch from 4152cfb to d9e55da Compare July 31, 2026 01:21
@THardy98
THardy98 merged commit 803d95a into main Jul 31, 2026
62 of 66 checks passed
@THardy98
THardy98 deleted the feat/ts-type-hints-mapper branch July 31, 2026 14:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants