API: some() Function
Relevant source files
The following files were used as context for generating this wiki page:
The some() function is a core utility within the cheerio-select library used to determine if at least one element within a provided list matches a specific selector. It serves as a predicate for element sets, supporting both standard CSS selectors and advanced jQuery-style positional pseudo-selectors.
This function is internally utilized by other API methods such as is() to evaluate single-element matches by wrapping them in an array. It offers a highly efficient way to perform checks on DOM structures without necessarily retrieving all matching nodes.
Sources: src/index.ts:51-53, README.md:52-53
Function Signature and Parameters
The some() function accepts an array of elements, a selector (which can be a string or a predicate function), and an optional configuration object.
| Parameter | Type | Description |
|---|---|---|
elements | Element[] | An array of DOM elements to evaluate against the selector. |
selector | string | ((element: Element) => boolean) | The CSS selector string or a function that returns true for a match. |
options | Options | Optional settings including xmlMode, lowerCaseTags, and root reference. |
Sources: src/index.ts:60-64, src/index.ts:39-42
Options Interface
The Options object extends CSSSelectOptions and can include a root property of type Document, which provides a reference point for global document queries.
Sources: src/index.ts:39-42
Logical Execution Flow
When some() is invoked, it first checks the type of the selector. If a function is provided, it uses the native Array.prototype.some method. If a string is provided, the selector is parsed and split into "plain" selectors (standard CSS) and "filtered" selectors (containing positional pseudos like :first or :eq).
The diagram shows the decision logic used to handle different selector types and optimize performance by checking plain selectors before more complex filtered ones.
Sources: src/index.ts:66-76, src/index.ts:241-248
Internal Logic and Dependencies
Selector Grouping
The function relies on groupSelectors to separate standard CSS selectors from those containing jQuery-style positionals. This allows cheerio-select to delegate standard parts to css-select while handling custom positionals internally.
Sources: src/index.ts:69, src/helpers.spec.ts:5-13
Positional Pseudo-Selectors
Supported positional filters include:
:first/:last:eq(index)/:nth(index):gt(index)/:lt(index):even/:odd:not(:positional)
Sources: src/positionals.ts:7-17, README.md:7-17
Handling Traversals
If a selector contains traversals (e.g., child or sibling combinators), some() triggers filterBySelector. This logic identifies the document root or context to ensure relative selectors (like :scope) are evaluated correctly within the tree.
Sources: src/index.ts:182-192
Usage Examples
Using String Selectors
import { some } from "cheerio-select";
// ps = [<p>First</p>, <p>Second</p>]
const hasSecond = some(ps, "p:contains(Second)"); // returns true
const hasIndexThree = some(ps, "p:eq(3)"); // returns false
Sources: src/index.spec.ts:85-88
Using Function Predicates
import { some } from "cheerio-select";
const hasChildren = some([div], (element) => element.children.length > 1);
Sources: src/index.spec.ts:92-94
Performance Considerations
The some() function is optimized to return true as soon as the first match is encountered. By checking plain selectors before filtered selectors, it leverages the speed of the underlying css-select engine for standard CSS queries before falling back to custom positional logic.
Sources: src/index.ts:72-75
Summary
The some() function provides a boolean-returning interface for selector matching against element sets. By integrating with css-what for parsing and css-select for execution, while adding specialized handling for positional filters, it offers a comprehensive solution for jQuery-compatible selection logic in the Cheerio ecosystem.