Tagged values, Smis & heap numbers

One word, many values

In JavaScript, 42, 1.5, and NaN all have the same type: number. You never choose how a number is stored. The engine does. The engine is the program that runs your JavaScript. Chrome and Node use one called V8. Firefox uses SpiderMonkey. Safari uses JavaScriptCore.

The engine has to store every value somewhere in memory. Here are the words you need:

• A bit is a single 0 or 1.
• A word is a fixed group of bits that the computer handles in one go. On most computers today, a word is 64 bits.
• The heap is the large area of memory where the engine keeps objects.
• An address (also called a pointer) is a number that says where something sits in memory.

A representation is the way the engine stores one value in those bits. The same JavaScript number can be stored in more than one way. You can't see the difference from your code.

This lesson comes after on-stack replacement in the engine track. How numbers behave in JavaScript (rounding, safe whole numbers, and so on) is covered in Numbers and Numbers in depth. This lesson is only about storage. You will meet these ideas in order:

• tag bits at the end of a word;
• Smis, small whole numbers stored right in the word;
• HeapNumbers, numbers stored in a box on the heap;
• NaN-boxing, the way Firefox and Safari pack values;
• number fields that the engine updates in place;
• why whole numbers can be faster than numbers with a decimal point.

Pointer tagging: use the last bit as a label

The engine places every heap object at an address that is a multiple of 4 or 8. This is called alignment. In binary, a multiple of 4 or 8 always ends in 0. So the last bit of a real address is always 0, and it carries no information.

Pointer tagging uses that spare last bit as a label. In V8, the simple version of the rule is:

• last bit 0: the rest of the word is a small whole number;
• last bit 1: the rest of the word is an address of an object on the heap.

Real engines add more details, but this one rule is the picture to keep in mind. The code below is a model of it. It doesn't look at real memory. It applies the same rule in plain JavaScript:

• Number.isInteger(value) checks that the value is a whole number.
• 2 ** 31 means 2 to the power of 31, which is 2147483648.
• Object.is(value, -0) checks for negative zero, -0. JavaScript has both 0 and -0, and Object.is can tell them apart.

1function teachingTag(value) {2  const isSmi =3    Number.isInteger(value) &&4    value >= -(2 ** 31) &&5    value <= 2 ** 31 - 1 &&6    !Object.is(value, -0);7  return isSmi ? "low bit 0: Smi payload" : "low bit 1: pointer to a box";8}9 10console.log(teachingTag(42));11console.log(teachingTag(1.5));12console.log(teachingTag(-0));

Line 2 starts the test for a small whole number. Lines 3 to 5 check that the value is whole and in range. Line 6 turns away -0. Lines 10 to 12 try three values. All three have the type number in JavaScript, but only 42 fits in the word. The other two need a box on the heap.

V8 calls a number that fits in the word a Smi. It calls the box on the heap a HeapNumber. The next two sections explain each one.

In the playground below, type a number and see how each engine model would store it. It uses two tools:

• new ArrayBuffer(8) makes 8 empty bytes (64 bits) of memory.
• new DataView(...) lets you write a number into those bytes and read the raw bits back.

1const input = "42";2const value = Number(input);3const view = new DataView(new ArrayBuffer(8));4view.setFloat64(0, value, false);5 6console.log("double bits", view.getBigUint64(0, false).toString(16));7console.log("Node model", Number.isInteger(value) ? "Smi candidate" : "HeapNumber");

The bits on the first card are real. JavaScript stores every number in a 64-bit format called Float64 (also called a double). Its official name is IEEE-754. The playground shows those bits in hexadecimal, or hex: base 16, where each digit stands for 4 bits. The other cards are models built from the engines' published notes. They are good for thinking, but they don't read your browser's memory.

Small whole numbers: Smis

Smi is short for "small integer". An integer is a whole number. V8 keeps a Smi right in the tagged word, so it doesn't need to make a separate box on the heap. Counters, array positions, and lengths are usually Smis. That is why engine teams care so much about them.

How small is "small"? We can check in Node. Node has a special command, %IsSmi(value), that asks V8 directly. It only works when you start Node with the flag --allow-natives-syntax, so you can't run this code in the browser:

1console.log("node", process.version);2console.log("v8", process.versions.v8);3console.log("pointer compression", process.config.variables.v8_enable_pointer_compression);4console.log("sandbox", process.config.variables.v8_enable_sandbox);5console.log("max smi", %IsSmi(2 ** 31 - 1));6console.log("overflow", %IsSmi(2 ** 31));7console.log("min smi", %IsSmi(-(2 ** 31)));8console.log("underflow", %IsSmi(-(2 ** 31) - 1));9console.log("minus zero", %IsSmi(-0));10console.log("double", %IsSmi(1.5));

