HomepageExploring JavaScript (ES2024 Edition)
You can support this book: buy it or donate
(Ad, please don’t block.)

24 Symbols [ES6]

24.1 Symbols are primitives that are also like objects

Symbols are primitive values that are created via the factory function Symbol():

const mySymbol = Symbol('mySymbol');

The parameter is optional and provides a description, which is mainly useful for debugging.

24.1.1 Symbols are primitive values

Symbols are primitive values:

24.1.2 Symbols are also like objects

Even though symbols are primitives, they are also like objects in that each value created by Symbol() is unique and not compared by value:

> Symbol() === Symbol()
false

Prior to symbols, objects were the best choice if we needed values that were unique (only equal to themselves):

const string1 = 'abc';
const string2 = 'abc';
assert.equal(
  string1 === string2, true); // not unique

const object1 = {};
const object2 = {};
assert.equal(
  object1 === object2, false); // unique

const symbol1 = Symbol();
const symbol2 = Symbol();
assert.equal(
  symbol1 === symbol2, false); // unique

24.2 The descriptions of symbols

The parameter we pass to the symbol factory function provides a description for the created symbol:

const mySymbol = Symbol('mySymbol');

The description can be accessed in two ways.

First, it is part of the string returned by .toString():

assert.equal(mySymbol.toString(), 'Symbol(mySymbol)');

Second, since ES2019, we can retrieve the description via the property .description:

assert.equal(mySymbol.description, 'mySymbol');

24.3 Use cases for symbols

The main use cases for symbols, are:

24.3.1 Symbols as values for constants

Let’s assume you want to create constants representing the colors red, orange, yellow, green, blue, and violet. One simple way of doing so would be to use strings:

const COLOR_BLUE = 'Blue';

On the plus side, logging that constant produces helpful output. On the minus side, there is a risk of mistaking an unrelated value for a color because two strings with the same content are considered equal:

const MOOD_BLUE = 'Blue';
assert.equal(COLOR_BLUE, MOOD_BLUE);

We can fix that problem via symbols:

const COLOR_BLUE = Symbol('Blue');
const MOOD_BLUE = Symbol('Blue');

assert.notEqual(COLOR_BLUE, MOOD_BLUE);

Let’s use symbol-valued constants to implement a function:

const COLOR_RED    = Symbol('Red');
const COLOR_ORANGE = Symbol('Orange');
const COLOR_YELLOW = Symbol('Yellow');
const COLOR_GREEN  = Symbol('Green');
const COLOR_BLUE   = Symbol('Blue');
const COLOR_VIOLET = Symbol('Violet');

function getComplement(color) {
  switch (color) {
    case COLOR_RED:
      return COLOR_GREEN;
    case COLOR_ORANGE:
      return COLOR_BLUE;
    case COLOR_YELLOW:
      return COLOR_VIOLET;
    case COLOR_GREEN:
      return COLOR_RED;
    case COLOR_BLUE:
      return COLOR_ORANGE;
    case COLOR_VIOLET:
      return COLOR_YELLOW;
    default:
      throw new Exception('Unknown color: '+color);
  }
}
assert.equal(getComplement(COLOR_YELLOW), COLOR_VIOLET);

24.3.2 Symbols as unique property keys

The keys of properties (fields) in objects are used at two levels:

The base level and the meta-level of a program must be independent: Base-level property keys should not be in conflict with meta-level property keys.

If we use names (strings) as property keys, we are facing two challenges:

These are two examples of where the latter was an issue for JavaScript:

Symbols, used as property keys, help us here: Each symbol is unique and a symbol key never clashes with any other string or symbol key.

24.3.2.1 Example: a library with a meta-level method

As an example, let’s assume we are writing a library that treats objects differently if they implement a special method. This is what defining a property key for such a method and implementing it for an object would look like:

const specialMethod = Symbol('specialMethod');
const obj = {
  _id: 'kf12oi',
  [specialMethod]() { // (A)
    return this._id;
  }
};
assert.equal(obj[specialMethod](), 'kf12oi');

The square brackets in line A enable us to specify that the method must have the key specialMethod. More details are explained in “Computed keys in object literals” (§30.7.2).

24.4 Publicly known symbols

Symbols that play special roles within ECMAScript are called publicly known symbols. Examples include:

Icon “exercise”Exercises: Publicly known symbols

24.5 Converting symbols

What happens if we convert a symbol sym to another primitive type? Table 24.1 has the answers.

Convert toExplicit conversionCoercion (implicit conv.)
booleanBoolean(sym) → OK!sym → OK
numberNumber(sym)TypeErrorsym*2TypeError
stringString(sym) → OK''+symTypeError
sym.toString() → OK`${sym}`TypeError

Table 24.1: The results of converting symbols to other primitive types.

One key pitfall with symbols is how often exceptions are thrown when converting them to something else. What is the thinking behind that? First, conversion to number never makes sense and should be warned about. Second, converting a symbol to a string is indeed useful for diagnostic output. But it also makes sense to warn about accidentally turning a symbol into a string (which is a different kind of property key):

const obj = {};
const sym = Symbol();
assert.throws(
  () => { obj['__'+sym+'__'] = true },
  { message: 'Cannot convert a Symbol value to a string' });

The downside is that the exceptions make working with symbols more complicated. You have to explicitly convert symbols when assembling strings via the plus operator:

> const mySymbol = Symbol('mySymbol');
> 'Symbol I used: ' + mySymbol
TypeError: Cannot convert a Symbol value to a string
> 'Symbol I used: ' + String(mySymbol)
'Symbol I used: Symbol(mySymbol)'