20.1 Object Objects

20.1.1 The Object Constructor

The Object constructor:

  • is %Object%.
  • is the initial value of the "Object" property of the global object.
  • creates a new ordinary object when called as a constructor.
  • performs a type conversion when called as a function rather than as a constructor.
  • is designed to be subclassable. It may be used as the value of an extends clause of a class definition.

20.1.1.1 Object ( [ value ] )

When the Object function is called with optional argument value, the following steps are taken:

  1. If NewTarget is neither undefined nor the active function, then
    1. Return ? OrdinaryCreateFromConstructor(NewTarget, "%Object.prototype%").
  2. If value is undefined or null, return ! OrdinaryObjectCreate(%Object.prototype%).
  3. Return ! ToObject(value).

The "length" property of the Object function is 1𝔽.

20.1.2 Properties of the Object Constructor

The Object constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has a "length" property.
  • has the following additional properties:

20.1.2.1 Object.assign ( target, ...sources )

The assign function is used to copy the values of all of the enumerable own properties from one or more source objects to a target object. When the assign function is called, the following steps are taken:

  1. Let to be ? ToObject(target).
  2. If only one argument was passed, return to.
  3. For each element nextSource of sources, do
    1. If nextSource is neither undefined nor null, then
      1. Let from be ! ToObject(nextSource).
      2. Let keys be ? from.[[OwnPropertyKeys]]().
      3. For each element nextKey of keys, do
        1. Let desc be ? from.[[GetOwnProperty]](nextKey).
        2. If desc is not undefined and desc.[[Enumerable]] is true, then
          1. Let propValue be ? Get(from, nextKey).
          2. Perform ? Set(to, nextKey, propValue, true).
  4. Return to.

The "length" property of the assign function is 2𝔽.

20.1.2.2 Object.create ( O, Properties )

The create function creates a new object with a specified prototype. When the create function is called, the following steps are taken:

  1. If Type(O) is neither Object nor Null, throw a TypeError exception.
  2. Let obj be ! OrdinaryObjectCreate(O).
  3. If Properties is not undefined, then
    1. Return ? ObjectDefineProperties(obj, Properties).
  4. Return obj.

20.1.2.3 Object.defineProperties ( O, Properties )

The defineProperties function is used to add own properties and/or update the attributes of existing own properties of an object. When the defineProperties function is called, the following steps are taken:

  1. If Type(O) is not Object, throw a TypeError exception.
  2. Return ? ObjectDefineProperties(O, Properties).

20.1.2.3.1 ObjectDefineProperties ( O, Properties )

The abstract operation ObjectDefineProperties takes arguments O and Properties. It performs the following steps when called:

  1. Assert: Type(O) is Object.
  2. Let props be ? ToObject(Properties).
  3. Let keys be ? props.[[OwnPropertyKeys]]().
  4. Let descriptors be a new empty List.
  5. For each element nextKey of keys, do
    1. Let propDesc be ? props.[[GetOwnProperty]](nextKey).
    2. If propDesc is not undefined and propDesc.[[Enumerable]] is true, then
      1. Let descObj be ? Get(props, nextKey).
      2. Let desc be ? ToPropertyDescriptor(descObj).
      3. Append the pair (a two element List) consisting of nextKey and desc to the end of descriptors.
  6. For each element pair of descriptors, do
    1. Let P be the first element of pair.
    2. Let desc be the second element of pair.
    3. Perform ? DefinePropertyOrThrow(O, P, desc).
  7. Return O.

20.1.2.4 Object.defineProperty ( O, P, Attributes )

The defineProperty function is used to add an own property and/or update the attributes of an existing own property of an object. When the defineProperty function is called, the following steps are taken:

  1. If Type(O) is not Object, throw a TypeError exception.
  2. Let key be ? ToPropertyKey(P).
  3. Let desc be ? ToPropertyDescriptor(Attributes).
  4. Perform ? DefinePropertyOrThrow(O, key, desc).
  5. Return O.

20.1.2.5 Object.entries ( O )

When the entries function is called with argument O, the following steps are taken:

  1. Let obj be ? ToObject(O).
  2. Let nameList be ? EnumerableOwnPropertyNames(obj, key+value).
  3. Return CreateArrayFromList(nameList).

20.1.2.6 Object.freeze ( O )

When the freeze function is called, the following steps are taken:

  1. If Type(O) is not Object, return O.
  2. Let status be ? SetIntegrityLevel(O, frozen).
  3. If status is false, throw a TypeError exception.
  4. Return O.

20.1.2.7 Object.fromEntries ( iterable )

When the fromEntries method is called with argument iterable, the following steps are taken:

  1. Perform ? RequireObjectCoercible(iterable).
  2. Let obj be ! OrdinaryObjectCreate(%Object.prototype%).
  3. Assert: obj is an extensible ordinary object with no own properties.
  4. Let stepsDefine be the algorithm steps defined in CreateDataPropertyOnObject Functions.
  5. Let lengthDefine be the number of non-optional parameters of the function definition in CreateDataPropertyOnObject Functions.
  6. Let adder be ! CreateBuiltinFunction(stepsDefine, lengthDefine, "", « »).
  7. Return ? AddEntriesFromIterable(obj, iterable, adder).
