perf(v4): use shared method references to reduce per-schema heap cost

[gsoldevila]

Summary

Zod v4 assigns every schema method (parse, check, optional, email, etc.) as an own-property arrow function on each schema instance. Because arrow functions close over inst, each instance gets a unique function object per method — roughly 50+ unique closures per schema.

For applications (like Kibana) that define hundreds of schemas at startup, this causes two distinct heap problems:

1. Closure explosion: ~50 unique (closure) objects per instance, plus one system/Context per closure.
2. Dictionary-mode objects: with ~70+ own properties per instance, V8 switches from its fast "hidden-class" property storage to a slower hash-map ((object properties) in heap snapshots), degrading property-access performance by up to 24×.

---

Optimisations (2 commits)

Commit 1 — Shared function references

Builder-style methods (check, with, clone, brand, optional, nullable, describe, and all string / number / bigint / date / array / object validators) are lifted out of the per-instance initialiser closures and defined once as named function declarations at module scope, using this instead of a captured inst.

All instances share the same ~50 function objects for these methods, eliminating the closure-per-instance overhead.

Not changed — parse/decode and their variants (parse, safeParse, parseAsync, safeParseAsync, spa, encode, decode, and all Async/safe* variants) remain as per-instance closures because they are commonly called in a detached manner:

const parse = schema.parse;
parse("hello");           // must work — would fail if parse relied on `this`

arr.map(schema.safeParse); // same

Commit 2 — Prototype-based method dispatch

Even with shared references, instances still carried ~70 own properties (13 parse-family closures + ~57 shared references), keeping V8 in dictionary mode.

This commit moves all shared methods from own properties on each instance to the prototype of each concrete schema constructor, using two module-level helpers:

• _protoInitMap — WeakMap<prototype, Set<key>> that tracks which initialisers have already run per prototype.
• _initProto(inst, key, methods) — sets methods on Object.getPrototypeOf(inst) exactly once per (prototype, key) pair.

Because each schema constructor (ZodString, ZodNumber, ZodObject, …) has its own prototype, the first instance of each type triggers a one-time prototype setup; all subsequent instances inherit those methods at zero marginal cost.

Per-instance own properties are now limited to:

• Data properties: def, type, _def, toJSONSchema, ~standard, _zod
• Type-specific data: format, minLength, maxLength (ZodString), etc.
• Parse-family closures (kept per-instance for detached-call compatibility)

This brings own-property count from ~70 to ~15–22, keeping most schema instances in V8's fast-property mode.

The // support prototype modifications loop in $constructor (core.ts) is removed — it was copying all prototype methods back onto each instance via .bind(), defeating the optimisation. Runtime prototype extensions continue to work naturally via the JS prototype chain (no copy loop needed).

---

Measurements (Kibana, ~500k schema instances at startup)

Metric	Unpatched main	Commit 1 only	This PR (both commits)
(object properties) vs Zod v3 baseline	+100.84 MB	+100 MB	+30.65 MB
(closure) reduction vs unpatched main	—	−54 MB	−37 MB
Net heap vs unpatched main	—	−33 MB (−3%)	−50 MB (−4.9%)
Net heap vs Zod v3 baseline	+200 MB	~+167 MB	+148 MB

---

Behaviour change

The prototype extension pattern — adding a method to z.ZodType.prototype and expecting it to appear on all schema instances via the copy loop — no longer works. Users must extend the concrete schema prototype instead:

// Before (relied on the copy loop):
z.ZodType.prototype.myMethod = function () { … };
z.string().myMethod(); // worked via copy loop

// After (standard JS prototype extension):
z.ZodString.prototype.myMethod = function () { … };
z.string().myMethod(); // works via prototype chain

The three existing prototype extension tests are updated to reflect this.

---

Backward compatibility

• 3575/3575 tests pass (all existing test scenarios unchanged).
• Parse/safeParse detached-call pattern (const p = schema.parse; p(data)) works unchanged.
• TypeScript interface types are unchanged; only implementations gain as any casts.

---

Related

• Upstream issue: Schema instances have ~91 own properties → dictionary mode → ~24× slower property access vs Zod 3 colinhacks/zod#5760
• Kibana patch-package workaround: elastic/kibana#263121

---

How to use this branch locally

Use this if you want to test the memory improvements in your own project before they land upstream.

1. Clone and build

git clone https://github.com/gsoldevila/zod.git
cd zod
pnpm install
pnpm build

The built output lives in packages/zod/ (CJS in *.cjs, ESM in *.js).

2. Point your project at the local build

In your project's package.json, replace the zod version string with a file: reference to the built package directory:

{
  "dependencies": {
    // Replace the published version:
    // "zod": "4.3.6",

    // With a path to the local build:
    "zod": "file:/absolute/path/to/zod/packages/zod"
  },
  ...
  "resolutions": {
    "zod": "file:/absolute/path/to/zod/packages/zod"
  }
}

npm / pnpm users: use npm install or pnpm install after editing package.json.
Yarn users: run yarn install — Yarn 1.x copies the package contents rather than symlinking, so re-run yarn install after each pnpm build if you rebuild.

3. Re-install

yarn kbn reset
yarn kbn bootstrap

4. Verify

import { z } from 'zod';

const s1 = z.string();
const s2 = z.string();

// Shared prototype methods — same function reference:
console.assert(s1.optional === s2.optional);        // true
console.assert(Object.getPrototypeOf(s1).optional === Object.getPrototypeOf(s2).optional); // true

// Per-instance parse closures — different references (by design):
console.assert(s1.parse !== s2.parse);              // true

---

Made with Cursor

[gsoldevila]

Improved patch on #2