feat(v4): parseMaybeAsync / safeParseMaybeAsync (JIT-preserving, follow-up to #5924) - #5948

TL;DR — Adds parseMaybeAsync / safeParseMaybeAsync (instance methods + core functions) that return sync when the schema is sync and a Promise only when an async refinement is hit. Reopens #5924 with an implementation that preserves the ZodObject JIT fastpass and adds a WeakSet cache for async-observed schemas, bringing the async-path overhead down from ~14.5x to ~1.4x vs safeParseAsync.

Key changes

• New parseMaybeAsync / safeParseMaybeAsync API — exposed on both ZodType (classic) and ZodMiniType (mini), typed as util.MaybeAsync<T>, with a JSDoc caveat covering side-effect doubling and sticky async observation.
• Sync-first execution — try ctx.async = false first so the ZodObject fastpass stays engaged; fall back to an async run on $ZodAsyncError or a returned Promise.
• WeakSet cache for async-observed schemas — after a schema throws $ZodAsyncError once, subsequent calls skip the sync attempt entirely and route straight to the async path. Sticky per schema instance.
• Purely additive — ~standard.validate is deliberately left on its existing safeParse + try/catch → safeParseAsync path; the internal rewire is deferred to a separable PR.
• Three-scenario micro-benchmark — packages/bench/object-maybe-async.ts covers flat sync, nested sync, and mostly-sync-with-one-async-refine.

_{Summary ｜ 8 files ｜ 1 commit ｜ base: main ← feat/parse-maybe-async-jit-preserving}

JIT-preserving sync-first execution

Before: #5924 set ctx.async = true unconditionally, which disabled the ZodObject fastpass (jit && fastEnabled && ctx?.async === false && ctx.jitless !== true) and regressed sync object parsing by ~5x.
After: _parseMaybeAsync / _safeParseMaybeAsync build a syncCtx with async: false, run the schema, and return inline when it completes without throwing $ZodAsyncError and without returning a Promise.

The sync-first branch is intentionally inlined rather than routed through a higher-order finalize factory — the PR notes that extracting a shared { ctx, result } helper regresses the sync path ~12x (per-call alloc + lost V8 inlining).

core/parse.ts

Sticky WeakSet cache for async-observed schemas

Before: A schema with an async refinement paid the cost of a short-circuited sync prefix plus the async run on every call (~14.5x vs safeParseAsync in the bench).
After: The first $ZodAsyncError adds the schema to a module-level WeakSet; subsequent calls skip the sync attempt and go straight to the async path (~1.4x steady-state, bounded by the WeakSet lookup and wrapper).

What are the tradeoffs?

Two caveats, both now called out in JSDoc on the public methods:

1. Side-effect doubling on first async observation. Sync work that runs before the first async step executes twice (once in the aborted sync attempt, once in the async re-run). For schemas with non-idempotent sync transforms composed with an async refinement this is observable. The JSDoc points users at parseAsync for those cases.
2. Sticky async routing. Once a schema is in the WeakSet, every subsequent call returns a Promise — even for inputs that would have resolved synchronously (e.g. the sync branch of z.union([sync, async]), or a preprocess-gated async branch). Fully avoiding the double-walk or the stickiness would require changing the $ZodAsyncError convention and is out of scope.

core/parse.ts · object-maybe-async.ts

Public API surface on ZodType and ZodMiniType

Before: Callers that didn't know up front whether a schema was async had to call safeParseAsync defensively and always await, forcing a microtask even for fully sync schemas.
After: schema.parseMaybeAsync(data) and schema.safeParseMaybeAsync(data) return core.output<T> / SafeParseResult<...> directly for sync schemas and a Promise of the same when async work is needed.

The instance wiring mirrors the existing parse / parseAsync pairs in both entry points, and the mini parse.ts re-export list picks up the two new names alongside parseAsync / safeParseAsync. Test coverage in parse-maybe-async.test.ts for both classic and mini asserts sync return, Promise return, and error propagation for sync and async paths.

classic/schemas.ts · mini/schemas.ts · classic/parse.ts · classic/tests/parse-maybe-async.test.ts

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

@colinhacks could you take a look when you have a moment? This is the follow-up to #5924 — the regression you flagged was caused by ctx.async = true upfront bypassing the ZodObject JIT fastpass (gated on ctx?.async === false strict). Running sync first and falling back to async only on $ZodAsyncError keeps the fastpass engaged; benchmarks now show parity with safeParse on sync object schemas.

Would value your read on whether the try-sync-then-async tradeoff (one short-circuited sync pass on async schemas, bailing at the first async check) is acceptable, or if you'd prefer a different shape entirely.

Pushed a perf follow-up (393876e) after another profiling pass:

• Sync path: delegates straight to _parse / _safeParse, so it runs the same JIT-compiled function as safeParse. On sync objects it's now on par (40.6 vs 39.6 ns per parse on a flat object); before this commit it was ~1.3x slower.
• Async path: delegates to _parseAsync / _safeParseAsync instead of ar.then(closure). The per-call closure cost about 1µs. On the mostly-sync + 1 async refine bench it's now ~10% faster than safeParseAsync, where it used to be ~1.25x slower.
• Cache: the module-level WeakSet is gone; a per-instance _zod.asyncSeen flag replaces it. No global state, and clones start fresh.
• Tests: added coverage for per-instance caching, the sticky union case, the side-effect count, and sync propagation of user throws. Each new test catches at least one deliberately broken version of the implementation.