Codec encode types and restrictions

[robbtraister]

My assumption is that

z.codec(a, b, { decode, encode })

is effectively implemented as

{
  decode: (val) => a.transform(decode).pipe(b).parse(val),
  encode: (val) => b.transform(encode).pipe(a).parse(val)
}

(with obvious caveats around safe, async, object wrappers, and any internal optimizations).

If this is the case, it leads to 2 questions:

• why is there a restriction on transforms during encoding?
• why are the types for the transform functions not mirrors of each other?
  the types here imply that decoding is performed as described above, while encoding is a direct pass-through of the provided function.
  https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/classic/schemas.ts#L1927-L1928

Here is a simple example that I expect to work, but fails type-checking because encode must return the output of A (i.e., string), rather than the input.

const codec = z.codec(
  z.coerce.string<string | number>(),
  z.coerce.number<number | string>(),
  {
    decode: (val) => val,
    encode: (val) => val, // <!-- val is string | number, but the return value requires string
  },
);

I assume this has to do with nested schemas, but the typing error in particular seems quite odd, especially when all of my runtime testing and repo spelunking suggests the behavior described above.

[dosubot[bot]]

You're correct that z.codec(a, b, { decode, encode }) is a bi-directional transformation, but the encode/decode types are intentionally asymmetric. The encode function must take the output type of schema B and return the output type of schema A—this ensures that the value produced by encode is valid for the input schema's .parse() method, maintaining round-trip type safety. That's why, in your example, encode must return a string (the output of z.coerce.string()), not just any input type like string | number—even if the runtime behavior seems to work as you expect. This is a deliberate design to enforce strong typing and validation guarantees at every stage, even during encoding. See the docs and implementation for details.

Transforms in Zod are unidirectional: if a schema uses .transform(), encoding will throw at runtime because transforms can't be safely reversed. This restriction prevents accidental misuse and ensures that encoding only happens through explicitly defined, reversible logic in codecs. More on this in the docs.

If you need to support a wider range of input types for encode, you may need to adjust your schemas or provide a custom encode function that ensures the output always matches the expected type for schema A. If you have further questions or want to discuss workarounds for specific cases, let me know! If this answers your question, feel free to close the issue.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}