Zod 4 support #840

Nicolapps · 2025-11-11T00:14:06Z

This pull request adds full support for Zod 4 in convex-helpers.

Migration

The methods in convex-helpers/server/zod have been moved to convex-helpers/server/zod3. The new Zod 4-compatible methods can be imported from convex-helpers/server/zod4.

For convenience, some methods in convex-helpers/server/zod (zodToConvex, zodOutputToConvex, zodToConvexFields, zodOutputToConvexFields, and withSystemFields) now accept both Zod 3 and Zod 4 schemas. If you’re using Zod 4 in your codebase, we strongly recommend that you import directly from convex-helpers/server/zod4, as it simplifies the work that the TypeScript compiler needs to do.

Codecs support

When using Zod 4.1, developers can benefit from Zod codecs to roundtrip values to/from functions and the database. As explained in https://www.notion.so/convex-dev/Convex-Zod-4-Codecs-integration-294b57ff32ab809fa067fe63c740ca74?source=copy_link, the code of convex-helpers doesn’t need to do anything related to codecs:

When using codecs to encode function arguments, developers can use codecs with Input = Convex value and Output = Developer-facing value
When using codecs to encode function return values, developers can use codecs with Input = Developer-facing value and Output = Convex value
When using codecs to store functions in the database, developers can use codecs with Input = Convex value and Output = Developer-facing value. (convex-helpers doesn’t provide a database wrapper that encodes values with Zod, but if you’re writing one, you would want to call the .encode() and .decode() functions of Zod schemas).

This strategy allows developers to keep using z.transform() in both args and returns, while keeping support for Zod 3 and 4.0.

Implementation details

