Suggest an edit

Improve this article

Refine the answer for “Reflect.defineProperty()”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`Reflect.defineProperty()` defines (adds or changes) an object property with a given descriptor and returns a boolean value telling you whether it succeeded.** It is the modern counterpart of `Object.defineProperty()`, but with more predictable and safer behaviour: here a failure is an ordinary result rather than an exception.

## Theory

### TL;DR

- Syntax: `Reflect.defineProperty(target, propertyKey, descriptor)`.
- Returns `true` on success and `false` on failure, not the object itself.
- It does not throw on failure, so no `try/catch` is needed.
- It accepts both a data descriptor (`value`, `writable`) and an accessor descriptor (`get`, `set`).
- Keys can be a string or a `Symbol`.
- Main uses: safe checks, metaprogramming and `Proxy` traps.

### Quick example

```javascript
const user = {};

const result = Reflect.defineProperty(user, 'name', {
  value: 'Maria',
  writable: true,
  enumerable: true,
  configurable: true
});

console.log(result);     // true
console.log(user.name);  // "Maria"
```

This is the same as `Object.defineProperty(user, 'name', { ... })`, with one important difference: `Reflect` does not throw an error, it simply returns `false`.

### Signature and arguments

```javascript
Reflect.defineProperty(target, propertyKey, descriptor)
```

| Argument | Description |
| --- | --- |
| `target` | The object on which the property is defined |
| `propertyKey` | The property name (a string or a `Symbol`) |
| `descriptor` | The descriptor, an object with flags (`value`, `writable`, `enumerable`, `configurable`, `get`, `set`) |

What it returns:

- `true` if the property was defined successfully;
- `false` if the operation failed (for example, the object is protected by `Object.freeze()` or the property is non-configurable).

### Difference from Object.defineProperty()

| Behaviour | `Object.defineProperty()` | `Reflect.defineProperty()` |
| --- | --- | --- |
| Returns | the object itself | `true` / `false` |
| On failure | throws an exception | returns `false` |
| Suited to | ordinary code | safe, "reflective" operations |

"Reflective" means working with the internal properties of objects without throwing errors.

A safe check in practice:

```javascript
const frozen = Object.freeze({});

try {
  Object.defineProperty(frozen, 'x', { value: 1 });
} catch (e) {
  console.log('Error:', e.message);
}

console.log(Reflect.defineProperty(frozen, 'x', { value: 1 })); // false, no exception
```

`Reflect.defineProperty()` simply returns `false` instead of throwing.

### Descriptors: data and accessor

The method works identically for data and accessor descriptors:

```javascript
const person = {};

Reflect.defineProperty(person, 'fullName', {
  get() {
    return 'Maria Koval';
  },
  enumerable: true
});

console.log(person.fullName); // "Maria Koval"
```

Here the property is described by a getter rather than a value, and `Reflect.defineProperty()` accepts such a descriptor without any caveats.

### Defining properties dynamically and conditionally

The method is convenient inside a loop, when the set of keys is only known at run time:

```javascript
const obj = {};

['name', 'age', 'city'].forEach(key => {
  Reflect.defineProperty(obj, key, {
    value: key.toUpperCase(),
    enumerable: true
  });
});

console.log(obj);
// { name: 'NAME', age: 'AGE', city: 'CITY' }
```

The return value is useful directly inside a condition:

```javascript
if (Reflect.defineProperty(user, 'role', { value: 'admin' })) {
  console.log('Property added successfully');
} else {
  console.log('Failed to add property');
}
```

This is handy precisely because it requires no `try/catch`: the result is checked like any other boolean expression.

### Working with Proxy

Inside a `Proxy` `defineProperty` trap, `Reflect.defineProperty` is used to delegate the default behaviour:

```javascript
const target = {};

proxy.x = 10; // under the hood this calls Reflect.defineProperty automatically
```

In a `Proxy`, the reflective methods (`Reflect.*`) make it easy to implement behaviour as naturally as possible: the trap signature matches the signature of the matching `Reflect` method, and the boolean result is exactly what the trap is supposed to return.

Summary table:

| Question | Answer |
| --- | --- |
| What it does | Defines (creates or changes) an object property with the given descriptor |
| What it returns | `true` on success, `false` on failure |
| Does it throw | No |
| Does it use a descriptor | Yes (`value`, `writable`, `configurable`, `enumerable`, `get`, `set`) |
| Where it is used | Safe operations, `Proxy`, metaprogramming |

### Common mistakes

- **Expecting the method to return an object.** `Object.defineProperty()` returns the object and therefore chains, while `Reflect.defineProperty()` returns `true` / `false`. Writing `Reflect.defineProperty(obj, 'a', d).b` will break.
- **Ignoring the return value.** Since there is no exception, a silent failure goes unnoticed. If the result matters, check it.
- **Wrapping the call in `try/catch` "just in case".** For a failed property definition that is pointless: the whole point of `Reflect` is to avoid the exception. An exception is only possible for invalid arguments, for example when `target` is not an object.
- **Forgetting that the flags default to `false`.** The descriptor `{ value: 1 }` creates a property that is not `writable`, `enumerable` or `configurable`, so it will not show up in `Object.keys()` and will not change on assignment.
- **Confusing it with `Reflect.getOwnPropertyDescriptor()`.** The first sets a descriptor, the second reads one.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts836 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.