2. $constructor Prototype Trait System & Immutability

Every schema, check, and error class in Zod v4.6.7 is built on a custom prototype-based trait factory—$constructor—defined in packages/zod/src/v4/core/core.ts alongside descriptor and memoization utilities in packages/zod/src/v4/core/util.ts. Rather than using deep ES6 class extends hierarchies, $constructor composes schema behaviors as flat, idempotent traits, isolates all internal metadata inside a single non-enumerable _zod slot, and replaces Function.prototype[Symbol.hasInstance] with a Set<string> lookup that works across v4/core, v4/classic, v4/mini, and dual CJS/ESM module realms.

02_constructor_and_traits_1
How $constructor (v4/core/core.ts) Composes Multi-Trait Schemas, Isolates _zod Internals, and Evaluates instanceof via Trait Sets
Source Code 
from drawlib.canvas import save, setup
from drawlib.icons import phosphor
from drawlib.lines import line
from drawlib.shapes import rectangle
from drawlib.smartarts import CardList, Panel
from drawlib.styles import Styles
from drawlib.text import text

setup(width=176, height=112)

text(
    (88, 107.5),
    "$constructor Prototype Trait Composition & Internals Architecture",
    style=Styles.DarkBold.patch(text_size=13.5),
)
text(
    (88, 103.5),
    "How packages/zod/src/v4/core/core.ts composes multi-trait schemas, isolates _zod internals, and evaluates instanceof via trait sets",
    style=Styles.Muted.patch(text_size=10.0),
)

# ==============================================================================
# TOP LEFT: 1. $constructor Factory & _.init() Pipeline (x=5..86, y=49..99)
# ==============================================================================
p_init = Panel(
    "1. $constructor(name, initializer, proto?, params?)",
    style=Styles.PrimaryNeutral,
    header_style=Styles.Primary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    icon=phosphor.gear,
    icon_style=Styles.White,
    header_height=6.0,
)
p_init.draw(xy=(5, 49), width=81, height=50)

init_cards = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=9.5),
    description_style=Styles.Muted.patch(text_size=9.5),
    badge_shape="none",
    direction="vertical",
    spacing=1.4,
)
init_cards.add(
    "Step A: Non-Enumerable _zod Slot (new Internals)",
    description="Attaches inst._zod ({ enumerable: false }) with def, constr, traits",
    style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=9.5),
    description_style=Styles.White.patch(text_size=9.5),
)
init_cards.add(
    "Step B: Diamond Idempotency Guard (traits.has)",
    description="Skips duplicate init if traits.has(name); adds name & runs init",
)
init_cards.add(
    "Step C: WeakSet Prototype Member Installation",
    description="Runs installMembers(target, proto) once per prototype via WeakSet",
)
init_cards.add(
    "Step D: Deferred Queue & Post-Processor Hook",
    description="Drains _zod.deferred callbacks and runs globalConfig.postProcessor",
)
init_cards.draw(xy=(7.5, 51.0), width=76, height=40.0)

# ==============================================================================
# TOP RIGHT: 2. Multi-Trait Composition DAG (ZodEmail) (x=90..171, y=49..99)
# ==============================================================================
p_dag = Panel(
    "2. Multi-Trait Diamond Composition (ZodEmail)",
    style=Styles.Neutral,
    header_style=Styles.Secondary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    icon=phosphor.git_merge,
    icon_style=Styles.White,
    header_height=6.0,
)
p_dag.draw(xy=(90, 49), width=81, height=50)

# Row 1 (Roots in v4/core)
rectangle((111.0, 86.5), width=35.0, height=8.0, style=Styles.White.patch(shape_r=1.5))
text((111.0, 88.2), "core.$ZodType.init", style=Styles.DarkBold.patch(text_size=9.5))
text((111.0, 84.8), "Base schema (_zod.parse / run)", style=Styles.Muted.patch(text_size=9.5))

rectangle((150.0, 86.5), width=35.0, height=8.0, style=Styles.White.patch(shape_r=1.5))
text((150.0, 88.2), "core.$ZodCheck.init", style=Styles.DarkBold.patch(text_size=9.5))
text((150.0, 84.8), "Base check (_zod.check / bag)", style=Styles.Muted.patch(text_size=9.5))

