Add properties checks for instanceof schemas (#5912)

* Add properties checks for instanceof schemas

* Revert "Add properties checks for instanceof schemas"

Replaced by a plain z.properties(shape) helper that returns an array of
ordinary $ZodCheckProperty checks. The dedicated $ZodCheckProperties check
type had no case in core/compile.ts, so any schema using it dropped off the
AOT fast path, and SupportedCheck there is a hand-listed union so nothing
caught the omission.

* Add z.properties() for checking several properties at once

Returns an array of ordinary $ZodCheckProperty checks to spread into the
existing variadic .check(), so there is no new check type, no new constructor,
and no per-schema-type method. Each check carries `when`, which opts it out of
the run loop's aborted-issue gate, so a parse reports every property that failed
rather than only the first.

* fix(v4): drop the always-run gate from z.properties

`when` opts a check past the *implicit* abort gate, not just the sibling-property
one. `runChecks` skips a `when`-carrying check only on `util.explicitlyAborted`, but
`z.object` / `z.record` / `z.array` push their type-mismatch issues with no `continue`
field, so the property checks ran against a value the base schema had already
rejected — and `$ZodCheckProperty` indexes `payload.value` unguarded.

    const obj = z.object({ a: z.string() }).check(...z.properties({ a: z.literal("x") }));
    obj.safeParse(null); // TypeError: Cannot read properties of null (reading 'a')
    obj.safeParse(5);    // invalid_type [] plus a spurious invalid_value ["a"]

A throwing `safeParse` is not a trade worth making for aggregated issue paths, so the
checks are now plain: `z.properties(shape)` is exactly the array of `z.property()`
calls it looks like, and behaves identically to writing them out. That also puts the
schema back on the compiled fast path, since `compile.ts` rejects any check carrying a
non-defaulted `when`.

The z.instanceof tests missed this because `_instanceof` aborts explicitly. The object
cases now cover null, undefined and a primitive.

* test(v4): pin where z.properties is looser than the longhand

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 compiles as a result, and fails
at parse time instead — where the equivalent chain of `z.property()` calls rejects it
outright.

Typing each element over only its own key restores the diagnostic and breaks every
valid call, because a union argument has to satisfy the target on its own. Pinning the
gap so it reads as a known trade rather than an accident.

Author: colinhacks

packages/docs/content/api.mdx

@@ -2210,6 +2210,20 @@ blobSchema.parse("hello there!"); // ✅
 blobSchema.parse("hello."); // ❌
 ```
 
+Use `z.properties()` to declare several property checks from an object literal. It returns an array to spread into `.check()`.
+
+```ts
+const httpsUrl = z.instanceof(URL).check(
+  ...z.properties({
+    protocol: z.literal("https:" as string),
+    hostname: z.string().regex(z.regexes.domain),
+  })
+);
+
+httpsUrl.parse(new URL("https://example.com")); // ✅
+httpsUrl.parse(new URL("http://localhost")); // ❌ protocol
+```
+
 ## Refinements
 
 Every Zod schema stores an array of *refinements*. Refinements are a way to perform custom validation that Zod doesn't provide a native API for.

packages/zod/src/v4/classic/checks.ts

@@ -21,6 +21,7 @@ export {
   _startsWith as startsWith,
   _endsWith as endsWith,
   _property as property,
+  _properties as properties,
   _mime as mime,
   _overwrite as overwrite,
   _normalize as normalize,

packages/zod/src/v4/classic/tests/instanceof.test.ts

@@ -58,3 +58,50 @@ test("instanceof respects customError", () => {
 
   z.config({ customError: undefined });
 });
+
+test("z.properties", () => {
+  const httpsUrl = z.instanceof(URL).check(
+    ...z.properties({
+      protocol: z.literal("https:" as string),
+      hostname: z.string().regex(z.regexes.domain),
+    })
+  );
+
+  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.
+  const both = httpsUrl.safeParse(new URL("http://localhost"));
+  expect(both.error!.issues.map((i) => i.path)).toEqual([["protocol"]]);
+
+  // A failing base schema yields its own issue and no property issues.
+  for (const input of ["not a url", null]) {
+    const issues = httpsUrl.safeParse(input).error!.issues;
+    expect(issues.map((i) => [i.code, i.path])).toEqual([["custom", []]]);
+  }
+
+  // Not specific to z.instanceof(). A base whose type mismatch aborts implicitly rather than explicitly must still not run the property checks against the rejected value.
+  const obj = z
+    .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"]]);
+  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.
+  z.object({ a: z.string() }).check(...z.properties({ a: z.literal("x"), b: z.literal("y") }));
+  expect(
+    z
+      .object({ a: z.string() })
+      .check(...z.properties({ a: z.string(), b: z.literal("y") }))
+      .safeParse({ a: "ok" })
+      .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.
+  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"]]);
+});

packages/zod/src/v4/core/api.ts

@@ -1127,6 +1127,15 @@ export function _property<K extends string, T extends schemas.$ZodType>(
   });
 }
 
+// @__NO_SIDE_EFFECTS__
+export function _properties<Shape extends schemas.$ZodShape>(
+  shape: Shape
+): checks.$ZodCheckProperty<{ -readonly [k in keyof Shape]: core.output<Shape[k]> }>[] {
+  return Object.entries(shape).map(
+    ([property, schema]) => new checks.$ZodCheckProperty({ check: "property", property, schema })
+  ) as any;
+}
+
 export type $ZodCheckMimeTypeParams = CheckParams<checks.$ZodCheckMimeType, "mime" | "when">;
 // @__NO_SIDE_EFFECTS__
 export function _mime(types: util.MimeTypes[], params?: string | $ZodCheckMimeTypeParams): checks.$ZodCheckMimeType {

packages/zod/src/v4/mini/checks.ts

@@ -23,6 +23,7 @@ export {
   _startsWith as startsWith,
   _endsWith as endsWith,
   _property as property,
+  _properties as properties,
   _mime as mime,
   _overwrite as overwrite,
   _normalize as normalize,

packages/zod/src/v4/mini/tests/checks.test.ts

@@ -140,6 +140,12 @@ test("z.overwrite", () => {
 // toUpperCase;
 // property
 
+test("z.properties", () => {
+  const a = z.instanceof(URL).check(...z.properties({ protocol: z.literal("https:" as string), hostname: z.string() }));
+  expect(z.safeParse(a, new URL("https://example.com")).success).toEqual(true);
+  expect(z.safeParse(a, new URL("http://example.com")).error!.issues.map((i) => i.path)).toEqual([["protocol"]]);
+});
+
 test("abort early", () => {
   const schema = z.string().check(
     z.refine((val) => val.length > 1),