Skip to content

fix: preserve unique tags with defaulted discriminators - #6582

Merged
colinhacks merged 2 commits into
mainfrom
fix/defaulted-discriminators-6577
Sep 9, 2026
Merged

colinhacks merged 2 commits into
mainfrom
fix/defaulted-discriminators-6577

Conversation

@colinhacks

@colinhacks colinhacks commented Sep 9, 2026 •

Copy link
Copy Markdown
Owner

Preserve explicitly tagged parsing when multiple discriminated-union members have defaulted tags. A shared map builder marks colliding undefined values as ambiguous; missing tags fail validation, while unique tags retain direct dispatch. Other duplicate values remain schema errors.

There are no schema-type checks, wrapper walks, new options, or new instance properties. The lookup helper uses the same map builder and rejects ambiguous lookup. Nested unions omit an unroutable undefined from their discriminator metadata; backward encoding of undefined uses the existing union fallback so forward-only metadata cannot select the wrong sibling. Defined tags retain their encoding fast path. The compiler keeps its existing interpreter fallback for collisions rather than introducing a second dispatch policy.

Local build, lint, resolution, integration, and the full suite pass, including 8,243 tests on each of TypeScript 5.5.4, 6.0.3, and 7.0.2. Plain-Node ESM/CJS probes pass for both classic and Mini. The encoding regression has synchronous and asynchronous coverage, and the API reference documents ambiguous lookup.

Measurement Base → change
Parse, median of ten process minima 38.06 → 38.44 ns (+1.0%)
Defined-tag encode, median of ten process minima 48.21 → 48.03 ns (-0.4%)
Construction, median of ten process minima 802.6 → 804.1 ns (+0.2%)
Classic discriminated-union fixture, gzip 21,159 → 21,248 B (+89 B)
Mini discriminated-union fixture, gzip 5,238 → 5,339 B (+101 B)
Classic / Mini object-only fixtures unchanged
Fresh two-member union, retained heap 9,136 → 9,136 B in repeated isolated measurements
Shared-member union, unparsed / parsed approximately 921 / 1,098 B on both revisions

Runtime measurements on f1f96bea use ten interleaved rounds, alternating which revision runs first, fixed iteration counts, and GC between samples. Host load stayed at 5.44–6.10; no meaningful runtime regression was observed. Earlier high-load timing samples were discarded. The initial broad memory run also showed a +288 B union result that did not reproduce in two isolated comparisons; the 500-resource catalogue remained approximately 38.53 MiB on both revisions.

Closes #6577.

@colinhacks
colinhacks marked this pull request as ready for review September 9, 2026 18:20
Copilot AI lite review requested due to automatic review settings September 9, 2026 18:20

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 public lookup ambiguity contract still needs documentation, so final human approval is warranted.

Pull request overview

Preserves explicit discriminator routing when multiple union members default to undefined, while rejecting ambiguous missing tags.

Changes:

  • Centralizes discriminator-map construction and ambiguity handling.
  • Preserves nested-union metadata and compiler fallback behavior.
  • Adds regression coverage for defaults, collisions, lookup, nesting, and duplicates.
File summaries
File Summary
packages/zod/src/v4/core/schemas.ts Implements ambiguity-aware discriminator handling.
packages/zod/src/v4/core/compile.ts Preserves interpreter fallback for collisions.
packages/zod/src/v4/classic/tests/discriminated-unions.test.ts Adds comprehensive regression tests.
Review details

Suppressed comments (1)

packages/zod/src/v4/core/schemas.ts:2640

  • This new branch makes a previously valid schema state throw when the caller asks for an ambiguous undefined, but getDiscriminatedOption's public type and docs still describe every declared discriminator value as returning an option (for example, two optional members make undefined a declared value). Please document the ambiguity/error contract in the public API and the helper's JSDoc so callers do not assume a declared value is always retrievable.
  if (option === null) throw new Error(`Ambiguous discriminator value "${String(value)}"`);
  • Files reviewed: 3/3 changed files
  • Comments generated: 0
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@pullfrog pullfrog Bot 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.

Important

Nested discriminator metadata can silently misroute backward encoding; this should be addressed before merging.

Reviewed changes Reviewed the runtime map semantics, getDiscriminatedOption() alignment, compiler fallback, nested-union metadata, and the added behavior tests.

  • Ambiguous undefined dispatch — duplicate absent-value claims no longer block unique explicit tags, while other duplicate values remain schema errors.
  • Shared lookup behavior — runtime parsing and getDiscriminatedOption() now use the same map construction and reject ambiguous lookup.
  • Nested and compiled unions — nested metadata omits forward-unroutable undefined, and compiler collisions continue through interpreter fallback.
  • Regression coverage — tests exercise wrapper variants, option order, synchronous and asynchronous parsing, lookup, nesting, and unionFallback.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using GPT Sol | 𝕏

Comment thread packages/zod/src/v4/core/schemas.ts Resolved
@colinhacks
colinhacks marked this pull request as draft September 9, 2026 18:34

@pullfrog pullfrog Bot 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.

✅ No new issues found.

Reviewed changes Reviewed the full PR through f1f96bea, including the follow-up that resolves the prior nested-encoding finding.

  • Ambiguous absent tags — repeated undefined claims now reject ambiguous input without disabling direct dispatch for unique explicit tags.
  • Nested encoding — backward parsing bypasses forward-only dispatch for an absent tag, allowing ordinary union matching to reach the correct codec-backed member.
  • Shared contracts — getDiscriminatedOption(), nested propValues, compiler fallback, and public documentation remain aligned with the runtime policy.
  • Regression coverage — exact sync and async assertions cover the original compatibility case, non-undefined collisions, nested forward routing, and the previously failing backward-encoding path.

Pullfrog  | View workflow run | Using GPT Sol | 𝕏

@colinhacks
colinhacks merged commit b12aa52 into main Sep 9, 2026
9 checks passed
@colinhacks
colinhacks deleted the fix/defaulted-discriminators-6577 branch September 9, 2026 19:20

This branch was successfully deployed

1 active deployment
Preview – zod-v4 — f1f96bea Deployed Sep 9, 2026 by vercel[bot]
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.

Compatibility reconsideration: defaulted discriminator fields prevent validation of explicitly tagged commands

2 participants