Bindings: how DOM objects exist in JavaScript

A browser API is a binding

JavaScript can call document.createElement, read document.body, and build a URL. Those values are not invented by JavaScript alone. The browser exposes its platform objects to JavaScript through a binding layer.

A binding is the agreement that makes a browser capability appear as a JavaScript value, property, method, constructor, or exception. It includes argument conversion, object identity, prototypes, and unusual old behavior kept for compatible websites.

This follows How input reaches your event handlers. Input handlers are JavaScript functions, but their event objects, targets, and document methods arrive through these bindings. Next, Realms, globals & WindowProxy explains why each global gets its own related objects.

Web IDL is the printed manual

Think of a TV remote. You press a button, but the electronics inside the TV do the work. The printed manual says what the button accepts and what it does. JavaScript is the remote; browser implementation objects are the electronics; Web IDL is the manual.

An IDL interface names attributes and operations. In JavaScript, regular operations usually become methods on an interface prototype, while an interface object is usually available on the global object. The specification also states which globals expose it.

This is why API behavior is more exact than a TypeScript declaration alone. Web IDL specifies conversion before an operation runs. If conversion fails, the operation does not run. That detail explains many useful browser edge cases.

// Simplified Web IDL, not the whole DOM Standard.
interface Element {
  undefined setAttribute(DOMString name, DOMString value);
};

const box = document.createElement("div");
box.setAttribute("data-count", 5);
console.log(box.getAttribute("data-count"));

The first three lines are a deliberately simplified reading aid, not a copy of the DOM Standard. interface Element names the kind of platform object. undefined says setAttribute does its work without returning a useful value.

The two DOMString words describe conversion at the boundary. In the JavaScript call, the number 5 reaches the second parameter and becomes the string "5". The final log prints 5, because the browser stored the converted string as the attribute value.

Read IDL as a compact contract: interface name, member name, return type, then argument types. It describes what JavaScript can observe. It does not promise a particular engine class, memory address, or internal implementation language.

DOMString, USVString, and sequences

Web APIs do not merely receive arbitrary JavaScript values. Each parameter has a Web IDL type. A DOMString is a string of UTF-16 code units, while a USVString is a Unicode scalar-value string that cannot retain a lone surrogate.

1const box = document.createElement("div");2box.setAttribute("data-count", 5);3console.log(typeof box.getAttribute("data-count"));

Line 1 creates a detached element. Line 2 gives setAttribute the number 5. The binding converts that value to the DOMString "5". Line 3 therefore prints string, not number.

1const value = 5;Run2const text = String(value);3const attribute = text;4console.log(typeof attribute);

1const url = new URL("https://shop.example/?q=\uD800");2console.log(url.search);

Line 1 gives URL text containing one unmatched surrogate. The URL API converts that input to a USVString, replacing the invalid scalar position with U+FFFD. Line 2 prints ?q=%EF%BF%BD, the percent encoding of that replacement character.

A DOMString uses JavaScript's ordinary string conversion and can retain a lone surrogate code unit. A USVString first makes a DOMString, then replaces each lone surrogate with the replacement character. URL parsing needs scalar values, so it uses the stricter representation.

This is not a general instruction to sanitize every JavaScript string. It is one API-boundary rule. Keep the question narrow: which Web IDL type does this specific parameter name? The answer predicts the conversion before the URL algorithm begins.

1const snacks = new Set(["tea", "cake"]);2const blob = new Blob(snacks);3console.log(blob.size);

Line 1 creates a Set, which is iterable. Line 2 passes it to Blob; its sequence parameter consumes the iterable into a list of blob parts. Line 3 prints 7, because tea has three UTF-8 bytes and cake has four.

const letters = new Set(["a", "b"]);
const copied = [...letters];
console.log(copied.join(","));

Line 1 makes a Set, whose iterator yields "a" and then "b". Line 2 spreads that iterable into a new Array. Line 3 prints a,b. A Web IDL sequence follows the same important idea: it accepts an iterable and builds a list of converted values rather than retaining the original Set object as the sequence.

Wrappers and browser objects

Many browsers implement DOM data using native browser objects. JavaScript receives a platform object that stands for that browser object. Developers often call this visible JavaScript object a wrapper.

1const firstBody = document.body;2const secondBody = document.body;3console.log(firstBody === secondBody);

