Introduction to cheerio-select

Relevant source files

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

• README.md
• src/index.ts
• src/positionals.ts
• src/helpers.spec.ts
• package.json
• src/index.spec.ts

cheerio-select is a CSS selector engine specifically designed to support jQuery-style positional pseudo-selectors. It acts as a wrapper around the css-select library, extending its standard CSS selector capabilities with advanced filtering logic required for complex DOM manipulation and selection tasks.

Sources: README.md:1-6, package.json:3-4

The primary purpose of this module is to provide high-performance selection within DOM structures (typically those generated by htmlparser2 and domhandler), offering support for non-standard CSS selectors like :eq(index), :first, and :gt(index). It is intended for use in environments where jQuery-compatible selector behavior is required, such as within the Cheerio library.

Sources: README.md:8-17, src/index.ts:1-20

Core Architecture and Logic

The architecture of cheerio-select centers on distinguishing between "plain" CSS selectors (handled directly by css-select) and "filtered" selectors that contain positional pseudo-classes.

Selector Grouping

When a selector string is provided, it is first parsed into a Selector[][] structure using css-what. The groupSelectors helper then splits these into two categories:

1. Plain Selectors: Standard CSS selectors that can be compiled and executed efficiently by the underlying engine.
2. Filtered Selectors: Selectors containing positional tokens (e.g., :first, :even) that require sequential processing.

Sources: src/index.ts:60-65, src/helpers.spec.ts:7-13

Execution Flow

The following diagram illustrates how cheerio-select processes a query through the select function.

Positional Pseudo-Selectors

The library's defining feature is its support for positional filters. These filters evaluate the index of elements within a set rather than just their attributes or tree position.

Supported Filters

Filter	Description
:first	Selects the first element in the set.
:last	Selects the last element in the set.
:eq(index)	Selects the element at the specified zero-based index.
:nth(index)	Equivalent to :eq(index).
:gt(index)	Selects all elements with an index greater than the specified value.
:lt(index)	Selects all elements with an index less than the specified value.
:even	Selects even-numbered elements (0, 2, 4...).
:odd	Selects odd-numbered elements (1, 3, 5...).
:not(:pos)	Excludes elements matching a positional selector.

Sources: README.md:8-17, src/positionals.ts:8-25

Limit Calculation

To optimize performance, cheerio-select calculates a "limit" for each positional selector. This determines the maximum number of elements the engine needs to find before it can stop searching the DOM. For example, :first sets a limit of 1.

Sources: src/positionals.ts:64-105

API Reference

The module exports several high-level functions for interacting with the DOM.

Primary Functions

• select(selector, root, options, limit): The main entry point. Searches a root (or list of nodes) for elements matching the selector.
• filter(selector, elements, options): Filters an existing array of elements against a selector.
• is(element, selector, options): Returns a boolean indicating if a single element matches the selector.
• some(elements, selector, options): Returns a boolean if at least one element in the provided list matches the selector.

Sources: src/index.ts:46-48, src/index.ts:67-69, src/index.ts:133-137, src/index.ts:232-237

Options Configuration

The Options interface extends standard css-select options:

• root: (Optional) A reference to the Document root. If not provided, it is computed from the first element.
• xmlMode: (Inherited) Enables XML-specific parsing rules (e.g., case sensitivity).
• context: (Inherited) Limits the search to specific nodes.

Sources: src/index.ts:34-39, src/index.spec.ts:114-118

Internal Logic: findFilterElements

The findFilterElements function is the core recursive engine for handling positional selectors. It slices the selector array at the first positional filter, retrieves elements matching the prefix, applies the positional logic (like index filtering), and then recursively processes the remaining selector string against the resulting subset.

Conclusion

cheerio-select extends the standard CSS selection model to bridge the gap between modern CSS-select engines and the legacy expectations of jQuery-like environments. By implementing a sophisticated grouping and recursive filtering strategy, it provides the positional accuracy required by Cheerio while maintaining compatibility with the broader domhandler ecosystem.

Sources: README.md:1-25, src/index.ts:1-15