Zod deep strict and `deepPartial` utility

zod-deep-strict-partial.ts

/*
   Copyright 2024, Jaen - https://github.com/jaens

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

import { z, type ZodDiscriminatedUnionOption } from "zod";

const RESOLVING = Symbol("mapOnSchema/resolving");

export function mapOnSchema<T extends z.ZodTypeAny, TResult extends z.ZodTypeAny>(
    schema: T,
    fn: (schema: z.ZodTypeAny) => TResult,
): TResult;

/** 
 * Applies {@link fn} to each element of the schema recursively, replacing every schema with its return value.
 * The rewriting is applied bottom-up (ie. {@link fn} will get called on "children" first).
 */
export function mapOnSchema(schema: z.ZodTypeAny, fn: (schema: z.ZodTypeAny) => z.ZodTypeAny): z.ZodTypeAny {
    // Cache results to support recursive schemas
    const results = new Map<z.ZodTypeAny, z.ZodTypeAny | typeof RESOLVING>();

    function mapElement(s: z.ZodTypeAny) {
        const value = results.get(s);
        if (value === RESOLVING) {
            throw new Error("Recursive schema access detected");
        } else if (value !== undefined) {
            return value;
        }

        results.set(s, RESOLVING);
        const result = mapOnSchema(s, fn);
        results.set(s, result);
        return result;
    }

    function mapInner() {
        if (schema instanceof z.ZodObject) {
            const newShape: Record<string, z.ZodTypeAny> = {};
            for (const [key, value] of Object.entries(schema.shape)) {
                newShape[key] = mapElement(value as z.ZodTypeAny);
            }

            return new z.ZodObject({
                ...schema._def,
                shape: () => newShape,
            });
        } else if (schema instanceof z.ZodArray) {
            return new z.ZodArray({
                ...schema._def,
                type: mapElement(schema._def.type),
            });
        } else if (schema instanceof z.ZodMap) {
            return new z.ZodMap({
                ...schema._def,
                keyType: mapElement(schema._def.keyType),
                valueType: mapElement(schema._def.valueType),
            });
        } else if (schema instanceof z.ZodSet) {
            return new z.ZodSet({
                ...schema._def,
                valueType: mapElement(schema._def.valueType),
            });
        } else if (schema instanceof z.ZodOptional) {
            return new z.ZodOptional({
                ...schema._def,
                innerType: mapElement(schema._def.innerType),
            });
        } else if (schema instanceof z.ZodNullable) {
            return new z.ZodNullable({
                ...schema._def,
                innerType: mapElement(schema._def.innerType),
            });
        } else if (schema instanceof z.ZodDefault) {
            return new z.ZodDefault({
                ...schema._def,
                innerType: mapElement(schema._def.innerType),
            });
        } else if (schema instanceof z.ZodReadonly) {
            return new z.ZodReadonly({
                ...schema._def,
                innerType: mapElement(schema._def.innerType),
            });
        } else if (schema instanceof z.ZodLazy) {
            return new z.ZodLazy({
                ...schema._def,
                // NB: This leaks `fn` into the schema, but there is no other way to support recursive schemas
                getter: () => mapElement(schema._def.getter()),
            });
        } else if (schema instanceof z.ZodBranded) {
            return new z.ZodBranded({
                ...schema._def,
                type: mapElement(schema._def.type),
            });
        } else if (schema instanceof z.ZodEffects) {
            return new z.ZodEffects({
                ...schema._def,
                schema: mapElement(schema._def.schema),
            });
        } else if (schema instanceof z.ZodFunction) {
            return new z.ZodFunction({
                ...schema._def,
                args: schema._def.args.map((arg: z.ZodTypeAny) => mapElement(arg)),
                returns: mapElement(schema._def.returns),
            });
        } else if (schema instanceof z.ZodPromise) {
            return new z.ZodPromise({
                ...schema._def,
                type: mapElement(schema._def.type),
            });
        } else if (schema instanceof z.ZodCatch) {
            return new z.ZodCatch({
                ...schema._def,
                innerType: mapElement(schema._def.innerType),
            });
        } else if (schema instanceof z.ZodTuple) {
            return new z.ZodTuple({
                ...schema._def,
                items: schema._def.items.map((item: z.ZodTypeAny) => mapElement(item)),
                rest: schema._def.rest && mapElement(schema._def.rest),
            });
        } else if (schema instanceof z.ZodDiscriminatedUnion) {
            const optionsMap = new Map(
                [...schema.optionsMap.entries()].map(([k, v]) => [
                    k,
                    mapElement(v) as ZodDiscriminatedUnionOption<string>,
                ]),
            );

            return new z.ZodDiscriminatedUnion({
                ...schema._def,
                options: [...optionsMap.values()],
                optionsMap: optionsMap,
            });
        } else if (schema instanceof z.ZodUnion) {
            return new z.ZodUnion({
                ...schema._def,
                options: schema._def.options.map((option: z.ZodTypeAny) => mapElement(option)),
            });
        } else if (schema instanceof z.ZodIntersection) {
            return new z.ZodIntersection({
                ...schema._def,
                right: mapElement(schema._def.right),
                left: mapElement(schema._def.left),
            });
        } else if (schema instanceof z.ZodRecord) {
            return new z.ZodRecord({
                ...schema._def,
                keyType: mapElement(schema._def.keyType),
                valueType: mapElement(schema._def.valueType),
            });
        } else {
            return schema;
        }
    }

    return fn(mapInner());
}

export function deepPartial<T extends z.ZodTypeAny>(schema: T): T {
    return mapOnSchema(schema, (s) => (s instanceof z.ZodObject ? s.partial() : s)) as T;
}

