Symbols

JavaScript's unique identifier primitive — Symbol(), well-known symbols, Symbol.iterator, Symbol.for, and using symbols as private-ish object keys.

What it is, in plain English: A Symbol is a primitive value that is guaranteed to be unique — no two Symbols are ever equal, even if created with the same description. Symbols are used as object property keys that can't accidentally collide with other keys. Well-known Symbols (Symbol.iterator, Symbol.toPrimitive, Symbol.hasInstance...) let you hook into JavaScript's built-in behaviours.

Where this bites you

Symbol keys are hidden from Object.keys, for...in and JSON.stringify, which makes them look private. They aren't. Object.getOwnPropertySymbols() and Reflect.ownKeys() list them, and Node's console.log prints them along with their values. Keep an API key under a Symbol and the first debug log of that object puts it in your logs.

const API_KEY = Symbol("apiKey");
const account = { name: "Alice", [API_KEY]: "sk-live-1234" };

console.log(Object.keys(account));        // looks hidden...
console.log(account);                     // ...until someone logs the object
console.log(Object.getOwnPropertySymbols(account).map(s => account[s]));
// [ 'name' ]
// { name: 'Alice', [Symbol(apiKey)]: 'sk-live-1234' }
// [ 'sk-live-1234' ]

Unique keys that never collide

JavaScript objects can have properties keyed by strings or Symbols. String keys can clash — if two pieces of code both add a "id" property, one overwrites the other. A Symbol is guaranteed unique — even two Symbols created with the same description are different values.

Creating Symbols

const sym1 = Symbol("description");   // the description is just for debugging
const sym2 = Symbol("description");

console.log(sym1 === sym2);   // false — ALWAYS different
console.log(typeof sym1);     // "symbol"
console.log(sym1.description); // "description" — the label you gave it
console.log(sym1.toString());  // "Symbol(description)"

// You cannot new Symbol() — it's not a constructor:
// new Symbol()  // TypeError: Symbol is not a constructor

Using Symbols as object keys

const SECRET = Symbol("secret");
const ID     = Symbol("id");

const user = {
  name:     "Alice",
  [SECRET]: "password123",   // computed property syntax for Symbol keys
  [ID]:     42,
};

// Access with the Symbol reference:
console.log(user[SECRET]);   // "password123"
console.log(user[ID]);       // 42
console.log(user.name);      // "Alice"

// Symbol keys are hidden from normal enumeration:
console.log(Object.keys(user));       // ["name"] — no symbols
console.log(JSON.stringify(user));    // {"name":"Alice"} — symbols dropped

// You need the actual Symbol reference to access it:
// user["secret"]  → undefined (that's a string key, not the Symbol)

Symbols prevent name collisions. They don't control access. When a value must not be readable from outside, use a class private field (#name). It's enforced by the language, it isn't listed by any reflection method, and Node's console.log doesn't print it:

class Account {
  #apiKey;                                // private field: unreachable outside the class
  constructor(name, apiKey) {
    this.name = name;
    this.#apiKey = apiKey;
  }
  authHeader() { return `Bearer ${this.#apiKey}`; }
}

const account = new Account("Alice", "sk-live-1234");
console.log(account);
console.log(Object.getOwnPropertySymbols(account));
console.log(account.authHeader());
// Account { name: 'Alice' }
// []
// Bearer sk-live-1234

The main uses of Symbols

// 1. Unique constants (no collision with other code):
const STATUS_PENDING  = Symbol("pending");
const STATUS_DONE     = Symbol("done");
const STATUS_FAILED   = Symbol("failed");

function process(task) {
  task.status = STATUS_PENDING;
  // ... do work ...
  task.status = STATUS_DONE;
}

// 2. Adding metadata to objects you don't own:
const META = Symbol("meta");
const thirdPartyObject = { data: [1, 2, 3] };
thirdPartyObject[META] = { addedAt: Date.now() };  // won't clash with any existing key

// 3. The global registry — share a Symbol across modules:
const shared1 = Symbol.for("app.user.id");
const shared2 = Symbol.for("app.user.id");
console.log(shared1 === shared2);  // true — same symbol from registry

Try It Yourself

// Every Symbol() call creates a unique value
const s1 = Symbol("my symbol");
const s2 = Symbol("my symbol");

console.log(s1 === s2);           // false — always unique!
console.log(typeof s1);           // "symbol"
console.log(s1.toString());       // "Symbol(my symbol)"
console.log(s1.description);      // "my symbol"

// Use as object keys — won't clash with string keys
const ID   = Symbol("id");
const TYPE = Symbol("type");

const user = {
  name: "Alice",
  [ID]:   42,         // Symbol key — uses computed property syntax
  [TYPE]: "admin",
};

