Symbol

A Symbol is a built-in, immutable primitive data type in JavaScript introduced in ECMAScript 2015 (ES6). Every symbol value returned from the Symbol() function is guaranteed to be strictly unique in the memory space, regardless of the optional description string provided during its creation.

Creation and Syntax

Symbols are created by invoking the Symbol() function. Because Symbol is a primitive type and not an object constructor, invoking it with the new keyword throws a TypeError.

const emptySymbol = Symbol();
const describedSymbol = Symbol("debug_identifier"); 

// TypeError: Symbol is not a constructor
// const invalidSymbol = new Symbol(); 

The string argument passed to Symbol() serves exclusively as a description for debugging purposes and does not affect the symbol’s identity. Two symbols created with the exact same description are strictly unequal.

const sym1 = Symbol("token");
const sym2 = Symbol("token");

console.log(sym1 === sym2); // false

Type Coercion

Unlike other JavaScript primitives, Symbols do not undergo implicit type coercion to strings or numbers. Attempting to implicitly convert a Symbol will result in a TypeError. Explicit conversion is required.

const sym = Symbol("data");

// Explicit conversion succeeds
console.log(String(sym)); // "Symbol(data)"
console.log(sym.toString()); // "Symbol(data)"

// Implicit coercion fails
// console.log(sym + " string"); // TypeError
// console.log(+sym); // TypeError

The Global Symbol Registry

JavaScript maintains a cross-realm Global Symbol Registry. To create or access a symbol that is shared globally (across different execution contexts like iframes or service workers), you use Symbol.for() and Symbol.keyFor().

• Symbol.for(key): Searches the registry for a symbol with the given key. If found, it returns it. If not, it creates a new symbol, registers it with that key, and returns it.
• Symbol.keyFor(sym): Retrieves the shared string key for a given global symbol.

const globalSym1 = Symbol.for("shared.connection");
const globalSym2 = Symbol.for("shared.connection");

console.log(globalSym1 === globalSym2); // true

const localSym = Symbol("shared.connection");
console.log(globalSym1 === localSym); // false

console.log(Symbol.keyFor(globalSym1)); // "shared.connection"
console.log(Symbol.keyFor(localSym)); // undefined

Object Property Enumerability

When used as object keys, Symbols are non-enumerable by standard object reflection mechanisms. They are ignored by for...in loops, Object.keys(), and JSON.stringify().

To retrieve Symbol properties from an object, you must use specific reflection methods like Object.getOwnPropertySymbols() or Reflect.ownKeys().

const symKey = Symbol("metadata");
const targetObj = {
    id: 42,
    [symKey]: "hidden_value"
};

console.log(Object.keys(targetObj)); 
// ["id"]

console.log(JSON.stringify(targetObj)); 
// '{"id":42}'

console.log(Object.getOwnPropertySymbols(targetObj)); 
// [ Symbol(metadata) ]

console.log(Reflect.ownKeys(targetObj)); 
// [ "id", Symbol(metadata) ]

Well-Known Symbols

JavaScript exposes several built-in symbols as static properties on the Symbol constructor. These “well-known symbols” act as extension points, allowing developers to override internal language behaviors for custom objects.

Examples of well-known symbols include:

• Symbol.iterator: Defines the default iteration behavior for an object (used by for...of).
• Symbol.toPrimitive: Defines how an object is converted to a primitive value.
• Symbol.toStringTag: Defines the string description returned by Object.prototype.toString.call().

const customIterable = {
    *[Symbol.iterator]() {
        yield 1;
        yield 2;
    }
};

console.log([...customIterable]); // [1, 2]

Master JavaScript with Deep Grasping Methodology!

Learn More