API: is() Function

Relevant source files

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

• src/index.ts
• src/index.spec.ts
• src/positionals.ts
• README.md
• test/sizzle.spec.ts

The is() function is a core utility within the cheerio-select library used to determine if a specific DOM element matches a given selector. It acts as a specialized wrapper around the library's internal selection logic, specifically utilizing the some() function to evaluate a single element against a selector string or a predicate function.

This function is essential for conditional logic during DOM traversal and manipulation, supporting standard CSS selectors as well as jQuery-specific positional pseudo-selectors like :first, :last, and :eq().

Sources: src/index.ts:50-54, README.md:46-47

Function Signature and Parameters

The is() function is designed to be concise, accepting an element, a selector, and an optional configuration object.

Parameter	Type	Description
element	Element	The specific DOM element to evaluate.
selector	string | ((element: Element) => boolean)	The selector string or a function used to match the element.
options	Options	Optional configuration for the selector engine (e.g., xmlMode, root).

Sources: src/index.ts:48-58, src/index.spec.ts:85-98

Internal Logic and Data Flow

The is() function is a pass-through to some(). It wraps the single element into an array ([element]) and delegates the matching logic.

Logical Execution Flow

1. Input Handling: The function receives the target Element.
2. Delegation: It calls some([element], selector, options).
3. Selector Parsing: If a string is provided, it is parsed and grouped into plain CSS selectors and filtered selectors (those containing positional pseudo-classes).
4. Evaluation:
   • If a function is provided, it is executed directly against the element.
   • If a string is provided, cheerio-select checks if the element matches the parsed tokens.

The logic ensures that even complex selectors involving positionals or traversals are correctly resolved against the single element context.

Sources: src/index.ts:50-84, src/index.spec.ts:85-98

Usage Examples

The is() function supports various selector types, including standard CSS, jQuery positionals, and custom functions.

import { is } from "cheerio-select";
import { parseDocument } from "htmlparser2";

const dom = parseDocument("<div><p>First</p><p>Second</p></div>");
const [div] = dom.children;
const [p1, p2] = div.children;

// Standard CSS matching
is(p1, "div p"); // true

// Positional pseudo-selector matching
is(p1, "div p:first"); // true
is(p2, "div p:first"); // false

// Predicate function matching
is(div, (elem) => elem.children.length > 1); // true

Sources: src/index.spec.ts:85-98, README.md:46-47

Integration with Positional Filters

Because is() utilizes the internal filterByPosition logic via some(), it correctly handles the jQuery-style positional filters defined in the library.

Filter	Description
:first / :last	Matches if the element is the first/last in its set.
:eq(index)	Matches if the element matches the specific index.
:gt(index) / :lt(index)	Matches based on index comparison.
:even / :odd	Matches based on zero-indexed parity.

When is(element, ":first") is called, the library evaluates the element's position within the context provided (or the document root).

Sources: src/positionals.ts:8-23, src/index.ts:70-112

Conclusion

The is() function provides a convenient, high-level API for element matching in cheerio-select. By abstracting the complexity of selector parsing and positional filter evaluation into a simple boolean check, it allows developers to perform precise DOM queries with minimal overhead. Its reliance on the some() function ensures consistent behavior across all selection utilities in the package.