zid is implemented as a z.custom call with a registry that stores the table name in a WeakMap. I considered extending z.ZodCustom or z.ZodType, but this isn’t officially supported by Zod (see https://discord.com/channels/893487829802418277/1359688107594748054/1367295316365152308).
zodToConvex and zodOutputToConvex support circular schemas (v.any() is returned when a type is used more than once).
z.templateLiteral() is now supported.
z.tuple() is now supported: it might return validators that are more complex than necessary (e.g. [number, number] will be converted to v.union(v.number(), v.number())).
z.literal() now supports literals with multiple values (e.g. z.literal([1, 2, 3])) correctly.
For some types, z.tuple() and z.literal(), the output type is loosened to not assume a specific order in the resulting VUnion. This is necessary since the type information in Zod only contains a union, which don’t have a guaranteed order in TypeScript. The Zod 3 implementation didn’t handle this correctly (but wasn’t updated).
z.record() now uses v.object() when the key is a literal (or union of literals), since v.union(v.literal(…), …) isn’t a valid Convex validator.
Methods that take a Zod schema support both Zod 4 and Zod 4 mini. Methods that return a Zod schema don’t support Zod Mini, but support could be added in the future if necesary.

Acknowledgments

This pull request is inspired by the work done by @ksinghal in #818 and by @natedunn in vendpark#1 and vendpark#2. Thanks to both of you!

Co-Authored-By: Karan Singhal [email protected]
Co-Authored-By: Nate Dunn [email protected]

ianmacartney

looks great!

ianmacartney · 2025-11-15T01:21:53Z

packages/convex-helpers/server/zod4.ts

+  >;
+};
+
+function customFnBuilder(


This function is almost identical to zod3 except for a few lines. Ok for now, but is the eventual plan to deprecate zod3 or to unify or keep as is? It's ok to keep it all separate. maybe a comment to keep them up to date is enough?

Thanks, I added a comment in fdf6e5b

ianmacartney · 2025-11-15T02:05:15Z

packages/convex-helpers/server/zod4.ts

+type IsUnion<T, U extends T = T> = T extends unknown
+  ? [U] extends [T]
+    ? false
+    : true
+  : false;


This is some more magic I don't yet understand.

This comes from https://stackoverflow.com/a/59687759/4652564. I don’t understand in detail how it works, but from my testing it looks like it works correctly.

ianmacartney · 2025-11-15T02:06:18Z

packages/convex-helpers/server/zod4.ts

+type IsUnknownOrAny<T> =
+  // any?
+  0 extends 1 & T
+    ? true
+    : // unknown?
+      unknown extends T
+      ? [T] extends [unknown]
+        ? true
+        : false
+      : false;


are these standard type utilities, llm-produced, or your own invention?

For this one I used a LLM to solve the following problems:

knowing whether a generic type is any

knowing whether a generic type is unknown

I got consistent answers after asking multiple times and my type tests pass, so I think that the solution is correct

I see the same solution for IsAny being used here: https://github.com/remix-run/react-router/blob/main/packages/react-router/lib/types/utils.ts

and I also see a simpler IsUnknown type in the TypeScript codebase:

https://github.com/microsoft/TypeScript/blob/cc2610fd347127c28609b4fca6fa9d55ee5063c6/tests/cases/conformance/types/unknown/unknownType2.ts#L3

so I simplified the type in a262a74

ianmacartney · 2025-11-15T02:12:18Z

packages/convex-helpers/server/zod4.ts

+      vRequired(valueValidator),
+    );
+
+    function extractStringLiterals(


any reason these helper functions can't be outside of the function body? not sure if it has an impact/ the interpreter is smart enough, but I wouldn't want every invocation of this function to create these functions if not necessary

No, they were just here to define them in the only place where they are used. I moved them to the global scope in e43940d

ianmacartney · 2025-11-15T02:13:36Z

packages/convex-helpers/server/zod4.ts

+                              >
+                            : never;
+
+function vRequired(validator: GenericValidator) {


one optimization would be to return the existing validator if it's already required

Thanks, I did it in 54e0622725e77f7de84673b4bc07f7edc84f5e76

ianmacartney · 2025-11-15T02:14:23Z

packages/convex-helpers/server/zod4.ts

+
+type NotUndefined<T> = Exclude<T, undefined>;
+
+type VRequired<T extends Validator<any, OptionalProperty, any>> =


do you think this would be useful in the core package? or just inline it here to start?

Yes, this is a good idea. I can do this as a follow-up task, I created an issue at #847

Nicolapps

Thanks @ianmacartney for your review!

Nicolapps · 2025-11-15T02:21:58Z

packages/convex-helpers/server/zod4.ts

+type IsUnion<T, U extends T = T> = T extends unknown
+  ? [U] extends [T]
+    ? false
+    : true
+  : false;


This comes from https://stackoverflow.com/a/59687759/4652564. I don’t understand in detail how it works, but from my testing it looks like it works correctly.

Nicolapps · 2025-11-15T02:25:56Z

packages/convex-helpers/server/zod4.ts

+  >;
+};
+
+function customFnBuilder(


Thanks, I added a comment in fdf6e5b

Nicolapps · 2025-11-15T02:27:34Z

packages/convex-helpers/server/zod4.ts

+      vRequired(valueValidator),
+    );
+
+    function extractStringLiterals(


No, they were just here to define them in the only place where they are used. I moved them to the global scope in e43940d

Nicolapps · 2025-11-15T02:31:02Z

packages/convex-helpers/server/zod4.ts

+                              >
+                            : never;
+
+function vRequired(validator: GenericValidator) {


Thanks, I did it in 54e0622725e77f7de84673b4bc07f7edc84f5e76

Nicolapps · 2025-11-15T02:32:00Z

packages/convex-helpers/server/zod4.ts

+
+type NotUndefined<T> = Exclude<T, undefined>;
+
+type VRequired<T extends Validator<any, OptionalProperty, any>> =


Yes, this is a good idea. I can do this as a follow-up task, I created an issue at #847

Nicolapps · 2025-11-15T02:37:48Z

packages/convex-helpers/server/zod4.ts

+type IsUnknownOrAny<T> =
+  // any?
+  0 extends 1 & T
+    ? true
+    : // unknown?
+      unknown extends T
+      ? [T] extends [unknown]
+        ? true
+        : false
+      : false;


For this one I used a LLM to solve the following problems:

knowing whether a generic type is any

knowing whether a generic type is unknown

I got consistent answers after asking multiple times and my type tests pass, so I think that the solution is correct

Nicolapps · 2025-11-15T02:40:03Z

packages/convex-helpers/server/zod4.ts

+type IsUnknownOrAny<T> =
+  // any?
+  0 extends 1 & T
+    ? true
+    : // unknown?
+      unknown extends T
+      ? [T] extends [unknown]
+        ? true
+        : false
+      : false;


I see the same solution for IsAny being used here: https://github.com/remix-run/react-router/blob/main/packages/react-router/lib/types/utils.ts

and I also see a simpler IsUnknown type in the TypeScript codebase:

https://github.com/microsoft/TypeScript/blob/cc2610fd347127c28609b4fca6fa9d55ee5063c6/tests/cases/conformance/types/unknown/unknownType2.ts#L3

so I simplified the type in a262a74

Nicolapps added 30 commits October 30, 2025 20:51

Fix Zod dependency requirement

0615b63

Move to Zod3

4d05fb1

Add references to existing types

c41aafd

Fix zod3 test imports

f5e6135

Progress

b45cbf2

Lock files

e3ad81a

Record support (WIP)

53744ce

Arrays

ef87833

Fixes

5929d06

Attempt to fix

5aed0f0

Fix union test

fd08b49

Fix union

a6d056f

Fix union

95519f4

Remove Array support for now

8789db9

Fix Object implementation

955e727

any + bytes

35481ca

Zod to Convex (WIP)

1e3fa1f

Readonly

07dedc5

WIP

54082c3

Fix zodToConvexFields

392180f

Fix tests

57dd565

Use Zod Core

5e96b2c

Fix constraint

7b62cf4

Tuple tests

8897c03

Optional/nullable

db75996

Branded

a7f16b7

Default

dcc123b

z.record + doc

5e460f0

Fix unions

a8a3de4

Reorganize tests

ddfeb25

Nicolapps added 9 commits November 13, 2025 15:59

Fix type comparison

659f6da

Fix nullable

d48cb71

Add documentation for Zod Mini support

943daa9

Make withSystemFields a namde function

2f4db83

Improve doc

cd90600

Implement functions that support both Zod 3 and 4

90a891e

Fix ID test

5d06d88

Use WeakSet

8bc3573

Consistent comment style

5fdeb97

Nicolapps requested a review from ianmacartney November 14, 2025 01:22

Merge branch 'main' into nicolas/zod-4-support

b40548b

Nicolapps changed the title ~~WIP: Zod 4 support~~ Zod 4 support Nov 14, 2025

Nicolapps and others added 6 commits November 13, 2025 17:44

Fix linter

e4b62cf

pin prettier

dc5f051

add type to customInput

1b6a32a

Merge branch 'main' into nicolas/zod-4-support

59630e0

test custom function capabilities

8b24482

add type to customInput for some typecheckers that don't like it as is

eac723c

ianmacartney approved these changes Nov 15, 2025

View reviewed changes

Nicolapps added 4 commits November 14, 2025 18:25

Add comment in customFnBuilder

fdf6e5b

Move functions to the global scope

e43940d

vRequired: don’t clone required validators

54e0622

Simplify IsUnknown check

a262a74

Nicolapps commented Nov 15, 2025

View reviewed changes

Nicolapps linked an issue Nov 15, 2025 that may be closed by this pull request

Update zod validation to support Zod 4 #558

Closed

Nicolapps merged commit 6472eca into main Nov 15, 2025
3 checks passed

Nicolapps deleted the nicolas/zod-4-support branch November 15, 2025 02:41

This was referenced Nov 15, 2025

Update zod validation to support Zod 4 #558

Closed

Zid can't be in a z.array #793

Closed

Zod 4 Support #818

Closed


		type NotUndefined<T> = Exclude<T, undefined>;

		type VRequired<T extends Validator<any, OptionalProperty, any>> =

Zod 4 support #840

Zod 4 support #840

Conversation

Nicolapps commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Migration

Codecs support

Implementation details

Acknowledgments

Uh oh!

ianmacartney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nicolapps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Nicolapps commented Nov 11, 2025 •

edited

Loading