zod 4.5.3 → 4.6.0

package/src/v4/core/memoizer.ts

@@ -1,6 +1,6 @@
 import type * as errors from "./errors.js";
-import type { $ZodMemoizer, $ZodType, ParseContextInternal, ParsePayload } from "./schemas.js";
-import type * as util from "./util.js";
+import type { $ZodMemoizer, $ZodType, $ZodTypeDef, ParseContextInternal, ParsePayload } from "./schemas.js";
+import * as util from "./util.js";
 
 export class $ZodCyclicError extends Error {
   constructor() {
@@ -16,9 +16,10 @@ interface Entry {
 }
 
 interface State {
-  buckets: Map<$ZodType, Map<object, Entry>>;
+  /** Weak throughout because `attach` caches a bucket on the schema instance, which outlives the parse. */
+  buckets: WeakMap<$ZodType, WeakMap<object, Entry>>;
   /** Nodes a back-edge resolved to before they finished. */
-  backEdges: Set<object> | undefined;
+  backEdges: WeakSet<object> | undefined;
 }
 
 /** Keyed off the context object every schema in one parse call already shares. */
@@ -27,6 +28,11 @@ type WithState = { [STATE]?: State };
 
 const NO_ISSUES: errors.$ZodRawIssue[] = [];
 
+// a value a cycle can close through; callables count, since z.properties asserts on one
+function isRef(value: unknown): value is object {
+  return value !== null && (typeof value === "object" || typeof value === "function");
+}
+
 // Receivers prefix paths in place, so the cache and every hand-out need their own copies.
 function cloneIssues(issues: errors.$ZodRawIssue[]): errors.$ZodRawIssue[] {
   return issues.map((iss) => (iss.path ? { ...iss, path: iss.path.slice() } : { ...iss }));
@@ -34,38 +40,153 @@ function cloneIssues(issues: errors.$ZodRawIssue[]): errors.$ZodRawIssue[] {
 
 const recursive: WeakMap<object, boolean> = /*@__PURE__*/ new WeakMap();
 
+/** What the walk established, in order of certainty: ordered so the strongest answer among children wins. */
+const NONE = 0;
+const ASSUMED = 1;
+const PROVEN = 2;
+type Answer = typeof NONE | typeof ASSUMED | typeof PROVEN;
+
 /** Whether this schema's subtree contains a cycle, so one parse can re-enter it. */
-function isRecursive(inst: $ZodType, stack: Set<object>): boolean {
+function isRecursive(inst: $ZodType, stack: Set<object>, resolve: boolean): Answer {
   const cached = recursive.get(inst);
-  if (cached !== undefined) return cached;
+  if (cached !== undefined) return cached ? PROVEN : NONE;
   // Relative to the walk in progress, so not cached.
-  if (stack.has(inst)) return true;
+  if (stack.has(inst)) return PROVEN;
   stack.add(inst);
 
-  let result = false;
+  let result: Answer = NONE;
   const check = (child: any) => {
-    if (!result && child?._zod && isRecursive(child, stack)) result = true;
+    if (result !== PROVEN && child?._zod) {
+      const answer = isRecursive(child, stack, resolve);
+      if (answer > result) result = answer;
+    }
+  };
+
+  // `Reflect.ownKeys` rather than `Object.keys`, so a cycle through a declared symbol key is still seen
+  const shape = (sh: object, spread: boolean): Answer => {
+    let answer: Answer = NONE;
+    for (const key of Reflect.ownKeys(sh)) {
+      const desc = Object.getOwnPropertyDescriptor(sh, key)!;
+      // an object resolves its shape by spread, so a key it does not enumerate is never parsed; `z.properties` reads every own key and so keeps them all
+      if (spread && !desc.enumerable) continue;
+      // resolving runs user code, and a factory mints a fresh subtree per read, so an edge the walk can't follow counts as a cycle
+      const child = desc.get ? ASSUMED : desc.value?._zod ? isRecursive(desc.value, stack, resolve) : NONE;
+      if (child > answer) answer = child;
+    }
+    return answer;
+  };
+
+  const merge = (answer: Answer) => {
+    if (answer > result) result = answer;
   };
 
   const def = inst._zod.def as any;
-  if (def.type === "lazy") {
-    check((inst as any)._zod.innerType);
-  } else {
-    // $ZodObject redefines `shape` as a non-enumerable accessor, so `for...in` misses it.
-    const shape = def.shape;
-    // `for...in` skips symbols, so a cycle through a declared symbol key would read as non-recursive
-    if (shape) for (const key of Reflect.ownKeys(shape)) check(shape[key]);
-    for (const key in def) {
-      const value = def[key];
-      if (!value || typeof value !== "object") continue;
-      if (value._zod) check(value);
-      else if (Array.isArray(value)) for (const el of value) check(el);
+  const kind = def.type as $ZodTypeDef["type"];
+  switch (kind) {
+    case "object": {
+      const raw = util.rawShape(def);
+      // a def with no raw shape answers `shape` from an accessor of its own, and running that can mint a whole fresh subtree
+      merge(raw ? shape(raw, true) : ASSUMED);
+      check(def.catchall);
+      break;
+    }
+    case "properties":
+      merge(shape(def.shape, false));
+      break;
+    case "array":
+      check(def.element);
+      break;
+    case "tuple":
+      for (const el of def.items) check(el);
+      check(def.rest);
+      break;
+    case "record":
+    case "map":
+      check(def.keyType);
+      check(def.valueType);
+      break;
+    case "set":
+      check(def.valueType);
+      break;
+    case "union":
+      for (const el of def.options) check(el);
+      break;
+    case "intersection":
+      check(def.left);
+      check(def.right);
+      break;
+    case "optional":
+    case "nullable":
+    case "default":
+    case "prefault":
+    case "catch":
+    case "readonly":
+    case "nonoptional":
+    case "promise":
+    case "success":
+      check(def.innerType);
+      break;
+    case "pipe":
+      check(def.in);
+      check(def.out);
+      break;
+    case "function":
+      check(def.input);
+      check(def.output);
+      break;
+    // `$ZodLazy` caches its inner on the def, so a resolved edge is followed exactly
+    case "lazy": {
+      const inner = def._cachedInner ?? (resolve ? (inst as any)._zod.innerType : undefined);
+      // walked with resolution off: one hop sees past the deferral, and a lazy that yields only another unresolved lazy is generative, so it stops there
+      merge(inner ? isRecursive(inner, stack, false) : ASSUMED);
+      break;
+    }
+    // a leaf by choice: `parts` are regex fragments, not data positions
+    case "template_literal":
+    // leaves
+    case "string":
+    case "number":
+    case "int":
+    case "boolean":
+    case "bigint":
+    case "symbol":
+    case "undefined":
+    case "null":
+    case "void":
+    case "never":
+    case "any":
+    case "unknown":
+    case "date":
+    case "nan":
+    case "enum":
+    case "literal":
+    case "file":
+    case "transform":
+    case "custom":
+      break;
+    default: {
+      // a new built-in kind becomes a compile error here
+      kind satisfies never;
+      // a user-defined kind can still hold children, and only its author knows where, so fall back to scanning the def — skipping accessors, since reading one can run user code
+      for (const key in def) {
+        const desc = Object.getOwnPropertyDescriptor(def, key);
+        if (!desc || desc.get) continue;
+        const value = desc.value;
+        if (!value || typeof value !== "object") continue;
+        if (value._zod) check(value);
+        else if (Array.isArray(value)) for (const el of value) check(el);
+      }
     }
   }
 
   stack.delete(inst);
-  recursive.set(inst, result);
-  return result;
+  return settle(inst, result);
+}
+
+/** An assumed answer must not outlive the resolution that settles it, so only a certain one is cached. */
+function settle(inst: $ZodType, answer: Answer): Answer {
+  if (answer !== ASSUMED) recursive.set(inst, answer === PROVEN);
+  return answer;
 }
 
 /**
@@ -75,20 +196,21 @@ function isRecursive(inst: $ZodType, stack: Set<object>): boolean {
  * generated fast path has no context to key on.
  */
 export function isRecursiveSchema(inst: $ZodType): boolean {
-  return isRecursive(inst, new Set());
+  // z.compile never parses, so nothing would ever resolve a lazy for it; it runs once and already treats a throw here as recursive
+  return isRecursive(inst, new Set(), true) !== NONE;
 }
 
-function bucketFor(state: State, inst: $ZodType): Map<object, Entry> {
+function bucketFor(state: State, inst: $ZodType): WeakMap<object, Entry> {
   let bucket = state.buckets.get(inst);
   if (!bucket) {
-    bucket = new Map();
+    bucket = new WeakMap();
     state.buckets.set(inst, bucket);
   }
   return bucket;
 }
 
 // Set immediately before delegating to core and cleared immediately after, so `alloc` registers only for a visit this module is driving.
-let handoff: Map<object, Entry> | undefined;
+let handoff: WeakMap<object, Entry> | undefined;
 
 // Allocated but unfinished entries. `alloc` and the matching pop both happen in the synchronous part of a parse, so they nest even when children are async, and one stack serves every schema.
 const open: Entry[] = [];
@@ -120,9 +242,10 @@ const memo: $ZodMemoizer = {
 
   attach(inst) {
     let isRecursiveInst: boolean | undefined;
-    // `bucket` memoized for one parse; a recursive schema is re-entered many times and its bucket never changes
+    let rechecked = false;
+    // a recursive schema is re-entered many times per parse and its bucket never changes
     let lastCtx: object | undefined;
-    let lastBucket: Map<object, Entry> | undefined;
+    let lastBucket: WeakMap<object, Entry> | undefined;
 
     // Wraps `parse` in a deferred so it sees the container's final parse. Core's own deferred copies `parse` into `run` when there are no checks, and it ran first, so `run` is patched to match; with checks, `run` reads `parse` dynamically.
     inst._zod.deferred ??= [];
@@ -131,25 +254,28 @@ const memo: $ZodMemoizer = {
 
       const wrapped = (payload: ParsePayload, ctx: ParseContextInternal): util.MaybeAsync<ParsePayload> => {
         if (isRecursiveInst === undefined) {
-          isRecursiveInst = isRecursive(inst, new Set());
-          if (!isRecursiveInst) {
+          const walked = isRecursive(inst, new Set(), false);
+          if (walked === NONE) {
             // Nothing here can ever fire, so take it back out.
             inst._zod.parse = base;
             if (inst._zod.run === wrapped) inst._zod.run = base;
             return base(payload, ctx);
           }
+          // this parse resolves the deferred edges on its own path, so ask once more before latching
+          if (walked === PROVEN || rechecked) isRecursiveInst = true;
+          else rechecked = true;
         }
 
         const input = payload.value;
-        if (input === null || typeof input !== "object") return base(payload, ctx);
+        if (!isRef(input)) return base(payload, ctx);
 
         let state = (ctx as WithState)[STATE];
         if (!state) {
-          state = { buckets: new Map(), backEdges: undefined };
+          state = { buckets: new WeakMap(), backEdges: undefined };
           (ctx as WithState)[STATE] = state;
         }
 
-        let bucket: Map<object, Entry>;
+        let bucket: WeakMap<object, Entry>;
         if (lastCtx === ctx) {
           bucket = lastBucket!;
         } else {
@@ -166,7 +292,7 @@ const memo: $ZodMemoizer = {
           } else {
             // Still being parsed: its own checks cover it, so skip them here.
             payload.memo = true;
-            state.backEdges ??= new Set();
+            state.backEdges ??= new WeakSet();
             state.backEdges.add(hit.value as object);
           }
           return payload;
@@ -204,5 +330,5 @@ export function memoizer(): $ZodMemoizer {
 /** Whether this value is a node a back-edge resolved to before it finished. */
 export function isBackEdge(ctx: object, value: unknown): boolean {
   const backEdges = (ctx as WithState)[STATE]?.backEdges;
-  return backEdges !== undefined && value !== null && typeof value === "object" && backEdges.has(value);
+  return backEdges !== undefined && isRef(value) && backEdges.has(value);
 }

package/src/v4/core/parse.ts

@@ -75,15 +75,33 @@ export const _safeParse: (_Err: $ZodErrorClass) => $SafeParse = (_Err) => (schem
     throw new core.$ZodAsyncError();
   }
 
-  return result.issues.length
-    ? {
-        success: false,
-        error: new (_Err ?? errors.$ZodError)(result.issues.map((iss) => util.finalizeIssue(iss, ctx, core.config()))),
-      }
-    : ({ success: true, data: result.value } as any);
+  return result.issues.length ? failure(_Err, result.issues, ctx) : ({ success: true, data: result.value } as any);
 };
 export const safeParse: $SafeParse = /* @__PURE__*/ _safeParse(errors.$ZodRealError);
 
+// the error is built on the first read of `error`: finalizing the issues and constructing the instance is most of a failing parse, and a caller that only branches on `success` never pays it. a getter in the literal keeps this small; the alternative, one shared accessor descriptor plus a hidden state slot, reads ~15% faster but costs ~75 B gzipped in every bundle
+function failure(Err: $ZodErrorClass, issues: errors.$ZodRawIssue[], ctx: schemas.ParseContextInternal): any {
+  let error: errors.$ZodError | undefined;
+  return {
+    success: false,
+    get error() {
+      if (!error) {
+        error = new Err(issues.map((iss) => util.finalizeIssue(iss, ctx, core.config())));
+        // finalizeIssue drops `input`, so the built error holds nothing; keeping the raw issues past this point pins the parsed value for the life of the result
+        issues = undefined as any;
+        ctx = undefined as any;
+      }
+      return error;
+    },
+    set error(e: errors.$ZodError) {
+      error = e;
+      // a replacement makes the getter's branch unreachable, so the captures have to go here too
+      issues = undefined as any;
+      ctx = undefined as any;
+    },
+  };
+}
+
 export type $SafeParseAsync = <T extends schemas.$ZodType>(
   schema: T,
   value: unknown,
@@ -95,12 +113,7 @@ export const _safeParseAsync: (_Err: $ZodErrorClass) => $SafeParseAsync = (_Err)
   let result = schema._zod.run({ value, issues: [] }, ctx);
   if (result instanceof Promise) result = await result;
 
-  return result.issues.length
-    ? {
-        success: false,
-        error: new _Err(result.issues.map((iss) => util.finalizeIssue(iss, ctx, core.config()))),
-      }
-    : ({ success: true, data: result.value } as any);
+  return result.issues.length ? failure(_Err, result.issues, ctx) : ({ success: true, data: result.value } as any);
 };
 
 export const safeParseAsync: $SafeParseAsync = /* @__PURE__*/ _safeParseAsync(errors.$ZodRealError);
@@ -110,7 +123,7 @@ const COMPILE_INVALID = /* @__PURE__ */ Symbol.for("zod.compile.invalid");
 const COMPILE_FALLBACK = /* @__PURE__ */ Symbol.for("zod.compile.fallback");
 
 interface CompiledBag {
-  validator?: (input: unknown) => unknown;
+  validator?: ((input: unknown) => unknown) & { definite?: boolean | undefined };
   fallbackRun?: (payload: schemas.ParsePayload, ctx: schemas.ParseContextInternal) => unknown;
 }
 
@@ -127,7 +140,11 @@ export const validate: $Validate = ((
   _ctx?: schemas.ParseContext<errors.$ZodIssue>
 ): boolean => {
   const validator = (schema._zod.bag as CompiledBag).validator;
-  if (validator !== undefined && validator(value) !== COMPILE_INVALID) return true;
+  if (validator !== undefined) {
+    if (validator(value) !== COMPILE_INVALID) return true;
+    // a definite sentinel means the runtime would reject, so skip the re-parse; a ctx can still change the answer
+    if (validator.definite === true && _ctx === undefined) return false;
+  }
   return validateFallback(schema, value, _ctx);
 }) as $Validate;
 
@@ -136,7 +153,9 @@ function validateFallback(
   value: unknown,
   _ctx?: schemas.ParseContext<errors.$ZodIssue>
 ): boolean {
-  const ctx: schemas.ParseContextInternal = _ctx ? { ..._ctx, async: false } : { async: false };
+  const ctx: schemas.ParseContextInternal = _ctx
+    ? { ..._ctx, async: false, abortEarly: true }
+    : { async: false, abortEarly: true };
   const fallbackRun = (schema._zod.bag as CompiledBag).fallbackRun;
   let result: unknown;
   if (fallbackRun) {
@@ -160,7 +179,9 @@ export type $ValidateAsync = <T extends schemas.$ZodType>(
 
 // no fast path: the compiler keeps async parses on the runtime, because a promise-returning callback that is not declared async compiles to a throw
 export const validateAsync: $ValidateAsync = async (schema, value, _ctx) => {
-  const ctx: schemas.ParseContextInternal = _ctx ? { ..._ctx, async: true } : { async: true };
+  const ctx: schemas.ParseContextInternal = _ctx
+    ? { ..._ctx, async: true, abortEarly: true }
+    : { async: true, abortEarly: true };
   let result: unknown = schema._zod.run({ value, issues: [] }, ctx);
   if (result instanceof Promise) result = await result;
   return (result as schemas.ParsePayload).issues.length === 0;

package/src/v4/core/regexes.ts

@@ -42,7 +42,7 @@ export const uuid7: RegExp = /*@__PURE__*/ uuid(7);
 
 /** Practical email validation */
 export const email: RegExp =
-  /^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/;
+  /^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/;
 
 /** Equivalent to the HTML5 input[type=email] validation implemented by browsers. Source: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email */
 export const html5Email: RegExp =
@@ -60,8 +60,8 @@ export const browserEmail: RegExp =
   /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
 // from https://thekevinscott.com/emojis-in-javascript/#writing-a-regular-expression
 
-// Single character class, not an alternation: the two properties overlap (U+1F9B0-U+1F9B3), so `(A|B)+` backtracks exponentially on a failed match.
-const _emoji: string = `^[\\p{Extended_Pictographic}\\p{Emoji_Component}]+$`;
+// Single character class, not an alternation: the two properties overlap (U+1F9B0-U+1F9B3), so `(A|B)+` backtracks exponentially on a failed match. The leading lookahead then demands one anchor — a pictograph, a regional indicator, or the enclosing keycap — because `\p{Emoji_Component}` on its own covers ASCII digits, `#`, `*`, ZWJ, variation selectors and skin tone modifiers, none of which is an emoji without a base.
+const _emoji: string = `^(?=[\\s\\S]*[\\p{Extended_Pictographic}\\p{Regional_Indicator}\\u20E3])[\\p{Extended_Pictographic}\\p{Emoji_Component}]+$`;
 export function emoji(): RegExp {
   return new RegExp(_emoji, "u");
 }
@@ -81,7 +81,7 @@ export const cidrv6: RegExp =
 
 // https://stackoverflow.com/questions/7860392/determine-if-string-is-in-base64-using-javascript
 export const base64: RegExp = /^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$/;
-export const base64url: RegExp = /^[A-Za-z0-9_-]*$/;
+export const base64url: RegExp = /^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-]{2,3})?$/;
 
 // based on https://stackoverflow.com/questions/106179/regular-expression-to-match-dns-hostname-or-ip-address
 // export const hostname: RegExp = /^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/;
@@ -98,6 +98,9 @@ export const e164: RegExp = /^\+[1-9]\d{6,14}$/;
 // Credit card shape: 12–19 digits, optionally separated by single spaces or single hyphens. ISO/IEC 7812 caps the PAN at 19 digits; 12 is the shortest issued length (Maestro).
 export const creditCard: RegExp = /^\d(?:[ -]?\d){11,18}$/;
 
+// iban electronic format: 2-letter country, check digits 02-98 (the only values `98 - remainder` can produce), 11-30 bban characters
+export const iban: RegExp = /^[A-Z]{2}(?!00|01|99)\d{2}[A-Z0-9]{11,30}$/;
+
 const dateSource = `(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))`;
 
 /** Anchors a pattern source. The interpolation lives here rather than at the call site because
@@ -147,6 +150,9 @@ export function datetime(args: {
   return new RegExp(`^${dateSource}T(?:${timeRegex})$`);
 }
 
+// the unbounded form of `string()` as a literal, so every plain string shares one instance instead of building its own
+export const anyString: RegExp = /^[\s\S]{0,}$/;
+
 export const string = (params?: { minimum?: number | undefined; maximum?: number | undefined }): RegExp => {
   const regex = params ? `[\\s\\S]{${params?.minimum ?? 0},${params?.maximum ?? ""}}` : `[\\s\\S]*`;
   return new RegExp(`^${regex}$`);