ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

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.
  • may be used as the value of an extends clause of a class definition.

20.1.1.1 Object ( [ value ] )

This function performs the following steps when called:

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

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 whose value is 1𝔽.
  • has the following additional properties:

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

This function copies the values of all of the enumerable own properties from one or more source objects to a target object.

It performs the following steps when called:

  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 this function is 2𝔽.

20.1.2.2 Object.create ( O, Properties )

This function creates a new object with a specified prototype.

It performs the following steps when called:

  1. If O is not an Object and O is not 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 )

This function adds own properties and/or updates the attributes of existing own properties of an object.

It performs the following steps when called:

  1. If O is not an 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 (an Object) and Properties (an ECMAScript language value) and returns either a normal completion containing an Object or a throw completion. It performs the following steps when called:

  1. Let props be ? ToObject(Properties).
  2. Let keys be ? props.[[OwnPropertyKeys]]().
  3. Let descriptors be a new empty List.
  4. 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 Record { [[Key]]: nextKey, [[Descriptor]]: desc } to descriptors.
  5. For each element property of descriptors, do
    1. Perform ? DefinePropertyOrThrow(O, property.[[Key]], property.[[Descriptor]]).
  6. Return O.

20.1.2.4 Object.defineProperty ( O, P, Attributes )

This function adds an own property and/or updates the attributes of an existing own property of an object.

It performs the following steps when called:

  1. If O is not an 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 )

This function performs the following steps when called:

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

20.1.2.6 Object.freeze ( O )

This function performs the following steps when called:

  1. If O is not an 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 )

This function performs the following steps when called:

  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 closure be a new Abstract Closure with parameters (key, value) that captures obj and performs the following steps when called:
    1. Let propertyKey be ? ToPropertyKey(key).
    2. Perform ! CreateDataPropertyOrThrow(obj, propertyKey, value).
    3. Return undefined.
  5. Let adder be CreateBuiltinFunction(closure, 2, "", « »).
  6. Return ? AddEntriesFromIterable(obj, iterable, adder).
 Note
The function created for adder is never directly accessible to ECMAScript code.

20.1.2.8 Object.getOwnPropertyDescriptor ( O, P )

This function performs the following steps when called:

  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 )

This function performs the following steps when called:

  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 )

This function performs the following steps when called:

  1. Return CreateArrayFromList(? GetOwnPropertyKeys(O, string)).

20.1.2.11 Object.getOwnPropertySymbols ( O )

This function performs the following steps when called:

  1. Return CreateArrayFromList(? GetOwnPropertyKeys(O, symbol)).

20.1.2.11.1 GetOwnPropertyKeys ( O, type )

The abstract operation GetOwnPropertyKeys takes arguments O (an ECMAScript language value) and type (string or symbol) and returns either a normal completion containing a List of property keys or a throw completion. 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 nextKey is a Symbol and type is symbol, or if nextKey is a String and type is string, then
      1. Append nextKey to nameList.
  5. Return nameList.

20.1.2.12 Object.getPrototypeOf ( O )

This function performs the following steps when called:

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

20.1.2.13 Object.groupBy ( items, callbackfn )

Note

callbackfn should be a function that accepts two arguments. groupBy calls callbackfn once for each element in items, in ascending order, and constructs a new object. Each value returned by callbackfn is coerced to a property key. For each such property key, the result object has a property whose key is that property key and whose value is an array containing all the elements for which the callbackfn return value coerced to that key.

callbackfn is called with two arguments: the value of the element and the index of the element.

The return value of groupBy is an object that does not inherit from %Object.prototype%.

This function performs the following steps when called:

  1. Let groups be ? GroupBy(items, callbackfn, property).
  2. Let obj be OrdinaryObjectCreate(null).
  3. For each Record { [[Key]], [[Elements]] } g of groups, do
    1. Let elements be CreateArrayFromList(g.[[Elements]]).
    2. Perform ! CreateDataPropertyOrThrow(obj, g.[[Key]], elements).
  4. Return obj.

20.1.2.14 Object.hasOwn ( O, P )

This function performs the following steps when called:

  1. Let obj be ? ToObject(O).
  2. Let key be ? ToPropertyKey(P).
  3. Return ? HasOwnProperty(obj, key).

20.1.2.15 Object.is ( value1, value2 )

This function performs the following steps when called:

  1. Return SameValue(value1, value2).