Chrome is different. Chrome uses pointer compression: it stores addresses in 32 bits instead of 64, to save memory. That leaves 31 bits for a Smi. So in 64-bit Chrome, Smis go from -(2 ** 30) to 2 ** 30 - 1. That is about one billion either way. The Node build tested here has a bigger range, about two billion either way. You can read more in The heap & pointer compression.

The code below makes the same Smi decision as the Node test, using only normal JavaScript. You can run it in the browser:

1function nodeSmiKind(value) {2  const min = -(2 ** 31);3  const max = 2 ** 31 - 1;4  return Number.isInteger(value) &&5    value >= min &&6    value <= max &&7    !Object.is(value, -0)8    ? "Smi"9    : "HeapNumber";10}11 12console.log(nodeSmiKind(2 ** 31 - 1));13console.log(nodeSmiKind(2 ** 31));14console.log(nodeSmiKind(-0));15console.log(nodeSmiKind(1.5));

Lines 2 and 3 set the smallest and largest Smi. Line 7 turns away -0. Lines 12 to 15 try four values. Only the first one, 2 ** 31 - 1, is a Smi.

Now watch one variable grow past the largest Smi. Step through it:

1function nodeSmiKind(value) {2  return Number.isInteger(value) &&3    value >= -(2 ** 31) &&4    value <= 2 ** 31 - 1 &&5    !Object.is(value, -0)6    ? "Smi"7    : "HeapNumber";8}9 10let x = 2 ** 31 - 2;Run11console.log(x, nodeSmiKind(x));12x = x + 1;13console.log(x, nodeSmiKind(x));14x = x + 1;15console.log(x, nodeSmiKind(x));

HeapNumbers and boxing

A HeapNumber is a small object on V8's heap that holds one Float64 number. V8 uses it for every number that can't be a Smi:

• numbers with a decimal point, like 1.5;
• Infinity, -Infinity, and NaN;
• -0;
• whole numbers outside the Smi range.

Boxing means putting a value in a box like this on the heap. The tagged word then holds the box's address instead of the value.

Why can't -0 be a Smi? Look at its bits. The code below writes a number into 8 bytes and prints them in hex:

1function float64Hex(value) {2  const view = new DataView(new ArrayBuffer(8));3  view.setFloat64(0, value, false);4  return "0x" + view.getBigUint64(0, false).toString(16).padStart(16, "0");5}6 7console.log(float64Hex(0.1));8console.log(float64Hex(-0));9console.log(float64Hex(Number.NaN));

Line 3 writes the number into the 8 bytes. Line 7 prints the bits of 0.1. Binary can't write 0.1 exactly, so the bits repeat (the many 9s in the hex) and are rounded at the end. Line 8 prints the bits of -0. Only the first bit, the sign bit, is 1. For +0 every bit is 0. A Smi stores a whole number with no room for that extra sign, so -0 would turn into 0. Line 9 prints the usual bits of NaN.

Node can also show what V8 made for a value. %DebugPrint(value) prints V8's own description. Like %IsSmi, it only works with --allow-natives-syntax:

1%DebugPrint(1.5);2const sample = { x: 1.5 };3%DebugPrint(sample);4sample.x = sample.x + 1;5%DebugPrint(sample);

The table below lists the ways of storing numbers in this lesson. Read each row from left to right: the name, what it holds, and where you meet it.

NaN-boxing in Firefox and Safari

V8 uses a tag bit and HeapNumbers. SpiderMonkey (Firefox) and JavaScriptCore (Safari) use a different trick, called NaN-boxing. It works like this:

• Every value is one 64-bit word.
• A normal Float64 number is stored right in the word, with no box.
• The Float64 format has a huge number of bit patterns that all mean NaN. JavaScript only needs one of them.
• The engine uses the spare NaN patterns for everything else: whole numbers, true, addresses of objects, and so on.

Your code sees exactly the same values in every engine. Only the hidden storage is different. The block below summarizes what the engines' own source code says:

1SpiderMonkey JS::Value source comment (Firefox):2  Any NaN bit pattern means either the real NaN or a value that is not a number.3  In PUNBOX64, the tag sits in five bits near the top of the word.4 5JavaScriptCore JSCJSValue.h source comment (Safari):6  0xFFFE marks 32-bit whole numbers.7  0x0000 marks an address or another simple value.8  Numbers are stored by adding 2^49 to their bits.

In plain words, line by line:

