null inside the engine

One null, made once

You know null from everyday JavaScript. It is the value you write on purpose to say "empty" or "nothing here". This lesson shows how a JavaScript engine stores it. An engine is the program that runs your code. We use V8, the engine inside Chrome and Node.js. Every fact here was checked in Node 22, which uses V8 version 12.4.

Inside V8, there is exactly one null. V8 makes it once, when it starts, and never makes another one. V8 calls a few special built-in values oddballs, and null is one of them. A variable that holds null only stores a pointer to it. A pointer is a memory address: it says where a value is.

If you want the everyday rules for null first, read null for beginners. This lesson also uses the idea of a tagged pointer: a stored pointer with a small mark that says "this is a pointer, not a small number". The Tagged values, Smis & heap numbers lesson explains it. This lesson comes right after undefined inside the engine.

Where V8 keeps null and its answers

V8 is written in the C++ language, and its source code is public. So we can read how it builds null. The file oddball.h describes oddballs. Its comment says that four values are oddballs: null, undefined, true, and false.

Each oddball keeps a few ready-made answers, so V8 never has to work them out again. V8 calls these saved answers cached fields:

• to_number_raw and to_number: the value as a number.
• to_string: the value as a string.
• type_of: what typeof gives.
• kind: a small number that says which oddball this is. For null, it is kNull = 3.

1// V8 12.4.254.21, src/objects/oddball.h2// The Oddball describes objects null, undefined, true, and false.3// [to_number_raw]: Cached raw to_number computed at startup.4// [to_string]: Cached to_string computed at startup.5// [to_number]: Cached to_number computed at startup.6// [typeof]: Cached type_of computed at startup.7static constexpr uint8_t kNull = 3;8static constexpr uint8_t kUndefined = 4;

Another file, setup-heap-internal.cc, builds null when V8 starts. Here is what the lines below do:

• Line 2 makes a separate map just for null, called null_map.
• Line 4 puts the undetectable mark on that map.
• Lines 5 and 6 fill in the ready-made answers: the string "null", the number zero, the typeof answer "object", and the kind kNull. Smi::zero() is the number 0 as a Smi, V8's name for a small whole number.

1// V8 12.4.254.21, src/heap/setup-heap-internal.cc2ALLOCATE_AND_SET_ROOT(Map, null_map, Map::kSize);3InitializePartialMap(null_map, meta_map, ODDBALL_TYPE, sizeof(Null));4roots.null_map()->set_is_undetectable(true);5Oddball::Initialize(isolate(), factory->null_value(), "null",6                    handle(Smi::zero(), isolate()), "object", Oddball::kNull);

1%DebugPrint(null);

%DebugPrint is a special V8 helper. It prints what V8 stores for a value. It only works when you start Node with node --allow-natives-syntax, so this block can't run on this page. The lesson's test runs it and checks the parts that are the same on every run:

1DebugPrint: ... [Oddball] in ReadOnlySpace: #null2... [Map] in ReadOnlySpace3 - type: ODDBALL_TYPE4 - stable_map5 - undetectable6 - non-extensible7 - prototype: ... <null>

• [Oddball] in ReadOnlySpace: #null: it is the null oddball, kept in read-only space.
• type: ODDBALL_TYPE: the map says its type is oddball.
• undetectable: the map has the undetectable mark.
• prototype: ... <null>: the map's prototype is null itself.

The test skips memory addresses and object sizes, because they change from build to build. This Node build has pointer compression turned off: a trick that stores pointers in fewer bytes. It also has the sandbox turned off: a fence that limits which memory V8 can touch. Chrome usually turns both on and may use a newer V8.

1console.log(Number(null));2console.log(String(null));3console.log(null + 1);4console.log(null >= 0);5console.log(null == 0);

Here is what each line prints:

• Line 1 prints 0: null as a number.
• Line 2 prints null: null as a string.
• Line 3 prints 1. The + turns null into 0 first, and 0 + 1 is 1.
• Line 4 prints true. The >= also turns null into 0, and 0 >= 0 is true.
• Line 5 prints false. Loose equality, ==, has its own rule for null: it is only loosely equal to null and undefined. So null == 0 is false.

