zodvex 0.3.2 → 0.4.0

package/dist/transform/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Transform layer type definitions.
+ *
+ * General-purpose types for schema traversal and value transformation.
+ */
+import type { z } from 'zod';
+/**
+ * Information about a field during schema traversal.
+ */
+export type FieldInfo = {
+    /** Dot-notation path (e.g., 'profile.email', 'contacts[].email') */
+    path: string;
+    /** The Zod schema for this field */
+    schema: z.ZodTypeAny;
+    /** Metadata from schema.meta() if present */
+    meta: Record<string, unknown> | undefined;
+    /** Whether the field is wrapped in optional/nullable */
+    isOptional: boolean;
+};
+/**
+ * Visitor functions for walkSchema().
+ */
+export type SchemaVisitor = {
+    /** Called for every field. Return 'skip' to skip children. */
+    onField?: (info: FieldInfo) => void | 'skip';
+    /** Called when entering an object schema */
+    onObject?: (info: FieldInfo) => void;
+    /** Called when entering an array schema */
+    onArray?: (info: FieldInfo) => void;
+    /** Called when entering a union schema */
+    onUnion?: (info: FieldInfo, variants: z.ZodTypeAny[]) => void;
+};
+/**
+ * Options for walkSchema().
+ */
+export type WalkSchemaOptions = {
+    /** Starting path prefix */
+    path?: string;
+};
+/**
+ * Context passed to transform functions.
+ */
+export type TransformContext<TCtx = unknown> = {
+    /** Current field path */
+    path: string;
+    /** The Zod schema for this field */
+    schema: z.ZodTypeAny;
+    /** Metadata from schema.meta() if present */
+    meta: Record<string, unknown> | undefined;
+    /** User-provided context */
+    ctx: TCtx;
+};
+/**
+ * Synchronous transform function signature.
+ */
+export type TransformFn<TCtx = unknown> = (value: unknown, context: TransformContext<TCtx>) => unknown;
+/**
+ * Async transform function signature.
+ */
+export type AsyncTransformFn<TCtx = unknown> = (value: unknown, context: TransformContext<TCtx>) => unknown | Promise<unknown>;
+/**
+ * Options for transformBySchema().
+ */
+export type TransformOptions = {
+    /** Starting path prefix */
+    path?: string;
+    /**
+     * How to handle values that don't match any union variant.
+     * - 'passthrough': Return value unchanged (default)
+     * - 'error': Throw an error
+     * - 'null': Replace with null (fail-closed for security)
+     */
+    unmatchedUnion?: 'passthrough' | 'error' | 'null';
+    /** Callback when a union doesn't match */
+    onUnmatchedUnion?: (path: string) => void;
+    /**
+     * Fast predicate to check if a schema needs transformation.
+     *
+     * When provided, this predicate is called before the transform callback.
+     * If it returns false, the transform callback is skipped for this schema
+     * (but recursion into children continues).
+     *
+     * This optimization avoids callback overhead for schemas that don't need
+     * transformation, which is useful when only a small subset of fields
+     * require processing (e.g., only sensitive fields).
+     *
+     * @example
+     * ```ts
+     * // Only call transform for schemas with sensitive metadata
+     * transformBySchema(value, schema, ctx, transform, {
+     *   shouldTransform: (sch) => getSensitiveMetadata(sch) !== undefined
+     * })
+     * ```
+     */
+    shouldTransform?: (schema: z.ZodTypeAny) => boolean;
+    /**
+     * Process array elements in parallel (async only).
+     *
+     * When true, array elements are processed with Promise.all() instead of
+     * sequentially. This can significantly improve performance for large arrays
+     * when transforms involve async operations like entitlement checks.
+     *
+     * Default: false (sequential processing for backwards compatibility)
+     *
+     * @example
+     * ```ts
+     * // Process user entitlements for all items in parallel
+     * const result = await transformBySchemaAsync(docs, schema, ctx, transform, {
+     *   parallel: true
+     * })
+     * ```
+     */
+    parallel?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/transform/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transform/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAA;IACpB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACzC,wDAAwD;IACxD,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,CAAA;IAC5C,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACpC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACnC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,IAAI,CAAA;CAC9D,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,GAAG,OAAO,IAAI;IAC7C,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAA;IACpB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACzC,4BAA4B;IAC5B,GAAG,EAAE,IAAI,CAAA;CACV,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,GAAG,OAAO,IAAI,CACxC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,KAC5B,OAAO,CAAA;AAEZ;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,IAAI,GAAG,OAAO,IAAI,CAC7C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,KAC5B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/B;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,cAAc,CAAC,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAA;IACjD,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,KAAK,OAAO,CAAA;IACnD;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import { type DefaultFunctionArgs, type RegisteredAction, type RegisteredMutation, type RegisteredQuery } from 'convex/server';
+import { z } from 'zod';
+export type InferArgs<A> = A extends z.ZodObject<infer S> ? z.infer<z.ZodObject<S>> : A extends Record<string, z.ZodTypeAny> ? {
+    [K in keyof A]: z.infer<A[K]>;
+} : A extends z.ZodTypeAny ? z.infer<A> : Record<string, never>;
+export type InferReturns<R> = R extends z.ZodType<any, any, any> ? z.output<R> : R extends undefined ? any : R;
+export type InferHandlerReturns<R> = R extends z.ZodType<any, any, any> ? z.output<R> : any;
+/**
+ * Extract the visibility type from a Convex builder function
+ */
+export type ExtractVisibility<Builder extends (...args: any) => any> = ReturnType<Builder> extends RegisteredQuery<infer V, any, any> ? V : ReturnType<Builder> extends RegisteredMutation<infer V, any, any> ? V : ReturnType<Builder> extends RegisteredAction<infer V, any, any> ? V : 'public';
+/**
+ * @deprecated Use GenericQueryCtx, GenericMutationCtx, or GenericActionCtx directly instead
+ */
+export type ExtractCtx<Builder> = Builder extends {
+    (fn: {
+        handler: (ctx: infer Ctx, ...args: any[]) => any;
+    }): any;
+} ? Ctx : never;
+/**
+ * @deprecated Return types are now specified explicitly using RegisteredQuery, RegisteredMutation, or RegisteredAction
+ */
+export type PreserveReturnType<Builder extends (...args: any) => any, ArgsType, ReturnsType> = ReturnType<Builder> extends RegisteredQuery<infer V, any, any> ? RegisteredQuery<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : ReturnType<Builder> extends RegisteredMutation<infer V, any, any> ? RegisteredMutation<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : ReturnType<Builder> extends RegisteredAction<infer V, any, any> ? RegisteredAction<V, ArgsType extends DefaultFunctionArgs ? ArgsType : DefaultFunctionArgs, Promise<ReturnsType>> : ReturnType<Builder>;
+export type ZodToConvexArgs<A> = A extends z.ZodObject<any> ? z.infer<A> : A extends Record<string, z.ZodTypeAny> ? {
+    [K in keyof A]: z.infer<A[K]>;
+} : A extends z.ZodTypeAny ? {
+    value: z.infer<A>;
+} : Record<string, never>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+export declare function returnsAs<R extends z.ZodTypeAny>(): <T extends z.input<R>>(v: T) => T;
+export declare function formatZodIssues(error: z.ZodError, context?: 'args' | 'returns' | 'input' | 'output' | 'codec'): {
+    error: string;
+    context: "output" | "input" | "args" | "returns" | "codec" | undefined;
+    issues: {
+        path: string;
+        code: "custom" | "invalid_type" | "unrecognized_keys" | "invalid_union" | "invalid_value" | "invalid_key" | "too_big" | "too_small" | "invalid_format" | "not_multiple_of" | "invalid_element";
+        message: string;
+    }[];
+    flatten: any;
+};
+export declare function handleZodValidationError(e: unknown, context: 'args' | 'returns' | 'input' | 'output' | 'codec'): never;
+export declare function zPaginated<T extends z.ZodTypeAny>(item: T): z.ZodObject<{
+    page: z.ZodArray<T>;
+    isDone: z.ZodBoolean;
+    continueCursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Maps Date fields to number fields for docSchema generation.
+ * Handles Date, Date.optional(), Date.nullable(), and Date.default() cases.
+ * Returns the original field for non-Date types.
+ */
+export 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.
+ */
+export declare function pickShape(schemaOrShape: z.ZodObject<any> | Record<string, any>, mask: Mask): Record<string, any>;
+export 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.
+ */
+export declare function safeOmit(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EACnE,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,CAAC,EAAE,GACR,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAMZ;AAGD,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,MACtC,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,OACnC;AAGD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,CAAC,CAAC,QAAQ,EACjB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO;;;;;;;;;EAa5D;AAID,wBAAgB,wBAAwB,CACtC,CAAC,EAAE,OAAO,EACV,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GACzD,KAAK,CAKP;AAGD,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;;;;kBAMzD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CA0BtE;AAGD,KAAK,IAAI,GAAG,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;AAOlE;;;GAGG;AACH,wBAAgB,SAAS,CACvB,aAAa,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrD,IAAI,EAAE,IAAI,GACT,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUrB;AAGD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAE/E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAM/E"}

package/dist/wrappers.d.ts

@@ -0,0 +1,22 @@
+import type { FunctionVisibility, RegisteredAction, RegisteredMutation, RegisteredQuery } from 'convex/server';
+import { z } from 'zod';
+import type { ExtractCtx, ExtractVisibility, InferHandlerReturns, InferReturns, ZodToConvexArgs } from './types';
+export 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>>>;
+export 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>>>;
+export 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>>>;
+export 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>>>;
+export 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>>>;
+export 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>>>;
+//# sourceMappingURL=wrappers.d.ts.map

package/dist/wrappers.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zodvex",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Zod <=> Convex integration, supporting Zod 4",
   "keywords": ["zod", "convex", "validators", "codec", "mapping", "schema", "validation"],
   "homepage": "https://github.com/panzacoder/zodvex#readme",
@@ -21,18 +21,23 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./transform": {
+      "types": "./dist/transform/index.d.ts",
+      "import": "./dist/transform/index.js",
+      "default": "./dist/transform/index.js"
     }
   },
   "files": ["dist", "src", "README.md", "LICENSE"],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --emitDeclarationOnly",
     "dev": "bun run tsup --watch",
     "type-check": "bun run tsc --noEmit",
     "test": "bun test",
     "lint": "bun x biome check src __tests__",
     "lint:fix": "bun x biome check --write src __tests__",
     "format": "bun x biome format --write src __tests__",
-    "prepare": "tsup",
+    "prepare": "tsup && tsc --emitDeclarationOnly",
     "prepublishOnly": "bun test && bun run type-check"
   },
   "peerDependencies": {
@@ -40,13 +45,15 @@
     "convex-helpers": "^0.1.104",
     "zod": "^4.1.12"
   },
