zod 4.5.4 → 4.6.0

package/v4/core/compile.cjs

@@ -25,6 +25,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZodCompileUnsupportedError = exports.ZodCompileAsyncError = exports.INVALID = void 0;
 exports.compile = compile;
+exports.withParser = withParser;
 exports.compileFn = compileFn;
 const core_js_1 = require("./core.cjs");
 const doc_js_1 = require("./doc.cjs");
@@ -32,7 +33,7 @@ const memoizer_js_1 = require("./memoizer.cjs");
 const regexes = __importStar(require("./regexes.cjs"));
 const schemas_js_1 = require("./schemas.cjs");
 const util = __importStar(require("./util.cjs"));
-/** Sentinel value returned by the compiled fast path when validation fails. Internal. */
+/** @internal Sentinel the compiled fast path returns when validation fails. */
 exports.INVALID = Symbol.for("zod.compile.invalid");
 // Set on the parse ctx when a compiled wrapper falls back to the runtime, so nested compiled wrappers skip their fast paths for the rest of that parse.
 const FALLBACK_FLAG = Symbol.for("zod.compile.fallback");
@@ -85,45 +86,9 @@ function compileValidator(schema, parser) {
 function compile(schema, options) {
     try {
         const parser = compileFn(schema);
-        const clone = util.clone(schema);
-        // Capture the source-of-truth runtime eagerly. If schema._zod.run is itself a shim installed by global-mode (`__originalRun` set), unwrap past it. Otherwise capturing the live property lazily would let a later self- replacement of schema._zod.run feed our wrapper back into itself.
-        const liveRun = schema._zod.run;
-        const originalRun = liveRun.__originalRun ?? liveRun;
-        // Delegate to the *original* schema's run on bypass/fallback (not the
-        // clone's). The original closed over its own `inst` at construction time;
-        // issue payloads use that reference to derive things like the class name
-        // for `z.instanceof(Test)`. Calling the clone's freshly-initialized run
-        // would push issues with `inst === clone`, producing diverging error
-        // messages from the original schema.
-        const wrapped = (payload, ctx) => {
-            if (ctx?.async ||
-                ctx?.direction === "backward" ||
-                ctx?.skipChecks ||
-                ctx?.[FALLBACK_FLAG]) {
-                return originalRun(payload, ctx);
-            }
-            // A memoized back-edge: only the runtime can close a reference cycle, and a transform on one must raise $ZodCyclicError from its own parse.
-            if (ctx && (0, memoizer_js_1.isBackEdge)(ctx, payload.value)) {
-                return originalRun(payload, ctx);
-            }
-            const out = parser(payload.value);
-            if (out !== exports.INVALID) {
-                payload.value = out;
-                return payload;
-            }
-            // Mark this parse as runtime-driven: under global mode every nested schema carries its own compiled wrapper, and without the flag the parent's runtime fallback re-enters each child's fast path, running user callbacks a third time on invalid input.
-            if (ctx)
-                ctx[FALLBACK_FLAG] = true;
-            return originalRun(payload, ctx);
-        };
-        // Let later compiles of (or through) this run unwrap to the true runtime — both the global shim and repeated z.compile calls rely on this. The bag also carries the parser and the validator, so the standalone validate can skip the payload and wrapper on the happy path.
-        wrapped.__originalRun = originalRun;
-        clone._zod.bag.fallbackRun = originalRun;
+        const clone = withParser(schema, parser);
+        // withParser leaves the parser as its own validator; the generated assert-only variant is better when we have one
         clone._zod.bag.validator = compileValidator(schema, parser);
-        clone._zod.run = wrapped;
-        // The fast parse/safeParse closures fall back through the source schema's methods. If the source is shim- or wrapper-managed, those methods route into a compiled run and would execute user callbacks a third time on invalid input — the plain method → wrapper path is exactly 2x, so skip.
-        if (!liveRun.__originalRun)
-            installCompiledUserMethods(clone, schema, parser);
         return clone;
     }
     catch (err) {
@@ -133,6 +98,59 @@ function compile(schema, options) {
         return schema;
     }
 }
+/**
+ * Install an already-generated parser as a schema's fast path. Returns a clone; the original is
+ * unchanged.
+ *
+ * The parser takes the input and returns the parsed value, or `INVALID` to hand the parse to the
+ * runtime. It must be synchronous and forward-direction, and it must build fresh output rather than
+ * return its input — Zod cannot check either, and a wrong *success* is returned to the caller as-is.
+ *
+ * `compile()` is the ordinary entry point. This is for a build-time or native compiler that produces
+ * a parser where `new Function` is unavailable.
+ */
+function withParser(schema, parser) {
+    // generated code never receives the parse context, so only the runtime can close a reference cycle; compileFn refuses these too
+    if ((0, memoizer_js_1.isRecursiveSchema)(schema)) {
+        throw new ZodCompileUnsupportedError("a schema whose subtree contains a reference cycle");
+    }
+    const clone = util.clone(schema);
+    // Capture the source-of-truth runtime eagerly. If schema._zod.run is itself a shim installed by global-mode (`__originalRun` set), unwrap past it. Otherwise capturing the live property lazily would let a later self- replacement of schema._zod.run feed our wrapper back into itself.
+    const liveRun = schema._zod.run;
+    const originalRun = liveRun.__originalRun ?? liveRun;
+    // Delegate to the *original* schema's run on bypass/fallback, not the clone's. The original closed over its own `inst` at construction time, and issue payloads use that reference to derive things like the class name for `z.instanceof(Test)`; calling the clone's freshly-initialized run would push issues with `inst === clone` and diverge from the original schema's error messages.
+    const wrapped = (payload, ctx) => {
+        if (ctx?.async ||
+            ctx?.direction === "backward" ||
+            ctx?.skipChecks ||
+            ctx?.[FALLBACK_FLAG]) {
+            return originalRun(payload, ctx);
+        }
+        // A memoized back-edge: only the runtime can close a reference cycle, and a transform on one must raise $ZodCyclicError from its own parse.
+        if (ctx && (0, memoizer_js_1.isBackEdge)(ctx, payload.value)) {
+            return originalRun(payload, ctx);
+        }
+        const out = parser(payload.value);
+        if (out !== exports.INVALID) {
+            payload.value = out;
+            return payload;
+        }
+        // Mark this parse as runtime-driven: under global mode every nested schema carries its own compiled wrapper, and without the flag the parent's runtime fallback re-enters each child's fast path, running user callbacks a third time on invalid input.
+        if (ctx)
+            ctx[FALLBACK_FLAG] = true;
+        return originalRun(payload, ctx);
+    };
+    // Let later compiles of (or through) this run unwrap to the true runtime — both the global shim and repeated z.compile calls rely on this. The bag also carries the parser and the validator, so the standalone validate can skip the payload and wrapper on the happy path.
+    wrapped.__originalRun = originalRun;
+    clone._zod.bag.fallbackRun = originalRun;
+    // a supplied parser answers `validate` too: one implementation means parse and validate cannot disagree, and its undefined `definite` keeps the runtime re-parse on every rejection
+    clone._zod.bag.validator = parser;
+    clone._zod.run = wrapped;
+    // The fast parse/safeParse closures fall back through the source schema's methods. If the source is shim- or wrapper-managed, those methods route into a compiled run and would execute user callbacks a third time on invalid input — the plain method → wrapper path is exactly 2x, so skip.
+    if (!liveRun.__originalRun)
+        installCompiledUserMethods(clone, schema, parser);
+    return clone;
+}
 function installCompiledUserMethods(target, source, parser) {
     const targetAny = target;
     const sourceAny = source;
@@ -158,9 +176,8 @@ function installCompiledUserMethods(target, source, parser) {
     }
 }
 /**
- * Generate the standalone compiled function: a parser by default, a validator under
- * `assertOnly`. Returns either the parsed value, `true` where nothing reads the output,
- * or the `INVALID` sentinel. Internal — consumers should use `compile()`.
+ * @internal Generate the standalone compiled function: a parser by default, a validator under
+ * `assertOnly`. Returns the parsed value, `true` where nothing reads the output, or `INVALID`. Consumers use `compile()`.
  */
 function compileFn(schema, options) {
     // Cycle-breaking is keyed on the parse context, which generated code never receives. `shape` can be a getter that throws (z.pick() with an unrecognized mask key), so treat "can't tell" as recursive.
@@ -176,6 +193,7 @@ function compileFn(schema, options) {
         constants: new Map(),
         constantCounter: 0,
         varCounter: 0,
+        definite: true,
     };
     const doc = new doc_js_1.Doc(["input"]);
     const outputAccessor = generateCheck(doc, ctx, schema, "input", !options?.assertOnly);
@@ -204,6 +222,7 @@ function compileFn(schema, options) {
     if (options?.debug) {
         fn.code = fullCode;
     }
+    fn.definite = ctx.definite;
     return fn;
 }
 function addConstant(ctx, value) {
@@ -216,6 +235,11 @@ function addConstant(ctx, value) {
     ctx.constants.set(name, value);
     return name;
 }
+/** Hoists a user-supplied callback. Anything the schema's author wrote can throw, and generated code can reject an earlier sibling before ever reaching it, so this clears `definite` — a rejection is then no longer proof that the interpreter would have rejected rather than thrown. */
+function addUserConstant(ctx, fn) {
+    ctx.definite = false;
+    return addConstant(ctx, fn);
+}
 function newVar(ctx) {
     return `v${ctx.varCounter++}`;
 }
@@ -251,6 +275,8 @@ function compileChild(doc, ctx, schema, accessor, needsValue = true) {
     }
 }
 function emitRuntimeIsland(doc, ctx, schema, accessor) {
+    // an islanded child answers INVALID for an async run too, which the interpreter throws for
+    ctx.definite = false;
     const schemaConst = addConstant(ctx, schema);
     const runConst = addConstant(ctx, runtimeRun);
     const outVar = newVar(ctx);
@@ -334,6 +360,9 @@ function generateChecks(doc, ctx, schema, accessor) {
             case "property":
                 generatePropertyCheck(doc, ctx, def, currentAccessor);
                 break;
+            case "properties":
+                generatePropertiesChecks(doc, ctx, def, currentAccessor, false);
+                break;
             case "overwrite": {
                 // Overwrite transforms the value - create new variable for transformed result
                 const newAccessor = newVar(ctx);
@@ -459,6 +488,26 @@ function generateMimeTypeCheck(doc, ctx, def, accessor) {
         doc.write(`if (!${mimeSet}.has(${accessor}.type)) return INVALID;`);
     }
 }
+// asserts each named property in place; children compile assert-only because z.properties never rebuilds its input
+function generatePropertiesChecks(doc, ctx, def, accessor, schemaRole) {
+    // a custom `when` gates the assertion at runtime; inside a union a wrongly-run branch is absorbed as a branch failure rather than falling back, so refuse at codegen the way the check role does
+    if (def.when) {
+        throw new ZodCompileUnsupportedError(`check with a custom "when" condition`);
+    }
+    // matches the runtime gate for whichever role this is: a schema rejects a primitive outright, a check only a nullish value
+    doc.write(schemaRole
+        ? `if (${accessor} === null || (typeof ${accessor} !== "object" && typeof ${accessor} !== "function")) return INVALID;`
+        : `if (${accessor} == null) return INVALID;`);
+    const shape = def.shape;
+    for (const key of Reflect.ownKeys(shape)) {
+        // a symbol has no source literal, so it is hoisted as a constant
+        const keyExpr = typeof key === "symbol" ? addConstant(ctx, key) : util.esc(key);
+        // cache the property read so a getter runs exactly once, matching the runtime
+        const inputVar = newVar(ctx);
+        doc.write(`const ${inputVar} = ${accessor}[${keyExpr}];`);
+        compileChild(doc, ctx, shape[key], inputVar, false);
+    }
+}
 function generatePropertyCheck(doc, ctx, def, accessor) {
     const propAccessor = `${accessor}[${JSON.stringify(def.property)}]`;
     generateCheck(doc, ctx, def.schema, propAccessor);
@@ -491,7 +540,7 @@ function generateCustomRefineCheck(doc, ctx, check, accessor) {
         if (isAsyncFunction(def.fn)) {
             throw new ZodCompileAsyncError("z.compile: async .refine() predicates are not supported");
         }
-        const fnConst = addConstant(ctx, def.fn);
+        const fnConst = addUserConstant(ctx, def.fn);
         const throwAsyncConst = addConstant(ctx, throwAsync);
         const resVar = newVar(ctx);
         doc.write(`const ${resVar} = ${fnConst}(${accessor});`);
@@ -519,7 +568,7 @@ function generateCustomRefineCheck(doc, ctx, check, accessor) {
                 throwAsync();
             return fakePayload.issues.length === 0 ? fakePayload.value : exports.INVALID;
         };
-        const helperConst = addConstant(ctx, helperFn);
+        const helperConst = addUserConstant(ctx, helperFn);
         const outVar = newVar(ctx);
         doc.write(`const ${outVar} = ${helperConst}(${accessor});`);
         doc.write(`if (${outVar} === INVALID) return INVALID;`);
@@ -596,6 +645,11 @@ function generateStringFormatCheck(doc, ctx, def, accessor) {
         doc.write(`if (!${validator}(${accessor})) return INVALID;`);
         return accessor;
     }
+    if (fmt === "iban") {
+        const validator = addConstant(ctx, schemas_js_1.isValidIBAN);
+        doc.write(`if (!${validator}(${accessor})) return INVALID;`);
+        return accessor;
+    }
     const formatDef = def;
     if (fmt === "url" ||
         fmt === "httpurl" ||
@@ -794,6 +848,10 @@ function generateCheck(doc, ctx, schema, accessor, needsValue = true) {
         case "custom":
             typeAccessor = generateCustomCheck(doc, ctx, schema, accessor);
             break;
+        case "properties":
+            generatePropertiesChecks(doc, ctx, schema._zod.def, accessor, true);
+            typeAccessor = accessor;
+            break;
         case "transform":
             typeAccessor = generateTransformCheck(doc, ctx, schema, accessor);
             break;
@@ -1511,6 +1569,8 @@ function literalEquality(ctx, accessor, value) {
 }
 function generateIntersectionCheck(doc, ctx, schema, accessor) {
     const def = schema._zod.def;
+    // An unmergeable merge, and a child failing before the merge is even reached, both return INVALID for a case the interpreter answers with a throw.
+    ctx.definite = false;
     const leftOutput = compileChild(doc, ctx, def.left, accessor);
     const rightOutput = compileChild(doc, ctx, def.right, accessor);
     // Hoist the runtime merge helper so recursive object/array merge semantics stay in one place. If the merge is invalid, return INVALID and let the runtime fallback construct canonical errors.
@@ -1580,14 +1640,15 @@ function generateRecordCheck(doc, ctx, schema, accessor) {
         // The runtime runs it against each own enumerable key and writes the value
         // under the key it produced, so compile it once and call it per key.
         const isLoose = def.mode === "loose";
-        const keyFast = addConstant(ctx, compileFn(def.keyType));
+        // the key compiles in its own context, so carry its verdict out: a key schema that can answer INVALID undecidably makes this validator undecidable too
+        const keyFn = compileFn(def.keyType);
+        if (keyFn.definite === false)
+            ctx.definite = false;
+        const keyFast = addConstant(ctx, keyFn);
         const numericConst = addConstant(ctx, regexes.number);
-        const propIsEnumerableConst = addConstant(ctx, Object.prototype.propertyIsEnumerable);
         const outKeyVar = newVar(ctx);
-        doc.write(`for (const ${kVar} of Reflect.ownKeys(${accessor})) {`);
-        doc.indented((d) => {
-            d.write(`if (${kVar} === "__proto__") continue;`);
-            d.write(`if (!${propIsEnumerableConst}.call(${accessor}, ${kVar})) continue;`);
+        // the body runs once per string key and once per symbol key, since a key schema can accept symbols
+        emitOwnKeys(doc, ctx, accessor, kVar, (d) => {
             d.write(`let ${outKeyVar} = ${keyFast}(${kVar});`);
             // Numeric-string retry, mirroring the runtime: a key the schema rejects as a string is tried again as a number, so z.record(z.number(), …) matches the numeric keys JavaScript stringified on the way in.
             d.write(`if (${outKeyVar} === INVALID && typeof ${kVar} === "string" && ${numericConst}.test(${kVar})) ${outKeyVar} = ${keyFast}(Number(${kVar}));`);
@@ -1606,22 +1667,41 @@ function generateRecordCheck(doc, ctx, schema, accessor) {
             const valOutput = compileChild(d, ctx, def.valueType, valueVar);
             d.write(`${outputVar}[${outKeyVar}] = ${valOutput};`);
         });
-        doc.write(`}`);
         return outputVar;
     }
-    // Plain z.string() keys: iterate enumerable own keys and validate each value. Runtime uses Reflect.ownKeys so symbol keys participate in validation; matching that here prevents silently accepting objects with enumerable Symbol keys under z.record(z.string(), ...).
-    const propIsEnumerable = addConstant(ctx, Object.prototype.propertyIsEnumerable);
-    doc.write(`for (const ${kVar} of Reflect.ownKeys(${accessor})) {`);
-    doc.indented((d) => {
-        d.write(`if (${kVar} === "__proto__") continue;`);
-        d.write(`if (!${propIsEnumerable}.call(${accessor}, ${kVar})) continue;`);
-        d.write(`if (typeof ${kVar} !== "string") return INVALID;`);
+    // Plain z.string() keys: every own enumerable string key's value is validated, and an own enumerable symbol key fails the string key schema, as it does in the runtime's Reflect.ownKeys walk.
+    emitOwnKeys(doc, ctx, accessor, kVar, (d) => {
         d.write(`const ${valVar} = ${accessor}[${kVar}];`);
         const valOutput = compileChild(d, ctx, def.valueType, valVar);
         d.write(`${outputVar}[${kVar}] = ${valOutput};`);
+    }, `return INVALID;`);
+    return outputVar;
+}
+// Walks the own enumerable keys of a plain object in Reflect.ownKeys order — strings from getOwnPropertyNames, then symbols — instead of Reflect.ownKeys, whose accumulator made that walk 3–6x the cost of the loop it fed. Both snapshots are taken before any value is read and every key is rechecked with propertyIsEnumerable when visited, exactly the runtime's walk, so a getter that adds, deletes, hides or reveals a key mid-walk sees the runtime's verdict; for-in and Object.keys were no faster and each lost a case (for-in enumerates the prototype chain after the own keys, Object.keys drops a key that is non-enumerable at snapshot time). `body` is written once for the string loop and once for the symbol loop unless `onSymbol` replaces the latter.
+function emitOwnKeys(doc, ctx, accessor, kVar, body, onSymbol) {
+    const propIsEnumerableConst = addConstant(ctx, Object.prototype.propertyIsEnumerable);
+    const symsVar = newVar(ctx);
+    const keysVar = newVar(ctx);
+    const iVar = newVar(ctx);
+    doc.write(`const ${symsVar} = Object.getOwnPropertySymbols(${accessor});`);
+    doc.write(`const ${keysVar} = Object.getOwnPropertyNames(${accessor});`);
+    doc.write(`for (let ${iVar} = 0; ${iVar} < ${keysVar}.length; ${iVar}++) {`);
+    doc.indented((d) => {
+        d.write(`const ${kVar} = ${keysVar}[${iVar}];`);
+        d.write(`if (${kVar} === "__proto__" || !${propIsEnumerableConst}.call(${accessor}, ${kVar})) continue;`);
+        body(d);
+    });
+    doc.write(`}`);
+    doc.write(`for (let ${iVar} = 0; ${iVar} < ${symsVar}.length; ${iVar}++) {`);
+    doc.indented((d) => {
+        d.write(`const ${kVar} = ${symsVar}[${iVar}];`);
+        d.write(`if (!${propIsEnumerableConst}.call(${accessor}, ${kVar})) continue;`);
+        if (onSymbol)
+            d.write(onSymbol);
+        else
+            body(d);
     });
     doc.write(`}`);
-    return outputVar;
 }
 function literalPropertyKey(ctx, key) {
     if (typeof key === "string")
@@ -1677,7 +1757,7 @@ function generateTemplateLiteralCheck(doc, ctx, schema, accessor) {
 function generateLazyCheck(doc, ctx, schema, accessor) {
     // For lazy schemas, we use a cached parser that falls back to runtime Zod parsing This handles recursive schemas correctly by avoiding infinite compilation loops
     const def = schema._zod.def;
-    const getterConst = addConstant(ctx, def.getter);
+    const getterConst = addUserConstant(ctx, def.getter);
     const cacheConst = addConstant(ctx, { parser: null });
     doc.write(`if (!${cacheConst}.parser) {`);
     doc.indented((d) => {
@@ -1701,7 +1781,7 @@ function generatePipeCheck(doc, ctx, schema, accessor) {
     // Validate input type first
     const inputOutput = generateCheck(doc, ctx, def.in, accessor);
     if (def.transform) {
-        // Apply transform and validate output. The transform may read its second `payload` argument (codec transforms like z.stringbool() push issues there) so wrap the call in a helper that spoofs a payload. Pushed issues signal INVALID and the wrapper falls back to the runtime.
+        // Apply transform and validate output. The transform may read its second `payload` argument (codec transforms like z.stringbool() push issues there) so wrap the call in a helper that spoofs a payload. Pushed issues signal INVALID and the wrapper falls back to the runtime, and a plain function handing back a promise answers INVALID too — union parity, but not a decidable rejection at the top level.
         if (isAsyncFunction(def.transform)) {
             throw new ZodCompileAsyncError("z.compile: async transforms in pipes are not supported");
         }
@@ -1715,7 +1795,7 @@ function generatePipeCheck(doc, ctx, schema, accessor) {
                 return exports.INVALID;
             return fakePayload.issues.length === 0 ? result : exports.INVALID;
         };
-        const helperConst = addConstant(ctx, helperFn);
+        const helperConst = addUserConstant(ctx, helperFn);
         const transformedVar = newVar(ctx);
         doc.write(`const ${transformedVar} = ${helperConst}(${inputOutput});`);
         doc.write(`if (${transformedVar} === INVALID) return INVALID;`);
@@ -1739,7 +1819,7 @@ function generateCustomCheck(doc, ctx, schema, accessor) {
             throw new ZodCompileAsyncError("z.compile: async custom predicates are not supported");
         }
         // Custom schema with a predicate function (e.g. z.instanceof). `isAsyncFunction` above is syntactic, so a plain function returning a promise reaches here, and a promise is truthy — it would read as a pass where the interpreter throws.
-        const fnConst = addConstant(ctx, def.fn);
+        const fnConst = addUserConstant(ctx, def.fn);
         const throwAsyncConst = addConstant(ctx, throwAsync);
         const resVar = newVar(ctx);
         doc.write(`const ${resVar} = ${fnConst}(${accessor});`);
@@ -1776,7 +1856,7 @@ function generateCatchCheck(doc, ctx, schema, accessor) {
     });
     doc.write(`})();`);
     const innerConst = addConstant(ctx, def.innerType);
-    const catchConst = addConstant(ctx, def.catchValue);
+    const catchConst = addUserConstant(ctx, def.catchValue);
     const catchHelperConst = addConstant(ctx, runtimeCatch);
     doc.write(`if (${outputVar} === INVALID) {`);
     doc.indented((d) => {
@@ -1803,7 +1883,7 @@ function generateTransformCheck(doc, ctx, schema, accessor) {
                 return exports.INVALID;
             return fakePayload.issues.length === 0 ? result : exports.INVALID;
         };
-        const helperConst = addConstant(ctx, helperFn);
+        const helperConst = addUserConstant(ctx, helperFn);
         const outputVar = newVar(ctx);
         doc.write(`const ${outputVar} = ${helperConst}(${accessor});`);
         doc.write(`if (${outputVar} === INVALID) return INVALID;`);
@@ -1811,3 +1891,22 @@ function generateTransformCheck(doc, ctx, schema, accessor) {
     }
     return accessor;
 }
+
+// seal-cjs-exports
+(function () {
+  var keys = Object.getOwnPropertyNames(exports);
+  for (var i = 0; i < keys.length; i++) {
+    var desc = Object.getOwnPropertyDescriptor(exports, keys[i]);
+    if (!desc || !desc.get || !desc.configurable) continue;
+    var value;
+    try {
+      value = desc.get();
+    } catch (e) {
+      continue;
+    }
+    // a circular require may not have settled this one yet, so leave it live
+    if (value === undefined) continue;
+    Object.defineProperty(exports, keys[i], { value: value, writable: false, enumerable: desc.enumerable, configurable: false });
+  }
+  Object.freeze(exports);
+})();

package/v4/core/compile.d.cts

@@ -1,7 +1,8 @@
 import type * as core from "./core.cjs";
 import type { SomeType } from "./schemas.cjs";
-/** Sentinel value returned by the compiled fast path when validation fails. Internal. */
+/** @internal Sentinel the compiled fast path returns when validation fails. */
 export declare const INVALID: unique symbol;
+/** @internal */
 export type INVALID = typeof INVALID;
 interface CompileFnOptions {
     debug?: boolean | undefined;
@@ -10,6 +11,8 @@ interface CompileFnOptions {
 }
 type CompiledFn<T> = ((input: unknown) => T | INVALID) & {
     code?: string | undefined;
+    /** False when this function's INVALID does not strictly mean "the runtime would reject". */
+    definite?: boolean | undefined;
 };
 /** Raised when the schema contains async refinements or transforms. Surfaces only under `compile(schema, { strict: true })`. */
 export declare class ZodCompileAsyncError extends Error {
@@ -43,9 +46,20 @@ export interface CompileOptions {
  */
 export declare function compile<T extends SomeType>(schema: T, options?: CompileOptions): T;
 /**
- * Generate the standalone compiled function: a parser by default, a validator under
- * `assertOnly`. Returns either the parsed value, `true` where nothing reads the output,
- * or the `INVALID` sentinel. Internal — consumers should use `compile()`.
+ * Install an already-generated parser as a schema's fast path. Returns a clone; the original is
+ * unchanged.
+ *
+ * The parser takes the input and returns the parsed value, or `INVALID` to hand the parse to the
+ * runtime. It must be synchronous and forward-direction, and it must build fresh output rather than
+ * return its input — Zod cannot check either, and a wrong *success* is returned to the caller as-is.
+ *
+ * `compile()` is the ordinary entry point. This is for a build-time or native compiler that produces
+ * a parser where `new Function` is unavailable.
+ */
+export declare function withParser<T extends SomeType>(schema: T, parser: (input: unknown) => core.output<T> | INVALID): T;
+/**
+ * @internal Generate the standalone compiled function: a parser by default, a validator under
+ * `assertOnly`. Returns the parsed value, `true` where nothing reads the output, or `INVALID`. Consumers use `compile()`.
  */
 export declare function compileFn<T extends SomeType>(schema: T, options?: CompileFnOptions): CompiledFn<core.output<T>>;
 export {};

package/v4/core/compile.d.ts

@@ -1,7 +1,8 @@
 import type * as core from "./core.js";
 import type { SomeType } from "./schemas.js";
-/** Sentinel value returned by the compiled fast path when validation fails. Internal. */
+/** @internal Sentinel the compiled fast path returns when validation fails. */
 export declare const INVALID: unique symbol;
+/** @internal */
 export type INVALID = typeof INVALID;
 interface CompileFnOptions {
     debug?: boolean | undefined;
@@ -10,6 +11,8 @@ interface CompileFnOptions {
 }
 type CompiledFn<T> = ((input: unknown) => T | INVALID) & {
     code?: string | undefined;
+    /** False when this function's INVALID does not strictly mean "the runtime would reject". */
+    definite?: boolean | undefined;
 };
 /** Raised when the schema contains async refinements or transforms. Surfaces only under `compile(schema, { strict: true })`. */
 export declare class ZodCompileAsyncError extends Error {
@@ -43,9 +46,20 @@ export interface CompileOptions {
  */
 export declare function compile<T extends SomeType>(schema: T, options?: CompileOptions): T;
 /**
- * Generate the standalone compiled function: a parser by default, a validator under
- * `assertOnly`. Returns either the parsed value, `true` where nothing reads the output,
- * or the `INVALID` sentinel. Internal — consumers should use `compile()`.
+ * Install an already-generated parser as a schema's fast path. Returns a clone; the original is
+ * unchanged.
+ *
+ * The parser takes the input and returns the parsed value, or `INVALID` to hand the parse to the
+ * runtime. It must be synchronous and forward-direction, and it must build fresh output rather than
+ * return its input — Zod cannot check either, and a wrong *success* is returned to the caller as-is.
+ *
+ * `compile()` is the ordinary entry point. This is for a build-time or native compiler that produces
+ * a parser where `new Function` is unavailable.
+ */
+export declare function withParser<T extends SomeType>(schema: T, parser: (input: unknown) => core.output<T> | INVALID): T;
+/**
+ * @internal Generate the standalone compiled function: a parser by default, a validator under
+ * `assertOnly`. Returns the parsed value, `true` where nothing reads the output, or `INVALID`. Consumers use `compile()`.
  */
 export declare function compileFn<T extends SomeType>(schema: T, options?: CompileFnOptions): CompiledFn<core.output<T>>;
 export {};