Revamp schema coercion

[transparent-citizen]

Problem

The definition of coerceFormValue asserts an explicit return type to make it identical with the input schema type. This makes it seem like a transparent wrapper to TypeScript, but the returned schema's type doesn't actually match up. This makes wrapped schemas inflexible and unfortunately brittle at runtime.

Here's how they currently differ (assuming zod v4):

const schema = z.object({ a: z.string() });
const coercedSchema = coerceFormValue(schema);

const keys = Reflect.ownKeys(schema);
const coercedKeys = Reflect.ownKeys(coercedSchema);

const difference = new Set(keys).difference(new Set(coercedKeys));
console.log(difference);

// Set(47) { 'toJSONSchema', '_def', 'spa', 'encode', 'decode', 'encodeAsync', 'decodeAsync', 'safeEncode', 'safeDecode', 'safeEncodeAsync', 'safeDecodeAsync', 'refine', 'superRefine', 'overwrite', 'optional', 'exactOptional', 'nullable', 'nullish', 'nonoptional', 'array', 'or', 'and', 'transform', 'default', 'prefault', 'catch', 'pipe', 'readonly', 'describe', 'description', 'meta', 'isOptional', 'isNullable', 'shape', 'keyof', 'catchall', 'passthrough', 'loose', 'strict', 'strip', 'extend', 'safeExtend', 'merge', 'pick', 'omit', 'partial', 'required' }

Workarounds

If an unsupported property like .shape is needed, you need to create bindings for the zod schema as well as the coerced zod schema and be mindful about naming and access:

const loginSchema = z.object({ user: z.string(), password: z.string() });
const conformLoginSchema = coerceFormValue(loginSchema);
// ...
const shape = loginSchema.shape;
// ...
useForm(conformLoginSchema, {
   // ...
});

This creates cognitive overhead, since the same schema not only comes in different variations, but the variations are of different actual types, which the type system does not reveal.

Solutions

1. coerceFormValue might be able to return a Proxy around the input schema. This way, Conform doesn't break as soon as validation libraries add a new property onto their schemas.

2. Preferrably internalize coerceFormValue and remove it from the public interface. Coerced schema definitions floating around in application code might be completely avoidable, since they are only used in two Conform-specific places anyway:

• on the client, as the first argument to useForm
• on the server, to parse the payload of parseSubmission

Would an abstraction along these lines be helpful?

// old
const submission = parseSubmission(formData);
const result = coerceFormValue(schema).safeParse(submission.payload);

// new
const submission = parseSubmission(schema, formData);
const result = submission.coercedSchema.safeParse(submission.payload);

This might also allow proper type inference here:

report(submission, {
    value: {
        // <-- submission knows about schema,
        // <-- so the type of value can be inferred
    }
}) 

[edmundhung]

That does sounds like a bug. I think if we make sure it returns the base zod type instead of the exact schema type, then it will warn you if you try to access .shape.

Preferrably internalize coerceFormValue and remove it from the public interface.

Internalizing coerceFormValue means we will have to ship a different version of parseSubmission for each schema library, and the story with schema that doesn't have an official integration much challenging. The current solution requires slightly more function calls. But I still believe it strike a better balance in terms of flexibility and composibility.

This also complicate the story in the client. How should we tell useForm how to coerce the schema?

[transparent-citizen]

I've given it some more thought and ended up doubting that going through configureForms could change the type safety of report. I nonetheless still think that there is merit in moving coerceFormValue handling into configureForms.

[edmundhung]

This is already possible with the validateSchema option. You can wrap coerceFormValue there and it applies to all forms:

import { configureForms } from '@conform-to/react/future';
import { coerceFormValue, formatResult, isSchema } from '@conform-to/zod/v3/future';
import type { ZodTypeAny, input, output } from 'zod';
declare module '@conform-to/react/future' {
  interface CustomSchemaTypes<Schema> {
    input: Schema extends ZodTypeAny ? input<Schema> : never;
    output: Schema extends ZodTypeAny ? output<Schema> : never;
  }
}
export const { useForm } = configureForms({
  isSchema,
  validateSchema(schema, payload) {
    try {
      const result = coerceFormValue(schema).safeParse(payload);
      return formatResult(result);
    } catch {
      return coerceFormValue(schema).safeParseAsync(payload).then(formatResult);
    }
  },
});

Having said that, I am hesitant to recommend this as it creates a mismatch where client and server expect different schemas. I would love if there is a way to customize this on the server side, but neither parseSubmission nor report is responsible for the validation. I am not sure what is the best way to abstract this out.

[transparent-citizen]

I've been trying to adapt this to zod v4 like this:

import { configureForms } from "@conform-to/react/future";
import {
	coerceFormValue,
	formatResult,
	isSchema,
} from "@conform-to/zod/v4/future";
import type { input, output, ZodType } from "zod";

declare module "@conform-to/react/future" {
	interface CustomSchemaTypes<Schema> {
		input: Schema extends ZodType ? input<Schema> : never;
		output: Schema extends ZodType ? output<Schema> : never;
	}
}

