zodvex 0.2.0 → 0.2.1

package/README.md

@@ -226,12 +226,14 @@ Handlers should return domain values shaped by your `returns` schema. zodvex val
 
 ```ts
 import { z } from "zod";
-import { zQuery, zodTableWithDocs, returnsAs } from "zodvex";
+import { zQuery, zodTable, returnsAs } from "zodvex";
 import { query } from "./_generated/server";
 
-// Table with doc helpers (use zodTableWithDocs for .docArray)
-const UserSchema = z.object({ name: z.string(), createdAt: z.date() });
-export const Users = zodTableWithDocs("users", UserSchema);
+// Table with doc helpers
+export const Users = zodTable("users", {
+  name: z.string(),
+  createdAt: z.date()
+});
 
 // 1) Return full docs, strongly typed
 export const listUsers = zQuery(
@@ -326,9 +328,10 @@ const postShape = {
 export const Posts = zodTable("posts", postShape);
 
 // Access properties
-Posts.table; // → Table definition for defineSchema
-Posts.shape; // → Original plain object shape
-Posts.zDoc;  // → ZodObject with _id and _creationTime system fields
+Posts.table;    // → Table definition for defineSchema
+Posts.shape;    // → Original plain object shape
+Posts.zDoc;     // → ZodObject with _id and _creationTime system fields
+Posts.docArray; // → z.array(zDoc) for return type validation
 
 // Use in schema.ts
 export default defineSchema({
@@ -336,6 +339,14 @@ export default defineSchema({
     .index("by_author", ["authorId"])
     .index("by_published", ["published"]),
 });
+
+// Use docArray for return types
+export const listPosts = zQuery(
+  query,
+  {},
+  async (ctx) => ctx.db.query("posts").collect(),
+  { returns: Posts.docArray }
+);
 ```
 
 #### Working with Large Schemas
