zod 4.5.3 → 4.6.0

package/src/v4/classic/tests/cyclic-data.test.ts

@@ -1,3 +1,5 @@
+import v8 from "node:v8";
+import vm from "node:vm";
 import { expect, test } from "vitest";
 import * as z from "zod/v4";
 
@@ -676,3 +678,317 @@ test("guards a transform built before any container", () => {
 
   expect(() => Wrapped.parse(input)).toThrow(/reference cycle/);
 });
+
+test("detects a cycle reachable only through a merged catchall", () => {
+  const Cyclic: any = z.object({
+    id: z.string(),
+    get next() {
+      return z.optional(Root);
+    },
+  });
+  const Root: any = z.object({ tag: z.string() }).merge(z.object({}).catchall(Cyclic));
+
+  const input: any = { tag: "root" };
+  input.child = { id: "1", next: input };
+
+  const out: any = Root.parse(input);
+  expect(out.child.next).toBe(out);
+});
+
+// the per-type switch can only enumerate kinds Zod ships, so an unknown `def.type` falls back to scanning the def; without it a cycle through a third-party container overflows the stack
+test("detects a cycle through a user-defined container type", () => {
+  const MyBox: any = z.core.$constructor("MyBox", (inst: any, def: any) => {
+    z.core.$ZodType.init(inst, def);
+    inst._zod.parse = (payload: any, ctx: any) => {
+      if (payload.value === null || typeof payload.value !== "object") return payload;
+      const inner = def.inner._zod.run({ value: payload.value.v, issues: [] }, ctx);
+      payload.value = { v: inner.value };
+      return payload;
+    };
+  });
+
+  const Node: any = z.object({
+    id: z.string(),
+    get boxed() {
+      return z.optional(new MyBox({ type: "mybox", inner: z.lazy(() => Node) }));
+    },
+  });
+
+  const input: any = { id: "1" };
+  input.boxed = { v: input };
+
+  const out: any = Node.parse(input);
+  expect(out.boxed.v).toBe(out);
+});
+
+// #6526: a factory returns fresh instances, so the identity walk never revisits a node; it descends until the stack overflows unless it stops at the deferred edge
+test("parses a factory-built recursive schema", () => {
+  const Node = (): any =>
+    z.object({
+      id: z.number(),
+      get kids() {
+        return z.array(Node());
+      },
+    });
+
+  const S = z.object({ root: Node() });
+  const out = S.parse({ root: { id: 1, kids: [{ id: 2, kids: [] }] } });
+  expect(out.root.kids[0].id).toBe(2);
+  expect(S.safeParse({ root: { id: 1, kids: [{ id: "x", kids: [] }] } }).success).toBe(false);
+});
+
+test("parses a factory-built recursive discriminated union at the root and nested", () => {
+  const Geometry = (): any =>
+    z.discriminatedUnion("type", [
+      z.object({ type: z.literal("Point"), coordinates: z.array(z.number()) }),
+      z.looseObject({
+        type: z.literal("GeometryCollection"),
+        get geometries() {
+          return z.array(Geometry());
+        },
+      }),
+    ]);
+
+  const collection = { type: "GeometryCollection", geometries: [{ type: "Point", coordinates: [1, 2] }] };
+  expect(Geometry().parse(collection).geometries[0].coordinates).toEqual([1, 2]);
+  expect(z.object({ g: Geometry() }).parse({ g: collection }).g.type).toBe("GeometryCollection");
+});
+
+test("the walk reports a cycle for a deferred edge instead of resolving it", () => {
+  const Node = (): any =>
+    z.object({
+      get self() {
+        return Node();
+      },
+    });
+  expect(z.core.isRecursiveSchema(Node())).toBe(true);
+
+  // conservative by design: a getter that closes no cycle is reported too, and pays only the memoizer it keeps
+  const Leaf = z.object({ id: z.string() });
+  const forward: any = z.object({
+    get leaf() {
+      return Leaf;
+    },
+  });
+  expect(z.core.isRecursiveSchema(forward)).toBe(true);
+
+  // a lazy is followed one hop, which is what lets z.compile see past it; past that hop it is deferred like any other edge
+  expect(z.core.isRecursiveSchema(z.lazy(() => Leaf) as any)).toBe(false);
+  expect(z.core.isRecursiveSchema(z.lazy(() => z.lazy(() => Leaf)) as any)).toBe(true);
+});
+
+// the builders answer `shape` from an accessor that resolves the source's getters, so the walk has to reach the source schema itself
+test("parses a factory-built recursive schema through every object builder", () => {
+  const wraps: [string, (base: () => any) => any][] = [
+    ["extend", (b) => b().extend({ x: z.string() })],
+    ["safeExtend", (b) => b().safeExtend({ x: z.string() })],
+    ["merge", (b) => z.object({ x: z.string() }).merge(b())],
+    ["partial", (b) => b().partial()],
+    ["required", (b) => b().required()],
+    ["pick", (b) => b().pick({ self: true })],
+    ["omit", (b) => b().omit({ y: true })],
+    ["chained", (b) => b().extend({ x: z.string() }).partial()],
+    // rebuilds the def without touching the shape, so the clone carries the source's accessor rather than a shape of its own
+    ["strict", (b) => b().extend({ x: z.string() }).strict()],
+    ["catchall", (b) => b().extend({ x: z.string() }).catchall(z.unknown())],
+    ["meta", (b) => b().extend({ x: z.string() }).meta({ id: "node" })],
+  ];
+
+  for (const [name, wrap] of wraps) {
+    const Node = (): any =>
+      wrap(() =>
+        z.object({
+          y: z.string(),
+          get self() {
+            return z.optional(Node());
+          },
+        })
+      );
+    const S = z.object({ r: Node() });
+    for (const attempt of ["first", "second"]) {
+      expect(() => S.safeParse({ r: { y: "s", x: "s" } }), `${name} (${attempt} parse)`).not.toThrow();
+    }
+  }
+});
+
+test("an ordinary builder stays exact, so it still compiles", () => {
+  const plain = z.object({ a: z.string(), b: z.number() });
+  const derived: [string, any][] = [
+    ["extend", plain.extend({ c: z.boolean() })],
+    ["merge", plain.merge(z.object({ d: z.string() }))],
+    ["partial", plain.partial()],
+    ["required", plain.partial().required()],
+    ["pick", plain.pick({ a: true })],
+    ["omit", plain.omit({ a: true })],
+    ["strict", plain.extend({ c: z.boolean() }).strict()],
+    ["catchall", plain.extend({ c: z.boolean() }).catchall(z.unknown())],
+    ["meta", plain.extend({ c: z.boolean() }).meta({ id: "plain" })],
+  ];
+  for (const [name, schema] of derived) {
+    expect(z.core.isRecursiveSchema(schema), name).toBe(false);
+    expect(() => z.compile(schema, { strict: true }), name).not.toThrow();
+  }
+});
+
+// a derived shape mirrors its source's descriptors, so dropping or overwriting the key that carries the cycle leaves nothing deferred and the walk is exact before anything parses
+test("a builder that drops the recursive key ends up exact", () => {
+  const Node: any = z.object({
+    id: z.number(),
+    get self() {
+      return z.optional(Node);
+    },
+  });
+
+  const derived: [string, any, any][] = [
+    ["omit", Node.omit({ self: true }), { id: 1 }],
+    ["pick", Node.pick({ id: true }), { id: 1 }],
+    ["extend overwrites it", Node.extend({ self: z.string() }), { id: 1, self: "x" }],
+  ];
+  for (const [name, schema, input] of derived) {
+    expect(z.core.isRecursiveSchema(schema), name).toBe(false);
+    expect(() => z.compile(schema, { strict: true }), name).not.toThrow();
+    expect(schema.parse(input), name).toEqual(input);
+  }
+
+  // the branch that stays is still found
+  const kept = Node.extend({ x: z.string() });
+  expect(z.core.isRecursiveSchema(kept)).toBe(true);
+});
+
+// resolving a lazy runs user code, which can re-enter the walk; a walk that kept its certainty outside its own frames would have the inner one clobber the outer
+test("a nested walk can't corrupt the one that resolved into it", () => {
+  const Node: any = z.object({
+    id: z.number(),
+    self: z.lazy(() => {
+      z.compile(z.string(), { strict: true });
+      return z.optional(Node);
+    }),
+  });
+
+  const omitted = Node.omit({ self: true });
+  // exact before anything parses: the mirrored shape kept only `id`, so nothing here is deferred
+  expect(z.core.isRecursiveSchema(omitted)).toBe(false);
+  omitted.parse({ id: 1 });
+  expect(z.core.isRecursiveSchema(omitted)).toBe(false);
+  expect(() => z.compile(omitted, { strict: true })).not.toThrow();
+
+  const shared = { id: 1 };
+  const out: any = z.object({ a: omitted, b: omitted }).parse({ a: shared, b: shared });
+  expect(out.a).not.toBe(out.b);
+  expect(z.core.isRecursiveSchema(Node)).toBe(true);
+});
+
+test("detects a cycle that closes through a builder", () => {
+  const Node: any = z
+    .object({
+      id: z.number(),
+      get self() {
+        return z.optional(Node);
+      },
+    })
+    .extend({ x: z.string() });
+
+  const input: any = { id: 1, x: "s" };
+  input.self = input;
+  const out = Node.parse(input);
+  expect(out.self).toBe(out);
+});
+
+test("a deferred edge stops being assumed a cycle once the graph resolves", () => {
+  const Leaf = z.object({ n: z.number() });
+  const Forward: any = z.object({
+    get a() {
+      return Leaf;
+    },
+  });
+  expect(z.core.isRecursiveSchema(Forward)).toBe(true);
+  Forward.parse({ a: { n: 1 } });
+  // the parse resolved the getter, so the walk can follow it and drop the assumption
+  expect(z.core.isRecursiveSchema(Forward)).toBe(false);
+
+  // a factory hands back a fresh subtree every time, so no parse ever resolves it into a finite graph
+  const Node = (): any =>
+    z.object({
+      get kids() {
+        return z.array(Node());
+      },
+    });
+  const Generated = Node();
+  expect(z.core.isRecursiveSchema(Generated)).toBe(true);
+  Generated.parse({ kids: [] });
+  expect(z.core.isRecursiveSchema(Generated)).toBe(true);
+
+  // a lazy that closes a real cycle stays recursive however often it resolves
+  const Cyclic: any = z.object({ id: z.number(), self: z.lazy(() => z.optional(Cyclic)) });
+  Cyclic.parse({ id: 1 });
+  expect(z.core.isRecursiveSchema(Cyclic)).toBe(true);
+});
+
+// `z.object` resolves its shape by spread, so a non-enumerable key is no part of it; `z.properties` reads every own key, so one there is still parsed and can still close a cycle
+test("a non-enumerable key counts for z.properties and not for z.object", () => {
+  const props = (enumerable: boolean) => {
+    const shape: Record<string, any> = { id: z.number() };
+    const P = z.properties(shape);
+    Object.defineProperty(shape, "next", { value: z.lazy(() => z.optional(P)), enumerable, configurable: true });
+    return P;
+  };
+  expect(z.core.isRecursiveSchema(props(true) as any)).toBe(true);
+  expect(z.core.isRecursiveSchema(props(false) as any)).toBe(true);
+
+  const object = (enumerable: boolean) => {
+    const shape: Record<string, any> = { id: z.number() };
+    const O: any = z.object(shape);
+    Object.defineProperty(shape, "next", { value: z.lazy(() => z.optional(O)), enumerable, configurable: true });
+    return O;
+  };
+  expect(z.core.isRecursiveSchema(object(true))).toBe(true);
+  // the spread drops it, so nothing can ever parse it
+  expect(z.core.isRecursiveSchema(object(false))).toBe(false);
+});
+
+test("the walk stays exact where nothing is deferred", () => {
+  let deep: any = z.string();
+  for (let i = 0; i < 300; i++) deep = z.object({ v: deep });
+  expect(z.core.isRecursiveSchema(deep)).toBe(false);
+});
+
+test("parses a factory-built recursive schema through z.lazy", () => {
+  const Node = (): any =>
+    z.object({
+      id: z.number(),
+      child: z.lazy(() => z.optional(Node())),
+    });
+
+  const out = z.object({ root: Node() }).parse({ root: { id: 1, child: { id: 2, child: undefined } } });
+  expect(out.root.child.id).toBe(2);
+});
+
+test("a finished parse pins nothing on the schema", async () => {
+  // es2020 is the target, and its lib predates WeakRef
+  type Weak<T extends object> = { deref(): T | undefined };
+  const { WeakRef: Weak } = globalThis as unknown as { WeakRef: new <T extends object>(target: T) => Weak<T> };
+  // vitest carries no --expose-gc, so reach the collector the way node's own tests do
+  v8.setFlagsFromString("--expose-gc");
+  const gc = vm.runInNewContext("gc") as () => void;
+
+  const Node: any = z.object({
+    id: z.number(),
+    get next() {
+      return z.optional(Node);
+    },
+  });
+
+  const ref = ((): Weak<object> => {
+    const input = { id: 1, next: { id: 2, next: undefined } };
+    Node.parse(input);
+    return new Weak(input);
+  })();
+
+  for (let attempt = 0; attempt < 10 && ref.deref(); attempt++) {
+    // the input stays on the stack until a macrotask boundary
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    gc();
+  }
+
+  expect(ref.deref()).toBeUndefined();
+});

