JavaScript Symbol

Symbol uniqueness, the Symbol.for registry, and why symbol keys are hidden from Object.keys and JSON but are not private.

模块页正文目前为英文。

Symbol is an ECMAScript primitive used as a unique property key. It is not a string, and it is not an access-control or privacy mechanism. Code that can reach the object can still list or read symbol keys with the ordinary reflection APIs.

Well-known symbols such as Symbol.iterator are covered on the iterators and generators page. Object.keys and JSON.stringify omit symbol keys; those pages stay the place for key order and JSON exceptions.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
Symbol, Symbol.for, and Symbol.keyForSymbol() always creates a new unique symbol. Symbol.for looks up or creates a registry symbol. Symbol.keyFor returns the registry key, or undefined.
Object.getOwnPropertySymbols and Reflect.ownKeysObject.keys and JSON.stringify omit symbol keys, but getOwnPropertySymbols and Reflect.ownKeys can still list them.

Symbol() and Symbol.for

Symbol(description) creates a new unique symbol every time, even when the optional description string is the same. The description is for debugging; it does not make two symbols equal.

Symbol.for(key) returns a symbol from a global registry, creating it if needed. Symbol.keyFor(sym) returns that registry key, or undefined for a symbol that was not created with Symbol.for.

Symbol, Symbol.for, and Symbol.keyFor

Symbol(description)
Symbol.for(key)
Symbol.keyFor(sym)

Symbol() always creates a new unique symbol. Symbol.for looks up or creates a registry symbol. Symbol.keyFor returns the registry key, or undefined.

ParameterDescription
descriptionOptional string used in the symbol’s toString result. It is not an identity key.
keyThe registry string for Symbol.for and Symbol.keyFor.

Returns: Symbol() and Symbol.for return a symbol. Symbol.keyFor returns a string or undefined.

  • typeof a symbol is "symbol".
  • Symbol("id") === Symbol("id") is false. Symbol.for("id") === Symbol.for("id") is true.
javascript
const a = Symbol("id");
const b = Symbol("id");
console.log(a === b, typeof a, a.toString());
const shared = Symbol.for("id");
console.log(shared === Symbol.for("id"), Symbol.keyFor(shared), Symbol.keyFor(a));

Expected output

false symbol Symbol(id)
true id undefined

Related: Symbol keys are not private, Official Symbol.for

MDN documentation →

Symbol keys are discoverable

A property whose key is a symbol is skipped by Object.keys, Object.values, for…in, and JSON.stringify. That hiding is not privacy. Object.getOwnPropertySymbols and Reflect.ownKeys still list the symbol, and anyone who has the symbol value can read the property.

Do not store secrets behind a symbol key and expect the value to be hidden from later inspection.

Object.getOwnPropertySymbols and Reflect.ownKeys

Object.getOwnPropertySymbols(object)
Reflect.ownKeys(object)

Object.keys and JSON.stringify omit symbol keys, but getOwnPropertySymbols and Reflect.ownKeys can still list them.

ParameterDescription
objectThe object to inspect. Inherited keys are not included.

Returns: getOwnPropertySymbols returns an array of own symbol keys. Reflect.ownKeys returns string and symbol keys together.

javascript
const id = Symbol("id");
const obj = { visible: 1 };
obj[id] = 2;
console.log(Object.keys(obj).join(","), JSON.stringify(obj));
console.log(obj[id], Object.getOwnPropertySymbols(obj).map((s) => s.toString()).join(","));
console.log(Reflect.ownKeys(obj).map((k) => (typeof k === "symbol" ? k.toString() : k)).join(","));

Expected output

visible {"visible":1}
2 Symbol(id)
visible,Symbol(id)

Related: Object.keys, JSON.stringify, Reflect.ownKeys, Symbol.iterator

MDN documentation →