Recursively Unwrapping a Schema in Zod 4

[zfm-lucaschultz]

I'm working on an app where we need to preprocess data before it is passed to a Zod schema. The preprocessing depends on the schema. It's a weird use case, I know, but we've successfully used this approach with v3 for a long time, and refactoring would be a major pain.

So anyway, I came up with this solution:

const isUwrappable = (
  schema: z.ZodType,
): schema is
  | z.ZodArray
  | z.ZodOptional
  | z.ZodNullable
  | z.ZodDefault
  | z.ZodPrefault
  | z.ZodNonOptional
  | z.ZodSuccess
  | z.ZodCatch
  | z.ZodReadonly
  | z.ZodLazy
  | z.ZodPromise => {
  return (
    schema instanceof z.ZodArray ||
    schema instanceof z.ZodOptional ||
    schema instanceof z.ZodNullable ||
    schema instanceof z.ZodDefault ||
    schema instanceof z.ZodPrefault ||
    schema instanceof z.ZodNonOptional ||
    schema instanceof z.ZodSuccess ||
    schema instanceof z.ZodCatch ||
    schema instanceof z.ZodReadonly ||
    schema instanceof z.ZodLazy ||
    schema instanceof z.ZodPromise
  );
};

const unwrap = (schema: z.ZodType): z.ZodType => {
  if (!(schema instanceof z.ZodType)) {
    throw new Error('Schema is not a ZodType');
  }

  if (isUwrappable(schema)) {
    const unwrapped = schema.unwrap();

    if (!(unwrapped instanceof z.ZodType)) {
      throw new Error('Unwrapped schema is not a ZodType');
    }

    return unwrap(unwrapped);
  }

  if (schema instanceof z.ZodPipe) {
    // Handle ZodPipe created by z.preprocess
    if (
      schema.def.out instanceof z.ZodType &&
      schema.def.in instanceof z.ZodTransform
    ) {
      return unwrap(schema.def.out);
    }

    // Handle ZodPipe created by z.transform
    if (
      schema.def.in instanceof z.ZodType &&
      schema.def.out instanceof z.ZodTransform
    ) {
      return unwrap(schema.def.in);
    }

    // If both `in` and `out` are ZodTypes, prefer to unwrap `in` because
    // that's relevant for form schema preprocessing
    if (
      schema.def.in instanceof z.ZodType &&
      schema.def.out instanceof z.ZodType
    ) {
      return unwrap(schema.def.in);
    }

    if (schema.def.in instanceof z.ZodType) {
      return unwrap(schema.def.in);
    }

    if (schema.def.out instanceof z.ZodType) {
      return unwrap(schema.def.out);
    }

    throw new Error(
      'Cannot unwrap ZodPipe, neither `in` nor `out` is a ZodType',
    );
  }

  return schema;
};

This, of course, makes two assumptions I'm not entirely sure are correct:

1. Every schema in Zod is an instance of z.ZodType.
2. Either in or out of a z.ZodPipe created by preprocess and transform is always a z.ZodTransform, and the other is a z.ZodType.

Are these assumptions correct? Is there something else that can be improved?

Thank you for your help ✌️

EDIT: I'm aware that we can manually create a z.ZodPipe where in and out are both a z.ZodType:

const both = z.number().pipe(z.number().transform((n) => n * 2));

but fortunately that isn't relevant for us.

[inkeep-ai-assistant[bot]]

Your first assumption—that every schema in Zod 4 is an instance of z.ZodType—is correct. In Zod 4, all schema classes inherit from the ZodType base class, which now uses the signature class ZodType<Output = unknown, Input = unknown> and does not require the Def generic from v3(1)(2).

Regarding your second assumption about ZodPipe, Zod 4 introduces a dedicated ZodPipe class for composed transforms. The .transform() and z.preprocess() methods now return a ZodPipe instance. In a ZodPipe, the internals (def.in and def.out) can be either ZodType or ZodTransform. The structure is as follows:

• .transform() returns ZodPipe<ZodString, ZodTransform>
• z.preprocess(val => val, z.string()) returns ZodPipe<ZodTransform, ZodString>

So, either def.in or def.out can be a ZodTransform, but not both at the same time. Your check covers the valid combinations(2).

Additionally, the unwrap() method is available on wrappers like ZodOptional, ZodNullable, and so on—your use of .unwrap() aligns with the intended API(3)(4).

In summary:

• All Zod schemas are instances of ZodType in v4(1)(2).
• In ZodPipe, either def.in or def.out will be a ZodTransform, and the other will be a ZodType(2).
• Your recursive unwrapping logic matches the structure and behavior described in Zod 4's documentation and migration guide(2)(3)(4).

📚 Sources:

1. Zod v4 LLMs-Full
2. Migration guide
3. Zod v4 LLMs-Full
4. Zod v4 LLMs-Full

---

Have another question? Just tag @inkeep.