Note
The function created for adder is never directly accessible to ECMAScript code.

20.1.2.7.1 CreateDataPropertyOnObject Functions

A CreateDataPropertyOnObject function is an anonymous built-in function. When a CreateDataPropertyOnObject function is called with arguments key and value, the following steps are taken:

  1. Let O be the this value.
  2. Assert: Type(O) is Object.
  3. Assert: O is an extensible ordinary object.
  4. Let propertyKey be ? ToPropertyKey(key).
  5. Perform ! CreateDataPropertyOrThrow(O, propertyKey, value).
  6. Return undefined.

20.1.2.8 Object.getOwnPropertyDescriptor ( O, P )

When the getOwnPropertyDescriptor function is called, the following steps are taken:

  1. Let obj be ? ToObject(O).
  2. Let key be ? ToPropertyKey(P).
  3. Let desc be ? obj.[[GetOwnProperty]](key).
  4. Return FromPropertyDescriptor(desc).

20.1.2.9 Object.getOwnPropertyDescriptors ( O )

When the getOwnPropertyDescriptors function is called, the following steps are taken:

  1. Let obj be ? ToObject(O).
  2. Let ownKeys be ? obj.[[OwnPropertyKeys]]().
  3. Let descriptors be ! OrdinaryObjectCreate(%Object.prototype%).
  4. For each element key of ownKeys, do
    1. Let desc be ? obj.[[GetOwnProperty]](key).
    2. Let descriptor be ! FromPropertyDescriptor(desc).
    3. If descriptor is not undefined, perform ! CreateDataPropertyOrThrow(descriptors, key, descriptor).
  5. Return descriptors.

20.1.2.10 Object.getOwnPropertyNames ( O )

When the getOwnPropertyNames function is called, the following steps are taken:

  1. Return ? GetOwnPropertyKeys(O, string).

20.1.2.11 Object.getOwnPropertySymbols ( O )

When the getOwnPropertySymbols function is called with argument O, the following steps are taken:

  1. Return ? GetOwnPropertyKeys(O, symbol).

20.1.2.11.1 GetOwnPropertyKeys ( O, type )

The abstract operation GetOwnPropertyKeys takes arguments O and type (either string or symbol). It performs the following steps when called:

  1. Let obj be ? ToObject(O).
  2. Let keys be ? obj.[[OwnPropertyKeys]]().
  3. Let nameList be a new empty List.
  4. For each element nextKey of keys, do
    1. If Type(nextKey) is Symbol and type is symbol or Type(nextKey) is String and type is string, then
      1. Append nextKey as the last element of nameList.
  5. Return CreateArrayFromList(nameList).

20.1.2.12 Object.getPrototypeOf ( O )

When the getPrototypeOf function is called with argument O, the following steps are taken:

  1. Let obj be ? ToObject(O).
  2. Return ? obj.[[GetPrototypeOf]]().

20.1.2.13 Object.is ( value1, value2 )

When the is function is called with arguments value1 and value2, the following steps are taken:

  1. Return SameValue(value1, value2).

20.1.2.14 Object.isExtensible ( O )

When the isExtensible function is called with argument O, the following steps are taken:

  1. If Type(O) is not Object, return false.
  2. Return ? IsExtensible(O).

20.1.2.15 Object.isFrozen ( O )

When the isFrozen function is called with argument O, the following steps are taken:

  1. If Type(O) is not Object, return true.
  2. Return ? TestIntegrityLevel(O, frozen).

20.1.2.16 Object.isSealed ( O )

When the isSealed function is called with argument O, the following steps are taken:

  1. If Type(O) is not Object, return true.
  2. Return ? TestIntegrityLevel(O, sealed).

20.1.2.17 Object.keys ( O )

When the keys function is called with argument O, the following steps are taken:

  1. Let obj be ? ToObject(O).
  2. Let nameList be ? EnumerableOwnPropertyNames(obj, key).
  3. Return CreateArrayFromList(nameList).

20.1.2.18 Object.preventExtensions ( O )

When the preventExtensions function is called, the following steps are taken:

  1. If Type(O) is not Object, return O.
  2. Let status be ? O.[[PreventExtensions]]().
  3. If status is false, throw a TypeError exception.
  4. Return O.

20.1.2.19 Object.prototype

The initial value of Object.prototype is the Object prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

20.1.2.20 Object.seal ( O )

When the seal function is called, the following steps are taken:

  1. If Type(O) is not Object, return O.
  2. Let status be ? SetIntegrityLevel(O, sealed).
  3. If status is false, throw a TypeError exception.
  4. Return O.

20.1.2.21 Object.setPrototypeOf ( O, proto )

When the setPrototypeOf function is called with arguments O and proto, the following steps are taken:

  1. Set O to ? RequireObjectCoercible(O).
  2. If Type(proto) is neither Object nor Null, throw a TypeError exception.
  3. If Type(O) is not Object, return O.
  4. Let status be ? O.[[SetPrototypeOf]](proto).
  5. If status is false, throw a TypeError exception.
  6. Return O.