# Row 2 (String & CheckStringFormat)
rectangle((111.0, 74.5), width=35.0, height=8.0, style=Styles.White.patch(shape_r=1.5))
text((111.0, 76.2), "core.$ZodString.init", style=Styles.DarkBold.patch(text_size=9.5))
text((111.0, 72.8), "typeof === 'string' & bag", style=Styles.Muted.patch(text_size=9.5))

rectangle((150.0, 74.5), width=35.0, height=8.0, style=Styles.White.patch(shape_r=1.5))
text((150.0, 76.2), "core.$ZodCheckStringFormat", style=Styles.DarkBold.patch(text_size=9.5))
text((150.0, 72.8), "Regex / format validator trait", style=Styles.Muted.patch(text_size=9.5))

line((111.0, 82.5), (111.0, 78.5), arrow_head="->", style=Styles.PrimaryBold)
line((150.0, 82.5), (150.0, 78.5), arrow_head="->", style=Styles.SecondaryBold)

# Row 3 (Merged $ZodStringFormat -> $ZodEmail)
rectangle((130.5, 63.5), width=74.0, height=7.5, style=Styles.PrimaryFlat.patch(shape_r=1.5))
text((130.5, 65.2), "core.$ZodStringFormat.init  -->  ZodEmail.init", style=Styles.WhiteBold.patch(text_size=9.5))
text((130.5, 61.8), "Merges schema + check traits: works as z.email() AND .check(z.email())", style=Styles.White.patch(text_size=9.5))

line((111.0, 70.5), (120.0, 67.25), arrow_head="->", style=Styles.PrimaryBold)
line((150.0, 70.5), (141.0, 67.25), arrow_head="->", style=Styles.SecondaryBold)

# Row 4 (Classic vs Mini wrappers)
rectangle((111.0, 53.5), width=35.0, height=5.5, style=Styles.PrimaryNeutral.patch(shape_r=1.2))
text((111.0, 53.5), "classic.ZodEmail", style=Styles.DarkBold.patch(text_size=9.5))

rectangle((150.0, 53.5), width=35.0, height=5.5, style=Styles.PrimaryNeutral.patch(shape_r=1.2))
text((150.0, 53.5), "mini.ZodMiniEmail", style=Styles.DarkBold.patch(text_size=9.5))

line((120.0, 59.75), (111.0, 56.25), arrow_head="->", style=Styles.PrimaryBold)
line((141.0, 59.75), (150.0, 56.25), arrow_head="->", style=Styles.PrimaryBold)

# ==============================================================================
# BOTTOM: 3. Runtime Memory Layout & Trait-Set [Symbol.hasInstance] (x=5..171, y=5..44)
# ==============================================================================
p_mem = Panel(
    "3. V8 Fast-Property Instance Layout (_zod Internals) & Cross-Realm instanceof Dispatch",
    style=Styles.Neutral,
    header_style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    icon=phosphor.cpu,
    icon_style=Styles.White,
    header_height=6.0,
)
p_mem.draw(xy=(5, 5), width=166, height=39)

mem_left = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=9.5),
    description_style=Styles.Muted.patch(text_size=9.5),
    badge_shape="none",
    direction="vertical",
    spacing=1.4,
)
mem_left.add(
    "inst._zod.def & inst._zod.constr (In-Object Slots)",
    description="Immutable config { type: 'string' } + constructor ref for clone()",
    style=Styles.PrimaryNeutral,
)
mem_left.add(
    "inst._zod.run & inst._zod.parse (Validation Closures)",
    description="parse(payload, ctx) checks type; run(payload, ctx) runs checks",
)
mem_left.add(
    "Prototype Chain: inst._zod --> zodProto (defineLazyInternal)",
    description="Shared lazy getters (pattern, propValues) live on zodProto once",
)
mem_left.draw(xy=(7.5, 7.0), width=79, height=29.0)

mem_right = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=9.5),
    description_style=Styles.Muted.patch(text_size=9.5),
    badge_shape="none",
    direction="vertical",
    spacing=1.4,
)
mem_right.add(
    "inst._zod.traits = Set(7) { '$ZodType', 'ZodString', 'ZodCheck', ... }",
    description="Records all initialized trait names in an O(1) Set across diamond",
    style=Styles.AccentFlat,
    text_style=Styles.WhiteBold.patch(text_size=9.5),
    description_style=Styles.White.patch(text_size=9.5),
)
mem_right.add(
    "inst instanceof core.$ZodString  -->  true",
    description="Custom [Symbol.hasInstance] checks inst._zod.traits.has(name)",
    style=Styles.PrimaryNeutral,
)
mem_right.add(
    "inst instanceof core.$ZodCheck  -->  true",
    description="True for both schema and check hierarchies across CJS/ESM realms",
    style=Styles.PrimaryNeutral,
)
mem_right.draw(xy=(89.5, 7.0), width=79, height=29.0)

save()

1. Why Zod v4 Replaced ES6 Classes with $constructor

In JavaScript and TypeScript, standard ES6 class B extends A inheritance enforces a strict single-inheritance prototype chain. For a validation library like Zod v4, single inheritance breaks down in three critical places:

  1. Dual Skin Facades (v4/classic vs v4/mini): Every schema type in v4/core (such as $ZodString, $ZodObject, $ZodUnion) must be wrapped by both ZodType in v4/classic (which attaches .min(), .max(), .optional(), .parse()) and ZodMiniType in v4/mini (which attaches only .parse(), .check(), .clone()). Under ES6 classes, ZodString cannot simultaneously extend both ZodType and $ZodString if $ZodString already extends $ZodType.
  2. Schema + Check Dual-Role Types ($ZodStringFormat): In Zod v4, string format validators like z.email(), z.uuid(), and z.url() are simultaneously standalone schemas (z.email().parse(val)) and composable validation checks (z.string().check(z.email())). That requires $ZodStringFormat to inherit both the $ZodString schema lifecycle and the $ZodCheckStringFormat check lifecycle.
  3. Cross-Realm instanceof Fragility: In monorepos, serverless bundles, or dual CommonJS/ESM dependency graphs, Function.prototype[Symbol.hasInstance] fails whenever two copies of a class constructor exist in memory, or when a library accepts a schema created by zod/mini and checks schema instanceof $ZodType.

$constructor (packages/zod/src/v4/core/core.ts:L51-145) solves all three problems by decoupling trait initialization (_.init) and type membership (inst._zod.traits) from JavaScript's single prototype chain.

2. Inside $constructor (packages/zod/src/v4/core/core.ts)

2.1 Signature and Type-Level Brand Inference

// packages/zod/src/v4/core/core.ts
export type $constructor<T extends ZodTrait, D = T["_zod"]["def"]> = {
  new (def: D): T;
  init(inst: T, def: D): asserts inst is T;
};

Calling $constructor(name, initializer, proto?, params?) returns a constructor function _ that can be invoked with new _(def) to instantiate a concrete object, or via _.init(inst, def) to compose its trait logic onto an existing instance created by a sub-trait.

2.2 zodProto and V8 Hidden-Class Optimization (Internals)

Every time $constructor is called to define a trait, it creates a dedicated prototype object zodProto = {} and an internal constructor Internals:

// packages/zod/src/v4/core/core.ts
const zodProto = {};
function Internals(this: any, def: any) {
  this.def = def;
  this.constr = _;
  this.traits = new Set();
}
Internals.prototype = zodProto;

Why does core.ts allocate inst._zod via new (Internals as any)(def) instead of an object literal { def, constr: _, traits: new Set() }?

  • Pre-sized In-Object Properties: V8 assigns a dedicated hidden class (Map) to Internals with pre-allocated in-object slots for def, constr, and traits.
  • Shared Prototype for Lazy Internals (zodProto): When schemas define lazy computed properties on _zod via util.defineLazyInternal(inst, key, compute)—such as _zod.pattern on regex checks or _zod.propValues on objects and literals—the getter is installed once on zodProto (Object.getPrototypeOf(inst._zod)) rather than calling Object.defineProperty on every individual schema instance. This avoids per-instance descriptor overhead and prevents V8 from demoting _zod to dictionary mode.