Other engines store null in different ways. Read each row of the table as: the engine, how it stores null, and what its source code says.

1JavaScriptCore JSCJSValue.h:2  ValueNull = OtherTag; JSValue(JSNullTag) stores ValueNull.3 4SpiderMonkey js/public/Value.h:5  JSVAL_TYPE_NULL = 0x04; JSVAL_TAG_NULL stores a null payload.6 7V8 12.4 oddball.h:8  Null is an Oddball subclass; kind kNull = 3.

JavaScriptCore is the engine inside Safari. Its file JSCJSValue.h stores null as a fixed value, ValueNull, right inside the value itself. No object in memory is needed. SpiderMonkey is the engine inside Firefox. Its file Value.h gives null the type number JSVAL_TYPE_NULL = 0x04. Every engine gives the same JavaScript results. Only the way it stores null is different.

Why typeof null says "object"

The rules of JavaScript, called the spec, still say that typeof null gives "object". The reason is older than V8. It goes back to the first JavaScript engine, built at Netscape in 1995.

That engine stored every value in one 32-bit word: a number made of 32 bits, where each bit is a 0 or a 1. The last 3 bits were a type tag, a small code that said what kind of value the word held. Axel Rauschmayer's archived 2ality article lists the old tags:

• 000: an object.
• 1 as the last bit: a whole number.
• 010: a decimal number.
• 100: a string.
• 110: a boolean.

null was stored as a word where all 32 bits are 0. The old Netscape source shows this in jsapi.h: JSVAL_OBJECT is 0x0, and JSVAL_NULL is OBJECT_TO_JSVAL(0). In jsapi.c, the old typeof code checks for the object tag, JSVAL_IS_OBJECT, before it checks for numbers, strings, or booleans. All those zeros look like the object tag, so the answer was "object".

1const JSVAL_OBJECT = 0x0;2const JSVAL_INT = 0x1;3const JSVAL_STRING = 0x4;4const JSVAL_BOOLEAN = 0x6;5const JSVAL_VOID = 0xfffffff0;6 7function tagBits(word) {8  return (word & 0x7).toString(2).padStart(3, "0");9}10 11function typeof1995(word) {12  const tag = word & 0x7;13  if (word === JSVAL_VOID) return "undefined";14  if (tag === JSVAL_OBJECT) return "object";15  if (word & JSVAL_INT) return "number";16  if (tag === JSVAL_STRING) return "string";17  if (tag === JSVAL_BOOLEAN) return "boolean";18  return "number";19}20 21const nullWord = 0x00000000;22console.log("null", tagBits(nullWord), typeof1995(nullWord));23console.log("object", tagBits(0x00001000), typeof1995(0x00001000));24console.log("string", tagBits(0x00003004), typeof1995(0x00003004));

This code is a teaching model, not the real 1995 engine. It turns each value into a 32-bit word and reads the last 3 bits. In plain words, line by line:

1. Line 1 sets the object tag to 0.
2. Line 7 starts tagBits. It keeps only the last 3 bits, with word & 0x7, and shows them as 0s and 1s.
3. Line 11 starts typeof1995, the old typeof decision.
4. Line 14 gives "object" when the tag is 000. Nothing checks for null before it.
5. Line 21 makes the word for null: all zeros.
6. Line 22 prints null 000 object.

1const JSVAL_OBJECT = 0x0;2const JSVAL_INT = 0x1;3const JSVAL_STRING = 0x4;4const JSVAL_BOOLEAN = 0x6;5const JSVAL_VOID = 0xfffffff0;6 7function tagBits(word) {8  return (word & 0x7).toString(2).padStart(3, "0");9}10 11function typeof1995(word) {12  const tag = word & 0x7;13  if (word === JSVAL_VOID) return "undefined";14  if (tag === JSVAL_OBJECT) return "object";15  if (word & JSVAL_INT) return "number";16  if (tag === JSVAL_STRING) return "string";17  if (tag === JSVAL_BOOLEAN) return "boolean";18  return "number";19}20 21const nullWord = 0x00000000;Run22console.log("null", tagBits(nullWord), typeof1995(nullWord));23console.log("object", tagBits(0x00001000), typeof1995(0x00001000));24console.log("string", tagBits(0x00003004), typeof1995(0x00003004));

