zodvex 0.3.2 → 0.4.1

package/README.md

@@ -19,6 +19,7 @@ Type-safe Convex functions with Zod schemas. Preserve Convex's optional/nullable
 - [API Reference](#api-reference)
 - [Advanced Usage](#advanced-usage)
   - [Custom Context Builders](#custom-context-builders)
+    - [Hooks and Transforms](#hooks-and-transforms)
   - [Date Handling](#date-handling)
   - [Return Type Helpers](#return-type-helpers)
   - [Working with Large Schemas](#working-with-large-schemas)
@@ -446,6 +447,80 @@ export const updateProfile = authMutation({
 })
 ```
 
+#### Hooks and Transforms
+
+For advanced use cases like logging, analytics, or data transformations, use `customCtxWithHooks`:
+
+```ts
+import { zCustomMutationBuilder, customCtxWithHooks } from 'zodvex'
+import { type MutationCtx, mutation } from './_generated/server'
+
+export const secureMutation = zCustomMutationBuilder(
+  mutation,
+  customCtxWithHooks(async (ctx: MutationCtx) => {
+    const securityCtx = await getSecurityContext(ctx)
+
+    return {
+      // Custom context (same as customCtx)
+      ctx: { securityCtx },
+
+      // Hooks: observe execution (side effects, no return value)
+      hooks: {
+        onSuccess: ({ ctx, args, result }) => {
+          // Called after successful execution
+          console.log('Mutation succeeded:', { args, result })
+          analytics.track('mutation_success', { userId: ctx.securityCtx.userId })
+        }
+      },
+
+      // Transforms: modify data in the flow
+      transforms: {
+        // Transform args after validation, before handler
+        input: (args, schema) => {
+          // e.g., Convert wire format to runtime objects
+          return transformIncomingArgs(args, securityCtx)
+        },
+        // Transform result after handler, before response
+        output: (result, schema) => {
+          // e.g., Mask sensitive fields based on permissions
+          return transformOutgoingResult(result, securityCtx)
+        }
+      }
+    }
+  })
+)
+```
+
+**Execution order:**
+
+1. Args received from client
+2. Zod validation on args
+3. `transforms.input` runs (if provided)
+4. Handler executes
+5. Zod validation on returns (if provided)
+6. `hooks.onSuccess` runs (if provided)
+7. `transforms.output` runs (if provided)
+8. Response sent to client
+
+**Use cases:**
+
+| Feature | Use Case |
+|---------|----------|
+| `hooks.onSuccess` | Logging, analytics, audit trails, cache invalidation |
+| `transforms.input` | Wire format → runtime objects, field decryption, data hydration |
+| `transforms.output` | Sensitive field masking, data redaction, format conversion |
+
+**Note:** Both `transforms.input` and `transforms.output` can be async:
+
+```ts
+transforms: {
+  input: async (args, schema) => {
+    const decrypted = await decrypt(args.sensitiveField)
+    return { ...args, sensitiveField: decrypted }
+  }
+}
+```
+
 ### Date Handling
 
 zodvex automatically converts dates between JavaScript `Date` objects and Convex timestamps when using `z.date()` in your schemas.

package/dist/__type-tests__/infer-returns.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=infer-returns.d.ts.map

package/dist/__type-tests__/infer-returns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer-returns.d.ts","sourceRoot":"","sources":["../../src/__type-tests__/infer-returns.ts"],"names":[],"mappings":""}

package/dist/__type-tests__/zodTable-inference.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=zodTable-inference.d.ts.map

package/dist/__type-tests__/zodTable-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zodTable-inference.d.ts","sourceRoot":"","sources":["../../src/__type-tests__/zodTable-inference.ts"],"names":[],"mappings":""}

package/dist/builders.d.ts

@@ -0,0 +1,173 @@
+import type { FunctionVisibility, RegisteredAction, RegisteredMutation, RegisteredQuery } from 'convex/server';
+import type { PropertyValidators } from 'convex/values';
+import type { Customization } from 'convex-helpers/server/customFunctions';
+import { z } from 'zod';
+import { type CustomBuilder } from './custom';
+import type { ExtractCtx, ExtractVisibility, InferHandlerReturns, InferReturns, ZodToConvexArgs } from './types';
+/**
+ * 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)
+ *   }
+ * })
+ * ```
+ */
+export 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 })
+ *   }
+ * })
+ * ```
+ */
+export 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
+ *   }
+ * })
+ * ```
+ */
+export 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 { type QueryCtx, query } from './_generated/server'
+ * import { zCustomQueryBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authQuery = zCustomQueryBuilder(
+ *   query,
+ *   customCtx(async (ctx: QueryCtx) => {
+ *     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)
+ *   }
+ * })
+ * ```
+ */
+export 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 { type MutationCtx, mutation } from './_generated/server'
+ * import { zCustomMutationBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authMutation = zCustomMutationBuilder(
+ *   mutation,
+ *   customCtx(async (ctx: MutationCtx) => {
+ *     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 })
+ *   }
+ * })
+ * ```
+ */
+export 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 { type ActionCtx, action } from './_generated/server'
+ * import { zCustomActionBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authAction = zCustomActionBuilder(
+ *   action,
+ *   customCtx(async (ctx: ActionCtx) => {
+ *     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)
+ *   }
+ * })
+ * ```
+ */
+export 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>;
+//# sourceMappingURL=builders.d.ts.map

package/dist/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"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"}

package/dist/codec.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export type ConvexCodec<T> = {
+    validator: any;
+    encode: (value: T) => any;
+    decode: (value: any) => T;
+    pick: <K extends keyof T>(keys: K[]) => ConvexCodec<Pick<T, K>>;
+};
+export declare function convexCodec<T>(schema: z.ZodType<T>): ConvexCodec<T>;
+export declare function toConvexJS(schema?: any, value?: any): any;
+export declare function fromConvexJS(value: any, schema: any): any;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AASvB,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,SAAS,EAAE,GAAG,CAAA;IACd,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,CAAA;IACzB,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAA;IACzB,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;CAChE,CAAA;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAmBnE;AAGD,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,GAAG,CASzD;AAkGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,CA+EzD"}

package/dist/custom.d.ts

@@ -0,0 +1,147 @@
+import { type ArgsArrayToObject, type DefaultFunctionArgs, type FunctionVisibility, type GenericDataModel, type GenericQueryCtx, type QueryBuilder } from 'convex/server';
+import { type PropertyValidators } from 'convex/values';
+import { type Customization } from 'convex-helpers/server/customFunctions';
+import { z } from 'zod';
+import { type ZodValidator } from './mapping';
+import type { ExtractCtx } from './types';
+/**
+ * Hooks for observing the function execution (side effects, no return value).
+ */
+export type CustomizationHooks = {
+    /** Called after successful execution with access to ctx, args, and result */
+    onSuccess?: (info: {
+        ctx: unknown;
+        args: Record<string, unknown>;
+        result: unknown;
+    }) => void | Promise<void>;
+};
+/**
+ * Transforms for modifying data in the function flow.
+ */
+export type CustomizationTransforms = {
+    /** Transform args after validation but before handler receives them */
+    input?: (args: unknown, schema: z.ZodTypeAny) => unknown | Promise<unknown>;
+    /** Transform the output after validation but before wire encoding */
+    output?: (result: unknown, schema: z.ZodTypeAny) => unknown | Promise<unknown>;
+};
+/**
+ * Result returned from a customization input function.
+ * Separates Convex concepts (ctx, args) from hooks (side effects) and transforms (data modifications).
+ */
+export type CustomizationResult<CustomCtx extends Record<string, any> = Record<string, any>, CustomArgs extends Record<string, any> = Record<string, any>> = {
+    /** Custom context to merge with base context */
+    ctx?: CustomCtx;
+    /** Custom args to merge with parsed args */
+    args?: CustomArgs;
+    /** Hooks for observing execution (side effects) */
+    hooks?: CustomizationHooks;
+    /** Transforms for modifying the data flow */
+    transforms?: CustomizationTransforms;
+};
+/**
+ * Extended input result that includes hooks and transforms.
+ * This is what the input function returns internally.
+ */
+export type CustomizationInputResult<OutCtx extends Record<string, any>, OutArgs extends Record<string, any>> = {
+    ctx: OutCtx;
+    args: OutArgs;
+    hooks?: CustomizationHooks;
+    transforms?: CustomizationTransforms;
+};
+/**
+ * Customization type that supports hooks and transforms.
+ * This extends convex-helpers' Customization pattern to include
+ * hooks (side effects) and transforms (data modifications).
+ *
+ * Use customCtxWithHooks() to create instances of this type.
+ */
+export type CustomizationWithHooks<InCtx extends Record<string, any>, OutCtx extends Record<string, any> = Record<string, any>, OutArgs extends Record<string, any> = Record<string, any>, ExtraArgs extends Record<string, any> = Record<string, any>> = {
+    args: Record<string, never>;
+    input: (ctx: InCtx, args?: Record<string, unknown>, extra?: ExtraArgs) => Promise<CustomizationInputResult<OutCtx, OutArgs>> | CustomizationInputResult<OutCtx, OutArgs>;
+};
+/**
+ * A helper for defining a Customization with full support for hooks and transforms.
+ * Use this instead of customCtx when you need onSuccess, transforms.input, transforms.output, etc.
+ *
+ * @example
+ * ```ts
+ * const secureMutation = zCustomMutationBuilder(
+ *   mutation,
+ *   customCtxWithHooks(async (ctx: MutationCtx) => {
+ *     const securityCtx = await getSecurityContext(ctx)
+ *     return {
+ *       ctx: { securityCtx },
+ *       hooks: {
+ *         onSuccess: ({ result }) => console.log('Mutation returned:', result),
+ *       },
+ *       transforms: {
+ *         // Transform incoming args (e.g., wire format → runtime objects)
+ *         input: (args, schema) => transformIncomingArgs(args, securityCtx),
+ *         // Transform outgoing result (e.g., runtime objects → wire format)
+ *         output: (result, schema) => transformOutgoingResult(result, securityCtx),
+ *       },
+ *     }
+ *   })
+ * )
+ * ```
+ */
+export declare function customCtxWithHooks<InCtx extends Record<string, any>, OutCtx extends Record<string, any> = Record<string, any>, OutArgs extends Record<string, any> = Record<string, any>>(fn: (ctx: InCtx) => Promise<CustomizationResult<OutCtx, OutArgs>> | CustomizationResult<OutCtx, OutArgs>): CustomizationWithHooks<InCtx, OutCtx, OutArgs>;
+type OneArgArray<ArgsObject extends DefaultFunctionArgs = DefaultFunctionArgs> = [ArgsObject];
+type NullToUndefinedOrNull<T> = T extends null ? T | undefined | void : T;
+type Returns<T> = Promise<NullToUndefinedOrNull<T>> | NullToUndefinedOrNull<T>;
+type ReturnValueInput<ReturnsValidator extends z.ZodTypeAny | ZodValidator | void> = [
+    ReturnsValidator
+] extends [z.ZodTypeAny] ? Returns<z.output<ReturnsValidator>> : [ReturnsValidator] extends [ZodValidator] ? Returns<z.output<z.ZodObject<ReturnsValidator>>> : any;
+type ReturnValueOutput<ReturnsValidator extends z.ZodTypeAny | ZodValidator | void> = [
+    ReturnsValidator
+] extends [z.ZodTypeAny] ? Returns<z.output<ReturnsValidator>> : [ReturnsValidator] extends [ZodValidator] ? Returns<z.output<z.ZodObject<ReturnsValidator>>> : any;
+type ArgsInput<ArgsValidator extends ZodValidator | z.ZodObject<any> | void> = [
+    ArgsValidator
+] extends [z.ZodObject<any>] ? [z.input<ArgsValidator>] : [ArgsValidator] extends [ZodValidator] ? [z.input<z.ZodObject<ArgsValidator>>] : OneArgArray;
+type ArgsOutput<ArgsValidator extends ZodValidator | z.ZodObject<any> | void> = [
+    ArgsValidator
+] extends [z.ZodObject<any>] ? [z.output<ArgsValidator>] : [ArgsValidator] extends [ZodValidator] ? [z.output<z.ZodObject<ArgsValidator>>] : OneArgArray;
+type Overwrite<T, U> = Omit<T, keyof U> & U;
+type Expand<ObjectType extends Record<any, any>> = ObjectType extends Record<any, any> ? {
+    [Key in keyof ObjectType]: ObjectType[Key];
+} : never;
+type ArgsForHandlerType<OneOrZeroArgs extends [] | [Record<string, any>], CustomMadeArgs extends Record<string, any>> = CustomMadeArgs extends Record<string, never> ? OneOrZeroArgs : OneOrZeroArgs extends [infer A] ? [Expand<A & CustomMadeArgs>] : [CustomMadeArgs];
+type Registration<FuncType extends 'query' | 'mutation' | 'action', Visibility extends FunctionVisibility, Args extends DefaultFunctionArgs, Output> = FuncType extends 'query' ? import('convex/server').RegisteredQuery<Visibility, Args, Output> : FuncType extends 'mutation' ? import('convex/server').RegisteredMutation<Visibility, Args, Output> : import('convex/server').RegisteredAction<Visibility, Args, Output>;
+/**
+ * A builder that customizes a Convex function, whether or not it validates
+ * arguments. If the customization requires arguments, however, the resulting
+ * builder will require argument validation too.
+ *
+ * This is our own Zod-aware CustomBuilder type that properly handles Zod validators.
+ */
+export type CustomBuilder<FuncType extends 'query' | 'mutation' | 'action', CustomArgsValidator extends PropertyValidators, CustomCtx extends Record<string, any>, CustomMadeArgs extends Record<string, any>, InputCtx, Visibility extends FunctionVisibility, ExtraArgs extends Record<string, any>> = {
+    <ArgsValidator extends ZodValidator | z.ZodObject<any> | void, ReturnsZodValidator extends z.ZodTypeAny | ZodValidator | void = void, ReturnValue extends ReturnValueInput<ReturnsZodValidator> = any>(func: ({
+        /**
+         * Specify the arguments to the function as a Zod validator.
+         */
+        args?: ArgsValidator;
+        handler: (ctx: Overwrite<InputCtx, CustomCtx>, ...args: ArgsForHandlerType<ArgsOutput<ArgsValidator>, CustomMadeArgs>) => ReturnValue;
+        /**
+         * Validates the value returned by the function.
+         * Note: you can't pass an object directly without wrapping it
+         * in `z.object()`.
+         */
+        returns?: ReturnsZodValidator;
+        /**
+         * If true, the function will not be validated by Convex,
+         * in case you're seeing performance issues with validating twice.
+         */
+        skipConvexValidation?: boolean;
+    } & {
+        [key in keyof ExtraArgs as key extends 'args' | 'handler' | 'skipConvexValidation' | 'returns' ? never : key]: ExtraArgs[key];
+    }) | {
+        (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 & import('convex/values').ObjectType<CustomArgsValidator>>] : [import('convex/values').ObjectType<CustomArgsValidator>]>, ReturnsZodValidator extends void ? ReturnValue : ReturnValueOutput<ReturnsZodValidator>>;
+};
+export 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> | CustomizationWithHooks<Ctx, CustomCtx, CustomMadeArgs, ExtraArgs>): (fn: any) => any;
+export 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>;
+export 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>;
+export 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>;
+export 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>;
+export {};
+//# sourceMappingURL=custom.d.ts.map

package/dist/custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../src/custom.ts"],"names":[],"mappings":"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"}

package/dist/ids.d.ts

@@ -0,0 +1,23 @@
+/**
+ * IDs + registry for Convex + Zod v4
+ */
+import type { GenericId } from 'convex/values';
+import { z } from 'zod';
+export declare const registryHelpers: {
+    getMetadata: (type: z.ZodTypeAny) => any;
+    setMetadata: (type: z.ZodTypeAny, meta: any) => WeakMap<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, any>;
+};
+/**
+ * Create a Zod validator for a Convex Id
+ *
+ * Compatible with AI SDK and other tools that don't support transforms.
+ * Uses type-level branding instead of runtime transforms for GenericId<T> compatibility.
+ *
+ * @param tableName - The Convex table name for this ID
+ * @returns A Zod string validator typed as GenericId<TableName>
+ */
+export declare function zid<TableName extends string>(tableName: TableName): z.ZodType<GenericId<TableName>> & {
+    _tableName: TableName;
+};
+export type Zid<TableName extends string> = ReturnType<typeof zid<TableName>>;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB,eAAO,MAAM,eAAe;wBACN,CAAC,CAAC,UAAU;wBACZ,CAAC,CAAC,UAAU,QAAQ,GAAG;CAC5C,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,SAAS,SAAS,MAAM,EAC1C,SAAS,EAAE,SAAS,GACnB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,GAAG;IAAE,UAAU,EAAE,SAAS,CAAA;CAAE,CAwB7D;AAED,MAAM,MAAM,GAAG,CAAC,SAAS,SAAS,MAAM,IAAI,UAAU,CAAC,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAA"}