API: select() Function
Relevant source files
The following files were used as context for generating this wiki page:
The select() function is the primary entry point for the cheerio-select library. It provides a CSS selector engine that extends the standard css-select capabilities by adding support for jQuery-style positional pseudo-selectors, such as :first, :eq(), and :gt().
This function allows developers to query a DOM structure—represented by domhandler nodes—using either a string selector or a predicate function. It handles complex selector groupings, traversals, and positional filtering to return an array of matching elements.
Sources: README.md:1-12, src/index.ts:182-192
Core Architecture and Data Flow
The select() function operates by parsing the input selector and bifurcating it into "plain" CSS selectors and "filtered" selectors (those containing positional pseudos). Plain selectors are delegated to the underlying css-select engine, while filtered selectors are processed through a specialized positional handling logic.
Logic Flow for Selector Processing
The following diagram illustrates how a selector string is processed through the system:
The diagram shows the branching logic between standard CSS selectors and positional-dependent selectors within the select() engine.
Sources: src/index.ts:193-219, src/helpers.spec.ts:5-15
API Definition
select() Signature
export function select(
selector: string | ((element: Element) => boolean),
root: AnyNode | AnyNode[],
options: Options = {},
limit = Number.POSITIVE_INFINITY,
): Element[];
Sources: src/index.ts:182-187
Parameters
| Parameter | Type | Description |
|---|---|---|
selector | string | Function | A CSS selector string or a function returning a boolean for a given element. |
root | AnyNode | AnyNode[] | The starting node(s) for the search. |
options | Options | Configuration for the query, including xmlMode and root document reference. |
limit | number | The maximum number of results to return (default: Infinity). |
Sources: src/index.ts:182-192, src/index.spec.ts:109-122
Positional Pseudo-Selectors
A key feature of select() is its support for jQuery positionals. These are identified via isFilter and processed using getLimit to optimize performance by stopping the search once the required number of elements is found.
Supported Positional Filters
:first: Selects the first matching element.:last: Selects the last matching element.:eq(index)/:nth(index): Selects element at specific index.:gt(index): Selects elements with index greater than specified.:lt(index): Selects elements with index less than specified.:even/:odd: Selects elements based on parity.:not(:positional): Excludes elements matching positional criteria.
Sources: README.md:10-21, src/positionals.ts:8-25
Execution Sequence for Filters
When a positional filter is encountered, the engine follows this sequence:
This sequence shows how select() utilizes findFilterElements to apply positional constraints during the discovery phase rather than just as a post-processing step.
Sources: src/index.ts:229-265, src/positionals.ts:60-95
Configuration Options
The Options interface extends standard css-select options, providing fine-grained control over the selection process.
| Option | Type | Description |
|---|---|---|
xmlMode | boolean | If true, treats the document as XML (case-sensitive tags). |
root | Document | Optional reference to the root of the document for absolute selectors. |
context | AnyNode[] | The context in which the selector is evaluated (useful for :scope). |
lowerCaseTags | boolean | Whether to treat tags as case-insensitive (ignored in xmlMode). |
Sources: src/index.ts:28-33, test/advanced-selectors.spec.ts:60-70
Implementation Details
Selection Logic (findFilterElements)
The findFilterElements function is a recursive internal helper that handles the heavy lifting for selectors containing positionals. It slices the selector at the first filter, retrieves the necessary elements up to a calculated limit, applies the positional filter, and then recursively processes the remainder of the selector string.
Sources: src/index.ts:229-307
Handling Traversal
If a selector contains traversals (like +, >, or ~) and positionals, select() adjusts the search context. For example, if a selector starts with a sibling traversal (e.g., + .class), it ensures the context includes siblings of the target nodes.
Sources: src/index.ts:271-290, src/index.spec.ts:38-42
Performance Optimization
The engine uses getLimit to determine the maximum number of elements needed. For :first, it returns a limit of 1, allowing DomUtils.find to terminate early. For :even or :odd, it calculates a limit based on the overall partLimit.
Sources: src/positionals.ts:60-95, src/index.ts:246-260
Summary
The select() function provides a powerful bridge between standard CSS selection and jQuery's intuitive positional filtering. By intelligently splitting selectors and applying limits during the DOM traversal, it maintains high performance while supporting complex, multi-stage queries across domhandler structures.
Sources: src/index.ts:182-307, README.md:23-53