package/src/v4/classic/tests/default.test.ts

@@ -407,3 +407,49 @@ test("direction-aware defaults", () => {
     }
   `);
 });
+
+test("default factory runs once per parse inside a container", () => {
+  let calls = 0;
+  const schema = z.object({
+    a: z.string().default(() => {
+      calls++;
+      return "d";
+    }),
+  });
+
+  expect(schema.parse({})).toEqual({ a: "d" });
+  expect(calls).toBe(1);
+
+  // the key is present, so the factory has nothing to produce
+  expect(schema.parse({ a: "given" })).toEqual({ a: "given" });
+  expect(calls).toBe(1);
+});
+
+test("prefault factory runs once per parse inside a container", () => {
+  let calls = 0;
+  const schema = z.object({
+    a: z.string().prefault(() => {
+      calls++;
+      return "d";
+    }),
+  });
+
+  expect(schema.parse({})).toEqual({ a: "d" });
+  expect(calls).toBe(1);
+});
+
+test("default factory does not run at compile time", () => {
+  let calls = 0;
+  const compiled = z.compile(
+    z.object({
+      a: z.string().default(() => {
+        calls++;
+        return "d";
+      }),
+    })
+  );
+
+  expect(calls).toBe(0);
+  expect(compiled.parse({})).toEqual({ a: "d" });
+  expect(calls).toBe(1);
+});

package/src/v4/classic/tests/enum.test.ts

@@ -87,6 +87,15 @@ test("enum from non-const inputs", () => {
 
 test("get options", () => {
   expect(z.enum(["tuna", "trout"]).options).toEqual(["tuna", "trout"]);
+
+  enum Fish {
+    Tuna = 0,
+    Trout = 1,
+  }
+
+  // numeric enums carry reverse-mapping keys; options lists only what parse accepts
+  expect(z.enum(Fish).options).toEqual([Fish.Tuna, Fish.Trout]);
+  expect(z.enum(Fish).safeParse("Tuna").success).toEqual(false);
 });
 
 test("readonly enum", () => {

package/src/v4/classic/tests/error.test.ts

@@ -1,5 +1,7 @@
 import { inspect, types } from "node:util";
-import { afterEach, expect, test, vi } from "vitest";
+import v8 from "node:v8";
+import vm from "node:vm";
+import { afterEach, describe, expect, test, vi } from "vitest";
 import * as z from "zod/v4";
 
 // Several tests install a global error map. Resetting on the last line of each leaks it into every later test in the file whenever an assertion above that line fails, which turns one real failure into a cascade.
@@ -977,3 +979,130 @@ test("error initializer never installs onto an intrinsic prototype", () => {
   expect({}.toString()).toEqual("[object Object]");
   expect(String(new Error("boom"))).toEqual("Error: boom");
 });
+
+describe("safeParse builds the error on first read", () => {
+  class CountingError {
+    static constructed = 0;
+    constructor(public issues: unknown[]) {
+      CountingError.constructed++;
+    }
+  }
+
+  test("constructs once, on read", () => {
+    CountingError.constructed = 0;
+    const result = z.core._safeParse(CountingError as any)(z.string(), 1) as any;
+    expect(result.success).toBe(false);
+    expect(CountingError.constructed).toBe(0);
+    const err = result.error;
+    expect(CountingError.constructed).toBe(1);
+    expect(result.error).toBe(err);
+    expect(CountingError.constructed).toBe(1);
+    expect(err.issues[0].code).toBe("invalid_type");
+  });
+
+  test("async variant", async () => {
+    CountingError.constructed = 0;
+    const result = (await z.core._safeParseAsync(CountingError as any)(z.string(), 1)) as any;
+    expect(CountingError.constructed).toBe(0);
+    expect(result.error).toBeInstanceOf(CountingError);
+    expect(CountingError.constructed).toBe(1);
+  });
+
+  test("result stays plain data", () => {
+    const result = z.string().safeParse(1);
+    expect(Object.keys(result)).toEqual(["success", "error"]);
+    expect(result).toEqual({ success: false, error: expect.any(z.ZodError) });
+    expect(structuredClone(result).error).toBeInstanceOf(Error);
+    const replaced = new z.ZodError([]);
+    (result as any).error = replaced;
+    expect(result.error).toBe(replaced);
+  });
+
+  test("reading the error releases the parsed input", async () => {
+    // es2020 is the target, and its lib predates WeakRef
+    type Weak<T extends object> = { deref(): T | undefined };
+    const { WeakRef: Weak } = globalThis as unknown as { WeakRef: new <T extends object>(target: T) => Weak<T> };
+    // vitest carries no --expose-gc, so reach the collector the way node's own tests do
+    v8.setFlagsFromString("--expose-gc");
+    const gc = vm.runInNewContext("gc") as () => void;
+
+    const schema = z.string();
+    const refs: Weak<object>[] = [];
+    const results: unknown[] = [];
+    for (let i = 0; i < 50; i++) {
+      const input = { i, blob: new Array(500).fill(i) };
+      refs.push(new Weak(input));
+      const result = schema.safeParse(input);
+      // half read the error, half replace it without ever reading; both have to release
+      if (i % 2) void result.error;
+      else (result as { error: z.core.$ZodError }).error = new z.ZodError([]);
+      results.push(result);
+    }
+    // the collector decides when it runs, so give it several passes; a retained input never clears no matter how many it gets
+    const live = () => refs.filter((ref) => ref.deref() !== undefined).length;
+    for (let attempt = 0; attempt < 10 && live() > 1; attempt++) {
+      // the loop's last input stays on the stack until a macrotask boundary
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      gc();
+    }
+    expect(live()).toBeLessThanOrEqual(1);
+    expect(results).toHaveLength(50);
+  });
+
+  test("no reader frames leak into the error, however late it is read", async () => {
+    const result = z.string().safeParse(12) as { error: z.core.$ZodError };
+
+    // the constructor runs at THIS read: a macrotask later and twenty frames deeper than the parse
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    const readDeep = <T>(n: number, make: () => T): T => (n ? readDeep(n - 1, make) : make());
+    const error = readDeep(20, () => result.error) as unknown as Error;
+
+    // control: a plain Error at that same depth does carry the frames, so the assertions below discriminate rather than pass vacuously
+    const control = readDeep(20, () => new Error("control"));
+    expect(control.stack!.split("\n").some((line) => line.trim().startsWith("at "))).toBe(true);
+    expect(control.stack!).toContain("readDeep");
+
+    expect(error.stack!.startsWith("ZodError: [")).toBe(true);
+    expect(error.stack!.split("\n").some((line) => line.trim().startsWith("at "))).toBe(false);
+    expect(error.stack!).not.toContain("readDeep");
+  });
+
+  test("a lazy build gives back the caller's stackTraceLimit, not the parse-time one", () => {
+    const result = z.string().safeParse(12) as { error: z.core.$ZodError };
+    const ambient = Error.stackTraceLimit;
+    // changed between the parse and the read, so restoring a value captured at parse time would clobber it
+    Error.stackTraceLimit = ambient + 7;
+    try {
+      void result.error;
+      expect(Error.stackTraceLimit).toBe(ambient + 7);
+    } finally {
+      Error.stackTraceLimit = ambient;
+    }
+  });
+});
+
+test("a finalized issue copies the raw issue's own keys only", () => {
+  const proto = { inherited: true };
+  const schema = z.string().check((ctx) => {
+    const raw = Object.create(proto);
+    Object.assign(raw, { code: "custom", message: "own", input: ctx.value, extra: 1 });
+    ctx.issues.push(raw);
+  });
+  const issue = schema.safeParse("x").error!.issues[0];
+  expect(issue).toStrictEqual({ code: "custom", message: "own", path: [], extra: 1 });
+  expect("inherited" in issue).toBe(false);
+  // own symbol-keyed fields are not copied either; nothing in zod produces one and the walk stays a string-key walk
+  const sym = Symbol("meta");
+  const symbolic = z.string().check((ctx) => {
+    ctx.issues.push({ code: "custom", message: "sym", input: ctx.value, [sym]: 1 } as never);
+  });
+  expect(Object.getOwnPropertySymbols(symbolic.safeParse("x").error!.issues[0])).toEqual([]);
+  // an own __proto__ key, as JSON.parse produces, neither swaps the prototype nor survives
+  const parsed = z.string().check((ctx) => {
+    ctx.issues.push(JSON.parse('{"code":"custom","message":"json","__proto__":{"polluted":true}}'));
+  });
+  const fromJson = parsed.safeParse("x").error!.issues[0];
+  expect(Object.getPrototypeOf(fromJson)).toBe(Object.prototype);
+  expect(Object.prototype.hasOwnProperty.call(fromJson, "__proto__")).toBe(false);
+  expect("polluted" in fromJson).toBe(false);
+});

package/src/v4/classic/tests/firstparty.test.ts

@@ -80,6 +80,8 @@ test("first party switch", () => {
       break;
     case "file":
       break;
+    case "properties":
+      break;
     case "lazy":
       break;
     case "function":
@@ -170,6 +172,8 @@ test("$ZodSchemaTypes", () => {
       break;
     case "lazy":
       break;
+    case "properties":
+      break;
     case "function":
       break;