const configuredForms = configureForms({
	isSchema,
	validateSchema(schema, payload) {
		try {
			const result = coerceFormValue(schema).safeParse(payload);
			return formatResult(result);
		} catch {
			return coerceFormValue(schema)
				.safeParseAsync(payload)
				.then(formatResult);
		}
	},
});

However, I get a type error on validateSchema:

Type '<Schema extends ZodAny>(schema: Schema, payload: Record<string, FormValue>) => FormError<string> | Promise<{ error: FormError<string> | null; value?: InferOutput<...>; } | FormError<...> | null> | null' is not assignable to type '<Schema extends ZodAny>(schema: Schema, payload: Record<string, FormValue>, options?: InferOptions<Schema> | undefined) => MaybePromise<{ ...; }>'.
  Type 'FormError<string> | Promise<{ error: FormError<string> | null; value?: InferOutput<Schema>; } | FormError<unknown> | null> | null' is not assignable to type 'MaybePromise<{ error: FormError<string> | null; value?: InferOutput<Schema>; }>'.
    Type 'null' is not assignable to type 'MaybePromise<{ error: FormError<string> | null; value?: InferOutput<Schema>; }>'.

There's no immediate need to make this work. Let's go a step back:

as it creates a mismatch where client and server expect different schemas. I would love if there is a way to customize this on the server side

So would I. Even if there was a way to adapt the above validateSchema setup to zod v4, with the current API it wouldn't be very useful in practice: You would still have to remember not to manually put coerceFormValue into your useForm() calls, but still remember to put it into actions and loaders. This makes the overall code harder to grasp and explain.

I'm curious if at least in theory, a solution could be crafted that uniformly wraps schemas in coerceFormValue, so that the server and client schemas match.

Would it not be a natural fit to extend the scope of configureForms to the server as well? It would then return hooks for the client (like useForm), but also functions to be used on the server that take a schema and internally wrap it in coerceFormValue.

[edmundhung]

However, I get a type error on validateSchema:

Found some types issue. I will fix it later.

I'm curious if at least in theory, a solution could be crafted that uniformly wraps schemas in coerceFormValue, so that the server and client schemas match.

I am not against of this idea at all. I just don't have a good idea yet how this can fit into any of the existing APIs naturally, except re-introducing parseWithZod, which does the following:

1. Parse the form data: construct a payload based on the naming convention and extract the serialized intent (i.e. parseSubmission(formData))
2. Resolve the intent: update the payload based on the intent (i.e. resolveIntent(submission)) This is optional in the future API unless you want progressive enhancement.
3. Enhance the schema and validate the payload (i.e. coerceFormValue(schema).safeParse(submission.payload)/.safeParseAsync(submission.payload))
4. Format the validation result and prepare a json serializable value to return to client (i.e. report(submission, options)

[transparent-citizen]

For the consumer, it is useful that parseWithZod coerces your schema internally in v1.
parseWithZod being split up in v2 is useful for custom error handling, since it allows specialized calls to report.

Not sure if this is the right abstraction, but what I'm trying to show below is that report depends on submission so that its options.value can be typed properly. If submission and result were computed in one step, this could enable proper type inference:

// coerceFormValue(schema).safeParse(     submission.payload)
//                       /.safeParseAsync(submission.payload)
const { submission, result } = parseSubmission(schema, formData);

report(submission, options); // options.value: output<typeof schema>

The dependence between submission and report might even imply this abstraction:

const { submission, result } = parseSubmission(schema, formData);

submission.report(options); // options.value: output<typeof schema>

[edmundhung]

If the main problem here is just about accessing shape from the result schema. I think we can explore solution to makes it work with the result schema, e.g. wrapping the result schema in an object schema.

[transparent-citizen]

I already refactored my actions and loaders so that coerceFormValue(schema) is inlined, so at this point I don't use the return value for anything else than interacting with Conform. My main concern is that the consumer must manage the coexistence of a schema and its corresponding coerceFormValue(schema).

I think we can separate this discussion into individual concerns:

1. The return type of coerceFormValue should be truthful
2. The server API should allow for customization
3. report(submission, { value: ... }) should be type-safe
4. The consumer shouldn't have to manage schema and coerceFormValue(schema) if it can be avoided

The latter three are each worth their own discussion, but 1 seems like low-hanging fruit. I tried updating the return type from Schema to $ZodType<output<Schema>, input<Schema>>, and that does get rid of .shape, but it also loses .safeParse.

ZodMiniType<output<Schema>, input<Schema>> looks like it might be the right type. Do you have thoughts on this?

[edmundhung]

How about this: #1164

(FYI I answered your question in another thread above, not sure if you see that)

[transparent-citizen]

Today I learned about the nuance between $ZodType and ZodType. 😅

Thanks, this is looking great!

[edmundhung]

It's complicated because zod now have a mini variant. The $ZodType type is a shared interface which doesn't even have .safeParse() on it. If we wanna do it right, I might need yet another package export (i.e. @conform-to/zod/v4-mini for proper zod mini support 🙃