• Line 1 names the file in Firefox's engine.
• Line 2: any NaN bit pattern means either the real NaN or a value that is not a number.
• Line 3: in the 64-bit layout (called PUNBOX64), the tag sits in five bits near the top of the word.
• Line 5 names the file in Safari's engine.
• Line 6: a word that starts with 0xFFFE holds a 32-bit whole number.
• Line 7: a word that starts with 0x0000 holds an address or another simple value.
• Line 8: numbers are stored after adding a fixed amount, 2^49, to their bits.

You can read the original notes in Mozilla's Value.h and WebKit's JSCJSValue.h.

Number fields that change in place

A normal HeapNumber never changes. Two variables might point at the same box holding 4.2. If V8 changed the box, both variables would change, and that would break JavaScript. So when a number changes, V8 makes a new box.

Making a new box every time is slow when an object field changes again and again. So V8 has a shortcut. When a field always holds numbers with a decimal point, V8 can mark it as a double field. It then keeps that field's number in a box that it is allowed to change, called a MutableHeapNumber, and updates the box in place. The V8 team explains this in its blog post about a React slowdown.

Step through the code below. It shows what your code sees:

1const point = { x: 0.1 };Run2 3function nudgeX(object) {4  object.x = object.x + 1;5  return object.x;6}7 8console.log(nudgeX(point));9const saved = point.x;10point.x = point.x + 1;11console.log(saved);12console.log(point.x);

saved keeps the number it read. Changing point.x later does not change it. V8's shortcut is safe only because of one rule: when a number is read out of a double field, V8 copies it into a new normal box. So saved never shares the box that changes.

Where does each fact come from? The %DebugPrint code in the previous section shows the double field as a HeapNumber. The V8 blog gives the name MutableHeapNumber and explains the update in place.

Why whole numbers can be faster

A Smi lives right in the word. So working with Smis can skip some costs:

• The engine doesn't need to make a box on the heap.
• The garbage collector, the part of the engine that clears away boxes nobody uses, has less to clean up.
• The engine can use fast whole-number instructions instead of decimal-point ones.

That doesn't make doubles bad. JavaScript needs them, and they are correct for many values. It just means that busy code full of small whole numbers is cheaper for the engine to run.

1function addOne(value) {2  return value + 1;3}4 5console.log(Number.isInteger(addOne(41)));6console.log(addOne(2 ** 31 - 1));7console.log(addOne(1.5));

Line 1 defines addOne, which adds 1. Line 5 gives 42, a whole number, so it prints true. Line 6 gives 2147483648. That is still a whole number, but it is past the largest Smi in Node, so it needs a HeapNumber. Line 7 gives 2.5, which has a decimal point, so a double is the natural fit. Optimizing compilers make more choices like these. They are covered in What optimizing compilers do.

Practical use: measure first, then keep busy numbers steady

Most of the time, you should not try to make numbers into Smis by hand. The useful habits are small. They matter only for hot code: code that runs very many times, such as a chart animation, a parser, or a big grid. A profiler, like the Performance panel in your browser's developer tools, shows you which code is hot.

• Turn user input into numbers as soon as it arrives. Then busy math always gets numbers, never sometimes strings.
• Don't let -0, NaN, or values like 0.5 slip into counters that should be whole numbers.
• Write clear arrays and objects. Let the engine choose Smi, double, or HeapNumber.
• Profile first. Then try a change with real data and measure again.

Common misconceptions

• "A Smi is a JavaScript type." No. It is one way V8 stores numbers. typeof 1 still says "number".
• "Node and Chrome always have the same Smi range." No. The Node build tested here has pointer compression off. Chrome has it on, so its Smis are smaller.
• "A HeapNumber is the same as new Number(...)." No. A HeapNumber is hidden inside V8. new Number(1.5) makes a normal object that your code can see.
• "NaN-boxing changes how math works." No. It only changes storage. The JavaScript rules still decide every answer.
• "Code with whole numbers is always faster." No. It depends on how often the code runs, what the engine has learned about it, and what you measure.

The table below lists ideas that are easy to mix up. Read each row as: the idea, what it really is, and what it is not.

Key takeaways

• A tagged value is one word with tag bits and a payload. The tag says whether the payload is the value or an address.
• A V8 Smi stores a small whole number right in the word. A HeapNumber stores any other number in a box on the heap.
• The Node 22 build tested here has 32-bit Smis, because pointer compression is off. Chrome has pointer compression on, so it has 31-bit Smis.
• Firefox's and Safari's engines hide other values inside spare NaN bit patterns instead.
• Use this knowledge only after a profiler shows busy number code.

Up next: Booleans inside the engine. There, true and false turn out to be two ready-made objects on the heap that never change. After that come undefined, null, and strings.