/** Make all object schemas "strict" (ie. fail on unknown keys), except if they are marked as `.passthrough()` */
export function deepStrict<T extends z.ZodTypeAny>(schema: T): T {
    return mapOnSchema(schema, (s) =>
        s instanceof z.ZodObject && s._def.unknownKeys !== "passthrough" ? s.strict() : s,
    ) as T;
}

export function deepStrictAll<T extends z.ZodTypeAny>(schema: T): T {
    return mapOnSchema(schema, (s) => (s instanceof z.ZodObject ? s.strict() : s)) as T;
}

This is missing ZodDefault. Is that not necessary? I noticed this when I created another implementation to dynamically (and with async) walk and modify the schema where I had someOtherObjectSchema.array().default([]).

My solution adds this:

    } else if (schema instanceof z.ZodDefault) {
      const innerType = mapElement(schema.removeDefault());
      return z.ZodDefault.create(innerType, { default: schema._def.defaultValue });

@kernwig That's interesting...

The type list is from the official Zod source code, so if you needed that, it implies that the deepPartialify implementation in Zod itself is buggy.

Indeed, analyzing the rest of the source code of Zod, this (and deepPartialify) is also missing ZodLazy and ZodEffects and a bunch of other stuff.

@jaens I did indeed need it for an applications where I dynamically add a superRefine to some string properties that may have a default value, or a string property on an object inside of an array that defaults to empty.

Aside: Because my callback fn needs to call an API to fetch the list of valid string values, I had to implement an async version of mapOnSchema.

Just discovered that this function is why my object properties loose their z.describe() values when I use zod-to-openapi to create OpenAPI.

I fixed by adding { ...schema._def } as the second parameter to all of the z.Zod<thing>.create() function calls, thus preserving not only the description but errorMap, invalid_type_error, and required_error.

I updated the code to account for all known flaws. The usage of .create() was removed to be more "extension-proof".

Aside: Because my callback fn needs to call an API to fetch the list of valid string values, I had to implement an async version of mapOnSchema.

I mean, technically might not be necessary, it can be done in three passes (since the mapping order is deterministic, unless using lazy schemas):

1. Use mapOnSchema with the identity function, but as a side-effect, push all required requests into an eg. array (as promises).
2. Await all the promises in the array, into a new resolved one.
3. Run mapOnSchema again, this time reading the resolved values from the array (with an incrementing index).

Updated the solution to with more details and a license.

@jaens Thanks for the update. Will be great if you can add JS doc comments to all exported functions to clearly differentiate their usage.

Looks time to turn this gist into a published library.

Good job up there!

However, I encounter a bug with array of union objects. Works only first type in union:

The test

import { z } from "zod";

import { deepPartial } from "./zodDeep.utils";

const schema = z.object({
  arr: z.array(
    z.union([
      z.object({
        union1_Key1: z.string(),
        union1_Key2: z.number(),
      }),
      z.object({
        union2_Key1: z.string(),
        union2_Key2: z.number(),
      }),
    ]),
  ),
});

const data = {
  arr: [
    // {
    //   union1_Key1: "d",
    //   union1_Key2: 2,
    // },
    {
      union2_Key1: "f",
      union2_Key2: 3,
    },
  ],
};

describe("zodDeep.utils", () => {
  it("shoud make schema optional and result in sucess parse", () => {
    const _schema = deepPartial(schema);
    // const _schema = schema;

    expect(_schema.parse(data)).toEqual(data);
  });
});

Test result

---

UPD: just realized that simple union objects doesn't work either

Simple union test

const union1Schema = z.union([
  z.object({ union1_Key1: z.string(), union1_Key2: z.number() }),
  z.object({ union2_Key1: z.string(), union2_Key2: z.number() }),
]);

const unionData = { union2_Key1: "f", union2_Key2: 3 };

it("shoud make schema optional and result in sucess parse", () => {
  const _schema = deepPartial(union1Schema);
  // const _schema = union1Schema;

  expect(_schema.parse(unionData)).toEqual(unionData);
});

@Alexander-ilyin3 No, this library does work perfectly (ie. outputs the "correct" schema) in this case.

You just missed the fact that this is in fact how Zod works:

const union1SchemaPartial = z.union([
    z.object({ union1_Key1: z.string(), union1_Key2: z.number() }).partial(), // <<<<< NB
    z.object({ union2_Key1: z.string(), union2_Key2: z.number() }).partial(), // <<<<< NB
]);

const unionData = { union2_Key1: "f", union2_Key2: 3 };

test("should make schema optional and result in sucess parse", () => {
    // Nope, this is not how Zod works
    expect(union1SchemaPartial.parse(unionData)).toEqual(unionData);
});

To explain:

Zod will choose the first successful parse from an union. Since an empty object is a successful parse of an object with all keys optional (and also type-correct), the empty object is a perfectly "valid" result. (although unintuitive)

For this and many other reasons, in well-designed APIs, all unions should have at least 1 non-optional field, eg. a discriminator.
(or have completely non-overlapping types, eg. a string and an object)

If you want to union objects, do it via .merge() or .extend() etc. instead.

Ok. I guess I using it the wrong way then.

What I was trying to do is to make the first parse regular, then if that catches an error try to do deepPartial on a schema and then try to parse it that way.
So: try return schema.parse(data) catch try return deepPartial(schema).parse(data) catch return data.

The purpose was to not throw an error when some of the fields are missing because of the unstable backend. Just for application to try to work with DTOs "as is" and at the same time to evaluate .transform() on schemas that uses it. And if that fails, well, you on your own with the raw data.

Vanilla zod will not do a transform on a second schema in union if first passes the validation. Wow. That is so unfortunate... But it perfectly makes sense for me now

I realized that I need to write another type of Frankenstein in my case. And also became a better developer