zod 4.5.4 → 4.6.0

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

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "vitest";
+import * as z from "zod";
+
+describe("z.iban", () => {
+  const valid: [string, string][] = [
+    ["Norway (15, minimum)", "NO9386011117947"],
+    ["Belgium (16)", "BE68539007547034"],
+    ["Netherlands (18)", "NL91ABNA0417164300"],
+    ["Germany (22)", "DE89370400440532013000"],
+    ["Great Britain (22)", "GB29NWBK60161331926819"],
+    ["Turkey (26)", "TR610000100000000000000001"],
+    ["France (27)", "FR1420041010050500013M02606"],
+    ["Cyprus (28)", "CY17002001280000001200527600"],
+    ["Malta (31)", "MT84MALT011000012345MTLCAST001S"],
+    ["Maximum length (34)", "AA73AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"],
+    ["Maximum length mixed (34)", "ZZ560123456789ABCDEFGHIJKLMNOPQRST"],
+  ];
+
+  test.each(valid)("accepts %s", (_label, n) => {
+    expect(z.iban().parse(n)).toBe(n);
+  });
+
+  test("rejects lowercase characters", () => {
+    expect(() => z.iban().parse("no9386011117947")).toThrow();
+    expect(() => z.iban().parse("de89370400440532013000")).toThrow();
+    expect(() => z.iban().parse("FR1420041010050500013m02606")).toThrow();
+  });
+
+  test("rejects spaces and hyphens", () => {
+    expect(() => z.iban().parse("NO93 8601 1117 947")).toThrow();
+    expect(() => z.iban().parse(" DE89370400440532013000")).toThrow();
+    expect(() => z.iban().parse("DE89370400440532013000 ")).toThrow();
+    expect(() => z.iban().parse("NO93-8601-1117-947")).toThrow();
+    expect(() => z.iban().parse("DE89-3704-0044-0532-0130-00")).toThrow();
+  });
+
+  test("rejects special characters", () => {
+    expect(() => z.iban().parse("NO938601111794!")).toThrow();
+    expect(() => z.iban().parse("DE8937040044053201300@")).toThrow();
+    expect(() => z.iban().parse("")).toThrow();
+  });
+
+  test("rejects inputs outside length bounds (15-34)", () => {
+    expect(() => z.iban().parse("NO938601111794")).toThrow();
+    expect(() => z.iban().parse("AA73AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")).toThrow();
+  });
+
+  test("rejects invalid check digits (checksum failure)", () => {
+    expect(() => z.iban().parse("NO9386011117948")).toThrow();
+    expect(() => z.iban().parse("DE89370400440532013001")).toThrow();
+    expect(() => z.iban().parse("FR1420041010050500013M02607")).toThrow();
+  });
+
+  test("rejects check digits outside 02-98", () => {
+    // mod 97 alone accepts all three; `98 - remainder` can only ever emit 02-98
+    expect(() => z.iban().parse("DE00000000000000000066")).toThrow();
+    expect(() => z.iban().parse("DE01000000000000000048")).toThrow();
+    expect(() => z.iban().parse("DE99000000000000000030")).toThrow();
+  });
+
+  test("carries the shape regex as its JSON Schema pattern", () => {
+    expect(z.toJSONSchema(z.iban())).toMatchObject({
+      format: "iban",
+      pattern: z.regexes.iban.source,
+    });
+  });
+
+  test("round-trips through JSON Schema with the checksum intact", () => {
+    const schema = z.fromJSONSchema(z.toJSONSchema(z.iban()));
+    expect(schema.safeParse("DE89370400440532013000").success).toBe(true);
+    expect(schema.safeParse("DE89370400440532013001").success).toBe(false);
+  });
+
+  test("error message references IBAN", () => {
+    const result = z.iban().safeParse("not-an-iban");
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0]?.message).toMatch(/IBAN/i);
+    }
+  });
+});

package/src/v4/classic/tests/instance-footprint.test.ts

