Skip to content

fix(ts): accept serialized string enum values - #471

Open
与世无争剑宇子 (yushiwuzhengjianyuzi) wants to merge 13 commits into
microsoft:mainfrom
yushiwuzhengjianyuzi:fix/enum-wire-validation
Open

与世无争剑宇子 (yushiwuzhengjianyuzi) wants to merge 13 commits into
microsoft:mainfrom
yushiwuzhengjianyuzi:fix/enum-wire-validation

Conversation

@yushiwuzhengjianyuzi

@yushiwuzhengjianyuzi 与世无争剑宇子 (yushiwuzhengjianyuzi) commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Normalize JSON-facing TypeScript schema types so serialized string-enum values are accepted without casts or diagnostic suppression.
  • Recursively preserve nested objects, arrays, tuples, optional properties, unions, index signatures, and recursive schemas while leaving numeric enums unchanged.
  • Limit string normalization to values declared by enums so branded strings, class instances, callable types, and non-primitive object constraints keep their existing semantics.
  • Keep primitive wrapper types (String, Number, Boolean) assignable to their primitive values when a string enum is present.
  • Preserve weak-type checking for ordinary all-optional shapes while separately honoring explicit object intersections, including all-optional and primitive wrapper properties.
  • Keep internal helper names out of diagnostics without rewriting property identifiers, template-literal types, quoted data values, or literal-bearing type arguments, and avoid helper names that collide with enum values or the imported target type, including escaped identifiers.
  • Scope missing-property expansion to the outer declaration so nested recursive diagnostics keep their own missing fields.

Validation

  • npm test - 408/408 tests pass
  • npm run build-all - all workspaces build successfully

Fixes #465

@robgruen robgruen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

AI-assisted review: changes requested

This review was prepared with GitHub Copilot and is submitted at robgruen's explicit request.

The intent is worthwhile and matches the acceptance criteria in #465: validate serialized string-enum values without casts, suppressed diagnostics, or executing schema code. The focused documentation and regression coverage are useful. However, I reproduced two compatibility regressions that should be addressed before merging; the inline comments include sample code and observed results:

  1. The recursive normalization erases call and constructor signatures. Previously rejected JSON can now pass validation even in schemas without enums. This also makes Promise-shaped JSON pass when combined with main's standard-library helper support. Preserve rejection of these non-JSON types and add negative regression tests.
  2. Missing-property diagnostics unwrap unrelated generic types. With a custom createModuleTextFromJson implementation, a declaration targeting Wrapper<Metadata> reports missing fields from Metadata rather than the wrapper. Restrict unwrapping to the generated JSON-wire helper and add coverage for custom generic declarations.

Verification and separate baseline concern

  • Reviewed PR head e2f3f7bc7ce60083b5a20d2eff5eabf45ad689de using Node.js 24.22.1 and the existing installed dependencies; this was not a fresh npm ci run.
  • The library build and test compilation passed. The validator suite passed 19/19 tests on the PR head and 40/40 after a local merge with then-main d2a5a3ffe6e2962d36781d861a2feb6fae406573.
  • Additional before/after probes reproduced both regressions, including after merging that main baseline. Optional tuples and recursive enum schemas also behaved as intended in the extra probes.
  • Current main has since advanced to 137c5e1982323878866b5620c1f552cef16c6c80; I checked the intervening diff. It only adds validator cleanup in tests and does not change the validation logic or the examples runner discussed below.
  • Full npm test on the PR head produced 162 passes and one failed test-file startup, rather than a fully green run. The unchanged typescript/tests/examples.test.mjs:56 fails before discovering its tests:
compilerOptions: { module: ts.ModuleKind.CommonJS, esModuleInterop: true },
                                         ^
TypeError: Cannot read properties of undefined (reading 'CommonJS')

I reproduced that same startup failure on the main baseline. This is a pre-existing validation limitation, not an enum regression or a request to add an unrelated fix to this PR. GitHub currently reports only the CLA check for this PR, so I also do not have an automated TypeScript test result confirming the stated full-suite pass. Please provide updated, reproducible test evidence with the revision and distinguish any remaining baseline failure from these two requested fixes.

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Copilot AI balanced review requested due to automatic review settings November 9, 2026 07:22
@yushiwuzhengjianyuzi

Copy link
Copy Markdown
Contributor Author

Thanks robgruen — both compatibility regressions are fixed in 2634316.

  • The JSON-wire normalization now preserves call and construct signatures instead of mapping them through keyof, so {} no longer satisfies () => string or new () => …. This also keeps Promise-like then/catch methods callable and rejects non-callable stand-ins.
  • TS2740 diagnostic expansion now unwraps only the validator's own __TypeChatJsonWire annotation. Custom createModuleTextFromJson declarations such as Wrapper<Metadata> keep their full generic target and report the wrapper's missing fields.

Added regression coverage for call signatures, construct signatures, non-callable Promise-shaped objects, and a custom generic module generator.

Verification on 2634316 (Node 24.11.1, existing installed dependencies):

  • npm run build — passed
  • npx tsc -p test — passed
  • npm test — 187/187 tests passed, 0 failed
  • The full suite, including tests/examples.test.mjs, is green in this environment.

Please take another look when you have a moment.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Note

Copilot was unable to run its full agentic suite in this review.

Copilot review overview

3 open issues
What changed in this PR

Adds support for validating JSON-serialized string enums by introducing a “wire” type wrapper during TypeScript assignment checks, along with new tests and documentation describing the behavior.

