JavaScript: Symbol Tutorial
New in JS2015.
- Symbol is a Primitive Value.
- Symbol is one of the allowed type for a object's Property Key.
- The purpose of symbol is to avoid property name collision.
- Each symbol value is unique and immutable.
- Each symbol value has an associated value called “Description”, usually denoted in document as [[Description]]. Its value is either
undefined
or a string. This [[Description]] cannot be changed once created.
Create Symbol
Symbol()
- Return a symbol.
Symbol(description)
- Return a symbol with description string description.
The description is a printed representation of the symbol, mostly for debugging purposes. The description is used when you convert symbol to string. Note: 2 symbols with same description are still different symbols.
// creating symbol let x = Symbol(); let y = Symbol(); let z = Symbol("my cat"); console.log(x); // prints Symbol() console.log(y); // prints Symbol() console.log(z); // prints Symbol(my cat)
[see const Declaration]
「Symbol()」 Cannot be Used with 「new」
Symbol()
cannot be used with new
.
new Symbol(); // TypeError: Symbol is not a constructor
Symbol() Return a Unique Symbol, Always
// Symbol() always returns a unique symbol console.log( Symbol() === Symbol() ); // false
typeof Symbol
typeof
on symbol value returns string "symbol"
.
[see Value Types]
console.log( typeof Symbol() === "symbol" ); // true console.log( typeof Symbol("abc") === "symbol" ); // true
Using Symbol as Property Key
Before JS2015, property key can only be string type. In JS2015, property key can be either a string type or symbol type.
- Property key that is string is called “property name”
- Property key that is symbol is called “property symbol”
The symbol value is designed to be keys for properties. Because symbol values are unique, this means property key collision cannot happen. This lets you add properties to any object of any libraries and don't have to worry about property key collision.
Use Bracket Notation to Access Symbol Property
Use bracket notation to access property symbol. Like this:
obj[symbol]
obj[variable_of_symbol]
Note: you cannot use dot notation for property keys that are symbol. [see Property Dot Notation / Bracket Notation]
// adding a symbol key property const x = Symbol(); const obj = {}; obj[x] = 3; console.log( obj[x] === 3 ); // true
// adding a symbol key property, via symbol value directly const obj = {}; obj[Symbol()] = 4; console.log( obj[Object.getOwnPropertySymbols(obj)[0]] === 4 ); // true
Symbol Property in Object Literal Expression
You can use symbol property key in object literal expression (New in JS2015.), like this:
const obj = {[symbol]:value}
[see ES2015 Object Literal Expression Extensions]
// use of symbol key in object literal expression const obj = {[Symbol()]:3}; console.log( obj ); // { [Symbol()]: 3 };
Symbol Properties Are Usually Ignored
Symbol properties are usually ignored by constructs that access properties.
- for-in Loop ignore symbol key properties.
- for-of Loop usually ignore symbol key properties.
Object.getOwnPropertyNames(obj)
ignores symbol key properties.Object.keys(obj)
ignores symbol key properties.
console.log(obj)
may or may not print symbol properties of obj.
[see List Properties]
const obj = {[Symbol()]:4}; console.log( obj[(Object.getOwnPropertySymbols ( obj ))[0]] === 4 ); // true // exists // symbol key properties are ignored by many constructs console.log(Object.keys(obj)); // [] console.log(Object.getOwnPropertyNames(obj)); // [] for (let p in obj) { console.log("yes"); } // prints nothing
Check Symbol Property Existence
List Symbol Keys
Convert Symbol to String
To convert symbol to string, do
sym.toString()
Note:
"some " + symbol
results TypeError.
you must use
"some " + symbol.toString()
const ss = Symbol("cat"); console.log( ss.toString() === "Symbol(cat)"); // true console.log( "my " + ss.toString() === "my Symbol(cat)"); // true // console.log( "my " + ss); // TypeError: Cannot convert a Symbol value to a string