Architecture Overview

Relevant source files

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

• Readme.md
• package.json
• THREAT_MODEL.md
• src/parse.spec.ts
• website/src/content/blog/2024-08-07-version-1.md
• src/cheerio.spec.ts
• src/api/manipulation.spec.ts

Cheerio is a fast, flexible, and elegant library designed for parsing and manipulating HTML and XML in Node.js and browser environments. It implements a subset of core jQuery functionality, specifically optimized for server-side use by removing DOM inconsistencies and browser-specific logic. Unlike a full browser environment, Cheerio does not execute scripts, evaluate expressions, or access the network autonomously.

Sources: Readme.md:1-20, THREAT_MODEL.md:8-12

Core System Components

The architecture is built upon several specialized libraries within the ecosystem that handle parsing, selection, and DOM tree management. Cheerio acts as a high-level wrapper that provides a jQuery-compatible API over these low-level components.

Component Breakdown

Component	Responsibility	Source Package
Parser	Converts raw markup strings into a DOM tree. Supports HTML and XML.	parse5, htmlparser2
DOM Handler	Defines the structure of the DOM nodes (Element, Text, Comment, etc.).	domhandler
Selector Engine	Executes CSS selectors against the DOM tree.	cheerio-select
Serializer	Converts the internal DOM tree back into a markup string.	dom-serializer
Utilities	Provides DOM traversal and manipulation helper functions.	domutils

Sources: package.json:115-125, Readme.md:46-52, THREAT_MODEL.md:17-26

High-Level Flow

The following diagram illustrates the typical lifecycle of a Cheerio operation, from initial markup loading to final rendering.

The system supports multiple input methods, including strings, buffers, and streams.
Sources: website/src/content/blog/2024-08-07-version-1.md:27-36, Readme.md:55-65

Document Loading and Parsing

Cheerio provides multiple entry points for ingesting data. While load is the primary method for strings, version 1.0 introduced specialized methods for different data types.

• load(content, options): Standard method for HTML/XML strings.
• loadBuffer(buffer): Handles binary data and automatically detects document encoding.
• fromURL(url): Fetches and parses markup from a remote URL using undici.
• Streaming: Supports stringStream and decodeStream for direct processing of input streams.

Sources: website/src/content/blog/2024-08-07-version-1.md:27-36

Parsing Logic

Cheerio utilizes parse5 by default for HTML parsing due to its compliance with the WHATWG HTML specification. For XML or specific performance requirements, it can utilize htmlparser2.

The internal parser configuration determines how nodes like <script>, <style>, and directives are handled.
Sources: src/parse.spec.ts:8-15, src/cheerio.spec.ts:250-265

Internal Data Model (DOM Tree)

Cheerio collections consist of objects that resemble browser-based DOM nodes. These nodes follow the domhandler schema.

Node Properties

Key properties defined on Cheerio-wrapped nodes include:

• tagName: The name of the element (e.g., 'div').
• parentNode: Reference to the parent node.
• childNodes: Array of children.
• attribs: An object containing the element's attributes.
• nodeValue: The value of text or comment nodes.

Sources: Readme.md:112-124, src/parse.spec.ts:160-185

Relationship Schema

The following diagram shows how nodes are related within the internal tree structure.

Data Extraction and Manipulation

Cheerio provides a jQuery-like API for interacting with the DOM. A significant architectural feature is the extract method, which allows for declarative data retrieval into structured objects.

Declarative Extraction

The extract feature maps CSS selectors to object keys, allowing complex tree traversal in a single call.

// Example of structured extraction
const data = $.extract({
  items: [{
    selector: 'li',
    value: {
      name: '.title',
      link: { selector: 'a', value: 'href' }
    }
  }]
});

Sources: website/src/content/blog/2024-08-07-version-1.md:42-77, src/static.spec.ts:275-290

Manipulation API

Traversal and manipulation operations update the internal domhandler tree in real-time. Operations like .append(), .prepend(), and .wrap() adjust the nextSibling, previousSibling, and parentNode pointers of the affected nodes to maintain tree integrity.

Security Architecture

Cheerio operates within defined trust boundaries, assuming the calling application handles final output sanitization.

• Markup Input: Treated as untrusted; the parser is designed to handle malicious or malformed input without execution.
• Script Execution: Cheerio never executes JavaScript found within <script> tags.
• Network Access: Except for the explicit fromURL helper, the core library does not perform network operations.
• Prototype Pollution: The library includes defenses against modifying Object.prototype through parsed content.

Sources: THREAT_MODEL.md:8-40, SECURITY.md:38-50

Conclusion

Cheerio's architecture is a composite of specialized tools unified by a familiar jQuery-style interface. By decoupling the parser (parse5/htmlparser2) from the manipulation logic and using a standardized DOM model (domhandler), Cheerio provides a high-performance environment for server-side HTML/XML processing that remains consistent across different JavaScript runtimes.