@@ -370,52 +381,87 @@ const zClerkFields = z.object(pickShape(users, ["email", "firstName", "lastName"
 // Use zClerkFields in function wrappers or validators
 ```
 
-#### Alternative: zodTableWithDocs
+## 🔧 Advanced Usage
+
+### Builder Pattern for Reusable Function Creators
 
-If you prefer working with `z.object()` directly, use `zodTableWithDocs`:
+For projects with many functions, create reusable builders instead of repeating the base builder.
+Builders use Convex's native `{ args, handler, returns }` object syntax:
 
 ```ts
-const PostSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  authorId: zid("users"),
+import { query, mutation } from "./_generated/server";
+import { zQueryBuilder, zMutationBuilder } from "zodvex";
+
+// Create reusable builders
+export const zq = zQueryBuilder(query);
+export const zm = zMutationBuilder(mutation);
+
+// Use them with Convex-style object syntax
+export const getUser = zq({
+  args: { id: z.string() },
+  handler: async (ctx, { id }) => {
+    return ctx.db.get(id);
+  }
 });
 
-export const Posts = zodTableWithDocs("posts", PostSchema);
-
-// Different properties available:
-Posts.table;      // → Table definition
-Posts.schema;     // → Original z.object() schema
-Posts.docSchema;  // → Schema with _id and _creationTime (Dates → numbers)
-Posts.docArray;   // → z.array(docSchema) for return types
+export const updateUser = zm({
+  args: { id: z.string(), name: z.string() },
+  handler: async (ctx, { id, name }) => {
+    return ctx.db.patch(id, { name });
+  }
+});
 ```
 
-## 🔧 Advanced Usage
+### Custom Context with Middleware
 
-### Custom Validators with Zod
+Use custom builders to inject auth, permissions, or other context into your functions.
+zodvex provides `customCtx` (re-exported from convex-helpers) for convenience:
 
 ```ts
-import { z } from "zod";
-import { zCustomQuery } from "zodvex";
-import { customQuery } from "convex-helpers/server/customFunctions";
-
-// Use with custom function builders
-export const authenticatedQuery = zCustomQuery(
-  customQuery(query, {
-    args: { sessionId: v.string() },
-    input: async (ctx, { sessionId }) => {
-      const user = await getUser(ctx, sessionId);
-      return { user };
-    },
-  }),
-  { postId: z.string() },
-  async (ctx, { postId }) => {
-    // ctx.user is available from custom input
-    return ctx.db.get(postId);
-  },
+import { query, mutation } from "./_generated/server";
+import { zCustomQueryBuilder, zCustomMutationBuilder, customCtx } from "zodvex";
+
+// Create authenticated query builder
+export const authQuery = zCustomQueryBuilder(
+  query,
+  customCtx(async (ctx) => {
+    const user = await getUserOrThrow(ctx);
+    return { user };
+  })
+);
+
+// Create authenticated mutation builder
+export const authMutation = zCustomMutationBuilder(
+  mutation,
+  customCtx(async (ctx) => {
+    const user = await getUserOrThrow(ctx);
+    return { user };
+  })
 );
+
+// Use them with automatic type-safe context
+export const getProfile = authQuery({
+  args: {},
+  handler: async (ctx) => {
+    // ctx.user is automatically available and typed!
+    return ctx.db.query("users").filter(q => q.eq(q.field("_id"), ctx.user._id)).first();
+  }
+});
+
+export const updateProfile = authMutation({
+  args: { name: z.string() },
+  handler: async (ctx, { name }) => {
+    // ctx.user is automatically available and typed!
+    return ctx.db.patch(ctx.user._id, { name });
+  }
+});
 ```
 
+**Available custom builders:**
+- `zCustomQueryBuilder` - for queries with custom context
+- `zCustomMutationBuilder` - for mutations with custom context
+- `zCustomActionBuilder` - for actions with custom context
+
 ### Working with Dates
 
 ```ts

package/dist/index.d.mts

@@ -1,21 +1,12 @@
-import { z } from 'zod';
+import { Customization } from 'convex-helpers/server/customFunctions';
+export { customCtx } from 'convex-helpers/server/customFunctions';
+import * as convex_server from 'convex/server';
+import { RegisteredQuery, RegisteredMutation, RegisteredAction, DefaultFunctionArgs, FunctionVisibility, ArgsArrayToObject, GenericDataModel, QueryBuilder, GenericQueryCtx } from 'convex/server';
 import * as convex_values from 'convex/values';
 import { VAny, VOptional, VUnion, VId, GenericId, VString, VFloat64, VInt64, VBoolean, VNull, VArray, VObject, VLiteral, VRecord, PropertyValidators } from 'convex/values';
-import * as convex_server from 'convex/server';
-import { RegisteredQuery, RegisteredMutation, RegisteredAction, DefaultFunctionArgs, FunctionVisibility, ArgsArrayToObject, GenericDataModel, QueryBuilder, GenericQueryCtx, MutationBuilder, GenericMutationCtx, ActionBuilder, GenericActionCtx } from 'convex/server';
-import { Customization } from 'convex-helpers/server/customFunctions';
+import { z } from 'zod';
 import * as convex_helpers from 'convex-helpers';
 
-type ConvexCodec<T> = {
-    validator: any;
-    encode: (value: T) => any;
-    decode: (value: any) => T;
-    pick: <K extends keyof T>(keys: K[]) => ConvexCodec<Pick<T, K>>;
-};
-declare function convexCodec<T>(schema: z.ZodType<T>): ConvexCodec<T>;
-declare function toConvexJS(schema?: any, value?: any): any;
-declare function fromConvexJS(value: any, schema: any): any;
-
 type IsZid<T> = T extends {
     _tableName: infer _TableName extends string;
 } ? true : false;
@@ -147,14 +138,189 @@ type CustomBuilder<FuncType extends 'query' | 'mutation' | 'action', CustomArgsV
         (ctx: Overwrite<InputCtx, CustomCtx>, ...args: ArgsForHandlerType<ArgsOutput<ArgsValidator>, CustomMadeArgs>): ReturnValue;
     }): Registration<FuncType, Visibility, ArgsArrayToObject<CustomArgsValidator extends Record<string, never> ? ArgsInput<ArgsValidator> : ArgsInput<ArgsValidator> extends [infer A] ? [Expand<A & convex_values.ObjectType<CustomArgsValidator>>] : [convex_values.ObjectType<CustomArgsValidator>]>, ReturnsZodValidator extends void ? ReturnValue : ReturnValueOutput<ReturnsZodValidator>>;
 };
+declare function customFnBuilder<Ctx extends Record<string, any>, Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, ExtraArgs extends Record<string, any> = Record<string, any>>(builder: Builder, customization: Customization<Ctx, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): (fn: any) => any;
 declare function zCustomQuery<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, DataModel extends GenericDataModel, ExtraArgs extends Record<string, any> = Record<string, any>>(query: QueryBuilder<DataModel, Visibility>, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'query', CustomArgsValidator, CustomCtx, CustomMadeArgs, GenericQueryCtx<DataModel>, Visibility, ExtraArgs>;
 declare function zCustomQuery<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility, ExtraArgs extends Record<string, any> = Record<string, any>>(query: QueryBuilder<any, Visibility>, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'query', CustomArgsValidator, CustomCtx, CustomMadeArgs, any, Visibility, ExtraArgs>;
-declare function zStrictQuery<Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility = ExtractVisibility<Builder>, ExtraArgs extends Record<string, any> = Record<string, any>>(query: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'query', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
-declare function zStrictMutation<Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility = ExtractVisibility<Builder>, ExtraArgs extends Record<string, any> = Record<string, any>>(mutation: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'mutation', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
-declare function zStrictAction<Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility = ExtractVisibility<Builder>, ExtraArgs extends Record<string, any> = Record<string, any>>(action: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'action', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
 declare function zCustomMutation<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Builder extends (fn: any) => any, Visibility extends FunctionVisibility = 'public', ExtraArgs extends Record<string, any> = Record<string, any>>(mutation: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'mutation', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
 declare function zCustomAction<CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Builder extends (fn: any) => any, Visibility extends FunctionVisibility = 'public', ExtraArgs extends Record<string, any> = Record<string, any>>(action: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'action', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
 
+/**
+ * Creates a reusable query builder from a Convex query builder.
+ * Returns a builder function that accepts Convex-style config objects with args, handler, and returns.
+ *
+ * @example
+ * ```ts
+ * import { query } from './_generated/server'
+ * import { zQueryBuilder } from 'zodvex'
+ *
+ * // Create a reusable builder
+ * export const zq = zQueryBuilder(query)
+ *
+ * // Use it with Convex-style object syntax
+ * export const getUser = zq({
+ *   args: { id: z.string() },
+ *   handler: async (ctx, { id }) => {
+ *     return ctx.db.get(id)
+ *   }
+ * })
+ * ```
+ */
+declare function zQueryBuilder<Builder extends (fn: any) => any>(builder: Builder): <A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(config: {
+    args?: A;
+    handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A extends undefined ? Record<string, never> : A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>;
+    returns?: R;
+}) => RegisteredQuery<Visibility, ZodToConvexArgs<A extends undefined ? Record<string, never> : A>, Promise<InferReturns<R>>>;
+/**
+ * Creates a reusable mutation builder from a Convex mutation builder.
+ * Returns a builder function that accepts Convex-style config objects with args, handler, and returns.
+ *
+ * @example
+ * ```ts
+ * import { mutation } from './_generated/server'
+ * import { zMutationBuilder } from 'zodvex'
+ *
+ * // Create a reusable builder
+ * export const zm = zMutationBuilder(mutation)
+ *
+ * // Use it with Convex-style object syntax
+ * export const updateUser = zm({
+ *   args: { id: z.string(), name: z.string() },
+ *   handler: async (ctx, { id, name }) => {
+ *     return ctx.db.patch(id, { name })
+ *   }
+ * })
+ * ```
+ */
+declare function zMutationBuilder<Builder extends (fn: any) => any>(builder: Builder): <A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(config: {
+    args?: A;
+    handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A extends undefined ? Record<string, never> : A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>;
+    returns?: R;
+}) => RegisteredMutation<Visibility, ZodToConvexArgs<A extends undefined ? Record<string, never> : A>, Promise<InferReturns<R>>>;
+/**
+ * Creates a reusable action builder from a Convex action builder.
+ * Returns a builder function that accepts Convex-style config objects with args, handler, and returns.
+ *
+ * @example
+ * ```ts
+ * import { action } from './_generated/server'
+ * import { zActionBuilder } from 'zodvex'
+ *
+ * // Create a reusable builder
+ * export const za = zActionBuilder(action)
+ *
+ * // Use it with Convex-style object syntax
+ * export const sendEmail = za({
+ *   args: { to: z.string().email(), subject: z.string() },
+ *   handler: async (ctx, { to, subject }) => {
+ *     // Send email
+ *   }
+ * })
+ * ```
+ */
+declare function zActionBuilder<Builder extends (fn: any) => any>(builder: Builder): <A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(config: {
+    args?: A;
+    handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A extends undefined ? Record<string, never> : A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>;
+    returns?: R;
+}) => RegisteredAction<Visibility, ZodToConvexArgs<A extends undefined ? Record<string, never> : A>, Promise<InferReturns<R>>>;
+/**
+ * Creates a custom query builder with context injection from a Convex query builder.
+ * Allows you to add custom context (like auth, permissions, etc.) to your queries.
+ *
+ * @example
+ * ```ts
+ * import { query } from './_generated/server'
+ * import { zCustomQueryBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authQuery = zCustomQueryBuilder(
+ *   query,
+ *   customCtx(async (ctx) => {
+ *     const user = await getUserOrThrow(ctx)
+ *     return { user }
+ *   })
+ * )
+ *
+ * // Use it with automatic user injection
+ * export const getMyProfile = authQuery({
+ *   args: {},
+ *   handler: async (ctx) => {
+ *     // ctx.user is automatically available
+ *     return ctx.db.get(ctx.user._id)
+ *   }
+ * })
+ * ```
+ */
+declare function zCustomQueryBuilder<Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility = ExtractVisibility<Builder>, ExtraArgs extends Record<string, any> = Record<string, any>>(query: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'query', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
+/**
+ * Creates a custom mutation builder with context injection from a Convex mutation builder.
+ * Allows you to add custom context (like auth, permissions, etc.) to your mutations.
+ *
+ * @example
+ * ```ts
+ * import { mutation } from './_generated/server'
+ * import { zCustomMutationBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authMutation = zCustomMutationBuilder(
+ *   mutation,
+ *   customCtx(async (ctx) => {
+ *     const user = await getUserOrThrow(ctx)
+ *     return { user }
+ *   })
+ * )
+ *
+ * // Use it with automatic user injection
+ * export const updateProfile = authMutation({
+ *   args: { name: z.string() },
+ *   handler: async (ctx, { name }) => {
+ *     // ctx.user is automatically available
+ *     await ctx.db.patch(ctx.user._id, { name })
+ *   }
+ * })
+ * ```
+ */
+declare function zCustomMutationBuilder<Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility = ExtractVisibility<Builder>, ExtraArgs extends Record<string, any> = Record<string, any>>(mutation: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'mutation', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
+/**
+ * Creates a custom action builder with context injection from a Convex action builder.
+ * Allows you to add custom context (like auth, permissions, etc.) to your actions.
+ *
+ * @example
+ * ```ts
+ * import { action } from './_generated/server'
+ * import { zCustomActionBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authAction = zCustomActionBuilder(
+ *   action,
+ *   customCtx(async (ctx) => {
+ *     const identity = await ctx.auth.getUserIdentity()
+ *     if (!identity) throw new Error('Unauthorized')
+ *     return { userId: identity.subject }
+ *   })
+ * )
+ *
+ * // Use it with automatic auth injection
+ * export const sendEmail = authAction({
+ *   args: { to: z.string().email() },
+ *   handler: async (ctx, { to }) => {
+ *     // ctx.userId is automatically available
+ *     await sendEmailService(to, ctx.userId)
+ *   }
+ * })
+ * ```
+ */
+declare function zCustomActionBuilder<Builder extends (fn: any) => any, CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, Visibility extends FunctionVisibility = ExtractVisibility<Builder>, ExtraArgs extends Record<string, any> = Record<string, any>>(action: Builder, customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>): CustomBuilder<'action', CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtractCtx<Builder>, Visibility, ExtraArgs>;
+
+type ConvexCodec<T> = {
+    validator: any;
+    encode: (value: T) => any;
+    decode: (value: any) => T;
+    pick: <K extends keyof T>(keys: K[]) => ConvexCodec<Pick<T, K>>;
+};
+declare function convexCodec<T>(schema: z.ZodType<T>): ConvexCodec<T>;
+declare function toConvexJS(schema?: any, value?: any): any;
+declare function fromConvexJS(value: any, schema: any): any;
+
 type BaseCodec = {
     check: (schema: any) => boolean;
     toValidator: (schema: any) => any;
@@ -186,7 +352,29 @@ declare function zodDocOrNull<TableName extends string, Shape extends z.ZodRawSh
  * This architectural decision is important for projects that rely heavily on type safety and
  * developer experience, as it avoids the type erasure that can occur when using ZodObject directly.
  *
- * Returns both the Table and the shape for use with zCrud.
+ * Returns the Table definition along with Zod schemas for documents and arrays.
+ *
+ * @param name - The table name
+ * @param shape - A raw object mapping field names to Zod validators
+ * @returns A Table with attached shape, zDoc schema, and docArray helper
+ *
+ * @example
+ * ```ts
+ * const Users = zodTable('users', {
+ *   name: z.string(),
+ *   email: z.string().email(),
+ *   age: z.number().optional()
+ * })
+ *
+ * // Use in schema
+ * export default defineSchema({ users: Users.table })
+ *
+ * // Use for return types
+ * export const getUsers = zQuery(query, {},
+ *   async (ctx) => ctx.db.query('users').collect(),
+ *   { returns: Users.docArray }
+ * )
+ * ```
  */
 declare function zodTable<TableName extends string, Shape extends Record<string, z.ZodTypeAny>>(name: TableName, shape: Shape): {
     name: TableName;
@@ -238,55 +426,14 @@ declare function zodTable<TableName extends string, Shape extends Record<string,
         _id: ReturnType<typeof zid<TableName>>;
         _creationTime: z.ZodNumber;
     }>;
-};
-declare function zodTableWithDocs<T extends z.ZodObject<any>, TableName extends string>(name: TableName, schema: T): {
-    schema: T;
-    docSchema: z.ZodObject<{
-        _id: z.ZodType<GenericId<TableName>, unknown, z.core.$ZodTypeInternals<GenericId<TableName>, unknown>> & {
-            _tableName: TableName;
-        };
-        _creationTime: z.ZodNumber;
-    }, z.core.$strip>;
-    docArray: z.ZodArray<z.ZodObject<{
+    docArray: z.ZodArray<z.ZodObject<Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }> & {
         _id: z.ZodType<GenericId<TableName>, unknown, z.core.$ZodTypeInternals<GenericId<TableName>, unknown>> & {
             _tableName: TableName;
         };
         _creationTime: z.ZodNumber;
     }, z.core.$strip>>;
-    name: TableName;
-    table: convex_server.TableDefinition<convex_values.VObject<{
-        [x: string]: any;
-        [x: number]: any;
-        [x: symbol]: any;
-    }, ConvexValidatorFromZodFieldsAuto<any>, "required", string>, {}, {}, {}>;
-    doc: convex_values.VObject<{
-        [x: string]: any;
-        [x: number]: any;
-        [x: symbol]: any;
-    }, {
-        [x: string]: convex_values.VFloat64<number, "required"> | convex_values.VNull<null, "required"> | convex_values.VLiteral<z.core.util.Literal, "required"> | convex_values.VAny<"required", "required", string> | convex_values.VAny<"required", "required", string> | convex_values.VAny<"required", "required", string> | convex_values.VAny<"required", "required", string> | convex_values.VUnion<unknown, any[], "required", any> | convex_values.VUnion<unknown, any[], "required", any> | convex_values.VString<any, "required"> | convex_values.VFloat64<any, "required"> | convex_values.VInt64<any, "required"> | convex_values.VBoolean<any, "required"> | convex_values.VArray<any, convex_values.VAny<"required", "required", string>, "required"> | convex_values.VObject<any, {
-            readonly [x: string]: convex_values.VAny<"required", "required", string>;
-        }, "required", string> | convex_values.VUnion<z.core.util.EnumValue, any[], "required", any> | convex_values.VRecord<Record<string, unknown>, convex_values.VString<string, "required">, convex_values.VAny<"required", "required", string>, "required", string> | convex_values.VLiteral<z.core.util.Literal, "optional"> | convex_values.VAny<"required" | undefined, "optional", string> | convex_values.VUnion<unknown, any[], "optional", any> | convex_values.VString<any, "optional"> | convex_values.VFloat64<any, "optional"> | convex_values.VFloat64<number, "optional"> | convex_values.VInt64<any, "optional"> | convex_values.VBoolean<any, "optional"> | convex_values.VNull<null, "optional"> | convex_values.VArray<any, convex_values.VAny<"required", "required", string>, "optional"> | convex_values.VObject<any, {
-            readonly [x: string]: convex_values.VAny<"required", "required", string>;
-        }, "optional", string> | convex_values.VUnion<z.core.util.EnumValue, any[], "optional", any> | convex_values.VRecord<Record<string, unknown>, convex_values.VString<string, "required">, convex_values.VAny<"required", "required", string>, "optional", string>;
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    }, "required", string>;
-    withoutSystemFields: ConvexValidatorFromZodFieldsAuto<any>;
-    withSystemFields: {
-        [x: string]: convex_values.VFloat64<number, "required"> | convex_values.VNull<null, "required"> | convex_values.VLiteral<z.core.util.Literal, "required"> | convex_values.VAny<"required", "required", string> | convex_values.VAny<"required", "required", string> | convex_values.VAny<"required", "required", string> | convex_values.VAny<"required", "required", string> | convex_values.VUnion<unknown, any[], "required", any> | convex_values.VUnion<unknown, any[], "required", any> | convex_values.VString<any, "required"> | convex_values.VFloat64<any, "required"> | convex_values.VInt64<any, "required"> | convex_values.VBoolean<any, "required"> | convex_values.VArray<any, convex_values.VAny<"required", "required", string>, "required"> | convex_values.VObject<any, {
-            readonly [x: string]: convex_values.VAny<"required", "required", string>;
-        }, "required", string> | convex_values.VUnion<z.core.util.EnumValue, any[], "required", any> | convex_values.VRecord<Record<string, unknown>, convex_values.VString<string, "required">, convex_values.VAny<"required", "required", string>, "required", string> | convex_values.VLiteral<z.core.util.Literal, "optional"> | convex_values.VAny<"required" | undefined, "optional", string> | convex_values.VUnion<unknown, any[], "optional", any> | convex_values.VString<any, "optional"> | convex_values.VFloat64<any, "optional"> | convex_values.VFloat64<number, "optional"> | convex_values.VInt64<any, "optional"> | convex_values.VBoolean<any, "optional"> | convex_values.VNull<null, "optional"> | convex_values.VArray<any, convex_values.VAny<"required", "required", string>, "optional"> | convex_values.VObject<any, {
-            readonly [x: string]: convex_values.VAny<"required", "required", string>;
-        }, "optional", string> | convex_values.VUnion<z.core.util.EnumValue, any[], "optional", any> | convex_values.VRecord<Record<string, unknown>, convex_values.VString<string, "required">, convex_values.VAny<"required", "required", string>, "optional", string>;
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    };
-    systemFields: {
-        _id: convex_values.VId<GenericId<TableName>, "required">;
-        _creationTime: convex_values.VFloat64<number, "required">;
-    };
-    _id: convex_values.VId<GenericId<TableName>, "required">;
 };
 
 declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
@@ -314,27 +461,35 @@ declare function zPaginated<T extends z.ZodTypeAny>(item: T): z.ZodObject<{
  */
 declare function mapDateFieldToNumber(field: z.ZodTypeAny): z.ZodTypeAny;
 type Mask = readonly string[] | Record<string, boolean | 1 | true>;
+/**
+ * Returns a plain shape object containing only the selected fields.
+ * Accepts either a ZodObject or a raw shape object.
+ */
 declare function pickShape(schemaOrShape: z.ZodObject<any> | Record<string, any>, mask: Mask): Record<string, any>;
 declare function safePick(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any>;
+/**
+ * Convenience: omit a set of keys by building the complement.
+ * Avoids using Zod's .omit() which can cause type depth issues.
+ */
 declare function safeOmit(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any>;
 
-declare function zQuery<DataModel extends GenericDataModel, Visibility extends FunctionVisibility, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(query: QueryBuilder<DataModel, Visibility>, input: A, handler: (ctx: GenericQueryCtx<DataModel>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
+declare function zQuery<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(query: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
     returns?: R;
 }): RegisteredQuery<Visibility, ZodToConvexArgs<A>, Promise<InferReturns<R>>>;
-declare function zInternalQuery<DataModel extends GenericDataModel, Visibility extends FunctionVisibility, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalQuery: QueryBuilder<DataModel, Visibility>, input: A, handler: (ctx: GenericQueryCtx<DataModel>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
+declare function zInternalQuery<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(internalQuery: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
     returns?: R;
 }): RegisteredQuery<Visibility, ZodToConvexArgs<A>, Promise<InferReturns<R>>>;
-declare function zMutation<DataModel extends GenericDataModel, Visibility extends FunctionVisibility, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(mutation: MutationBuilder<DataModel, Visibility>, input: A, handler: (ctx: GenericMutationCtx<DataModel>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
+declare function zMutation<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(mutation: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
     returns?: R;
 }): RegisteredMutation<Visibility, ZodToConvexArgs<A>, Promise<InferReturns<R>>>;
-declare function zInternalMutation<DataModel extends GenericDataModel, Visibility extends FunctionVisibility, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalMutation: MutationBuilder<DataModel, Visibility>, input: A, handler: (ctx: GenericMutationCtx<DataModel>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
+declare function zInternalMutation<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(internalMutation: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
     returns?: R;
 }): RegisteredMutation<Visibility, ZodToConvexArgs<A>, Promise<InferReturns<R>>>;
-declare function zAction<DataModel extends GenericDataModel, Visibility extends FunctionVisibility, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(action: ActionBuilder<DataModel, Visibility>, input: A, handler: (ctx: GenericActionCtx<DataModel>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
+declare function zAction<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(action: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
     returns?: R;
 }): RegisteredAction<Visibility, ZodToConvexArgs<A>, Promise<InferReturns<R>>>;
-declare function zInternalAction<DataModel extends GenericDataModel, Visibility extends FunctionVisibility, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined>(internalAction: ActionBuilder<DataModel, Visibility>, input: A, handler: (ctx: GenericActionCtx<DataModel>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
+declare function zInternalAction<Builder extends (fn: any) => any, A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>, R extends z.ZodTypeAny | undefined = undefined, Visibility extends FunctionVisibility = ExtractVisibility<Builder>>(internalAction: Builder, input: A, handler: (ctx: ExtractCtx<Builder>, args: ZodToConvexArgs<A>) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>, options?: {
     returns?: R;
 }): RegisteredAction<Visibility, ZodToConvexArgs<A>, Promise<InferReturns<R>>>;
 
-export { type ConvexCodec, type ConvexValidatorFromZod, type ConvexValidatorFromZodFieldsAuto, type CustomBuilder, type ExtractCtx, type ExtractVisibility, type InferArgs, type InferHandlerReturns, type InferReturns, type PreserveReturnType, type Zid, type ZodToConvexArgs, type ZodValidator, convexCodec, findBaseCodec, formatZodIssues, fromConvexJS, getObjectShape, handleZodValidationError, isDateSchema, makeUnion, mapDateFieldToNumber, pick, pickShape, registerBaseCodec, registryHelpers, returnsAs, safeOmit, safePick, toConvexJS, zAction, zCustomAction, zCustomMutation, zCustomQuery, zInternalAction, zInternalMutation, zInternalQuery, zMutation, zPaginated, zQuery, zStrictAction, zStrictMutation, zStrictQuery, zid, zodDoc, zodDocOrNull, zodTable, zodTableWithDocs, zodToConvex, zodToConvexFields };
+export { type ConvexCodec, type ConvexValidatorFromZod, type ConvexValidatorFromZodFieldsAuto, type CustomBuilder, type ExtractCtx, type ExtractVisibility, type InferArgs, type InferHandlerReturns, type InferReturns, type PreserveReturnType, type Zid, type ZodToConvexArgs, type ZodValidator, convexCodec, customFnBuilder, findBaseCodec, formatZodIssues, fromConvexJS, getObjectShape, handleZodValidationError, isDateSchema, makeUnion, mapDateFieldToNumber, pick, pickShape, registerBaseCodec, registryHelpers, returnsAs, safeOmit, safePick, toConvexJS, zAction, zActionBuilder, zCustomAction, zCustomActionBuilder, zCustomMutation, zCustomMutationBuilder, zCustomQuery, zCustomQueryBuilder, zInternalAction, zInternalMutation, zInternalQuery, zMutation, zMutationBuilder, zPaginated, zQuery, zQueryBuilder, zid, zodDoc, zodDocOrNull, zodTable, zodToConvex, zodToConvexFields };