@@ -152,10 +152,16 @@ test("a live member keeps the descriptor a prototype member had", () => {
   const proto = Object.getPrototypeOf(z.string());
   expect(Object.getOwnPropertyDescriptor(proto, "description")?.enumerable).toBe(false);
   expect(Object.getOwnPropertyDescriptor(proto, "_def")?.enumerable).toBe(false);
+  // a derived member installs like a literal's accessor: not enumerable, still configurable
+  expect(Object.getOwnPropertyDescriptor(proto, "minLength")).toMatchObject({ enumerable: false, configurable: true });
 
+  // the derived metadata members live on the prototype and shadow as own data on first read
+  const schema = z.string();
   const keys: string[] = [];
-  for (const k in z.string()) keys.push(k);
-  expect(keys).toEqual(["def", "type", "format", "minLength", "maxLength"]);
+  for (const k in schema) keys.push(k);
+  expect(keys).toEqual(["def", "type"]);
+  expect(schema.minLength).toBe(null);
+  expect(Object.keys(schema)).toContain("minLength");
 });
 
 test("a live member is not cached per instance", () => {
@@ -221,6 +227,16 @@ test("a hand-written getter member accepts assignment", () => {
   const mini: any = zm.string();
   mini.with = () => "WITH";
   expect(mini.with()).toBe("WITH");
+
+  // a derived metadata member accepts assignment before its first read, as it did as an own property
+  const derived = z.number().min(2);
+  derived.minValue = 99;
+  expect(derived.minValue).toBe(99);
+  expect(Object.keys(derived)).toContain("minValue");
+
+  // and, like every prototype member, recomputes after deletion rather than staying absent
+  delete (derived as any).minValue;
+  expect(derived.minValue).toBe(2);
 });
 
 test("shape is lazy and stays out of Object.keys", () => {

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

@@ -62,7 +62,7 @@ test("instanceof respects customError", () => {
 test("z.properties", () => {
   const httpsUrl = z.instanceof(URL).check(
     ...z.properties({
-      protocol: z.literal("https:" as string),
+      protocol: z.literal("https:"),
       hostname: z.string().regex(z.regexes.domain),
     })
   );
@@ -70,9 +70,9 @@ test("z.properties", () => {
   expectTypeOf<URL>().toEqualTypeOf<z.infer<typeof httpsUrl>>();
   expect(httpsUrl.safeParse(new URL("https://example.com")).success).toBe(true);
 
-  // Checks abort on the first failure, exactly as the equivalent chain of z.property() calls does.
+  // One check iterates the whole shape, so every failing property reports — unlike the equivalent chain of z.property() calls, which aborts on the first.
   const both = httpsUrl.safeParse(new URL("http://localhost"));
-  expect(both.error!.issues.map((i) => i.path)).toEqual([["protocol"]]);
+  expect(both.error!.issues.map((i) => i.path)).toEqual([["protocol"], ["hostname"]]);
 
   // A failing base schema yields its own issue and no property issues.
   for (const input of ["not a url", null]) {
@@ -85,12 +85,12 @@ test("z.properties", () => {
     .object({ a: z.string(), b: z.string() })
     .check(...z.properties({ a: z.literal("x"), b: z.literal("y") }));
   expect(obj.safeParse({ a: "x", b: "y" }).success).toBe(true);
-  expect(obj.safeParse({ a: "!", b: "!" }).error!.issues.map((i) => i.path)).toEqual([["a"]]);
+  expect(obj.safeParse({ a: "!", b: "!" }).error!.issues.map((i) => i.path)).toEqual([["a"], ["b"]]);
   for (const input of [null, undefined, 5]) {
     expect(obj.safeParse(input).error!.issues.map((i) => [i.code, i.path])).toEqual([["invalid_type", []]]);
   }
 
-  // Known looseness versus the longhand, pinned so it stays deliberate: every element is typed over the whole shape, and `$ZodCheckInternals.check()` is a method, so TypeScript compares it bivariantly and accepts a check type that is a subtype of the target. Naming a key the target lacks therefore compiles here and fails at parse time, where the equivalent chain of `z.property()` calls rejects it outright. Typing each element over only its own key fixes that and breaks every valid call, since a union argument must satisfy the target on its own.
+  // Known looseness versus the longhand, pinned so it stays deliberate: the schema-as-check is typed over the whole shape, and `$ZodCheckInternals.check()` is a method, so TypeScript compares it bivariantly and accepts a check type that is a subtype of the target. Naming a key the target lacks therefore compiles here and fails at parse time, where the equivalent chain of `z.property()` calls rejects it outright.
   z.object({ a: z.string() }).check(...z.properties({ a: z.literal("x"), b: z.literal("y") }));
   expect(
     z
@@ -100,8 +100,28 @@ test("z.properties", () => {
       .error!.issues.map((i) => [i.code, i.path])
   ).toEqual([["invalid_value", ["b"]]]);
 
-  // Plain property checks carry no `when`, so the schema stays on the compiled fast path.
+  // literal and enum inputs widen to their primitive, so a `string`/`boolean` property accepts them without a cast, while a genuine type mismatch or an unknown key still fails to compile
+  z.instanceof(URL).check(z.property("protocol", z.literal("https:")));
+  z.instanceof(Request).check(...z.properties({ method: z.enum(["POST", "PUT"]), bodyUsed: z.literal(false) }));
+  // @ts-expect-error length is a number
+  z.string().check(z.property("length", z.string()));
+  // @ts-expect-error no such key
+  z.instanceof(URL).check(z.property("nope", z.string()));
+
+  // the check feeds the property value into its schema, so it is typed over the input side rather than the output
+  const stringToLength = z.property(
+    "a",
+    z.string().transform((s) => s.length)
+  );
+  z.object({ a: z.string() }).check(stringToLength);
+  // @ts-expect-error a is a number, the schema takes a string
+  z.object({ a: z.number() }).check(stringToLength);
+
+  // The properties check carries no `when`, so the schema stays on the compiled fast path.
   const compiled = z.compile(httpsUrl);
   expect(compiled.safeParse(new URL("https://example.com")).success).toBe(true);
-  expect(compiled.safeParse(new URL("http://localhost")).error!.issues.map((i) => i.path)).toEqual([["protocol"]]);
+  expect(compiled.safeParse(new URL("http://localhost")).error!.issues.map((i) => i.path)).toEqual([
+    ["protocol"],
+    ["hostname"],
+  ]);
 });

package/src/v4/classic/tests/issue-schema.test.ts

@@ -5,6 +5,9 @@ afterEach(() => {
   z.config({ customError: undefined });
 });
 
+/** Error maps run on the first read of `error`, so a test that only observes them reads it. */
+const fail = (r: { error?: unknown }) => r.error;
+
 /** Collects the owning schema's registered metadata for every issue an error map sees. */
 function captureMeta(): { seen: (z.core.GlobalMeta | undefined)[] } {
   const seen: (z.core.GlobalMeta | undefined)[] = [];
@@ -20,11 +23,11 @@ function captureMeta(): { seen: (z.core.GlobalMeta | undefined)[] } {
 test("check-originated issues expose the owning schema", () => {
   const { seen } = captureMeta();
 
-  z.object({ name: z.string().min(5).meta({ title: "Name" }) }).safeParse({ name: "ab" });
-  z.string().max(2).meta({ title: "Max" }).safeParse("abc");
-  z.email().meta({ title: "Email" }).safeParse("nope");
-  z.number().multipleOf(3).meta({ title: "Multiple" }).safeParse(4);
-  z.array(z.string()).min(2).meta({ title: "Array" }).safeParse([]);
+  fail(z.object({ name: z.string().min(5).meta({ title: "Name" }) }).safeParse({ name: "ab" }));
+  fail(z.string().max(2).meta({ title: "Max" }).safeParse("abc"));
+  fail(z.email().meta({ title: "Email" }).safeParse("nope"));
+  fail(z.number().multipleOf(3).meta({ title: "Multiple" }).safeParse(4));
+  fail(z.array(z.string()).min(2).meta({ title: "Array" }).safeParse([]));
 
   expect(seen).toEqual([
     { title: "Name" },
@@ -38,8 +41,8 @@ test("check-originated issues expose the owning schema", () => {
 test("schema-originated issues expose the owning schema", () => {
   const { seen } = captureMeta();
 
-  z.object({ name: z.string().min(5).meta({ title: "Name" }) }).safeParse({ name: 123 });
-  z.email().meta({ title: "Email" }).safeParse(123);
+  fail(z.object({ name: z.string().min(5).meta({ title: "Name" }) }).safeParse({ name: 123 }));
+  fail(z.email().meta({ title: "Email" }).safeParse(123));
 
   expect(seen).toEqual([{ title: "Name" }, { title: "Email" }]);
 });
@@ -47,14 +50,20 @@ test("schema-originated issues expose the owning schema", () => {
 test("refinements attribute to the refined schema, not the internal check schema", () => {
   const { seen } = captureMeta();
 
-  z.string()
-    .refine(() => false)
-    .meta({ title: "Refine" })
-    .safeParse("abc");
-  z.string()
-    .superRefine((_, ctx) => ctx.addIssue({ code: "custom", message: "" }))
-    .meta({ title: "SuperRefine" })
-    .safeParse("abc");
+  fail(
+    z
+      .string()
+      .refine(() => false)
+      .meta({ title: "Refine" })
+      .safeParse("abc")
+  );
+  fail(
+    z
+      .string()
+      .superRefine((_, ctx) => ctx.addIssue({ code: "custom", message: "" }))
+      .meta({ title: "SuperRefine" })
+      .safeParse("abc")
+  );
 
   expect(seen).toEqual([{ title: "Refine" }, { title: "SuperRefine" }]);
 });
@@ -62,17 +71,26 @@ test("refinements attribute to the refined schema, not the internal check schema
 test("the innermost schema owns the issue", () => {
   const { seen } = captureMeta();
 
-  z.array(z.string().min(5).meta({ title: "Element" }))
-    .meta({ title: "Array" })
-    .safeParse(["ab"]);
-  z.string()
-    .pipe(z.string().min(5).meta({ title: "Target" }))
-    .meta({ title: "Pipe" })
-    .safeParse("ab");
-  z.looseObject({})
-    .check(z.property("a", z.string().meta({ title: "Property" })))
-    .meta({ title: "Object" })
-    .safeParse({ a: 1 });
+  fail(
+    z
+      .array(z.string().min(5).meta({ title: "Element" }))
+      .meta({ title: "Array" })
+      .safeParse(["ab"])
+  );
+  fail(
+    z
+      .string()
+      .pipe(z.string().min(5).meta({ title: "Target" }))
+      .meta({ title: "Pipe" })
+      .safeParse("ab")
+  );
+  fail(
+    z
+      .looseObject({})
+      .check(z.property("a", z.string().meta({ title: "Property" })))
+      .meta({ title: "Object" })
+      .safeParse({ a: 1 })
+  );
 
   expect(seen).toEqual([{ title: "Element" }, { title: "Target" }, { title: "Property" }]);
 });
@@ -81,12 +99,15 @@ test("issues carrying no usable `inst` still get the owning schema", () => {
   const { seen } = captureMeta();
 
   // A hand-pushed issue may carry no inst at all, and ctx.addIssue(string) puts the check's def — not a Zod object — on inst.
-  z.string()
-    .check((payload) => {
-      payload.issues.push({ code: "custom", input: payload.value });
-    })
-    .meta({ title: "Bare" })
-    .safeParse("abc");
+  fail(
+    z
+      .string()
+      .check((payload) => {
+        payload.issues.push({ code: "custom", input: payload.value });
+      })
+      .meta({ title: "Bare" })
+      .safeParse("abc")
+  );
   const shorthand = z
     .string()
     .superRefine((_, ctx) => ctx.addIssue("bad stuff"))
@@ -100,11 +121,13 @@ test("issues carrying no usable `inst` still get the owning schema", () => {
 test("async checks expose the owning schema", async () => {
   const { seen } = captureMeta();
 
-  await z
-    .string()
-    .refine(async () => false)
-    .meta({ title: "Async" })
-    .safeParseAsync("abc");
+  fail(
+    await z
+      .string()
+      .refine(async () => false)
+      .meta({ title: "Async" })
+      .safeParseAsync("abc")
+  );
 
   expect(seen).toEqual([{ title: "Async" }]);
 });
@@ -120,7 +143,7 @@ test("the owning schema is the clone `.meta()` registered, not the pre-metadata
     },
   });
 
-  labeled.safeParse("ab");
+  fail(labeled.safeParse("ab"));
 
   expect(seen).toEqual([true]);
 });
@@ -134,12 +157,12 @@ test("`inst` keeps its meaning and `schema` stays off the finalized issue", () =
     },
   });
 
-  const tooSmall = z.string().min(5).safeParse("ab");
-  const wrongType = z.string().safeParse(123);
+  const tooSmall = z.string().min(5).safeParse("ab").error!;
+  const wrongType = z.string().safeParse(123).error!;
 
   expect(insts).toEqual(["$ZodCheckMinLength", "ZodString"]);
-  expect(Object.keys(tooSmall.error!.issues[0])).not.toContain("schema");
-  expect(Object.keys(wrongType.error!.issues[0])).not.toContain("schema");
+  expect(Object.keys(tooSmall.issues[0])).not.toContain("schema");
+  expect(Object.keys(wrongType.issues[0])).not.toContain("schema");
 });
 
 test("every error map kind receives the owning schema", () => {
@@ -149,28 +172,37 @@ test("every error map kind receives the owning schema", () => {
     return undefined;
   };
 
-  z.string()
-    .min(5, { error: capture("check") })
-    .meta({ title: "Check" })
-    .safeParse("ab");
+  fail(
+    z
+      .string()
+      .min(5, { error: capture("check") })
+      .meta({ title: "Check" })
+      .safeParse("ab")
+  );
 
   // A schema-bound map is only consulted for issues the schema itself raised, so this one needs a type error.
-  z.string({ error: capture("schema") })
-    .meta({ title: "Schema" })
-    .safeParse(123);
-
-  z.string()
-    .min(5)
-    .meta({ title: "Parse" })
-    .safeParse("ab", { error: capture("parse") });
+  fail(
+    z
+      .string({ error: capture("schema") })
+      .meta({ title: "Schema" })
+      .safeParse(123)
+  );
+
+  fail(
+    z
+      .string()
+      .min(5)
+      .meta({ title: "Parse" })
+      .safeParse("ab", { error: capture("parse") })
+  );
 
   z.config({ customError: capture("customError") });
-  z.string().min(5).meta({ title: "Custom" }).safeParse("ab");
+  fail(z.string().min(5).meta({ title: "Custom" }).safeParse("ab"));
 
   // localeError carries the default English locale, so it is restored rather than cleared.
   const localeError = z.config().localeError;
   z.config({ customError: undefined, localeError: capture("localeError") });
-  z.string().min(5).meta({ title: "Locale" }).safeParse("ab");
+  fail(z.string().min(5).meta({ title: "Locale" }).safeParse("ab"));
   z.config({ localeError });
 
   expect(seen).toEqual({

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

@@ -838,6 +838,62 @@ describe("__proto__ as a declared shape key", () => {
     expect(() => (schema[method] as any)(mask).shape).toThrow('Unrecognized key: "__proto__"');
   });
 
+  // the mask is checked against the source's declared keys, which reads without resolving them, so it throws where the mistake is
+  test.each(["pick", "omit", "partial", "required"] as const)("%s rejects an undeclared key at the call", (method) => {
+    const schema = z.object({ value: z.string() });
+
+    expect(() => (schema[method] as any)({ nope: true })).toThrow('Unrecognized key: "nope"');
+  });
+
+  // a derived shape is built key by key, and a plain assignment runs whatever setter answers to the key — `__proto__` always has one, and a polluted prototype can supply one for any name
+  test("an inherited setter cannot swallow a derived key", () => {
+    let swallowed: unknown;
+    Object.defineProperty(Object.prototype, "field", {
+      configurable: true,
+      set(v) {
+        swallowed = v;
+      },
+      get() {
+        return undefined;
+      },
+    });
+
+    try {
+      const derived = z.object({ field: z.string() }).extend({ extra: z.number() });
+
+      expect(Object.keys(derived.shape)).toEqual(["field", "extra"]);
+      expect(swallowed).toBeUndefined();
+      // the key is still validated; what a parse writes into its result is the ambient prototype's business, as it is without a builder
+      expect(derived.safeParse({ field: 123, extra: 1 }).success).toBe(false);
+      expect(derived.safeParse({ field: "a", extra: 1 }).success).toBe(true);
+    } finally {
+      delete (Object.prototype as any).field;
+    }
+  });
+
+  // a shape resolves by object spread, so a non-enumerable entry is no part of it and no builder may promote one into a derived shape
+  test("a non-enumerable shape entry stays out of every derived shape", () => {
+    const sym = Symbol("kept");
+    const hide = (target: Record<string, any>) =>
+      Object.defineProperty(target, "hidden", { value: z.string(), enumerable: false, configurable: true });
+    // each case needs a source whose shape is still unresolved, since resolving drops the entry on its own
+    const source = () => z.object(hide({ b: z.number(), [sym]: z.boolean() }) as any);
+
+    expect(Reflect.ownKeys(source().shape)).toEqual(["b", sym]);
+    expect(Reflect.ownKeys(source().extend({ c: z.boolean() }).shape)).toEqual(["b", "c", sym]);
+    expect(Reflect.ownKeys(source().partial().shape)).toEqual(["b", sym]);
+    expect(Reflect.ownKeys(source().merge(z.object({ c: z.boolean() })).shape)).toEqual(["b", "c", sym]);
+    expect(Object.keys(z.object({ b: z.number() }).extend(hide({}) as any).shape)).toEqual(["b"]);
+    expect(() => source().pick({ hidden: true } as any)).toThrow('Unrecognized key: "hidden"');
+
+    // promoting it would make a key the source ignores required
+    expect(
+      source()
+        .extend({ c: z.boolean() })
+        .safeParse({ b: 1, [sym]: true, c: true }).success
+    ).toBe(true);
+  });
+
   test("shape helpers preserve a declared key", () => {
     const shape = () =>
       Object.fromEntries([

package/src/v4/classic/tests/optin-ladder.test.ts

@@ -222,7 +222,8 @@ test("ladder: the rung values themselves", () => {
 
 test("exactOptional overrides the values and pattern optional installs", () => {
   expect(z.exactOptional(z.enum(["a", "b"]))._zod.values).toEqual(new Set(["a", "b"]));
-  expect(z.exactOptional(z.string().regex(/^abc$/))._zod.pattern).toEqual(/^abc$/);
+  // a format carries its pattern on its def; a chained `.regex()` no longer folds into the inner `_zod.pattern`, the template literal derives that itself
+  expect(z.exactOptional(z.stringFormat("abc", /^abc$/))._zod.pattern).toEqual(/^abc$/);
   expect(z.templateLiteral(["a", z.exactOptional(z.literal("b"))]).safeParse("a").success).toEqual(false);
 });
 
@@ -230,5 +231,5 @@ test("exactOptional overrides the values and pattern optional installs", () => {
 test("exactOptional's override holds for later instances", () => {
   z.exactOptional(z.enum(["a", "b"]));
   expect(z.exactOptional(z.enum(["c", "d"]))._zod.values).toEqual(new Set(["c", "d"]));
-  expect(z.exactOptional(z.string().regex(/^xyz$/))._zod.pattern).toEqual(/^xyz$/);
+  expect(z.exactOptional(z.stringFormat("xyz", /^xyz$/))._zod.pattern).toEqual(/^xyz$/);
 });