Update zod validation to support Zod 4

[thebruceyang]

I ran the zod 4 update docs against server/zod. Hope this helps (at least logs) some required updates:

Key Compatibility Issues:

1. Internal Structure Access:
   The library heavily relies on accessing ._def directly:

   const typeName: ZodFirstPartyTypeKind | "ConvexId" = zod._def.typeName;

   But the Zod 4 migration guide explicitly states:

   moves ._def
   The ._def property is now moved to ._zod.def.
   

   This is a critical issue that would prevent the library from working correctly with Zod 4.

2. Function Returns API:
   The library does have some backward compatibility:

   let returns = fn.returns ?? fn.output;

   It checks for both returns and output, which is good, but the core function API in Zod 4 has changed significantly.

3. Schema Access Pattern:
   Many of the helper functions like zodToConvex and zodOutputToConvex directly access internal properties of Zod schemas that have changed in Zod 4.

What This Means:

1. This version of convex-helpers is not compatible with Zod 4 without modifications.

2. You would need:

   • An updated version of convex-helpers specifically built for Zod 4
   • To modify the library code to use ._zod.def instead of ._def
   • To update any other internal structure access patterns

3. The returns field mentioned in the previous document might work because the library explicitly checks for both returns and output, but the underlying validation mechanism would still fail due to the internal structure changes.

[ianmacartney]

I'm going to wait until it's out of beta to make any changes, and I wonder if the zod4 version should get published as its own library - I've wondered if ***@***.***/zod` would be a good move - to start separating helpers into first-class packages

…

On Wed, Apr 30, 2025 at 1:21 PM Bruce Yang ***@***.***> wrote: *thebruceyang* created an issue (get-convex/convex-helpers#558) <#558> AI says: After examining the library code, I can see that there are potential compatibility issues with Zod 4: Key Compatibility Issues: 1. *Internal Structure Access*: The library heavily relies on accessing ._def directly: const typeName: ZodFirstPartyTypeKind | "ConvexId" = zod._def.typeName; But the Zod 4 migration guide explicitly states: moves ._def The ._def property is now moved to ._zod.def. This is a critical issue that would prevent the library from working correctly with Zod 4. 2. *Function Returns API*: The library does have some backward compatibility: let returns = fn.returns ?? fn.output; It checks for both returns and output, which is good, but the core function API in Zod 4 has changed significantly. 3. *Schema Access Pattern*: Many of the helper functions like zodToConvex and zodOutputToConvex directly access internal properties of Zod schemas that have changed in Zod 4. What This Means: 1. This version of convex-helpers is *not compatible* with Zod 4 without modifications. 2. You would need: - An updated version of convex-helpers specifically built for Zod 4 - To modify the library code to use ._zod.def instead of ._def - To update any other internal structure access patterns 3. The returns field mentioned in the previous document might work because the library explicitly checks for both returns and output, but the underlying validation mechanism would still fail due to the internal structure changes. — Reply to this email directly, view it on GitHub <#558>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW3WKHCQWD4NXVJIK4324EWGNAVCNFSM6AAAAAB4GRPJX2VHI2DSMVQWIX3LMV43ASLTON2WKOZTGAZTENBSGY4DOMQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[ianmacartney]

Feel free to start a branch that makes the changes based on the migration guide though! That'd be a big help

…

On Wed, Apr 30, 2025 at 1:25 PM Ian Macartney ***@***.***> wrote: I'm going to wait until it's out of beta to make any changes, and I wonder if the zod4 version should get published as its own library - I've wondered if ***@***.***/zod` would be a good move - to start separating helpers into first-class packages On Wed, Apr 30, 2025 at 1:21 PM Bruce Yang ***@***.***> wrote: > *thebruceyang* created an issue (get-convex/convex-helpers#558) > <#558> > > AI says: > After examining the library code, I can see that there are potential > compatibility issues with Zod 4: > Key Compatibility Issues: > > 1. > > *Internal Structure Access*: > The library heavily relies on accessing ._def directly: > > const typeName: ZodFirstPartyTypeKind | "ConvexId" = zod._def.typeName; > > But the Zod 4 migration guide explicitly states: > > moves ._def > The ._def property is now moved to ._zod.def. > > This is a critical issue that would prevent the library from working > correctly with Zod 4. > 2. > > *Function Returns API*: > The library does have some backward compatibility: > > let returns = fn.returns ?? fn.output; > > It checks for both returns and output, which is good, but the core > function API in Zod 4 has changed significantly. > 3. > > *Schema Access Pattern*: > Many of the helper functions like zodToConvex and zodOutputToConvex > directly access internal properties of Zod schemas that have changed in Zod > 4. > > What This Means: > > 1. > > This version of convex-helpers is *not compatible* with Zod 4 without > modifications. > 2. > > You would need: > - An updated version of convex-helpers specifically built for Zod 4 > - To modify the library code to use ._zod.def instead of ._def > - To update any other internal structure access patterns > 3. > > The returns field mentioned in the previous document might work > because the library explicitly checks for both returns and output, > but the underlying validation mechanism would still fail due to the > internal structure changes. > > — > Reply to this email directly, view it on GitHub > <#558>, or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AACZQW3WKHCQWD4NXVJIK4324EWGNAVCNFSM6AAAAAB4GRPJX2VHI2DSMVQWIX3LMV43ASLTON2WKOZTGAZTENBSGY4DOMQ> > . > You are receiving this because you are subscribed to this thread.Message > ID: ***@***.***> >

[ksanfi]

Probably relevant colinhacks/zod#4371

[ianmacartney]

Totally! I really like the approach and I think it would make sense to support this in a similar way with both a convex/helpers/zod3 and convex/helpers/zod4 endpoint that where (for now) the bare /zod endpoint exports everything from /zod3

The reason I'm hesitant to support both in the same functions is everyone would end up with twice as much code as they need. With tree shaking it can only import what it needs.

Anyone brave enough to start the zod4 implementation? I learned a lot about Zod making the last one.
I have a lot on my plate and the number of users who would benefit from this isn't (yet) very high.

[thlmenezes]

Anyone brave enough to start the zod4 implementation?

I'm currently making an attempt (started today); the types are scarily complex, but will give updates as I go.

I was eager to try out Zod v4 in my project, did not expect to get so close to the plumbing so soon, lol

[ianmacartney]

good luck!

…

On Mon, Jun 2, 2025 at 2:54 PM Thales Menezes ***@***.***> wrote: *thlmenezes* left a comment (get-convex/convex-helpers#558) <#558 (comment)> Anyone brave enough to start the zod4 implementation? I'm currently making an attempt (started today); the types are scarily complex, but will give updates as I go. I was eager to try out Zod v4 in my project, did not expect to get so close to the plumbing so soon, lol — Reply to this email directly, view it on GitHub <#558 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW7IYVXADAKZTULTJU33BTBX5AVCNFSM6AAAAAB4GRPJX2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSMZSGY2DENJTHE> . You are receiving this because you commented.Message ID: ***@***.***>

[ianmacartney]

#665 is aiming to address this

[SamJB123]

Just posted #701 for testing/refining. I can very much relate @thlmenezes - it is a can of worms! There's enough going on in v4's internals that you probably spotted useful things I didn't, so please go nuts on it