JavaScript Proxy handler.getOwnPropertyDescriptor() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
Proxy trap

Definition

handler.getOwnPropertyDescriptor(target, property) is a trap that runs when JavaScript asks a Proxy for the descriptor of one of its own properties. A descriptor is a small object that says what a property is: its value and whether it is writable, enumerable and configurable.

It runs for Object.getOwnPropertyDescriptor() and Reflect.getOwnPropertyDescriptor(), but also behind the scenes for hasOwnProperty(), Object.keys(), JSON.stringify() and the spread syntax. The trap returns a descriptor object, or undefined to say that the property does not exist.

Remember
const handler = {
  getOwnPropertyDescriptor(target, property) { ... }
};

target    → the original object
property  → the name (a string or a symbol)

return an object  → the property exists, with this descriptor
return undefined  → the property does not exist

Syntax

Add a getOwnPropertyDescriptor trap to the handler of a Proxy.

JavaScript
const user = { name: "Ann", _id: 7 };

const view = new Proxy(user, {
  getOwnPropertyDescriptor(target, key) {
    if (key === "_id") {
      return undefined;   // hide _id
    }
    return Reflect.getOwnPropertyDescriptor(target, key);
  }
});

console.log(Object.keys(view).join(", "));   // name
CallWhat it does
Object.getOwnPropertyDescriptor(proxy, "a")Asks directly for a descriptor. Runs the trap.
proxy.hasOwnProperty("a")Checks if the property is an own property. Runs the trap.
Object.keys(proxy), JSON.stringify(proxy)Both ask for each key's descriptor to see if it is enumerable. They run the trap.
{ ...proxy }, Object.assign({}, proxy)Copying properties also runs the trap.

A standard JavaScript Proxy trap (ES2015). You write it inside the handler object that you pass to new Proxy(). JavaScript calls it for you. No import required. Siblings: Proxy.revocable(), handler.apply(), handler.construct(), handler.defineProperty(), handler.deleteProperty(), handler.get(), handler.getPrototypeOf(), handler.has(), handler.isExtensible(), handler.ownKeys(), handler.preventExtensions(), handler.set(), handler.setPrototypeOf().

Library declarations
JavaScript
// ECMAScript 2015 (ES6)
handler.getOwnPropertyDescriptor(target, property)

// target   : the original object
// property : a string or a symbol
// returns  : a descriptor object, or undefined

Parameters

ParameterDescription
targetThe original object that the Proxy wraps.
propertyThe name of the property whose descriptor is wanted: a string or a symbol.

Return Value

Return ValueDescription
ObjectA descriptor such as { value: 1, writable: true, enumerable: true, configurable: true }. The property counts as existing.
undefinedThe property counts as not existing.
TypeError (thrown)The trap returned something else, or broke a rule about what the target really has.

JavaScript Examples

Example 1 — Hide Properties from Keys and JSON

Return undefined for names that start with an underscore. They then disappear from hasOwnProperty(), Object.keys() and JSON.stringify().

JavaScript
const user = { name: "Ann", _secret: "xyz" };

const view = new Proxy(user, {
  getOwnPropertyDescriptor(target, key) {
    if (typeof key === "string" && key.startsWith("_")) {
      return undefined;
    }
    return Reflect.getOwnPropertyDescriptor(target, key);
  }
});

console.log("Has name: " + view.hasOwnProperty("name"));
console.log("Has _secret: " + view.hasOwnProperty("_secret"));
console.log("Keys: " + Object.keys(view).join(", "));
console.log("JSON: " + JSON.stringify(view));
console.log("Still readable: " + view._secret);
Try It Yourself

How It Works

  1. Hide by name. For names that start with "_", the trap returns undefined, which means "no such own property".
  2. Lists skip it. Object.keys() and JSON.stringify() ask for each descriptor first, so _secret never makes it into the key list or the JSON text.
  3. Reading is separate. The trap only changes the descriptor. view._secret is a read, so it still returns the value. Add a get trap to block it too.

Example 2 — Report a Different Descriptor

The trap can change what the descriptor says. Here every property is reported as read-only, while the real property is unchanged.

