diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7edc8326..296e083c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -27,7 +27,6 @@ jobs: run: | npm i npm run build - - name: Publish pkg-pr-new run: | npx pkg-pr-new publish ./packages/convex-helpers diff --git a/convex/_generated/api.d.ts b/convex/_generated/api.d.ts index 11ccaea8..4a03a990 100644 --- a/convex/_generated/api.d.ts +++ b/convex/_generated/api.d.ts @@ -24,6 +24,8 @@ import type * as sessionsExample from "../sessionsExample.js"; import type * as streamsExample from "../streamsExample.js"; import type * as testingFunctions from "../testingFunctions.js"; import type * as triggersExample from "../triggersExample.js"; +import type * as zodTest from "../zodTest.js"; +import type * as zodTestSchema from "../zodTestSchema.js"; /** * A utility for referencing Convex functions in your app's API. @@ -45,6 +47,8 @@ declare const fullApi: ApiFromModules<{ streamsExample: typeof streamsExample; testingFunctions: typeof testingFunctions; triggersExample: typeof triggersExample; + zodTest: typeof zodTest; + zodTestSchema: typeof zodTestSchema; }>; export declare const api: FilterApi< typeof fullApi, diff --git a/convex/schema.ts b/convex/schema.ts index d1345503..3d6ef404 100644 --- a/convex/schema.ts +++ b/convex/schema.ts @@ -1,6 +1,7 @@ import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values"; import { migrationsTable } from "convex-helpers/server/migrations"; +import { zodTestTable } from "./zodTestSchema"; export default defineSchema({ users: defineTable({ @@ -45,4 +46,5 @@ export default defineSchema({ .index("from", ["from", "sentAt"]) // pairwise .index("from_to", ["from", "to", "sentAt"]), + zodTest: zodTestTable, }); diff --git a/convex/zodTest.ts b/convex/zodTest.ts new file mode 100644 index 00000000..1a6a2e90 --- /dev/null +++ b/convex/zodTest.ts @@ -0,0 +1,408 @@ +import { query, mutation, action } from "./_generated/server"; +import { + zCustomQuery, + zCustomMutation, + zid, + zCustomAction, + transformZodDataForConvex, + transformConvexDataToZod, +} from "convex-helpers/server/zodV4"; +import { ConvexError } from "convex/values"; + +import { NoOp } from "convex-helpers/server/customFunctions"; +import { + testRecordSchema, + settingsValueSchema, + scoresValueSchema, + metadataValueSchema, + lowercaseEmailSchema, + positiveNumberSchema, + percentageSchema, + normalizedPhoneSchema, + urlSlugSchema, + flexibleBooleanSchema, + userProfileSchema, +} from "./zodTestSchema"; +import { z } from "zod/v4"; + +// Use the standard zCustom functions directly - Convex needs to see these clearly +export const zQuery = zCustomQuery(query, NoOp); +export const zMutation = zCustomMutation(mutation, NoOp); +export const zAction = zCustomAction(action, NoOp); + +// Create a new test record using zCustomMutation with NoOp +export const create = zMutation({ + args: { data: testRecordSchema }, + handler: async (ctx, args) => { + // The transformation should happen automatically in the zodV4.ts layer + console.log( + "Creating record with args:", + JSON.stringify(args.data, null, 2), + ); + // args.data is already parsed and transformed by zMutation - just use it directly + const convexData = transformZodDataForConvex(args.data, testRecordSchema); + + const docId = await ctx.db.insert("zodTest", convexData); + console.log("Created record with ID:", docId); + return docId; + }, +}); + +// Get a single record +export const get = zCustomQuery( + query, + NoOp, +)({ + args: { id: zid("zodTest") }, + handler: async (ctx, args) => { + const doc = await ctx.db.get(args.id); + console.log("Retrieved record:", doc); + return doc; + }, +}); + +// List all records +export const list = zCustomQuery( + query, + NoOp, +)({ + args: {}, + handler: async (ctx) => { + const docs = await ctx.db.query("zodTest").collect(); + console.log("Listed records:", docs); + return docs; + }, +}); + +// Define the update schema +const updateRecordSchema = testRecordSchema.partial(); + +// Update a record (partial update) +export const update = zMutation({ + args: { + id: zid("zodTest"), + updates: updateRecordSchema, + }, + handler: async (ctx, args) => { + const existing = await ctx.db.get(args.id); + if (!existing) throw new Error("Record not found"); + + // Args are already transformed by our wrapper + // Merge with existing data + const updated = { ...existing, ...args.updates }; + + await ctx.db.replace(args.id, updated); + console.log("Updated record:", updated); + + return args.id; + }, +}); + +// Delete a record +export const remove = zMutation({ + args: { id: zid("zodTest") }, + handler: async (ctx, args) => { + await ctx.db.delete(args.id); + console.log("Deleted record:", args.id); + }, +}); + +// Test function to create a record with minimal data +export const createMinimal = zMutation({ + args: testRecordSchema.pick({ name: true }).shape, + handler: async (ctx, args) => { + // Apply defaults by parsing with full schema + const fullData = testRecordSchema.parse(args); + + // Transform the Zod-parsed data to Convex format (wrapper handles args, but we need to handle fullData) + const convexData = transformZodDataForConvex(fullData, testRecordSchema); + + const docId = await ctx.db.insert("zodTest", convexData); + console.log("Created minimal record with all defaults:", fullData); + console.log("Convex-formatted data:", convexData); + + return docId; + }, +}); + +// Test updating record fields in different ways +export const testRecordUpdate = zMutation({ + args: { + id: zid("zodTest"), + settingKey: z.string(), + settingValue: z.number().nullable().optional(), + scoreKey: z.string(), + scoreValue: z.number().nullable().optional(), + }, + handler: async (ctx, args) => { + const existing = await ctx.db.get(args.id); + if (!existing) throw new Error("Record not found"); + + // Update settings and scores + const updates = { + settings: { ...existing.settings } as Record, + scores: { ...existing.scores } as Record, + }; + + // Test different update patterns + if (args.settingValue !== undefined) { + updates.settings[args.settingKey] = args.settingValue ?? 0; // Apply default if null + } + + if (args.scoreValue !== undefined) { + updates.scores[args.scoreKey] = args.scoreValue; // Can be null + } + + const updated = { ...existing, ...updates }; + await ctx.db.replace(args.id, updated); + + console.log("Test record update result:", { + settingKey: args.settingKey, + settingValue: updates.settings[args.settingKey], + scoreKey: args.scoreKey, + scoreValue: updates.scores[args.scoreKey], + fullRecord: updated, + }); + + return args.id; + }, +}); + +// Update individual fields in Records without overwriting the entire record +export const updateRecordField = zMutation({ + args: { + id: zid("zodTest"), + recordType: z.enum(["settings", "scores", "metadata"]), + fieldKey: z.string(), + fieldValue: z.any().optional(), // undefined means delete the field + }, + handler: async (ctx, args) => { + const doc = await ctx.db.get(args.id); + if (!doc) throw new Error("Record not found"); + + console.log( + `Updating ${args.recordType}.${args.fieldKey} to:`, + args.fieldValue, + ); + console.log(`Current ${args.recordType}:`, doc[args.recordType]); + + // Type for record values based on our schemas + type RecordValue = + | number + | null + | { + value: unknown; + timestamp?: number; + flags?: Record; + } + | undefined; + const recordCopy = { ...doc[args.recordType] } as Record< + string, + RecordValue + >; + + if (args.fieldValue === undefined) { + // Delete the field using destructuring to avoid dynamic delete + const { [args.fieldKey]: _, ...newRecord } = recordCopy; + const updates = { + [args.recordType]: newRecord, + }; + await ctx.db.patch(args.id, updates); + } else { + // Validate the value using the imported schemas + let validatedValue: RecordValue; + try { + if (args.recordType === "settings") { + validatedValue = settingsValueSchema.parse(args.fieldValue); + } else if (args.recordType === "scores") { + validatedValue = scoresValueSchema.parse(args.fieldValue); + } else if (args.recordType === "metadata") { + validatedValue = metadataValueSchema.parse(args.fieldValue); + } else { + throw new Error(`Unknown record type: ${args.recordType}`); + } + } catch (error) { + if (error instanceof z.ZodError) { + throw new ConvexError( + `Invalid value for ${args.recordType}.${args.fieldKey}: ${error.message}`, + ); + } + throw error; + } + + // Update the field in our copy + recordCopy[args.fieldKey] = validatedValue; + + // Update the entire record (since Convex doesn't support dot notation) + const updates = { + [args.recordType]: recordCopy, + }; + await ctx.db.patch(args.id, updates); + } + + const updated = await ctx.db.get(args.id); + console.log(`Updated ${args.recordType}:`, updated?.[args.recordType]); + + return args.id; + }, +}); + +// Test advanced Zod v4 features +export const testAdvancedFeatures = zMutation({ + args: { + id: zid("zodTest"), + email: z.string().optional().nullable(), + rating: z.number().optional().nullable(), + completionRate: z.number().optional().nullable(), + phone: z.string().optional().nullable(), + slug: z.string().optional().nullable(), + isActive: z + .union([z.boolean(), z.string(), z.number()]) + .optional() + .nullable(), + userProfile: z + .object({ + displayName: z.string(), + bio: z.string().optional(), + socialLinks: z + .array( + z.object({ + platform: z.enum(["twitter", "github", "linkedin"]), + username: z.string(), + }), + ) + .optional(), + }) + .optional() + .nullable(), + }, + handler: async (ctx, args) => { + const doc = await ctx.db.get(args.id); + if (!doc) throw new Error("Record not found"); + + // Parse each field through its respective schema to apply transforms + const updates: Record = {}; + + if (args.email !== undefined) { + updates.email = lowercaseEmailSchema.parse(args.email); + console.log(`Email transformed: ${args.email} -> ${updates.email}`); + } + + if (args.rating !== undefined) { + updates.rating = positiveNumberSchema.parse(args.rating); + console.log(`Rating validated: ${updates.rating}`); + } + + if (args.completionRate !== undefined) { + updates.completionRate = percentageSchema.parse(args.completionRate); + console.log( + `Completion rate rounded: ${args.completionRate} -> ${updates.completionRate}`, + ); + } + + if (args.phone !== undefined) { + updates.phone = normalizedPhoneSchema.parse(args.phone); + console.log(`Phone normalized: ${args.phone} -> ${updates.phone}`); + } + + if (args.slug !== undefined) { + updates.slug = urlSlugSchema().parse(args.slug); + console.log(`Slug transformed: ${args.slug} -> ${updates.slug}`); + } + + if (args.isActive !== undefined) { + updates.isActive = flexibleBooleanSchema.parse(args.isActive); + console.log(`Boolean parsed: ${args.isActive} -> ${updates.isActive}`); + } + + if (args.userProfile !== undefined) { + updates.userProfile = userProfileSchema.parse(args.userProfile); + console.log(`User profile transformed:`, updates.userProfile); + } + + // Apply transforms to get Convex format + const transformedUpdates = transformZodDataForConvex( + updates, + testRecordSchema.partial(), + ); + + await ctx.db.patch(args.id, transformedUpdates); + + return { id: args.id, updates: transformedUpdates }; + }, +}); + +// Test roundtrip conversion +export const testRoundtrip = zQuery({ + args: { + testData: testRecordSchema, + }, + handler: async (ctx, args) => { + // Data is already parsed by Zod with defaults applied and transformed by our wrapper + console.log("Received data with defaults:", args.testData); + + // Test that defaults were applied correctly + const tests = { + age: args.testData.age, // Should be 25 if not provided + settings: args.testData.settings, // Should have default 0 for missing keys + scores: args.testData.scores, // Should have default 100 for missing keys + profile: args.testData.profile, // Should have default object + tags: args.testData.tags, // Should be empty array + status: args.testData.status, // Should be "pending" + coordinates: args.testData.coordinates, // Should be {_0: 0, _1: 0} in Convex format + metadata: args.testData.metadata, // Should be {} + }; + + return tests; + }, +}); + +// Test whether brands are preserved when retrieving from database +export const testBrandPreservation = zQuery({ + args: { + id: zid("zodTest"), + }, + handler: async (ctx, args) => { + // Get raw data from database + const doc = await ctx.db.get(args.id); + if (!doc) throw new Error("Record not found"); + + console.log("Raw doc from DB:", doc); + + // Test 1: Check if the value has brand at runtime (it shouldn't) + const emailHasBrand = + doc.email && typeof doc.email === "object" && "$brand" in doc.email; + console.log("Email has brand property at runtime?", emailHasBrand); + + // Test 2: Try to parse the retrieved data through the schema again + let reparseResult; + let reparseError; + try { + // Use our schema-aware transformation to convert Convex format back to Zod format + const docForReparsing = transformConvexDataToZod(doc, testRecordSchema); + + // This will apply transforms again (e.g., lowercase the email again) + reparseResult = testRecordSchema.parse(docForReparsing); + console.log("Reparsed successfully"); + } catch (e) { + reparseError = e; + console.log("Reparse failed:", e); + } + + // Test 3: Check if transforms are applied when reparsing + const transformsApplied = + reparseResult && doc.email && reparseResult.email !== doc.email; + + return { + emailType: typeof doc.email, + emailValue: doc.email, + hasBrandAtRuntime: emailHasBrand, + reparseSuccess: !reparseError, + reparseError: reparseError ? String(reparseError) : undefined, + transformsReapplied: transformsApplied, + reparsedEmail: reparseResult?.email, + // TypeScript type info (will be stripped at runtime) + typescriptThinksBranded: true, // TypeScript believes doc.email is branded + }; + }, +}); diff --git a/convex/zodTestSchema.ts b/convex/zodTestSchema.ts new file mode 100644 index 00000000..90ae84b7 --- /dev/null +++ b/convex/zodTestSchema.ts @@ -0,0 +1,200 @@ +import { z } from "zod/v4"; +import { + zodToConvex, + zBrand, + createBrandedValidator, + zid, +} from "convex-helpers/server/zodV4"; +import { defineTable } from "convex/server"; +import { v } from "convex/values"; + +export const testType = zodToConvex(z.record(z.string(), z.any())); +export type TestType = z.infer; + +// Export individual value schemas for reuse +export const settingsValueSchema = z.number().optional().default(0); +export const scoresValueSchema = z.number().nullable().default(100); +export const metadataValueSchema = z + .object({ + value: z.any().optional().default(null), + timestamp: z + .number() + .optional() + .default(() => Date.now()), + flags: z.record(z.string(), z.boolean().nullable().default(false)), + }) + .optional(); + +// Advanced Zod v4 schemas + +// 1. Transform example - lowercase email +export const lowercaseEmailSchema = zBrand( + z + .string() + .email("Must be a valid email") + .transform((email) => email.toLowerCase()), + "LowercaseEmail", +); + +// 2. Refine example - positive number with custom message +export const positiveNumberSchema = zBrand( + z.number().refine((n) => n > 0, { + message: "Number must be positive", + }), + "PositiveNumber", +); + +// 3. Overwrite example - rounded percentage (preserves number type) +export const percentageSchema = zBrand( + z + .number() + .min(0, "Percentage cannot be negative") + .max(100, "Percentage cannot exceed 100") + .overwrite((val) => Math.round(val * 100) / 100), // Round to 2 decimals + "Percentage", +); + +// 4. Complex transform - phone number normalization +export const normalizedPhoneSchema = zBrand( + z + .string() + .regex(/^\+?[\d\s()-]+$/, "Invalid phone format") + .transform((val) => val.replace(/\D/g, "")) // Remove non-digits + .transform((val) => { + // Add country code if missing + if (val.length === 10) return `+1${val}`; + if (!val.startsWith("+")) return `+${val}`; + return val; + }) + .refine((val) => val.length >= 11 && val.length <= 15, { + message: "Phone number must be 11-15 digits including country code", + }), + "NormalizedPhone", +); + +// 5. Custom validator with Convex mapping +export const urlSlugSchema = createBrandedValidator( + z + .string() + .regex( + /^[a-z0-9-]+$/, + "Only lowercase letters, numbers, and hyphens allowed", + ) + .min(3, "Slug must be at least 3 characters") + .max(50, "Slug must be at most 50 characters") + .transform((val) => val.toLowerCase().replace(/\s+/g, "-")), + "URLSlug", + () => v.string(), + { + registryKey: "url-slug", + }, +); + +// 6. Union with transform - flexible boolean +export const flexibleBooleanSchema = zBrand( + z.union([ + z.boolean(), + z.string().transform((s) => s.toLowerCase() === "true" || s === "1"), + z.number().transform((n) => n !== 0), + ]), + "FlexibleBoolean", +); + +// 7. Nested transform - user profile +export const userProfileSchema = zBrand( + z.object({ + displayName: z + .string() + .min(2, "Display name must be at least 2 characters") + .transform((name) => name.trim()) + .transform((name) => { + // Capitalize first letter of each word + return name.replace(/\b\w/g, (l) => l.toUpperCase()); + }), + bio: z + .string() + .max(500, "Bio must be 500 characters or less") + .optional() + .transform((bio) => bio?.trim() || undefined), + socialLinks: z + .array( + z.object({ + platform: z.enum(["twitter", "github", "linkedin"]), + username: z.string().transform((u) => u.replace(/^@/, "")), // Remove @ if present + }), + ) + .optional() + .default([]), + }), + "UserProfile", +); + +// Define various test schemas +export const testRecordSchema = z.object({ + name: z.string(), + + // Simple optional with default + age: z.number().optional().default(25), + + // Record with optional values that have defaults + settings: z.record(z.string(), settingsValueSchema).default({}), + + // Record with nullable values that have defaults + scores: z.record(z.string(), scoresValueSchema).default({}), + + // Nested object with defaults + profile: z + .object({ + bio: z.string().optional().default("No bio provided"), + avatar: z.string().nullable().default("default-avatar.png"), + preferences: z.record(z.string(), z.boolean().optional().default(false)), + }) + .optional() + .default({ + bio: "Default bio", + avatar: "default.png", + preferences: {}, + }), + + // Array with defaults + tags: z.array(z.string()).optional().default([]), + + // Union with default + status: z + .union([z.literal("active"), z.literal("inactive"), z.literal("pending")]) + .optional() + .default("pending"), + + // Tuple converted to object with _0, _1 keys + coordinates: z.tuple([z.number(), z.number()]).optional().default([0, 0]), + + // Complex nested structure + metadata: z.record(z.string(), metadataValueSchema).optional().default({}), + + // Advanced Zod v4 fields + email: lowercaseEmailSchema.optional(), + rating: positiveNumberSchema.optional(), + completionRate: percentageSchema.optional(), + phone: normalizedPhoneSchema.optional(), + slug: urlSlugSchema().optional(), + isActive: flexibleBooleanSchema.optional(), + userProfile: userProfileSchema.optional(), + + // Related ID example + createdBy: zid("users").optional(), + + // Date transform example - bidirectional ISO string handling + lastModified: zBrand( + z + .date() + .default(() => new Date()) + .transform((date) => date.toISOString()), + "ISODateString", + ).optional(), +}); + +// Create table with the converted schema +export const zodTestTable = defineTable(zodToConvex(testRecordSchema)); + +// Export the schema for use in functions +export type TestRecord = z.infer; diff --git a/package-lock.json b/package-lock.json index 7f97d606..d851e74d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11418,7 +11418,7 @@ }, "packages/convex-helpers/dist": { "name": "convex-helpers", - "version": "0.1.101", + "version": "0.1.101-alpha.1", "license": "Apache-2.0", "bin": { "convex-helpers": "bin.cjs" diff --git a/packages/convex-helpers/package.json b/packages/convex-helpers/package.json index 989c00c1..c9d0fadf 100644 --- a/packages/convex-helpers/package.json +++ b/packages/convex-helpers/package.json @@ -1,6 +1,6 @@ { "name": "convex-helpers", - "version": "0.1.101", + "version": "0.1.101-alpha.1", "description": "A collection of useful code to complement the official convex package.", "type": "module", "bin": { @@ -115,6 +115,10 @@ "types": "./server/zod.d.ts", "default": "./server/zod.js" }, + "./server/zodV4": { + "types": "./server/zodV4.d.ts", + "default": "./server/zodV4.js" + }, "./react/*": { "types": "./react/*.d.ts", "default": "./react/*.js" diff --git a/packages/convex-helpers/server/zodV4.test.ts b/packages/convex-helpers/server/zodV4.test.ts new file mode 100644 index 00000000..9566f977 --- /dev/null +++ b/packages/convex-helpers/server/zodV4.test.ts @@ -0,0 +1,3190 @@ +/* eslint-disable @typescript-eslint/no-unused-vars */ +import type { + DataModelFromSchemaDefinition, + QueryBuilder, + MutationBuilder, + ActionBuilder, +} from "convex/server"; +import { + defineTable, + defineSchema, + queryGeneric, + mutationGeneric, + actionGeneric, +} from "convex/server"; +import { convexTest } from "convex-test"; +import { describe, expect, expectTypeOf, test } from "vitest"; +import { modules } from "./setup.test.js"; +import { + zid, + zCustomQuery, + zCustomMutation, + zCustomAction, + zodToConvex, + zodToConvexFields, + zodOutputToConvex, + convexToZod, + convexToZodFields, + withSystemFields, + zBrand, + createBidirectionalSchema, + convexZodTestUtils, + registryHelpers, + createBrandedValidator, + createParameterizedBrandedValidator, +} from "./zodV4.js"; +import { z } from "zod/v4"; +import { customCtx } from "convex-helpers/server/customFunctions"; +import type { + VString, + VFloat64, + VObject, + VId, + Infer, + GenericId, +} from "convex/values"; +import { v } from "convex/values"; + +export const kitchenSinkValidator = { + email: z.email(), + userId: zid("users"), + // Otherwise this is equivalent, but wouldn't catch zid("CounterTable") + // counterId: zid("counter_table"), + num: z.number().min(0), + nan: z.nan(), + bigint: z.bigint(), + bool: z.boolean(), + null: z.null(), + any: z.unknown(), + array: z.array(z.string()), + object: z.object({ a: z.string(), b: z.number() }), + objectWithOptional: z.object({ a: z.string(), b: z.number().optional() }), + record: z.record(z.string(), z.union([z.number(), z.string()])), + union: z.union([z.string(), z.number()]), + discriminatedUnion: z.discriminatedUnion("kind", [ + z.object({ kind: z.literal("a"), a: z.string() }), + z.object({ kind: z.literal("b"), b: z.number() }), + ]), + literal: z.literal("hi"), + tuple: z.tuple([z.string(), z.number()]), + lazy: z.lazy(() => z.string()), + enum: z.enum(["a", "b"]), + + // v4: Four methods that replaced z.effect + transform: z.string().transform((val) => val.toUpperCase()), // Changes output type to string + refine: z.string().refine((val) => val.length >= 3, { message: "Too short" }), // Validation only, preserves type + overwrite: z + .number() + .overwrite((val) => Math.round(val)) + .max(100), // Type-preserving transform, allows chaining + check: z.array(z.string()).check((ctx) => { + // Complex validation with custom issues (replaces .superRefine()) + if (ctx.value.length > 5) { + ctx.issues.push({ + code: "too_big", + origin: "array", + maximum: 5, + inclusive: true, + message: "Array too long", + input: ctx.value, + }); + } + }), + + // v4: Test the chaining that was BROKEN in v3 but WORKS in v4 + chainedRefinements: z + .string() + .refine((val) => val.includes("@"), { message: "Must contain @" }) + .min(5, { message: "Must be at least 5 chars" }) // ✅ This works in v4! + .max(50, { message: "Must be at most 50 chars" }) // ✅ This works in v4! + .refine((val) => val.endsWith(".com"), { message: "Must end with .com" }) + .optional(), // ✅ Even more chaining works! + + optional: z.object({ a: z.string(), b: z.number() }).optional(), + // For Convex compatibility, we need to avoid patterns that produce undefined + // Instead, use union with null for nullable fields and .optional() for optional fields + nullableOptional: z.union([z.string(), z.null()]).optional(), + optionalNullable: z.union([z.string(), z.null()]).optional(), + nullable: z.nullable(z.string()), + // z.string().brand("branded") also works, but zBrand also brands the input + branded: zBrand(z.string(), "branded"), + default: z.string().default("default"), + readonly: z.object({ a: z.string(), b: z.number() }).readonly(), + pipeline: z.number().pipe(z.coerce.string()), +}; + +// Debug: Let's see what zodToConvexFields produces +const convexFields = zodToConvexFields(kitchenSinkValidator); +// Type test to see what TypeScript infers +type ConvexFieldsType = typeof convexFields; + +const schema = defineSchema({ + sink: defineTable(convexFields).index("email", ["email"]), + users: defineTable({}), +}); + +type DataModel = DataModelFromSchemaDefinition; +const query = queryGeneric as QueryBuilder; + +const zQuery = zCustomQuery(query, { + args: {}, + input: async (ctx, args) => { + return { ctx: {}, args: {} }; + }, +}); + +// v4 Performance and Feature Tests + +describe("Zod v4 Performance Features", () => { + test("string validation performance", () => { + // v4 is 14x faster at string parsing + const emailSchema = z.email(); + const start = performance.now(); + for (let i = 0; i < 1000; i++) { + emailSchema.parse("test@example.com"); + } + const end = performance.now(); + // Should be very fast with v4 optimizations + expect(end - start).toBeLessThan(50); + }); + + test("array validation performance", () => { + // v4 is 7x faster at array parsing + const arraySchema = z.array(z.string()); + const testArray = Array(100).fill("test"); + const start = performance.now(); + for (let i = 0; i < 100; i++) { + arraySchema.parse(testArray); + } + const end = performance.now(); + // Should be very fast with v4 optimizations + expect(end - start).toBeLessThan(50); + }); + + test("object validation performance", () => { + // v4 is 6.5x faster at object parsing + const objectSchema = z.object({ + name: z.string(), + age: z.number(), + email: z.email(), + tags: z.array(z.string()), + }); + const testObject = { + name: "John", + age: 30, + email: "john@example.com", + tags: ["user", "active"], + }; + const start = performance.now(); + for (let i = 0; i < 1000; i++) { + objectSchema.parse(testObject); + } + const end = performance.now(); + // Should be very fast with v4 optimizations + expect(end - start).toBeLessThan(100); + }); +}); + +describe("Zod v4 Enhanced Validation", () => { + test("improved string validators", () => { + const emailSchema = z.email(); + const urlSchema = z.string().url(); + const uuidSchema = z.string().uuid(); + const datetimeSchema = z.string().datetime(); + + expect(emailSchema.parse("test@example.com")).toBe("test@example.com"); + expect(urlSchema.parse("https://example.com")).toBe("https://example.com"); + expect( + uuidSchema.parse("550e8400-e29b-41d4-a716-446655440000"), + ).toBeTruthy(); + expect(datetimeSchema.parse("2023-01-01T00:00:00Z")).toBeTruthy(); + }); + + test("enhanced number validators", () => { + const intSchema = z.number().int(); + const positiveSchema = z.number().positive(); + const finiteSchema = z.number().finite(); + const safeSchema = z.number().safe(); + + expect(intSchema.parse(42)).toBe(42); + expect(positiveSchema.parse(1)).toBe(1); + expect(finiteSchema.parse(100)).toBe(100); + expect(safeSchema.parse(Number.MAX_SAFE_INTEGER)).toBe( + Number.MAX_SAFE_INTEGER, + ); + }); +}); + +describe("Zod v4 Convex Integration", () => { + test("zid validator", () => { + const userIdSchema = zid("users"); + // zid validates string format + expect(userIdSchema.parse("j57w5jqkm7en7g3qchebbvhqy56ygdqy")).toBeTruthy(); + }); + + test("zodToConvex conversion", () => { + const zodSchema = z.object({ + name: z.string(), + age: z.number().int().positive(), + email: z.email(), + tags: z.array(z.string()), + isActive: z.boolean(), + }); + + const convexValidator = zodToConvex(zodSchema); + expect(convexValidator.kind).toBe("object"); + expect(convexValidator.fields.name.kind).toBe("string"); + expect(convexValidator.fields.age.kind).toBe("float64"); + expect(convexValidator.fields.email.kind).toBe("string"); + expect(convexValidator.fields.tags.kind).toBe("array"); + expect(convexValidator.fields.isActive.kind).toBe("boolean"); + }); + + test("convexToZod conversion", () => { + const convexSchema = v.object({ + id: v.id("users"), + name: v.string(), + count: v.number(), + active: v.boolean(), + items: v.array(v.string()), + }); + + const zodSchema = convexToZod(convexSchema); + + const validData = { + id: "j57w5jqkm7en7g3qchebbvhqy56ygdqy", + name: "Test", + count: 42, + active: true, + items: ["a", "b", "c"], + }; + + expect(zodSchema.parse(validData)).toEqual(validData); + }); +}); + +describe("Zod v4 Custom Functions", () => { + const schema = defineSchema({ + testTable: defineTable({ + email: v.string(), + age: v.number(), + tags: v.array(v.string()), + }), + users: defineTable({}), + }); + type DataModel = DataModelFromSchemaDefinition; + const query = queryGeneric as QueryBuilder; + + test("custom query with zod validation", async () => { + // Test the zCustomQuery function with Zod validators converted to Convex + const zodArgs = { + email: z.email(), + minAge: z.number().min(0), + }; + + const testQuery = zCustomQuery(query, { + args: zodToConvexFields(zodArgs), + input: async (ctx, args) => { + // Validate that args are properly typed and validated + expect(typeof args.email).toBe("string"); + expect(typeof args.minAge).toBe("number"); + return { ctx: {}, args: {} }; + }, + }); + + // Test that the query was created successfully + expect(testQuery).toBeDefined(); + expect(typeof testQuery).toBe("function"); + }); +}); + +describe("Zod v4 System Fields", () => { + test("withSystemFields helper", () => { + const userFields = withSystemFields("users", { + name: z.string(), + email: z.email(), + role: z.enum(["admin", "user", "guest"]), + }); + + expect(userFields._id).toBeDefined(); + expect(userFields._creationTime).toBeDefined(); + expect(userFields.name).toBeDefined(); + expect(userFields.email).toBeDefined(); + expect(userFields.role).toBeDefined(); + }); +}); + +describe("Zod v4 Output Validation", () => { + test("zodOutputToConvex for transformed values", () => { + const schema = z.object({ + date: z.string().transform((s) => new Date(s)), + count: z.string().transform((s) => parseInt(s, 10)), + uppercase: z.string().transform((s) => s.toUpperCase()), + }); + + // Output validator should handle the transformed types + const outputValidator = zodOutputToConvex(schema); + expect(outputValidator.kind).toBe("object"); + // After transformation, these remain as their input types for Convex + expect(outputValidator.fields.date.kind).toBe("any"); + expect(outputValidator.fields.count.kind).toBe("any"); + expect(outputValidator.fields.uppercase.kind).toBe("any"); + }); + + test("default values with zodOutputToConvex", () => { + const schema = z.object({ + name: z.string().default("Anonymous"), + count: z.number().default(0), + active: z.boolean().default(true), + }); + + const outputValidator = zodOutputToConvex(schema); + expect(outputValidator.kind).toBe("object"); + // Defaults make fields non-optional in output + expect(outputValidator.fields.name.isOptional).toBe("required"); + expect(outputValidator.fields.count.isOptional).toBe("required"); + expect(outputValidator.fields.active.isOptional).toBe("required"); + }); +}); + +describe("Zod v4 Branded Types", () => { + test("zBrand for input and output branding", () => { + const UserId = zBrand(z.string(), "UserId"); + const userIdSchema = z.object({ + id: UserId, + name: z.string(), + }); + + type UserInput = z.input; + type UserOutput = z.output; + + // Test that branded types exist and work + const brandedValue = UserId.parse("test-id"); + expect(brandedValue).toBe("test-id"); + + // Test that the schema accepts branded values + const validUser = userIdSchema.parse({ + id: "user-123", + name: "Test User", + }); + expect(validUser.id).toBe("user-123"); + expect(validUser.name).toBe("Test User"); + }); + + test("branded types with Convex conversion", () => { + console.log("=== BRANDED TYPES TEST START ==="); + + const userIdBranded = zBrand(z.string(), "UserId"); + console.log("Created userIdBranded:", userIdBranded.constructor.name); + + const brandedSchema = z.object({ + userId: userIdBranded, + score: zBrand(z.number(), "Score"), + count: zBrand(z.bigint(), "Count"), + }); + console.log("Created brandedSchema:", brandedSchema.constructor.name); + + console.log("About to call zodToConvex..."); + const convexValidator = zodToConvex(brandedSchema); + console.log("zodToConvex result:", convexValidator); + + expect(convexValidator.kind).toBe("object"); + expect(convexValidator.fields.userId.kind).toBe("string"); + expect(convexValidator.fields.score.kind).toBe("float64"); + expect(convexValidator.fields.count.kind).toBe("int64"); + }); +}); + +describe("Zod v4 Advanced Features", () => { + test("discriminated unions", () => { + const resultSchema = z.discriminatedUnion("status", [ + z.object({ + status: z.literal("success"), + data: z.any(), + timestamp: z.string().datetime(), + }), + z.object({ + status: z.literal("error"), + error: z.object({ + code: z.string(), + message: z.string(), + details: z.any().optional(), + }), + timestamp: z.string().datetime(), + }), + ]); + + const convexValidator = zodToConvex(resultSchema); + expect(convexValidator.kind).toBe("union"); + expect(convexValidator.members).toHaveLength(2); + }); + + test("recursive schemas with lazy", () => { + type Category = { + name: string; + subcategories?: Category[]; + }; + + const categorySchema: z.ZodType = z.lazy(() => + z.object({ + name: z.string(), + subcategories: z.array(categorySchema).optional(), + }), + ); + + // Lazy schemas work with Convex conversion + const convexValidator = zodToConvex(categorySchema); + expect(convexValidator.kind).toBe("object"); + }); +}); + +// Type tests +describe("Zod v4 Type Inference", () => { + test("type inference with Convex integration", () => { + const userSchema = z.object({ + id: zid("users"), + email: z.email(), + profile: z.object({ + name: z.string(), + age: z.number().positive().int(), + bio: z.string().optional(), + }), + settings: z.record(z.string(), z.boolean()), + roles: z.array(z.enum(["admin", "user", "guest"])), + }); + + type User = z.infer; + + // Type checks + expectTypeOf().toMatchTypeOf<{ + id: string; + email: string; + profile: { + name: string; + age: number; + bio?: string; + }; + settings: Record; + roles: ("admin" | "user" | "guest")[]; + }>(); + + // Convex conversion preserves types + const convexValidator = zodToConvex(userSchema); + type ConvexUser = Infer; + expectTypeOf().toMatchTypeOf(); + }); +}); + +describe("Zod v4 New Testing Utilities", () => { + describe("createBidirectionalSchema", () => { + test("creates bidirectional schemas correctly", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ + name: z.string(), + email: z.email(), + age: z.number().min(0), + role: z.enum(["admin", "user", "guest"]), + }), + post: z.object({ + title: z.string(), + content: z.string(), + authorId: zid("users"), + tags: z.array(z.string()), + }), + }); + + // Test that both zod and convex versions exist + expect(schemas.zod.user).toBeDefined(); + expect(schemas.zod.post).toBeDefined(); + expect(schemas.convex.user).toBeDefined(); + expect(schemas.convex.post).toBeDefined(); + + // Test that validators can be used (functional testing instead of internal structure) + const userValidator = schemas.convex.user; + const postValidator = schemas.convex.post; + + // Test that validators exist and are callable + expect(typeof userValidator).toBe("object"); + expect(typeof postValidator).toBe("object"); + + // Test that validators have expected properties + expect(userValidator).toBeDefined(); + expect(postValidator).toBeDefined(); + }); + + test("keys() method returns correct keys", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ name: z.string() }), + post: z.object({ title: z.string() }), + }); + + const keys = schemas.keys(); + expect(keys).toContain("user"); + expect(keys).toContain("post"); + expect(keys).toHaveLength(2); + }); + + test("pick() method works correctly", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ name: z.string() }), + post: z.object({ title: z.string() }), + comment: z.object({ content: z.string() }), + }); + + const picked = schemas.pick("user", "post"); + + expect(picked.zod.user).toBeDefined(); + expect(picked.zod.post).toBeDefined(); + expect(Object.keys(picked.zod)).toEqual( + expect.arrayContaining(["user", "post"]), + ); + expect(Object.keys(picked.zod)).toHaveLength(2); + + expect(picked.convex.user).toBeDefined(); + expect(picked.convex.post).toBeDefined(); + expect(Object.keys(picked.convex)).toEqual( + expect.arrayContaining(["user", "post"]), + ); + expect(Object.keys(picked.convex)).toHaveLength(2); + }); + + test("extend() method works correctly", () => { + const baseSchemas = createBidirectionalSchema({ + user: z.object({ name: z.string() }), + }); + + const extendedSchemas = baseSchemas.extend({ + post: z.object({ title: z.string() }), + comment: z.object({ content: z.string() }), + }); + + const keys = extendedSchemas.keys(); + expect(keys).toContain("user"); + expect(keys).toContain("post"); + expect(keys).toContain("comment"); + expect(keys).toHaveLength(3); + }); + }); + + describe("convexZodTestUtils", () => { + const testSchema = z.object({ + name: z.string().min(1), + email: z.email(), + age: z.number().min(0).max(150), + active: z.boolean(), + }); + + test("testValueConsistency with valid values", () => { + const results = convexZodTestUtils.testValueConsistency(testSchema, { + valid: [ + { name: "John", email: "john@example.com", age: 25, active: true }, + { name: "Jane", email: "jane@test.org", age: 30, active: false }, + ], + invalid: [], + }); + + expect(results.passed).toBe(2); + expect(results.failed).toBe(0); + expect(results.errors).toHaveLength(0); + }); + + test("testValueConsistency with invalid values", () => { + const results = convexZodTestUtils.testValueConsistency(testSchema, { + valid: [], + invalid: [ + { name: "", email: "john@example.com", age: 25, active: true }, // empty name + { name: "John", email: "invalid-email", age: 25, active: true }, // invalid email + { name: "John", email: "john@example.com", age: -5, active: true }, // negative age + { name: "John", email: "john@example.com", age: 200, active: true }, // age too high + ], + }); + + expect(results.passed).toBe(4); // All invalid values should fail validation (which is correct) + expect(results.failed).toBe(0); + expect(results.errors).toHaveLength(0); + }); + + test("testValueConsistency detects actual validation inconsistencies", () => { + // Test with values that should be valid but fail + const results = convexZodTestUtils.testValueConsistency(testSchema, { + valid: [ + { name: "", email: "john@example.com", age: 25, active: true }, // This should fail + ], + invalid: [], + }); + + expect(results.passed).toBe(0); + expect(results.failed).toBe(1); + expect(results.errors).toHaveLength(1); + const firstError = results.errors[0]; + if (!firstError) { + throw new Error("Expected error to be defined"); + } + expect(firstError.type).toBe("valid_value_failed_zod"); + }); + + test("generateTestData creates valid data", () => { + const generated = convexZodTestUtils.generateTestData(testSchema); + + expect(generated).toHaveProperty("name"); + expect(generated).toHaveProperty("email"); + expect(generated).toHaveProperty("age"); + expect(generated).toHaveProperty("active"); + + expect(typeof generated.name).toBe("string"); + expect(typeof generated.email).toBe("string"); + expect(typeof generated.age).toBe("number"); + expect(typeof generated.active).toBe("boolean"); + + // The generated data should be valid + const parseResult = testSchema.safeParse(generated); + expect(parseResult.success).toBe(true); + }); + + test("generateTestData handles different schema types", () => { + // Test string + const stringData = convexZodTestUtils.generateTestData(z.string()); + expect(typeof stringData).toBe("string"); + + // Test number + const numberData = convexZodTestUtils.generateTestData(z.number()); + expect(typeof numberData).toBe("number"); + + // Test boolean + const booleanData = convexZodTestUtils.generateTestData(z.boolean()); + expect(typeof booleanData).toBe("boolean"); + + // Test array + const arrayData = convexZodTestUtils.generateTestData( + z.array(z.string()), + ); + expect(Array.isArray(arrayData)).toBe(true); + expect(arrayData.length).toBeGreaterThan(0); + + // Test enum + const enumData = convexZodTestUtils.generateTestData( + z.enum(["a", "b", "c"]), + ); + expect(["a", "b", "c"]).toContain(enumData); + + // Test literal + const literalData = convexZodTestUtils.generateTestData( + z.literal("test"), + ); + expect(literalData).toBe("test"); + }); + + test("generateTestData handles optional and nullable", () => { + // Optional should sometimes return undefined + const optionalSchema = z.string().optional(); + let hasUndefined = false; + let hasString = false; + + // Run multiple times to check randomness + for (let i = 0; i < 20; i++) { + const result = convexZodTestUtils.generateTestData(optionalSchema); + if (result === undefined) hasUndefined = true; + if (typeof result === "string") hasString = true; + } + + expect(hasUndefined || hasString).toBe(true); // Should have at least one type + + // Nullable should sometimes return null + const nullableSchema = z.string().nullable(); + let hasNull = false; + hasString = false; + + for (let i = 0; i < 20; i++) { + const result = convexZodTestUtils.generateTestData(nullableSchema); + if (result === null) hasNull = true; + if (typeof result === "string") hasString = true; + } + + expect(hasNull || hasString).toBe(true); // Should have at least one type + }); + + test("testConversionRoundTrip works correctly", () => { + const result = convexZodTestUtils.testConversionRoundTrip(testSchema); + + expect(result).toHaveProperty("success"); + expect(result).toHaveProperty("originalValid"); + expect(result).toHaveProperty("roundTripValid"); + + // For most schemas, round-trip should work + expect(result.success).toBe(true); + expect(result.originalValid).toBe(true); + expect(result.roundTripValid).toBe(true); + }); + + test("testConversionRoundTrip with custom test value", () => { + const testValue = { + name: "Test", + email: "test@example.com", + age: 25, + active: true, + }; + const result = convexZodTestUtils.testConversionRoundTrip( + testSchema, + testValue, + ); + + expect(result.success).toBe(true); + expect(result.originalValid).toBe(true); + expect(result.roundTripValid).toBe(true); + }); + + test("validateBidirectionalSchemas works correctly", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ + name: z.string(), + age: z.number(), + }), + post: z.object({ + title: z.string(), + published: z.boolean(), + }), + }); + + const results = convexZodTestUtils.validateBidirectionalSchemas(schemas); + + expect(results).toHaveProperty("user"); + expect(results).toHaveProperty("post"); + + const userResult = results.user; + if (!userResult) { + throw new Error("Expected user result to be defined"); + } + expect(userResult.zodValid).toBe(true); + expect(userResult.hasConvexValidator).toBe(true); + expect(userResult.testValue).toBeDefined(); + + const postResult = results.post; + if (!postResult) { + throw new Error("Expected post result to be defined"); + } + expect(postResult.zodValid).toBe(true); + expect(postResult.hasConvexValidator).toBe(true); + expect(postResult.testValue).toBeDefined(); + }); + + test("validateBidirectionalSchemas with custom test data", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ + name: z.string(), + age: z.number(), + }), + }); + + const results = convexZodTestUtils.validateBidirectionalSchemas(schemas, { + user: { name: "Custom Test", age: 42 }, + }); + + const userResult = results.user; + if (!userResult) { + throw new Error("Expected user result to be defined"); + } + expect(userResult.zodValid).toBe(true); + expect(userResult.testValue).toEqual({ name: "Custom Test", age: 42 }); + }); + }); + + describe("Custom Branded Validators", () => { + test("createBrandedValidator creates bidirectional branded types", () => { + // Create a branded email validator + const zEmail = createBrandedValidator( + z.string().email(), + "Email", + () => v.string(), + { + registryKey: "email", + convexToZodFactory: () => z.string().email(), + }, + ); + + // Test Zod → Convex + const emailSchema = z.object({ + userEmail: zEmail(), + adminEmail: zEmail(), + }); + + const convexFields = zodToConvexFields(emailSchema.shape); + expect(convexFields.userEmail.kind).toBe("string"); + expect(convexFields.adminEmail.kind).toBe("string"); + + // Test validation + const validData = { + userEmail: "user@example.com", + adminEmail: "admin@example.com", + }; + const invalidData = { + userEmail: "not-an-email", + adminEmail: "admin@example.com", + }; + + expect(emailSchema.safeParse(validData).success).toBe(true); + expect(emailSchema.safeParse(invalidData).success).toBe(false); + }); + + test("createParameterizedBrandedValidator creates parameterized branded types", () => { + // Create a custom ID validator for different entity types + const zEntityId = createParameterizedBrandedValidator( + (entity: string) => + z.string().regex(new RegExp(`^${entity}_[a-zA-Z0-9]+$`)), + (entity: string) => `${entity}Id` as const, + (entity: string) => v.string(), + ); + + // Use it for different entities + const schema = z.object({ + userId: zEntityId("user"), + postId: zEntityId("post"), + commentId: zEntityId("comment"), + }); + + // Test validation + const validData = { + userId: "user_abc123", + postId: "post_xyz789", + commentId: "comment_def456", + }; + + const invalidData = { + userId: "post_abc123", // Wrong prefix + postId: "post_xyz789", + commentId: "comment_def456", + }; + + expect(schema.safeParse(validData).success).toBe(true); + expect(schema.safeParse(invalidData).success).toBe(false); + + // Test conversion to Convex + const convexFields = zodToConvexFields(schema.shape); + expect(convexFields.userId.kind).toBe("string"); + expect(convexFields.postId.kind).toBe("string"); + expect(convexFields.commentId.kind).toBe("string"); + }); + + test("Custom branded validators preserve type information", () => { + // Create domain-specific branded types + const zPositiveNumber = createBrandedValidator( + z.number().positive(), + "PositiveNumber", + () => v.float64(), + ); + + const zUrl = createBrandedValidator(z.string().url(), "URL", () => + v.string(), + ); + + const zDateString = createBrandedValidator( + z.string().regex(/^\d{4}-\d{2}-\d{2}$/), + "DateString", + () => v.string(), + ); + + // Use in a complex schema + const productSchema = z.object({ + price: zPositiveNumber(), + imageUrl: zUrl(), + releaseDate: zDateString(), + }); + + // Test type inference + type Product = z.infer; + + // The schema itself can be used as a type! + const product: Product = { + price: 29.99, + imageUrl: "https://example.com/image.jpg", + releaseDate: "2024-01-15", + } as Product; + + // Test validation + expect(productSchema.safeParse(product).success).toBe(true); + expect( + productSchema.safeParse({ + price: -10, // Invalid: negative + imageUrl: "not a url", + releaseDate: "2024/01/15", // Invalid format + }).success, + ).toBe(false); + + // Test conversion maintains validators + const convexFields = zodToConvexFields(productSchema.shape); + expect(convexFields.price.kind).toBe("float64"); + expect(convexFields.imageUrl.kind).toBe("string"); + expect(convexFields.releaseDate.kind).toBe("string"); + }); + + test("Round-trip conversion preserves branded validator behavior", () => { + // Create a branded percentage validator (0-100) + const zPercentage = createBrandedValidator( + z.number().min(0).max(100), + "Percentage", + () => v.float64(), + ); + + const schema = z.object({ + completion: zPercentage(), + }); + + // Convert to Convex and back + const convexFields = zodToConvexFields(schema.shape); + const roundTripFields = convexToZodFields({ + completion: convexFields.completion, + }); + + // Original validation should work + expect(schema.safeParse({ completion: 50 }).success).toBe(true); + expect(schema.safeParse({ completion: 150 }).success).toBe(false); + + // Round-trip should maintain basic type (though not the brand constraints) + const roundTripSchema = z.object(roundTripFields); + expect(roundTripSchema.safeParse({ completion: 50 }).success).toBe(true); + // Note: Round-trip loses the min/max constraints since Convex doesn't preserve them + expect(roundTripSchema.safeParse({ completion: 150 }).success).toBe(true); + }); + }); + + describe("Bidirectional Schema Advanced Tests", () => { + test("bidirectional schemas maintain type safety", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ + name: z.string(), + age: z.number(), + }), + }); + + // Test that types are preserved + type ZodUser = z.infer; + type ConvexUser = Infer; + + // These should be equivalent types + expectTypeOf().toEqualTypeOf(); + + // Functional validation + expect(schemas.zod.user).toBeDefined(); + expect(schemas.convex.user).toBeDefined(); + expect(schemas.convex.user.kind).toBe("object"); + }); + + test("bidirectional handles complex nested schemas", () => { + const schemas = createBidirectionalSchema({ + complex: z.object({ + id: zid("users"), + nested: z.object({ + array: z.array(z.union([z.string(), z.number()])), + optional: z.string().optional(), + nullable: z.number().nullable(), + }), + record: z.record(z.string(), z.boolean()), + }), + }); + + // Test the conversion worked + expect(schemas.convex.complex.kind).toBe("object"); + expect(schemas.convex.complex.fields.nested.kind).toBe("object"); + expect(schemas.convex.complex.fields.id.kind).toBe("id"); + expect(schemas.convex.complex.fields.record.kind).toBe("record"); + + // Test nested object structure + const nestedFields = schemas.convex.complex.fields.nested.fields; + expect(nestedFields.array.kind).toBe("array"); + expect(nestedFields.optional.kind).toBe("union"); // optional becomes union with undefined + expect(nestedFields.nullable.kind).toBe("union"); // nullable becomes union with null + }); + + test("bidirectional schema conversion handles unsupported types gracefully", () => { + // Test with a type that might not convert cleanly + const schemas = createBidirectionalSchema({ + withTransform: z.object({ + date: z.string().transform((s) => new Date(s)), + }), + }); + + // Should still create valid schemas + expect(schemas.zod.withTransform).toBeDefined(); + expect(schemas.convex.withTransform).toBeDefined(); + expect(schemas.convex.withTransform.kind).toBe("object"); + + // Transform fields should become 'any' in Convex + expect(schemas.convex.withTransform.fields.date.kind).toBe("any"); + }); + + test("bidirectional schema creation performance", () => { + const start = performance.now(); + + const schemas = createBidirectionalSchema({ + schema1: z.object({ a: z.string() }), + schema2: z.object({ b: z.number() }), + schema3: z.object({ c: z.boolean() }), + schema4: z.object({ d: z.array(z.string()) }), + schema5: z.object({ e: z.record(z.string(), z.number()) }), + schema6: z.object({ f: z.union([z.string(), z.number()]) }), + schema7: z.object({ g: z.literal("test") }), + schema8: z.object({ h: z.enum(["a", "b", "c"]) }), + schema9: z.object({ i: z.string().optional() }), + schema10: z.object({ j: z.number().nullable() }), + }); + + const end = performance.now(); + + // Should be fast even with multiple schemas + expect(end - start).toBeLessThan(100); // Generous timeout for CI environments + + // Verify all schemas were created + expect(Object.keys(schemas.zod)).toHaveLength(10); + expect(Object.keys(schemas.convex)).toHaveLength(10); + }); + + test("bidirectional schemas work with Convex function signatures", () => { + const schemas = createBidirectionalSchema({ + createUser: z.object({ + name: z.string(), + email: z.email(), + }), + }); + + // Mock a Convex mutation using the schema + const mockMutation = { + args: schemas.convex.createUser, + handler: async (ctx: any, args: any) => { + // args should be typed correctly in real usage + expect(args).toHaveProperty("name"); + expect(args).toHaveProperty("email"); + return args; + }, + }; + + expect(mockMutation.args).toBeDefined(); + expect(mockMutation.args.kind).toBe("object"); + expect(mockMutation.args.fields.name.kind).toBe("string"); + expect(mockMutation.args.fields.email.kind).toBe("string"); // email becomes string in Convex + }); + + test("bidirectional schemas preserve constraint information", () => { + const schemas = createBidirectionalSchema({ + constrainedSchema: z.object({ + email: z.email(), + url: z.string().url(), + minString: z.string().min(5), + maxNumber: z.number().max(100), + enumValue: z.enum(["red", "green", "blue"]), + }), + }); + + // Test that the original Zod schema maintains all constraints + const zodSchema = schemas.zod.constrainedSchema; + + // Valid values should pass + expect( + zodSchema.safeParse({ + email: "test@example.com", + url: "https://example.com", + minString: "hello", + maxNumber: 50, + enumValue: "red", + }).success, + ).toBe(true); + + // Invalid values should fail + expect( + zodSchema.safeParse({ + email: "invalid-email", + url: "not-a-url", + minString: "hi", // too short + maxNumber: 150, // too big + enumValue: "purple", // not in enum + }).success, + ).toBe(false); + + // Convex schema should exist and be valid + expect(schemas.convex.constrainedSchema.kind).toBe("object"); + }); + + test("bidirectional schemas support method chaining", () => { + const baseSchemas = createBidirectionalSchema({ + user: z.object({ name: z.string() }), + }); + + const extendedSchemas = baseSchemas + .extend({ + post: z.object({ title: z.string() }), + }) + .extend({ + comment: z.object({ content: z.string() }), + }); + + const picked = extendedSchemas.pick("user", "post"); + + expect(extendedSchemas.keys()).toContain("user"); + expect(extendedSchemas.keys()).toContain("post"); + expect(extendedSchemas.keys()).toContain("comment"); + expect(extendedSchemas.keys()).toHaveLength(3); + + // Test picked schemas exist + expect(picked.zod.user).toBeDefined(); + expect(picked.zod.post).toBeDefined(); + expect(picked.convex.user).toBeDefined(); + expect(picked.convex.post).toBeDefined(); + + // Test that comment was not picked + expect("comment" in picked.zod).toBe(false); + expect("comment" in picked.convex).toBe(false); + }); + + test("bidirectional schemas maintain consistency in round-trip conversion", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ + name: z.string(), + age: z.number(), + tags: z.array(z.string()), + }), + }); + + // Convert Convex back to Zod + const convexToZodSchema = convexToZod(schemas.convex.user); + + // Test data + const testData = { name: "John", age: 30, tags: ["active", "admin"] }; + + // Both should validate the same data + expect(schemas.zod.user.parse(testData)).toEqual(testData); + expect(convexToZodSchema.parse(testData)).toEqual(testData); + }); + + test("bidirectional schemas handle validation errors consistently", () => { + const schemas = createBidirectionalSchema({ + user: z.object({ + email: z.email(), + age: z.number().min(18), + }), + }); + + const invalidData = { email: "not-an-email", age: 15 }; + + // Test Zod validation errors + const zodResult = schemas.zod.user.safeParse(invalidData); + expect(zodResult.success).toBe(false); + + // Verify error details exist + if (!zodResult.success) { + expect(zodResult.error.issues).toHaveLength(2); + expect(zodResult.error.issues.some((i) => i.path[0] === "email")).toBe( + true, + ); + expect(zodResult.error.issues.some((i) => i.path[0] === "age")).toBe( + true, + ); + } + }); + + test("bidirectional schemas can be reused across multiple contexts", () => { + const schemas = createBidirectionalSchema({ + address: z.object({ + street: z.string(), + city: z.string(), + zip: z.string().regex(/^\d{5}$/), + }), + }); + + // Reuse in another schema + const userWithAddress = z.object({ + name: z.string(), + address: schemas.zod.address, + }); + + // Verify nested schema works + const validUser = { + name: "John", + address: { street: "123 Main", city: "Boston", zip: "12345" }, + }; + + expect(userWithAddress.parse(validUser)).toEqual(validUser); + }); + + test("bidirectional schemas handle special Convex types", () => { + const schemas = createBidirectionalSchema({ + document: z.object({ + _id: zid("documents"), + authorId: zid("users"), + content: z.string(), + metadata: z.record(z.string(), z.any()), + }), + }); + + // Verify Convex ID fields + expect(schemas.convex.document.fields._id.kind).toBe("id"); + expect(schemas.convex.document.fields.authorId.kind).toBe("id"); + expect(schemas.convex.document.fields._id.tableName).toBe("documents"); + expect(schemas.convex.document.fields.authorId.tableName).toBe("users"); + }); + + test("bidirectional schemas preserve Zod-specific constraints not in Convex", () => { + const schemas = createBidirectionalSchema({ + userProfile: z.object({ + email: z.email(), // Email validation + website: z.url(), // URL validation + userId: z.uuid(), // UUID validation + serverIp: z.ipv4(), // IP validation + createdAt: z.date(), // ISO datetime validation + username: z.string().min(3).max(20), // Length constraints + age: z.number().positive().int(), // Number constraints + phonePattern: z.string().regex(/^\+\d{10,15}$/), // Regex validation + }), + }); + + // Test that bidirectional schema preserves all constraints + const validData = { + email: "user@example.com", + website: "https://example.com", + userId: "123e4567-e89b-12d3-a456-426614174000", + serverIp: "192.168.1.1", + createdAt: new Date("2023-12-25T10:30:00Z"), + username: "validuser", + age: 25, + phonePattern: "+1234567890", + }; + + const invalidData = { + email: "not-an-email", + website: "not-a-url", + userId: "not-a-uuid", + serverIp: "999.999.999.999", + createdAt: new Date("invalid-date"), // invalid date + username: "ab", // too short + age: -5, // negative + phonePattern: "invalid-phone", + }; + + // Original Zod schema should validate correctly + expect(schemas.zod.userProfile.safeParse(validData).success).toBe(true); + expect(schemas.zod.userProfile.safeParse(invalidData).success).toBe( + false, + ); + + // Convex schema should exist but constraints become basic types + expect(schemas.convex.userProfile.kind).toBe("object"); + expect(schemas.convex.userProfile.fields.email.kind).toBe("string"); + expect(schemas.convex.userProfile.fields.website.kind).toBe("string"); + expect(schemas.convex.userProfile.fields.userId.kind).toBe("string"); + expect(schemas.convex.userProfile.fields.serverIp.kind).toBe("string"); + expect(schemas.convex.userProfile.fields.createdAt.kind).toBe("float64"); // Date becomes float64 in Convex + }); + + test("basic round-trip conversion loses Zod-specific constraints (expected behavior)", () => { + const originalSchema = z.object({ + email: z.email(), + url: z.string().url(), + uuid: z.string().uuid(), + constrainedString: z.string().min(5).max(10), + positiveInt: z.number().positive().int(), + }); + + // Convert through basic round-trip (loses constraints) + const convexValidator = zodToConvex(originalSchema); + const roundTripSchema = convexToZod(convexValidator); + + const testData = { + email: "not-an-email", // Invalid email + url: "not-a-url", // Invalid URL + uuid: "not-a-uuid", // Invalid UUID + constrainedString: "ab", // Too short + positiveInt: -5, // Negative number + }; + + // Original schema should reject invalid data + expect(originalSchema.safeParse(testData).success).toBe(false); + + // Round-trip schema should accept it (constraints lost) + expect(roundTripSchema.safeParse(testData).success).toBe(true); + + // This demonstrates why bidirectional schemas are important! + }); + + test("bidirectional schema vs round-trip comparison", () => { + const zodSchema = z.object({ + email: z.email(), + age: z.number().min(18).max(100), + }); + + // Method 1: Bidirectional schema (preserves constraints) + const bidirectionalSchemas = createBidirectionalSchema({ + user: zodSchema, + }); + + // Method 2: Basic round-trip (loses constraints) + const convexValidator = zodToConvex(zodSchema); + const roundTripSchema = convexToZod(convexValidator); + + const invalidData = { email: "invalid", age: 15 }; + + // Bidirectional: Original schema still validates (constraints preserved) + expect(bidirectionalSchemas.zod.user.safeParse(invalidData).success).toBe( + false, + ); + + // Round-trip: Validation is lost (constraints lost) + expect(roundTripSchema.safeParse(invalidData).success).toBe(true); + + // Both have same Convex validator for backend usage + expect(bidirectionalSchemas.convex.user.kind).toBe("object"); + expect(convexValidator.kind).toBe("object"); + }); + + test("complex nested schema with mixed constraint types", () => { + const schemas = createBidirectionalSchema({ + complexForm: z.object({ + personalInfo: z.object({ + email: z.email(), + phone: z.string().regex(/^\+\d{10,15}$/), + age: z.number().min(18).max(120), + }), + preferences: z.object({ + newsletter: z.boolean(), + theme: z.enum(["light", "dark", "auto"]), + tags: z.array(z.string().min(1).max(50)), + }), + metadata: z.object({ + createdAt: z.date(), + updatedAt: z.date().optional(), + version: z.number().int().positive(), + }), + }), + }); + + const validComplexData = { + personalInfo: { + email: "test@example.com", + phone: "+1234567890", + age: 25, + }, + preferences: { + newsletter: true, + theme: "dark", + tags: ["developer", "typescript"], + }, + metadata: { + createdAt: new Date("2023-12-25T10:30:00Z"), + version: 1, + }, + }; + + const invalidComplexData = { + personalInfo: { + email: "invalid-email", + phone: "invalid-phone", + age: 15, // too young + }, + preferences: { + newsletter: true, + theme: "purple", // not in enum + tags: [""], // empty string not allowed + }, + metadata: { + createdAt: new Date("invalid-date"), + version: -1, // negative not allowed + }, + }; + + // Bidirectional schema preserves all nested constraints + expect(schemas.zod.complexForm.safeParse(validComplexData).success).toBe( + true, + ); + expect( + schemas.zod.complexForm.safeParse(invalidComplexData).success, + ).toBe(false); + + // Convex schema should handle the structure + expect(schemas.convex.complexForm.kind).toBe("object"); + expect(schemas.convex.complexForm.fields.personalInfo.kind).toBe( + "object", + ); + expect(schemas.convex.complexForm.fields.preferences.kind).toBe("object"); + expect(schemas.convex.complexForm.fields.metadata.kind).toBe("object"); + }); + }); +}); + +// ============================================================================ +// V3 PARITY TESTS - Ensuring v4 has all the coverage v3 had +// ============================================================================ + +describe("Zod v4 Kitchen Sink - Comprehensive Type Testing", () => { + test("all supported Zod types convert correctly to Convex", () => { + const kitchenSink = z.object({ + // Primitives + string: z.string(), + number: z.number(), + nan: z.nan(), + bigint: z.bigint(), + boolean: z.boolean(), + date: z.date(), + null: z.null(), + undefined: z.undefined(), + unknown: z.unknown(), + any: z.any(), + + // String variants + email: z.email(), + url: z.url(), + uuid: z.uuid(), + cuid: z.cuid(), + datetime: z.iso.datetime(), + ipv4: z.ipv4(), + + // Number variants + int: z.number().int(), + positive: z.number().positive(), + negative: z.number().negative(), + safe: z.number().safe(), + finite: z.number().finite(), + + // Complex types + array: z.array(z.string()), + tuple: z.tuple([z.string(), z.number(), z.boolean()]), + object: z.object({ + nested: z.string(), + deep: z.object({ + value: z.number(), + }), + }), + union: z.union([z.string(), z.number()]), + discriminatedUnion: z.discriminatedUnion("type", [ + z.object({ type: z.literal("text"), value: z.string() }), + z.object({ type: z.literal("number"), value: z.number() }), + ]), + literal: z.literal("exact"), + enum: z.enum(["red", "green", "blue"]), + nativeEnum: z.enum({ Admin: 1, User: 2, Guest: 3 }), + record: z.record(z.string(), z.number()), + recordWithUnionKey: z.record( + z.union([z.literal("a"), z.literal("b")]), + z.string(), + ), + + // Optional and nullable + optional: z.string().optional(), + nullable: z.number().nullable(), + nullableOptional: z.boolean().nullable().optional(), + optionalNullable: z.string().optional().nullable(), + + // Special types + convexId: zid("users"), + lazy: z.lazy(() => z.string()), + + // Transforms (should become 'any' in Convex) + transform: z.string().transform((s) => s.length), + preprocess: z.preprocess((val) => String(val), z.string()), + + // Refinements (should become base type in Convex) + refined: z.string().refine((s) => s.length > 5), + superRefine: z.string().superRefine((val, ctx) => { + if (val.length < 3) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: "Too short", + }); + } + }), + + // Special modifiers + readonly: z.string().readonly(), + branded: zBrand(z.string(), "UserId"), + + // Default values + withDefault: z.string().default("default"), + withCatch: z.number().catch(0), + }); + + const convexValidator = zodToConvex(kitchenSink); + + // Test basic structure + expect(convexValidator.kind).toBe("object"); + expect(convexValidator.fields).toBeDefined(); + + // Test primitives + expect(convexValidator.fields.string.kind).toBe("string"); + expect(convexValidator.fields.number.kind).toBe("float64"); + expect(convexValidator.fields.nan.kind).toBe("float64"); + expect(convexValidator.fields.bigint.kind).toBe("int64"); + expect(convexValidator.fields.boolean.kind).toBe("boolean"); + expect(convexValidator.fields.date.kind).toBe("float64"); + expect(convexValidator.fields.null.kind).toBe("null"); + expect(convexValidator.fields.undefined.kind).toBe("any"); // undefined becomes any + expect(convexValidator.fields.unknown.kind).toBe("any"); + expect(convexValidator.fields.any.kind).toBe("any"); + + // String variants all become string + expect(convexValidator.fields.email.kind).toBe("string"); + expect(convexValidator.fields.url.kind).toBe("string"); + expect(convexValidator.fields.uuid.kind).toBe("string"); + expect(convexValidator.fields.cuid.kind).toBe("string"); + expect(convexValidator.fields.datetime.kind).toBe("string"); + expect(convexValidator.fields.ipv4.kind).toBe("string"); + + // Number variants all become float64 + expect(convexValidator.fields.int.kind).toBe("float64"); + expect(convexValidator.fields.positive.kind).toBe("float64"); + expect(convexValidator.fields.negative.kind).toBe("float64"); + expect(convexValidator.fields.safe.kind).toBe("float64"); + expect(convexValidator.fields.finite.kind).toBe("float64"); + + // Complex types + expect(convexValidator.fields.array.kind).toBe("array"); + expect(convexValidator.fields.array.element.kind).toBe("string"); + expect(convexValidator.fields.tuple.kind).toBe("array"); + expect(convexValidator.fields.object.kind).toBe("object"); + expect(convexValidator.fields.union.kind).toBe("union"); + expect(convexValidator.fields.discriminatedUnion.kind).toBe("union"); + expect(convexValidator.fields.literal.kind).toBe("literal"); + expect(convexValidator.fields.literal.value).toBe("exact"); + expect(convexValidator.fields.enum.kind).toBe("union"); + expect(convexValidator.fields.nativeEnum.kind).toBe("union"); + expect(convexValidator.fields.record.kind).toBe("record"); + expect(convexValidator.fields.recordWithUnionKey.kind).toBe("record"); + + // Optional and nullable + expect(convexValidator.fields.optional.kind).toBe("union"); // optional becomes union with null + expect(convexValidator.fields.nullable.kind).toBe("union"); // nullable becomes union with null + expect(convexValidator.fields.nullableOptional.kind).toBe("union"); + expect(convexValidator.fields.optionalNullable.kind).toBe("union"); + + // Special types + expect(convexValidator.fields.convexId.kind).toBe("id"); + expect(convexValidator.fields.lazy.kind).toBe("string"); + + // Transforms become any + expect(convexValidator.fields.transform.kind).toBe("any"); + expect(convexValidator.fields.preprocess.kind).toBe("any"); + + // Refinements preserve base type + expect(convexValidator.fields.refined.kind).toBe("string"); + expect(convexValidator.fields.superRefine.kind).toBe("string"); + + // Modifiers + expect(convexValidator.fields.readonly.kind).toBe("string"); + expect(convexValidator.fields.branded.kind).toBe("string"); + + // Defaults make fields required + expect(convexValidator.fields.withDefault.isOptional).toBe("required"); + expect(convexValidator.fields.withCatch.isOptional).toBe("required"); + }); + + test("kitchen sink with actual data validation", () => { + const schema = z.object({ + name: z.string(), + age: z.number().int().positive(), + tags: z.array(z.string()), + metadata: z.record(z.string(), z.any()), + status: z.enum(["active", "inactive"]), + optional: z.string().optional(), + nullable: z.number().nullable(), + }); + + const testData = { + name: "Test User", + age: 25, + tags: ["tag1", "tag2"], + metadata: { key: "value", count: 42 }, + status: "active" as const, + optional: undefined, + nullable: null, + }; + + // Validate with Zod + const zodResult = schema.parse(testData); + expect(zodResult).toEqual(testData); + + // Convert and ensure structure is preserved + const convexValidator = zodToConvex(schema); + expect(convexValidator.kind).toBe("object"); + expect(Object.keys(convexValidator.fields)).toEqual( + Object.keys(schema.shape), + ); + }); +}); + +describe("Zod v4 Custom Function Patterns", () => { + const customFunctionSchema = defineSchema({ + users: defineTable({ + name: v.string(), + email: v.string(), + role: v.string(), + }), + sessions: defineTable({ + userId: v.id("users"), + token: v.string(), + }), + }); + type DataModel = DataModelFromSchemaDefinition; + const query = queryGeneric as QueryBuilder; + const mutation = mutationGeneric as MutationBuilder; + const action = actionGeneric as ActionBuilder; + + const zQuery = zCustomQuery(query, { + args: {}, + input: async (ctx, args) => { + return { ctx: {}, args: {} }; + }, + }); + + test("custom query with only context modification", async () => { + const withUser = zCustomQuery( + query, + customCtx(async (ctx) => { + // Simulate getting user from auth + const user = { id: "user123", name: "Test User", role: "admin" }; + return { user }; + }), + ); + + const getUserQuery = withUser({ + handler: async (ctx) => { + // ctx.user should be available + return ctx.user; + }, + }); + + expect(typeof getUserQuery).toBe("function"); + }); + + test("custom mutation with argument transformation", async () => { + const withAuth = zCustomMutation(mutation, { + args: { sessionId: v.id("sessions") }, + input: async (ctx, { sessionId }) => { + // Simulate session lookup + const session = { userId: "user123", token: "abc" }; + const user = { id: session.userId, name: "Test User" }; + return { + ctx: { user, session }, + args: { authenticatedUserId: session.userId }, + }; + }, + }); + + // Test type inference directly + type WithAuthType = typeof withAuth; + + const updateProfile = withAuth({ + args: { + name: z.string().min(1), + email: z.email(), + }, + handler: async (ctx, args) => { + // Should have access to: + // - ctx.user (from modification) + // - ctx.session (from modification) + // - args.authenticatedUserId (from transformation) + // - args.name, args.email (from function args) + return { + userId: args.authenticatedUserId, + name: args.name, + email: args.email, + }; + }, + }); + + expect(typeof updateProfile).toBe("function"); + }); + + test("custom action with complex argument modification", async () => { + const withRateLimit = zCustomAction(action, { + args: { + apiKey: v.string(), + rateLimitBucket: v.optional(v.string()), + }, + input: async (ctx, { apiKey, rateLimitBucket }) => { + // Simulate rate limit check + const bucket = rateLimitBucket || "default"; + const allowed = true; // Simulate check + + if (!allowed) { + throw new Error("Rate limit exceeded"); + } + + return { + ctx: { rateLimitBucket: bucket }, + args: { isRateLimited: false }, + }; + }, + }); + + const sendEmail = withRateLimit({ + args: { + to: z.email(), + subject: z.string(), + body: z.string(), + }, + handler: async (ctx, args) => { + // Has access to rate limit info and email args + return { + sent: true, + bucket: ctx.rateLimitBucket, + }; + }, + }); + + expect(typeof sendEmail).toBe("function"); + }); + + test("function with only return validation", async () => { + const getConfig = zQuery({ + handler: async (ctx) => { + return { + version: "1.0.0", + features: ["feature1", "feature2"], + settings: { + theme: "dark" as const, + language: "en", + }, + }; + }, + returns: z.object({ + version: z.string(), + features: z.array(z.string()), + settings: z.object({ + theme: z.enum(["light", "dark"]), + language: z.string(), + }), + }), + }); + + expect(typeof getConfig).toBe("function"); + }); + + test("nested custom builders", async () => { + // First level: add user + const withUser = zCustomQuery( + query, + customCtx(async (ctx) => ({ user: { id: "user123" } })), + ); + + // Second level: add permissions based on user + const withPermissions = zCustomQuery(withUser, { + args: {}, + input: async (ctx, args) => { + const permissions = ["read", "write"]; // Based on ctx.user + return { ctx: { permissions }, args: {} }; + }, + }); + + const secureQuery = withPermissions({ + handler: async (ctx) => { + // Has both user and permissions + return { + userId: ctx.user.id, + permissions: ctx.permissions, + }; + }, + }); + + expect(typeof secureQuery).toBe("function"); + }); +}); + +describe("Zod v4 Effects and Refinements", () => { + test("basic refinements", () => { + const schema = z.object({ + password: z.string().refine((val) => val.length >= 8, { + message: "Password must be at least 8 characters", + }), + email: z.email().refine((val) => val.endsWith("@company.com"), { + message: "Must be a company email", + }), + age: z.number().refine((val) => val >= 18 && val <= 100, { + message: "Age must be between 18 and 100", + }), + }); + + // Test valid data + const validData = { + password: "longpassword", + email: "user@company.com", + age: 25, + }; + expect(schema.parse(validData)).toEqual(validData); + + // Test Convex conversion (refinements are stripped) + const convexValidator = zodToConvex(schema); + expect(convexValidator.kind).toBe("object"); + expect(convexValidator.fields.password.kind).toBe("string"); + expect(convexValidator.fields.email.kind).toBe("string"); + expect(convexValidator.fields.age.kind).toBe("float64"); + }); + + test("super refinements with complex validation", () => { + const schema = z + .object({ + startDate: z.string(), + endDate: z.string(), + }) + .superRefine((data, ctx) => { + const start = new Date(data.startDate); + const end = new Date(data.endDate); + + if (end <= start) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: "End date must be after start date", + path: ["endDate"], + }); + } + }); + + // Test validation + const validData = { + startDate: "2023-01-01", + endDate: "2023-12-31", + }; + expect(schema.parse(validData)).toEqual(validData); + + // Test invalid data + const invalidData = { + startDate: "2023-12-31", + endDate: "2023-01-01", + }; + expect(() => schema.parse(invalidData)).toThrow(); + + // Convex conversion preserves structure + const convexValidator = zodToConvex(schema); + expect(convexValidator.kind).toBe("object"); + }); + + test("transforms are converted to any", () => { + const schema = z.object({ + numericString: z.string().transform(Number), + trimmed: z.string().transform((s) => s.trim()), + parsed: z.string().transform((s) => JSON.parse(s)), + date: z + .string() + .datetime() + .transform((s) => new Date(s)), + }); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.kind).toBe("object"); + // All transforms become 'any' in Convex + expect(convexValidator.fields.numericString.kind).toBe("any"); + expect(convexValidator.fields.trimmed.kind).toBe("any"); + expect(convexValidator.fields.parsed.kind).toBe("any"); + expect(convexValidator.fields.date.kind).toBe("any"); + }); + + test("preprocess transforms", () => { + const schema = z.object({ + number: z.preprocess( + (val) => (typeof val === "string" ? Number(val) : val), + z.number(), + ), + trimmedString: z.preprocess( + (val) => (typeof val === "string" ? val.trim() : val), + z.string(), + ), + }); + + // Test preprocessing + const result = schema.parse({ + number: "42", + trimmedString: " hello ", + }); + expect(result).toEqual({ + number: 42, + trimmedString: "hello", + }); + + // Convex conversion + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.number.kind).toBe("any"); + expect(convexValidator.fields.trimmedString.kind).toBe("any"); + }); +}); + +describe("Zod v4 Complex Type Combinations", () => { + test("nullable and optional combinations", () => { + const schema = z.object({ + // All 4 combinations + required: z.string(), + optional: z.string().optional(), + nullable: z.string().nullable(), + optionalNullable: z.string().optional().nullable(), + nullableOptional: z.string().nullable().optional(), + }); + + // Test type inference + type Schema = z.infer; + expectTypeOf().toMatchTypeOf<{ + required: string; + optional?: string; + nullable: string | null; + optionalNullable?: string | null; + nullableOptional?: string | null; + }>(); + + // Test Convex conversion + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.required.kind).toBe("string"); + expect(convexValidator.fields.optional.kind).toBe("union"); + expect(convexValidator.fields.nullable.kind).toBe("union"); + expect(convexValidator.fields.optionalNullable.kind).toBe("union"); + expect(convexValidator.fields.nullableOptional.kind).toBe("union"); + }); + + test("tuple types", () => { + const schema = z.object({ + pair: z.tuple([z.string(), z.number()]), + triple: z.tuple([z.string(), z.number(), z.boolean()]), + mixed: z.tuple([ + z.string(), + z.object({ x: z.number() }), + z.array(z.string()), + ]), + }); + + const testData = { + pair: ["hello", 42], + triple: ["world", 100, true], + mixed: ["test", { x: 10 }, ["a", "b", "c"]], + }; + + expect(schema.parse(testData)).toEqual(testData); + + // Convex conversion - tuples become arrays + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.pair.kind).toBe("array"); + expect(convexValidator.fields.triple.kind).toBe("array"); + expect(convexValidator.fields.mixed.kind).toBe("array"); + }); + + test("readonly modifiers", () => { + const schema = z.object({ + readonlyString: z.string().readonly(), + readonlyArray: z.array(z.string()).readonly(), + readonlyObject: z + .object({ + prop: z.string(), + }) + .readonly(), + }); + + const convexValidator = zodToConvex(schema); + // Readonly is a TypeScript-only concept, doesn't affect runtime + expect(convexValidator.fields.readonlyString.kind).toBe("string"); + expect(convexValidator.fields.readonlyArray.kind).toBe("array"); + expect(convexValidator.fields.readonlyObject.kind).toBe("object"); + }); + + test("pipeline transforms", () => { + const schema = z.object({ + email: z.email().toLowerCase().trim(), + age: z.string().regex(/^\d+$/).transform(Number).pipe(z.number().min(0)), + }); + + // These become 'any' in Convex due to transforms + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.email.kind).toBe("string"); + expect(convexValidator.fields.age.kind).toBe("any"); + }); + + test("deeply nested structures", () => { + const schema = z.object({ + level1: z.object({ + level2: z.object({ + level3: z + .object({ + level4: z + .object({ + value: z.string(), + array: z.array( + z.object({ + nested: z.boolean(), + }), + ), + }) + .optional(), + }) + .nullable(), + }), + }), + }); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.kind).toBe("object"); + expect(convexValidator.fields.level1.kind).toBe("object"); + + // Navigate the nested structure + const level2 = convexValidator.fields.level1.fields.level2; + expect(level2.kind).toBe("object"); + + const level3 = level2.fields.level3; + expect(level3.kind).toBe("union"); // nullable makes it a union + }); +}); + +describe("Zod v4 Database Integration Tests", () => { + // Create a dedicated schema for database integration tests + const dbIntegrationSchema = defineSchema({ + users: defineTable({ + name: v.string(), + email: v.string(), + role: v.string(), + }), + posts: defineTable({ + title: v.string(), + content: v.string(), + authorId: v.id("users"), + }), + }); + + test("query with zod args and database operations", async () => { + const t = convexTest(dbIntegrationSchema, modules); + + await t.run(async (ctx) => { + // Create test data + const userId = await ctx.db.insert("users", { + name: "Test User", + email: "test@example.com", + role: "admin", + }); + + // Create a query builder for the test schema + const testQuery = queryGeneric as QueryBuilder< + DataModelFromSchemaDefinition, + "public" + >; + + // Define query with zod validation + const getUserQuery = zCustomQuery(testQuery, { + args: {}, + input: async (ctx, args) => ({ ctx: {}, args: {} }), + })({ + args: { + userId: zid("users"), + includeEmail: z.boolean().default(false), + }, + handler: async (ctx, args) => { + // If this fails, it means the zid -> GenericId conversion isn't working + const user = await ctx.db.get(args.userId); + if (!user) return null; + + if (!args.includeEmail) { + return { + _id: user._id, + _creationTime: user._creationTime, + name: user.name, + role: user.role, + }; + } + return user; + }, + }); + + // Test that the query was created successfully + expect(typeof getUserQuery).toBe("function"); + }); + }); + + test("mutation with complex validation and db writes", async () => { + const t = convexTest(dbIntegrationSchema, modules); + + await t.run(async (ctx) => { + const mutation = mutationGeneric as MutationBuilder< + DataModelFromSchemaDefinition, + "public" + >; + const createUser = zCustomMutation(mutation, { + args: {}, + input: async (ctx, args) => ({ ctx: {}, args }), + })({ + args: { + name: z.string().min(1).max(100), + email: z.email(), + role: z.enum(["admin", "user", "guest"]), + metadata: z.record(z.string(), z.any()).optional(), + }, + handler: async (ctx, args) => { + // Insert into database with real validation + const id = await ctx.db.insert("users", { + name: args.name, + email: args.email, + role: args.role, + }); + return id; + }, + }); + + expect(typeof createUser).toBe("function"); + }); + }); +}); + +describe("Zod v4 Error Handling and Edge Cases", () => { + test("invalid zod types throw appropriate errors", () => { + // Test unsupported validator as args - this should be a runtime error + // We can't test this at compile time due to TypeScript checking + // In real usage, this would be caught by zodToConvexFields validation + expect(() => { + // This would throw at runtime when zodToConvexFields is called + zodToConvexFields(z.string() as any); + }).toThrow(); + }); + + test("empty values handling", () => { + const schema = z.object({ + emptyString: z.string(), + emptyArray: z.array(z.string()), + emptyObject: z.object({}), + emptyRecord: z.record(z.string(), z.any()), + }); + + const testData = { + emptyString: "", + emptyArray: [], + emptyObject: {}, + emptyRecord: {}, + }; + + // Should validate successfully + expect(schema.parse(testData)).toEqual(testData); + + // Convex conversion + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.emptyString.kind).toBe("string"); + expect(convexValidator.fields.emptyArray.kind).toBe("array"); + expect(convexValidator.fields.emptyObject.kind).toBe("object"); + expect(convexValidator.fields.emptyRecord.kind).toBe("record"); + }); + + test("null vs undefined distinctions", () => { + const schema = z.object({ + nullValue: z.null(), + undefinedValue: z.undefined(), + nullableString: z.string().nullable(), + optionalString: z.string().optional(), + either: z.union([z.null(), z.undefined()]), + }); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.nullValue.kind).toBe("null"); + expect(convexValidator.fields.undefinedValue.kind).toBe("any"); + expect(convexValidator.fields.nullableString.kind).toBe("union"); + expect(convexValidator.fields.optionalString.kind).toBe("union"); + expect(convexValidator.fields.either.kind).toBe("union"); + }); + + test("invalid table names for IDs", () => { + // This should work + const validId = zid("users"); + expect(validId.parse("abc123")).toBe("abc123"); + + // Table name validation happens at runtime in Convex + const invalidTableId = zid("not_a_real_table"); + // Parse still works (just checks string format) + expect(invalidTableId.parse("xyz789")).toBe("xyz789"); + }); + + test("recursive schema edge cases", () => { + // Self-referential schema + interface Comment { + text: string; + replies?: Comment[]; + } + + const commentSchema: z.ZodType = z.lazy(() => + z.object({ + text: z.string(), + replies: z.array(commentSchema).optional(), + }), + ); + + const testData: Comment = { + text: "Parent", + replies: [ + { text: "Child 1" }, + { + text: "Child 2", + replies: [{ text: "Grandchild" }], + }, + ], + }; + + expect(commentSchema.parse(testData)).toEqual(testData); + + // Convex conversion handles lazy schemas + const convexValidator = zodToConvex(commentSchema); + expect(convexValidator.kind).toBe("object"); + }); +}); + +describe("Zod v4 Missing Specific Type Tests", () => { + test("NaN type handling", () => { + const schema = z.object({ + nanValue: z.nan(), + numberOrNan: z.union([z.number(), z.nan()]), + }); + + const testData = { + nanValue: NaN, + numberOrNan: NaN, + }; + + expect(schema.parse(testData)).toEqual(testData); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.nanValue.kind).toBe("float64"); + expect(convexValidator.fields.numberOrNan.kind).toBe("union"); + }); + + test("basic bigint without branding", () => { + const schema = z.object({ + bigintValue: z.bigint(), + positiveBigint: z.bigint().positive(), + bigintWithRange: z.bigint().min(0n).max(1000n), + }); + + const testData = { + bigintValue: 123n, + positiveBigint: 456n, + bigintWithRange: 789n, + }; + + expect(schema.parse(testData)).toEqual(testData); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.bigintValue.kind).toBe("int64"); + expect(convexValidator.fields.positiveBigint.kind).toBe("int64"); + expect(convexValidator.fields.bigintWithRange.kind).toBe("int64"); + }); + + test("native enum support", () => { + enum Color { + Red = "RED", + Green = "GREEN", + Blue = "BLUE", + } + + enum Status { + Active = 1, + Inactive = 0, + Pending = -1, + } + + const schema = z.object({ + color: z.nativeEnum(Color), + status: z.nativeEnum(Status), + }); + + const testData = { + color: Color.Red, + status: Status.Active, + }; + + expect(schema.parse(testData)).toEqual(testData); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.color.kind).toBe("union"); + expect(convexValidator.fields.status.kind).toBe("union"); + }); + + test("record with union keys", () => { + const schema = z.object({ + statusMap: z.record( + z.union([ + z.literal("success"), + z.literal("error"), + z.literal("pending"), + ]), + z.object({ + count: z.number(), + lastUpdated: z.string().datetime(), + }), + ), + }); + + const testData = { + statusMap: { + success: { count: 10, lastUpdated: "2023-01-01T00:00:00Z" }, + error: { count: 2, lastUpdated: "2023-01-02T00:00:00Z" }, + pending: { count: 5, lastUpdated: "2023-01-03T00:00:00Z" }, + }, + }; + + expect(schema.parse(testData)).toEqual(testData); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.statusMap.kind).toBe("record"); + }); + + test("complex discriminated unions with nested objects", () => { + const schema = z.discriminatedUnion("event", [ + z.object({ + event: z.literal("user.created"), + data: z.object({ + id: z.string(), + email: z.email(), + createdAt: z.string().datetime(), + }), + }), + z.object({ + event: z.literal("user.updated"), + data: z.object({ + id: z.string(), + changes: z.record(z.string(), z.any()), + updatedAt: z.string().datetime(), + }), + }), + z.object({ + event: z.literal("user.deleted"), + data: z.object({ + id: z.string(), + deletedAt: z.string().datetime(), + reason: z.string().optional(), + }), + }), + ]); + + const createEvent = { + event: "user.created" as const, + data: { + id: "123", + email: "new@example.com", + createdAt: "2023-01-01T00:00:00Z", + }, + }; + + expect(schema.parse(createEvent)).toEqual(createEvent); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.kind).toBe("union"); + expect(convexValidator.members.length).toBe(3); + }); + + test("default values in nested structures", () => { + const schema = z.object({ + settings: z + .object({ + theme: z.enum(["light", "dark"]).default("light"), + notifications: z + .object({ + email: z.boolean().default(true), + push: z.boolean().default(false), + frequency: z + .enum(["instant", "daily", "weekly"]) + .default("daily"), + }) + .default({ + email: true, + push: false, + frequency: "daily", + }), + }) + .default({ + theme: "light", + notifications: { + email: true, + push: false, + frequency: "daily", + }, + }), + }); + + // Empty object should get all defaults + const result = schema.parse({}); + expect(result).toEqual({ + settings: { + theme: "light", + notifications: { + email: true, + push: false, + frequency: "daily", + }, + }, + }); + + const convexValidator = zodToConvex(schema); + expect(convexValidator.fields.settings.isOptional).toBe("required"); + }); +}); + +describe("Zod v4 Type-level Testing", () => { + test("type equality checks", () => { + const zodSchema = z.object({ + id: z.string(), + count: z.number(), + active: z.boolean(), + }); + + type ZodInferred = z.infer; + + const convexValidator = zodToConvex(zodSchema); + type ConvexInferred = Infer; + + // These types should be equivalent + expectTypeOf().toEqualTypeOf(); + + // Test specific field types + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + }); + + test("complex type preservation", () => { + const complexSchema = z.object({ + union: z.union([z.string(), z.number()]), + array: z.array(z.string()), + optional: z.string().optional(), + nullable: z.number().nullable(), + record: z.record(z.string(), z.boolean()), + }); + + type ComplexZod = z.infer; + // Fix: Call zodToConvex at runtime, then use Infer on the result + const convexValidator = zodToConvex(complexSchema); + type ComplexConvex = Infer; + + // Test union types + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + + // Test array types + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + + // Test optional types + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf< + string | undefined + >(); + + // Test nullable types + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + + // Test record types + expectTypeOf().toEqualTypeOf< + Record + >(); + expectTypeOf().toEqualTypeOf< + Record + >(); + }); +}); + +describe("Testing literal value validation at compile time", () => { + test("Can TypeScript catch literal negative values?", () => { + // Create a positive number schema + const PositiveNumber = z.number().positive(); + type PositiveNumber = z.infer; + + // Test with literal values + const literalNegative = -1; + const literalPositive = 1; + + // Does TypeScript catch this at compile time? NO! + // These will throw at RUNTIME, not compile time + expect(() => PositiveNumber.parse(-1)).toThrow(); // Literal negative + expect(() => PositiveNumber.parse(literalNegative)).toThrow(); // Const negative + + // These succeed at runtime + const test3 = PositiveNumber.parse(1); // Literal positive + const test4 = PositiveNumber.parse(literalPositive); // Const positive + expect(test3).toBe(1); + expect(test4).toBe(1); + + // What about with safeParse? + const safe1 = PositiveNumber.safeParse(-1); + const safe2 = PositiveNumber.safeParse(literalNegative); + expect(safe1.success).toBe(false); + expect(safe2.success).toBe(false); + + // What about with branded types? + const BrandedPositive = z.number().positive().brand("Positive"); + type BrandedPositive = z.infer; + + expect(() => BrandedPositive.parse(-1)).toThrow(); + const branded2: BrandedPositive = -1 as BrandedPositive; // We can force it with 'as' + + // Function that requires positive (branded type) + function requiresPositive(n: PositiveNumber) { + return n * 2; + } + + // TypeScript prevents these because PositiveNumber is branded: + // requiresPositive(1); // ❌ number is not assignable to number & BRAND + // requiresPositive(-1); // ❌ number is not assignable to number & BRAND + + // You must parse first: + const parsed = PositiveNumber.parse(5); + requiresPositive(parsed); // ✅ This works + }); +}); + +describe("Zod v4 API Compatibility Tests", () => { + test("zodToConvex properly converts Zod types to Convex validators", () => { + // Test that zodToConvex returns actual Convex validator instances + + // Test string conversion + const stringValidator = zodToConvex(z.string()); + expect(stringValidator).toBeDefined(); + expect(stringValidator.kind).toBe("string"); + expect(stringValidator.isOptional).toBe("required"); + expect(stringValidator.isConvexValidator).toBe(true); + // Verify it matches the shape of VString + const convexString: VString = v.string(); + expect(stringValidator).toHaveProperty("kind", convexString.kind); + expect(stringValidator).toHaveProperty( + "isOptional", + convexString.isOptional, + ); + expect(stringValidator).toHaveProperty( + "isConvexValidator", + convexString.isConvexValidator, + ); + + // Test number conversion + const numberValidator = zodToConvex(z.number()); + const convexFloat: VFloat64 = v.float64(); + expect(numberValidator.kind).toBe("float64"); + expect(numberValidator.kind).toBe(convexFloat.kind); + expect(numberValidator.isOptional).toBe(convexFloat.isOptional); + expect(numberValidator.isConvexValidator).toBe( + convexFloat.isConvexValidator, + ); + + // Test object conversion + const objectValidator = zodToConvex( + z.object({ + name: z.string(), + age: z.number(), + }), + ); + const convexObject: VObject = v.object({ + name: v.string(), + age: v.float64(), + }); + expect(objectValidator.kind).toBe("object"); + expect(objectValidator.kind).toBe(convexObject.kind); + expect(objectValidator.isOptional).toBe(convexObject.isOptional); + expect(objectValidator.isConvexValidator).toBe( + convexObject.isConvexValidator, + ); + expect(objectValidator.fields).toBeDefined(); + expect(objectValidator.fields.name.kind).toBe("string"); + expect(objectValidator.fields.age.kind).toBe("float64"); + + // Test Convex ID conversion + const idValidator = zodToConvex(zid("users")); + const convexId = v.id("users"); + expect(idValidator.kind).toBe("id"); + expect(idValidator.kind).toBe(convexId.kind); + expect(idValidator.tableName).toBe("users"); + expect(idValidator.tableName).toBe(convexId.tableName); + expect(idValidator.isOptional).toBe(convexId.isOptional); + expect(idValidator.isConvexValidator).toBe(convexId.isConvexValidator); + + // Test that the validators are structurally compatible with Convex validators + // by checking they can be assigned to typed variables + const _stringCheck: VString = stringValidator; + const _floatCheck: VFloat64 = numberValidator; + const _objectCheck: VObject = objectValidator; + const _idCheck: VId, "required"> = idValidator; + }); + + test("zodToConvexFields maintains field structure and converts types", () => { + const zodFields = { + name: z.string(), + age: z.number(), + tags: z.array(z.string()), + userId: zid("users"), + metadata: z.object({ + created: z.date(), + updated: z.date().optional(), + }), + }; + + const convexFields = zodToConvexFields(zodFields); + + // Should have same keys + expect(Object.keys(convexFields)).toEqual(Object.keys(zodFields)); + + // Check each field is properly converted to Convex validators + expect(convexFields.name).toMatchObject({ + kind: "string", + isOptional: "required", + isConvexValidator: true, + }); + + expect(convexFields.age).toMatchObject({ + kind: "float64", + isOptional: "required", + isConvexValidator: true, + }); + + expect(convexFields.tags).toMatchObject({ + kind: "array", + isOptional: "required", + isConvexValidator: true, + }); + expect(convexFields.tags.element).toMatchObject({ + kind: "string", + }); + + expect(convexFields.userId).toMatchObject({ + kind: "id", + tableName: "users", + isOptional: "required", + isConvexValidator: true, + }); + + expect(convexFields.metadata).toMatchObject({ + kind: "object", + isOptional: "required", + isConvexValidator: true, + }); + expect(convexFields.metadata.fields.created).toMatchObject({ + kind: "float64", // Dates become float64 in Convex + isOptional: "required", + }); + expect(convexFields.metadata.fields.updated).toMatchObject({ + kind: "union", // Optional becomes union with null + isOptional: "required", + }); + }); + + test("convexToZodFields maintains field structure and converts types", () => { + const convexFields = { + name: v.string(), + age: v.float64(), + tags: v.array(v.string()), + userId: v.id("users"), + metadata: v.object({ + created: v.float64(), + updated: v.optional(v.float64()), + }), + }; + + const zodFields = convexToZodFields(convexFields); + + // Should have same keys + expect(Object.keys(zodFields)).toEqual(Object.keys(convexFields)); + + // Check each field is properly converted to Zod validators + expect(zodFields.name).toBeInstanceOf(z.ZodString); + expect(zodFields.age).toBeInstanceOf(z.ZodNumber); + expect(zodFields.tags).toBeInstanceOf(z.ZodArray); + expect((zodFields.tags as z.ZodArray).element).toBeInstanceOf( + z.ZodString, + ); + // zid() returns a ZodPipe (branded type), not plain ZodString + expect(zodFields.userId).toBeInstanceOf(z.ZodPipe); + expect(zodFields.metadata).toBeInstanceOf(z.ZodObject); + + // Test that converted fields validate correctly + const testData = { + name: "Test User", + age: 25.5, + tags: ["tag1", "tag2"], + userId: "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", + metadata: { + created: Date.now(), + updated: Date.now(), + }, + }; + + // Each field should parse its respective data correctly + expect(zodFields.name.parse(testData.name)).toBe(testData.name); + expect(zodFields.age.parse(testData.age)).toBe(testData.age); + expect(zodFields.tags.parse(testData.tags)).toEqual(testData.tags); + expect(zodFields.userId.parse(testData.userId)).toBe(testData.userId); + expect(zodFields.metadata.parse(testData.metadata)).toEqual( + testData.metadata, + ); + }); + + test("convexToZodFields handles all basic Convex types", () => { + const convexFields = { + string: v.string(), + float64: v.float64(), + int64: v.int64(), + boolean: v.boolean(), + null: v.null(), + any: v.any(), + bytes: v.bytes(), + id: v.id("users"), + literal: v.literal("test"), + }; + + const zodFields = convexToZodFields(convexFields); + + // Verify type conversions + expect(zodFields.string).toBeInstanceOf(z.ZodString); + expect(zodFields.float64).toBeInstanceOf(z.ZodNumber); + expect(zodFields.int64).toBeInstanceOf(z.ZodBigInt); + expect(zodFields.boolean).toBeInstanceOf(z.ZodBoolean); + expect(zodFields.null).toBeInstanceOf(z.ZodNull); + expect(zodFields.any).toBeInstanceOf(z.ZodAny); + expect(zodFields.bytes).toBeInstanceOf(z.ZodBase64); // base64 string + expect(zodFields.id).toBeInstanceOf(z.ZodPipe); // zid() returns branded type + expect(zodFields.literal).toBeInstanceOf(z.ZodLiteral); + + // Test parsing + expect(zodFields.string.parse("hello")).toBe("hello"); + expect(zodFields.float64.parse(3.14)).toBe(3.14); + expect(zodFields.int64.parse(BigInt(42))).toBe(BigInt(42)); + expect(zodFields.boolean.parse(true)).toBe(true); + expect(zodFields.null.parse(null)).toBe(null); + expect(zodFields.any.parse({ anything: "goes" })).toEqual({ + anything: "goes", + }); + expect(zodFields.bytes.parse("SGVsbG8gV29ybGQ=")).toBe("SGVsbG8gV29ybGQ="); + expect(zodFields.id.parse("kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v")).toBe( + "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", + ); + expect(zodFields.literal.parse("test")).toBe("test"); + }); + + test("convexToZodFields handles complex nested structures", () => { + const convexFields = { + nested: v.object({ + inner: v.object({ + value: v.string(), + count: v.float64(), + }), + list: v.array( + v.object({ + id: v.id("items"), + name: v.string(), + }), + ), + }), + record: v.record(v.string(), v.float64()), + union: v.union(v.string(), v.float64(), v.null()), + optional: v.optional(v.string()), + arrayOfUnions: v.array(v.union(v.string(), v.float64())), + }; + + const zodFields = convexToZodFields(convexFields); + + // Verify nested object structure + expect(zodFields.nested).toBeInstanceOf(z.ZodObject); + // Since convexToZodFields returns z.ZodType, we can't access .shape directly + // Instead, test by parsing data + const nestedTestData = { + inner: { value: "test", count: 42 }, + list: [{ id: "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", name: "Item 1" }], + }; + expect(zodFields.nested.parse(nestedTestData)).toEqual(nestedTestData); + + // Verify record + expect(zodFields.record).toBeInstanceOf(z.ZodRecord); + + // Verify union + expect(zodFields.union).toBeInstanceOf(z.ZodUnion); + + // Verify optional (should be union with null) + expect(zodFields.optional).toBeInstanceOf(z.ZodUnion); + + // Verify array of unions + expect(zodFields.arrayOfUnions).toBeInstanceOf(z.ZodArray); + + // Test parsing complex data + const testData = { + nested: { + inner: { value: "test", count: 42 }, + list: [ + { id: "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", name: "Item 1" }, + { id: "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", name: "Item 2" }, + ], + }, + record: { key1: 1.5, key2: 2.5 }, + union: "string value", + optional: null, + arrayOfUnions: ["string", 123, "another string", 456], + }; + + expect(zodFields.nested.parse(testData.nested)).toEqual(testData.nested); + expect(zodFields.record.parse(testData.record)).toEqual(testData.record); + expect(zodFields.union.parse(testData.union)).toBe(testData.union); + expect(zodFields.union.parse(123)).toBe(123); + expect(zodFields.union.parse(null)).toBe(null); + expect(zodFields.optional.parse(null)).toBe(null); + expect(zodFields.optional.parse("value")).toBe("value"); + expect(zodFields.arrayOfUnions.parse(testData.arrayOfUnions)).toEqual( + testData.arrayOfUnions, + ); + }); + + test("convexToZodFields produces correct runtime behavior", () => { + // Test that the converted Zod validators behave correctly at runtime + const convexFields = { + string: v.string(), + number: v.float64(), + boolean: v.boolean(), + array: v.array(v.string()), + object: v.object({ + nested: v.string(), + count: v.float64(), + }), + optional: v.optional(v.string()), + union: v.union(v.string(), v.float64()), + id: v.id("users"), + literal: v.literal("test"), + record: v.record(v.string(), v.float64()), + }; + + const zodFields = convexToZodFields(convexFields); + + // Test valid data parses correctly + const validData = { + string: "hello", + number: 42.5, + boolean: true, + array: ["a", "b", "c"], + object: { nested: "value", count: 10 }, + optional: "present", + union: "string value", + id: "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", + literal: "test", + record: { key1: 1.5, key2: 2.5 }, + }; + + // Each field should parse its data correctly + expect(zodFields.string.parse(validData.string)).toBe(validData.string); + expect(zodFields.number.parse(validData.number)).toBe(validData.number); + expect(zodFields.boolean.parse(validData.boolean)).toBe(validData.boolean); + expect(zodFields.array.parse(validData.array)).toEqual(validData.array); + expect(zodFields.object.parse(validData.object)).toEqual(validData.object); + expect(zodFields.optional.parse(validData.optional)).toBe( + validData.optional, + ); + expect(zodFields.optional.parse(null)).toBe(null); + expect(zodFields.union.parse(validData.union)).toBe(validData.union); + expect(zodFields.union.parse(123)).toBe(123); + expect(zodFields.id.parse(validData.id)).toBe(validData.id); + expect(zodFields.literal.parse(validData.literal)).toBe(validData.literal); + expect(zodFields.record.parse(validData.record)).toEqual(validData.record); + + // Test invalid data throws errors + expect(() => zodFields.string.parse(123)).toThrow(); + expect(() => zodFields.number.parse("not a number")).toThrow(); + expect(() => zodFields.boolean.parse("not a boolean")).toThrow(); + expect(() => zodFields.array.parse("not an array")).toThrow(); + expect(() => zodFields.object.parse({ wrong: "shape" })).toThrow(); + expect(() => zodFields.literal.parse("wrong")).toThrow(); + }); + + test("convexToZodFields handles optional fields correctly", () => { + const convexFields = { + required: v.string(), + optional: v.optional(v.string()), + optionalObject: v.optional( + v.object({ + field: v.string(), + }), + ), + optionalArray: v.optional(v.array(v.string())), + deepOptional: v.object({ + required: v.string(), + optional: v.optional(v.float64()), + }), + }; + + const zodFields = convexToZodFields(convexFields); + + // Test that optional fields accept null + expect(zodFields.optional.parse(null)).toBe(null); + expect(zodFields.optional.parse("value")).toBe("value"); + expect(zodFields.optionalObject.parse(null)).toBe(null); + expect(zodFields.optionalObject.parse({ field: "test" })).toEqual({ + field: "test", + }); + expect(zodFields.optionalArray.parse(null)).toBe(null); + expect(zodFields.optionalArray.parse(["a", "b"])).toEqual(["a", "b"]); + + // Test nested optional + expect( + zodFields.deepOptional.parse({ required: "test", optional: null }), + ).toEqual({ + required: "test", + optional: null, + }); + expect( + zodFields.deepOptional.parse({ required: "test", optional: 42 }), + ).toEqual({ + required: "test", + optional: 42, + }); + }); + + test("convexToZodFields round-trip preserves behavior", () => { + // Start with Convex validators + const originalConvexFields = { + name: v.string(), + age: v.float64(), + userId: v.id("users"), + tags: v.array(v.string()), + metadata: v.object({ + created: v.float64(), + updated: v.optional(v.float64()), + }), + }; + + // Convert to Zod + const zodFields = convexToZodFields(originalConvexFields); + + // Convert back to Convex + const roundTripConvexFields = zodToConvexFields(zodFields); + + // Test data + const testData = { + name: "Test User", + age: 25.5, + tags: ["tag1", "tag2"], + userId: "kp7cs96nvmfnv3cvyx6sm4c9d46yqn9v", + metadata: { + created: Date.now(), + updated: Date.now(), + }, + }; + + // Both should validate the same data successfully + expect(zodFields.name.parse(testData.name)).toBe(testData.name); + expect(zodFields.age.parse(testData.age)).toBe(testData.age); + expect(zodFields.tags.parse(testData.tags)).toEqual(testData.tags); + expect(zodFields.userId.parse(testData.userId)).toBe(testData.userId); + expect(zodFields.metadata.parse(testData.metadata)).toEqual( + testData.metadata, + ); + + // The round-trip Convex validators should have the correct structure + expect(roundTripConvexFields.name.kind).toBe("string"); + expect(roundTripConvexFields.age.kind).toBe("float64"); + expect(roundTripConvexFields.tags.kind).toBe("array"); + expect(roundTripConvexFields.tags.element.kind).toBe("string"); + expect(roundTripConvexFields.userId.kind).toBe("id"); + expect(roundTripConvexFields.userId.tableName).toBe("users"); // Table name preserved! + expect(roundTripConvexFields.metadata.kind).toBe("object"); + expect(roundTripConvexFields.metadata.fields.created.kind).toBe("float64"); + expect(roundTripConvexFields.metadata.fields.updated.kind).toBe("union"); // Optional becomes union + }); + + test("convexToZod round trip", () => { + const convexSchema = v.object({ + id: v.id("users"), + name: v.string(), + age: v.number(), + active: v.boolean(), + tags: v.array(v.string()), + metadata: v.record(v.string(), v.any()), + optional: v.optional(v.string()), + union: v.union(v.string(), v.number()), + }); + + const zodSchema = convexToZod(convexSchema); + + const testData = { + id: "123", + name: "Test", + age: 25, + active: true, + tags: ["a", "b"], + metadata: { key: "value" }, + optional: "test", + union: "string", + }; + + // Should validate the same data + expect(zodSchema.parse(testData)).toEqual(testData); + }); + + test("output validation with transforms", () => { + const schema = z.object({ + input: z.string(), + transformed: z.string().transform((s) => s.toUpperCase()), + coerced: z.coerce.number(), + }); + + const outputValidator = zodOutputToConvex(schema); + + // Check that transforms are handled + expect(outputValidator.fields.input.kind).toBe("string"); + expect(outputValidator.fields.transformed.kind).toBe("any"); // Transforms that change type become any + expect(outputValidator.fields.coerced.kind).toBe("float64"); // Coerce to number is still a number + }); + + test("zodToConvex returns actual Convex validator instances", () => { + // Test that zodToConvex returns the same type of validators as v.* functions + + // String + const zodString = zodToConvex(z.string()); + const convexString = v.string(); + // Both should be VString instances with the same properties + expect(zodString.kind).toBe(convexString.kind); + expect(zodString.isOptional).toBe(convexString.isOptional); + expect(zodString.isConvexValidator).toBe(convexString.isConvexValidator); + // Type check - if this compiles, they're the same type + const stringTest: typeof convexString = zodString; + expect(stringTest).toBe(zodString); + + // Number/Float64 + const zodNumber = zodToConvex(z.number()); + const convexFloat = v.float64(); + expect(zodNumber.kind).toBe(convexFloat.kind); + expect(zodNumber.isOptional).toBe(convexFloat.isOptional); + expect(zodNumber.isConvexValidator).toBe(convexFloat.isConvexValidator); + const floatTest: typeof convexFloat = zodNumber; + expect(floatTest).toBe(zodNumber); + + // Boolean + const zodBool = zodToConvex(z.boolean()); + const convexBool = v.boolean(); + expect(zodBool.kind).toBe(convexBool.kind); + expect(zodBool.isOptional).toBe(convexBool.isOptional); + expect(zodBool.isConvexValidator).toBe(convexBool.isConvexValidator); + const boolTest: typeof convexBool = zodBool; + expect(boolTest).toBe(zodBool); + + // Object + const zodObject = zodToConvex(z.object({ x: z.string(), y: z.number() })); + const convexObject = v.object({ x: v.string(), y: v.float64() }); + expect(zodObject.kind).toBe(convexObject.kind); + expect(zodObject.isOptional).toBe(convexObject.isOptional); + expect(zodObject.isConvexValidator).toBe(convexObject.isConvexValidator); + expect(zodObject.fields.x.kind).toBe(convexObject.fields.x.kind); + expect(zodObject.fields.y.kind).toBe(convexObject.fields.y.kind); + + // Array + const zodArray = zodToConvex(z.array(z.string())); + const convexArray = v.array(v.string()); + expect(zodArray.kind).toBe(convexArray.kind); + expect(zodArray.isOptional).toBe(convexArray.isOptional); + expect(zodArray.isConvexValidator).toBe(convexArray.isConvexValidator); + expect(zodArray.element.kind).toBe(convexArray.element.kind); + const arrayTest: typeof convexArray = zodArray; + expect(arrayTest).toBe(zodArray); + + // ID + const zodId = zodToConvex(zid("users")); + const convexId = v.id("users"); + expect(zodId.kind).toBe(convexId.kind); + expect(zodId.isOptional).toBe(convexId.isOptional); + expect(zodId.isConvexValidator).toBe(convexId.isConvexValidator); + expect(zodId.tableName).toBe(convexId.tableName); + const idTest: typeof convexId = zodId; + expect(idTest).toBe(zodId); + + // Union (from optional) + const zodOptional = zodToConvex(z.string().optional()); + const convexUnion = v.union(v.string(), v.null()); + expect(zodOptional.kind).toBe(convexUnion.kind); + expect(zodOptional.isOptional).toBe(convexUnion.isOptional); + expect(zodOptional.isConvexValidator).toBe(convexUnion.isConvexValidator); + + // Literal + const zodLiteral = zodToConvex(z.literal("test")); + const convexLiteral = v.literal("test"); + expect(zodLiteral.kind).toBe(convexLiteral.kind); + expect(zodLiteral.isOptional).toBe(convexLiteral.isOptional); + expect(zodLiteral.isConvexValidator).toBe(convexLiteral.isConvexValidator); + expect(zodLiteral.value).toBe(convexLiteral.value); + const literalTest: typeof convexLiteral = zodLiteral; + expect(literalTest).toBe(zodLiteral); + + // Null + const zodNull = zodToConvex(z.null()); + const convexNull = v.null(); + expect(zodNull.kind).toBe(convexNull.kind); + expect(zodNull.isOptional).toBe(convexNull.isOptional); + expect(zodNull.isConvexValidator).toBe(convexNull.isConvexValidator); + const nullTest: typeof convexNull = zodNull; + expect(nullTest).toBe(zodNull); + + // Any + console.log("DEBUG: z.any() instance test"); + const any1 = z.any(); + const any2 = z.any(); + console.log("DEBUG: Are z.any() instances the same?", any1 === any2); + console.log( + "DEBUG: any1 metadata:", + (registryHelpers as any).getMetadata?.(any1), + ); + console.log( + "DEBUG: any2 metadata:", + (registryHelpers as any).getMetadata?.(any2), + ); + + const zodAny = zodToConvex(z.any()); + const convexAny = v.any(); + console.log("DEBUG: zodAny result:", zodAny); + console.log( + "DEBUG: zodAny.kind:", + zodAny.kind, + "expected:", + convexAny.kind, + ); + expect(zodAny.kind).toBe(convexAny.kind); + expect(zodAny.isOptional).toBe(convexAny.isOptional); + expect(zodAny.isConvexValidator).toBe(convexAny.isConvexValidator); + // const anyTest: typeof convexAny = zodAny; + // expect(anyTest).toBe(zodAny); + + // BigInt -> Int64 + const zodBigInt = zodToConvex(z.bigint()); + const convexInt64 = v.int64(); + expect(zodBigInt.kind).toBe(convexInt64.kind); + expect(zodBigInt.isOptional).toBe(convexInt64.isOptional); + expect(zodBigInt.isConvexValidator).toBe(convexInt64.isConvexValidator); + const int64Test: typeof convexInt64 = zodBigInt; + expect(int64Test).toBe(zodBigInt); + + // Record + const zodRecord = zodToConvex(z.record(z.string(), z.number())); + const convexRecord = v.record(v.string(), v.float64()); + expect(zodRecord.kind).toBe(convexRecord.kind); + expect(zodRecord.isOptional).toBe(convexRecord.isOptional); + expect(zodRecord.isConvexValidator).toBe(convexRecord.isConvexValidator); + expect(zodRecord.value.kind).toBe(convexRecord.value.kind); + }); +}); + +describe("Zod v4 Zid Detection Tests", () => { + test("isZid function correctly identifies zid types", () => { + // Create a zid + const userIdValidator = zid("users"); + const regularStringValidator = z.string(); + + // Import isZid function for testing (it's currently internal) + // For now, let's test indirectly by checking the conversion + const userIdConvex = zodToConvex(userIdValidator); + const stringConvex = zodToConvex(regularStringValidator); + + // If isZid is working, userIdValidator should convert to v.id("users") + expect(userIdConvex.kind).toBe("id"); + expect((userIdConvex as any).tableName).toBe("users"); + + // Regular string should convert to v.string() + expect(stringConvex.kind).toBe("string"); + + console.log("userIdValidator:", userIdValidator); + console.log("userIdConvex:", userIdConvex); + console.log("stringConvex:", stringConvex); + }); + + test("zid metadata is correctly stored", () => { + const userIdValidator = zid("posts"); + + // Check if metadata was stored correctly + const metadata = + (userIdValidator as any)._metadata || + registryHelpers?.getMetadata?.(userIdValidator); + + console.log("zid metadata:", metadata); + + // The metadata should contain the table name and isConvexId flag + if (metadata) { + expect(metadata.tableName).toBe("posts"); + expect(metadata.isConvexId).toBe(true); + expect(metadata.typeName).toBe("ConvexId"); + } + }); +}); diff --git a/packages/convex-helpers/server/zodV4.ts b/packages/convex-helpers/server/zodV4.ts new file mode 100644 index 00000000..97c0c7b0 --- /dev/null +++ b/packages/convex-helpers/server/zodV4.ts @@ -0,0 +1,3989 @@ +/* eslint-disable @typescript-eslint/no-explicit-any */ + +/** + * Zod v4 Integration for Convex + * + * This module provides a full Zod v4 integration for Convex, embracing all v4 features: + * - Schema Registry for metadata and JSON Schema + * - Enhanced error reporting with pretty printing + * - File validation support + * - Template literal types + * - Performance optimizations (14x faster string parsing, 7x faster arrays) + * - Cleaner type definitions with z.interface() + * - New .overwrite() method for transforms + * + * Requires Zod 3.25.0 or higher and imports from the /v4 subpath + */ + +/** + * CRITICAL MIGRATION NOTE: z.effect Removal in Zod v4 + * + * Zod v4 completely removed the `z.effect` API that existed in v3. This is a major + * breaking change that affects how validation and transformation are handled. + * + * ## What z.effect Was in Zod v3 + * + * In Zod v3, `z.effect` was a single API that handled both validation and transformation: + * + * ```typescript + * // Zod v3 - z.effect for transformation + * const schema = z.string().effect((val) => val.toUpperCase()); + * + * // Zod v3 - z.effect for validation + * const schema = z.string().effect((val) => { + * if (val.length < 5) throw new Error("Too short"); + * return val; + * }); + * ``` + * + * ## What Replaced z.effect in Zod v4 + * + * z.effect was split into THREE more specific methods: + * + * ### 1. `.transform()` - For Data Transformations + * ```typescript + * // v4: Use .transform() for data transformations that change the output type + * const schema = z.string().transform((val) => val.toUpperCase()); + * // Output type: string (transformed) + * ``` + * + * ### 2. `.refine()` - For Custom Validations + * ```typescript + * // v4: Use .refine() for custom validations that don't change the type + * const schema = z.string().refine((val) => val.length >= 5, { + * message: "Too short" + * }); + * // Output type: string (unchanged) + * ``` + * + * ### 3. `.overwrite()` - NEW in v4 - For Type-Preserving Transforms + * ```typescript + * // v4: Use .overwrite() for transforms that don't change the inferred type + * const schema = z.number().overwrite(val => val ** 2).max(100); + * // Output type: ZodNumber (allows further chaining) + * // vs .transform() which would return ZodPipe + * ``` + * + * ## Major Architectural Change: Refinements Inside Schemas + * + * **Zod v3 Problem:** + * ```typescript + * // v3: This was BROKEN - couldn't chain after .refine() + * z.string() + * .refine(val => val.includes("@")) + * .min(5); // ❌ Property 'min' does not exist on type ZodEffects + * ``` + * + * In v3, refinements were wrapped in a `ZodEffects` class that prevented chaining + * with other schema methods like `.min()`, `.max()`, `.optional()`, etc. + * + * **Zod v4 Solution:** + * ```typescript + * // v4: This WORKS - refinements live inside schemas + * z.string() + * .refine(val => val.includes("@")) + * .min(5); // ✅ Works! + * ``` + * + * In v4, refinements are stored directly inside the schemas themselves, allowing + * seamless method chaining and much better developer experience. + * + * ## Additional Method Changes + * + * ### `.check()` Replaces `.superRefine()` + * ```typescript + * // v3: Used .superRefine() for complex validations + * schema.superRefine((val, ctx) => { + * if (condition) { + * ctx.addIssue({ ... }); + * } + * }); + * + * // v4: Use .check() instead (.superRefine() is deprecated) + * schema.check((ctx) => { + * if (condition) { + * ctx.issues.push({ ... }); + * } + * }); + * ``` + */ + +import * as z from "zod/v4"; +import type { + GenericId, + Infer, + ObjectType, + PropertyValidators, + Value, + VArray, + VAny, + VString, + VId, + VUnion, + VFloat64, + VInt64, + VBoolean, + VNull, + VLiteral, + GenericValidator, + VOptional, + VObject, + Validator, + VRecord, + VBytes, +} from "convex/values"; +import { ConvexError, v } from "convex/values"; +import type { + FunctionVisibility, + GenericDataModel, + GenericActionCtx, + GenericQueryCtx, + MutationBuilder, + QueryBuilder, + GenericMutationCtx, + ActionBuilder, + TableNamesInDataModel, + DefaultFunctionArgs, + ArgsArrayToObject, + ReturnValueForOptionalValidator, +} from "convex/server"; +import type { Mod, Registration } from "convex-helpers/server/customFunctions"; +import { NoOp } from "convex-helpers/server/customFunctions"; +import { pick, type EmptyObject } from "convex-helpers"; + +/** + * Zod v4 Schema Registry + * + * Using the actual Zod v4 registry API for metadata and schema management. + */ + +// Define the metadata structure we'll store in the v4 registry +type ConvexSchemaMetadata = { + description?: string; + deprecated?: boolean; + version?: string; + tags?: string[]; + example?: string; + tableName?: string; // for Zid types + generateJsonSchema?: boolean; + // Store JSON schema directly in metadata since v4 registry handles one object per schema + jsonSchema?: Record; + [key: string]: any; +}; + +/** + * Enhanced transform metadata for bidirectional data flow + */ +interface TransformMetadata { + /** The input validator (what Zod expects to validate) */ + inputValidator: z.ZodType; + /** The output validator (what gets stored in Convex) */ + outputValidator: z.ZodType; + /** Forward transform function (input → output) */ + forwardTransform: (input: any) => any; + /** Optional reverse transform function (output → input) */ + reverseTransform?: (output: any) => any; + /** Unique identifier for this transform */ + transformId: string; + /** Whether this transform is reversible */ + isReversible: boolean; +} + +/** + * **THIS IS NOT CURRENTLY USED** + * Retaining for reviewers/testers/experimenters who might want to play with it since it could be a useful pattern. + * Unused right now as this helper treats transforms as one way trips. + * + * Global transform registry for storing transform metadata + */ +class TransformRegistry { + private transforms = new Map(); + private schemaToTransformId = new WeakMap(); + + /** + * Register a transform with its metadata + */ + register(transformMetadata: TransformMetadata): void { + this.transforms.set(transformMetadata.transformId, transformMetadata); + } + + /** + * Associate a Zod schema with a transform ID + */ + associateSchema(schema: z.ZodType, transformId: string): void { + this.schemaToTransformId.set(schema, transformId); + } + + /** + * Get transform metadata for a schema + */ + getTransformForSchema(schema: z.ZodType): TransformMetadata | undefined { + const transformId = this.schemaToTransformId.get(schema); + return transformId ? this.transforms.get(transformId) : undefined; + } + + /** + * Get transform metadata by ID + */ + getTransform(transformId: string): TransformMetadata | undefined { + return this.transforms.get(transformId); + } + + /** + * Check if a schema has an associated transform + */ + hasTransform(schema: z.ZodType): boolean { + return this.schemaToTransformId.has(schema); + } +} + +// Global transform registry instance +export const transformRegistry = new TransformRegistry(); + +// Global registry instance using actual Zod v4 API +export const globalRegistry = z.registry(); + +// Helper functions to maintain backward compatibility with our existing API +export const registryHelpers = { + setMetadata(schema: z.ZodType, metadata: Record): void { + const existing = globalRegistry.get(schema) || {}; + globalRegistry.add(schema, { ...existing, ...metadata }); + }, + + getMetadata(schema: z.ZodType): Record | undefined { + const metadata = globalRegistry.get(schema); + if (!metadata) return undefined; + + // Extract non-jsonSchema properties for backward compatibility + const { jsonSchema, ...rest } = metadata; + return rest; + }, + + setJsonSchema(schema: z.ZodType, jsonSchema: Record): void { + const existing = globalRegistry.get(schema) || {}; + globalRegistry.add(schema, { ...existing, jsonSchema }); + }, + + getJsonSchema(schema: z.ZodType): Record | undefined { + return globalRegistry.get(schema)?.jsonSchema; + }, + + register(id: string, schema: z.ZodType): void { + // v4 registry is schema-keyed, not string-keyed + // Store the ID in the metadata for backward compatibility + const existing = globalRegistry.get(schema) || {}; + globalRegistry.add(schema, { ...existing, registryId: id }); + }, +}; + +/** + * v4-compatible type definitions + */ +export type ZodValidator = Record; + +/** + * Zid - Convex ID validator using Zod v4 branding (following external reviewer's exact specification) + */ + +/** + * Create a validator for a Convex `Id` using v4's custom type approach. + * + * When used as a validator, it will check that it's for the right table. + * When used as a parser, it will only check that the Id is a string. + * + * @param tableName - The table that the `Id` references. i.e.` Id` + * @returns - A Zod object representing a Convex `Id` + */ +export const zid = < + DataModel extends GenericDataModel = GenericDataModel, + TableName extends + TableNamesInDataModel = TableNamesInDataModel, +>( + tableName: TableName, +) => { + // Create a schema that transforms string to GenericId + // Cast the string to GenericId type without modifying the actual value + const baseSchema = z.string().transform((val) => { + // Return the string as-is but with the correct type + return val as string & GenericId; + }); + + // Then brand it for additional type safety + const brandedId = zBrand(baseSchema, `ConvexId_${tableName}` as const); + + // Store table name in metadata for type checking + registryHelpers.setMetadata(brandedId, { + tableName, + isConvexId: true, + typeName: "ConvexId", + originalSchema: z.string(), + }); + + return brandedId as z.ZodType>; +}; + +export type Zid = ReturnType< + typeof zid +>; + +/** + * v4 Custom Zid Class (maintaining compatibility with original) + * + * This class provides the same interface as the original Zid class + * while working with v4's API structure. + */ +interface ZidDef { + typeName: "ConvexId"; + tableName: TableName; +} + +export class ZidClass { + _def: ZidDef; + private _zodType: z.ZodType>; + + constructor(def: ZidDef) { + this._def = def; + this._zodType = zid(def.tableName); + } + + parse(input: any): GenericId { + return this._zodType.parse(input); + } + + safeParse(input: any) { + return this._zodType.safeParse(input); + } + + get tableName() { + return this._def.tableName; + } + + // Forward all other ZodType methods to the underlying zid + optional() { + return this._zodType.optional(); + } + + nullable() { + return this._zodType.nullable(); + } + + describe(description: string) { + return this._zodType.describe(description); + } +} + +/** + * Create a Zid class instance + */ +export function createZidClass( + tableName: TableName, +): ZidClass { + return new ZidClass({ typeName: "ConvexId", tableName }); +} + +/** + * Custom error formatting (v4 feature) + */ +/** + * v4 Enhanced error formatting using native Zod v4 error types and formatters + */ +export function formatZodError( + error: z.ZodError, + options?: { + includePath?: boolean; + includeCode?: boolean; + pretty?: boolean; + format?: "flat" | "tree" | "formatted" | "prettified"; + }, +): string { + if (options?.pretty || options?.format === "prettified") { + // Use v4's native prettifyError function + return z.prettifyError(error); + } + + if (options?.format === "flat") { + // Simple flat format using error issues directly + const formErrors = error.issues.filter((issue) => issue.path.length === 0); + const fieldErrors = error.issues.filter((issue) => issue.path.length > 0); + + const parts: string[] = []; + + if (formErrors.length > 0) { + parts.push(`Form errors: ${formErrors.map((e) => e.message).join(", ")}`); + } + + if (fieldErrors.length > 0) { + const grouped = fieldErrors.reduce( + (acc, issue) => { + const pathStr = issue.path.join("."); + if (!acc[pathStr]) acc[pathStr] = []; + acc[pathStr].push(issue.message); + return acc; + }, + {} as Record, + ); + + const fieldErrorStr = Object.entries(grouped) + .map(([field, messages]) => `${field}: ${messages.join(", ")}`) + .join("; "); + parts.push(`Field errors: ${fieldErrorStr}`); + } + + return parts.join("\n") || "Unknown validation error"; + } + + if (options?.format === "formatted") { + // Use v4's formatError for hierarchical output + const formatted = z.formatError(error); + return JSON.stringify(formatted, null, 2); + } + + if (options?.format === "tree") { + // Use v4's treeifyError for tree structure + const tree = z.treeifyError(error); + return JSON.stringify(tree, null, 2); + } + + // Default: use v4's native error message + return error.message; +} + +/** + * Create a structured error object using Zod v4's enhanced error types + * @param error The ZodError instance + * @returns Enhanced error object with v4 error structure + */ +export function createV4ErrorObject(error: z.ZodError) { + return { + issues: error.issues.map((issue) => ({ + code: issue.code, + path: issue.path.map((p) => String(p)), + message: issue.message, + // Include v4-specific issue properties (only serializable values) + ...(issue.code === "invalid_type" && + "expected" in issue && { expected: String(issue.expected) }), + ...(issue.code === "too_big" && + "maximum" in issue && { maximum: Number(issue.maximum) }), + ...(issue.code === "too_small" && + "minimum" in issue && { minimum: Number(issue.minimum) }), + ...(issue.code === "invalid_format" && + "format" in issue && { format: String(issue.format) }), + ...(issue.code === "unrecognized_keys" && + "keys" in issue && { keys: issue.keys }), + ...(issue.code === "invalid_value" && + "values" in issue && { + values: issue.values?.map((v) => String(v)), + }), + })), + // Use native v4's flattened error structure + flat: z.flattenError(error), + // Include v4's formatted error structure + formatted: z.formatError(error), + // Include v4's tree structure for hierarchical error display + tree: z.treeifyError(error), + // Include v4's prettified string for human-readable output + prettified: z.prettifyError(error), + }; +} + +// Helper function to transform Zod output to Convex-compatible format +export function transformZodOutputToConvex( + data: any, + zodValidators: Record, +): any { + if (!data || typeof data !== "object") return data; + + const transformed: any = {}; + + for (const [key, value] of Object.entries(data)) { + const zodValidator = zodValidators[key]; + if (!zodValidator) { + throw new Error(`No validator found for key: ${key}`); + } + + if (zodValidator instanceof z.ZodTuple && Array.isArray(value)) { + // Convert array to object with _0, _1, etc. keys + const tupleObj: Record = {}; + value.forEach((item, index) => { + tupleObj[`_${index}`] = item; + }); + transformed[key] = tupleObj; + } else if ( + zodValidator instanceof z.ZodObject && + typeof value === "object" && + value !== null + ) { + // Recursively transform nested objects + transformed[key] = transformZodOutputToConvex(value, zodValidator.shape); + } else { + // Apply forward transforms if available + const processedValue = applyForwardTransformsToValue(value, zodValidator); + transformed[key] = processedValue; + } + } + + return transformed; +} + +// Helper to transform data based on a Zod schema (handles defaults and optionals) +export function transformZodDataForConvex(data: any, schema: z.ZodType): any { + if (!data || typeof data !== "object") return data; + + // Helper to check if a schema contains tuples + function transformValue(value: any, zodSchema: z.ZodType): any { + // Handle optional schemas + if (zodSchema instanceof z.ZodOptional) { + return value === undefined + ? undefined + : transformValue(value, zodSchema.unwrap() as z.ZodType); + } + + // Handle default schemas + if (zodSchema instanceof z.ZodDefault) { + const innerSchema = zodSchema.def.innerType; + return transformValue(value, innerSchema as z.ZodType); + } + + // Handle tuples + if (zodSchema instanceof z.ZodTuple && Array.isArray(value)) { + const tupleObj: Record = {}; + value.forEach((item, index) => { + tupleObj[`_${index}`] = item; + }); + return tupleObj; + } + + // Handle objects + if ( + zodSchema instanceof z.ZodObject && + typeof value === "object" && + value !== null + ) { + const transformed: any = {}; + const shape = zodSchema.shape; + + for (const [key, val] of Object.entries(value)) { + if (shape[key]) { + transformed[key] = transformValue(val, shape[key] as z.ZodType); + } else { + transformed[key] = val; + } + } + return transformed; + } + + // Handle arrays + if (zodSchema instanceof z.ZodArray && Array.isArray(value)) { + return value.map((item) => + transformValue(item, zodSchema.element as z.ZodType), + ); + } + + // Default: return value as is + return value; + } + + return transformValue(data, schema); +} + +// Helper to create Convex validators that accept arrays for tuple fields +function createTupleAcceptingValidator(zodSchema: z.ZodType): any { + // Handle optional schemas + if (zodSchema instanceof z.ZodOptional) { + return v.optional( + createTupleAcceptingValidator(zodSchema.unwrap() as z.ZodType), + ); + } + + // Handle default schemas + if (zodSchema instanceof z.ZodDefault) { + const innerType = zodSchema.def.innerType as z.ZodType; + return createTupleAcceptingValidator(innerType); + } + + // Handle tuples - create a union that accepts both array and object formats + if (zodSchema instanceof z.ZodTuple) { + const items = zodSchema.def.items as z.ZodTypeAny[]; + + // Create object validator for Convex format + const fields: Record = {}; + items.forEach((item, index) => { + fields[`_${index}`] = zodToConvex(item); + }); + const objectValidator = v.object(fields); + + // Create array validator that matches the tuple structure + const arrayValidator = v.array(v.any()); + + // Return a union that accepts both formats + return v.union(arrayValidator, objectValidator); + } + + // Handle objects - recursively process shape + if (zodSchema instanceof z.ZodObject) { + const shape = zodSchema.shape; + const convexShape: Record = {}; + + for (const [key, value] of Object.entries(shape)) { + convexShape[key] = createTupleAcceptingValidator(value as z.ZodType); + } + + return v.object(convexShape); + } + + // For other types, use normal conversion + return zodToConvex(zodSchema); +} + +// Helper to pre-transform client args to Convex format +function preTransformClientArgs( + args: any, + zodValidators: Record, +): any { + if (!args || typeof args !== "object") return args; + + const transformed: any = {}; + + for (const [key, value] of Object.entries(args)) { + const zodValidator = zodValidators[key]; + + // Transform arrays to objects for tuples BEFORE Convex validation + if (zodValidator instanceof z.ZodTuple && Array.isArray(value)) { + const tupleObj: Record = {}; + value.forEach((item, index) => { + tupleObj[`_${index}`] = item; + }); + transformed[key] = tupleObj; + } else if ( + zodValidator instanceof z.ZodObject && + typeof value === "object" && + value !== null + ) { + // Recursively transform nested objects + transformed[key] = preTransformClientArgs(value, zodValidator.shape); + } else { + transformed[key] = value; + } + } + + return transformed; +} + +/** + * Apply forward transforms to data before storing in Convex + * This handles bidirectional transforms by applying the forward function + */ +export function applyForwardTransforms(data: any, schema: z.ZodType): any { + if (!data || typeof data !== "object") return data; + + const result: any = {}; + + // Handle object schemas + if (schema instanceof z.ZodObject) { + const shape = schema.shape; + for (const [key, value] of Object.entries(data)) { + const fieldSchema = shape[key]; + if (fieldSchema) { + result[key] = applyForwardTransformsToValue(value, fieldSchema); + } else { + result[key] = value; + } + } + return result; + } + + // For non-object schemas, apply transform to the whole value + return applyForwardTransformsToValue(data, schema); +} + +/** + * Apply forward transform to a single value + */ +function applyForwardTransformsToValue(value: any, schema: z.ZodType): any { + if (value === undefined || value === null) return value; + + // Unwrap optional and default schemas + let actualSchema: any = schema; + if (actualSchema instanceof z.ZodOptional) { + actualSchema = actualSchema.unwrap(); + } + if (actualSchema instanceof z.ZodDefault) { + actualSchema = actualSchema.def.innerType; + } + + // Check if this schema has a registered transform + const transformMetadata = + transformRegistry.getTransformForSchema(actualSchema); + if (transformMetadata) { + // Only apply forward transform if the value is in input format + // If it's already transformed (e.g., already a string from Date), skip it + try { + // Try to parse with input validator to see if value is in input format + transformMetadata.inputValidator.parse(value); + // If parsing succeeds, value is in input format, so apply forward transform + return transformMetadata.forwardTransform(value); + } catch { + // If parsing fails, value might already be transformed or invalid + // Return as-is to avoid double transformation + return value; + } + } + + // Handle arrays recursively + if (actualSchema instanceof z.ZodArray && Array.isArray(value)) { + return value.map((item) => + applyForwardTransformsToValue(item, actualSchema.element as any), + ); + } + + // Handle nested objects recursively + if (actualSchema instanceof z.ZodObject && typeof value === "object") { + return applyForwardTransforms(value, actualSchema); + } + + return value; +} + +/** + * Apply reverse transforms to data coming from Convex + * This handles bidirectional transforms by applying the reverse function + */ +export function applyReverseTransforms(data: any, schema: z.ZodType): any { + if (!data || typeof data !== "object") return data; + + const result: any = {}; + + // Handle object schemas + if (schema instanceof z.ZodObject) { + const shape = schema.shape; + for (const [key, value] of Object.entries(data)) { + const fieldSchema = shape[key]; + if (fieldSchema) { + result[key] = applyReverseTransformsToValue(value, fieldSchema); + } else { + result[key] = value; + } + } + return result; + } + + // For non-object schemas, apply transform to the whole value + return applyReverseTransformsToValue(data, schema); +} + +/** + * Apply reverse transform to a single value + */ +function applyReverseTransformsToValue(value: any, schema: z.ZodType): any { + if (value === undefined || value === null) return value; + + // Unwrap optional and default schemas + let actualSchema: any = schema; + if (actualSchema instanceof z.ZodOptional) { + actualSchema = actualSchema.unwrap(); + } + if (actualSchema instanceof z.ZodDefault) { + actualSchema = actualSchema.def.innerType; + } + + // Check if this schema has a registered transform with reverse capability + const transformMetadata = + transformRegistry.getTransformForSchema(actualSchema); + if (transformMetadata && transformMetadata.reverseTransform) { + return transformMetadata.reverseTransform(value); + } + + // Handle arrays recursively + if (actualSchema instanceof z.ZodArray && Array.isArray(value)) { + return value.map((item) => + applyReverseTransformsToValue(item, actualSchema.element as any), + ); + } + + // Handle nested objects recursively + if (actualSchema instanceof z.ZodObject && typeof value === "object") { + return applyReverseTransforms(value, actualSchema); + } + + return value; +} + +/** + * Transform data from Convex format back to Zod format using schema conversion. + * This leverages our existing convexToZod schema converter to create a transform. + */ +export function transformConvexDataToZod( + data: any, + originalZodSchema: z.ZodType, +): any { + // First convert the Zod schema to Convex validator + const convexValidator = zodToConvex(originalZodSchema); + + // Then convert it back to get a Zod schema that knows about the transformations + const transformedZodSchema = convexToZod(convexValidator); + + // Debug logging + console.log("Original schema:", originalZodSchema); + console.log("Convex validator:", convexValidator); + console.log("Transformed schema:", transformedZodSchema); + console.log("Data to transform:", data); + + // The convexToZod function already creates schemas that handle tuple conversion + // We just need to parse the data through it + try { + const transformed = transformedZodSchema.parse(data); + console.log("Successfully transformed data:", transformed); + return transformed; + } catch (e) { + // If parsing fails, return original data + console.warn("Failed to transform Convex data to Zod format:", e); + return data; + } +} + +// Move CustomBuilder and helper functions first +function customFnBuilder(builder: any, mod: any): any { + // Looking forward to when input / args / ... are optional + const inputMod = mod.input ?? NoOp.input; + const inputArgs = mod.args ?? NoOp.args; + + // We'll create the wrapper inside the returned function where we have access to fn + + return (fn: Registration): any => { + let args = fn.args ?? {}; + let returns = fn.returns; + const originalZodArgs = { ...args }; // Keep original Zod args for transformation + + // Create a wrapper around the original builder that pre-transforms args + const wrappedBuilder = (fnDef: any) => { + // If fnDef has a handler and args with Zod validators, wrap it + if ( + fnDef.handler && + fnDef.args && + Object.values(originalZodArgs).some((v) => v instanceof z.ZodType) + ) { + const originalHandler = fnDef.handler; + + // Create a new handler that pre-transforms tuple args + fnDef.handler = async (ctx: any, args: any) => { + // Pre-transform client args (arrays) to Convex format (objects) for tuples + args = preTransformClientArgs(args, originalZodArgs); + return originalHandler(ctx, args); + }; + } + return builder(fnDef); + }; + + // Convert Zod validators to Convex + if (!fn.skipConvexValidation) { + if (args && Object.values(args).some((arg) => arg instanceof z.ZodType)) { + // Create modified Convex validators that accept arrays for tuples + const modifiedArgs: Record = {}; + + for (const [key, value] of Object.entries(args)) { + if (value instanceof z.ZodType) { + const validator = createTupleAcceptingValidator(value); + modifiedArgs[key] = validator; + } else { + modifiedArgs[key] = value; + } + } + + args = modifiedArgs; + } + } + + // Handle return validation with v4 metadata - Add type guard + if (returns && returns instanceof z.ZodType) { + // Already a ZodType, use it directly + } else if (returns && !(returns instanceof z.ZodType)) { + returns = z.object(returns); + } + + // v4: Store metadata if provided + if (fn.metadata) { + if (returns && returns instanceof z.ZodType) { + registryHelpers.setMetadata(returns, fn.metadata); + } + + // Generate JSON Schema automatically + if (fn.metadata.generateJsonSchema && returns instanceof z.ZodType) { + const jsonSchema = zodToJsonSchema(returns); + registryHelpers.setJsonSchema(returns, jsonSchema); + } + } + + const returnValidator = + fn.returns && !fn.skipConvexValidation + ? { returns: zodOutputToConvex(returns) } + : null; + + // Handle the case where function has args (like original) + if ("args" in fn && fn.args !== undefined && !fn.skipConvexValidation) { + let argsValidator = fn.args; + + // Check if it's actually a ZodValidator (has Zod fields) or just an empty object + const hasZodFields = + argsValidator && + typeof argsValidator === "object" && + Object.values(argsValidator).some((v) => v instanceof z.ZodType); + + // Check if it's EmptyObject (Record) or just {} + // Both represent "no arguments" - EmptyObject is the type-safe version + const isEmptyObject = Object.keys(argsValidator).length === 0; + + // If it's an empty object with no Zod fields, skip args validation + if (!hasZodFields && isEmptyObject) { + // Fall through to the simple handler case below + } else { + // Process Zod validators + if (argsValidator instanceof z.ZodType) { + if (argsValidator instanceof z.ZodObject) { + argsValidator = argsValidator.def.shape; + } else { + throw new Error( + "Unsupported zod type as args validator: " + + argsValidator.constructor.name, + ); + } + } + // Use our tuple-accepting validator instead of direct conversion + const convexValidator: Record = {}; + for (const [key, value] of Object.entries(argsValidator)) { + if (value instanceof z.ZodType) { + convexValidator[key] = createTupleAcceptingValidator(value); + } else { + convexValidator[key] = value; + } + } + + const convexFn = { + args: { + ...convexValidator, + ...inputArgs, + }, + ...returnValidator, + handler: async (ctx: any, allArgs: any) => { + const added = await inputMod( + ctx, + pick(allArgs, Object.keys(inputArgs)), + ); + const rawArgs = pick(allArgs, Object.keys(originalZodArgs)); + // No transformation needed - we're accepting arrays directly now + // Validate with original Zod schemas + const parsed = z.object(originalZodArgs).safeParse(rawArgs); + if (!parsed.success) { + throw new ConvexError({ + ZodError: JSON.parse( + JSON.stringify(parsed.error.issues, null, 2), + ) as Value[], + }); + } + // Transform the parsed data to Convex format for database operations + const convexCompatibleArgs = transformZodOutputToConvex( + parsed.data, + originalZodArgs, + ); + const result = await fn.handler( + { ...ctx, ...added.ctx }, + { ...convexCompatibleArgs, ...added.args }, + ); + if (returns && returns instanceof z.ZodType) { + // Parse the result to ensure it matches the expected type + // This preserves literal types from the Zod schema + const parsedResult = returns.parse(result); + return parsedResult; + } + return result; + }, + }; + + return wrappedBuilder(convexFn); + } + } + + // Handle validation error for inputArgs without function args + if (Object.keys(inputArgs).length > 0 && !fn.skipConvexValidation) { + throw new Error( + "If you're using a custom function with arguments for the input " + + "modifier, you must declare the arguments for the function too.", + ); + } + + // Fallback case when no args are declared (simplified version) + const handler = fn.handler ?? fn; + const convexFn = { + ...returnValidator, + args: inputArgs, + handler: async (ctx: any, args: any) => { + const added = await inputMod(ctx, args); + const result = await handler( + { ...ctx, ...added.ctx }, + { ...args, ...added.args }, + ); + if (returns && returns instanceof z.ZodType) { + // Parse the result to ensure it matches the expected type + // This preserves literal types from the Zod schema + const parsedResult = returns.parse(result); + return parsedResult; + } + return result; + }, + }; + + return builder(convexFn); + }; +} + +/** + * v4 Enhanced custom query with metadata and error handling + */ +export function zCustomQuery< + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + InputCtx extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + query: QueryBuilder, + mod: Mod, ModArgsValidator, ModCtx, ModMadeArgs>, +): CustomBuilder< + "query", + ModArgsValidator, + ModCtx, + ModMadeArgs, + GenericQueryCtx, + Visibility +>; + +// Overload for chaining CustomBuilder instances +export function zCustomQuery< + PrevModArgsValidator extends PropertyValidators, + PrevModCtx extends Record, + PrevModMadeArgs extends Record, + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + customBuilder: CustomBuilder< + "query", + PrevModArgsValidator, + PrevModCtx, + PrevModMadeArgs, + GenericQueryCtx, + Visibility + >, + mod: Mod< + Overwrite, PrevModCtx>, + ModArgsValidator, + ModCtx, + ModMadeArgs + >, +): CustomBuilder< + "query", + PrevModArgsValidator & ModArgsValidator, + PrevModCtx & ModCtx, + PrevModMadeArgs & ModMadeArgs, + GenericQueryCtx, + Visibility +>; + +export function zCustomQuery< + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + query: + | QueryBuilder + | CustomBuilder, Visibility>, + mod: Mod, +) { + return customFnBuilder(query, mod) as CustomBuilder< + "query", + ModArgsValidator, + ModCtx, + ModMadeArgs, + GenericQueryCtx, + Visibility + >; +} + +/** + * v4 Enhanced custom mutation + */ +export function zCustomMutation< + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + mutation: MutationBuilder, + mod: Mod< + GenericMutationCtx, + ModArgsValidator, + ModCtx, + ModMadeArgs + >, +): CustomBuilder< + "mutation", + ModArgsValidator, + ModCtx, + ModMadeArgs, + GenericMutationCtx, + Visibility +>; + +// Overload for chaining CustomBuilder instances +export function zCustomMutation< + PrevModArgsValidator extends PropertyValidators, + PrevModCtx extends Record, + PrevModMadeArgs extends Record, + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + customBuilder: CustomBuilder< + "mutation", + PrevModArgsValidator, + PrevModCtx, + PrevModMadeArgs, + GenericMutationCtx, + Visibility + >, + mod: Mod< + Overwrite, PrevModCtx>, + ModArgsValidator, + ModCtx, + ModMadeArgs + >, +): CustomBuilder< + "mutation", + PrevModArgsValidator & ModArgsValidator, + PrevModCtx & ModCtx, + PrevModMadeArgs & ModMadeArgs, + GenericMutationCtx, + Visibility +>; + +export function zCustomMutation< + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + mutation: + | MutationBuilder + | CustomBuilder< + any, + any, + any, + any, + GenericMutationCtx, + Visibility + >, + mod: Mod, +) { + return customFnBuilder(mutation, mod) as CustomBuilder< + "mutation", + ModArgsValidator, + ModCtx, + ModMadeArgs, + GenericMutationCtx, + Visibility + >; +} + +/** + * v4 Enhanced custom action + */ +export function zCustomAction< + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + action: ActionBuilder, + mod: Mod, ModArgsValidator, ModCtx, ModMadeArgs>, +): CustomBuilder< + "action", + ModArgsValidator, + ModCtx, + ModMadeArgs, + GenericActionCtx, + Visibility +>; + +// Overload for chaining CustomBuilder instances +export function zCustomAction< + PrevModArgsValidator extends PropertyValidators, + PrevModCtx extends Record, + PrevModMadeArgs extends Record, + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + customBuilder: CustomBuilder< + "action", + PrevModArgsValidator, + PrevModCtx, + PrevModMadeArgs, + GenericActionCtx, + Visibility + >, + mod: Mod< + Overwrite, PrevModCtx>, + ModArgsValidator, + ModCtx, + ModMadeArgs + >, +): CustomBuilder< + "action", + PrevModArgsValidator & ModArgsValidator, + PrevModCtx & ModCtx, + PrevModMadeArgs & ModMadeArgs, + GenericActionCtx, + Visibility +>; + +export function zCustomAction< + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + Visibility extends FunctionVisibility, + DataModel extends GenericDataModel, +>( + action: + | ActionBuilder + | CustomBuilder< + any, + any, + any, + any, + GenericActionCtx, + Visibility + >, + mod: Mod, +) { + return customFnBuilder(action, mod) as CustomBuilder< + "action", + ModArgsValidator, + ModCtx, + ModMadeArgs, + GenericActionCtx, + Visibility + >; +} + +export interface CustomBuilder< + Type extends "query" | "mutation" | "action", + ModArgsValidator extends PropertyValidators, + ModCtx extends Record, + ModMadeArgs extends Record, + InputCtx extends Record, + Visibility extends FunctionVisibility, +> { + < + ArgsValidator extends ZodValidator | PropertyValidators = EmptyObject, + ReturnsZodValidator extends + | z.ZodType + | ZodValidator + | PropertyValidators = any, + // v4: Support for .overwrite() transforms + ReturnValue extends + ReturnValueForOptionalZodValidator = any, + >( + fn: + | ((ArgsValidator extends EmptyObject + ? + | { + args?: ArgsValidator; + } + | { [K in keyof ArgsValidator]: never } + : { args: ArgsValidator }) & { + // v4: Enhanced metadata support + returns?: ReturnsZodValidator; + metadata?: { + description?: string; + deprecated?: boolean; + version?: string; + tags?: string[]; + generateJsonSchema?: boolean; + [key: string]: any; + }; + // v4: Skip Convex validation for pure Zod + skipConvexValidation?: boolean; + // ✅ Now properly types the handler function using Convex argument structure + handler: ( + ctx: Overwrite, + ...args: ArgsValidator extends EmptyObject + ? ArgsArrayForOptionalValidator extends [infer A] + ? [A & ModMadeArgs] + : [ModMadeArgs] + : ArgsArrayForOptionalValidator extends [infer A] + ? [A & ModMadeArgs] + : [ModMadeArgs] + ) => ReturnsZodValidator extends z.ZodType + ? + | z.output + | Promise> + : ReturnsZodValidator extends ZodValidator + ? + | z.output> + | Promise>> + : ReturnsZodValidator extends PropertyValidators + ? + | ObjectType + | Promise> + : any; + // v4: Return type validation support + /** + * Validates the value returned by the function. + * Note: you can't pass an object directly without wrapping it + * in `z.object()`. + */ + }) + | { + // Alternative: function-only syntax + ( + ctx: Overwrite, + ...args: ArgsValidator extends EmptyObject + ? ArgsArrayForOptionalValidator extends [infer A] + ? [A & ModMadeArgs] + : [ModMadeArgs] + : ArgsArrayForOptionalValidator extends [infer A] + ? [A & ModMadeArgs] + : [ModMadeArgs] + ): any; + }, + ): Registration< + Type, + Visibility, + ArgsArrayToObject< + ArgsValidator extends ZodValidator + ? [ + ObjectType< + ConvexValidatorFromZodFields + > & + ObjectType, + ] + : ArgsValidator extends PropertyValidators + ? [ObjectType & ObjectType] + : [ObjectType] + >, + ReturnsZodValidator extends z.ZodType | ZodValidator | PropertyValidators + ? ReturnValueForOptionalZodValidator + : any + >; +} + +// Type helpers +/** + * Converts a return value validator to the appropriate TypeScript type. + * Handles the conversion from various validator types (Zod, ZodValidator, PropertyValidators) to their TypeScript equivalents. + * This is used in custom builder functions to type the return value of handlers. + * + * @example + * ```ts + * // Zod type → z.output + * type UserResult = ReturnValueForOptionalZodValidator> + * // Result: { name: string } + * + * // ZodValidator (Record) → inferred object type + * type UserResult = ReturnValueForOptionalZodValidator<{ name: z.ZodString, age: z.ZodNumber }> + * // Result: { name: string; age: number } + * + * // PropertyValidators (Convex validators) → inferred object type + * type UserResult = ReturnValueForOptionalZodValidator<{ name: VString<"required"> }> + * // Result: { name: string } + * ``` + */ +export type ReturnValueForOptionalZodValidator< + ReturnsValidator extends z.ZodType | ZodValidator | PropertyValidators, +> = ReturnsValidator extends z.ZodType + ? z.output | Promise> + : ReturnsValidator extends ZodValidator + ? + | z.output> + | Promise>> + : ReturnsValidator extends PropertyValidators + ? ObjectType | Promise> + : any; + +// Helper types +/** + * Utility type that merges two types by overwriting properties in T with properties from U. + * Used for context modification in custom builders where ModCtx overrides InputCtx. + * + * @example + * ```ts + * type Base = { a: string; b: number }; + * type Override = { b: string; c: boolean }; + * type Result = Overwrite; // { a: string; b: string; c: boolean } + * ``` + */ +type Overwrite = Omit & U; + +/** + * Hack! This type causes TypeScript to simplify how it renders object types. + * + * It is functionally the identity for object types, but in practice it can + * simplify expressions like `A & B`. + * + * This is copied from the v3 helper to solve intersection type display issues. + */ +type Expand> = + ObjectType extends Record + ? { + [Key in keyof ObjectType]: ObjectType[Key]; + } + : never; + +/** + * Represents Convex's fundamental argument structure: either no arguments or exactly one arguments object. + * This encodes the core constraint of Convex functions. + * + * @example + * ```ts + * // Valid Convex function signatures: + * handler: (ctx) => void // No arguments + * handler: (ctx, args: { name: string }) => void // One arguments object + * + * // Invalid Convex function signatures: + * handler: (ctx, name: string, age: number) => void // Multiple arguments (not allowed) + * ``` + */ +type OneArgArray = + [ArgsObject]; + +/** + * The exported type representing valid Convex function argument structures. + * Either an empty array (no arguments) or a single-element array (one arguments object). + * This is the foundation for all Convex function argument typing. + */ +export type ArgsArray = OneArgArray | []; + +/** + * Converts a Zod validator to the appropriate Convex argument array structure. + * Handles the conversion from Zod schemas to Convex's single-argument constraint. + * + * @example + * ```ts + * // ZodValidator (Record) → [inferred object type] + * type UserArgs = ArgsArrayForOptionalValidator<{ name: z.ZodString, age: z.ZodNumber }> + * // Result: [{ name: string; age: number }] + * + * // z.ZodObject → [output type] + * type UserArgs = ArgsArrayForOptionalValidator> + * // Result: [{ name: string }] + * + * // void → ArgsArray (either [] or [DefaultFunctionArgs]) + * type NoArgs = ArgsArrayForOptionalValidator + * // Result: [] | [DefaultFunctionArgs] + * ``` + */ +export type ArgsArrayForOptionalValidator< + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type + ArgsValidator extends + | ZodValidator + | z.ZodObject + | PropertyValidators + | void, +> = [ArgsValidator] extends [ZodValidator] + ? [z.output>] + : [ArgsValidator] extends [z.ZodObject] + ? [z.output] + : [ArgsValidator] extends [PropertyValidators] + ? [ObjectType] + : ArgsArray; + +/** + * Similar to ArgsArrayForOptionalValidator but guarantees a single argument object. + * Used when we know there should be at least one argument (even if empty). + * Falls back to OneArgArray instead of ArgsArray for the void case. + * + * @example + * ```ts + * // Always produces a single-element array structure + * type Result = DefaultArgsForOptionalValidator + * // Result: [DefaultFunctionArgs] (not [] | [DefaultFunctionArgs]) + * ``` + */ +export type DefaultArgsForOptionalValidator< + // eslint-disable-next-line @typescript-eslint/no-invalid-void-type + ArgsValidator extends ZodValidator | z.ZodObject | void, +> = [ArgsValidator] extends [ZodValidator] + ? [z.output>] + : [ArgsValidator] extends [z.ZodObject] + ? [z.output] + : OneArgArray; + +/** + * JSON Schema generation using Zod v4's built-in API + */ +export function zodToJsonSchema( + schema: z.ZodType, + options?: { + /** A registry used to look up metadata for each schema. Any schema with an `id` property will be extracted as a $def. + * @default globalRegistry */ + metadata?: any; // z.registry type + /** The JSON Schema version to target. + * - `"draft-2020-12"` — Default. JSON Schema Draft 2020-12 + * - `"draft-7"` — JSON Schema Draft 7 */ + target?: "draft-7" | "draft-2020-12"; + /** How to handle unrepresentable types. + * - `"throw"` — Default. Unrepresentable types throw an error + * - `"any"` — Unrepresentable types become `{}` */ + unrepresentable?: "throw" | "any"; + /** Arbitrary custom logic that can be used to modify the generated JSON Schema. */ + override?: (ctx: { + zodSchema: any; + jsonSchema: any; + path: (string | number)[]; + }) => void; + /** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, defaults, coerced primitives, etc. + * - `"output"` — Default. Convert the output schema. + * - `"input"` — Convert the input schema. */ + io?: "input" | "output"; + /** How to handle cycles. + * - `"ref"` — Default. Cycles will be broken using $defs + * - `"throw"` — Cycles will throw an error if encountered */ + cycles?: "ref" | "throw"; + /** How to handle reused schemas. + * - `"ref"` — Use $refs for reused schemas + * - `"inline"` — Inline reused schemas */ + reused?: "ref" | "inline"; + }, +): Record { + // Check cache first + const cached = registryHelpers.getJsonSchema(schema); + if (cached) return cached; + + try { + // Use Zod v4's built-in JSON Schema generation with our metadata registry + const finalOptions = { + metadata: globalRegistry, + target: "draft-2020-12" as const, + unrepresentable: "any" as const, + ...options, + }; + + const jsonSchema = z.toJSONSchema(schema, finalOptions); + + // Cache the result in our registry + registryHelpers.setJsonSchema(schema, jsonSchema); + + return jsonSchema; + } catch (error) { + // Fallback for schemas that might not be supported by z.toJSONSchema + console.warn( + "Failed to generate JSON Schema with z.toJSONSchema, using fallback:", + error, + ); + + // Simple fallback for unsupported schemas + const fallbackSchema = { + type: "object", + additionalProperties: true, + description: "Schema conversion not supported", + }; + + registryHelpers.setJsonSchema(schema, fallbackSchema); + return fallbackSchema; + } +} + +/** + * Convert a Zod validator to a Convex validator + */ +export function zodToConvex( + zodValidator: Z, +): ConvexValidatorFromZod; + +export function zodToConvex( + zod: Z, +): ConvexValidatorFromZodFields; + +export function zodToConvex( + zod: Z, +): Z extends z.ZodType + ? ConvexValidatorFromZod + : Z extends ZodValidator + ? ConvexValidatorFromZodFields + : never { + if (typeof zod === "object" && zod !== null && !("_zod" in zod)) { + return zodToConvexFields(zod as ZodValidator) as Z extends z.ZodType + ? ConvexValidatorFromZod + : Z extends ZodValidator + ? ConvexValidatorFromZodFields + : never; + } + + return zodToConvexInternal(zod as z.ZodType) as Z extends z.ZodType + ? ConvexValidatorFromZod + : Z extends ZodValidator + ? ConvexValidatorFromZodFields + : never; +} + +export function zodToConvexFields(zod: Z) { + return Object.fromEntries( + Object.entries(zod).map(([k, v]) => [k, zodToConvex(v)]), + ) as ConvexValidatorFromZodFieldsAuto; +} + +/** + * Convert a Zod output validator to Convex + */ +export function zodOutputToConvex( + zodValidator: Z, +): ConvexValidatorFromZodOutput; + +export function zodOutputToConvex( + zod: Z, +): { [k in keyof Z]: ConvexValidatorFromZodOutput }; + +export function zodOutputToConvex( + zod: Z, +): Z extends z.ZodType + ? ConvexValidatorFromZodOutput + : Z extends ZodValidator + ? { [k in keyof Z]: ConvexValidatorFromZodOutput } + : never { + if (typeof zod === "object" && zod !== null && !("_zod" in zod)) { + return zodOutputToConvexFields(zod as ZodValidator) as Z extends z.ZodType + ? ConvexValidatorFromZodOutput + : Z extends ZodValidator + ? { [k in keyof Z]: ConvexValidatorFromZodOutput } + : never; + } + return zodOutputToConvexInternal(zod as z.ZodType) as Z extends z.ZodType + ? ConvexValidatorFromZodOutput + : Z extends ZodValidator + ? { [k in keyof Z]: ConvexValidatorFromZodOutput } + : never; +} + +export function zodOutputToConvexFields(zod: Z) { + return Object.fromEntries( + Object.entries(zod).map(([k, v]) => [k, zodOutputToConvex(v)]), + ) as { [k in keyof Z]: ConvexValidatorFromZodOutput }; +} + +/** + * v4 Enhanced system fields with metadata + */ +export const withSystemFields = < + Table extends string, + T extends { [key: string]: z.ZodType }, +>( + tableName: Table, + zObject: T, + options?: { + includeUpdatedAt?: boolean; + metadata?: Record; + }, +) => { + const fields = { + ...zObject, + _id: zid(tableName).optional(), + _creationTime: z.number().optional().describe("Creation timestamp"), + } as T & { + _id: z.ZodOptional>; + _creationTime: z.ZodOptional; + _updatedAt?: z.ZodOptional; + }; + + if (options?.includeUpdatedAt) { + fields._updatedAt = z.number().optional().describe("Last update timestamp"); + } + + if (options?.metadata) { + Object.values(fields).forEach((field) => { + if (field instanceof z.ZodType) { + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion + registryHelpers.setMetadata(field, options.metadata!); + } + }); + } + + return fields; +}; + +/** + * Convert Convex validator to Zod + */ +export function convexToZod( + convexValidator: V, +): ZodTypeFromConvexValidator { + const isOptional = convexValidator.isOptional === "optional"; + + let zodValidator: z.ZodType; + + switch (convexValidator.kind) { + case "id": { + const idValidator = convexValidator as { tableName: string }; + zodValidator = zid(idValidator.tableName); + break; + } + case "string": + zodValidator = z.string(); + break; + case "float64": + zodValidator = z.number(); + break; + case "int64": + zodValidator = z.bigint(); + break; + case "boolean": + zodValidator = z.boolean(); + break; + case "null": + zodValidator = z.null(); + break; + case "any": + zodValidator = z.any(); + break; + case "bytes": { + // Bytes in Convex are base64 encoded strings. This matches what is expected by Zod v4's built-in base64 validator + zodValidator = z.base64(); + break; + } + case "array": { + const arrayValidator = convexValidator as VArray; + zodValidator = z.array(convexToZod(arrayValidator.element)); + break; + } + case "object": { + const objectValidator = convexValidator as VObject; + + // Check if this object represents a tuple + if ((objectValidator as any)._zodTuple) { + // Convert back to tuple + const fields = objectValidator.fields; + const keys = Object.keys(fields); + + // Check if all keys are _0, _1, _2, etc. + const tuplePattern = /^_(\d+)$/; + const numericKeys = keys + .map((k) => { + const match = k.match(tuplePattern); + return match ? parseInt(match[1]!, 10) : -1; + }) + .filter((n) => n >= 0); + + const isSequential = + numericKeys.length === keys.length && + numericKeys.sort((a, b) => a - b).every((val, idx) => val === idx); + + if (isSequential) { + // Convert fields to tuple items + const sortedKeys = numericKeys.sort((a, b) => a - b); + const items = sortedKeys.map((idx) => convexToZod(fields[`_${idx}`])); + + // Handle rest elements if present + const rest = (objectValidator as any)._zodTupleRest; + if (rest) { + // Create a schema that handles both fixed items and rest elements + zodValidator = z.object(fields).transform((obj) => { + // First, collect the fixed tuple items + const tupleArray: any[] = sortedKeys.map((idx) => obj[`_${idx}`]); + + // Then, collect any additional numeric keys for rest elements + const allKeys = Object.keys(obj); + const restKeys = allKeys + .filter((k) => { + const match = k.match(/^_(\d+)$/); + if (!match) return false; + const idx = parseInt(match[1]!, 10); + return idx >= sortedKeys.length; + }) + .sort((a, b) => { + const aIdx = parseInt(a.substring(1), 10); + const bIdx = parseInt(b.substring(1), 10); + return aIdx - bIdx; + }); + + // Add rest elements to the array + restKeys.forEach((key) => { + tupleArray.push(obj[key]); + }); + + return tupleArray; + }); + } else { + // No rest elements, just transform the fixed items + const objectSchema = z.object( + Object.fromEntries( + sortedKeys.map((idx, i) => [`_${idx}`, items[i]]), + ), + ); + + zodValidator = objectSchema.transform((obj) => { + return sortedKeys.map((idx) => obj[`_${idx}`]); + }); + } + } else { + // Fall back to regular object + zodValidator = z.object(convexToZodFields(objectValidator.fields)); + } + } else { + // Check if this is an object where ALL keys match _0, _1, _2 pattern (potential tuple) + const fields = objectValidator.fields; + const keys = Object.keys(fields); + const tuplePattern = /^_(\d+)$/; + const numericKeys = keys.map((k) => { + const match = k.match(tuplePattern); + return match ? parseInt(match[1]!, 10) : -1; + }); + const allNumeric = keys.length > 0 && numericKeys.every((n) => n >= 0); + + if (allNumeric) { + // Sort numeric keys and check if sequential from 0 + const sortedNumeric = numericKeys.sort((a, b) => a - b); + const isSequential = sortedNumeric.every((val, idx) => val === idx); + + if (isSequential) { + // Convert to tuple with transform to handle object input + const items = sortedNumeric.map((idx) => + convexToZod(fields[`_${idx}`]), + ); + + // Create a schema that accepts the object format and transforms to array + const objectSchema = z.object( + Object.fromEntries( + sortedNumeric.map((idx) => [`_${idx}`, items[idx]]), + ), + ); + + zodValidator = objectSchema.transform((obj) => { + // Transform {_0: x, _1: y} to [x, y] + return sortedNumeric.map((idx) => obj[`_${idx}`]); + }); + } else { + // Non-sequential numeric keys, keep as object + zodValidator = z.object(convexToZodFields(objectValidator.fields)); + } + } else { + // Regular object + zodValidator = z.object(convexToZodFields(objectValidator.fields)); + } + } + break; + } + case "union": { + const unionValidator = convexValidator as VUnion; + const memberValidators = unionValidator.members.map( + (member: GenericValidator) => convexToZod(member), + ); + zodValidator = z.union([ + memberValidators[0], + memberValidators[1], + ...memberValidators.slice(2), + ]); + break; + } + case "literal": { + const literalValidator = convexValidator as VLiteral; + zodValidator = z.literal(literalValidator.value); + break; + } + case "record": { + const recordValidator = convexValidator as VRecord< + any, + any, + any, + any, + any + >; + const valueValidator = recordValidator.value; + + // Always convert record values normally - don't try to be smart about unions + zodValidator = z.record(z.string(), convexToZod(valueValidator)); + break; + } + default: + throw new Error( + // @ts-expect-error - convexValidator is a never type when every case is handled! + `Unsupported Convex validator kind: ${convexValidator.kind}`, + ); + } + + // For VOptional validators, create a union with null instead of using .optional() + // This matches the expected behavior where optional fields should become unions with null + if (isOptional && convexValidator.kind !== "union") { + zodValidator = z.union([zodValidator, z.null()]); + } + + // Check for default metadata + if ( + convexValidator && + typeof convexValidator === "object" && + "_zodDefault" in convexValidator + ) { + const defaultValue = (convexValidator as any)._zodDefault; + if ( + zodValidator && + typeof zodValidator === "object" && + "default" in zodValidator && + typeof zodValidator.default === "function" + ) { + zodValidator = zodValidator.default(defaultValue); + } + } + + return zodValidator as ZodTypeFromConvexValidator; +} + +// Type helper that maps Convex validators to their specific Zod types +type ZodTypeFromConvexValidator = + V extends VString + ? z.ZodString + : V extends VFloat64 + ? z.ZodNumber + : V extends VInt64 + ? z.ZodBigInt + : V extends VBoolean + ? z.ZodBoolean + : V extends VNull + ? z.ZodNull + : V extends VAny + ? z.ZodAny + : V extends VBytes + ? z.ZodBase64 + : V extends VId + ? z.ZodPipe, any> // zid returns a complex branded type + : V extends VLiteral + ? z.ZodType // Use generic ZodType instead of ZodLiteral to avoid constraint issues + : V extends VArray + ? z.ZodArray>> + : V extends VObject + ? z.ZodObject<{ + [K in keyof F]: z.ZodType>; + }> + : V extends VRecord + ? z.ZodRecord< + z.ZodString, + ZodTypeFromConvexValidator + > + : V extends VUnion + ? Members extends readonly [ + infer A extends GenericValidator, + infer B extends GenericValidator, + ...infer Rest, + ] + ? Rest extends readonly GenericValidator[] + ? z.ZodUnion< + [ + ZodTypeFromConvexValidator, + ZodTypeFromConvexValidator, + ...{ + [I in keyof Rest]: ZodTypeFromConvexValidator< + Rest[I] & GenericValidator + >; + }, + ] + > + : z.ZodUnion< + [ + ZodTypeFromConvexValidator, + ZodTypeFromConvexValidator, + ] + > + : z.ZodUnion<[z.ZodAny, z.ZodAny]> + : V extends VOptional + ? z.ZodOptional> + : z.ZodType>; + +export function convexToZodFields( + convex: C, +): { [K in keyof C]: ZodTypeFromConvexValidator } { + return Object.fromEntries( + Object.entries(convex).map(([k, v]) => [k, convexToZod(v)]), + ) as { [K in keyof C]: ZodTypeFromConvexValidator }; +} + +// Helper function to check if a schema is a Zid +function isZid(schema: z.ZodType): schema is Zid { + // Check our metadata registry for ConvexId marker + const metadata = registryHelpers.getMetadata(schema); + return ( + metadata?.isConvexId === true && + metadata?.tableName && + typeof metadata.tableName === "string" + ); +} + +// Helper function to handle tuple conversion logic +function convertZodTupleToConvex( + actualValidator: z.ZodTuple, + useRecursiveCall: boolean = false, +): GenericValidator { + const items = actualValidator.def.items as z.ZodTypeAny[]; + + // Tuples should become arrays in Convex, not objects + // We'll use the first element's type as the array element type + // If there are multiple different types, we'll create a union + if (items.length === 0) { + return v.array(v.any()); + } + + // Convert all tuple items to their Convex validators + const convexItems = items.map((item) => + useRecursiveCall ? zodToConvexInternal(item) : zodToConvex(item), + ); + + // If all items have the same kind, use that as the element type + const firstKind = convexItems[0]?.kind; + const allSameKind = convexItems.every((item) => item.kind === firstKind); + + if (allSameKind && convexItems.length > 0) { + // All elements are the same type, use that as the array element type + return v.array(convexItems[0]!); + } else if (convexItems.length === 1) { + // Single element tuple + return v.array(convexItems[0]!); + } else if (convexItems.length >= 2) { + // Multiple different types, create a union for the array element type + const unionValidator = v.union( + convexItems[0]!, + convexItems[1]!, + ...convexItems.slice(2), + ); + return v.array(unionValidator); + } else { + return v.array(v.any()); + } +} + +// Helper function to handle readonly conversion logic +function convertZodReadonlyToConvex( + actualValidator: z.ZodReadonly, +): GenericValidator { + const innerType = actualValidator.def.innerType; + if (innerType && innerType instanceof z.ZodType) { + return zodToConvex(innerType); + } else { + return v.any(); + } +} + +// Internal conversion functions using ZodType +function zodToConvexInternal( + zodValidator: Z, +): ConvexValidatorFromZod { + // Check for default and optional wrappers + let actualValidator = zodValidator; + let isOptional = false; + let defaultValue: any = undefined; + let hasDefault = false; + + // Handle ZodDefault (which wraps ZodOptional when using .optional().default()) + if (zodValidator instanceof z.ZodDefault) { + hasDefault = true; + // defaultValue is a getter property, not a function + defaultValue = zodValidator.def.defaultValue; + actualValidator = zodValidator.def.innerType as Z; + } + + // Check for optional (may be wrapped inside ZodDefault) + if (actualValidator instanceof z.ZodOptional) { + isOptional = true; + actualValidator = actualValidator.unwrap() as Z; + + // If the unwrapped type is ZodDefault, handle it here + if (actualValidator instanceof z.ZodDefault) { + hasDefault = true; + defaultValue = actualValidator.def.defaultValue; + actualValidator = actualValidator.def.innerType as Z; + } + } + + let convexValidator: GenericValidator; + + // Check for Zid first (special case) + if (isZid(actualValidator)) { + const metadata = registryHelpers.getMetadata(actualValidator); + const tableName = metadata?.tableName || "unknown"; + convexValidator = v.id(tableName); + } else { + // Use the def.type property for robust type detection + const defType = actualValidator.def?.type; + + switch (defType) { + case "string": + // This catches ZodString and ALL string format types (email, url, uuid, etc.) + convexValidator = v.string(); + break; + case "number": + convexValidator = v.float64(); + break; + case "bigint": + convexValidator = v.int64(); + break; + case "boolean": + convexValidator = v.boolean(); + break; + case "date": + convexValidator = v.float64(); // Dates are stored as timestamps in Convex + break; + case "null": + convexValidator = v.null(); + break; + case "array": { + // Use classic API: ZodArray has .element property + if (actualValidator instanceof z.ZodArray) { + const element = actualValidator.element; + if (element && element instanceof z.ZodType) { + convexValidator = v.array(zodToConvex(element)); + } else { + convexValidator = v.array(v.any()); + } + } else { + convexValidator = v.array(v.any()); + } + break; + } + case "object": { + // Use classic API: ZodObject has .shape property + if (actualValidator instanceof z.ZodObject) { + const shape = actualValidator.shape; + const convexShape: PropertyValidators = {}; + for (const [key, value] of Object.entries(shape)) { + if (value && value instanceof z.ZodType) { + convexShape[key] = zodToConvex(value); + } + } + convexValidator = v.object(convexShape); + } else { + convexValidator = v.object({}); + } + break; + } + case "union": { + // Use classic API: ZodUnion has .options property + if (actualValidator instanceof z.ZodUnion) { + const options = actualValidator.options; + if (options && Array.isArray(options) && options.length > 0) { + if (options.length === 1) { + convexValidator = zodToConvexInternal(options[0]); + } else { + // Convert each option recursively - use zodToConvexInternal to avoid optional wrapping + const convexOptions = options.map((opt) => + zodToConvexInternal(opt), + ) as Validator[]; + if (convexOptions.length >= 2) { + convexValidator = v.union( + convexOptions[0]!, + convexOptions[1]!, + ...convexOptions.slice(2), + ); + } else { + convexValidator = v.any(); + } + } + } else { + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + break; + } + case "literal": { + // Use classic API: ZodLiteral has .value property + if (actualValidator instanceof z.ZodLiteral) { + const literalValue = actualValidator.value; + if (literalValue !== undefined && literalValue !== null) { + convexValidator = v.literal(literalValue); + } else { + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + break; + } + case "enum": { + // Use classic API: ZodEnum has .options property + if (actualValidator instanceof z.ZodEnum) { + const options = actualValidator.options; + if (options && Array.isArray(options) && options.length > 0) { + // Filter out undefined/null and convert to Convex validators + const validLiterals = options + .filter((opt) => opt !== undefined && opt !== null) + .map((opt) => v.literal(opt)); + + if (validLiterals.length === 1) { + convexValidator = validLiterals[0]!; + } else if (validLiterals.length >= 2) { + convexValidator = v.union( + validLiterals[0]!, + validLiterals[1]!, + ...validLiterals.slice(2), + ); + } else { + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + break; + } + case "record": { + // Use classic API: ZodRecord has .valueType property + if (actualValidator instanceof z.ZodRecord) { + const valueType = actualValidator.valueType; + if (valueType && valueType instanceof z.ZodType) { + // First check if the Zod value type is optional before conversion + const isZodOptional = + valueType instanceof z.ZodOptional || + valueType instanceof z.ZodDefault || + (valueType instanceof z.ZodDefault && + valueType.def.innerType instanceof z.ZodOptional); + + if (isZodOptional) { + // For optional record values, we need to handle this specially + // Extract the inner type (non-optional part) and default value if present + let innerType: z.ZodTypeAny; + let defaultValue: any = undefined; + let hasDefault = false; + + if (valueType instanceof z.ZodDefault) { + // Handle ZodDefault wrapper + hasDefault = true; + defaultValue = valueType.def.defaultValue; + const innerFromDefault = valueType.def.innerType; + if (innerFromDefault instanceof z.ZodOptional) { + innerType = innerFromDefault.unwrap() as z.ZodTypeAny; + } else { + innerType = innerFromDefault as z.ZodTypeAny; + } + } else if (valueType instanceof z.ZodOptional) { + // Direct ZodOptional + innerType = valueType.unwrap() as z.ZodTypeAny; + } else { + // Shouldn't happen based on isZodOptional check, but TypeScript needs this + innerType = valueType as z.ZodTypeAny; + } + + // Convert the inner type to Convex and wrap in union with null + const innerConvex = zodToConvexInternal(innerType); + const unionValidator = v.union(innerConvex, v.null()); + + // Add default metadata if present + if (hasDefault) { + (unionValidator as any)._zodDefault = defaultValue; + } + + convexValidator = v.record(v.string(), unionValidator); + } else { + // Non-optional values can be converted normally + convexValidator = v.record(v.string(), zodToConvex(valueType)); + } + } else { + convexValidator = v.record(v.string(), v.any()); + } + } else { + convexValidator = v.record(v.string(), v.any()); + } + break; + } + case "transform": + case "pipe": { + // Handle registered transforms with explicit metadata first + const transformMetadata = + transformRegistry.getTransformForSchema(actualValidator); + if (transformMetadata) { + // Use the output validator from the registered transform + convexValidator = zodToConvex(transformMetadata.outputValidator); + break; + } + + // Handle branded types (which use ZodTransform/ZodPipe but don't change the runtime type) + const metadata = registryHelpers.getMetadata(actualValidator); + + // Check for new transform metadata + if (metadata?.isTransform && metadata?.transformMetadata) { + const tmeta = metadata.transformMetadata as TransformMetadata; + convexValidator = zodToConvex(tmeta.outputValidator); + } + // Check for custom branded validators + else if ( + metadata?.isBrandedValidator && + metadata?.convexValidatorFactory + ) { + // Use the custom Convex validator factory + convexValidator = metadata.convexValidatorFactory(); + } else if (metadata?.brand && metadata?.originalSchema) { + // For branded types created by our zBrand function, use the original schema + convexValidator = zodToConvex(metadata.originalSchema); + } else { + // For non-registered transforms, fall back to 'any' with a warning + console.warn( + "Encountered transform without explicit metadata. Consider using zTransform() for better type safety.", + ); + convexValidator = v.any(); + } + break; + } + case "nullable": { + // Handle nullable schemas by creating a union with null + if (actualValidator instanceof z.ZodNullable) { + const innerSchema = actualValidator.unwrap(); + if (innerSchema && innerSchema instanceof z.ZodType) { + // Check if the inner schema is optional + if (innerSchema instanceof z.ZodOptional) { + // For nullable(optional(T)), we want optional(union(T, null)) + const innerInnerSchema = innerSchema.unwrap(); + const innerInnerValidator = zodToConvexInternal( + innerInnerSchema as z.ZodType, + ); + convexValidator = v.union(innerInnerValidator, v.null()); + isOptional = true; // Mark as optional so it gets wrapped later + } else { + const innerValidator = zodToConvex(innerSchema); + convexValidator = v.union(innerValidator, v.null()); + } + } else { + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + break; + } + case "tuple": { + // Handle tuple types as objects with numeric keys + if (actualValidator instanceof z.ZodTuple) { + convexValidator = convertZodTupleToConvex(actualValidator, false); + } else { + convexValidator = v.object({}); + } + break; + } + case "readonly": { + // Handle readonly schemas by accessing the inner type + if (actualValidator instanceof z.ZodReadonly) { + convexValidator = convertZodReadonlyToConvex(actualValidator); + } else { + convexValidator = v.any(); + } + break; + } + case "nan": + convexValidator = v.float64(); + break; + case "lazy": { + // Handle lazy schemas by resolving them + if (actualValidator instanceof z.ZodLazy) { + try { + const resolvedSchema = actualValidator.def?.getter?.(); + if (resolvedSchema && resolvedSchema instanceof z.ZodType) { + convexValidator = zodToConvex(resolvedSchema); + } else { + convexValidator = v.any(); + } + } catch { + // If resolution fails, fall back to 'any' + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + break; + } + case "any": + // Handle z.any() directly + convexValidator = v.any(); + break; + case "unknown": + // Handle z.unknown() as any + convexValidator = v.any(); + break; + default: + // Fallback to instance checks for any types not covered by def.type + if (actualValidator instanceof z.ZodString) { + convexValidator = v.string(); + } else if (actualValidator instanceof z.ZodNumber) { + convexValidator = v.float64(); + } else if (actualValidator instanceof z.ZodBigInt) { + convexValidator = v.int64(); + } else if (actualValidator instanceof z.ZodBoolean) { + convexValidator = v.boolean(); + } else if (actualValidator instanceof z.ZodDate) { + convexValidator = v.float64(); + } else if (actualValidator instanceof z.ZodNull) { + convexValidator = v.null(); + } else if (actualValidator instanceof z.ZodNaN) { + convexValidator = v.float64(); + } else if (actualValidator instanceof z.ZodTuple) { + convexValidator = convertZodTupleToConvex(actualValidator, true); + } else if (actualValidator instanceof z.ZodReadonly) { + convexValidator = convertZodReadonlyToConvex(actualValidator); + } else if (actualValidator instanceof z.ZodTransform) { + const innerType = actualValidator.safeParse; + if (innerType && innerType instanceof z.ZodType) { + convexValidator = zodToConvex(innerType); + } else { + convexValidator = v.any(); + } + } else { + convexValidator = v.any(); + } + break; + } + } + + // For optional fields, create a union with null instead of using v.optional() + // This matches the expected behavior where optional Zod types become unions + const finalValidator = isOptional + ? v.union(convexValidator, v.null()) + : convexValidator; + + // Add metadata if there's a default value + if ( + hasDefault && + typeof finalValidator === "object" && + finalValidator !== null + ) { + (finalValidator as any)._zodDefault = defaultValue; + } + + return finalValidator as ConvexValidatorFromZod; +} + +function zodOutputToConvexInternal( + zodValidator: Z, +): ConvexValidatorFromZodOutput { + // For output types, we need to consider transformations + if (zodValidator instanceof z.ZodTransform) { + // Check if this is a branded type (which doesn't change the runtime type) + const metadata = registryHelpers.getMetadata(zodValidator); + if (metadata?.brand && metadata?.originalSchema) { + // For branded types created by our zBrand function, use the original schema + // and run it through our main conversion logic! + return zodToConvexInternal( + metadata.originalSchema, + ) as ConvexValidatorFromZodOutput; + } + // For non-branded transforms, we can't easily determine the output type in v4 + // Use VAny as a safe fallback for transformed types + return v.any() as ConvexValidatorFromZodOutput; + } + + // For non-transformed types, use the regular conversion + return zodToConvexInternal(zodValidator) as ConvexValidatorFromZodOutput< + Z, + "required" + >; +} + +// Helper type to convert optional types to union with undefined for container elements +// This ensures we never produce VOptional which has "optional" constraint +type ConvexValidatorFromZodRequired = + Z extends z.ZodOptional + ? VUnion< + z.infer | null, + [ConvexValidatorFromZodBase, VNull<"required">], + "required" + > + : ConvexValidatorFromZodBase; + +// Base type mapper that never produces VOptional +type ConvexValidatorFromZodBase = Z extends z.ZodString + ? VString, "required"> + : Z extends z.ZodBase64 + ? VBytes, "required"> // Base64 strings map to VBytes + : Z extends z.ZodNumber + ? VFloat64, "required"> + : Z extends z.ZodDate + ? VFloat64 + : Z extends z.ZodBigInt + ? VInt64, "required"> + : Z extends z.ZodBoolean + ? VBoolean, "required"> + : Z extends z.ZodNull + ? VNull + : Z extends z.ZodNaN + ? VFloat64 + : Z extends z.ZodArray + ? T extends z.ZodType + ? VArray< + z.infer, + ConvexValidatorFromZodRequired, + "required" + > + : VArray, VAny<"required">, "required"> + : Z extends z.ZodObject + ? VObject< + z.infer, + ConvexValidatorFromZodFieldsAuto, + "required", + string + > + : Z extends z.ZodUnion + ? T extends readonly [ + z.ZodType, + z.ZodType, + ...z.ZodType[], + ] + ? VUnion< + z.infer, + [ + ConvexValidatorFromZodRequired, + ConvexValidatorFromZodRequired, + ...{ + [K in keyof T]: K extends "0" | "1" + ? never + : K extends keyof T + ? ConvexValidatorFromZodRequired + : never; + }[keyof T & number][], + ], + "required" + > + : never + : Z extends z.ZodLiteral + ? VLiteral + : Z extends z.ZodEnum + ? T extends readonly [string, ...string[]] + ? T["length"] extends 1 + ? VLiteral + : T["length"] extends 2 + ? VUnion< + T[number], + [ + VLiteral, + VLiteral, + ], + "required" + > + : VUnion< + T[number], + [ + VLiteral, + VLiteral, + ...{ + [K in keyof T]: K extends "0" | "1" + ? never + : K extends keyof T + ? VLiteral + : never; + }[keyof T & number][], + ], + "required" + > + : T extends Record + ? VUnion< + T[keyof T], + Array>, + "required" + > + : never + : Z extends z.ZodRecord + ? K extends z.ZodString + ? VRecord< + Record< + string, + ConvexValidatorFromZodRequired< + V & z.ZodType + >["type"] + >, + VString, + ConvexValidatorFromZodRequired, + "required", + string + > // ✅ Fixed: Use proper Record type + : K extends z.ZodUnion + ? VRecord< + Record, + VAny<"required">, + ConvexValidatorFromZodRequired< + V & z.ZodType + >, + "required", + string + > // Union keys become any key validator + : never + : Z extends z.ZodNullable + ? Inner extends z.ZodOptional + ? // Handle nullable(optional(T)) as optional(union(T, null)) + VOptional< + VUnion< + | ConvexValidatorFromZodBase< + InnerInner & z.ZodType + >["type"] + | null, + [ + ConvexValidatorFromZodBase< + InnerInner & z.ZodType + >, + VNull<"required">, + ], + "required", + ConvexValidatorFromZodBase< + InnerInner & z.ZodType + >["fieldPaths"] + > + > + : // Regular nullable + VUnion< + | ConvexValidatorFromZodBase< + Inner & z.ZodType + >["type"] + | null, + [ + ConvexValidatorFromZodBase< + Inner & z.ZodType + >, + VNull<"required">, + ], + "required", + ConvexValidatorFromZodBase< + Inner & z.ZodType + >["fieldPaths"] + > + : Z extends z.ZodTuple + ? Items extends readonly z.ZodType[] + ? VObject< + Record, + { + [K in keyof Items as K extends number + ? `_${K}` + : never]: Items[K] extends z.ZodType + ? ConvexValidatorFromZodRequired< + Items[K] + > + : never; + }, + "required", + string + > + : VObject< + Record, + Record>, + "required", + string + > + : Z extends Zid + ? VId, "required"> + : Z extends z.ZodAny + ? VAny<"required"> + : Z extends z.ZodUnknown + ? VAny<"required"> + : VAny<"required">; + +// Helper for object fields that always uses "required" +type ConvexValidatorFromZodFieldsRequired = { + [K in keyof T]: T[K] extends z.ZodType + ? ConvexValidatorFromZodRequired + : VAny<"required">; +}; + +/** + * Zod Optional Field Shimming System (New in v4) + * + * This complex type system is necessary because Zod and Convex handle optional fields differently: + * + * **The Problem:** + * - Zod: `z.string().optional()` creates `string | undefined` + * - Convex: Cannot store `undefined` in documents, uses `VOptional` or `string | null` + * + * **The Solution:** + * This type chain automatically converts Zod optional fields to Convex-compatible validators: + * + * 1. **Detects optional fields**: `Z extends z.ZodOptional` + * 2. **Context-aware conversion**: + * - In "required" context: `VUnion, VNull]>` + * - In "optional" context: `VOptional>` + * 3. **Result**: Zod's `string | undefined` becomes Convex's `string | null` or `VOptional` + * + * **Why This is New:** + * The v3 helper had simpler optional field handling. v4 needs this complex shimming because: + * - More sophisticated constraint system (required/optional contexts) + * - Better type safety and error prevention + * - Automatic conversion without manual intervention + * + * **Example:** + * ```typescript + * // Input: z.object({ name: z.string().optional() }) + * // Output: VObject<{ name: string | null }, { name: VUnion }> + * ``` + * + * This prevents the runtime error: "Type 'undefined' is not assignable to type 'Value'" + */ +// Type mapping helpers - Fixed for v4 constraint system with context-aware constraints +type ConvexValidatorFromZod< + Z extends z.ZodType, + Constraint extends "required" | "optional" = "required", +> = Z extends z.ZodAny + ? VAny // Always use "required" for any types + : Z extends z.ZodUnknown + ? VAny // Always use "required" for unknown types + : Z extends z.ZodDefault + ? ConvexValidatorFromZod // Handle ZodDefault by recursing on inner type + : Z extends z.ZodOptional + ? T extends z.ZodNullable + ? // For optional(nullable(T)), we want optional(union(T, null)) + VOptional< + VUnion< + z.infer | null, + [ + ConvexValidatorFromZod, + VNull, + ], + "required" + > + > + : Constraint extends "required" + ? VUnion< + z.infer | null, + [ + ConvexValidatorFromZod, + VNull, + ], + "required" + > // In required context, use union with null + : VOptional> // In optional context, use VOptional + : Z extends z.ZodNullable + ? VUnion< + z.infer | null, + [ + ConvexValidatorFromZod, + VNull, + ], + Constraint + > + : Z extends z.ZodString + ? VString, Constraint> + : Z extends z.ZodBase64 + ? VBytes, Constraint> // Base64 strings map to VBytes + : Z extends z.ZodNumber + ? VFloat64, Constraint> + : Z extends z.ZodDate + ? VFloat64 + : Z extends z.ZodBigInt + ? VInt64, Constraint> + : Z extends z.ZodBoolean + ? VBoolean, Constraint> + : Z extends z.ZodNull + ? VNull + : Z extends z.ZodNaN + ? VFloat64 + : Z extends z.ZodArray + ? T extends z.ZodType + ? VArray< + z.infer, + ConvexValidatorFromZodRequired, // ✅ Use helper to handle optional elements correctly + Constraint // ✅ The array itself inherits the constraint + > + : VArray, VAny<"required">, Constraint> // ✅ Fixed here too + : Z extends z.ZodObject + ? VObject< + z.infer, // ✅ Type first + ConvexValidatorFromZodFields, // ✅ Always "required" for fields + Constraint, // ✅ The object itself inherits the constraint + string // ✅ FieldPaths fourth + > + : Z extends z.ZodUnion + ? T extends readonly [ + z.ZodType, + z.ZodType, + ...z.ZodType[], + ] + ? VUnion< + z.infer, + [ + ConvexValidatorFromZodRequired, // ✅ Use helper to handle optional union members correctly + ConvexValidatorFromZodRequired, // ✅ Use helper to handle optional union members correctly + ...{ + [K in keyof T]: K extends "0" | "1" + ? never + : K extends keyof T + ? ConvexValidatorFromZodRequired< + T[K] + > // ✅ Use helper to handle optional union members correctly + : never; + }[keyof T & number][], + ], + Constraint // ✅ The union itself inherits the constraint + > + : never + : Z extends z.ZodLiteral + ? VLiteral + : Z extends z.ZodEnum + ? T extends readonly [string, ...string[]] + ? T["length"] extends 1 + ? VLiteral + : T["length"] extends 2 + ? VUnion< + T[number], + [ + VLiteral, + VLiteral, + ], + Constraint + > // ✅ Always "required" for enum members + : VUnion< + T[number], + [ + VLiteral, // ✅ Always "required" for enum members + VLiteral, // ✅ Always "required" for enum members + ...{ + [K in keyof T]: K extends + | "0" + | "1" + ? never + : K extends keyof T + ? VLiteral< + T[K], + "required" + > // ✅ Always "required" for enum members + : never; + }[keyof T & number][], + ], + Constraint // ✅ The enum union itself inherits the constraint + > + : T extends Record< + string, + string | number + > + ? VUnion< + T[keyof T], + Array< + VLiteral + >, + Constraint + > + : never + : Z extends z.ZodRecord + ? K extends z.ZodString + ? V extends z.ZodAny + ? VRecord< + Record, + VAny<"required">, + ConvexValidatorFromZod< + V & z.ZodType + >, + Constraint, + string + > + : V extends z.ZodOptional + ? VRecord< + Record< + string, + ConvexValidatorFromZodRequired< + V & z.ZodType + >["type"] + >, + VString, + ConvexValidatorFromZodRequired< + V & z.ZodType + >, + Constraint, + string + > // Handle optional values specially + : VRecord< + Record< + string, + ConvexValidatorFromZod< + V & z.ZodType, + "required" + >["type"] + >, + VString, + ConvexValidatorFromZod< + V & z.ZodType, + "required" + >, + Constraint, + string + > + : K extends z.ZodUnion + ? V extends z.ZodOptional + ? VRecord< + Record, + VAny<"required">, + ConvexValidatorFromZodRequired< + V & z.ZodType + >, + Constraint, + string + > // Handle optional values specially + : VRecord< + Record, + VAny<"required">, + ConvexValidatorFromZod< + V & z.ZodType, + "required" + >, + Constraint, + string + > + : never + : Z extends z.ZodTemplateLiteral< + infer Template + > + ? VString // ✅ Map template literals to strings + : Z extends z.ZodTuple + ? Items extends readonly z.ZodType[] + ? VObject< + Record, + { + [K in keyof Items as K extends number + ? `_${K}` + : never]: Items[K] extends z.ZodType + ? ConvexValidatorFromZod< + Items[K], + "required" + > + : never; + }, + Constraint, + string + > + : VObject< + Record, + Record< + string, + VAny<"required"> + >, + Constraint, + string + > + : Z extends Zid + ? VId< + GenericId, + Constraint + > + : Z extends z.ZodTransform< + infer Input extends z.ZodType, + any + > + ? ConvexValidatorFromZod< + Input, + Constraint + > // Handle transforms by using input type + : Z extends z.ZodPipe< + infer A extends z.ZodType, + infer B extends z.ZodType + > + ? ConvexValidatorFromZod< + A, + Constraint + > // For pipes, use the input type + : Z extends z.ZodAny + ? VAny // Always use "required" for any types + : Z extends z.ZodUnknown + ? VAny // Always use "required" for unknown types + : VAny<"VALIDATION_ERROR">; // THIS LINE IS RESPONSIBLE FOR EVERYTHING BEING ASSIGNED THE 'REQUIRED' TYPE!! + +type ConvexValidatorFromZodFields< + T extends { [key: string]: any }, + Constraint extends "required" | "optional" = "required", +> = { + [K in keyof T]: T[K] extends z.ZodType + ? ConvexValidatorFromZod + : VAny<"required">; +}; + +// Auto-detect optional fields and apply appropriate constraints +type ConvexValidatorFromZodFieldsAuto = { + [K in keyof T]: T[K] extends z.ZodOptional + ? ConvexValidatorFromZod // Pass "optional" for optional fields + : T[K] extends z.ZodType + ? ConvexValidatorFromZod // Pass "required" for required fields + : VAny<"required">; +}; + +type ConvexValidatorFromZodOutput< + Z extends z.ZodType, + Constraint extends "required" | "optional" = "required", +> = + Z extends z.ZodOptional + ? VOptional> + : Z extends z.ZodTransform + ? ConvexValidatorFromZod + : ConvexValidatorFromZod; + +/** + * v4 Branded types with input/output branding + * Adds brand metadata and custom error messages for better DX + */ +export function zBrand( + schema: T, + brand: B, +) { + // Create a transform schema that includes brand information + const branded = schema.transform((val) => val as z.output & z.BRAND); + + // Store brand metadata AND the original schema for conversion + registryHelpers.setMetadata(branded, { + brand: String(brand), + originalSchema: schema, // Store the original schema so we can convert it properly + }); + + return branded; +} + +/** + * Create a bidirectional transform with explicit input/output validators + * + * This solves the core problem where transforms like z.date().transform(d => d.toISOString()) + * break bidirectional data flow because the system can't determine the reverse mapping. + * + * @param config Transform configuration + * @returns A Zod schema with proper bidirectional metadata + * + * @example + * ```ts + * // Date to ISO string transform with reverse mapping + * const dateToISO = zTransform({ + * input: z.date(), + * output: z.string(), + * forward: (date: Date) => date.toISOString(), + * reverse: (iso: string) => new Date(iso), + * transformId: 'date-to-iso' + * }); + * + * // Usage in schema + * const schema = z.object({ + * createdAt: dateToISO.optional().default(() => new Date()) + * }); + * ``` + */ +export function zTransform(config: { + /** Input validator - what Zod validates before transformation */ + input: z.ZodType; + /** Output validator - what gets stored/retrieved from Convex */ + output: z.ZodType; + /** Forward transform function (input → output) */ + forward: (input: TInput) => TOutput; + /** Reverse transform function (output → input) - required for bidirectional flow */ + reverse: (output: TOutput) => TInput; + /** Unique identifier for this transform */ + transformId: string; +}): any { + // Create the transform schema + const transformSchema = config.input.transform(config.forward); + + // Register the transform metadata + const metadata: TransformMetadata = { + inputValidator: config.input, + outputValidator: config.output, + forwardTransform: config.forward, + reverseTransform: config.reverse, + transformId: config.transformId, + isReversible: true, + }; + + transformRegistry.register(metadata); + transformRegistry.associateSchema(transformSchema, config.transformId); + + // Also store in the standard metadata for backward compatibility + registryHelpers.setMetadata(transformSchema, { + transformMetadata: metadata, + transformId: config.transformId, + isTransform: true, + }); + + return transformSchema; +} + +/** + * Create a one-way transform (forward only) + * Use this when you don't need bidirectional data flow + */ +export function zTransformOneWay(config: { + input: z.ZodType; + output: z.ZodType; + forward: (input: TInput) => TOutput; + transformId: string; +}): any { + const transformSchema = config.input.transform(config.forward); + + const metadata: TransformMetadata = { + inputValidator: config.input, + outputValidator: config.output, + forwardTransform: config.forward, + transformId: config.transformId, + isReversible: false, + }; + + transformRegistry.register(metadata); + transformRegistry.associateSchema(transformSchema, config.transformId); + + registryHelpers.setMetadata(transformSchema, { + transformMetadata: metadata, + transformId: config.transformId, + isTransform: true, + }); + + return transformSchema; +} + +// Global registry for custom validator mappings +const customValidatorRegistry = new Map< + string, + { + convexToZod: (convexValidator: GenericValidator) => z.ZodType; + zodToConvex: (zodValidator: z.ZodType) => GenericValidator; + } +>(); + +/** + * Register a custom validator mapping for bidirectional conversion + * + * @example + * ```ts + * // Register a custom email validator + * registerCustomValidator('email', { + * convexToZod: (conv) => z.string().email(), + * zodToConvex: (zod) => v.string() + * }); + * ``` + */ +export function registerCustomValidator( + key: string, + mapping: { + convexToZod: (convexValidator: GenericValidator) => z.ZodType; + zodToConvex: (zodValidator: z.ZodType) => GenericValidator; + }, +) { + customValidatorRegistry.set(key, mapping); +} + +/** + * Create a custom branded validator that maps to a specific Convex validator + * This allows users to create their own branded types that work bidirectionally + * + * Note: Branded types in TypeScript require explicit parsing to apply the brand. + * You cannot directly assign unbranded values to branded types. + * + * @example + * ```ts + * // Create a branded email type that maps to v.string() + * const zEmail = createBrandedValidator( + * z.string().email(), + * 'Email', + * () => v.string() + * ); + * + * // Create a branded positive number that maps to v.float64() + * const zPositiveNumber = createBrandedValidator( + * z.number().positive(), + * 'PositiveNumber', + * () => v.float64() + * ); + * + * // Use in schemas + * const schema = z.object({ + * userEmail: zEmail(), + * score: zPositiveNumber() + * }); + * + * // Parse data to apply brands + * const data = schema.parse({ + * userEmail: "user@example.com", + * score: 42 + * }); + * + * // TypeScript knows data.userEmail is branded as Email + * // and data.score is branded as PositiveNumber + * ``` + */ +export function createBrandedValidator< + T extends z.ZodType, + B extends string, + V extends GenericValidator, +>( + zodSchema: T, + brand: B, + convexValidatorFactory: () => V, + options?: { + convexToZodFactory?: () => z.ZodType; + registryKey?: string; + }, +) { + // Register the custom mapping if a registry key is provided + if (options?.registryKey) { + registerCustomValidator(options.registryKey, { + convexToZod: options.convexToZodFactory || (() => zodSchema), + zodToConvex: () => convexValidatorFactory(), + }); + } + + return () => { + const branded = zBrand(zodSchema, brand); + + // Store the Convex validator factory in metadata + registryHelpers.setMetadata(branded, { + brand, + originalSchema: zodSchema, + convexValidatorFactory, + isBrandedValidator: true, + registryKey: options?.registryKey, + }); + + return branded; + }; +} + +/** + * Create a parameterized branded validator (like zid for table names) + * + * @example + * ```ts + * // Create a branded ID validator similar to zid + * const zUserId = createParameterizedBrandedValidator( + * (userId: string) => z.string().regex(/^user_[a-zA-Z0-9]+$/), + * (userId: string) => `UserId_${userId}`, + * (userId: string) => v.string() + * ); + * + * // Use it + * const schema = z.object({ + * id: zUserId('admin') + * }); + * ``` + */ +export function createParameterizedBrandedValidator< + P extends string | number, + T extends z.ZodType, + V extends GenericValidator, +>( + zodSchemaFactory: (param: P) => T, + brandFactory: (param: P) => string, + convexValidatorFactory: (param: P) => V, +) { + return (param: P) => { + const zodSchema = zodSchemaFactory(param); + const brand = brandFactory(param); + const branded = zBrand(zodSchema, brand); + + // Store all the metadata including the parameter + registryHelpers.setMetadata(branded, { + brand, + originalSchema: zodSchema, + convexValidatorFactory: () => convexValidatorFactory(param), + isBrandedValidator: true, + parameter: param, + }); + + return branded; + }; +} + +/** + * v4 ZodBrandedInputAndOutput class (simplified compatibility version) + * + * A simpler implementation that works with v4 API by using transform approach. + */ +export class ZodBrandedInputAndOutput< + T extends z.ZodType, + B extends string | number | symbol, +> { + constructor( + private type: T, + private brand: B, + ) { + // Store brand metadata on the underlying type for consistency with the main zBrand function + registryHelpers.setMetadata(type, { + brand: String(brand), + originalSchema: type, + inputOutputBranded: true, + }); + } + + parse(input: any) { + const result = this.type.parse(input); + // Add brand information for debugging (non-enumerable so it doesn't interfere with data) + if (typeof result === "object" && result !== null) { + Object.defineProperty(result, "__brand", { + value: this.brand, + enumerable: false, + writable: false, + }); + } + return result as T["_output"] & z.BRAND; + } + + safeParse(input: any) { + return this.type.safeParse(input); + } + + unwrap() { + return this.type; + } + + // Provide access to the brand for debugging/introspection + getBrand(): B { + return this.brand; + } + + // Provide basic ZodType-like interface + get _def() { + return this.type._def; + } + + get _type() { + return this.type.type; + } +} + +/** + * Create a branded validator that brands both input and output types (v4 compatible) + * + * @param validator A zod validator - generally a string, number, or bigint + * @param brand A string, number, or symbol to brand the validator with + * @returns A zod validator that brands both the input and output types. + */ +export function zBrandInputOutput< + T extends z.ZodType, + B extends string | number | symbol, +>(validator: T, brand: B): ZodBrandedInputAndOutput { + return new ZodBrandedInputAndOutput(validator, brand); +} + +/** + * v4 Template literal types using the real Zod v4 API + * + * Template literals in Zod v4 can only contain: + * - String/number/boolean/null/undefined literals + * - Schemas with defined patterns: z.string(), z.number(), z.boolean(), z.literal(), z.enum(), etc. + * + * @example + * ```ts + * // Array syntax + * const emailTemplate = zTemplate(["user-", z.string(), ".", z.string(), "@example.com"]); + * + * // Template literal syntax helper (safer, validates at compile time) + * const template = zTemplate`user-${z.string()}.${z.string()}@example.com`; + * + * // Complex patterns + * const versionTemplate = zTemplate(["v", z.number(), ".", z.number(), ".", z.number()]); + * const statusTemplate = zTemplate(["status:", z.enum(["active", "inactive"]), "!"]); + * ``` + */ +export function zTemplate( + parts: Parts, +): z.ZodTemplateLiteral>; + +export function zTemplate( + strings: TemplateStringsArray, + ...schemas: ( + | z.ZodString + | z.ZodNumber + | z.ZodBigInt + | z.ZodBoolean + | z.ZodLiteral + | z.ZodEnum + )[] +): z.ZodTemplateLiteral; + +export function zTemplate( + partsOrStrings: z.core.$ZodTemplateLiteralPart[] | TemplateStringsArray, + ...schemas: ( + | z.ZodString + | z.ZodNumber + | z.ZodBigInt + | z.ZodBoolean + | z.ZodLiteral + | z.ZodEnum + )[] +): z.ZodTemplateLiteral { + // Handle template literal syntax: zTemplate`hello ${z.string()}` + if (Array.isArray(partsOrStrings) && "raw" in partsOrStrings) { + const strings = partsOrStrings as TemplateStringsArray; + const parts: z.core.$ZodTemplateLiteralPart[] = []; + + for (let i = 0; i < strings.length; i++) { + if (strings[i]) parts.push(strings[i]); + if (i < schemas.length) + parts.push(schemas[i] as z.core.$ZodTemplateLiteralPart); + } + + return z.templateLiteral(parts); + } + + // Handle array syntax: zTemplate(["hello ", z.string()]) + return z.templateLiteral(partsOrStrings as z.core.$ZodTemplateLiteralPart[]); +} + +/** + * v4 Recursive schema helper + */ +export function zRecursive( + name: string, + schema: (self: z.ZodType) => z.ZodType, +): z.ZodType { + const baseSchema: z.ZodType = z.lazy(() => schema(baseSchema)); + registryHelpers.register(name, baseSchema); + return baseSchema; +} + +/** + * v4 Type Helpers (maintaining compatibility with original) + */ + +/** + * Helper type for getting custom context from a builder + */ +export type ZCustomCtx = + Builder extends CustomBuilder< + any, + any, + infer ModCtx, + any, + infer InputCtx, + any + > + ? Overwrite + : never; + +/** + * Simple interface definition using Zod schemas + * + * @example + * ```ts + * // Define your interface + * const UserInterface = z.object({ + * email: z.string().email(), + * age: z.number().positive(), + * name: z.string() + * }); + * + * // Use it as a type + * type User = z.infer; + * + * // Create instances with full IDE type checking + * const user: User = { + * email: "test@example.com", // ✓ IDE validates email format + * age: 25, // ✓ IDE validates positive number + * name: "John" + * }; + * + * // This will show IDE errors: + * const badUser: User = { + * email: "not-an-email", // ✗ IDE error: doesn't match email + * age: -5, // ✗ IDE error: not positive + * name: "John" + * }; + * ``` + */ +export const defineInterface = z.object; + +/** + * Simple type conversion from a Convex validator to a Zod validator + */ +export type ConvexToZod = z.ZodType>; + +/** + * v4 Bidirectional Schema Builder + * + * Create schemas once and use them in both Zod and Convex contexts. + * This eliminates the need to maintain duplicate schema definitions. + * + * @example + * ```ts + * const schemas = createBidirectionalSchema({ + * user: z.object({ + * name: z.string(), + * email: z.string().email(), + * role: z.enum(["admin", "user"]) + * }), + * post: z.object({ + * title: z.string(), + * authorId: zid("users") + * }) + * }); + * + * // Use in Convex functions + * export const createUser = mutation({ + * args: schemas.convex.user, + * handler: async (ctx, args) => { ... } + * }); + * + * // Use in Zod validation + * const validatedUser = schemas.zod.user.parse(userData); + * + * // Pick subset of schemas + * const userSchemas = schemas.pick("user"); + * + * // Extend with new schemas + * const extendedSchemas = schemas.extend({ + * comment: z.object({ content: z.string() }) + * }); + * ``` + */ +export function createBidirectionalSchema>( + schemas: T, +): { + /** Original Zod schemas */ + zod: T; + /** Converted Convex validators */ + convex: { [K in keyof T]: ConvexValidatorFromZod }; + /** Get all schema keys */ + keys: () => (keyof T)[]; + /** Pick subset of schemas */ + pick: ( + ...keys: K[] + ) => { + zod: Pick; + convex: Pick< + { [P in keyof T]: ConvexValidatorFromZod }, + K + >; + }; + /** Extend with additional schemas */ + extend: >( + extension: E, + ) => ReturnType>; +} { + // Convert all Zod schemas to Convex validators + const convexSchemas = {} as { + [K in keyof T]: ConvexValidatorFromZod; + }; + + for (const [key, zodSchema] of Object.entries(schemas)) { + convexSchemas[key as keyof T] = zodToConvex( + zodSchema as z.ZodType, + ) as ConvexValidatorFromZod; + } + + return { + zod: schemas, + convex: convexSchemas, + + keys: () => Object.keys(schemas) as (keyof T)[], + + pick: (...keys) => { + const pickedZod = {} as Pick; + const pickedConvex = {} as Pick< + { [P in keyof T]: ConvexValidatorFromZod }, + (typeof keys)[number] + >; + + for (const key of keys) { + pickedZod[key] = schemas[key]; + pickedConvex[key] = convexSchemas[key]; + } + + return { zod: pickedZod, convex: pickedConvex }; + }, + + extend: (extension) => + createBidirectionalSchema({ ...schemas, ...extension }), + }; +} + +/** + * v4 Testing and Validation Utilities + * + * Comprehensive utilities for testing schema conversions and validation consistency. + * Essential for ensuring your Zod schemas convert correctly to Convex validators. + * + * @example + * ```ts + * const userSchema = z.object({ + * name: z.string(), + * email: z.string().email(), + * age: z.number().min(0) + * }); + * + * // Test that valid and invalid values behave consistently + * const results = convexZodTestUtils.testValueConsistency(userSchema, { + * valid: [ + * { name: "John", email: "john@example.com", age: 25 }, + * { name: "Jane", email: "jane@test.org", age: 30 } + * ], + * invalid: [ + * { name: "John", email: "invalid-email", age: 25 }, + * { name: "John", email: "john@example.com", age: -5 } + * ] + * }); + * + * console.log(`${results.passed} tests passed, ${results.failed} failed`); + * + * // Generate test data for a schema + * const testData = convexZodTestUtils.generateTestData(userSchema); + * console.log(testData); // { name: "test_string", email: "test@example.com", age: 42 } + * + * // Test conversion round-trip + * convexZodTestUtils.testConversionRoundTrip(userSchema); + * ``` + */ +export const convexZodTestUtils = { + /** + * Test that a value validates consistently between Zod and converted Convex validator. + * This helps ensure that your schema conversions maintain the same validation behavior. + * + * @param zodSchema The Zod schema to test + * @param testValues Object with arrays of valid and invalid test values + * @param options Optional settings for the test + * @returns Test results with pass/fail counts and any errors found + */ + testValueConsistency: ( + zodSchema: z.ZodType, + testValues: { + valid: T[]; + invalid: any[]; + }, + options?: { + verbose?: boolean; + throwOnFailure?: boolean; + }, + ) => { + const results = { + passed: 0, + failed: 0, + errors: [] as Array<{ + type: + | "valid_value_failed_zod" + | "invalid_value_passed_zod" + | "conversion_error"; + value: any; + error?: any; + details?: string; + }>, + }; + + let convexValidator: GenericValidator; + + // Test conversion doesn't throw + try { + convexValidator = zodToConvex(zodSchema); + } catch (error) { + results.errors.push({ + type: "conversion_error", + value: "N/A", + error, + details: "Failed to convert Zod schema to Convex validator", + }); + + if (options?.throwOnFailure) { + throw new Error(`Schema conversion failed: ${error}`); + } + + return results; + } + + // Test valid values should pass Zod validation + for (const value of testValues.valid) { + const zodResult = zodSchema.safeParse(value); + if (!zodResult.success) { + results.failed++; + results.errors.push({ + type: "valid_value_failed_zod", + value, + error: zodResult.error, + details: `Expected valid value to pass Zod validation`, + }); + + if (options?.verbose) { + console.warn("Valid value failed Zod validation:", { + value, + error: zodResult.error, + }); + } + } else { + results.passed++; + } + } + + // Test invalid values should fail Zod validation + for (const value of testValues.invalid) { + const zodResult = zodSchema.safeParse(value); + if (zodResult.success) { + results.failed++; + results.errors.push({ + type: "invalid_value_passed_zod", + value, + details: `Expected invalid value to fail Zod validation`, + }); + + if (options?.verbose) { + console.warn("Invalid value passed Zod validation:", { value }); + } + } else { + results.passed++; + } + } + + if (options?.verbose) { + console.log("Value consistency test results:", { + passed: results.passed, + failed: results.failed, + totalTests: testValues.valid.length + testValues.invalid.length, + convexValidator: convexValidator?.kind || "unknown", + }); + } + + if (options?.throwOnFailure && results.failed > 0) { + throw new Error(`${results.failed} validation consistency tests failed`); + } + + return results; + }, + + /** + * Generate sample test data for a Zod schema. + * Useful for creating test cases or example data. + * + * @param schema The Zod schema to generate data for + * @returns Generated test data that should validate against the schema + */ + generateTestData: (schema: z.ZodType): any => { + // Handle v4 email validator specifically + if (schema.constructor && schema.constructor.name === "ZodEmail") { + return "test@example.com"; + } + + if (schema instanceof z.ZodString) { + // For strings, try common patterns and return the first one that validates + const testPatterns = [ + "test@example.com", // Email + "https://example.com", // URL + "2023-12-25", // Date + "2023-12-25T10:30:00Z", // DateTime + "TestString123", // Min length with chars/numbers + "test_string_value", // Generic fallback + ]; + + // Find the first pattern that works + for (const pattern of testPatterns) { + const result = schema.safeParse(pattern); + if (result.success) { + return pattern; + } + } + + // Final fallback + return "test_string_value"; + } + if (schema instanceof z.ZodNumber) { + // For numbers, use a safe middle value that works with most constraints + return 42; + } + if (schema instanceof z.ZodBigInt) { + return BigInt(123); + } + if (schema instanceof z.ZodBoolean) { + return true; + } + if (schema instanceof z.ZodNull) { + return null; + } + if (schema instanceof z.ZodArray) { + const elementData = convexZodTestUtils.generateTestData( + schema.element as z.ZodType, + ); + return [elementData, elementData]; // Generate array with 2 elements + } + if (schema instanceof z.ZodObject) { + const obj: any = {}; + const shape = schema.shape; + for (const [key, fieldSchema] of Object.entries(shape)) { + obj[key] = convexZodTestUtils.generateTestData( + fieldSchema as z.ZodType, + ); + } + return obj; + } + if (schema instanceof z.ZodOptional) { + // 50% chance of undefined, 50% chance of generated value + return Math.random() > 0.5 + ? undefined + : convexZodTestUtils.generateTestData(schema.unwrap() as z.ZodType); + } + if (schema instanceof z.ZodNullable) { + // 25% chance of null, 75% chance of generated value + return Math.random() > 0.75 + ? null + : convexZodTestUtils.generateTestData(schema.unwrap() as z.ZodType); + } + if (schema instanceof z.ZodUnion) { + const options = schema.options as z.ZodType[]; + if (options.length > 0) { + // Pick random option from union + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion + const randomOption = + options[Math.floor(Math.random() * options.length)]!; + return convexZodTestUtils.generateTestData(randomOption as z.ZodType); + } + } + if (schema instanceof z.ZodLiteral) { + return schema.value; + } + if (schema instanceof z.ZodEnum) { + const options = schema.options; + if (options && options.length > 0) { + // Pick random enum value + return options[Math.floor(Math.random() * options.length)]; + } + } + if (schema instanceof z.ZodRecord) { + return { + key1: convexZodTestUtils.generateTestData( + schema.valueType as z.ZodType, + ), + key2: convexZodTestUtils.generateTestData( + schema.valueType as z.ZodType, + ), + }; + } + + // Handle Zid type + if (isZid(schema)) { + const metadata = registryHelpers.getMetadata(schema); + const tableName = metadata?.tableName || "table"; + // Generate a realistic mock Convex ID (doesn't encode table name, but varies per table for debugging) + const tableHash = tableName.slice(0, 4).padEnd(4, "x"); // Use first 4 chars of table name + return `k${tableHash}${"t".repeat(26)}${Math.floor(Math.random() * 10)}`; // 32-char ID with table prefix for debugging + } + + // Default fallback + return "unknown_type_value"; + }, + + /** + * Test that converting through the bidirectional schema system preserves constraints. + * This demonstrates proper round-trip conversion using createBidirectionalSchema. + * + * @param zodSchema Original Zod schema + * @param testValue Optional test value, will generate one if not provided + * @returns True if bidirectional conversion preserves behavior, false otherwise + */ + testConversionRoundTrip: ( + zodSchema: z.ZodType, + testValue?: T, + ): { + success: boolean; + originalValid: boolean; + roundTripValid: boolean; + error?: any; + } => { + try { + // Generate test value if not provided + const value = testValue ?? convexZodTestUtils.generateTestData(zodSchema); + + // Test original schema + const originalResult = zodSchema.safeParse(value); + + // Use the bidirectional schema system to preserve constraints + const bidirectionalSchemas = createBidirectionalSchema({ + testSchema: zodSchema, + }); + + // The round-trip schema should be the same as the original + const roundTripZodSchema = bidirectionalSchemas.zod.testSchema; + + // Test round-trip schema with the same value + const roundTripResult = roundTripZodSchema.safeParse(value); + + // With bidirectional schemas, both should behave identically + const success = originalResult.success === roundTripResult.success; + + return { + success, + originalValid: originalResult.success, + roundTripValid: roundTripResult.success, + error: success + ? undefined + : { + original: originalResult.success + ? "passed" + : originalResult.error, + roundTrip: roundTripResult.success + ? "passed" + : roundTripResult.error, + }, + }; + } catch (error) { + return { + success: false, + originalValid: false, + roundTripValid: false, + error: `Conversion round-trip failed: ${error}`, + }; + } + }, + + /** + * Validate that a bidirectional schema object works correctly. + * Tests both the Zod and Convex versions for consistency. + * + * @param schemas Bidirectional schema object from createBidirectionalSchema + * @param testData Optional test data for each schema, will generate if not provided + * @returns Validation results for each schema + */ + validateBidirectionalSchemas: >( + schemas: ReturnType>, + testData?: Partial<{ [K in keyof T]: z.infer }>, + ) => { + const results: Record< + string, + { + zodValid: boolean; + hasConvexValidator: boolean; + testValue: any; + error?: any; + } + > = {}; + + for (const key of schemas.keys()) { + const zodSchema = schemas.zod[key]; + const convexValidator = schemas.convex[key]; + + // TypeScript guard: ensure zodSchema exists (it should, but TypeScript doesn't know) + if (!zodSchema) { + results[key as string] = { + zodValid: false, + hasConvexValidator: convexValidator !== undefined, + testValue: null, + error: `Schema not found for key: ${String(key)}`, + }; + continue; + } + + // Generate or use provided test data + const testValue = + testData?.[key] ?? convexZodTestUtils.generateTestData(zodSchema); + + try { + const zodResult = zodSchema.safeParse(testValue); + + results[key as string] = { + zodValid: zodResult.success, + hasConvexValidator: convexValidator !== undefined, + testValue, + error: zodResult.success ? undefined : zodResult.error, + }; + } catch (error) { + results[key as string] = { + zodValid: false, + hasConvexValidator: convexValidator !== undefined, + testValue, + error, + }; + } + } + + return results; + }, +}; diff --git a/src/components/ZodTestPage.tsx b/src/components/ZodTestPage.tsx new file mode 100644 index 00000000..4eed4828 --- /dev/null +++ b/src/components/ZodTestPage.tsx @@ -0,0 +1,955 @@ +import { useState } from "react"; +import { useMutation, useQuery, useConvex } from "convex/react"; +import { api } from "../../convex/_generated/api.js"; +import { + testRecordSchema, + settingsValueSchema, + scoresValueSchema, +} from "../../convex/zodTestSchema.js"; +import type { GenericId } from "convex/values"; + +export function ZodTestPage() { + const convex = useConvex(); + const records = useQuery(api.zodTest.list); + const createRecord = useMutation(api.zodTest.create); + const createMinimalRecord = useMutation(api.zodTest.createMinimal); + const updateRecord = useMutation(api.zodTest.update); + const deleteRecord = useMutation(api.zodTest.remove); + const testRecordUpdateMutation = useMutation(api.zodTest.testRecordUpdate); + const updateRecordField = useMutation(api.zodTest.updateRecordField); + const testAdvancedFeatures = useMutation(api.zodTest.testAdvancedFeatures); + + const [selectedRecord, setSelectedRecord] = + useState | null>(null); + const [newRecordName, setNewRecordName] = useState(""); + const [updateKey, setUpdateKey] = useState(""); + const [updateValue, setUpdateValue] = useState(""); + const [showRoundtripTest, setShowRoundtripTest] = useState(false); + + // Record field update state + const [recordType, setRecordType] = useState< + "settings" | "scores" | "metadata" + >("settings"); + const [recordFieldKey, setRecordFieldKey] = useState(""); + const [recordFieldValue, setRecordFieldValue] = useState(""); + + // Advanced features state + const [advancedData, setAdvancedData] = useState({ + email: "", + rating: "", + completionRate: "", + phone: "", + slug: "", + isActive: "", + displayName: "", + bio: "", + socialLinks: [] as { + platform: "twitter" | "github" | "linkedin"; + username: string; + }[], + }); + + // Brand test results state + const [brandTestResults, setBrandTestResults] = useState<{ + emailValue: string; + hasBrandAtRuntime: boolean; + reparseSuccess: boolean; + transformsReapplied: boolean; + reparseError?: string; + reparsedEmail?: string; + } | null>(null); + + // Use a stable timestamp to avoid infinite re-renders + const [stableTimestamp] = useState(() => Date.now()); + + const roundtripResult = useQuery( + api.zodTest.testRoundtrip, + showRoundtripTest + ? { + testData: { + name: "Test Record", + age: 30, + settings: { theme: 1, fontSize: 16 }, + scores: { math: 95, science: null }, + profile: { + bio: "Custom bio", + avatar: null, + preferences: { darkMode: true }, + }, + tags: ["test", "demo"], + status: "active", + coordinates: [10, 20], + metadata: { + customField: { + value: "test value", + timestamp: stableTimestamp, + flags: { important: true }, + }, + }, + }, + } + : "skip", + ); + + const selectedRecordData = useQuery( + api.zodTest.get, + selectedRecord ? { id: selectedRecord } : "skip", + ); + + const handleCreateFull = async () => { + try { + // Parse on client to apply transforms, then send to server + const rawData = { + name: newRecordName || "Test Record", + age: 30, + settings: { theme: 1, fontSize: 16 }, + scores: { math: 95, science: null }, + profile: { + bio: "Custom bio", + avatar: null, + preferences: { darkMode: true }, + }, + tags: ["test", "demo"], + status: "active" as const, + coordinates: [10, 20] as [number, number], + metadata: { + customField: { + value: "test value", + timestamp: Date.now(), // This is OK in event handler + flags: { important: true }, + }, + }, + }; + + // Send raw data - let server handle parsing and transforms + const id = await createRecord({ data: rawData }); + setSelectedRecord(id); + } catch (error) { + if (error instanceof Error) { + alert(`Validation error: ${error.message}`); + } + console.error("Create error:", error); + } + }; + + const handleCreateMinimal = async () => { + try { + // Use pick to validate only the name field + const minimalSchema = testRecordSchema.pick({ name: true }); + const validatedData = minimalSchema.parse({ + name: newRecordName || "Minimal Record", + }); + + const id = await createMinimalRecord(validatedData); + setSelectedRecord(id); + } catch (error) { + if (error instanceof Error) { + alert(`Validation error: ${error.message}`); + } + console.error("Create minimal error:", error); + } + }; + + const handleTestUpdate = async () => { + if (!selectedRecord) return; + + try { + // Use the imported value schemas directly + const settingValue = updateValue + ? settingsValueSchema.parse(Number(updateValue)) + : null; + const scoreValue = updateValue + ? scoresValueSchema.parse( + updateValue === "null" ? null : Number(updateValue), + ) + : null; + + await testRecordUpdateMutation({ + id: selectedRecord, + settingKey: updateKey || "testSetting", + settingValue: settingValue, + scoreKey: updateKey || "testScore", + scoreValue: scoreValue, + }); + } catch (error) { + if (error instanceof Error) { + alert(`Validation error: ${error.message}`); + } + console.error("Update error:", error); + } + }; + + return ( +
+

Zod to Convex Test Page

+
+

Create New Record

+ setNewRecordName(e.target.value)} + style={{ marginRight: "10px" }} + /> + + +
+
+

