zodvex 0.2.5 → 0.3.2

package/README.md

@@ -18,6 +18,13 @@ Type-safe Convex functions with Zod schemas. Preserve Convex's optional/nullable
 - [Form Validation](#form-validation)
 - [API Reference](#api-reference)
 - [Advanced Usage](#advanced-usage)
+  - [Custom Context Builders](#custom-context-builders)
+  - [Date Handling](#date-handling)
+  - [Return Type Helpers](#return-type-helpers)
+  - [Working with Large Schemas](#working-with-large-schemas)
+  - [Polymorphic Tables with Unions](#polymorphic-tables-with-unions)
+  - [AI SDK Compatibility](#ai-sdk-compatibility)
+- [Migration Guide](./MIGRATION.md)
 
 ## Installation
 
@@ -441,27 +448,94 @@ export const updateProfile = authMutation({
 
 ### Date Handling
 
-Dates are automatically converted to timestamps:
+zodvex automatically converts dates between JavaScript `Date` objects and Convex timestamps when using `z.date()` in your schemas.
+
+#### Automatic Conversion (Recommended)
+
+Use `z.date()` for automatic handling - no manual conversion needed:
 
 ```ts
 const eventShape = {
   title: z.string(),
   startDate: z.date(),
-  endDate: z.date().nullable()
+  endDate: z.date().nullable(),
+  createdAt: z.date().optional()
 }
 
 export const Events = zodTable('events', eventShape)
 
+// In your function - dates work seamlessly
 export const createEvent = zm({
   args: eventShape,
-  handler: async (ctx, event) => {
-    // event.startDate is a Date object
-    // Automatically converted to timestamp for storage
-    return await ctx.db.insert('events', event)
+  handler: async (ctx, { startDate, endDate, title }) => {
+    // startDate and endDate are already Date objects!
+    console.log(startDate.toISOString()) // ✅ Works
+
+    // Automatically converted to timestamps for storage
+    return await ctx.db.insert('events', { title, startDate, endDate })
   }
 })
+
+// On the frontend - just pass Date objects
+const createEvent = useMutation(api.events.createEvent)
+await createEvent({
+  title: 'My Event',
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-01-02')
+})
+// ✅ No manual conversion needed!
 ```
 
+**How it works:**
+- **Args**: Timestamps from client → automatically decoded to `Date` objects
+- **Returns**: `Date` objects from handler → automatically encoded to timestamps
+- **Storage**: Dates are stored as `v.float64()` (Convex doesn't have a native Date type)
+
+#### Manual String Dates (Alternative)
+
+If you prefer working with ISO strings instead of Date objects, use `z.string()`:
+
+```ts
+// ❌ Using z.string() means NO automatic conversion
+const schema = {
+  birthday: z.string() // Stored as ISO string
+}
+
+export const updateUser = zm({
+  args: schema,
+  handler: async (ctx, { birthday }) => {
+    // birthday is a string, you must manually parse
+    const date = new Date(birthday) // Manual conversion
+    await ctx.db.insert('users', { birthday })
+  }
+})
+
+// On frontend - manual conversion
+await updateUser({
+  birthday: new Date().toISOString() // Must manually convert
+})
+```
+
+**When to use which:**
+- ✅ **`z.date()`** - When you want automatic conversion and type-safe Date objects (recommended)
+- ⚠️ **`z.string()`** - When you need ISO strings for display/formatting (requires manual parsing)
+
+#### Edge Case: Date/Number Unions
+
+If you need a field that accepts both dates and numbers (rare), use explicit transforms:
+
+```ts
+// Edge case: field that can be a date OR a timestamp
+const flexibleDate = z.union([
+  z.date(),
+  z.number().transform(ts => new Date(ts))
+])
+
+// Most apps don't need this - fields are either dates OR numbers, not both
+```
+
+**Note:** In real-world schemas, mixing dates and numbers in unions is uncommon. Design your data model so fields have a single type.
+
 ### Return Type Helpers
 
 ```ts
@@ -501,6 +575,243 @@ const UserUpdate = safePick(User, {
 })
 ```
 
+### Polymorphic Tables with Unions
+
+zodvex fully supports polymorphic tables using discriminated unions! Use `zodTable()` directly with union schemas:
+
+```ts
+import { zodTable, zid } from 'zodvex'
+import { z } from 'zod'
+
+// Define your discriminated union schema
+const shapeSchema = z.union([
+  z.object({
+    kind: z.literal('circle'),
+    cx: z.number(),
+    cy: z.number(),
+    r: z.number()
+  }),
+  z.object({
+    kind: z.literal('rectangle'),
+    x: z.number(),
+    y: z.number(),
+    width: z.number(),
+    height: z.number()
+  }),
+  z.object({
+    kind: z.literal('path'),
+    path: z.string()
+  })
+])
+
+// Define the table - zodTable() accepts unions!
+export const Shapes = zodTable('shapes', shapeSchema)
+
+// Use in schema
+export default defineSchema({
+  shapes: Shapes.table
+})
+
+// docArray automatically includes system fields for each variant
+export const getShapes = zq({
+  args: {},
+  returns: Shapes.docArray,  // ✅ Each variant has _id and _creationTime
+  handler: async (ctx) => ctx.db.query('shapes').collect()
+})
+
+// Create with type-safe discriminated unions
+export const createShape = zm({
+  args: shapeSchema,
+  handler: async (ctx, shape) => {
+    // shape is discriminated - TypeScript knows the fields based on `kind`
+    return await ctx.db.insert('shapes', shape)
+  }
+})
+```
+
+#### Union Table Helpers
+
+Union tables provide different helpers than object tables:
+
+```ts
+const Shapes = zodTable('shapes', shapeSchema)
+
+// Available properties:
+Shapes.table          // TableDefinition for schema
+Shapes.tableName      // 'shapes'
+Shapes.schema         // Original union schema
+Shapes.validator      // Convex validator (union)
+Shapes.docArray       // Array schema with system fields added to each variant
+Shapes.withSystemFields()  // Returns union with _id and _creationTime on each variant
+
+// NOT available (specific to object tables):
+// Shapes.shape       - unions don't have a fixed shape
+// Shapes.zDoc        - use withSystemFields() instead
+```
+
+#### Advanced Union Patterns
+
+**Shared base schema:**
+
+```ts
+const baseShape = z.object({
+  color: z.string(),
+  strokeWidth: z.number()
+})
+
+const shapeSchema = z.union([
+  baseShape.extend({
+    kind: z.literal('circle'),
+    radius: z.number()
+  }),
+  baseShape.extend({
+    kind: z.literal('rectangle'),
+    width: z.number(),
+    height: z.number()
+  })
+])
+
+export const Shapes = zodTable('shapes', shapeSchema)
+```
+
+**Using z.discriminatedUnion:**
+
+```ts
+const shapeSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('circle'), r: z.number() }),
+  z.object({ kind: z.literal('rectangle'), w: z.number(), h: z.number() })
+])
+
+export const Shapes = zodTable('shapes', shapeSchema)
+```
+
+**When to use discriminated unions:**
+- Polymorphic data (e.g., different shape types, notification variants)
+- Tables with multiple distinct subtypes sharing common fields
+- Event sourcing patterns with different event types
+- When you need type-safe variant handling in TypeScript
+
+**Learn more:**
+- [Convex Polymorphic Data](https://docs.convex.dev/database/types#polymorphic-types)
+- [Zod Discriminated Unions](https://zod.dev/discriminated-unions)
+
+### AI SDK Compatibility
+
+zodvex schemas are fully compatible with [Vercel's AI SDK](https://sdk.vercel.ai/docs), including `zid` for Convex IDs.
+
+#### Using with AI SDK
+
+```ts
+import { generateObject } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+import { zid } from 'zodvex'
+
+const userSchema = z.object({
+  id: zid('users'),        // ✅ Works with AI SDK
+  name: z.string(),
+  email: z.string().email(),
+  age: z.number().int(),
+  teamId: zid('teams').optional()
+})
+
+const result = await generateObject({
+  model: openai('gpt-4'),
+  schema: userSchema,
+  prompt: 'Generate a sample user profile'
+})
+
+// result.object is fully typed and validated
+console.log(result.object.id) // Type: GenericId<'users'>
+```
+
+#### Why It Works
+
+AI SDK requires schemas to be serializable (no `.transform()` or `.brand()`). zodvex's `zid` uses type-level branding instead of runtime transforms, making it compatible:
+
+```ts
+// zodvex approach (compatible)
+zid('users') // String validator with type assertion → GenericId<'users'>
+
+// Not compatible (using transforms)
+z.string().transform(s => s as GenericId<'users'>) // ❌ AI SDK rejects
+```
+
+#### Schemas with Custom Transforms
+
+If you have schemas with custom `.transform()` or `.pipe()`, AI SDK may reject them. For complex transformations, consider:
+
+**Option 1: Separate schemas**
+```ts
+// For AI SDK (no transforms)
+const aiUserSchema = z.object({
+  createdAt: z.string() // ISO string
+})
+
+// For internal use (with transforms)
+const internalUserSchema = z.object({
+  createdAt: z.string().transform(s => new Date(s))
+})
+```
+
+**Option 2: Use zodvex's JSON Schema helper**
+```ts
+import { toJSONSchema } from 'zodvex'
+
+const schema = z.object({
+  userId: zid('users'),
+  createdAt: z.date(),
+  name: z.string()
+})
+
+// Automatically handles zid and z.date() for JSON Schema generation
+const jsonSchema = toJSONSchema(schema)
+// Use with AI SDK or other JSON Schema consumers
+```
+
+The `toJSONSchema` helper automatically handles zodvex-managed types:
+- `zid('tableName')` → `{ type: "string", format: "convex-id:tableName" }`
+- `z.date()` → `{ type: "string", format: "date-time" }`
+
+For custom overrides, use `zodvexJSONSchemaOverride` directly:
+```ts
+import { zodvexJSONSchemaOverride, composeOverrides } from 'zodvex'
+
+const jsonSchema = z.toJSONSchema(schema, {
+  unrepresentable: 'any',
+  override: composeOverrides(myCustomOverride, zodvexJSONSchemaOverride)
+})
+```
+
+## zodvex vs convex-helpers/zod4
+
+Convex officially supports Zod 4 via `convex-helpers/server/zod4`. zodvex builds on those primitives to provide a batteries-included, opinionated solution.
+
+**Use convex-helpers if you want:**
+- Low-level control over encoding/decoding
+- Explicit Zod codecs for all conversions
+- Minimal abstractions
+- Both Zod 3 and 4 support in one package
+
+**Use zodvex if you want:**
+- Automatic date handling (no manual codecs needed)
+- Table helpers with `.table`, `.zDoc`, `.docArray`, `.shape`
+- Builder pattern API for consistent function definitions
+- Codec abstraction with `.pick()` for subsets
+- Turnkey developer experience
+
+**Key differences:**
+
+| Feature | zodvex | convex-helpers/zod4 |
+|---------|--------|---------------------|
+| Date conversion | Automatic with `z.date()` | Manual `z.codec()` required |
+| Table helpers | `zodTable()` with helpers | Not provided |
+| Builder pattern | `zQueryBuilder()`, etc. | Not provided |
+| Codec abstraction | `convexCodec()` with `.pick()` | Not provided |
+| Philosophy | Batteries-included | Minimal primitives |
+
+Both are valid choices - zodvex trades some explicitness for significantly better ergonomics.
+
 ## Why zodvex?
 
 - **Correct optional/nullable semantics** - Preserves Convex's distinction
@@ -508,7 +819,8 @@ const UserUpdate = safePick(User, {
   - `.nullable()` → `v.union(T, v.null())` (required but can be null)
   - Both → `v.optional(v.union(T, v.null()))`
 - **Superior type safety** - Builders provide better type inference than wrapper functions
-- **Date handling** - Automatic `Date` ↔ timestamp conversion
+- **Automatic date handling** - `Date` ↔ timestamp conversion happens transparently
+- **Table helpers** - `zodTable()` provides `.zDoc`, `.docArray`, and `.shape` for DRY schemas
 - **End-to-end validation** - Same schema from database to frontend forms
 
 ## Compatibility

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Customization } from 'convex-helpers/server/customFunctions';
 export { customCtx } from 'convex-helpers/server/customFunctions';
 import * as convex_server from 'convex/server';
-import { RegisteredQuery, RegisteredMutation, RegisteredAction, DefaultFunctionArgs, FunctionVisibility, ArgsArrayToObject, GenericDataModel, QueryBuilder, GenericQueryCtx } from 'convex/server';
+import { RegisteredQuery, RegisteredMutation, RegisteredAction, DefaultFunctionArgs, FunctionVisibility, ArgsArrayToObject, GenericDataModel, QueryBuilder, GenericQueryCtx, defineTable } from 'convex/server';
 import * as convex_values from 'convex/values';
 import { VAny, VOptional, VUnion, VId, GenericId, VString, VFloat64, VInt64, VBoolean, VNull, VArray, VObject, VLiteral, VRecord, PropertyValidators } from 'convex/values';
 import { z } from 'zod';
-import * as convex_helpers from 'convex-helpers';
+import { Table } from 'convex-helpers/server';
 
 type IsZid<T> = T extends {
     _tableName: infer _TableName extends string;
@@ -61,8 +61,11 @@ declare const registryHelpers: {
 /**
  * Create a Zod validator for a Convex Id
  *
- * Uses the string → transform → brand pattern for proper type narrowing with ctx.db.get()
- * This aligns with Zod v4 best practices and matches convex-helpers implementation
+ * Compatible with AI SDK and other tools that don't support transforms.
+ * Uses type-level branding instead of runtime transforms for GenericId<T> compatibility.
+ *
+ * @param tableName - The Convex table name for this ID
+ * @returns A Zod string validator typed as GenericId<TableName>
  */
 declare function zid<TableName extends string>(tableName: TableName): z.ZodType<GenericId<TableName>> & {
     _tableName: TableName;
@@ -75,8 +78,8 @@ declare function getObjectShape(obj: any): Record<string, any>;
 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.ZodUnion<any> ? any : R extends z.ZodCustom<any> ? any : R extends z.ZodType<any, any, any> ? z.output<R> : R extends undefined ? any : R;
-type InferHandlerReturns<R> = R extends z.ZodUnion<any> ? any : R extends z.ZodCustom<any> ? any : R extends z.ZodType<any, any, any> ? z.input<R> : any;
+type InferReturns<R> = R extends z.ZodType<any, any, any> ? z.output<R> : R extends undefined ? any : R;
+type InferHandlerReturns<R> = R extends z.ZodType<any, any, any> ? z.input<R> : any;
 /**
  * Extract the visibility type from a Convex builder function
  */
@@ -343,7 +346,133 @@ type BaseCodec = {
 declare function registerBaseCodec(codec: BaseCodec): void;
 declare function findBaseCodec(schema: any): BaseCodec | undefined;
 declare function isDateSchema(schema: any): boolean;
+/**
+ * Checks if a schema is a zid (Convex ID) schema by looking at its description.
+ * zid schemas are marked with "convexId:{tableName}" in their description.
+ */
+declare function isZidSchema(schema: z.ZodTypeAny): boolean;
+/**
+ * Extracts the table name from a zid schema's description.
+ * Returns undefined if not a zid schema.
+ */
+declare function getZidTableName(schema: z.ZodTypeAny): string | undefined;
+/**
+ * Context object passed to the JSON Schema override function.
+ * Uses 'any' types for compatibility with Zod's internal types.
+ */
+interface JSONSchemaOverrideContext {
+    zodSchema: any;
+    jsonSchema: any;
+}
+/**
+ * Override function for z.toJSONSchema that handles zodvex-managed types.
+ *
+ * Handles:
+ * - zid schemas: Converts to { type: "string" } with convexId format
+ * - z.date(): Converts to { type: "string", format: "date-time" }
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { zid, zodvexJSONSchemaOverride } from 'zodvex'
+ *
+ * const schema = z.object({
+ *   userId: zid('users'),
+ *   name: z.string()
+ * })
+ *
+ * const jsonSchema = z.toJSONSchema(schema, {
+ *   unrepresentable: 'any',
+ *   override: zodvexJSONSchemaOverride
+ * })
+ * // => { type: "object", properties: { userId: { type: "string" }, name: { type: "string" } } }
+ * ```
+ */
+declare function zodvexJSONSchemaOverride(ctx: JSONSchemaOverrideContext): void;
+/**
+ * Composes multiple JSON Schema override functions into one.
+ * Overrides run in order - first override runs first.
+ *
+ * @example
+ * ```ts
+ * import { composeOverrides, zodvexJSONSchemaOverride } from 'zodvex'
+ *
+ * const myOverride = (ctx) => {
+ *   if (ctx.zodSchema.description?.startsWith('myType:')) {
+ *     ctx.jsonSchema.type = 'string'
+ *     ctx.jsonSchema.format = 'my-format'
+ *   }
+ * }
+ *
+ * // User's override runs first, then zodvex's
+ * z.toJSONSchema(schema, {
+ *   unrepresentable: 'any',
+ *   override: composeOverrides(myOverride, zodvexJSONSchemaOverride)
+ * })
+ * ```
+ */
+declare function composeOverrides(...overrides: Array<((ctx: JSONSchemaOverrideContext) => void) | undefined>): (ctx: JSONSchemaOverrideContext) => void;
+/**
+ * Options for toJSONSchema, matching Zod's interface.
+ */
+interface ToJSONSchemaOptions {
+    target?: 'draft-4' | 'draft-7' | 'draft-2020-12' | 'openapi-3.0';
+    unrepresentable?: 'throw' | 'any';
+    cycles?: 'ref' | 'throw';
+    reused?: 'ref' | 'inline';
+    io?: 'input' | 'output';
+    override?: (ctx: JSONSchemaOverrideContext) => void;
+}
+/**
+ * Converts a Zod schema to JSON Schema with zodvex-aware overrides.
+ *
+ * This is a convenience wrapper around z.toJSONSchema that automatically
+ * handles zodvex-managed types like zid and dates.
+ *
+ * @example
+ * ```ts
+ * import { zid, toJSONSchema } from 'zodvex'
+ *
+ * const schema = z.object({
+ *   userId: zid('users'),
+ *   createdAt: z.date(),
+ *   name: z.string()
+ * })
+ *
+ * const jsonSchema = toJSONSchema(schema)
+ * // Works with AI SDK's generateObject, etc.
+ * ```
+ */
+declare function toJSONSchema<T extends z.ZodTypeAny>(schema: T, options?: ToJSONSchemaOptions): Record<string, any>;
 
+/**
+ * Helper type for Convex system fields added to documents
+ */
+type SystemFields<TableName extends string> = {
+    _id: ReturnType<typeof zid<TableName>>;
+    _creationTime: z.ZodNumber;
+};
+/**
+ * Maps over union options, extending each ZodObject variant with system fields.
+ * Non-object variants are preserved as-is.
+ */
+type MapSystemFields<TableName extends string, Options extends readonly z.ZodTypeAny[]> = {
+    [K in keyof Options]: Options[K] extends z.ZodObject<infer Shape extends z.ZodRawShape> ? z.ZodObject<Shape & SystemFields<TableName>> : Options[K];
+};
+/**
+ * Adds Convex system fields (_id, _creationTime) to a Zod schema.
+ *
+ * For object schemas: extends with system fields
+ * For union schemas: adds system fields to each variant
+ *
+ * @param tableName - The Convex table name
+ * @param schema - The Zod schema (object or union)
+ * @returns Schema with system fields added
+ */
+declare function addSystemFields<TableName extends string, Shape extends z.ZodRawShape>(tableName: TableName, schema: z.ZodObject<Shape>): z.ZodObject<Shape & SystemFields<TableName>>;
+declare function addSystemFields<TableName extends string, Options extends readonly z.ZodTypeAny[]>(tableName: TableName, schema: z.ZodUnion<Options>): z.ZodUnion<MapSystemFields<TableName, Options>>;
+declare function addSystemFields<TableName extends string, Options extends readonly z.ZodObject<z.ZodRawShape>[], Discriminator extends string>(tableName: TableName, schema: z.ZodDiscriminatedUnion<Options, Discriminator>): z.ZodDiscriminatedUnion<MapSystemFields<TableName, Options>, Discriminator>;
+declare function addSystemFields<TableName extends string, S extends z.ZodTypeAny>(tableName: TableName, schema: S): S;
 declare function zodDoc<TableName extends string, Shape extends z.ZodRawShape, Schema extends z.ZodObject<Shape>>(tableName: TableName, schema: Schema): z.ZodObject<Shape & {
     _id: ReturnType<typeof zid<TableName>>;
     _creationTime: z.ZodNumber;
@@ -357,21 +486,23 @@ declare function zodDocOrNull<TableName extends string, Shape extends z.ZodRawSh
     _creationTime: z.ZodNumber;
 }, z.core.$strip>, z.ZodNull]>;
 /**
- * Defines a Convex table using a raw Zod shape (an object mapping field names to Zod types).
+ * Defines a Convex table using either:
+ * - A raw Zod shape (an object mapping field names to Zod types)
+ * - A Zod union schema (for polymorphic tables)
  *
- * This function intentionally accepts a raw shape instead of a ZodObject instance.
+ * For object shapes, this function intentionally accepts a raw shape instead of a ZodObject instance.
  * Accepting raw shapes allows TypeScript to infer field types more accurately and efficiently,
  * leading to better type inference and performance throughout the codebase.
- * This architectural decision is important for projects that rely heavily on type safety and
- * developer experience, as it avoids the type erasure that can occur when using ZodObject directly.
+ *
+ * For union schemas, this enables polymorphic tables with discriminated unions.
  *
  * Returns the Table definition along with Zod schemas for documents and arrays.
  *
  * @param name - The table name
- * @param shape - A raw object mapping field names to Zod validators
- * @returns A Table with attached shape, zDoc schema, and docArray helper
+ * @param schemaOrShape - Either a raw object shape or a Zod union schema
+ * @returns A Table with attached helpers (shape, schema, zDoc, docArray, withSystemFields)
  *
- * @example
+ * @example Object shape
  * ```ts
  * const Users = zodTable('users', {
  *   name: z.string(),
@@ -388,65 +519,45 @@ declare function zodDocOrNull<TableName extends string, Shape extends z.ZodRawSh
  *   { returns: Users.docArray }
  * )
  * ```
+ *
+ * @example Union schema (polymorphic table)
+ * ```ts
+ * const shapeSchema = z.union([
+ *   z.object({ kind: z.literal('circle'), r: z.number() }),
+ *   z.object({ kind: z.literal('rectangle'), width: z.number() })
+ * ])
+ *
+ * const Shapes = zodTable('shapes', shapeSchema)
+ *
+ * // Use in schema
+ * export default defineSchema({ shapes: Shapes.table })
+ *
+ * // Use for return types with system fields
+ * export const getShapes = zQuery(query, {},
+ *   async (ctx) => ctx.db.query('shapes').collect(),
+ *   { returns: Shapes.docArray }
+ * )
+ * ```
  */
-declare function zodTable<TableName extends string, Shape extends Record<string, z.ZodTypeAny>>(name: TableName, shape: Shape): {
-    name: TableName;
-    table: convex_server.TableDefinition<convex_values.VObject<convex_server.Expand<{ [Property_1 in { [Property in keyof ConvexValidatorFromZodFieldsAuto<Shape>]: ConvexValidatorFromZodFieldsAuto<Shape>[Property]["isOptional"] extends "optional" ? Property : never; }[keyof Shape]]?: Exclude<convex_values.Infer<ConvexValidatorFromZodFieldsAuto<Shape>[Property_1]>, undefined> | undefined; } & { [Property_2_1 in Exclude<keyof Shape, { [Property_2 in keyof ConvexValidatorFromZodFieldsAuto<Shape>]: ConvexValidatorFromZodFieldsAuto<Shape>[Property_2]["isOptional"] extends "optional" ? Property_2 : never; }[keyof Shape]>]: convex_values.Infer<ConvexValidatorFromZodFieldsAuto<Shape>[Property_2_1]>; }>, ConvexValidatorFromZodFieldsAuto<Shape>, "required", { [Property_3 in keyof ConvexValidatorFromZodFieldsAuto<Shape>]: Property_3 | `${Property_3 & string}.${ConvexValidatorFromZodFieldsAuto<Shape>[Property_3]["fieldPaths"]}`; }[keyof Shape] & string>, {}, {}, {}>;
-    doc: convex_values.VObject<convex_server.Expand<{ [Property_5 in (convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }> extends infer T_1 extends Record<string, convex_values.GenericValidator> ? { [Property_4 in keyof T_1]: T_1[Property_4]["isOptional"] extends "optional" ? Property_4 : never; } : never)[keyof convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>]]?: Exclude<convex_values.Infer<convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>[Property_5]>, undefined> | undefined; } & { [Property_1_1 in Exclude<keyof convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>, (convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }> extends infer T_2 extends Record<string, convex_values.GenericValidator> ? { [Property_4_1 in keyof T_2]: T_2[Property_4_1]["isOptional"] extends "optional" ? Property_4_1 : never; } : never)[keyof convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>]>]: convex_values.Infer<convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>[Property_1_1]>; }>, convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>, "required", (convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }> extends infer T_3 extends convex_values.PropertyValidators ? { [Property_2_1_1 in keyof T_3]: Property_2_1_1 | `${Property_2_1_1 & string}.${T_3[Property_2_1_1]["fieldPaths"]}`; } : never)[keyof convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>]>;
-    withoutSystemFields: ConvexValidatorFromZodFieldsAuto<Shape>;
-    withSystemFields: convex_helpers.Expand<ConvexValidatorFromZodFieldsAuto<Shape> & {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }>;
-    systemFields: {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    };
-    _id: convex_values.VId<GenericId<TableName>, "required">;
-} & {
+type AddSystemFieldsResult<TableName extends string, Schema extends z.ZodTypeAny> = Schema extends z.ZodObject<infer Shape extends z.ZodRawShape> ? z.ZodObject<Shape & SystemFields<TableName>> : Schema extends z.ZodUnion<infer Options extends readonly z.ZodTypeAny[]> ? z.ZodUnion<MapSystemFields<TableName, Options>> : Schema extends z.ZodDiscriminatedUnion<infer Options extends readonly z.ZodObject<z.ZodRawShape>[], infer Disc extends string> ? z.ZodDiscriminatedUnion<MapSystemFields<TableName, Options>, Disc> : Schema;
+declare function zodTable<TableName extends string, Shape extends Record<string, z.ZodTypeAny>>(name: TableName, shape: Shape): ReturnType<typeof Table<ConvexValidatorFromZodFieldsAuto<Shape>, TableName>> & {
     shape: Shape;
     zDoc: z.ZodObject<Shape & {
         _id: ReturnType<typeof zid<TableName>>;
         _creationTime: z.ZodNumber;
     }>;
-    docArray: z.ZodArray<z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }> & {
-        _id: z.ZodType<GenericId<TableName>, unknown, z.core.$ZodTypeInternals<GenericId<TableName>, unknown>> & {
-            _tableName: TableName;
-        };
+    docArray: z.ZodArray<z.ZodObject<Shape & {
+        _id: ReturnType<typeof zid<TableName>>;
         _creationTime: z.ZodNumber;
-    }, z.core.$strip>>;
+    }>>;
+};
+declare function zodTable<TableName extends string, Schema extends z.ZodTypeAny>(name: TableName, schema: Schema): {
+    table: ReturnType<typeof defineTable>;
+    tableName: TableName;
+    validator: ReturnType<typeof zodToConvex<Schema>>;
+    schema: Schema;
+    docArray: z.ZodArray<AddSystemFieldsResult<TableName, Schema>>;
+    withSystemFields: () => AddSystemFieldsResult<TableName, Schema>;
 };
 
 declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
@@ -486,4 +597,4 @@ declare function safePick(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any
  */
 declare function safeOmit(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any>;
 
-export { type ConvexCodec, type ConvexValidatorFromZod, type ConvexValidatorFromZodFieldsAuto, type CustomBuilder, type ExtractCtx, type ExtractVisibility, type InferArgs, type InferHandlerReturns, type InferReturns, type PreserveReturnType, type Zid, type ZodToConvexArgs, type ZodValidator, convexCodec, customFnBuilder, findBaseCodec, formatZodIssues, fromConvexJS, getObjectShape, handleZodValidationError, isDateSchema, makeUnion, mapDateFieldToNumber, pick, pickShape, registerBaseCodec, registryHelpers, returnsAs, safeOmit, safePick, toConvexJS, zActionBuilder, zCustomAction, zCustomActionBuilder, zCustomMutation, zCustomMutationBuilder, zCustomQuery, zCustomQueryBuilder, zMutationBuilder, zPaginated, zQueryBuilder, zid, zodDoc, zodDocOrNull, zodTable, zodToConvex, zodToConvexFields };
+export { type ConvexCodec, type ConvexValidatorFromZod, type ConvexValidatorFromZodFieldsAuto, type CustomBuilder, type ExtractCtx, type ExtractVisibility, type InferArgs, type InferHandlerReturns, type InferReturns, type JSONSchemaOverrideContext, type PreserveReturnType, type ToJSONSchemaOptions, type Zid, type ZodToConvexArgs, type ZodValidator, addSystemFields, composeOverrides, convexCodec, customFnBuilder, findBaseCodec, formatZodIssues, fromConvexJS, getObjectShape, getZidTableName, handleZodValidationError, isDateSchema, isZidSchema, makeUnion, mapDateFieldToNumber, pick, pickShape, registerBaseCodec, registryHelpers, returnsAs, safeOmit, safePick, toConvexJS, toJSONSchema, zActionBuilder, zCustomAction, zCustomActionBuilder, zCustomMutation, zCustomMutationBuilder, zCustomQuery, zCustomQueryBuilder, zMutationBuilder, zPaginated, zQueryBuilder, zid, zodDoc, zodDocOrNull, zodTable, zodToConvex, zodToConvexFields, zodvexJSONSchemaOverride };