Could the answer be fixed? Brendan Eich, who created JavaScript, suggested a change on the es-discuss mailing list. An old proposal said: "With opt-in to Harmony, typeof null === "null"." Harmony was the working name for the next big version of JavaScript. The proposal is archived at harmony:typeof_null. It was dropped, because changing the answer would break websites that already depend on "object".

The small instructions behind null checks

Before V8 runs a function, it turns the function into bytecode: a list of small, simple instructions. V8's interpreter, called Ignition, then runs those instructions one by one. Each instruction has a short name, such as TestNull.

The lesson's test runs the code below with node --print-bytecode, which prints the bytecode of each function. It checks only the instruction names. It skips their positions, because those can change.

1function strictNull(x) {2  return x === null;3}4 5function looseNull(x) {6  return x == null;7}8 9function objectType(x) {10  return typeof x === "object";11}12 13console.log(strictNull(null));14console.log(looseNull(undefined));15console.log(objectType(null));

1strictNull: Ldar a0; TestNull; Return2looseNull: Ldar a0; TestUndetectable; Return3objectType: Ldar a0; TestTypeOf #7; Return

In each function, Ldar a0 loads the first argument, and Return gives back the result. The instruction in the middle is the check itself:

The undetectable mark and document.all

document.all is a very old browser feature. It lists every element on a web page. Browsers keep it working for old websites, but they make it look missing in checks. The undetectable mark is what links == null and document.all.

A comment in V8's map.h file says that an object with the undetectable mark:

• gives "undefined" for typeof,
• turns into false as a boolean,
• is useful for document.all.

V8's public API is the set of tools that programs such as Chrome use to build on V8. In api.cc, it has ObjectTemplate::MarkAsUndetectable. A browser can use it to put the mark on its own objects.

1const value = %GetUndetectable();2console.log(typeof value);3console.log(value == null);4console.log(value == undefined);5console.log(value === null);6console.log(Boolean(value));7%DebugPrint(value);

%GetUndetectable() is another special V8 helper. It makes a test object that has the undetectable mark. The lesson's test checks that this object:

• gives "undefined" for typeof (line 2),
• is loosely equal, ==, to null and to undefined (lines 3 and 4),
• is not strictly equal, ===, to null (line 5),
• is falsy, so Boolean(value) is false (line 6).

Its debug print also shows undetectable and callable on the object's map.

1// This only works in a browser. Node has no document.all.2console.log(typeof document.all);3console.log(document.all == null);4console.log(document.all == undefined);5console.log(document.all === null);6console.log(Boolean(document.all));

Objects whose prototype is null

Most objects have a prototype: another object they borrow properties from. A plain {} borrows from Object.prototype, which gives it names such as toString.

Object.create(null) and the literal { __proto__: null } make real objects whose prototype is null. They borrow nothing. That makes them safe dictionaries: objects you use to look up values by string keys. A key such as "toString" can't find a borrowed method by accident. But these objects are still objects. They are not the value null.

1const dict = Object.create(null);2dict.answer = 42;3console.log(Object.getPrototypeOf(dict) === null);4console.log("toString" in dict);5console.log(dict.answer);6 7const literal = { __proto__: null, answer: 42 };8console.log(Object.getPrototypeOf(literal) === null);

• Line 1 makes dict with Object.create(null).
• Line 3 prints true: the prototype of dict is null.
• Line 4 prints false: dict has no toString, because it borrows nothing.
• Line 5 prints 42, the value saved on line 2.
• Lines 7 and 8 do the same with a literal and print true.

1const created = Object.create(null);2const literal = { __proto__: null };3const ordinary = {};4console.log(%HasFastProperties(created));5console.log(%HasFastProperties(literal));6console.log(%HasFastProperties(ordinary));7%DebugPrint(created);

V8 can store the properties of an object in two ways:

• Fast properties sit in fixed places that the object's map describes.
• Dictionary mode, also called slow properties, keeps them in a lookup table, like a small phone book.

%HasFastProperties is a special V8 helper. It gives true when an object uses fast properties. The lesson's test shows:

• %HasFastProperties(Object.create(null)) is false.
• %HasFastProperties({ __proto__: null }) is false.
• %HasFastProperties({}) is true.