Changes:

  • Add a generated __TypeChatJsonWire<T> helper type to accept serialized string-enum values during validate().
  • Extend the test suite with coverage for string enums across nested shapes and for diagnostic targeting with custom module text.
  • Document how string enums are validated from JSON in the TypeScript basic usage guide.
File Description
typescript/​src/​ts/​validate.ts Generates and uses a unique JsonWire helper type in the emitted module text; adjusts missing-property expansion to avoid unwrapping custom type annotations.
typescript/​test/​validate.test.ts Adds test cases for serialized string enums (including nested usage) and for diagnostics when custom module text is used.
site/​src/​docs/​typescript/​basic-usage.md Documents string-enum JSON representation and how the validator handles it (including computed members).

Review effort: Lite

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/test/validate.test.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Comment thread typescript/test/validate.test.ts Resolved
Comment thread typescript/test/validate.test.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 10, 2026 20:52

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Normalization weakens validation by dropping private/protected class constraints and converting the broad object type to {}, allowing previously rejected values.

2 open issues
2 previously missed issues

In code that hasn't changed since last review

High severity Mapping object to {} allows primitive values

typescript/​src/​ts/​validate.ts:63

Mapping the broad object type loses its non-primitive constraint: keyof object is never, so this branch produces {}, which also accepts strings, numbers, and booleans. For example, export interface Response { value: object } now accepts { value: 123 }, whereas the original assignment rejects it. Preserve types with no keys instead of mapping them to {}, and add a regression test that rejects primitive values for an object property.

High severity Mapped types drop private and protected class member constraints

typescript/​src/​ts/​validate.ts:63

The mapped-object branch drops private and protected class members because they are excluded from keyof T, weakening validation even for schemas without enums. For example, export declare class Token { private value: string; label: string; } used by Response { token: Token } now accepts { token: { label: "x" } }, whereas the original assignment rejects it. Preserve private/protected class constraints during normalization and add a regression case with both private and public members.

4 resolved since last review

Review effort: Balanced

@robgruen robgruen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

AI-assisted follow-up review: changes requested

This review was prepared with GitHub Copilot and is submitted at robgruen's explicit request.

Thanks for addressing the earlier callable/constructor and custom-generic diagnostic findings. Those cases now behave correctly in my checks on 05788e4823d6369f626c079c19c656de63a8dd66. The string-enum support, focused documentation, and regression coverage remain useful.

Two issues still need attention before merging; both inline comments include runnable reproductions:

  1. The recursive mapped type drops class-instance constraints. A plain JSON object now satisfies a class-typed property despite lacking its required private member. The pre-PR assignment rejects the same input. This affects schemas without enums and conflicts with #465's requirement to preserve the rest of the schema's validation.
  2. The latest multiline refactor breaks the generated-module test. The helper now contains a newline after =, while the assertion still requires a single-line substring. Please make the assertion whitespace-independent.

Verification

  • Reviewed exact head 05788e4823d6369f626c079c19c656de63a8dd66.
  • Node.js 24.22.1, TypeScript 7.0.2, using existing installed dependencies rather than a fresh npm ci.
  • Library build and test compilation passed.
  • Focused validator suite: 59 passed, 1 failed. The failing test is produces valid TypeScript module text for a simple object; this is a failure introduced by the latest revision, not the previously reported baseline issue.
  • Additional before/after probes confirmed the class-instance regression and checked enum behavior and the earlier callable/constructor fixes.
  • I did not run the full suite. GitHub currently exposes only the successful CLA check for this head.

Please fix these two issues, add the class-instance regression test, and provide updated validation results.

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/test/validate.test.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/test/validate.test.ts Resolved
Comment thread typescript/test/validate.test.ts Resolved
Comment thread typescript/test/validate.test.ts Resolved
Copilot AI max review requested due to automatic review settings November 17, 2026 09:02
@yushiwuzhengjianyuzi

Copy link
Copy Markdown
Contributor Author

Thanks robgruen — both issues from the latest review are addressed in 8acc9d0.

  • The JSON-wire helper now checks a public-shape-only copy against T before mapping. Class instances with private/protected members fail that check and are left untouched, so { token: { value: "unbranded" } } is rejected again while string-enum normalization still works for structural object types. Added an enum-free class regression test.
  • The generated-module assertion now uses a whitespace-tolerant regex.

Verification on 8acc9d0 (Node 24.11.1, TypeScript 7.0.2):

  • npm run build — passed
  • npm test — 383/383 passed, 0 failed

Please take another look when you have a moment.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
@yushiwuzhengjianyuzi

Copy link
Copy Markdown
Contributor Author

All review points are addressed in dc9a39d and 3a14429. Full suite passes 387/387, including tuple, optional, recursive, branded-string, object, and diagnostic regressions.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved
Comment thread typescript/src/ts/validate.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Normalization loses explicit object constraints and rewrites property names as enum aliases, causing incorrect validation results and misleading repair diagnostics.

1 open issue
3 resolved since last review

Review effort: Max

Comment thread typescript/src/ts/validate.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The validator can incorrectly accept primitives for object-wrapper intersections and corrupt property names when rewriting helper-type diagnostics.

1 open issue
1 resolved since last review

Review effort: Max

Comment thread typescript/src/ts/validate.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The test lacks invalid enum cases for lookup and the successful result union branch, so unintended type widening in those paths could go undetected.

No open issues 🎉

1 resolved since last review

Review effort: Max

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.

Support serialized enum values with Zod-style schema normalization

3 participants