handler.defineProperty(target, property, descriptor) is a trap that runs when a property is defined on a Proxy. This happens with Object.defineProperty() and Reflect.defineProperty(), and also when you add or change a property with =, if the handler has no set trap.
Inside the trap you can log the change, block it, or change the descriptor. The trap returns true when the property was defined and false when it was not. To define the property in the normal way, use Reflect.defineProperty(target, property, descriptor).
Remember
const handler = {
defineProperty(target, property, descriptor) { ... }
};
target → the original object
property → the name (a string or a symbol)
descriptor → { value, writable, enumerable, configurable }
return true → the property was defined
return false → refused (Object.defineProperty then throws)
Syntax
Add a defineProperty trap to the handler of a Proxy.
// ECMAScript 2015 (ES6)
handler.defineProperty(target, property, descriptor)
// target : the original object
// property : a string or a symbol
// descriptor : an object with the fields that were given
// returns : true or false
Parameters
Parameter
Description
target
The original object that the Proxy wraps.
property
The name of the property that is being defined: a string or a symbol.
descriptor
An object that describes the property. It only holds the fields that were given, for example { value: 7 }. An assignment like proxy.a = 1 gives value, writable, enumerable and configurable for a new property.
Return Value
Return Value
Description
true
The property was defined.
false
The change is refused. Reflect.defineProperty() returns false, Object.defineProperty() throws a TypeError, and a plain = is ignored (or throws in strict mode).
TypeError (thrown)
The trap broke a rule, for example by returning true for a property that the target cannot really have.
JavaScript Examples
Example 1 — Log Every Defined Property
Record each property that is defined, with the descriptor that came with it. Notice that a plain assignment gives a full descriptor.
id {"value":7}
name {"value":"Ann","writable":true,"enumerable":true,"configurable":true}
id: 7, name: Ann
How It Works
Only given fields.Object.defineProperty(proxy, "id", { value: 7 }) gives the trap just { value: 7 }. The trap writes it to the log and forwards it with Reflect.defineProperty().
Assignment too.proxy.name = "Ann" has no set trap, so JavaScript defines a new property, with all four fields set to their normal values.
Values are stored. Because the trap forwarded each call to the target, reading id and name works as usual.
Example 2 — Allow Only Some Properties
Return false to refuse a property. See how each way of adding a property reacts. The catch blocks print the error type only.
Keys: name
Reflect: false
Object.defineProperty: TypeError
Strict assignment: TypeError
How It Works
A list of allowed names. The trap returns false for any name that is not in allowed. name is stored and email is not, so only name is a key.
The refusal is quiet for =. In normal code, user.email = ... is just ignored. Reflect.defineProperty() shows the refusal as false.
Louder in other places.Object.defineProperty() and an assignment in strict mode both turn the false into a TypeError.
Example 3 — Change the Descriptor and Respect the Rules
The trap can change the descriptor on its way to the target. Here, every property becomes read-only. A trap that lies about a locked target throws a TypeError.
color: red
{"value":"red","writable":false,"enumerable":true,"configurable":true}
Lying trap: TypeError
How It Works
Edit the descriptor.Object.assign({}, descriptor, { writable: false }) makes a copy with writable switched off, and the trap defines that copy.
Second write is ignored. The property is now read-only, so color = "blue" does nothing and the value stays "red". The descriptor shows writable: false.
Rules still apply. The target locked cannot get new properties. A trap that says true anyway is caught by JavaScript, which throws a TypeError.
Compatibility
Browser & Runtime Support
handler.defineProperty() is part of ES2015 (ES6), together with the Proxy object and the Reflect object. Every current browser and Node.js has it.
✓ ES2015 · Widely supported
handler.defineProperty()
Supported in Chrome 49+, Edge 12+, Firefox 49+, Safari 10+, Opera 36+ and Node.js 6+. Internet Explorer never got it.
ES2015Standard since
Google Chrome49+ · Desktop & Mobile
Full support
Microsoft Edge12+ · Chromium and legacy
Full support
Mozilla Firefox49+ · Desktop & Mobile
Full support
Apple Safari10+ · macOS & iOS
Full support
Opera36+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView49+ · Chromium based
Supported
Node.js6+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
handler.defineProperty()Excellent
Bottom line: Safe to use in every current browser and in Node.js. A Proxy cannot be faked in old browsers, so do not use it where Internet Explorer must work.
Frequently Asked Questions
It is a method of the handler object that runs when a property is defined on a Proxy, for example with Object.defineProperty(), Reflect.defineProperty() or an assignment. It receives the target, the property name and the descriptor.
If the handler has no set trap, an assignment to a Proxy ends up defining the property on the Proxy itself, and that calls the defineProperty trap. If you add a set trap, that trap runs first, and it decides what happens next.
The change is refused. Reflect.defineProperty() returns false, Object.defineProperty() throws a TypeError, and an assignment is ignored in normal code but throws a TypeError in strict mode.
Only the fields that were given. Object.defineProperty(proxy, "id", { value: 7 }) gives { value: 7 }. A plain assignment of a new property gives all four fields: value, writable, enumerable and configurable.
The set trap handles reading and writing values with =. The defineProperty trap handles the more detailed task of defining a property with its flags. Use set for simple validation, and defineProperty to control the descriptors.