2.3 The 4-Step init(inst, def) Lifecycle

When init(inst, def) runs on a schema or check instance, it executes four deterministic steps:

  1. Non-Enumerable _zod Attachment: If inst._zod does not exist yet (which is true on the outermost constructor call before parent traits run), core.ts defines _zod using a shared descriptor _zodDesc = { value: undefined, enumerable: false } inside a try/finally block that clears _zodDesc.value = undefined afterward so the global descriptor never retains a reference to the last-created schema in memory.
  2. Idempotent Trait Guard:
    if (inst._zod.traits.has(name)) {
  return;
}
inst._zod.traits.add(name);
    Because diamond trait graphs are common—for example, ZodString calls ZodType.init (which calls $ZodType.init) and $ZodString.init (which also calls $ZodType.init)—checking inst._zod.traits.has(name) ensures each trait initializer runs at most once per instance.
  3. Initializer Execution: initializer(inst, def) runs, allowing parent traits to be composed first (ParentTrait.init(inst, def)) before specializing inst._zod.parse or inst._zod.check.
  4. WeakSet-Guarded Prototype Installation: Each constructor maintains a const initialized = new WeakSet<object>(). The first time an instance with a given Object.getPrototypeOf(inst) passes through init, installMembers(target, protoMembers) copies all lazy/bound property descriptors onto target and binds any direct prototype functions. Subsequent instances of the same constructor skip prototype installation completely (O(1) WeakSet.has check).

2.4 Fast Error Subclassing (newError for $ZodRealError)

When $constructor is called with params: { Parent: Error } (used by $ZodRealError in packages/zod/src/v4/core/errors.ts), calling new Error() in V8 normally captures a full call stack trace, which is expensive during validation failure paths. core.ts bypasses stack frame capture with newError(BaseClass):

// packages/zod/src/v4/core/core.ts
function newError(BaseClass: ErrorConstructor) {
  const _limit = Error.stackTraceLimit;
  Error.stackTraceLimit = 0;
  const err = new BaseClass();
  Error.stackTraceLimit = _limit;
  return err;
}

2.5 Cross-Realm [Symbol.hasInstance] Dispatch

Finally, $constructor defines a custom Symbol.hasInstance trap on _:

Object.defineProperty(_, Symbol.hasInstance, {
  value: (inst: any) => {
    if (params?.Parent && inst instanceof params.Parent) return true;
    return inst?._zod?.traits?.has(name);
  },
});

Because inst?._zod?.traits is a plain Set<string> of trait names (e.g., "$ZodType", "$ZodString", "$ZodCheck", "$ZodEmail"), schema instanceof $ZodType and schema instanceof $ZodCheck both evaluate to true in O(1) time—even across v4/classic and v4/mini or across duplicate module instances in a bundler.

3. Copy-on-Write Immutability & Cycle-Safe Memoization (v4/core/util.ts)

Every schema method in Zod v4 is strictly immutable. Chaining .min(3), .optional(), or .check(...) never mutates an existing schema's _zod.def.checks array in place; instead, it creates a lightweight clone via util.clone() while relying on cycle-safe lazy getters (defineLazy and defineLazyInternal) to defer expensive metadata computation until first parse.

02_constructor_and_traits_2
Copy-on-Write Immutability (clone), Cycle-Safe Lazy Memoization (defineLazy / defineLazyInternal), and Prototype Descriptors (util.ts)
Source Code 
from drawlib.canvas import save, setup
from drawlib.icons import phosphor
from drawlib.smartarts import CardList, Panel
from drawlib.styles import Styles
from drawlib.text import text

setup(width=176, height=96)

text(
    (88, 91.5),
    "Copy-on-Write Immutability (clone) & Cycle-Safe Lazy Memoization (util.ts)",
    style=Styles.DarkBold.patch(text_size=13.5),
)
text(
    (88, 87.5),
    "How packages/zod/src/v4/core/util.ts guarantees immutable schema chaining, breaks recursive cycles, and binds prototype descriptors",
    style=Styles.Muted.patch(text_size=10.0),
)

