Multipage preference

20 Fundamental Objects

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 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 targetObj be ? ToObject(target).
  2. If only one argument was passed, return targetObj.
  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 propertyDesc be ? from.[[GetOwnProperty]](nextKey).
        2. If propertyDesc is not undefined and propertyDesc.[[Enumerable]] is true, then
          1. Let propertyValue be ? Get(from, nextKey).
          2. Perform ? Set(targetObj, nextKey, propertyValue, true).
  4. Return targetObj.

The "length" property of this function is 2𝔽.

20.1.2.2 Object.create ( proto, properties )

This function creates a new object with a specified prototype.

It performs the following steps when called:

  1. If proto is not an Object and proto is not null, throw a TypeError exception.
  2. Let obj be OrdinaryObjectCreate(proto).
  3. If properties is not undefined, then
    1. Return ? ObjectDefineProperties(obj, properties).
  4. Return obj.

20.1.2.3 Object.defineProperties ( obj, 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 obj is not an Object, throw a TypeError exception.
  2. Return ? ObjectDefineProperties(obj, properties).

20.1.2.3.1 ObjectDefineProperties ( obj, properties )

The abstract operation ObjectDefineProperties takes arguments obj (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. Set properties to ? ToObject(properties).
  2. Let keys be ? properties.[[OwnPropertyKeys]]().
  3. Let propertyDescs be a new empty List.
  4. For each element nextKey of keys, do
    1. Let currentPropertyDesc be ? properties.[[GetOwnProperty]](nextKey).
    2. If currentPropertyDesc is not undefined and currentPropertyDesc.[[Enumerable]] is true, then
      1. Let propertyDescObj be ? Get(properties, nextKey).
      2. Let propertyDesc be ? ToPropertyDescriptor(propertyDescObj).
      3. Append the Record { [[Key]]: nextKey, [[Descriptor]]: propertyDesc } to propertyDescs.
  5. For each element property of propertyDescs, do
    1. Perform ? DefinePropertyOrThrow(obj, property.[[Key]], property.[[Descriptor]]).
  6. Return obj.

20.1.2.4 Object.defineProperty ( obj, key, attrs )

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 obj is not an Object, throw a TypeError exception.
  2. Let propertyKey be ? ToPropertyKey(key).
  3. Let propertyDesc be ? ToPropertyDescriptor(attrs).
  4. Perform ? DefinePropertyOrThrow(obj, propertyKey, propertyDesc).
  5. Return obj.

20.1.2.5 Object.entries ( obj )

This function performs the following steps when called:

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

20.1.2.6 Object.freeze ( obj )

This function performs the following steps when called:

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

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 NormalCompletion(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 ( obj, key )

This function performs the following steps when called:

  1. Let coerced be ? ToObject(obj).
  2. Let propertyKey be ? ToPropertyKey(key).
  3. Let propertyDesc be ? coerced.[[GetOwnProperty]](propertyKey).
  4. Return FromPropertyDescriptor(propertyDesc).

20.1.2.9 Object.getOwnPropertyDescriptors ( obj )

This function performs the following steps when called:

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

20.1.2.10 Object.getOwnPropertyNames ( obj )

This function performs the following steps when called:

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

20.1.2.11 Object.getOwnPropertySymbols ( obj )

This function performs the following steps when called:

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

20.1.2.11.1 GetOwnPropertyKeys ( value, type )

The abstract operation GetOwnPropertyKeys takes arguments value (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(value).
  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 ( obj )

This function performs the following steps when called:

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

20.1.2.13 Object.groupBy ( items, callback )

Note

callback should be a function that accepts two arguments. groupBy calls callback once for each element in items, in ascending order, and constructs a new object. Each value returned by callback 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 callback return value coerced to that key.

callback 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, callback, property).
  2. Let obj be OrdinaryObjectCreate(null).
  3. For each Record { [[Key]], [[Elements]] } group of groups, do
    1. Let elements be CreateArrayFromList(group.[[Elements]]).
    2. Perform ! CreateDataPropertyOrThrow(obj, group.[[Key]], elements).
  4. Return obj.

20.1.2.14 Object.hasOwn ( obj, key )

This function performs the following steps when called:

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

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 ( obj )

This function performs the following steps when called:

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

20.1.2.17 Object.isFrozen ( obj )

This function performs the following steps when called:

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

20.1.2.18 Object.isSealed ( obj )

This function performs the following steps when called:

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

20.1.2.19 Object.keys ( obj )

This function performs the following steps when called:

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

20.1.2.20 Object.preventExtensions ( obj )

This function performs the following steps when called:

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

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 ( obj )

This function performs the following steps when called:

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

20.1.2.23 Object.setPrototypeOf ( obj, proto )

This function performs the following steps when called:

  1. Perform ? RequireObjectCoercible(obj).
  2. If proto is not an Object and proto is not null, throw a TypeError exception.
  3. If obj is not an Object, return obj.
  4. Let status be ? obj.[[SetPrototypeOf]](proto).
  5. If status is false, throw a TypeError exception.
  6. Return obj.

20.1.2.24 Object.values ( obj )

This function performs the following steps when called:

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

20.1.3 Properties of the Object Prototype Object

The Object prototype object:

20.1.3.1 Object.prototype.constructor

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

20.1.3.2 Object.prototype.hasOwnProperty ( value )

This method performs the following steps when called:

  1. Let propertyKey be ? ToPropertyKey(value).
  2. Let obj be ? ToObject(this value).
  3. Return ? HasOwnProperty(obj, propertyKey).
 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 ( value )

This method performs the following steps when called:

  1. If value is not an Object, return false.
  2. Let obj be ? ToObject(this value).
  3. Repeat,
    1. Set value to ? value.[[GetPrototypeOf]]().
    2. If value is null, return false.
    3. If SameValue(obj, value) 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 value is not an object and the this value is undefined or null.

20.1.3.4 Object.prototype.propertyIsEnumerable ( value )

This method performs the following steps when called:

  1. Let propertyKey be ? ToPropertyKey(value).
  2. Let obj be ? ToObject(this value).
  3. Let propertyDesc be ? obj.[[GetOwnProperty]](propertyKey).
  4. If propertyDesc is undefined, return false.
  5. Return propertyDesc.[[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 thisValue be the this value.
  2. Return ? Invoke(thisValue, "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 obj be ! ToObject(this value).
  4. Let isArray be ? IsArray(obj).
  5. If isArray is true, let builtinTag be "Array".
  6. Else if obj has a [[ParameterMap]] internal slot, let builtinTag be "Arguments".
  7. Else if obj has a [[Call]] internal method, let builtinTag be "Function".
  8. Else if obj has an [[ErrorData]] internal slot, let builtinTag be "Error".
  9. Else if obj has a [[BooleanData]] internal slot, let builtinTag be "Boolean".
  10. Else if obj has a [[NumberData]] internal slot, let builtinTag be "Number".
  11. Else if obj has a [[StringData]] internal slot, let builtinTag be "String".
  12. Else if obj has a [[DateValue]] internal slot, let builtinTag be "Date".
  13. Else if obj has a [[RegExpMatcher]] internal slot, let builtinTag be "RegExp".
  14. Else, let builtinTag be "Object".
  15. Let tag be ? Get(obj, %Symbol.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 %Symbol.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 [[Getter]] and [[Setter]] attributes are defined as follows:

20.1.3.8.1 get Object.prototype.__proto__

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

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

20.1.3.8.2 set Object.prototype.__proto__

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

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

20.1.3.9 Legacy Object.prototype Accessor Methods

20.1.3.9.1 Object.prototype.__defineGetter__ ( key, getter )

This method performs the following steps when called:

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

20.1.3.9.2 Object.prototype.__defineSetter__ ( key, setter )

This method performs the following steps when called:

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

20.1.3.9.3 Object.prototype.__lookupGetter__ ( key )

This method performs the following steps when called:

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

20.1.3.9.4 Object.prototype.__lookupSetter__ ( key )

This method performs the following steps when called:

  1. Let obj be ? ToObject(this value).
  2. Let propertyKey be ? ToPropertyKey(key).
  3. Repeat,
    1. Let propertyDesc be ? obj.[[GetOwnProperty]](propertyKey).
    2. If propertyDesc is not undefined, then
      1. If IsAccessorDescriptor(propertyDesc) is true, return propertyDesc.[[Setter]].
      2. Return undefined.
    3. Set obj to ? obj.[[GetPrototypeOf]]().
    4. If obj 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.

20.2 Function Objects

20.2.1 The Function Constructor

The Function constructor:

  • is %Function%.
  • is the initial value of the "Function" property of the global object.
  • creates and initializes a new function object when called as a function rather than as a constructor. Thus the function call Function(…) is equivalent to the object creation expression new Function(…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Function behaviour must include a super call to the Function constructor to create and initialize a subclass instance with the internal slots necessary for built-in function behaviour. All ECMAScript syntactic forms for defining function objects create instances of Function. There is no syntactic means to create instances of Function subclasses except for the built-in GeneratorFunction, AsyncFunction, and AsyncGeneratorFunction subclasses.

20.2.1.1 Function ( ...paramArgs, bodyArg )

The last argument (if any) specifies the body (executable code) of a function; any preceding arguments specify formal parameters.

This function performs the following steps when called:

  1. Let ctor be the active function object.
  2. If bodyArg is not present, set bodyArg to the empty String.
  3. Return ? CreateDynamicFunction(ctor, NewTarget, normal, paramArgs, bodyArg).
 Note

It is permissible but not necessary to have one argument for each formal parameter to be specified. For example, all three of the following expressions produce the same result:

new Function("a", "b", "c", "return a+b+c")
new Function("a, b, c", "return a+b+c")
new Function("a,b", "c", "return a+b+c")

20.2.1.1.1 CreateDynamicFunction ( ctor, newTarget, kind, paramArgs, bodyArg )

The abstract operation CreateDynamicFunction takes arguments ctor (a constructor), newTarget (a constructor or undefined), kind (normal, generator, async, or async-generator), paramArgs (a List of ECMAScript language values), and bodyArg (an ECMAScript language value) and returns either a normal completion containing an ECMAScript function object or a throw completion. ctor is the constructor function that is performing this action. newTarget is the constructor that new was initially applied to. paramArgs and bodyArg reflect the argument values that were passed to ctor. It performs the following steps when called:

  1. If newTarget is undefined, set newTarget to ctor.
  2. If kind is normal, then
    1. Let prefix be "function".
    2. Let exprGrammar be the grammar symbol FunctionExpression.
    3. Let bodyGrammar be the grammar symbol FunctionBody[~Yield, ~Await].
    4. Let paramGrammar be the grammar symbol FormalParameters[~Yield, ~Await].
    5. Let fallbackProto be "%Function.prototype%".
  3. Else if kind is generator, then
    1. Let prefix be "function*".
    2. Let exprGrammar be the grammar symbol GeneratorExpression.
    3. Let bodyGrammar be the grammar symbol GeneratorBody.
    4. Let paramGrammar be the grammar symbol FormalParameters[+Yield, ~Await].
    5. Let fallbackProto be "%GeneratorFunction.prototype%".
  4. Else if kind is async, then
    1. Let prefix be "async function".
    2. Let exprGrammar be the grammar symbol AsyncFunctionExpression.
    3. Let bodyGrammar be the grammar symbol AsyncFunctionBody.
    4. Let paramGrammar be the grammar symbol FormalParameters[~Yield, +Await].
    5. Let fallbackProto be "%AsyncFunction.prototype%".
  5. Else,
    1. Assert: kind is async-generator.
    2. Let prefix be "async function*".
    3. Let exprGrammar be the grammar symbol AsyncGeneratorExpression.
    4. Let bodyGrammar be the grammar symbol AsyncGeneratorBody.
    5. Let paramGrammar be the grammar symbol FormalParameters[+Yield, +Await].
    6. Let fallbackProto be "%AsyncGeneratorFunction.prototype%".
  6. Let argCount be the number of elements in paramArgs.
  7. Let paramStrings be a new empty List.
  8. For each element arg of paramArgs, do
    1. If arg is an Object, let paramString be HostGetCodeForEval(arg); else let paramString be no-code.
    2. If paramString is no-code, set paramString to ? ToString(arg).
    3. Append paramString to paramStrings.
  9. If bodyArg is an Object, let bodyString be HostGetCodeForEval(bodyArg); else let bodyString be no-code.
  10. If bodyString is no-code, set bodyString to ? ToString(bodyArg).
  11. Let currentRealm be the current Realm Record.
  12. Let joinedParamsString be the empty String.
  13. If argCount > 0, then
    1. Set joinedParamsString to paramStrings[0].
    2. Let k be 1.
    3. Repeat, while k < argCount,
      1. Let nextArgString be paramStrings[k].
      2. Set joinedParamsString to the string-concatenation of joinedParamsString, "," (a comma), and nextArgString.
      3. Set k to k + 1.
  14. Let bodyParseString be the string-concatenation of 0x000A (LINE FEED), bodyString, and 0x000A (LINE FEED).
  15. Let sourceString be the string-concatenation of prefix, " anonymous(", joinedParamsString, 0x000A (LINE FEED), ") {", bodyParseString, and "}".
  16. Perform ? HostEnsureCanCompileStrings(currentRealm, paramStrings, bodyString, sourceString, function, paramArgs, bodyArg).
  17. Let sourceText be StringToCodePoints(sourceString).
  18. Let params be ParseText(joinedParamsString, paramGrammar).
  19. If params is a List of errors, throw a SyntaxError exception.
  20. Let body be ParseText(bodyParseString, bodyGrammar).
  21. If body is a List of errors, throw a SyntaxError exception.
  22. NOTE: The parameters and body are parsed separately to ensure that each is valid alone. For example, new Function("/*", "*/ ) {") does not evaluate to a function.
  23. NOTE: If this step is reached, sourceText must have the syntax of exprGrammar (although the reverse implication does not hold). The purpose of the next two steps is to enforce any Early Error rules which apply to exprGrammar directly.
  24. Let expr be ParseText(sourceText, exprGrammar).
  25. If expr is a List of errors, throw a SyntaxError exception.
  26. Let funcProto be ? GetPrototypeFromConstructor(newTarget, fallbackProto).
  27. Let envRecord be currentRealm.[[GlobalEnv]].
  28. Let privateEnv be null.
  29. Let func be OrdinaryFunctionCreate(funcProto, sourceText, params, body, non-lexical-this, envRecord, privateEnv).
  30. Perform SetFunctionName(func, "anonymous").
  31. If kind is generator, then
    1. Let protoProto be OrdinaryObjectCreate(%GeneratorPrototype%).
    2. Perform ! DefinePropertyOrThrow(func, "prototype", PropertyDescriptor { [[Value]]: protoProto, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false }).
  32. Else if kind is async-generator, then
    1. Let protoProto be OrdinaryObjectCreate(%AsyncGeneratorPrototype%).
    2. Perform ! DefinePropertyOrThrow(func, "prototype", PropertyDescriptor { [[Value]]: protoProto, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false }).
  33. Else if kind is normal, then
    1. Perform MakeConstructor(func).
  34. NOTE: Functions whose kind is async are not constructable and do not have a [[Construct]] internal method or a "prototype" property.
  35. Return func.
 Note

CreateDynamicFunction defines a "prototype" property on any function it creates whose kind is not async to provide for the possibility that the function will be used as a constructor.

20.2.2 Properties of the Function Constructor

The Function constructor:

  • is itself a built-in function object.
  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has a "length" property whose value is 1𝔽.
  • has the following properties:

20.2.2.1 Function.prototype

The value of Function.prototype is the Function prototype object.

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

20.2.3 Properties of the Function Prototype Object

The Function prototype object:

  • is %Function.prototype%.
  • is itself a built-in function object.
  • accepts any arguments and returns undefined when invoked.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • does not have a "prototype" property.
  • has a "length" property whose value is +0𝔽.
  • has a "name" property whose value is the empty String.
Note

The Function prototype object is specified to be a function object to ensure compatibility with ECMAScript code that was created prior to the ECMAScript 2015 specification.

20.2.3.1 Function.prototype.apply ( thisArg, argArray )

This method performs the following steps when called:

  1. Let func be the this value.
  2. If IsCallable(func) is false, throw a TypeError exception.
  3. If argArray is either undefined or null, then
    1. Perform PrepareForTailCall().
    2. Return ? Call(func, thisArg).
  4. Let argList be ? CreateListFromArrayLike(argArray).
  5. Perform PrepareForTailCall().
  6. Return ? Call(func, thisArg, argList).
 Note 1

The thisArg value is passed without modification as the this value. This is a change from Edition 3, where an undefined or null thisArg is replaced with the global object and ToObject is applied to all other values and that result is passed as the this value. Even though the thisArg is passed without modification, non-strict functions still perform these transformations upon entry to the function.

 Note 2

If func is either an arrow function or a bound function exotic object, then the thisArg will be ignored by the function [[Call]] in step 6.

20.2.3.2 Function.prototype.bind ( thisArg, ...args )

This method performs the following steps when called:

  1. Let target be the this value.
  2. If IsCallable(target) is false, throw a TypeError exception.
  3. Let boundFunc be ? BoundFunctionCreate(target, thisArg, args).
  4. Let length be 0.
  5. Let targetHasLength be ? HasOwnProperty(target, "length").
  6. If targetHasLength is true, then
    1. Let targetLength be ? Get(target, "length").
    2. If targetLength is a Number, then
      1. Let targetLengthAsInt be ! ToIntegerOrInfinity(targetLength).
      2. If targetLengthAsInt = +∞, then
        1. Set length to +∞.
      3. Else if targetLengthAsInt = -∞, then
        1. Set length to 0.
      4. Else,
        1. Let argCount be the number of elements in args.
        2. Set length to max(targetLengthAsInt - argCount, 0).
  7. Perform SetFunctionLength(boundFunc, length).
  8. Let targetName be ? Get(target, "name").
  9. If targetName is not a String, set targetName to the empty String.
  10. Perform SetFunctionName(boundFunc, targetName, "bound").
  11. Return boundFunc.
 Note 1

Function objects created using Function.prototype.bind are exotic objects. They also do not have a "prototype" property.

 Note 2

If target is either an arrow function or a bound function exotic object, then the thisArg passed to this method will not be used by subsequent calls to func.

20.2.3.3 Function.prototype.call ( thisArg, ...args )

This method performs the following steps when called:

  1. Let func be the this value.
  2. If IsCallable(func) is false, throw a TypeError exception.
  3. Perform PrepareForTailCall().
  4. Return ? Call(func, thisArg, args).
 Note 1

The thisArg value is passed without modification as the this value. This is a change from Edition 3, where an undefined or null thisArg is replaced with the global object and ToObject is applied to all other values and that result is passed as the this value. Even though the thisArg is passed without modification, non-strict functions still perform these transformations upon entry to the function.

 Note 2

If func is either an arrow function or a bound function exotic object, then the thisArg will be ignored by the function [[Call]] in step 4.

20.2.3.4 Function.prototype.constructor

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

20.2.3.5 Function.prototype.toString ( )

This method performs the following steps when called:

  1. Let func be the this value.
  2. If func is an Object, func has a [[SourceText]] internal slot, func.[[SourceText]] is a sequence of Unicode code points, and HostHasSourceTextAvailable(func) is true, then
    1. Return CodePointsToString(func.[[SourceText]]).
  3. If func is a built-in function object, return an implementation-defined String source code representation of func. The representation must have the syntax of a NativeFunction. Additionally, if func has an [[InitialName]] internal slot and func.[[InitialName]] is a String, the portion of the returned String that would be matched by NativeFunctionAccessoropt PropertyName must be func.[[InitialName]].
  4. If func is an Object and IsCallable(func) is true, return an implementation-defined String source code representation of func. The representation must have the syntax of a NativeFunction.
  5. Throw a TypeError exception.
 NativeFunction : function NativeFunctionAccessoropt PropertyName[~Yield, ~Await]opt ( FormalParameters[~Yield, ~Await] ) { [ native code ] } NativeFunctionAccessor : get set

20.2.3.6 Function.prototype [ %Symbol.hasInstance% ] ( value )

This method performs the following steps when called:

  1. Let thisValue be the this value.
  2. Return ? OrdinaryHasInstance(thisValue, value).

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

Note

This is the default implementation of %Symbol.hasInstance% that most functions inherit. %Symbol.hasInstance% is called by the instanceof operator to determine whether a value is an instance of a specific constructor. An expression such as

v instanceof F

evaluates as

F[%Symbol.hasInstance%](v)

A constructor function can control which objects are recognized as its instances by instanceof by exposing a different %Symbol.hasInstance% method on the function.

This property is non-writable and non-configurable to prevent tampering that could be used to globally expose the target function of a bound function.

The value of the "name" property of this method is "[Symbol.hasInstance]".

20.2.4 Function Instances

Every Function instance is an ECMAScript function object and has the internal slots listed in Table 26. Function objects created using the Function.prototype.bind method (20.2.3.2) have the internal slots listed in Table 27.

Function instances have the following properties:

20.2.4.1 length

The value of the "length" property is an integral Number that indicates the typical number of arguments expected by the function. However, the language permits the function to be invoked with some other number of arguments. The behaviour of a function when invoked on a number of arguments other than the number specified by its "length" property depends on the function. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

20.2.4.2 name

The value of the "name" property is a String that is descriptive of the function. The name has no semantic significance but is typically a variable or property name that is used to refer to the function at its point of definition in ECMAScript source text. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

Anonymous function objects that do not have a contextual name associated with them by this specification use the empty String as the value of the "name" property.

20.2.4.3 prototype

Function instances that can be used as a constructor have a "prototype" property. Whenever such a Function instance is created another ordinary object is also created and is the initial value of the function's "prototype" property. Unless otherwise specified, the value of the "prototype" property is used to initialize the [[Prototype]] internal slot of the object created when that function is invoked as a constructor.

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

Note

Function objects created using Function.prototype.bind, or by evaluating a MethodDefinition (that is not a GeneratorMethod or AsyncGeneratorMethod) or an ArrowFunction do not have a "prototype" property.

20.2.5 HostHasSourceTextAvailable ( func )

The host-defined abstract operation HostHasSourceTextAvailable takes argument func (a function object) and returns a Boolean. It allows host environments to prevent the source text from being provided for func.

An implementation of HostHasSourceTextAvailable must conform to the following requirements:

  • It must be deterministic with respect to its parameters. Each time it is called with a specific func as its argument, it must return the same result.

The default implementation of HostHasSourceTextAvailable is to return true.

20.3 Boolean Objects

20.3.1 The Boolean Constructor

The Boolean constructor:

  • is %Boolean%.
  • is the initial value of the "Boolean" property of the global object.
  • creates and initializes a new Boolean 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. Subclass constructors that intend to inherit the specified Boolean behaviour must include a super call to the Boolean constructor to create and initialize the subclass instance with a [[BooleanData]] internal slot.

20.3.1.1 Boolean ( value )

This function performs the following steps when called:

  1. Let bool be ToBoolean(value).
  2. If NewTarget is undefined, return bool.
  3. Let obj be ? OrdinaryCreateFromConstructor(NewTarget, "%Boolean.prototype%", « [[BooleanData]] »).
  4. Set obj.[[BooleanData]] to bool.
  5. Return obj.

20.3.2 Properties of the Boolean Constructor

The Boolean constructor:

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

20.3.2.1 Boolean.prototype

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

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

20.3.3 Properties of the Boolean Prototype Object

The Boolean prototype object:

20.3.3.1 Boolean.prototype.constructor

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

20.3.3.2 Boolean.prototype.toString ( )

This method performs the following steps when called:

  1. Let bool be ? ThisBooleanValue(this value).
  2. If bool is true, return "true".
  3. Return "false".

20.3.3.3 Boolean.prototype.valueOf ( )

This method performs the following steps when called:

  1. Return ? ThisBooleanValue(this value).

20.3.3.3.1 ThisBooleanValue ( arg )

The abstract operation ThisBooleanValue takes argument arg (an ECMAScript language value) and returns either a normal completion containing a Boolean or a throw completion. It performs the following steps when called:

  1. If arg is a Boolean, return arg.
  2. If arg is an Object and arg has a [[BooleanData]] internal slot, then
    1. Let bool be arg.[[BooleanData]].
    2. Assert: bool is a Boolean.
    3. Return bool.
  3. Throw a TypeError exception.

20.3.4 Properties of Boolean Instances

A Boolean object is an Object with a [[BooleanData]] internal slot containing the Boolean value it represents. Boolean instances are ordinary objects that inherit properties from the Boolean prototype object.

Note

Boolean objects can be created by using the Boolean constructor in a new expression, supplying a Boolean value as an argument. A Boolean object can be converted to the Boolean value it represents by calling Boolean.prototype.valueOf (20.3.3.3). All Boolean objects convert to true when in a position that expects a Boolean value.

20.4 Symbol Objects

20.4.1 The Symbol Constructor

The Symbol constructor:

  • is %Symbol%.
  • is the initial value of the "Symbol" property of the global object.
  • returns a new Symbol value when called as a function.
  • is not intended to be used with the new operator.
  • is not intended to be subclassed.
  • may be used as the value of an extends clause of a class definition but a super call to it will cause an exception.

20.4.1.1 Symbol ( [ description ] )

This function performs the following steps when called:

  1. If NewTarget is not undefined, throw a TypeError exception.
  2. If description is undefined, let descString be undefined.
  3. Else, let descString be ? ToString(description).
  4. Return a new Symbol whose [[Description]] is descString.

20.4.2 Properties of the Symbol Constructor

The Symbol constructor:

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

20.4.2.1 Symbol.asyncDispose

The initial value of Symbol.asyncDispose is the well-known symbol %Symbol.asyncDispose% (Table 1).

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

20.4.2.2 Symbol.asyncIterator

The initial value of Symbol.asyncIterator is the well-known symbol %Symbol.asyncIterator% (Table 1).

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

20.4.2.3 Symbol.dispose

The initial value of Symbol.dispose is the well-known symbol %Symbol.dispose% (Table 1).

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

20.4.2.4 Symbol.for ( key )

This function performs the following steps when called:

  1. Let stringKey be ? ToString(key).
  2. Let agentRecord be the Agent Record of the surrounding agent.
  3. Let globalSymbolRegistry be agentRecord.[[GlobalSymbolRegistry]].
  4. For each element element of globalSymbolRegistry, do
    1. If element.[[Key]] is stringKey, return element.[[Symbol]].
  5. Assert: globalSymbolRegistry does not currently contain an entry for stringKey.
  6. Let newSymbol be a new Symbol whose [[Description]] is stringKey.
  7. Append the GlobalSymbolRegistry Record { [[Key]]: stringKey, [[Symbol]]: newSymbol } to globalSymbolRegistry.
  8. Return newSymbol.

20.4.2.5 Symbol.hasInstance

The initial value of Symbol.hasInstance is the well-known symbol %Symbol.hasInstance% (Table 1).

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

20.4.2.6 Symbol.isConcatSpreadable

The initial value of Symbol.isConcatSpreadable is the well-known symbol %Symbol.isConcatSpreadable% (Table 1).

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

20.4.2.7 Symbol.iterator

The initial value of Symbol.iterator is the well-known symbol %Symbol.iterator% (Table 1).

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

20.4.2.8 Symbol.keyFor ( symbol )

This function performs the following steps when called:

  1. If symbol is not a Symbol, throw a TypeError exception.
  2. Return KeyForSymbol(symbol).

20.4.2.9 Symbol.match

The initial value of Symbol.match is the well-known symbol %Symbol.match% (Table 1).

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

20.4.2.10 Symbol.matchAll

The initial value of Symbol.matchAll is the well-known symbol %Symbol.matchAll% (Table 1).

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

20.4.2.11 Symbol.prototype

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

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

20.4.2.12 Symbol.replace

The initial value of Symbol.replace is the well-known symbol %Symbol.replace% (Table 1).

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

20.4.2.13 Symbol.search

The initial value of Symbol.search is the well-known symbol %Symbol.search% (Table 1).

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

20.4.2.14 Symbol.species

The initial value of Symbol.species is the well-known symbol %Symbol.species% (Table 1).

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

20.4.2.15 Symbol.split

The initial value of Symbol.split is the well-known symbol %Symbol.split% (Table 1).

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

20.4.2.16 Symbol.toPrimitive

The initial value of Symbol.toPrimitive is the well-known symbol %Symbol.toPrimitive% (Table 1).

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

20.4.2.17 Symbol.toStringTag

The initial value of Symbol.toStringTag is the well-known symbol %Symbol.toStringTag% (Table 1).

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

20.4.2.18 Symbol.unscopables

The initial value of Symbol.unscopables is the well-known symbol %Symbol.unscopables% (Table 1).

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

20.4.3 Properties of the Symbol Prototype Object

The Symbol prototype object:

20.4.3.1 Symbol.prototype.constructor

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

20.4.3.2 get Symbol.prototype.description

Symbol.prototype.description is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let symbol be ? ThisSymbolValue(this value).
  2. Return symbol.[[Description]].

20.4.3.3 Symbol.prototype.toString ( )

This method performs the following steps when called:

  1. Let symbol be ? ThisSymbolValue(this value).
  2. Return SymbolDescriptiveString(symbol).

20.4.3.3.1 SymbolDescriptiveString ( symbol )

The abstract operation SymbolDescriptiveString takes argument symbol (a Symbol) and returns a String. It performs the following steps when called:

  1. Let description be symbol.[[Description]].
  2. If description is undefined, set description to the empty String.
  3. Assert: description is a String.
  4. Return the string-concatenation of "Symbol(", description, and ")".

20.4.3.4 Symbol.prototype.valueOf ( )

This method performs the following steps when called:

  1. Return ? ThisSymbolValue(this value).

20.4.3.4.1 ThisSymbolValue ( arg )

The abstract operation ThisSymbolValue takes argument arg (an ECMAScript language value) and returns either a normal completion containing a Symbol or a throw completion. It performs the following steps when called:

  1. If arg is a Symbol, return arg.
  2. If arg is an Object and arg has a [[SymbolData]] internal slot, then
    1. Let symbol be arg.[[SymbolData]].
    2. Assert: symbol is a Symbol.
    3. Return symbol.
  3. Throw a TypeError exception.

20.4.3.5 Symbol.prototype [ %Symbol.toPrimitive% ] ( hint )

This method is called by ECMAScript language operators to convert a Symbol object to a primitive value.

It performs the following steps when called:

  1. Return ? ThisSymbolValue(this value).
 Note

The argument is ignored.

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

The value of the "name" property of this method is "[Symbol.toPrimitive]".

20.4.3.6 Symbol.prototype [ %Symbol.toStringTag% ]

The initial value of the %Symbol.toStringTag% property is the String value "Symbol".

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

20.4.4 Properties of Symbol Instances

A Symbol object is an Object with a [[SymbolData]] internal slot containing the Symbol value it represents. Symbol instances are ordinary objects that inherit properties from the Symbol prototype object.

20.4.5 Abstract Operations for Symbols

20.4.5.1 GlobalSymbolRegistry Records

A GlobalSymbolRegistry Record is a Record used to associate a String key with a Symbol value registered through Symbol.for.

GlobalSymbolRegistry Records have the fields listed in Table 59.

Table 59: GlobalSymbolRegistry Record Fields
Field Name Value Usage
[[Key]] a String A string key used to globally identify a Symbol.
[[Symbol]] a Symbol A symbol that can be retrieved from any realm.

20.4.5.2 KeyForSymbol ( symbol )

The abstract operation KeyForSymbol takes argument symbol (a Symbol) and returns a String or undefined. If symbol is in the surrounding agent's [[GlobalSymbolRegistry]] List, the String used to register symbol will be returned. It performs the following steps when called:

  1. Let agentRecord be the Agent Record of the surrounding agent.
  2. Let globalSymbolRegistry be agentRecord.[[GlobalSymbolRegistry]].
  3. For each element element of globalSymbolRegistry, do
    1. If SameValue(element.[[Symbol]], symbol) is true, return element.[[Key]].
  4. Assert: globalSymbolRegistry does not currently contain an entry for symbol.
  5. Return undefined.

20.5 Error Objects

Instances of Error objects are thrown as exceptions when runtime errors occur. The Error objects may also serve as base objects for user-defined exception classes.

When an ECMAScript implementation detects a runtime error, it throws a new instance of one of the NativeError objects defined in 20.5.5 or a new instance of either the AggregateError object defined in 20.5.7, or the SuppressedError object defined in 20.5.8. Each of these objects has the structure described below, differing only in the name used as the constructor name instead of NativeError, in the "name" property of the prototype object, in the implementation-defined "message" property of the prototype object, and in the presence of the %AggregateError%-specific "errors" property or the %SuppressedError%-specific "error" and "suppressed" properties.

20.5.1 The Error Constructor

The Error constructor:

  • is %Error%.
  • is the initial value of the "Error" property of the global object.
  • creates and initializes a new Error object when called as a function rather than as a constructor. Thus the function call Error(…) is equivalent to the object creation expression new Error(…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Error behaviour must include a super call to the Error constructor to create and initialize subclass instances with an [[ErrorData]] internal slot.

20.5.1.1 Error ( message [ , options ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, let newTarget be the active function object; else let newTarget be NewTarget.
  2. Let obj be ? OrdinaryCreateFromConstructor(newTarget, "%Error.prototype%", « [[ErrorData]] »).
  3. If message is not undefined, then
    1. Let messageString be ? ToString(message).
    2. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "message", messageString).
  4. Perform ? InstallErrorCause(obj, options).
  5. Return obj.

20.5.2 Properties of the Error Constructor

The Error constructor:

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

20.5.2.1 Error.isError ( arg )

This function performs the following steps when called:

  1. If arg is not an Object, return false.
  2. If arg does not have an [[ErrorData]] internal slot, return false.
  3. Return true.

20.5.2.2 Error.prototype

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

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

20.5.3 Properties of the Error Prototype Object

The Error prototype object:

  • is %Error.prototype%.
  • is an ordinary object.
  • is not an Error instance and does not have an [[ErrorData]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.

20.5.3.1 Error.prototype.constructor

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

20.5.3.2 Error.prototype.message

The initial value of Error.prototype.message is the empty String.

20.5.3.3 Error.prototype.name

The initial value of Error.prototype.name is "Error".

20.5.3.4 Error.prototype.toString ( )

This method performs the following steps when called:

  1. Let obj be the this value.
  2. If obj is not an Object, throw a TypeError exception.
  3. Let name be ? Get(obj, "name").
  4. If name is undefined, set name to "Error"; else set name to ? ToString(name).
  5. Let message be ? Get(obj, "message").
  6. If message is undefined, set message to the empty String; else set message to ? ToString(message).
  7. If name is the empty String, return message.
  8. If message is the empty String, return name.
  9. Return the string-concatenation of name, the code unit 0x003A (COLON), the code unit 0x0020 (SPACE), and message.

20.5.4 Properties of Error Instances

Error instances are ordinary objects that inherit properties from the Error prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is to identify Error, AggregateError, SuppressedError, and NativeError instances as Error objects within Object.prototype.toString and Error.isError.

20.5.5 Native Error Types Used in This Standard

A new instance of one of the NativeError objects below or of either the AggregateError object or SuppressedError object is thrown when a runtime error is detected. All NativeError objects share the same structure, as described in 20.5.6.

20.5.5.1 EvalError

The EvalError constructor is %EvalError%.

This exception is not currently used within this specification. This object remains for compatibility with previous editions of this specification.

20.5.5.2 RangeError

The RangeError constructor is %RangeError%.

Indicates a value that is not in the set or range of allowable values.

20.5.5.3 ReferenceError

The ReferenceError constructor is %ReferenceError%.

Indicate that an invalid reference has been detected.

20.5.5.4 SyntaxError

The SyntaxError constructor is %SyntaxError%.

Indicates that a parsing error has occurred.

20.5.5.5 TypeError

The TypeError constructor is %TypeError%.

TypeError is used to indicate an unsuccessful operation when none of the other NativeError objects are an appropriate indication of the failure cause.

20.5.5.6 URIError

The URIError constructor is %URIError%.

Indicates that one of the global URI handling functions was used in a way that is incompatible with its definition.

20.5.6 NativeError Object Structure

Each of these objects has the structure described below, differing only in the name used as the constructor name and in the "name" property of the prototype object.

For each error object, references to NativeError in the definition should be replaced with the appropriate error object name from 20.5.5.

20.5.6.1 The NativeError Constructors

Each NativeError constructor:

  • creates and initializes a new NativeError object when called as a function rather than as a constructor. A call of the object as a function is equivalent to calling it as a constructor with the same arguments. Thus the function call NativeError(…) is equivalent to the object creation expression new NativeError(…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified NativeError behaviour must include a super call to the NativeError constructor to create and initialize subclass instances with an [[ErrorData]] internal slot.

20.5.6.1.1 NativeError ( message [ , options ] )

Each NativeError function performs the following steps when called:

  1. If NewTarget is undefined, let newTarget be the active function object; else let newTarget be NewTarget.
  2. Let obj be ? OrdinaryCreateFromConstructor(newTarget, "%NativeError.prototype%", « [[ErrorData]] »).
  3. If message is not undefined, then
    1. Let messageString be ? ToString(message).
    2. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "message", messageString).
  4. Perform ? InstallErrorCause(obj, options).
  5. Return obj.

The actual value of the string passed in step 2 is either "%EvalError.prototype%", "%RangeError.prototype%", "%ReferenceError.prototype%", "%SyntaxError.prototype%", "%TypeError.prototype%", or "%URIError.prototype%" corresponding to which NativeError constructor is being defined.

20.5.6.2 Properties of the NativeError Constructors

Each NativeError constructor:

  • has a [[Prototype]] internal slot whose value is %Error%.
  • has a "name" property whose value is the String value "NativeError".
  • has the following properties:

20.5.6.2.1 NativeError.prototype

The initial value of NativeError.prototype is a NativeError prototype object (20.5.6.3). Each NativeError constructor has a distinct prototype object.

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

20.5.6.3 Properties of the NativeError Prototype Objects

Each NativeError prototype object:

  • is an ordinary object.
  • is not an Error instance and does not have an [[ErrorData]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Error.prototype%.

20.5.6.3.1 NativeError.prototype.constructor

The initial value of the "constructor" property of the prototype for a given NativeError constructor is the constructor itself.

20.5.6.3.2 NativeError.prototype.message

The initial value of the "message" property of the prototype for a given NativeError constructor is the empty String.

20.5.6.3.3 NativeError.prototype.name

The initial value of the "name" property of the prototype for a given NativeError constructor is the String value consisting of the name of the constructor (the name used instead of NativeError).

20.5.6.4 Properties of NativeError Instances

NativeError instances are ordinary objects that inherit properties from their NativeError prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is by Object.prototype.toString (20.1.3.6) and Error.isError (20.5.2.1) to identify Error, AggregateError, SuppressedError, or NativeError instances.

20.5.7 AggregateError Objects

20.5.7.1 The AggregateError Constructor

The AggregateError constructor:

  • is %AggregateError%.
  • is the initial value of the "AggregateError" property of the global object.
  • creates and initializes a new AggregateError object when called as a function rather than as a constructor. Thus the function call AggregateError(…) is equivalent to the object creation expression new AggregateError(…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified AggregateError behaviour must include a super call to the AggregateError constructor to create and initialize subclass instances with an [[ErrorData]] internal slot.

20.5.7.1.1 AggregateError ( errors, message [ , options ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, let newTarget be the active function object; else let newTarget be NewTarget.
  2. Let obj be ? OrdinaryCreateFromConstructor(newTarget, "%AggregateError.prototype%", « [[ErrorData]] »).
  3. If message is not undefined, then
    1. Let messageString be ? ToString(message).
    2. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "message", messageString).
  4. Perform ? InstallErrorCause(obj, options).
  5. Let errorsList be ? IteratorToList(? GetIterator(errors, sync)).
  6. Perform ! DefinePropertyOrThrow(obj, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errorsList) }).
  7. Return obj.

20.5.7.2 Properties of the AggregateError Constructor

The AggregateError constructor:

  • has a [[Prototype]] internal slot whose value is %Error%.
  • has the following properties:

20.5.7.2.1 AggregateError.prototype

The initial value of AggregateError.prototype is %AggregateError.prototype%.

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

20.5.7.3 Properties of the AggregateError Prototype Object

The AggregateError prototype object:

  • is %AggregateError.prototype%.
  • is an ordinary object.
  • is not an Error instance or an AggregateError instance and does not have an [[ErrorData]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Error.prototype%.

20.5.7.3.1 AggregateError.prototype.constructor

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

20.5.7.3.2 AggregateError.prototype.message

The initial value of AggregateError.prototype.message is the empty String.

20.5.7.3.3 AggregateError.prototype.name

The initial value of AggregateError.prototype.name is "AggregateError".

20.5.7.4 Properties of AggregateError Instances

AggregateError instances are ordinary objects that inherit properties from their AggregateError prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is by Object.prototype.toString (20.1.3.6) and Error.isError (20.5.2.1) to identify Error, AggregateError, SuppressedError, or NativeError instances.

20.5.8 SuppressedError Objects

20.5.8.1 The SuppressedError Constructor

The SuppressedError constructor:

  • is %SuppressedError%.
  • is the initial value of the "SuppressedError" property of the global object.
  • creates and initializes a new SuppressedError object when called as a function rather than as a constructor. Thus the function call SuppressedError(…) is equivalent to the object creation expression new SuppressedError(…) with the same arguments.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified SuppressedError behaviour must include a super call to the SuppressedError constructor to create and initialize subclass instances with an [[ErrorData]] internal slot.

20.5.8.1.1 SuppressedError ( error, suppressed, message )

This function performs the following steps when called:

  1. If NewTarget is undefined, let newTarget be the active function object; else let newTarget be NewTarget.
  2. Let obj be ? OrdinaryCreateFromConstructor(newTarget, "%SuppressedError.prototype%", « [[ErrorData]] »).
  3. If message is not undefined, then
    1. Let messageString be ? ToString(message).
    2. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "message", messageString).
  4. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "error", error).
  5. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "suppressed", suppressed).
  6. Return obj.

20.5.8.2 Properties of the SuppressedError Constructor

The SuppressedError constructor:

  • has a [[Prototype]] internal slot whose value is %Error%.
  • has the following properties:

20.5.8.2.1 SuppressedError.prototype

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

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

20.5.8.3 Properties of the SuppressedError Prototype Object

The SuppressedError prototype object:

  • is %SuppressedError.prototype%.
  • is an ordinary object.
  • is not an Error instance or a SuppressedError instance and does not have an [[ErrorData]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Error.prototype%.

20.5.8.3.1 SuppressedError.prototype.constructor

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

20.5.8.3.2 SuppressedError.prototype.message

The initial value of SuppressedError.prototype.message is the empty String.

20.5.8.3.3 SuppressedError.prototype.name

The initial value of SuppressedError.prototype.name is "SuppressedError".

20.5.8.4 Properties of SuppressedError Instances

SuppressedError instances are ordinary objects that inherit properties from their SuppressedError prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is to identify Error, AggregateError, SuppressedError, and NativeError instances as Error objects within Object.prototype.toString and Error.isError.

20.5.9 Abstract Operations for Error Objects

20.5.9.1 InstallErrorCause ( obj, options )

The abstract operation InstallErrorCause takes arguments obj (an Object) and options (an ECMAScript language value) and returns either a normal completion containing unused or a throw completion. It is used to create a "cause" property on obj when a "cause" property is present on options. It performs the following steps when called:

  1. If options is an Object and ? HasProperty(options, "cause") is true, then
    1. Let cause be ? Get(options, "cause").
    2. Perform CreateNonEnumerableDataPropertyOrThrow(obj, "cause", cause).
  2. Return unused.