Line 1 reads the body wrapper. Line 2 reads it again. Line 3 prints true. The same underlying document body is observed as the same JavaScript object, so equality and event listeners behave predictably.

This does not require you to know the browser's internal language. The Web IDL standard permits implementation choices. The observable promise is the JavaScript identity and interface behavior, not a particular C++ class layout.

The useful mental model is simple: JavaScript holds a platform object, and browser code owns the platform behavior behind it. Do not serialize a DOM node expecting to recreate its browser identity somewhere else.

const body = document.body;
body.lessonNote = "tea";

console.log(document.body.lessonNote);
console.log(body === document.body);

delete body.lessonNote;

Line 1 reads the body once. Line 2 adds a temporary ordinary JavaScript property to that visible object. Line 4 reads body again through document.body and prints tea. Line 5 prints true; both names still refer to the same wrapper.

The final delete keeps this small example polite to the page. More importantly, it separates two facts: the property is ordinary JavaScript state on the wrapper, while the wrapper itself represents a stable browser platform object. Browser implementations may use C++ internally, but that is not a second object you manipulate directly from JavaScript.

1const body = document.body;Run2body.lessonNote = "tea";3const again = document.body;4console.log(again.lessonNote);5console.log(body === again);

Interface objects and prototypes

An interface object is the JavaScript value named after a Web IDL interface, such as HTMLElement. It is a function object, which is why typeof HTMLElement says function.

1console.log(typeof HTMLElement);2try {3  new HTMLElement();4} catch (error) {5  console.log(error.name);6}

Line 1 prints function. Line 3 tries to construct an HTMLElement directly. HTML elements need browser creation rules, so line 5 prints TypeError after the catch. A function object can expose an interface without accepting new.

1let current = document.body;2for (let step = 0; step < 5; step += 1) {3  current = Object.getPrototypeOf(current);4  console.log(current.constructor.name);5}

Line 1 starts at the body object. Line 3 moves one prototype upward each time. Line 4 prints five constructor names: HTMLBodyElement, HTMLElement, Element, Node, and EventTarget.

1const names = [];Run2let current = document.body;3 4for (let step = 0; step < 5; step += 1) {5  current = Object.getPrototypeOf(current);6  names.push(current.constructor.name);7}8 9console.log(names.join(" -> "));

That chain explains inherited methods. An element can call addEventListener because EventTarget behavior sits higher in the chain. It does not mean each body object stores a separate copy of every method.

The interface object and the interface prototype do different jobs. HTMLElement is the global interface object. Its prototype is the shared object in an element's prototype chain. Methods such as element operations live on those prototypes so the browser does not need to place a separate function on every element instance.

The constructor error is useful evidence rather than a dead end. Web IDL interface objects are function objects, but only interfaces with suitable constructor operations can make instances with new. The DOM instead makes elements through document creation methods, where the document can supply the right realm, owner document, and element-specific setup.

Legacy platform objects and live collections

Some older web objects act partly like ordinary JavaScript objects and partly like collections. Web IDL calls platform objects with indexed or named property support legacy platform objects. This behavior exists for compatibility and is not a pattern for new API design.

1const list = document.createElement("ul");2list.innerHTML = "<li>tea</li>";3const live = list.getElementsByTagName("li");4const snapshot = list.querySelectorAll("li");5list.append(document.createElement("li"));6console.log(live.length, snapshot.length);

Line 3 gets a live HTMLCollection. Line 4 gets a static NodeList. Line 5 adds another list item. Line 6 prints 2 1: the live collection updated, while the querySelectorAll result kept its original match list.

const list = document.createElement("ul");
list.innerHTML = "<li>tea</li>";
const live = list.getElementsByTagName("li");
const snapshot = list.querySelectorAll("li");
list.append(document.createElement("li"));
console.log(live.length, snapshot.length);

Live does not mean reactive in a framework sense. Reading the collection later can produce different contents because the DOM changed. Convert it to an Array when you need a stable copy for a later calculation.

Indexed collection access is legacy platform-object behavior: a collection can answer collection[0] even though it is not an Array. Named access is another old compatibility shape. Treat those conveniences as browser API behavior, not as a reason to use arbitrary property indexing in new application APIs.

In the playground, the only changed input is the number of list items. Reset restores one item. The live result follows that input; the static result deliberately stays at the query-time snapshot. That contrast is the safe debugging question to ask when a list appears to move.

DOMException

