The "DOM Node" Object

Relevant source files

The following files were used as context for generating this wiki page:

• Readme.md
• src/parse.spec.ts
• src/cheerio.spec.ts
• src/api/attributes.spec.ts
• src/api/manipulation.spec.ts
• THREAT_MODEL.md
• website/typedoc.json

In Cheerio, the "DOM Node" object represents the underlying data structure used to model HTML and XML documents. Cheerio collections are comprised of these objects, which bear a close resemblance to browser-based DOM nodes but operate within a server-side environment using a simple, consistent model. These nodes are primarily managed by the domhandler library and are the target of Cheerio's selection and manipulation APIs.

Sources: Readme.md:89-91, THREAT_MODEL.md:9-11

Core Properties and Structure

Cheerio's DOM nodes implement a subset of the standard browser DOM API, focusing on structural traversal and identity. The internal representation is provided by domhandler, which defines several specific node types such as Element, Document, Text, and Comment.

Common Node Properties

Nodes in a Cheerio collection define the following standard properties to facilitate tree navigation:

Property	Description
tagName	The name of the tag (e.g., 'div', 'p'). In HTML mode, this is typically lowercased.
parentNode	Reference to the parent node in the hierarchy.
previousSibling	Reference to the immediate preceding sibling node.
nextSibling	Reference to the immediate following sibling node.
firstChild	The first child node of the current node.
lastChild	The last child node of the current node.
childNodes	An array-like collection of all children of the node.
nodeValue	The value content for text or comment nodes.

Sources: Readme.md:92-101, src/parse.spec.ts:192-212

Node Types

The underlying parser categorizes nodes into specific types, which dictates how Cheerio interacts with them:

• tag: Represents standard HTML elements (e.g., <div>).
• text: Represents raw text content between tags.
• comment: Represents HTML/XML comments (<!-- ... -->).
• directive: Represents document declarations like <!doctype html>.
• root: A special node representing the top-level container of a document or fragment.

Sources: src/parse.spec.ts:67-154

Relationships and Hierarchy

The following diagram illustrates the relationship between different node types and their navigational properties within the Cheerio DOM model.

The diagram shows the inheritance structure where Document and Element act as parent nodes, while Text and Comment are leaf nodes in most contexts.
Sources: website/typedoc.json:23-30, src/parse.spec.ts:57-65

Data Persistence and Attributes

DOM Node objects store metadata and content in specific internal fields. For Element types, attributes are stored in an attribs object.

Attribute Management

Attributes are key-value pairs where the value is stored as a string. Boolean attributes (like disabled or checked) are handled as strings (e.g., checked="checked" or an empty string "" depending on the parser settings).

// Internal representation of an element with attributes
const element = {
  type: 'tag',
  tagName: 'img',
  attribs: {
    src: 'hello.png',
    alt: 'man waving'
  },
  childNodes: [],
  // ... sibling and parent references
};

Sources: src/parse.spec.ts:109-115, src/api/attributes.spec.ts:40-45

Data Storage

Cheerio implements a .data() API that interacts with a specialized data property on the node. This property persists information that is not necessarily reflected in the HTML source, although it can be initialized from data-* attributes.

Sources: src/api/attributes.spec.ts:430-440

Parsing and Serialization Flow

The DOM Node object is the central unit of the Cheerio pipeline, sitting between the initial string input and the final serialized output.

The flow shows how input strings are transformed into Node objects, which are then manipulated before being rendered back to text.
Sources: THREAT_MODEL.md:9-11, src/parse.spec.ts:9-13

Integration with External Parsers

Cheerio's DOM nodes are highly compatible with the domhandler ecosystem. The project allows switching between parse5 and htmlparser2 tree adapters while maintaining a consistent node structure.

• parse5: Used by default for HTML parsing. It can provide additional metadata such as sourceCodeLocation if enabled via options.
• htmlparser2: Optionally used for more forgiving parsing or XML documents.

Sources: Readme.md:38-41, src/parse.spec.ts:258-265, website/typedoc.json:31-34

Security Considerations

Since DOM nodes are derived from potentially untrusted markup, Cheerio defines a threat model around their handling:

1. Trust Boundary: Input markup is considered untrusted and can result in nodes that, when serialized, might enable XSS if not properly sanitized by the calling application.
2. Execution: Cheerio nodes never execute scripts or evaluate expressions. A <script> node is treated as a specialized element containing a text node child.
3. Prototype Integrity: Cheerio ensures that parsing content does not result in prototype pollution of the JavaScript runtime.

Sources: THREAT_MODEL.md:16-25, THREAT_MODEL.md:39-45

Summary

The "DOM Node" object is the fundamental building block of Cheerio's document model. By implementing a lightweight version of the W3C DOM Node interface, it provides a performant and familiar API for server-side manipulation. It acts as a structured bridge between raw markup and Cheerio's jQuery-like selection logic, maintaining hierarchies, attributes, and text content in a way that is easily traversable and serializable.