Symbols are primitive values that are created via the factory function :

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

On one hand, symbols are like objects in that each value created by Symbol() is unique and not compared by value:

> Symbol() === Symbol()

On the other hand, they also behave like primitive values – they have to be categorized via typeof and they can be property keys in objects:

const sym = Symbol();
  [sym]: 123,

The main use cases for symbols are:

• Defining constants for the values of an enumerated type.
• Creating unique property keys.

20.1.1. Symbols: enum-style values

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:

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 COLOR_BLUE = Symbol('Blue');
const MOOD_BLUE = 'Blue';

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

const COLOR_RED    = Symbol('Red');
const COLOR_YELLOW = Symbol('Yellow');
const COLOR_VIOLET = Symbol('Violet');
function getComplement(color) {
    case COLOR_RED:
    case COLOR_ORANGE:
    case COLOR_YELLOW:
    case COLOR_GREEN:
      return COLOR_ORANGE;
      return COLOR_YELLOW;
      throw new Exception('Unknown color: '+color);
}

Notably, this function throws an exception if you call it with 'Blue':

assert.throws(() => getComplement('Blue'));

20.1.2. Symbols: unique property keys

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

• The program operates at a base level. Its keys reflect the problem domain.

The following code demonstrates the difference:

Properties .x and .y exist at the base level. They are the coordinates of the point encoded by point and reflect the problem domain. Method .toString() is a meta-level property. It tells JavaScript how to stringify this object.

The meta-level and the base level must never clash, which becomes harder when introducing new mechanisms later in the life of a programming language.

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');
  [specialMethod](x) {
  }
assert.equal(obj[specialMethod]('abc'), 'abcabc');

This syntax is explained in more detail in .

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

• Symbol.iterator: makes an object iterable. It’s the key of a method that returns an iterator. Iteration is explained in its own chapter.

• Symbol.hasInstance: customizes how instanceof works. It’s the key of a method to be implemented by the right-hand side of that operator. For example:

  static [Symbol.hasInstance](x) {
  }
assert.equal(null instanceof PrimitiveNull, true);

• Symbol.toStringTag: influences the default method.

'[object Object]'
'[object is no money]'

Note: It’s usually better to override .toString().

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

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');
TypeError: Cannot convert a Symbol value to a string

• For in-depth information on symbols (cross-realm symbols, all publicly known symbols, etc.), see “Exploring ES6”