20.1.2.16 Object.isExtensible ( O )

This function performs the following steps when called:

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

20.1.2.17 Object.isFrozen ( O )

This function performs the following steps when called:

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

20.1.2.18 Object.isSealed ( O )

This function performs the following steps when called:

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

20.1.2.19 Object.keys ( O )

This function performs the following steps when called:

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

20.1.2.20 Object.preventExtensions ( O )

This function performs the following steps when called:

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

20.1.2.21 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.22 Object.seal ( O )

This function performs the following steps when called:

  1. If O is not an 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.23 Object.setPrototypeOf ( O, proto )

This function performs the following steps when called:

  1. Set O to ? RequireObjectCoercible(O).
  2. If proto is not an Object and proto is not null, throw a TypeError exception.
  3. If O is not an 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.24 Object.values ( O )

This function performs the following steps when called:

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

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 )

This method performs the following steps when called:

  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 )

This method performs the following steps when called:

  1. If V is not an 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 )

This method performs the following steps when called:

  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 ] ] )

This method performs the following steps when called:

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

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

Note 1

This method provides a generic toLocaleString implementation for objects that have no locale-sensitive 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 ( )

This method performs the following steps when called:

  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 tag is not a String, set tag to builtinTag.
  17. Return the string-concatenation of "[object ", tag, and "]".
 Note

Historically, this method 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 ( )

This method performs the following steps when called:

  1. Return ? ToObject(this value).
Normative Optional, Legacy

20.1.3.8 Object.prototype.__proto__

Object.prototype.__proto__ is an accessor property with attributes { [[Enumerable]]: false, [[Configurable]]: true }. The [[Get]] and [[Set]] attributes are defined as follows:

20.1.3.8.1 get Object.prototype.__proto__

The value of the [[Get]] attribute is a built-in function that requires no arguments. It performs the following steps when called:

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

20.1.3.8.2 set Object.prototype.__proto__

The value of the [[Set]] attribute is a built-in function that takes an argument proto. It performs the following steps when called:

  1. Let O be ? RequireObjectCoercible(this value).
  2. If proto is not an Object and proto is not null, return undefined.
  3. If O is not an Object, return undefined.
  4. Let status be ? O.[[SetPrototypeOf]](proto).
  5. If status is false, throw a TypeError exception.
  6. Return undefined.
Normative Optional, Legacy

20.1.3.9 Legacy Object.prototype Accessor Methods

20.1.3.9.1 Object.prototype.__defineGetter__ ( P, getter )

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. If IsCallable(getter) is false, throw a TypeError exception.
  3. Let desc be PropertyDescriptor { [[Get]]: getter, [[Enumerable]]: true, [[Configurable]]: true }.
  4. Let key be ? ToPropertyKey(P).
  5. Perform ? DefinePropertyOrThrow(O, key, desc).
  6. Return undefined.

20.1.3.9.2 Object.prototype.__defineSetter__ ( P, setter )

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. If IsCallable(setter) is false, throw a TypeError exception.
  3. Let desc be PropertyDescriptor { [[Set]]: setter, [[Enumerable]]: true, [[Configurable]]: true }.
  4. Let key be ? ToPropertyKey(P).
  5. Perform ? DefinePropertyOrThrow(O, key, desc).
  6. Return undefined.

20.1.3.9.3 Object.prototype.__lookupGetter__ ( P )

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let key be ? ToPropertyKey(P).
  3. Repeat,
    1. Let desc be ? O.[[GetOwnProperty]](key).
    2. If desc is not undefined, then
      1. If IsAccessorDescriptor(desc) is true, return desc.[[Get]].
      2. Return undefined.
    3. Set O to ? O.[[GetPrototypeOf]]().
    4. If O is null, return undefined.

20.1.3.9.4 Object.prototype.__lookupSetter__ ( P )

This method performs the following steps when called:

  1. Let O be ? ToObject(this value).
  2. Let key be ? ToPropertyKey(P).
  3. Repeat,
    1. Let desc be ? O.[[GetOwnProperty]](key).
    2. If desc is not undefined, then
      1. If IsAccessorDescriptor(desc) is true, return desc.[[Set]].
      2. Return undefined.
    3. Set O to ? O.[[GetPrototypeOf]]().
    4. If O is null, return undefined.

20.1.4 Properties of Object Instances

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