ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

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.asyncIterator

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

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

20.4.2.2 Symbol.for ( key )

This function performs the following steps when called:

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

The GlobalSymbolRegistry is an append-only List that is globally available. It is shared by all realms. Prior to the evaluation of any ECMAScript code, it is initialized as a new empty List. Elements of the GlobalSymbolRegistry are Records with the structure defined in Table 60.

Table 60: 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.2.3 Symbol.hasInstance

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

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

20.4.2.4 Symbol.isConcatSpreadable

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

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

20.4.2.5 Symbol.iterator

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

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

20.4.2.6 Symbol.keyFor ( sym )

This function performs the following steps when called:

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

20.4.2.7 Symbol.match

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

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

20.4.2.8 Symbol.matchAll

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

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

20.4.2.9 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.10 Symbol.replace

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

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

20.4.2.11 Symbol.search

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

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

20.4.2.12 Symbol.species

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

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

20.4.2.13 Symbol.split

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

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

20.4.2.14 Symbol.toPrimitive

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

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

20.4.2.15 Symbol.toStringTag

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

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

20.4.2.16 Symbol.unscopables

The initial value of Symbol.unscopables is the well-known 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 s be the this value.
  2. Let sym be ? ThisSymbolValue(s).
  3. Return sym.[[Description]].

20.4.3.3 Symbol.prototype.toString ( )

This method performs the following steps when called:

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

20.4.3.3.1 SymbolDescriptiveString ( sym )

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

  1. Let desc be sym's [[Description]] value.
  2. If desc is undefined, set desc to the empty String.
  3. Assert: desc is a String.
  4. Return the string-concatenation of "Symbol(", desc, 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 ( value )

The abstract operation ThisSymbolValue takes argument value (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 value is a Symbol, return value.
  2. If value is an Object and value has a [[SymbolData]] internal slot, then
    1. Let s be value.[[SymbolData]].
    2. Assert: s is a Symbol.
    3. Return s.
  3. Throw a TypeError exception.

20.4.3.5 Symbol.prototype [ @@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 [ @@toStringTag ]

The initial value of the @@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

Symbol instances are ordinary objects that inherit properties from the Symbol prototype object. Symbol instances have a [[SymbolData]] internal slot. The [[SymbolData]] internal slot is the Symbol value represented by this Symbol object.

20.4.5 Abstract Operations for Symbols

20.4.5.1 KeyForSymbol ( sym )

The abstract operation KeyForSymbol takes argument sym (a Symbol) and returns a String or undefined. If sym is in the GlobalSymbolRegistry (see 20.4.2.2) the String used to register sym will be returned. It performs the following steps when called:

  1. For each element e of the GlobalSymbolRegistry List, do
    1. If SameValue(e.[[Symbol]], sym) is true, return e.[[Key]].
  2. Assert: GlobalSymbolRegistry does not currently contain an entry for sym.
  3. Return undefined.