Static Methods & Utilities
Relevant source files
The following files were used as context for generating this wiki page:
Static methods and utilities in Cheerio provide foundational functionality that does not require a reference to a specific Cheerio instance. These methods handle tasks such as document loading, serialization, string manipulation, and DOM tree traversal. While Cheerio primarily follows a jQuery-like instance-based API, static methods serve as the entry point for document parsing and provide helper logic for internal operations.
The project distinguishes between public static methods (intended for users) and private utilities. Private functionality is implemented as named functions within modules to avoid unnecessary instance overhead.
Sources: CONTRIBUTING.md:27-30, src/static.ts
Core Static Methods
Static methods are typically accessed via the main cheerio module. They allow for the creation of new instances and the manipulation of DOM structures independently of a loaded document.
Parsing and Loading
The primary entry point for using Cheerio is the load method. Unlike jQuery, which operates on a global window object, Cheerio requires an explicit load step to parse HTML or XML strings into a DOM tree.
The diagram shows the data flow from raw input string to a functional Cheerio instance.
Sources: Readme.md:58-65, src/parse.spec.ts
Serialization Utilities
Static serialization methods allow for converting DOM nodes or collections back into markup.
| Method | Description |
|---|---|
$.html([selector/node]) | Renders the HTML content of the selection or the entire document. |
$.xml() | Renders the document or selection as XML. |
$.text() | Extracts the combined text content of the selected elements and their descendants. |
Sources: src/static.spec.ts:5-81, src/tests/deprecated.spec.ts:133-211
Internal Utility Functions
The utils.ts module contains helper functions used for string transformation and type checking. These are essential for maintaining compatibility with jQuery's naming conventions and handling internal object identification.
String Case Transformation
Cheerio uses specific utilities to convert between CSS-style properties and JavaScript-style camelCase.
- camelCase: Converts hyphenated strings (like
data-foo-bar) into camelCase (dataFooBar). - cssCase: Reverses the process, converting camelCase strings into hyphenated CSS properties.
// Example from src/utils.spec.ts
utils.camelCase('camel-case-'); // 'camelCase'
utils.cssCase('camelCase'); // 'camel-case'
Sources: src/utils.ts, src/utils.spec.ts:5-12, src/utils.spec.ts:25-30
Type Identification
To verify if an object is a valid Cheerio selection, the library uses a internal marker check.
| Utility | Logic |
|---|---|
isCheerio(obj) | Checks if the object has a property cheerio equal to [cheerio object]. |
isHtml(str) | Determines if a string contains HTML markup by checking for < tags, doctypes, or comments. |
Sources: src/utils.ts, src/utils.spec.ts:14-23, src/utils.spec.ts:32-44
DOM Traversal and Manipulation Utilities
Static methods also provide ways to compare nodes and merge collections, mimicking jQuery's internal behaviors.
Node Relationships
The $.contains(container, contained) method determines if a DOM node is a descendant of another node.
Logic for determining descendant relationships between nodes.
Sources: src/static.spec.ts:275-298, src/tests/deprecated.spec.ts:101-125
Collection Merging
The merge utility is used to combine two array-like objects into one. It modifies the first object by appending elements from the second.
- Logic: It iterates through the second array and assigns values to the first array starting at its current
length. - Validation: It rejects inputs that are not "array-like" (objects missing a non-negative integer
lengthproperty).
Sources: src/tests/deprecated.spec.ts:24-99, src/static.spec.ts:223-273
Deprecated Static APIs
Several static methods that were previously part of the "loaded" Cheerio instance are now deprecated in favor of either instance methods or module-level exports to better align with jQuery 4.0 standards.
- $.parseHTML: Static method to parse a string into an array of DOM nodes.
- Instance-attached .html()/.text(): Users are encouraged to use the instance methods (e.g.,
$('selector').html()) instead of passing a selection to the static$.html($selection).
Sources: src/tests/deprecated.spec.ts:13-22, src/static.spec.ts:137-221
Summary
Static methods and utilities form the structural backbone of Cheerio. They bridge the gap between raw string inputs and the object-oriented manipulation API. By providing robust utilities for case conversion, type checking, and collection management, these methods ensure that Cheerio remains fast and consistent while maintaining a lightweight footprint that does not rely on a browser DOM.