20.1.2.22 Object.values ( O )

When the values function is called with argument O, the following steps are taken:

  1. Let obj be ? ToObject(O).
  2. Let nameList be ? EnumerableOwnPropertyNames(obj, value).
  3. Return CreateArrayFromList(nameList).

20.1.3 Properties of the Object Prototype Object

The Object prototype object:

  • is %Object.prototype%.
  • has an [[Extensible]] internal slot whose value is true.
  • has the internal methods defined for ordinary objects, except for the [[SetPrototypeOf]] method, which is as defined in 10.4.7.1. (Thus, it is an immutable prototype exotic object.)
  • has a [[Prototype]] internal slot whose value is null.

20.1.3.1 Object.prototype.constructor

The initial value of Object.prototype.constructor is %Object%.

20.1.3.2 Object.prototype.hasOwnProperty ( V )

When the hasOwnProperty method is called with argument V, the following steps are taken:

  1. Let P be ? ToPropertyKey(V).
  2. Let O be ? ToObject(this value).
  3. Return ? HasOwnProperty(O, P).
Note

The ordering of steps 1 and 2 is chosen to ensure that any exception that would have been thrown by step 1 in previous editions of this specification will continue to be thrown even if the this value is undefined or null.

20.1.3.3 Object.prototype.isPrototypeOf ( V )

When the isPrototypeOf method is called with argument V, the following steps are taken:

  1. If Type(V) is not Object, return false.
  2. Let O be ? ToObject(this value).
  3. Repeat,
    1. Set V to ? V.[[GetPrototypeOf]]().
    2. If V is null, return false.
    3. If SameValue(O, V) is true, return true.
Note

The ordering of steps 1 and 2 preserves the behaviour specified by previous editions of this specification for the case where V is not an object and the this value is undefined or null.

20.1.3.4 Object.prototype.propertyIsEnumerable ( V )

When the propertyIsEnumerable method is called with argument V, the following steps are taken:

  1. Let P be ? ToPropertyKey(V).
  2. Let O be ? ToObject(this value).
  3. Let desc be ? O.[[GetOwnProperty]](P).
  4. If desc is undefined, return false.
  5. Return desc.[[Enumerable]].
Note 1

This method does not consider objects in the prototype chain.

Note 2

The ordering of steps 1 and 2 is chosen to ensure that any exception that would have been thrown by step 1 in previous editions of this specification will continue to be thrown even if the this value is undefined or null.

20.1.3.5 Object.prototype.toLocaleString ( [ reserved1 [ , reserved2 ] ] )

When the toLocaleString method is called, the following steps are taken:

  1. Let O be the this value.
  2. Return ? Invoke(O, "toString").

The optional parameters to this function are not used but are intended to correspond to the parameter pattern used by ECMA-402 toLocaleString functions. Implementations that do not include ECMA-402 support must not use those parameter positions for other purposes.

Note 1

This function provides a generic toLocaleString implementation for objects that have no locale-specific toString behaviour. Array, Number, Date, and %TypedArray% provide their own locale-sensitive toLocaleString methods.

Note 2

ECMA-402 intentionally does not provide an alternative to this default implementation.

20.1.3.6 Object.prototype.toString ( )

When the toString method is called, the following steps are taken:

  1. If the this value is undefined, return "[object Undefined]".
  2. If the this value is null, return "[object Null]".
  3. Let O be ! ToObject(this value).
  4. Let isArray be ? IsArray(O).
  5. If isArray is true, let builtinTag be "Array".
  6. Else if O has a [[ParameterMap]] internal slot, let builtinTag be "Arguments".
  7. Else if O has a [[Call]] internal method, let builtinTag be "Function".
  8. Else if O has an [[ErrorData]] internal slot, let builtinTag be "Error".
  9. Else if O has a [[BooleanData]] internal slot, let builtinTag be "Boolean".
  10. Else if O has a [[NumberData]] internal slot, let builtinTag be "Number".
  11. Else if O has a [[StringData]] internal slot, let builtinTag be "String".
  12. Else if O has a [[DateValue]] internal slot, let builtinTag be "Date".
  13. Else if O has a [[RegExpMatcher]] internal slot, let builtinTag be "RegExp".
  14. Else, let builtinTag be "Object".
  15. Let tag be ? Get(O, @@toStringTag).
  16. If Type(tag) is not String, set tag to builtinTag.
  17. Return the string-concatenation of "[object ", tag, and "]".
Note

Historically, this function was occasionally used to access the String value of the [[Class]] internal slot that was used in previous editions of this specification as a nominal type tag for various built-in objects. The above definition of toString preserves compatibility for legacy code that uses toString as a test for those specific kinds of built-in objects. It does not provide a reliable type testing mechanism for other kinds of built-in or program defined objects. In addition, programs can use @@toStringTag in ways that will invalidate the reliability of such legacy type tests.

20.1.3.7 Object.prototype.valueOf ( )

When the valueOf method is called, the following steps are taken:

  1. Return ? ToObject(this value).

20.1.4 Properties of Object Instances

Object instances have no special properties beyond those inherited from the Object prototype object.