feat: allow 'when' parameter in .superRefine by vilvai · Pull Request #5741 · colinhacks/zod

vilvai · 2026-03-02T14:10:09Z

This PR adds the params object to .superRefine which allows using when parameter to run the superrefine validation even when the base schema fails, similar to how .refine works currently

See my issue about this: #5739

vercel · 2026-03-02T14:10:16Z

@vilvai is attempting to deploy a commit to the colinhacks Team on Vercel.

A member of the Team first needs to authorize it.

pullfrog · 2026-04-27T22:54:09Z

TL;DR — Adds an optional params argument to .superRefine() (matching the existing .refine() API) so that a when callback can control whether the refinement runs — most notably allowing super-refinements to execute even when the base schema has errors.

Key changes

Add $ZodSuperRefineParams interface to core — introduces a when option for _superRefine, forwarding it to the underlying _check call
Thread params through classic and mini APIs — both superRefine() helpers and the ZodType.superRefine method now accept and forward the optional params object
Improve when JSDoc in $ZodCheckDef — clarifies the doc comment to match the new $ZodSuperRefineParams wording
Add tests for when in .superRefine() — two tests verify that a when callback controls whether the refinement runs when the base schema has errors

_{Summary ｜ 5 files ｜ 2 commits ｜ base: main ← main}

Before: .superRefine() accepted only a refinement function and always used the default when behavior (skip when aborted), meaning it could never run when the base schema produced errors.
After: .superRefine() accepts an optional second argument ({ when? }) that lets callers override the default gating — e.g. using a partial safeParse in when to run cross-field refinements even when some fields fail.

The new $ZodSuperRefineParams interface intentionally exposes only when (not message, path, abort, etc.) because superRefine pushes issues manually via ctx.addIssue. The params object is forwarded to _check which already supports these options, so the implementation is a thin passthrough.

How does the when callback work?

when receives the parse payload and returns a boolean. When it returns true the refinement executes regardless of earlier failures. A common pattern is to partially validate the input (e.g. baseSchema.pick({ foo: true }).safeParse(value).success) so the refinement only runs when the fields it depends on are valid.

api.ts · checks.ts · classic/schemas.ts · mini/schemas.ts · refine.test.ts

^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

pullfrog

Important

The JSDoc on $ZodSuperRefineParams.when describes the default behavior incorrectly — worth fixing before merge.

Added $ZodSuperRefineParams interface with a when option and threaded it through _superRefine → _check in both classic and mini APIs
Added two tests covering the when: () => true (superRefine runs despite base schema failure) and when: () => false (superRefine skipped) cases

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

pullfrog · 2026-04-27T23:44:16Z

