zodvex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zodvex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# zodvex
+#### [Zod](https://zod.dev/) + [Convex](https://www.convex.dev/)
+
+> Heavily inspired by [convex-helpers](https://github.com/get-convex/convex-helpers?tab=readme-ov-file). Some of those utilities are still being directly imported.
+
+Zod v4 → Convex validator mapping with correct optional vs nullable semantics. Thin, practical glue around `convex-helpers` that preserves Convex’s notion of optional fields and offers ergonomic wrappers/codecs.
+
+Why
+
+- Convex treats optional object fields only when wrapped with `v.optional(...)`.
+- Some mappers represent `.optional()` as `v.union(T, v.null())`, which still requires the key and changes semantics.
+- zodvex normalizes per-field validators so that:
+  - optional only → `v.optional(T)`
+  - nullable only → `v.union(T, v.null())`
+  - optional + nullable → `v.optional(v.union(T, v.null()))`
+
+What’s Included
+
+- Low-level mapping helpers
+  - `zodToConvex(z: ZodTypeAny): Validator`
+  - `zodToConvexFields(shapeOrObject: ZodRawShape | Record<string, ZodTypeAny> | ZodObject<any>): Record<string, Validator>`
+- Function wrappers (typed, Zod-validated)
+  - `zQuery(query, input, handler, { returns? })`
+  - `zMutation(mutation, input, handler, { returns? })`
+  - `zAction(action, input, handler, { returns? })`
+  - `zInternalQuery(...)`, `zInternalMutation(...)`, `zInternalAction(...)`
+  - Input can be a Zod object, a raw shape object, or a single Zod type. If a single Zod type is provided, args normalize to `{ value: ... }`.
+  - Optional `returns` lets you specify a Zod schema for return validation (see notes below for Dates/encoding).
+- Codecs
+  - `convexCodec(schema)` with:
+    - `toConvexSchema()` → Convex validators (object fields or a single validator)
+    - `encode(data)` → zod-shaped data → Convex-safe JSON (omits `undefined`, converts `Date` → timestamp)
+    - `decode(data)` → Convex JSON → zod-shaped data (timestamps → `Date`)
+    - `pick({ key: true })` → derive a sub-codec (ZodObject only)
+- Table helper
+  - `zodTable(name, zodObject)` → returns a helper with:
+    - `.table` → feed into `defineSchema`
+    - `.schema` → original Zod schema
+    - `.codec` → codec built from the schema (`toConvexSchema/encode/decode`)
+- CRUD helper
+  - `zCrud(table, queryBuilder, mutationBuilder)` → returns `{ create, read, paginate, update, destroy }` using Zod-validated args and `zid(tableName)`
+
+Usage
+
+Define a table from Zod in one place
+
+```ts
+import { z } from 'zod'
+import { zodTable } from 'zodvex'
+
+const zAgencies = z.object({
+  name: z.string(),
+  managerList: z.array(z.string()).optional() // → v.optional(v.array(v.string()))
+})
+
+export const Agencies = zodTable('agencies', zAgencies)
+// In schema.ts → Agencies.table.index(...)
+```
+
+Zod-validated Convex functions
+
+```ts
+import { z } from 'zod'
+import { query, mutation } from './_generated/server'
+import { zQuery, zMutation } from 'zodvex'
+
+export const getById = zQuery(
+  query,
+  { id: z.string() },
+  async (ctx, { id }) => ctx.db.get(id)
+)
+
+export const setName = zMutation(
+  mutation,
+  z.object({ id: z.string(), name: z.string() }),
+  async (ctx, { id, name }) => ctx.db.patch(id, { name })
+)
+
+// Single-value args normalize to { value }
+export const ping = zQuery(query, z.string(), async (ctx, { value }) => value)
+```
+
+CRUD scaffold from a table
+
+```ts
+import { zCrud } from 'zodvex'
+import { query, mutation } from './_generated/server'
+import { Agencies } from './schemas/agencies'
+
+export const agenciesCrud = zCrud(Agencies, query, mutation)
+// agenciesCrud.create/read/paginate/update/destroy
+```
+
+Codec usage
+
+```ts
+import { convexCodec } from 'zodvex'
+import { z } from 'zod'
+
+const zUser = z.object({
+  name: z.string(),
+  birthday: z.date().optional()
+})
+
+const UserCodec = convexCodec(zUser)
+const validators = UserCodec.toConvexSchema() // for Table(...)
+const toWrite = UserCodec.encode({ name: 'A', birthday: new Date() }) // Date → timestamp
+const toRead = UserCodec.decode({ name: 'A', birthday: Date.now() }) // timestamp → Date
+```
+
+Behavior & Semantics
+
+- Optional vs nullable
+  - `.optional()` becomes `v.optional(T)`
+  - `.nullable()` becomes `v.union(T, v.null())`
+  - Both → `v.optional(v.union(T, v.null()))`
+- Arrays/objects/records
+  - Mapping uses Zod v4 public APIs (`shape`, `element`, `options`, `valueType`).
+- Returns validation
+  - If you supply `returns`, wrappers validate the handler’s return value with the Zod schema and encode it to Convex-safe JSON (e.g., `z.date()` → timestamp) before returning.
+- Numbers
+  - `z.number()` maps to `v.float64()` to match Convex JSON. If you need integers, prefer `z.bigint()` (→ `v.int64()`) or handle integer checks at runtime.
+- IDs
+  - Use `zid('table')` from `convex-helpers/server/zodV4` inside Zod schemas for Convex Ids.
+- Fallbacks
+  - Unsupported Zod types (e.g., `ZodEffects` transforms, `ZodTuple`, `ZodIntersection`, maps/sets) fall back to `v.any()`.
+
+Compatibility
+
+- Zod v4 only. This library uses only Zod’s public v4 APIs and does not attempt v3 compatibility.
+
+Notes
+
+- Defaults imply optional at the Convex schema level; apply runtime defaults in app code as needed.
+- This package builds on `convex-helpers/server/zodV4` and post-processes validators to preserve Convex’s optional/null semantics.
+
+Install
+
+- Peer dependencies (must be installed by the host app):
+  - `zod` (v4)
+  - `convex` (>= 1.27)
+  - `convex-helpers` (>= 0.1.101-alpha.1)
+
+Using pnpm:
+
+```bash
+# add peers (if not already present)
+pnpm add zod convex convex-helpers
+
+# add this package
+pnpm add zodvex
+```
+
+Using npm:
+
+```bash
+npm install zod convex convex-helpers
+npm install zodvex
+```
+
+Using yarn:
+
+```bash
+yarn add zod convex convex-helpers
+yarn add zodvex
+```

package/dist/index.d.mts

@@ -0,0 +1,128 @@
+import * as convex_values from 'convex/values';
+import { Validator, PropertyValidators } from 'convex/values';
+import { z } from 'zod';
+import * as convex_server from 'convex/server';
+import { QueryBuilder, RegisteredQuery, DefaultFunctionArgs, MutationBuilder, RegisteredMutation, ActionBuilder, RegisteredAction, FunctionVisibility, GenericDataModel, GenericQueryCtx, GenericMutationCtx, GenericActionCtx } from 'convex/server';
+import { CustomBuilder, Customization } from 'convex-helpers/server/customFunctions';
+import { VFloat64 } from './validators.js';
+
+declare function makeUnion(members: any[]): any;
+declare function getObjectShape(obj: z.ZodObject<any>): Record<string, z.ZodTypeAny>;
+declare function analyzeZod(schema: z.ZodTypeAny): {
+    base: z.ZodTypeAny;
+    optional: boolean;
+    nullable: boolean;
+    hasDefault: boolean;
+};
+declare function simpleToConvex(schema: z.ZodTypeAny): any;
+declare function zodToConvex(schema: z.ZodTypeAny): Validator<any, any, any>;
+declare function zodToConvexFields(shapeOrObject: z.ZodRawShape | Record<string, z.ZodTypeAny> | z.ZodObject<any>): Record<string, Validator<any, any, any>>;
+
+type ConvexCodec<T = any> = {
+    schema: z.ZodTypeAny;
+    toConvexSchema: () => any;
+    encode: (data: T) => any;
+    decode: (data: any) => T;
+    pick: (keys: Record<string, true>) => ConvexCodec<any>;
+};
+declare function toConvexJS(value: any): any;
+declare function toConvexJS(schema: z.ZodTypeAny, value: any): any;
+declare function fromConvexJS(value: any, schema: z.ZodTypeAny): any;
+declare function convexCodec<T = any>(schema: z.ZodTypeAny): ConvexCodec<T>;
+
+type InferArgs<A> = A extends z.ZodObject<infer S> ? z.infer<z.ZodObject<S>> : A extends Record<string, z.ZodTypeAny> ? {
+    [K in keyof A]: z.infer<A[K]>;
+} : A extends z.ZodTypeAny ? z.infer<A> : Record<string, never>;
+type InferReturns<R> = R extends z.ZodTypeAny ? z.output<R> : R extends undefined ? any : R;
+type ExtractCtx<Builder> = Builder extends {
+    (fn: {
+        handler: (ctx: infer Ctx, ...args: any[]) => any;
+    }): any;
+} ? Ctx : never;
+type PreserveReturnType<Builder, ArgsType, ReturnsType> = Builder extends QueryBuilder<any, infer Visibility> ? RegisteredQuery<Visibility, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends MutationBuilder<any, infer Visibility> ? RegisteredMutation<Visibility, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends ActionBuilder<any, infer Visibility> ? RegisteredAction<Visibility, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends CustomBuilder<'query', any, any, any, any, infer V, any> ? RegisteredQuery<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends CustomBuilder<'mutation', any, any, any, any, infer V, any> ? RegisteredMutation<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends CustomBuilder<'action', any, any, any, any, infer V, any> ? RegisteredAction<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends (...args: any[]) => any ? ReturnType<Builder> : never;
+type ZodToConvexArgs<A> = A extends z.ZodObject<infer Shape> ? {
+    [K in keyof Shape]: any;
+} : A extends Record<string, z.ZodTypeAny> ? {
+    [K in keyof A]: any;
+} : A extends z.ZodTypeAny ? {
+    value: any;
+} : Record<string, never>;
+
+declare function zQuery<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(query: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zInternalQuery<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalQuery: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zMutation<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(mutation: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zInternalMutation<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalMutation: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zAction<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(action: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zInternalAction<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalAction: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+
+declare function zCustomQuery<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel>(query: any, customization: Customization<GenericQueryCtx<DataModel>, CustomArgsValidator, CustomCtx, CustomMadeArgs>): CustomBuilder<"query", CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericQueryCtx<DataModel>, Visibility, Record<string, any>>;
+declare function zCustomMutation<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel>(mutation: any, customization: Customization<GenericMutationCtx<DataModel>, CustomArgsValidator, CustomCtx, CustomMadeArgs>): CustomBuilder<"mutation", CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericMutationCtx<DataModel>, Visibility, Record<string, any>>;
+declare function zCustomAction<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel>(action: any, customization: Customization<GenericActionCtx<DataModel>, CustomArgsValidator, CustomCtx, CustomMadeArgs>): CustomBuilder<"action", CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericActionCtx<DataModel>, Visibility, Record<string, any>>;
+
+declare function zodTable<T extends z.ZodObject<any>, TableName extends string>(name: TableName, schema: T): {
+    codec: ConvexCodec<any>;
+    schema: T;
+    name: TableName;
+    table: convex_server.TableDefinition<convex_values.VObject<{
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+    }, any, "required", string>, {}, {}, {}>;
+    doc: convex_values.VObject<{
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+    }, {
+        [x: string]: any;
+    }, "required", string>;
+    withoutSystemFields: any;
+    withSystemFields: {
+        [x: string]: any;
+    };
+    systemFields: {
+        _id: convex_values.VId<convex_values.GenericId<TableName>, "required">;
+        _creationTime: VFloat64<number, "required">;
+    };
+    _id: convex_values.VId<convex_values.GenericId<TableName>, "required">;
+};
+declare function zCrud<TableDefinition extends ReturnType<typeof zodTable>, QueryBuilder extends (fn: any) => any, MutationBuilder extends (fn: any) => any>(table: TableDefinition, queryBuilder: QueryBuilder, mutationBuilder: MutationBuilder): {
+    create: PreserveReturnType<MutationBuilder, {
+        [x: string]: any;
+    }, any>;
+    read: PreserveReturnType<QueryBuilder, {
+        id: any;
+    }, any>;
+    paginate: any;
+    update: PreserveReturnType<MutationBuilder, {
+        id: any;
+        patch: any;
+    }, any>;
+    destroy: PreserveReturnType<MutationBuilder, {
+        id: any;
+    }, any>;
+};
+
+/**
+ * Minimal compatibility for convex-helpers/server/zodV4 imports
+ * This library itself IS the Zod v4 compatibility layer
+ */
+
+/**
+ * Create a Zod validator for a Convex Id
+ */
+declare function zid<TableName extends string>(tableName: TableName): z.ZodTypeAny;
+type Zid<TableName extends string> = ReturnType<typeof zid<TableName>>;
+
+export { type ConvexCodec, type ExtractCtx, type InferArgs, type InferReturns, type PreserveReturnType, type Zid, type ZodToConvexArgs, analyzeZod, convexCodec, fromConvexJS, getObjectShape, makeUnion, simpleToConvex, toConvexJS, zAction, zCrud, zCustomAction, zCustomMutation, zCustomQuery, zInternalAction, zInternalMutation, zInternalQuery, zMutation, zQuery, zid, zodTable, zodToConvex, zodToConvexFields };

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import * as convex_values from 'convex/values';
+import { Validator, PropertyValidators } from 'convex/values';
+import { z } from 'zod';
+import * as convex_server from 'convex/server';
+import { QueryBuilder, RegisteredQuery, DefaultFunctionArgs, MutationBuilder, RegisteredMutation, ActionBuilder, RegisteredAction, FunctionVisibility, GenericDataModel, GenericQueryCtx, GenericMutationCtx, GenericActionCtx } from 'convex/server';
+import { CustomBuilder, Customization } from 'convex-helpers/server/customFunctions';
+import { VFloat64 } from './validators.js';
+
+declare function makeUnion(members: any[]): any;
+declare function getObjectShape(obj: z.ZodObject<any>): Record<string, z.ZodTypeAny>;
+declare function analyzeZod(schema: z.ZodTypeAny): {
+    base: z.ZodTypeAny;
+    optional: boolean;
+    nullable: boolean;
+    hasDefault: boolean;
+};
+declare function simpleToConvex(schema: z.ZodTypeAny): any;
+declare function zodToConvex(schema: z.ZodTypeAny): Validator<any, any, any>;
+declare function zodToConvexFields(shapeOrObject: z.ZodRawShape | Record<string, z.ZodTypeAny> | z.ZodObject<any>): Record<string, Validator<any, any, any>>;
+
+type ConvexCodec<T = any> = {
+    schema: z.ZodTypeAny;
+    toConvexSchema: () => any;
+    encode: (data: T) => any;
+    decode: (data: any) => T;
+    pick: (keys: Record<string, true>) => ConvexCodec<any>;
+};
+declare function toConvexJS(value: any): any;
+declare function toConvexJS(schema: z.ZodTypeAny, value: any): any;
+declare function fromConvexJS(value: any, schema: z.ZodTypeAny): any;
+declare function convexCodec<T = any>(schema: z.ZodTypeAny): ConvexCodec<T>;
+
+type InferArgs<A> = A extends z.ZodObject<infer S> ? z.infer<z.ZodObject<S>> : A extends Record<string, z.ZodTypeAny> ? {
+    [K in keyof A]: z.infer<A[K]>;
+} : A extends z.ZodTypeAny ? z.infer<A> : Record<string, never>;
+type InferReturns<R> = R extends z.ZodTypeAny ? z.output<R> : R extends undefined ? any : R;
+type ExtractCtx<Builder> = Builder extends {
+    (fn: {
+        handler: (ctx: infer Ctx, ...args: any[]) => any;
+    }): any;
+} ? Ctx : never;
+type PreserveReturnType<Builder, ArgsType, ReturnsType> = Builder extends QueryBuilder<any, infer Visibility> ? RegisteredQuery<Visibility, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends MutationBuilder<any, infer Visibility> ? RegisteredMutation<Visibility, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends ActionBuilder<any, infer Visibility> ? RegisteredAction<Visibility, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends CustomBuilder<'query', any, any, any, any, infer V, any> ? RegisteredQuery<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends CustomBuilder<'mutation', any, any, any, any, infer V, any> ? RegisteredMutation<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends CustomBuilder<'action', any, any, any, any, infer V, any> ? RegisteredAction<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : Builder extends (...args: any[]) => any ? ReturnType<Builder> : never;
+type ZodToConvexArgs<A> = A extends z.ZodObject<infer Shape> ? {
+    [K in keyof Shape]: any;
+} : A extends Record<string, z.ZodTypeAny> ? {
+    [K in keyof A]: any;
+} : A extends z.ZodTypeAny ? {
+    value: any;
+} : Record<string, never>;
+
+declare function zQuery<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(query: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zInternalQuery<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalQuery: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zMutation<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(mutation: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zInternalMutation<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalMutation: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zAction<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(action: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+declare function zInternalAction<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalAction: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: InferArgs<A>) => Promise<InferReturns<R>> | InferReturns<R>, options?: {
+    returns?: R;
+}): PreserveReturnType<Builder, ZodToConvexArgs<A>, InferReturns<R>>;
+
+declare function zCustomQuery<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel>(query: any, customization: Customization<GenericQueryCtx<DataModel>, CustomArgsValidator, CustomCtx, CustomMadeArgs>): CustomBuilder<"query", CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericQueryCtx<DataModel>, Visibility, Record<string, any>>;
+declare function zCustomMutation<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel>(mutation: any, customization: Customization<GenericMutationCtx<DataModel>, CustomArgsValidator, CustomCtx, CustomMadeArgs>): CustomBuilder<"mutation", CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericMutationCtx<DataModel>, Visibility, Record<string, any>>;
+declare function zCustomAction<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel>(action: any, customization: Customization<GenericActionCtx<DataModel>, CustomArgsValidator, CustomCtx, CustomMadeArgs>): CustomBuilder<"action", CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericActionCtx<DataModel>, Visibility, Record<string, any>>;
+
+declare function zodTable<T extends z.ZodObject<any>, TableName extends string>(name: TableName, schema: T): {
+    codec: ConvexCodec<any>;
+    schema: T;
+    name: TableName;
+    table: convex_server.TableDefinition<convex_values.VObject<{
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+    }, any, "required", string>, {}, {}, {}>;
+    doc: convex_values.VObject<{
+        [x: string]: any;
+        [x: number]: any;
+        [x: symbol]: any;
+    }, {
+        [x: string]: any;
+    }, "required", string>;
+    withoutSystemFields: any;
+    withSystemFields: {
+        [x: string]: any;
+    };
+    systemFields: {
+        _id: convex_values.VId<convex_values.GenericId<TableName>, "required">;
+        _creationTime: VFloat64<number, "required">;
+    };
+    _id: convex_values.VId<convex_values.GenericId<TableName>, "required">;
+};
+declare function zCrud<TableDefinition extends ReturnType<typeof zodTable>, QueryBuilder extends (fn: any) => any, MutationBuilder extends (fn: any) => any>(table: TableDefinition, queryBuilder: QueryBuilder, mutationBuilder: MutationBuilder): {
+    create: PreserveReturnType<MutationBuilder, {
+        [x: string]: any;
+    }, any>;
+    read: PreserveReturnType<QueryBuilder, {
+        id: any;
+    }, any>;
+    paginate: any;
+    update: PreserveReturnType<MutationBuilder, {
+        id: any;
+        patch: any;
+    }, any>;
+    destroy: PreserveReturnType<MutationBuilder, {
+        id: any;
+    }, any>;
+};
+
+/**
+ * Minimal compatibility for convex-helpers/server/zodV4 imports
+ * This library itself IS the Zod v4 compatibility layer
+ */
+
+/**
+ * Create a Zod validator for a Convex Id
+ */
+declare function zid<TableName extends string>(tableName: TableName): z.ZodTypeAny;
+type Zid<TableName extends string> = ReturnType<typeof zid<TableName>>;
+
+export { type ConvexCodec, type ExtractCtx, type InferArgs, type InferReturns, type PreserveReturnType, type Zid, type ZodToConvexArgs, analyzeZod, convexCodec, fromConvexJS, getObjectShape, makeUnion, simpleToConvex, toConvexJS, zAction, zCrud, zCustomAction, zCustomMutation, zCustomQuery, zInternalAction, zInternalMutation, zInternalQuery, zMutation, zQuery, zid, zodTable, zodToConvex, zodToConvexFields };