# ==============================================================================
# PANEL 1 (LEFT): Copy-on-Write clone(inst, def) (x=5..58, y=6..83)
# ==============================================================================
p_clone = Panel(
    "1. Copy-on-Write clone(inst, def)",
    style=Styles.PrimaryNeutral,
    header_style=Styles.Primary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    icon=phosphor.copy,
    icon_style=Styles.White,
    header_height=6.0,
)
p_clone.draw(xy=(5, 6), width=53, height=77)

clone_cards = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=9.5),
    description_style=Styles.Muted.patch(text_size=9.5),
    badge_shape="none",
    direction="vertical",
    spacing=1.6,
)
clone_cards.add(
    "Base Schema: s1 = z.string()",
    description="s1._zod.constr = ZodString; checks: []",
)
clone_cards.add(
    "s1.min(3) --> s1.check(minLength(3))",
    description="Calls clone(s1, { ...def, checks: [c1] })",
    style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=9.5),
    description_style=Styles.White.patch(text_size=9.5),
)
clone_cards.add(
    "Cloned: s2 = new s1._zod.constr(newDef)",
    description="Sets s2._zod.parent = s1; wires _zod.run",
)
clone_cards.add(
    "Zero In-Place Mutation Guarantee",
    description="s1 stays unmutated (_zod.run === parse)",
    style=Styles.PrimaryNeutral,
)
clone_cards.draw(xy=(7.5, 8.5), width=48, height=66.5)

# ==============================================================================
# PANEL 2 (CENTER): Cycle-Safe Lazy Memoization (x=61.5..114.5, y=6..83)
# ==============================================================================
p_lazy = Panel(
    "2. Cycle-Safe Lazy Evaluation",
    style=Styles.Neutral,
    header_style=Styles.Secondary,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    icon=phosphor.arrows_clockwise,
    icon_style=Styles.White,
    header_height=6.0,
)
p_lazy.draw(xy=(61.5, 6), width=53, height=77)

lazy_cards = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=9.5),
    description_style=Styles.Muted.patch(text_size=9.5),
    badge_shape="none",
    direction="vertical",
    spacing=1.6,
)
lazy_cards.add(
    "defineLazy(object, key, getter)",
    description="Used for z.lazy() getter, ~standard, shape",
    style=Styles.PrimaryNeutral,
)
lazy_cards.add(
    "EVALUATING Sentinel Cycle Breaker",
    description="Returns undefined if re-entered mid-cycle",
    style=Styles.AccentFlat,
    text_style=Styles.WhiteBold.patch(text_size=9.5),
    description_style=Styles.White.patch(text_size=9.5),
)
lazy_cards.add(
    "defineLazyInternal(inst, key, fn)",
    description="Installed once on zodProto (propValues)",
    style=Styles.PrimaryNeutral,
)
lazy_cards.add(
    "Temporary breaker & Partial Reset",
    description="Deletes partial cycle so top caller caches",
)
lazy_cards.draw(xy=(64.0, 8.5), width=48, height=66.5)

# ==============================================================================
# PANEL 3 (RIGHT): Prototype Descriptor Table (x=118..171, y=6..83)
# ==============================================================================
p_desc = Panel(
    "3. Prototype Descriptor DSL",
    style=Styles.PrimaryNeutral,
    header_style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=10.5),
    icon=phosphor.stack,
    icon_style=Styles.White,
    header_height=6.0,
)
p_desc.draw(xy=(118, 6), width=53, height=77)

desc_cards = CardList(
    style=Styles.White,
    text_style=Styles.DarkBold.patch(text_size=9.5),
    description_style=Styles.Muted.patch(text_size=9.5),
    badge_shape="none",
    direction="vertical",
    spacing=1.6,
)
desc_cards.add(
    "defineBound(proto, key, fn)",
    description="Binds fn.bind(this) on first property read",
    style=Styles.PrimaryFlat,
    text_style=Styles.WhiteBold.patch(text_size=9.5),
    description_style=Styles.White.patch(text_size=9.5),
)
desc_cards.add(
    "derived(computes, table)",
    description="Freezes def.shape via ShapeGetter.raw",
)
desc_cards.add(
    "own(defineFn) & hide(defineFn)",
    description="Controls enumerable: true vs false flags",
)
desc_cards.add(
    "Zero Allocation Until Read",
    description="new ZodString(def) binds zero closures",
    style=Styles.PrimaryNeutral,
)
desc_cards.draw(xy=(120.5, 8.5), width=48, height=66.5)