+ * `when` — whether to run the refinement at all.
+ */
+export interface $ZodSuperRefineParams {
+  /** If provided, this refinement will only be executed if the function returns `true`. Defaults to `payload => z.util.isAborted(payload)`. */


The JSDoc says the default is payload => z.util.isAborted(payload), but the actual default behavior (when when is omitted) is to skip the check when the payload is aborted — effectively the opposite. Additionally, z.util.isAborted doesn't exist in v4; the internal helper is util.aborted.

Note: this same misleading JSDoc exists on $ZodCheckDef.when in checks.ts:16, so it's a pre-existing issue that was copied here. Still, it would be good to fix it in this PR since it's in newly added code.

Suggested wording:

/** If provided, this refinement will only be executed when the function returns `true`. When omitted, the refinement is skipped if the base schema produced any aborting issues. */

Suggested change

/** If provided, this refinement will only be executed if the function returns `true`. Defaults to `payload => z.util.isAborted(payload)`. */

/** If provided, this refinement will only be executed when the function returns `true`. When omitted, the refinement is skipped if the base schema produced any aborting issues. */

The previous `string | $ZodCustomParams` type advertised fields that don't do anything useful for `.superRefine` — `error`/`message`/`path` are never read because the refinement pushes its own issues via `ctx.addIssue`, and `abort` is redundant with the per-issue `fatal` flag (which sets `continue: false` directly on the issue, with finer granularity than a check-level toggle). Introduce a dedicated `$ZodSuperRefineParams` interface exposing only `when` — the one execution-control option that genuinely gates whether the refinement runs at all. Also wire `params` through in `mini` for parity.

pullfrog

No new issues. Reviewed the following changes:

Fixed the JSDoc on $ZodSuperRefineParams.when to accurately describe the default behavior
Fixed the same misleading JSDoc on $ZodCheckDef.when in checks.ts (the pre-existing issue flagged in the prior review)
Removed the verbose block comment on the $ZodSuperRefineParams interface

Prior review feedback:

JSDoc on $ZodSuperRefineParams.when describes default behavior incorrectly — addressed (also fixed in $ZodCheckDef.when)

^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

pullfrog

Approving — prior JSDoc feedback was fully addressed and no new issues found.

^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

colinhacks · 2026-04-29T04:35:11Z

Narrowed the params type on .superRefine to just { when } for now, rather than the full .refine params shape — when is really the only one that makes sense here, since the refinement pushes its own issues via ctx.addIssue (so error/message/path aren't read) and abort is redundant with the per-issue fatal flag. Thanks for picking this up 👍

Note: this comment was produced by an AI coding assistant.

colinhacks · 2026-04-30T16:15:33Z

Landed in Zod 4.4

allow 'when' parameter in .superRefine

37dc8fd

vilvai changed the title ~~allow 'when' parameter in .superRefine~~ feat: allow 'when' parameter in .superRefine Mar 2, 2026

vercel Bot had a problem deploying to Preview – zod-v4 March 2, 2026 14:12 Failure

vilvai mentioned this pull request Mar 2, 2026

.superRefine is missing "when" parameter #5739

Closed

vercel Bot deployed to Preview – zod-v4 April 27, 2026 22:54 View deployment

colinhacks force-pushed the main branch 2 times, most recently from 28782de to afc91d1 Compare April 27, 2026 23:39

vercel Bot deployed to Preview – zod-v4 April 27, 2026 23:40 View deployment

pullfrog Bot reviewed Apr 27, 2026

View reviewed changes

colinhacks force-pushed the main branch from afc91d1 to 45a06f2 Compare April 27, 2026 23:48

vercel Bot deployed to Preview – zod-v4 April 27, 2026 23:49 View deployment

colinhacks merged commit 65fab33 into colinhacks:main Apr 27, 2026
4 of 7 checks passed

pullfrog Bot reviewed Apr 27, 2026

View reviewed changes

colinhacks mentioned this pull request Apr 28, 2026

feat: add when param support to superRefine #5847

Closed

Anoesj mentioned this pull request Apr 30, 2026

Refine validations on object definitions don't get triggered until all fields in the object exist. #479

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: allow 'when' parameter in .superRefine#5741

feat: allow 'when' parameter in .superRefine#5741
colinhacks merged 2 commits into
colinhacks:mainfrom
vilvai:main

vilvai commented Mar 2, 2026

Uh oh!

vercel Bot commented Mar 2, 2026

Uh oh!

pullfrog Bot commented Apr 27, 2026 •

edited

Loading

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot Apr 27, 2026

Uh oh!

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot left a comment

Uh oh!

colinhacks commented Apr 29, 2026

Uh oh!

colinhacks commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	/** If provided, this refinement will only be executed if the function returns `true`. Defaults to `payload => z.util.isAborted(payload)`. */
	/** If provided, this refinement will only be executed when the function returns `true`. When omitted, the refinement is skipped if the base schema produced any aborting issues. */

Uh oh!

Conversation

vilvai commented Mar 2, 2026

Uh oh!

vercel Bot commented Mar 2, 2026

Uh oh!

pullfrog Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key changes

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

colinhacks commented Apr 29, 2026

Uh oh!

colinhacks commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pullfrog Bot commented Apr 27, 2026 •

edited

Loading