DOMException is a platform error object with a name and message. It is separate from JavaScript's ordinary Error subclasses, though it has error-like behavior and can be checked with instanceof DOMException.

1const stopped = new DOMException("Stopped", "AbortError");2console.log(stopped.name, stopped instanceof DOMException);

Line 1 creates an exception with the name AbortError. Line 2 prints AbortError true. Code should normally use the name to identify the web-platform condition, rather than relying on legacy numeric error codes.

1try {2  document.createElement("1abc");3} catch (error) {4  console.log(error.name);5}

Line 2 asks the DOM to create a name that starts with a digit. The DOM rejects that name. Line 4 prints InvalidCharacterError, a DOMException name defined for invalid characters.

A DOMException tells you an API contract was not met. It is not proof that every thrown browser error is a DOMException, and a normal JavaScript TypeError can still be the right error for a different kind of failure.

const problem = new DOMException("Bad name", "InvalidCharacterError");
console.log(problem.name);
console.log(problem.code);
console.log(problem instanceof DOMException);

Line 1 constructs a platform exception with a message and name. Line 2 prints InvalidCharacterError. Line 3 prints the legacy numeric code 5. Line 4 prints true. In application code, prefer the descriptive name; codes exist for compatibility with older APIs.

The DOM's invalid-name example shows a browser-created exception, while this snippet constructs one directly. In both cases, the important branch is a stable name such as InvalidCharacterError, not a browser-specific message string.

The document.all exception

document.all is a compatibility relic. It returns an HTMLAllCollection, so property reads such as document.all.length work. Yet the HTML specification gives it special behavior for old feature-detection code.

1console.log(typeof document.all);2console.log(Boolean(document.all));3console.log(typeof document.all.length);

Line 1 prints undefined. Line 2 prints false. Line 3 prints number, because the collection still has a readable length. It is not literally the JavaScript value undefined.

The special [[IsHTMLDDA]] internal slot makes this possible. It affects typeof, Boolean conversion, and loose equality behavior. New code must not use it for feature detection; it exists only so old pages keep working.

In particular, document.all == null is true while strict equality with undefined is false. This is a narrowly specified compatibility exception, not a conversion rule you can recreate with a normal object, Proxy, or custom valueOf method.

Treat the double brackets as specification notation for an internal slot. JavaScript source cannot add [[IsHTMLDDA]] to an object. The HTML Standard gives it only to HTMLAllCollection so old pages that detect ancient browsers still behave as they historically did.

Practical debugging habits

Bindings become useful when an API surprises you. First inspect the API signature and the type of each argument. A number stored as a DOM attribute, a malformed URL string, and a live collection are all ordinary consequences of the binding contract.

When object identity matters, test it directly with strict equality. When inherited behavior matters, inspect prototypes with Object.getPrototypeOf. When a collection changes unexpectedly, check whether you have HTMLCollection or NodeList.

The published lessons on the DOM tree, node properties, attributes and properties, and the prototype chain give the everyday API practice behind these internals.

Common misconceptions

• “The DOM is pure JavaScript.” DOM objects are platform objects exposed through a JavaScript binding.
• “Every interface function accepts new.” An interface object can be a function and still throw when constructed.
• “All DOM collections are arrays.” They can be collection objects with different identity and liveness rules.
• “document.all is undefined.” It has selected undefined-like behavior, but remains an object-like collection.
• “DOMException is just Error.” It is a distinct web-platform interface with observable names.

These distinctions save debugging time because they point to the correct layer. A conversion problem belongs at the API boundary. A prototype problem belongs in interface inheritance. A moving query result belongs in collection liveness.

Practice exercises

const box = document.createElement("div");
box.setAttribute("data-count", 5);
console.log(typeof box.getAttribute("data-count"));

const live = list.getElementsByTagName("li");

const stopped = new DOMException("Stopped", "AbortError");
console.log(stopped.name, stopped instanceof DOMException);

Check your understanding

Use the binding contract to predict values instead of treating browser behavior as magic.

Key takeaways

• Web IDL describes how browser APIs become JavaScript objects and methods.
• DOMString, USVString, and sequences each convert JavaScript input differently.
• DOM nodes are stable platform objects with interface prototypes.
• Live collections can change after DOM changes, unlike static query results.
• DOMException names describe web-platform failure conditions.
• document.all is a deliberate legacy compatibility exception.

Coming next: Realms, globals & WindowProxy.