+  "dependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.2.6",
     "@types/bun": "^1.3.0",
     "@types/node": "^24.8.0",
-    "ai": "^6.0.6",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
+    "ai": "^6.0.6"
   },
   "engines": {
     "node": ">=20",

package/src/__type-tests__/infer-returns.ts

@@ -152,3 +152,27 @@ const treeNodeSchema = z.object({
 })
 declare const treeNodeResult: InferReturns<typeof treeNodeSchema>
 expectNotAny(treeNodeResult)
+
+// --- Codec/Transform schemas: handler returns z.output (internal type), not z.input (wire type) ---
+// This tests the fix for Zod 4.1 codec support where input !== output
+
+// Simulate a pipe/transform schema where input !== output
+// z.input = string (wire format), z.output = Date (internal representation)
+declare const codecSchema: z.ZodPipe<z.ZodString, z.ZodDate>
+declare const codecResult: InferReturns<typeof codecSchema>
+expectNotAny(codecResult)
+// Handler should return Date (z.output), not string (z.input)
+// @ts-expect-error - If this errors with "unused directive", Result is string (the bug)
+const _codecInvalid: typeof codecResult = 'not a date'
+
+// Test with transform (coerce pattern)
+const coerceNumberSchema = z.coerce.number()
+declare const coerceResult: InferReturns<typeof coerceNumberSchema>
+expectNotAny(coerceResult)
+// @ts-expect-error - Result should be number, not string/any
+const _coerceInvalid: typeof coerceResult = 'not a number'
+
+// Test with preprocess (another transform pattern)
+const preprocessedSchema = z.preprocess(val => String(val), z.string())
+declare const preprocessResult: InferReturns<typeof preprocessedSchema>
+expectNotAny(preprocessResult)

package/src/custom.ts

@@ -18,6 +18,127 @@ import { type ZodValidator, zodToConvex, zodToConvexFields } from './mapping'
 import type { ExtractCtx, ExtractVisibility } from './types'
 import { handleZodValidationError, pick } from './utils'
 
+/**
+ * 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 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.output, etc.
+ *
+ * @example
+ * ```ts
+ * const secureQuery = zCustomQueryBuilder(
+ *   query,
+ *   customCtxWithHooks(async (ctx: QueryCtx) => {
+ *     const securityCtx = await getSecurityContext(ctx)
+ *     return {
+ *       ctx: { securityCtx },
+ *       hooks: {
+ *         onSuccess: ({ result }) => console.log('Query returned:', result),
+ *       },
+ *       transforms: {
+ *         output: (result, schema) => transformSensitiveFields(result, securityCtx),
+ *       },
+ *     }
+ *   })
+ * )
+ * ```
+ */
+export 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> {
+  return {
+    args: {},
+    input: async (ctx: InCtx): Promise<CustomizationInputResult<OutCtx, OutArgs>> => {
+      const result = await fn(ctx)
+      return {
+        ctx: result.ctx ?? ({} as OutCtx),
+        args: result.args ?? ({} as OutArgs),
+        hooks: result.hooks,
+        transforms: result.transforms
+      }
+    }
+  }
+}
+
 // Type helpers for args transformation (from zodV3 example)
 type OneArgArray<ArgsObject extends DefaultFunctionArgs = DefaultFunctionArgs> = [ArgsObject]
 
@@ -26,12 +147,14 @@ type NullToUndefinedOrNull<T> = T extends null ? T | undefined | void : T
 type Returns<T> = Promise<NullToUndefinedOrNull<T>> | NullToUndefinedOrNull<T>
 
 // The return value before it's been validated: returned by the handler
+// Uses z.output since the handler produces the internal representation (e.g., Date),
+// which is then encoded to wire format (e.g., string) before sending to the client
 type ReturnValueInput<ReturnsValidator extends z.ZodTypeAny | ZodValidator | void> = [
   ReturnsValidator
 ] extends [z.ZodTypeAny]
-  ? Returns<z.input<ReturnsValidator>>
+  ? Returns<z.output<ReturnsValidator>>
   : [ReturnsValidator] extends [ZodValidator]
-    ? Returns<z.input<z.ZodObject<ReturnsValidator>>>
+    ? Returns<z.output<z.ZodObject<ReturnsValidator>>>
     : any
 
 // The return value after it's been validated: returned to the client
@@ -171,7 +294,9 @@ export function customFnBuilder<
   ExtraArgs extends Record<string, any> = Record<string, any>
 >(
   builder: Builder,
-  customization: Customization<Ctx, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+  customization:
+    | Customization<Ctx, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+    | CustomizationWithHooks<Ctx, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
   const customInput = customization.input ?? NoOp.input
   const inputArgs = customization.args ?? NoOp.args
@@ -213,6 +338,13 @@ export function customFnBuilder<
         args: convexArgs,
         ...returnValidator,
         handler: async (ctx: Ctx, allArgs: any) => {
+          // Cast justification: customInput expects ObjectType<CustomArgsValidator>, but pick()
+          // returns Partial<T>. The cast is safe because inputArgs keys are derived from
+          // CustomArgsValidator at the type level. The 'added' result is typed as 'any' because
+          // it may include hooks/transforms from CustomizationWithHooks which aren't in the
+          // convex-helpers Customization type.
+          // TODO: Create a type-safe pickArgs<T>() helper that preserves the ObjectType<T>
+          // return type when the keys are statically known from the validator.
           const added: any = await customInput(
             ctx,
             pick(allArgs, Object.keys(inputArgs)) as any,
@@ -239,17 +371,21 @@ export function customFnBuilder<
             } catch (e) {
               handleZodValidationError(e, 'returns')
             }
-            if (added?.onSuccess) {
-              await added.onSuccess({
+            if (added?.hooks?.onSuccess) {
+              await added.hooks.onSuccess({
                 ctx,
                 args: parsed.data,
                 result: validated
               })
             }
-            return toConvexJS(returns as z.ZodTypeAny, validated)
+            // Apply output transform if provided
+            const transformed = added?.transforms?.output
+              ? await added.transforms.output(validated, returns as z.ZodTypeAny)
+              : validated
+            return toConvexJS(returns as z.ZodTypeAny, transformed)
           }
-          if (added?.onSuccess) {
-            await added.onSuccess({ ctx, args: parsed.data, result: ret })
+          if (added?.hooks?.onSuccess) {
+            await added.hooks.onSuccess({ ctx, args: parsed.data, result: ret })
           }
           return ret
         }
@@ -259,6 +395,9 @@ export function customFnBuilder<
       args: inputArgs,
       ...returnValidator,
       handler: async (ctx: Ctx, allArgs: any) => {
+        // Cast justification: Same as above - customInput expects ObjectType<CustomArgsValidator>
+        // but pick() returns Partial<T>. Safe because inputArgs keys match CustomArgsValidator.
+        // TODO: Create a type-safe pickArgs<T>() helper (see comment in with-args path above).
         const added: any = await customInput(
           ctx,
           pick(allArgs, Object.keys(inputArgs)) as any,
@@ -277,13 +416,17 @@ export function customFnBuilder<
           } catch (e) {
             handleZodValidationError(e, 'returns')
           }
-          if (added?.onSuccess) {
-            await added.onSuccess({ ctx, args: allArgs, result: validated })
+          if (added?.hooks?.onSuccess) {
+            await added.hooks.onSuccess({ ctx, args: allArgs, result: validated })
           }
-          return toConvexJS(returns as z.ZodTypeAny, validated)
+          // Apply output transform if provided
+          const transformed = added?.transforms?.output
+            ? await added.transforms.output(validated, returns as z.ZodTypeAny)
+            : validated
+          return toConvexJS(returns as z.ZodTypeAny, transformed)
         }
-        if (added?.onSuccess) {
-          await added.onSuccess({ ctx, args: allArgs, result: ret })
+        if (added?.hooks?.onSuccess) {
+          await added.hooks.onSuccess({ ctx, args: allArgs, result: ret })
         }
         return ret
       }
@@ -343,8 +486,16 @@ export function zCustomQuery<
   query: QueryBuilder<any, Visibility>,
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
-  // Implementation deliberately uses 'any' ctx to preserve overload behavior
-  // while avoiding a GenericDataModel constraint at the implementation level.
+  // Cast justification: This is the TypeScript overload implementation pattern. The function
+  // has two overloads (with/without DataModel constraint) that provide precise types to callers.
+  // The implementation must satisfy both overloads, which requires a broader signature.
+  // The 'as any' casts allow the implementation to delegate to customFnBuilder without
+  // TypeScript complaining about the generic parameter differences between overloads.
+  // This is type-safe because: (1) callers only see the overload signatures which are strict,
+  // (2) the runtime behavior is identical regardless of which overload matched.
+  // TODO: Consider using a conditional type or branded types to create a single signature
+  // that satisfies both overloads without casts. Alternatively, accept this as idiomatic
+  // TypeScript for overloaded functions and keep the casts.
   return customFnBuilder<
     any,
     typeof query,
@@ -388,6 +539,8 @@ export function zCustomMutation<
   mutation: Builder,
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
+  // Cast justification: Same overload implementation pattern as zCustomQuery.
+  // See detailed comment there. Type safety is enforced by the overload signature above.
   return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
     mutation as any,
     customization as any
@@ -427,6 +580,8 @@ export function zCustomAction<
   action: Builder,
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
+  // Cast justification: Same overload implementation pattern as zCustomQuery.
+  // See detailed comment there. Type safety is enforced by the overload signature above.
   return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
     action as any,
     customization as any

package/src/transform/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Transform layer - General-purpose schema traversal and value transformation utilities.
+ *
+ * This module provides primitives for:
+ * - Walking Zod schemas (walkSchema, findFieldsWithMeta)
+ * - Extracting metadata from schemas (getMetadata, hasMetadata)
+ * - Recursively transforming values based on schema structure (transformBySchema, transformBySchemaAsync)
+ *
+ * @example
+ * ```ts
+ * import { findFieldsWithMeta, transformBySchema } from 'zodvex/transform'
+ *
+ * // Find all fields with custom metadata
+ * const sensitiveFields = findFieldsWithMeta(schema, meta => meta?.sensitive === true)
+ *
+ * // Transform values based on metadata
+ * const masked = transformBySchema(value, schema, ctx, (val, info) => {
+ *   if (info.meta?.pii) return '[REDACTED]'
+ *   return val
+ * })
+ * ```
+ */
+
+// Transformation
+export { transformBySchema, transformBySchemaAsync } from './transform'
+
+// Traversal
+export { findFieldsWithMeta, getMetadata, hasMetadata, walkSchema } from './traverse'
+// Types
+export type {
+  AsyncTransformFn,
+  FieldInfo,
+  SchemaVisitor,
+  TransformContext,
+  TransformFn,
+  TransformOptions,
+  WalkSchemaOptions
+} from './types'