console.log(user.name);    // "Alice"
console.log(user[ID]);     // 42
console.log(user[TYPE]);   // "admin"

// Symbol keys are invisible to most iteration:
console.log(Object.keys(user));    // ["name"] — no symbols!
console.log(JSON.stringify(user)); // {"name":"Alice"} — symbols dropped

// Get symbol keys explicitly:
console.log(Object.getOwnPropertySymbols(user)); // [Symbol(id), Symbol(type)]

// Global Symbol registry — share symbols across files:
const globalSym1 = Symbol.for("shared");
const globalSym2 = Symbol.for("shared");
console.log(globalSym1 === globalSym2);  // true — same registry entry

// Well-known symbol: Symbol.iterator
class Range {
  constructor(start, end) { this.start = start; this.end = end; }
  [Symbol.iterator]() {
    let current = this.start;
    const end = this.end;
    return { next() { return current <= end
      ? { value: current++, done: false }
      : { value: undefined, done: true }; } };
  }
}
console.log([...new Range(1, 5)]);  // [1, 2, 3, 4, 5]

Well-known symbols — hooking into JS built-in behaviour

JavaScript has a set of built-in Symbols called well-known symbols. By adding these as methods on your objects, you customise how JavaScript's operators and built-in functions treat them.

Symbol.iterator — make anything iterable

class NumberRange {
  constructor(start, end, step = 1) {
    this.start = start;
    this.end   = end;
    this.step  = step;
  }

  [Symbol.iterator]() {
    let current = this.start;
    const { end, step } = this;
    return {
      next() {
        if (current <= end) {
          const value = current;
          current += step;
          return { value, done: false };
        }
        return { value: undefined, done: true };
      }
    };
  }
}

const evens = new NumberRange(2, 10, 2);
console.log([...evens]);           // [2, 4, 6, 8, 10]
for (const n of new NumberRange(1, 5)) console.log(n);  // 1 2 3 4 5

Symbol.toPrimitive — control type conversion

class Temperature {
  constructor(celsius) { this.celsius = celsius; }

  [Symbol.toPrimitive](hint) {
    if (hint === "number") return this.celsius;
    if (hint === "string") return `${this.celsius}°C`;
    return this.celsius;  // "default" hint
  }
}

const t = new Temperature(37);
console.log(+t);          // 37      (number hint)
console.log(`${t}`);      // "37°C"  (string hint)
console.log(t + 0);       // 37      (default hint)

Symbol.hasInstance — customise instanceof

class Even {
  static [Symbol.hasInstance](num) {
    return typeof num === "number" && num % 2 === 0;
  }
}

console.log(2 instanceof Even);   // true
console.log(3 instanceof Even);   // false

All well-known symbols

Symbol.iterator       // for...of, spread, destructuring
Symbol.asyncIterator  // for await...of
Symbol.toPrimitive    // +, template literals, comparisons
Symbol.toStringTag    // Object.prototype.toString() tag
Symbol.hasInstance    // instanceof
Symbol.isConcatSpreadable  // Array.prototype.concat
Symbol.species        // constructor for derived objects (Array, Map, Set)
Symbol.match          // String.prototype.match, startsWith
Symbol.replace        // String.prototype.replace
Symbol.search         // String.prototype.search
Symbol.split          // String.prototype.split
Symbol.unscopables    // with statement exclusions

Symbol internals and the global registry

Symbols in the spec (ECMA-262 §20.4)

Symbols are a primitive type — they pass the IsSymbol abstract operation check and have type tag "symbol" from typeof. Symbol values are not coercible to string via implicit conversion (only .toString() or .description) — attempting string concatenation throws a TypeError. Each Symbol has an internal [[Description]] slot and an internal [[SymbolData]] slot. The Symbol wrapper object (from Object(Symbol())) wraps the primitive.

The global Symbol registry

Symbol.for(key) and Symbol.keyFor(sym) access a global registry that persists across realms (iframes, workers). Regular Symbol() is never in the registry — only Symbol.for() entries are:

const s = Symbol("local");         // not in registry
const g = Symbol.for("global");    // in registry

Symbol.keyFor(s);   // undefined — not registered
Symbol.keyFor(g);   // "global"

// Cross-realm: the same Symbol.for("key") in an iframe and parent window
// returns the same Symbol — they share the global registry

Symbol.toStringTag — customising Object.prototype.toString

class MyCollection {
  get [Symbol.toStringTag]() { return "MyCollection"; }
}

const c = new MyCollection();
console.log(Object.prototype.toString.call(c)); // "[object MyCollection]"
// This is how built-ins work:
// Map:  [object Map], Set: [object Set], Promise: [object Promise]
// Used for reliable type detection across realms

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.