Records List

+ {records?.map( + (record: { + _id: GenericId<"zodTest">; + name: string; + _creationTime: number; + }) => ( +
setSelectedRecord(record._id)} + > + {record.name} (ID: {record._id}) +
+ ), + )} +
+ {selectedRecord && selectedRecordData && ( +
+

Selected Record Details

+ 
+            {JSON.stringify(selectedRecordData, null, 2)}
+
+ +
+

Test Record Update

+ setUpdateKey(e.target.value)} + style={{ marginRight: "10px" }} + /> + setUpdateValue(e.target.value)} + style={{ marginRight: "10px" }} + /> + + +
+ +
+

Test Record Field Updates

+

+ Update individual fields in Records without overwriting the entire + record +

+ + setRecordFieldKey(e.target.value)} + style={{ marginRight: "10px" }} + /> + setRecordFieldValue(e.target.value)} + style={{ marginRight: "10px" }} + /> + + + {selectedRecordData && ( +
+ Current {recordType}: + 
+                  {JSON.stringify(selectedRecordData[recordType], null, 2)}
+
+
+ )} +
+ +
+

Test Advanced Zod v4 Features

+

+ Test transforms, refinements, and branded types +

+ +
+
+ + + setAdvancedData({ + ...advancedData, + email: e.target.value, + }) + } + style={{ width: "100%" }} + /> +
+ +
+ + + setAdvancedData({ + ...advancedData, + rating: e.target.value, + }) + } + style={{ width: "100%" }} + /> +
+ +
+ + + setAdvancedData({ + ...advancedData, + completionRate: e.target.value, + }) + } + style={{ width: "100%" }} + /> +
+ +
+ + + setAdvancedData({ + ...advancedData, + phone: e.target.value, + }) + } + style={{ width: "100%" }} + /> +
+ +
+ + + setAdvancedData({ ...advancedData, slug: e.target.value }) + } + style={{ width: "100%" }} + /> +
+ +
+ + + setAdvancedData({ + ...advancedData, + isActive: e.target.value, + }) + } + style={{ width: "100%" }} + /> +
+ +
+ + + setAdvancedData({ + ...advancedData, + displayName: e.target.value, + }) + } + style={{ width: "100%" }} + /> +
+ +
+ +