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

When Symbol is called with optional argument description, the following steps are taken:

  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 unique Symbol value whose [[Description]] value 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 )

When Symbol.for is called with argument key it performs the following steps:

  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 unique Symbol value whose [[Description]] value is stringKey.
  5. Append the Record { [[Key]]: stringKey, [[Symbol]]: newSymbol } to the GlobalSymbolRegistry List.
  6. Return newSymbol.

The GlobalSymbolRegistry is a 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 51.

Table 51: 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 )

When Symbol.keyFor is called with argument sym it performs the following steps:

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

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:

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

The abstract operation thisSymbolValue takes argument value. It performs the following steps when called:

  1. If Type(value) is Symbol, return value.
  2. If Type(value) is Object and value has a [[SymbolData]] internal slot, then
    1. Let s be value.[[SymbolData]].
    2. Assert: Type(s) is Symbol.
    3. Return s.
  3. Throw a TypeError exception.

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:

  1. Let s be the this value.
  2. Let sym be ? thisSymbolValue(s).
  3. Return sym.[[Description]].

20.4.3.3 Symbol.prototype.toString ( )

The following steps are taken:

  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. It performs the following steps when called:

  1. Assert: Type(sym) is Symbol.
  2. Let desc be sym's [[Description]] value.
  3. If desc is undefined, set desc to the empty String.
  4. Assert: Type(desc) is String.
  5. Return the string-concatenation of "Symbol(", desc, and ")".

20.4.3.4 Symbol.prototype.valueOf ( )

The following steps are taken:

  1. Return ? thisSymbolValue(this value).

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

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

When the @@toPrimitive method is called with argument hint, the following steps are taken:

  1. Return ? thisSymbolValue(this value).

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

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

Note

The argument is ignored.

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.