V8's bootstrapper is the code that sets up the built-in objects. Its comment says "Set up slow map for Object.create(null) instances without in-object properties". It saves that map as slow_object_with_null_prototype_map.

A property lookup stops at null

When you read a property, JavaScript looks in the object first. If the property isn't there, it goes to the object's prototype and looks there. Then it goes to that object's prototype, and so on. This line of prototypes is the prototype chain. Every chain ends at null.

The spec step OrdinaryGet says it plainly: when the next prototype is null, the read gives undefined.

V8 can also remember the answer to a lookup. Each map has a prototype_validity_cell: a marker that changes when the prototype chain changes. An inline cache is V8's saved answer for a property read at one place in your code. It can check that marker before it reuses its answer.

1const base = { shared: "base value" };2const middle = Object.create(base);3const child = Object.create(middle);4 5console.log(child.shared);6console.log(child.missing);7console.log(Object.getPrototypeOf(Object.prototype) === null);

• Line 1 makes base, which owns shared.
• Line 2 makes middle, with base as its prototype.
• Line 3 makes child, with middle as its prototype.
• Line 5 prints base value. child and middle don't own shared, but base does.
• Line 6 prints undefined. No object owns missing, so the walk reaches null.
• Line 7 prints true: the prototype of Object.prototype is null.

1const base = { shared: "base value" };Run2const middle = Object.create(base);3const child = Object.create(middle);4 5console.log(child.shared);6console.log(child.missing);7console.log(Object.getPrototypeOf(Object.prototype) === null);

Prototype internals explains maps and prototype pointers in more detail. Inline caches explains why V8 wants to save an answer like "not found, as long as this chain doesn't change".

Try the checks, then use them in real code

Pick a value below. The playground runs five checks on it: typeof, loose null (== null), strict null (=== null), Boolean(), and Number(). It also names the V8 check that decides the answer.

1const value = null;2console.log(typeof value);3console.log(value == null);4console.log(value === null);5console.log(Boolean(value));

In real code, you often want to treat null and undefined as "missing" but keep values such as 0 and "". Those two are falsy: they count as false in an if. But they are real values.

1function describeResult(value) {2  if (value == null) {3    return "missing";4  }5  return "present: " + value;6}7 8console.log(describeResult(null));9console.log(describeResult(undefined));10console.log(describeResult(0));11console.log(describeResult(""));

• Line 2 uses value == null, so both null and undefined give "missing".
• Lines 8 and 9 print missing.
• Line 10 prints present: 0, and line 11 prints present: with nothing after it. 0 and "" are kept.

Which check to use:

• Use value === null when only null should match.
• Use value == null when both null and undefined mean "missing".
• Don't use typeof value === "object" alone. It is also true for null, so check value !== null too.
• Use Object.create(null) for simple dictionaries. Use Map when you need more.

Common misconceptions

• "typeof null proves that null is an object." No. The answer was kept from 1995 so old code keeps working. Reading a property of null still throws an error.
• "== null checks for any falsy value." No. It matches only null, undefined, and values with the undetectable mark. It does not match 0, "", or false.
• "document.all is just undefined." No. It is an old browser object with special rules. document.all === null and document.all === undefined are both false.
• "An object with a null prototype is null." No. It is a real object. Only its prototype is null.
• "Dictionary mode is always bad." No. V8 picks it on purpose for objects used as dictionaries, where keys come and go.

The next table compares four values. Each row is one value. Each column asks one question about it.

This table takes ideas that share the word "null". Each row says what the idea really means, and what it is not.

Key takeaways

• V8 keeps one read-only null. It holds ready-made answers: 0 as a number, "null" as a string, and "object" for typeof.
• typeof null gives "object" because, in 1995, null was an all-zero word, and 000 was the object tag.
• === null becomes the instruction TestNull. == null becomes TestUndetectable.
• document.all is an old browser object. It is falsy and == null, but it is not null.
• An object made with Object.create(null) is a useful dictionary. Every property lookup stops when it reaches a null prototype.

Up next: Strings inside the engine. You'll see the different ways V8 stores strings, such as one-byte strings, two-byte strings, ropes, and slices.