JavaScript Proxy and Reflect: The Complete Guide

You set user.age = -5 on a plain object and nothing stops you. No error, no warning — the object silently accepts a value that makes no sense, and the bug surfaces three files away, in whatever code trusted age to be a real number. Every framework that seems to "just know" when your state changed — Vue's reactivity, a validation library that rejects bad input at the boundary, an ORM that lazy-loads a relation the moment you touch it — is solving this exact problem with one native JavaScript feature that most tutorials skip past in a paragraph: Proxy.

By the end of this guide you'll be able to:

Who this is for: you write JavaScript or TypeScript day to day, you've used objects and classes comfortably, and you've heard of Proxy but never reached for it — or you've seen Reflect.get(target, prop, receiver) in someone else's code and wondered why they didn't just write target[prop].

Here's the naive fix for "validate this field whenever it's set" — a hand-written getter/setter pair:

This works — for age. Add email, score, and role, and you're maintaining four nearly identical getter/setter pairs, each one a place to forget the check. Miss one, and that field silently accepts garbage, exactly like the plain object at the top of this article. The validation logic is also scattered per-field instead of living in one place you can audit.

What you actually want is a way to say "run this code whenever any property is read or written on this object" — one interception point, not N hand-written pairs. That's precisely what Proxy gives you, and Reflect is the toolkit that makes writing traps correctly possible.

The mental model: a Proxy is not the object — it's a stand-in that sits in front of the real object (the target) and intercepts a fixed set of fundamental operations: reading a property, writing one, checking in, deleting, listing keys, and a few others. Each operation you intercept is called a trap. If you don't define a trap for an operation, it passes straight through to the target, unchanged — and Reflect is how you perform that same "pass it through" behavior explicitly, from inside a trap you did define.

Think of it like a customs checkpoint at a border. Most traffic (an operation with no trap) just walks through untouched. But for the operations you care about, you install an inspector (the trap function) who can log the traffic, reject it, alter it, or wave it through — and when they wave it through, they're not improvising; they're calling the same official procedure (Reflect) that would have run automatically if no inspector were there at all.

Every stage below is this one idea, applied to a different operation.

The two most common traps intercept reading and writing a property:

Now replace the User class's boilerplate with one reusable set trap and a table of rules:

Adding a validated field for email or score is now a one-line rule in the rules object, not a new getter/setter pair. The check lives in exactly one place — the set trap — no matter how many fields you validate. In TypeScript, validated is worth making generic in its own right, so the object you get back keeps the exact shape of the object you passed in — the same type-parameter-as-argument idea covered in the guide to TypeScript generics.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Stage 1's traps forwarded reads and writes with obj[prop] directly. That works for plain data, but it quietly breaks once a getter and a prototype chain are involved — and this is the exact bug Reflect exists to prevent.

obj.self should return obj — that's what a getter returning this means when you access it through obj. But the trap wrote target[prop], so the getter ran with this bound to target, not obj. The fix is to forward the operation with Reflect.get, which takes a third argument — the receiver — and passes it through as this:

Reflect isn't a Proxy-only feature — it mirrors all 13 of the fundamental object operations (get, set, has, deleteProperty, ownKeys, getPrototypeOf, setPrototypeOf, isExtensible, preventExtensions, defineProperty, getOwnPropertyDescriptor, apply, construct) as plain functions instead of operators or statements. Outside a Proxy trap, that mostly matters for two things: Reflect.ownKeys(obj) gets you every own key (strings and symbols) in one call, and Reflect.construct(Ctor, args) calls a constructor with a dynamic argument list without new Ctor(...args)'s syntax constraints.

Traps aren't limited to get/set. has intercepts the in operator, deleteProperty intercepts delete, and ownKeys intercepts Object.keys, for...in, and JSON.stringify:

That last line matters: hiding a key from enumeration (ownKeys/has) is a different guarantee from blocking direct access (get). This example only hides password from listing and serialization — anyone who already knows the key name can still read it. If you want both, add a get trap that throws or returns undefined for that key.

This is the payoff: the same mechanism that powers Vue 3's reactivity system (Vue 2 used Object.defineProperty; Vue 3's official migration guide documents the switch to Proxy), stripped to its essence — a set trap that notifies subscribers whenever a value actually changes:

No state.setCount(...) call, no manual "mark dirty" step — state.count++ is ordinary JavaScript, and the set trap is where the framework hooks in to schedule a re-render. This is also why reactive frameworks generally avoid diffing entire objects on every render: the proxy already knows exactly which property changed, the moment it changes.

Reach for a Proxy when the behavior is cross-cutting — it applies to every property, not one: validation layers, reactive state, logging/instrumentation, lazy-loading a relation the first time it's touched, or sandboxing a reference you may need to revoke later.

Don't reach for a Proxy when a single field needs a single check — a plain getter/setter pair on a class is clearer and faster for that one case. Reserve Proxy for when you'd otherwise be copy-pasting the same trap logic across several fields.

Don't reach for a Proxy to copy or clone data. A Proxy intercepts operations on the original object — it is not a copy. If what you actually need is an independent snapshot of an object's current data, that's structuredClone, not a Proxy — the two solve opposite problems and are easy to reach for interchangeably by mistake.

Don't proxy built-ins directly. As the gotchas above show, Map, Set, Date, and similar built-ins carry internal slots a Proxy can't forward. Wrap the specific methods you need instead of proxying the instance.

Object.defineProperty configures one property on one object at a time — you call it once per field you want to intercept. A Proxy wraps the entire object with a single set of traps that apply to every property, including ones added later, which is why Vue 3 moved from the former to the latter.

No — they're complementary, not alternatives. Proxy is how you intercept an operation; Reflect is how you correctly perform that operation's default behavior (including forwarding the receiver) from inside the trap you wrote.

Yes. Array index access, length, and methods like push all go through the same get/set traps (array indices are just string-keyed properties under the hood). A set trap on an array proxy fires once per element write, including the implicit length update that array mutation methods perform.

Not directly — see the gotchas section above. Calling a Map/Set method on a Proxy wrapping one throws a TypeError, because those methods require an internal slot only real Map/Set instances have.

typeof proxy matches typeof target (both "object", or "function" if the target is callable and you defined apply/construct traps), and instanceof checks pass through correctly. But proxy !== target — they are not the same reference, which matters for equality checks and collection membership.

Yes, and it respects your traps: JSON.stringify reads properties through ownKeys, getOwnPropertyDescriptor, and get, in that order, so a proxy that hides or transforms properties in those traps produces correspondingly different JSON — exactly as shown in Stage 4.

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

That silent -5 from the top of this article never had a chance to happen in Stage 2 — one set trap rejected it before it ever reached the object. You now have the mechanism behind it: a checkpoint in front of the object, Reflect to forward what you don't intercept, and enough of the gotchas to avoid the ones that catch people in production. Where's the first validation class or manual "notify on change" pattern in your own code that a five-line Proxy could replace? Tell me in the comments.

Thanks for reading! Let's stay connected: