Symbols inside the engine

Every symbol is one of a kind

A symbol is a JavaScript value that is one of a kind. You make one with Symbol(). Each call gives you a new symbol. It is not equal to any other symbol.

You can give a symbol a description. It is a short text label, like "id" in Symbol("id"). The label helps people when they print the symbol. It does not change which symbol it is.

In your code, a symbol is a primitive: a simple value, like a number or a string. Inside the engine it looks different. The engine is the program that runs your JavaScript. This lesson uses V8, the engine inside Chrome and Node. V8 keeps each symbol as a small object in the heap, the memory area where the engine keeps objects. To check if two symbols are equal, V8 asks one question: are they the same object, at the same place in memory?

1const first = Symbol("id");2const second = Symbol("id");3console.log(first === second);4console.log(String(first));

Lines 1 and 2 make two symbols with the same label, "id". Line 3 prints false, because they are two different symbols. Line 4 prints Symbol(id). String(symbol) turns a symbol into text when you ask for it by name, so this line is allowed.

To learn how symbols work in everyday code, read Symbols and Well-known symbols first. This lesson looks only inside V8. Its facts come from:

• the V8 12.4.254.21 source code,
• the ECMAScript spec, the official rules of JavaScript,
• small test programs run in Node,
• a post on the V8 blog about class fields.

What V8 stores inside a symbol

V8 is written in C++. It declares its symbol type as class Symbol : public Name in src/objects/name.h. Name is V8's type for anything that can name a property: a string or a symbol. A Name already has a place for the hash. The Symbol class adds two more fields:

• flags_: a set of yes-or-no switches, packed into one number.
• description_: the label. A comment in the code says String|Undefined, so it holds a string or undefined.

Each row below is one flag. Read across to see what V8 uses it for.

V8 makes a new symbol in Factory::NewSymbolInternal, in src/heap/factory.cc. It does four things:

1. It sets aside memory for the symbol, with symbol_map as its map. That map is read-only: it never changes.
2. It calls GenerateIdentityHash to pick a random number, and stores it as the symbol's hash.
3. It sets the description to undefined for now.
4. It turns all the flags off.

The heap is split into areas. New objects usually go into young space, which the engine cleans often. Objects that live a long time move to old space. factory.h says that symbols made while your program runs go straight to old space (AllocationType::kOld). The factory does not allow young space for symbols at all. That is why Node's debug print says in OldSpace.

To see this yourself, you need Node and a special flag. Running node --allow-natives-syntax turns on V8's private helper functions. Their names start with %. %DebugPrint(value) prints what V8 knows about a value. These helpers only work in Node with that flag, so this code can't run in the browser.

1// Node-only: run with --allow-natives-syntax.2function print(label, value) {3  process.stdout.write("@@" + label + "\n");4  %DebugPrint(value);5}6 7const first = Symbol("id");8const second = Symbol("id");9print("first", first);10print("second", second);11print("empty", Symbol());12print("registered", Symbol.for("app.id"));

Lines 7 and 8 make two symbols with the same label. Lines 9 to 12 print four symbols: those two, one with no label, and one from Symbol.for. Each print shows the symbol's map, hash, flags, and description.

The shared registry: Symbol.for

Symbol.for(key) is a second way to get a symbol. It does not always make a new one. First it looks in the global symbol registry. The registry is one shared list of symbols, each stored under a text key.

• If the key is in the list, you get the symbol that is already there.
• If the key is not in the list, V8 makes a new symbol and adds it.

Inside V8, the steps are:

1. builtins-symbol.cc calls isolate->SymbolFor(RootIndex::kPublicSymbolTable, key, false). An isolate is one running copy of V8, with its own heap.
2. Isolate::SymbolFor internalizes the key. That means it swaps the key for V8's one shared copy of that string.
3. It looks the key up in a RegisteredSymbolTable. This lookup table is declared in hash-table.h.
4. If the key is missing, it makes a new symbol and adds it to the table.
5. The symbol in the table has its is_in_public_symbol_table flag on.

The next code uses Node's vm module. It runs code in a new realm: a fresh set of built-in objects and global variables, like a second web page. It also uses Symbol.keyFor(symbol), which gives back the key a symbol is stored under in the registry.

1// Node only: the vm module makes a new realm.2import vm from "node:vm";3console.log(vm.runInNewContext('Symbol.for("app.id")') === Symbol.for("app.id"));4console.log(vm.runInNewContext("Symbol.iterator") === Symbol.iterator);5console.log(Symbol.keyFor(Symbol.for("app.id")));6console.log(Symbol.keyFor(Symbol("app.id")));

Line 3 prints true. The new realm gets the same Symbol.for("app.id") from the registry. Line 4 prints true too. Both realms get the same Symbol.iterator, which V8 keeps in read-only memory (more on that in the next section). The ECMAScript well-known symbols section says these built-in symbols are shared by all realms.

Line 5 prints app.id, the registry key. Line 6 prints undefined, because Symbol("app.id") was never put in the registry.

A WeakMap is a map that holds its keys weakly. If nothing else in the program uses a key, the engine may free that key and drop its entry. The spec's CanBeHeldWeakly step decides which values can be weak keys:

• Objects can.
• Symbols can, but only if they are not in the registry.

Any code can get a registry symbol back with Symbol.for, at any time. So a WeakMap entry for it could never safely be dropped. That is why a symbol from Symbol() and Symbol.iterator work as weak keys, but a symbol from Symbol.for throws.

1for (const value of [Symbol("local"), Symbol.iterator, Symbol.for("shared")]) {2  try {3    new WeakMap().set(value, "stored");4    console.log(String(value), "accepted");5  } catch (error) {6    console.log(String(value), error.name + ": " + error.message);7  }8}

Line 1 loops over three symbols. Line 3 tries to store each one as a WeakMap key. The first two print accepted. The registry symbol jumps to the catch block on line 5, and line 6 prints TypeError: Invalid value used as weak map key.

Built-in symbols live in read-only memory

Well-known symbols are the built-in symbols stored on Symbol, such as Symbol.iterator and Symbol.toPrimitive. JavaScript uses them as hooks: special keys that let an object change how a language feature treats it. For example, an object with a Symbol.iterator method works in a for...of loop.

V8 makes these symbols when it sets up the heap, before your code runs. setup-heap-internal.cc makes them with AllocationType::kReadOnly. So they go into read-only space: memory that never changes after setup. V8's own private and public symbols are made there too.

The lists of these symbols are in heap-symbols.h. They are part of V8's read-only roots, listed in roots.h. A root is a value V8 can always find straight away, by its number. Because these values never change, V8 can build them once and share them with every new realm. This is the snapshot idea from Startup performance.

1// Node-only: run with --allow-natives-syntax.2function print(label, value) {3  process.stdout.write("@@" + label + "\n");4  %DebugPrint(value);5}6 7for (const name of [8  "iterator",9  "hasInstance",10  "isConcatSpreadable",11  "toPrimitive",12  "toStringTag",13]) {14  print(name, Symbol[name]);15}

Lines 7 to 13 print five built-in symbols. Every one of them prints in ReadOnlySpace. Now be careful: two different things are called "well-known".

• In the ECMAScript spec, every built-in Symbol.* value is a well-known symbol.
• In V8, is_well_known_symbol is a flag that V8 uses for one internal check. It is on for only a few symbols.

In Node 22 (V8 12.4), the print shows the flag on for Symbol.hasInstance, Symbol.isConcatSpreadable, and Symbol.toStringTag. It is off (0) for Symbol.iterator and Symbol.toPrimitive. Symbol.toPrimitive is still read-only. It has a different flag on, which you will meet in the next section.

V8 also has private symbols of its own. Your code can never get hold of them. The next probe shows one. Every object in V8 has a map that describes its shape. When an empty array gets a decimal number like 1.5, V8 moves the array to a new map. This move is called a transition, and V8 saves it under a key.

1// Node-only: run with --allow-natives-syntax.2const array = [];3array.push(1.5);4%DebugPrint(array);

Lines 2 and 3 make an array and push 1.5 into it. The print shows a transition saved under the key <Symbol: (elements_transition_symbol)>. That key is one of V8's own private symbols. It is not a property your program can see or use.

Interesting symbols and a lookup shortcut

Some features must check if an object has a hook. For example, JSON.stringify checks each object for a toJSON method. Checking takes time, and most objects have no hook. So V8 keeps a shortcut.

V8 marks a few names as interesting:

• the symbols Symbol.toPrimitive and Symbol.toStringTag. They get the is_interesting_symbol flag when V8 sets up the heap.
• the strings toJSON and get. Name::IsInteresting counts them as interesting too.

When an object gets a property with an interesting name, V8 turns on a flag called may_have_interesting_properties. It means "this object might have a hook, so check it". V8 puts the flag on the object's map. Some objects keep their properties in a dictionary instead, a slower lookup table; then the flag goes on the dictionary. The code that sets it is in map-inl.h and js-objects.cc.

1// Node-only: run with --allow-natives-syntax.2function print(label, value) {3  process.stdout.write("@@" + label + "\n");4  %DebugPrint(value);5}6 7print("plain", {});8print("toPrimitive", { [Symbol.toPrimitive]() { return 7; } });9print("toStringTag", { [Symbol.toStringTag]: "Tagged" });

Line 7 prints a plain object. Its map does not have the flag. Lines 8 and 9 print objects with a Symbol.toPrimitive method and a Symbol.toStringTag property. Both maps show may_have_interesting_properties.

The note below sums up where V8 sets the flag and where it reads it.

1V8 12.4 source model:2Name::IsInteresting() is true for symbols whose is_interesting_symbol bit is set,3and also for the strings "toJSON" and "get". Map::AppendDescriptor and dictionary4insertion copy that fact into may_have_interesting_properties. JSON.stringify walks5the receiver and prototypes with MayHaveInterestingProperties() before it pays for6the toJSON lookup.

The check is in json-stringifier.cc. MayHaveInterestingProperties looks at the map of the object and of each prototype, the objects it inherits from. If none of them has the flag, JSON.stringify skips the search for toJSON.

Turning an object into a primitive works differently. JSReceiver::ToPrimitive in js-objects.cc still calls Object::GetMethod to look for Symbol.toPrimitive.

Symbol.toPrimitive lets an object choose its own primitive value. JavaScript passes the method a hint: the kind of value it wants. +obj passes "number". A template string such as `${obj}` passes "string". The replay below walks through both. Its notes come from reading the V8 source. It is not a live recording from inside the engine.

1const plain = {Run2  valueOf() {3    return 10;4  },5};6const protocol = {7  [Symbol.toPrimitive](hint) {8    return hint === "string" ? "tagged" : 7;9  },10};11console.log(+plain);12console.log(+protocol);13console.log(`${protocol}`);

Private fields use hidden symbols

A private field is a class field whose name starts with #, like #x. Only code inside the class can read it. The V8 blog post Faster initialization of instances with new class features says V8 stores private fields under private symbols. These are hidden symbols that your code can never get. V8 stores the field like any other property, but it never shows up as a normal property.

The same post explains how V8 sets up these fields fast. Adding a field moves the object to a new map. V8 remembers the private symbol together with that map change, so the next object of the class can be set up quicker.

1// Node-only: run with --allow-natives-syntax.2class FieldBox {3  #x = 1;4  read() { return this.#x; }5}6class MethodBox {7  #m() { return 1; }8  call() { return this.#m(); }9}10%DebugPrint(new FieldBox());11%DebugPrint(new MethodBox());

Line 10 prints a FieldBox, which has the private field #x (line 2). The print shows a property stored inside the object, under the key <Symbol: #x>.

Line 11 prints a MethodBox, which has the private method #m (line 7). A class with private methods puts a hidden brand on each object it makes. A brand is a mark that says "this class made this object". The print shows the brand as <Symbol: MethodBox>. Its value is V8's record for the class. V8's Runtime_AddPrivateBrand stores the brand as an own property that can't be listed, deleted, or changed.

The next code uses three tools. Each one is explained here:

• Reflection means code that lists an object's own keys. Reflect.ownKeys lists all of them. Object.getOwnPropertySymbols lists only the symbol keys.
• #x in value is a brand check. It asks: does value have the #x field?
• A proxy, made with new Proxy(target, {}), is a wrapper object. It passes most actions on to the target object.

1class FieldBox {2  #x = 1;3  read() { return this.#x; }4  static hasBrand(value) { return #x in value; }5}6const box = new FieldBox();7console.log(Reflect.ownKeys(box).length);8console.log(Object.getOwnPropertySymbols(box).length);9console.log(FieldBox.hasBrand(box));10console.log(FieldBox.hasBrand(new Proxy(box, {})));11try {12  box.read.call(new Proxy(box, {}));13} catch (error) {14  console.log(error.name + ": " + error.message);15}16try {17  FieldBox.hasBrand(null);18} catch (error) {19  console.log(error.name + ": " + error.message);20}

• Lines 7 and 8 print 0 and 0. Neither tool can see #x.
• Line 9 prints true. The brand check finds #x on box.
• Line 10 prints false. The proxy is a different object, and it does not have #x.
• Line 12 calls read() with the proxy as this. Reading this.#x throws a TypeError.
• Line 17 checks #x in null. It throws, because null is not an object.

Symbols as property keys

A property key is the name of a property. V8 keeps property names as Name values. It stores them in two places:

• descriptor arrays: the list of property names that belongs to a map,
• property dictionaries: the slower lookup tables some objects use.

Name covers both strings and symbols. So a symbol can be a key just as it is. It is never turned into a string. The spec's OrdinaryOwnPropertyKeys step sets the order of an object's own keys:

1. whole-number keys, like 1 and 2, smallest first,
2. other string keys, in the order they were added,
3. symbol keys, in the order they were added.

1const secret = Symbol("secret");Run2const record = { 2: "two", a: "letter", [secret]: "hidden", 1: "one" };3console.log(Object.keys(record).join("|"));4console.log(Object.getOwnPropertySymbols(record).map(String).join("|"));5console.log(Reflect.ownKeys(record).map(String).join("|"));6console.log(JSON.stringify(record));

Object.keys, for...in, and JSON.stringify all skip symbol keys. To list only the symbol keys, use Object.getOwnPropertySymbols. To list every key, strings and symbols, use Reflect.ownKeys.

Build and test a symbol

Type a label and pick how to make the symbol: Symbol() or Symbol.for(). The code then does four things with it:

• compares it with a second symbol made the same way,
• uses it as a property key,
• tries it as a WeakMap key,
• turns it into text in two ways.

The list of V8 flags under the results is a summary of what the Node debug prints show. It is not read live from V8.

1const made = Symbol("app.id");2const twin = Symbol("app.id");3console.log(made === twin);4const bag = { [made]: "value" };5console.log(bag[made]);6try {7  new WeakMap().set(made, "stored");8  console.log("weak key accepted");9} catch (error) {10  console.log(error.name + ": " + error.message);11}12try {13  console.log("" + made);14} catch (error) {15  console.log(error.name + ": " + error.message);16}17console.log(String(made));

Practical use

Symbols help when you need a key that can't clash with other keys, or a hook into a language feature. Pick the kind that fits:

• Use Symbol() for a library's own data on other people's objects.
• Use Symbol.for() only when separate pieces of code must find the same symbol by a shared text key.
• Use a well-known symbol, like Symbol.iterator, when you want your object to work with a language feature, such as for...of.

Keep these tips in mind:

• A symbol key from Symbol() can't clash with string keys that users of your code add.
• Don't use the label to tell symbols apart. Two symbols with the same label are still different.
• For data that must stay truly private, use private fields (#x). Ordinary symbol keys can still be listed with Reflect.ownKeys.
• Don't guess that a symbol hook is slow. Measure first. V8 has the interesting-symbol flag so that objects without a hook stay fast.

Common misconceptions

• "The label decides which symbol it is." No. The label is only text. Two symbols are equal only if they are the very same symbol.
• "Every Symbol.* value has V8's well-known flag." No. V8's is_well_known_symbol flag is for one internal check, and only a few symbols have it.
• "Symbol keys are invisible." No. Object.keys and for...in skip them, but Reflect.ownKeys lists them.
• "Registry symbols make good WeakMap keys." No. The spec does not allow symbols from Symbol.for as weak keys.
• "Private fields are just normal symbols." No. V8 uses hidden symbols for them, but reflection and square brackets can't reach them.

Each row below is one kind of symbol. Read across to see where V8 keeps it and what you can do with it.

Key takeaways

• In V8, a symbol is a small object in the heap. Two symbols are equal only if they are the same object. The label does not decide it.
• A symbol made while your program runs goes straight to old space, and it gets a random hash when it is made.
• Symbol.for uses V8's shared registry. Symbols from the registry can't be WeakMap keys.
• Built-in symbols live in read-only memory. V8's is_well_known_symbol flag is on for only a few of them.
• Private fields and private methods use hidden symbols. Reflection can't list them.

Up next: Hidden classes & object shapes. There, the maps, descriptor arrays, and transitions you met here become the main story.