Symbols

1What a Symbol Is

Symbol is a primitive type introduced in ES6 whose only purpose is to be a guaranteed-unique value, typically used as an object property key that will never accidentally collide with any other key — including keys from other libraries.

const s1 = Symbol("id");
const s2 = Symbol("id");
console.log(s1 === s2); // false — every Symbol() call creates a distinct value, even with the same description

The string passed to Symbol() is just a description for debugging — it has no effect on uniqueness or equality.

2Symbols as Object Keys

const ID = Symbol("id");

const user = {
  name: "Ana",
  [ID]: 12345, // computed key — stores under the Symbol, not the string "id"
};

console.log(user[ID]);      // 12345
console.log(user["ID"]);    // undefined — a string key "ID" is unrelated to the Symbol ID
console.log(Object.keys(user)); // ["name"] — Symbol keys are excluded by default

3Symbols Are Hidden from Normal Enumeration

This makes Symbols useful for attaching metadata to an object without it showing up in normal iteration, serialization, or accidentally colliding with a user-supplied property name.

4Well-Known Symbols

JavaScript itself uses Symbols to let objects hook into language-level behavior:

class Range {
  constructor(start, end) { this.start = start; this.end = end; }
  [Symbol.iterator]() { /* makes this object work with for...of, see Iterators topic */ }
}

class Money {
  constructor(amount) { this.amount = amount; }
  [Symbol.toPrimitive](hint) {
    if (hint === "number") return this.amount;
    if (hint === "string") return `$${this.amount.toFixed(2)}`;
    return `Money(${this.amount})`;
  }
}
const price = new Money(9.5);
console.log(+price);         // 9.5 — hint "number"
console.log(`${price}`);     // "$9.50" — hint "string"

Symbol.iterator, Symbol.toPrimitive, Symbol.hasInstance, and Symbol.toStringTag are all "well-known symbols" that customize built-in language operations for your own classes.

5Symbol.for() — the Global Symbol Registry

const a = Symbol.for("shared-key");
const b = Symbol.for("shared-key");
console.log(a === b); // true — Symbol.for reuses the SAME symbol for the same string, across the entire runtime

Unlike Symbol("x") (always unique), Symbol.for("x") looks up (or creates) a shared Symbol in a global registry — useful when multiple, independently-loaded modules need to agree on the same Symbol key.

6Symbols Are Not Enumerable by JSON

const obj = { name: "Ana", [Symbol("secret")]: "hidden" };
console.log(JSON.stringify(obj)); // {"name":"Ana"} — Symbol-keyed data is silently dropped

This is a deliberate design choice: Symbols are meant for in-memory metadata, not serialized data.

console.log(typeof Array.prototype[Symbol.iterator]); // "function"

Symbol.for("app:id"); // first call: registry has no entry for "app:id" -> creates one, stores it, returns it
Symbol.for("app:id"); // second call, ANY module, ANY time later: registry already has it -> returns the SAME symbol

⚠️ Common Pitfalls

1. Expecting Symbol("x") === Symbol("x") — they are always different values; only Symbol.for("x") provides equality across calls.
2. Trying to use new Symbol() — throws a TypeError; Symbol is a function, not a constructor, and must be called without new.
3. Assuming Symbol-keyed properties are truly private — Object.getOwnPropertySymbols() can still retrieve them; use #private class fields (see the Classes topic) for genuine access-restricted privacy.
4. Forgetting JSON.stringify drops Symbol keys entirely — a common surprise when debugging "missing" data after serialization.

📋 Quick Reference

Symbol("desc")        → always unique, even with the same description
Symbol.for("key")      → shared/global, same value for the same key
obj[sym] = value        → hidden from Object.keys/for-in/JSON.stringify
Symbol.iterator          → well-known symbol powering for...of

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

Source: js_symbols_theory.md · generated by tools/build_lessons.py