save()

4. Deep Dive into util.ts: Cloning, Lazy Evaluation, and Prototype Descriptors

4.1 clone(inst, def, params) (packages/zod/src/v4/core/util.ts:L645-649)

// packages/zod/src/v4/core/util.ts
export function clone<T extends schemas.$ZodType>(inst: T, def?: T["_zod"]["def"], params?: { parent: boolean }): T {
  const cl = new inst._zod.constr(def ?? inst._zod.def);
  if (!def || params?.parent) cl._zod.parent = inst;
  return cl as any;
}

When you call schema.check(minLength(3)) or schema.optional(), Zod calls clone(this, { ...this._zod.def, checks: [...(this._zod.def.checks ?? []), ...checks] }). Because inst._zod.constr points to the exact leaf constructor that created inst (e.g., ZodString in v4/classic or ZodMiniString in v4/mini), clone() always produces a new instance of the same skin and re-runs the $ZodType deferred initialization hook—which automatically switches cl._zod.run from the zero-check fast path (inst._zod.parse) to the check-runner wrapper once checks.length > 0.

4.2 defineLazy vs defineLazyInternal (util.ts:L338-361 & L1220-1258)

Zod v4 provides two distinct lazy evaluation primitives tailored for different parts of a schema's lifecycle:

Primitive Target Object Cycle-Breaking Mechanism Primary Use Cases in v4/core
defineLazy(object, key, getter) Individual object (inst or def) Sets closure state value = EVALUATING; returns undefined if re-entered while value === EVALUATING. z.lazy() (def.getter), Standard Schema (inst["~standard"]), $ZodUnion options, $ZodError.issues.
defineLazyInternal(inst, key, compute) Shared zodProto (Object.getPrototypeOf(inst._zod)) Temporarily defines breaker (get: () => undefined) on this (inst._zod). If a recursive cycle hits breaker, deletes the property afterward instead of memoizing an incomplete result! _zod.propValues (discriminated union lookup tables), _zod.pattern (merged regexes), _zod.values (enum/literal sets), _zod.iscanonical.

Notice the subtlety in defineLazyInternal (util.ts:L1220-1258): if a mutually recursive union or object attempts to read _zod.propValues while _zod.propValues is already being computed higher on the call stack, the recursive inner read receives undefined via breaker and sets wasRecursive = true. When the inner frame returns, defineLazyInternal refuses to cache the partial result (Reflect.deleteProperty(this, key)), ensuring only the top-level caller with complete information memoizes the final value.

4.3 Declarative Prototype Descriptors (members, defineBound, derived)

In v4/classic/schemas.ts and v4/mini/schemas.ts, public methods and getters on ZodType and ZodObject are declared via util.members(proto, table):

// Example from packages/zod/src/v4/core/schemas.ts ($ZodObject)
const ShapeGetter = {
  raw(inst: $ZodObject) {
    return Object.freeze({ ...inst._zod.def.shape });
  },
};

export const $ZodObject = $constructor("$ZodObject", (inst, def) => {
  // ...
}, {
  shape: util.own(util.derived(ShapeGetter, {
    shape: (raw) => raw,
  }).shape),
});
  • defineBound(proto, key, fn): Installs a getter on proto that returns fn.bind(this) and caches the bound function directly on this via Object.defineProperty. This allows users to destructure methods (const { parse, safeParse } = UserSchema) without losing this context, while avoiding the memory cost of binding 40+ methods inside the constructor on every z.string() call.
  • derived(computes, table): Evaluates shared helper computations (such as ShapeGetter.raw, which clones and Object.freezes def.shape on first access) and memoizes the derived property on the schema instance.