> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript 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`.
```javascript theme={"dark"}
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.
```javascript theme={"dark"}
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.
```javascript theme={"dark"}
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.
```javascript theme={"dark"}
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()`.
```javascript theme={"dark"}
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()`.
```javascript theme={"dark"}
const customIterable = {
*[Symbol.iterator]() {
yield 1;
yield 2;
}
};
console.log([...customIterable]); // [1, 2]
```
Tired of Poor JavaScript Skills? Fix That With Deep Grasping!
Learn More
