Zod 4 Support

[ksinghal]

Summary

• This is an initial effort towards implementing zod4 support.
• Add Zod v4 monolithic integration for Convex in packages/convex-helpers/server/zod4.ts.
• Strongly typed implementation (no loose any for public APIs); lints clean.

Key Changes

• New API surface in server/zod4.ts: zid, zBrand, zCustomQuery/Mutation/Action, withSystemFields, zodToConvex, zodToConvexFields, zodOutputToConvex, convexToZod, toConvexJS, fromConvexJS, convexCodec.
• Package export: add ./server/zod4 subpath (types + default) in packages/convex-helpers/package.json.

Documentation

• Expanded Zod Validation section for v4 in packages/convex-helpers/README.md (see README for usage and examples).

Tests

• Added smoke test packages/convex-helpers/server/zod4.test.ts (parity suite to follow).

Peer Dependency

• Update zod peer range to ^3.22.4 || ^4.1.12 (v4.1+ required).

Compatibility

• Existing v3 helper (server/zod) remains unchanged; new v4 functionality is opt-in via ./server/zod4.

Follow-ups

• Port full v3 parity tests to zod4.test.ts.
• Add an end-to-end example module using server/zod4.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Fixes #558
Fixes #793

[ksinghal]

Huge credit to @panzacoder for his implementation in Zodvex, which this is heavily inspired by!!

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/convex-helpers@818

commit: e69aae5

[natedunn]

Casting any here would just override the types, no? Same for zCustomMuation and zCustomAction. Seems to be the case so far in my limited testing:

[natedunn]

Different spot but same idea?

[natedunn]

Very quick update before bed: re-adding CustomBuilder as seen in the v3 version, instead of any does seem to fix the issue related to the custom functions. We might need to generally review the any usage in order to preserve type-safety. I might have some time tomorrow to take a full pass on it.

[natedunn]

Didn't have enough time to complete a full pass yet. But making some progress though my own adjustments and using a bit from @panzacoder's wonderful zodvex project, mostly helping me with the zodToConvex() feature. Hopefully that is ok, let me know if you have any objection.

[Nicolapps]

Suggested change

	import { z } from "zod";
	import { z } from "zod/v4/core";

I think that this is change is necessary. With the current import, users of convex-helpers that use Zod 3 would get the /zod4 types incorrectly defined based on Zod 3 (see https://zod.dev/library-authors?id=how-to-support-zod-4). According to the same page, we need to import from zod/v4/core, unless we do something that can’t work with Zod Mini (but they strongly recommend against doing so).