Symbols and Well-Known Symbols

## What a symbol actually is A *symbol* is a primitive value, sitting alongside string, number, boolean, `null`, `undefined` and bigint in the language's set of primitives. You create one by calling the global `Symbol` function, optionally passing a **description** — a human-readable label used only for debugging. ```js const a = Symbol('id'); const b = Symbol('id'); a === b; // false — every call makes a new value typeof a; // 'symbol' a.description; // 'id' (ES2019 accessor) a.toString(); // 'Symbol(id)' ``` The description plays no role in equality. Two symbols are the same value only when they are literally the same symbol — the one produced by one particular call. That is the whole point: a symbol is a value you can hand out, and nobody can forge another one that compares equal to it. ## Symbol is a function, not a constructor ```js new Symbol('id'); // TypeError: Symbol is not a constructor ``` The spec deliberately blocks `new` here. Wrapper objects around primitives are already a source of confusion, and a `Symbol` object that is truthy but not `===` to the primitive it wraps would be worse. If you ever genuinely need the wrapper (rarely), `Object(sym)` produces it. ## Why a unique key is useful Property keys in JavaScript are strings or symbols — nothing else. (A number key like `obj[1]` is converted to the string `'1'`.) With string keys, any two pieces of code that pick the same name write to the same slot: ```js // library A obj.id = 42; // library B, later, in the same object obj.id = 'user-7'; // silently clobbers A ``` With a symbol, each library holds its own key and neither can see or overwrite the other's: ```js const ID = Symbol('id'); // module-private value let counter = 0; export function tag(obj) { obj[ID] = ++counter; } export function idOf(obj) { return obj[ID]; } ``` This is the everyday use: annotating objects you do not own — DOM-free plain objects passed through a framework, instances from a third-party class, an options bag threaded through several layers — without adding a name anyone else might also pick. ## Syntax: symbol keys are always computed Because the key is a *value*, not an identifier, you cannot write `obj.ID`. Every use goes through brackets, including in object literals and class bodies: ```js const ID = Symbol('id'); const user = { [ID]: 1, name: 'Ada' }; user[ID]; // 1 user.ID; // undefined — this is the string key 'ID' class Repo { [ID]() { return 'method with a symbol key'; } } ``` That also means you must keep the symbol itself around. A symbol you created and then dropped on the floor makes its property effectively unreachable — which is occasionally a feature and more often a bug. ## Hidden from enumeration, but not private Symbol-keyed properties are skipped by `for...in`, `Object.keys`, `Object.values`, `Object.entries`, `Object.getOwnPropertyNames` and `JSON.stringify`. That keeps your annotation out of everybody's loops and serialised payloads. It is *not* an access-control mechanism: `Object.getOwnPropertySymbols(obj)` returns the symbol keys, and `Reflect.ownKeys(obj)` returns strings and symbols together. Anyone with a reference to the object can enumerate and read them. ```js const s = Symbol('secret'); const o = { [s]: 'value', open: 1 }; Object.keys(o); // ['open'] JSON.stringify(o); // '{"open":1}' Object.getOwnPropertySymbols(o); // [ Symbol(secret) ] ``` If you want a member outsiders genuinely cannot reach, symbols are the wrong tool; they solve *collision*, not *confidentiality*. ## Two flavours beyond plain Symbol() The language adds two structured sources of symbols on top of anonymous `Symbol()` values. `Symbol.for(key)` looks a symbol up in a process-wide registry, returning the same symbol for the same string every time — the opposite of uniqueness, chosen when two independent copies of code must agree on one key. And the *well-known symbols* — `Symbol.iterator`, `Symbol.asyncIterator`, `Symbol.toPrimitive`, `Symbol.toStringTag`, `Symbol.hasInstance`, `Symbol.species` and a handful more — are fixed symbols the specification itself looks up on your objects, so that defining one lets your type plug into a built-in operation. ## Cost and gotchas Symbols are cheap; they are ordinary primitive values. The practical gotchas are: they vanish from JSON, so anything you need to survive serialisation must live under a string key; they cannot be implicitly concatenated into a string (`'x' + sym` throws); and `Object.assign` and object spread *do* copy own enumerable symbol keys, so a symbol annotation survives a shallow clone even though it disappeared from `Object.keys`.