9.9 API: property descriptors

The following tool methods use property descriptors:

  • Object.defineProperty(obj: object, key: string|symbol, propDesc: PropertyDescriptor): object [ES5]

    Creates or changes a property on obj whose key is key and whose attributes are specified via propDesc. Returns the modified object.

    1. const obj = {};
    2. const result = Object.defineProperty(
    3.   obj, 'happy', {
    4.     value: 'yes',
    5.     writable: true,
    6.     enumerable: true,
    7.     configurable: true,
    8.   });
    10. // obj was returned and modified:
    11. assert.equal(result, obj);
    12. assert.deepEqual(obj, {
    13.   happy: 'yes',
    14. });

  • Object.defineProperties(obj: object, properties: {[k: string|symbol]: PropertyDescriptor}): object [ES5]

    The batch version of Object.defineProperty(). Each property p of the object properties specifies one property that is to be added to obj: The key of p specifies the key of the property, the value of p is a descriptor that specifies the attributes of the property.

    1. const address1 = Object.defineProperties({}, {
    2.   street: { value: 'Evergreen Terrace', enumerable: true },
    3.   number: { value: 742, enumerable: true },
    4. });

  • Object.create(proto: null|object, properties?: {[k: string|symbol]: PropertyDescriptor}): object [ES5]

    First, creates an object whose prototype is proto. Then, if the optional parameter properties has been provided, adds properties to it – in the same manner as Object.defineProperties(). Finally, returns the result. For example, the following code snippet produces the same result as the previous snippet:

    1. const address2 = Object.create(Object.prototype, {
    2.   street: { value: 'Evergreen Terrace', enumerable: true },
    3.   number: { value: 742, enumerable: true },
    4. });
    5. assert.deepEqual(address1, address2);

  • Object.getOwnPropertyDescriptor(obj: object, key: string|symbol): undefined|PropertyDescriptor [ES5]

    Returns the descriptor of the own (non-inherited) property of obj whose key is key. If there is no such property, undefined is returned.

    1. assert.deepEqual(
    2.   Object.getOwnPropertyDescriptor(Object.prototype, 'toString'),
    3.   {
    4.     value: {}.toString,
    5.     writable: true,
    6.     enumerable: false,
    7.     configurable: true,
    8.   });
    9. assert.equal(
    10.   Object.getOwnPropertyDescriptor({}, 'toString'),
    11.   undefined);

  • Object.getOwnPropertyDescriptors(obj: object): {[k: string|symbol]: PropertyDescriptor} [ES2017]

    Returns an object where each property key 'k' of obj is mapped to the property descriptor for obj.k. The result can be used as input for Object.defineProperties() and Object.create().

    ``` const propertyKey = Symbol(‘propertyKey’); const obj = {

  1.   [propertyKey]: 'abc',
  2.   get count() { return 123 },
  3. };
  5. const desc = Object.getOwnPropertyDescriptor.bind(Object);
  6. assert.deepEqual(
  7.   Object.getOwnPropertyDescriptors(obj),
  8.   {
  9.     [propertyKey]: {
  10.       value: 'abc',
  11.       writable: true,
  12.       enumerable: true,
  13.       configurable: true
  14.     },
  15.     count: {
  16.       get: desc(obj, 'count').get, // (A)
  17.       set: undefined,
  18.       enumerable: true,
  19.       configurable: true
  20.     }
  21.   });
  22. ```
  24. Using `desc()` in line A is a work-around so that `.deepEqual()` works.