JavaScript
const data = { a: 1 };

const readOnlyView = new Proxy(data, {
  getOwnPropertyDescriptor(target, key) {
    const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
    if (descriptor) {
      descriptor.writable = false;
    }
    return descriptor;
  }
});

console.log("Through proxy: " + JSON.stringify(Object.getOwnPropertyDescriptor(readOnlyView, "a")));
console.log("Real object: " + JSON.stringify(Object.getOwnPropertyDescriptor(data, "a")));
console.log("Missing property: " + Object.getOwnPropertyDescriptor(readOnlyView, "z"));
Try It Yourself

How It Works

  1. Get the real descriptor. Reflect.getOwnPropertyDescriptor() returns a new descriptor object, so the trap can edit it safely.
  2. Change one field. The trap sets writable to false before returning it. This is allowed because the real property is configurable.
  3. Missing stays missing. For z, the real answer is undefined, and the trap passes it on unchanged.

Example 3 — A Virtual Property and the Rules

The trap can say that a property exists even when the target does not have it. Then see that it cannot hide a frozen property. The catch block prints the error type only.

JavaScript
const virtual = new Proxy({}, {
  getOwnPropertyDescriptor(target, key) {
    if (key === "id") {
      return { value: 99, writable: true, enumerable: true, configurable: true };
    }
    return undefined;
  }
});

console.log("Has own id: " + virtual.hasOwnProperty("id"));
console.log("Descriptor value: " + Object.getOwnPropertyDescriptor(virtual, "id").value);
console.log("Direct read: " + virtual.id);
console.log("Keys: " + Object.keys(virtual).length);

const frozen = Object.freeze({ x: 1 });
const liar = new Proxy(frozen, {
  getOwnPropertyDescriptor() {
    return undefined;
  }
});

try {
  Object.getOwnPropertyDescriptor(liar, "x");
} catch (err) {
  console.log("Hiding a frozen property: " + err.name);
}
Try It Yourself

How It Works

  1. A made-up descriptor. For id, the trap returns a full descriptor, so hasOwnProperty("id") says true and the descriptor value is 99. The target stays empty.
  2. Other traps are separate. A direct read uses the get trap, which does not exist here, so virtual.id is undefined. Object.keys() takes its names from the ownKeys trap, so the list is empty.
  3. No lying about frozen. x is non-configurable. Saying it does not exist is caught by JavaScript, which throws a TypeError.

Browser & Runtime Support

handler.getOwnPropertyDescriptor() 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.getOwnPropertyDescriptor()

Supported in Chrome 49+, Edge 12+, Firefox 49+, Safari 10+, Opera 36+ and Node.js 6+. Internet Explorer never got it.

ES2015 Standard since
Google Chrome 49+ · Desktop & Mobile
Full support
Microsoft Edge 12+ · Chromium and legacy
Full support
Mozilla Firefox 49+ · Desktop & Mobile
Full support
Apple Safari 10+ · macOS & iOS
Full support
Opera 36+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 49+ · Chromium based
Supported
Node.js 6+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No native support
Not supported
handler.getOwnPropertyDescriptor() 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 JavaScript asks a Proxy for the descriptor of an own property. It returns a descriptor object, or undefined if the property should count as missing.
Object.getOwnPropertyDescriptor() and Reflect.getOwnPropertyDescriptor() directly, and also hasOwnProperty(), Object.keys(), Object.entries(), JSON.stringify(), the spread syntax and Object.assign(), which ask for descriptors internally.
Return undefined from this trap for that property. Object.keys() asks for the descriptor of each key to see if it is enumerable, so it skips the ones that do not exist. You can also use the ownKeys trap to remove the key from the list.
No. Reading a value uses the get trap. This trap only answers questions about the property itself, such as whether it exists and whether it is writable or enumerable.
Most likely it returned something that is not an object or undefined, or it broke a rule. For example, it cannot report a non-configurable property of the target as missing, and it cannot add new properties to a target that is not extensible.

Next: handler.getPrototypeOf()

Learn how a Proxy can change what looks like the prototype with the getPrototypeOf trap.

handler.getPrototypeOf() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

7 people found this page helpful