DOM Traversal

/**
 * Main selector function for querying elements
 * @param selector - CSS selector, HTML string, or DOM elements
 * @param context - Context to search within (optional)
 * @param root - Root element for the search (optional)
 * @returns Cheerio instance wrapping matching elements
 */
<T extends AnyNode, S extends string>(
  selector?: S | BasicAcceptedElems<T>,
  context?: BasicAcceptedElems<AnyNode> | null,
  root?: BasicAcceptedElems<Document>
): Cheerio<S extends SelectorType ? Element : T>;

// CSS selectors
$('.class-name')        // Select by class
$('#element-id')        // Select by ID
$('div > p')           // Child selector
$('input[type="text"]') // Attribute selector

// With context
$('.item', '#container')  // Find .item within #container
$('li', $('ul').first()) // Find li within first ul

// Create from HTML
$('<div>New content</div>')

/**
 * Get descendants filtered by selector, jQuery object, or element
 * @param selector - Selector to filter descendants
 * @returns Cheerio instance with matching descendants
 */
find(selector?: string | Cheerio<Element> | Element): Cheerio<Element>;

// Find descendants by selector
$('#fruits').find('li')              // All li descendants
$('div').find('.highlight')          // All .highlight descendants

// Find by Cheerio object
const items = $('.item');
$('container').find(items)           // Find items within container

// Find by element
const element = $('span')[0];
$('div').find(element)               // Find specific element

/**
 * Get parent of each element, optionally filtered by selector
 * @param selector - Optional filter for parent selection
 * @returns Cheerio instance with parent elements
 */
parent(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get ancestors of each element, optionally filtered by selector
 * @param selector - Optional filter for ancestor selection
 * @returns Cheerio instance with ancestor elements
 */
parents(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get ancestors up to but not including the selector match
 * @param selector - Stop condition for ancestor traversal
 * @param filterSelector - Optional filter for results
 * @returns Cheerio instance with ancestor elements
 */
parentsUntil(
  selector?: AcceptedFilters<Element> | null,
  filterSelector?: AcceptedFilters<Element>
): Cheerio<Element>;

/**
 * Get first element matching selector by traversing up ancestors
 * @param selector - Selector to match against element and ancestors
 * @returns Cheerio instance with matching element
 */
closest(selector?: AcceptedFilters<Element>): Cheerio<AnyNode>;

// Get immediate parent
$('li').parent()                     // Parent elements of all li
$('span').parent('div')              // Parent div elements only

// Get all ancestors
$('.nested').parents()               // All ancestor elements
$('.item').parents('.container')     // Ancestor elements with .container class

// Get ancestors until condition
$('.deep').parentsUntil('body')      // Ancestors up to body element
$('.item').parentsUntil('.wrapper', '.section') // Ancestors up to .wrapper, filtered by .section

// Find closest matching ancestor
$('.button').closest('form')         // Closest form ancestor
$('.item').closest('.container')     // Closest container ancestor

/**
 * Get next sibling of each element, optionally filtered
 * @param selector - Optional filter for sibling selection
 * @returns Cheerio instance with next sibling elements
 */
next(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get all following siblings, optionally filtered
 * @param selector - Optional filter for sibling selection
 * @returns Cheerio instance with following sibling elements
 */
nextAll(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get following siblings up to but not including selector match
 * @param selector - Stop condition for sibling traversal
 * @param filterSelector - Optional filter for results
 * @returns Cheerio instance with following sibling elements
 */
nextUntil(
  selector?: AcceptedFilters<Element> | null,
  filterSelector?: AcceptedFilters<Element>
): Cheerio<Element>;

/**
 * Get previous sibling of each element, optionally filtered
 * @param selector - Optional filter for sibling selection
 * @returns Cheerio instance with previous sibling elements
 */
prev(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get all preceding siblings, optionally filtered
 * @param selector - Optional filter for sibling selection
 * @returns Cheerio instance with preceding sibling elements
 */
prevAll(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get preceding siblings up to but not including selector match
 * @param selector - Stop condition for sibling traversal
 * @param filterSelector - Optional filter for results
 * @returns Cheerio instance with preceding sibling elements
 */
prevUntil(
  selector?: AcceptedFilters<Element> | null,
  filterSelector?: AcceptedFilters<Element>
): Cheerio<Element>;

/**
 * Get siblings of each element (excluding the element itself)
 * @param selector - Optional filter for sibling selection
 * @returns Cheerio instance with sibling elements
 */
siblings(selector?: AcceptedFilters<Element>): Cheerio<Element>;

// Next/previous siblings
$('.current').next()                 // Immediate next sibling
$('.current').next('.item')          // Next sibling with .item class
$('.current').prev()                 // Immediate previous sibling

// All siblings in direction
$('.active').nextAll()               // All following siblings
$('.active').prevAll('.item')        // All preceding .item siblings

// Siblings until condition
$('.start').nextUntil('.end')        // Following siblings until .end
$('.current').prevUntil('.start', '.item') // Preceding siblings until .start, filtered by .item

// All siblings
$('.selected').siblings()            // All siblings (excluding .selected)
$('.item').siblings('.other')        // Sibling elements with .other class

/**
 * Get element children, optionally filtered by selector
 * @param selector - Optional filter for child selection
 * @returns Cheerio instance with child elements
 */
children(selector?: AcceptedFilters<Element>): Cheerio<Element>;

/**
 * Get all children including text and comment nodes
 * @returns Cheerio instance with all child nodes
 */
contents(): Cheerio<AnyNode>;

// Get element children
$('ul').children()                   // All child elements
$('div').children('p')               // Child p elements only
$('.container').children('.item')    // Child elements with .item class

// Get all content including text nodes
$('p').contents()                    // All child nodes including text

/**
 * Iterate over elements, executing a function for each
 * @param fn - Function to execute for each element
 * @returns Original Cheerio instance for chaining
 */
each(fn: (this: T, i: number, el: T) => void | boolean): Cheerio<T>;

/**
 * Transform elements through a function, creating new collection
 * @param fn - Function to transform each element
 * @returns New Cheerio instance with transformed elements
 */
map<M>(fn: (this: T, i: number, el: T) => M[] | M | null | undefined): Cheerio<M>;

/**
 * Filter elements to those matching selector or passing function test
 * @param match - Selector or function to test elements
 * @returns Filtered Cheerio instance
 */
filter(match: AcceptedFilters<T>): Cheerio<unknown>;

/**
 * Check if any elements match selector or pass function test
 * @param selector - Selector or function to test elements
 * @returns True if any element matches
 */
is(selector?: AcceptedFilters<T>): boolean;

/**
 * Remove elements matching selector or passing function test
 * @param match - Selector or function to test elements
 * @returns Cheerio instance with non-matching elements
 */
not(match: AcceptedFilters<T>): Cheerio<T>;

/**
 * Filter elements that have descendant matching selector
 * @param selector - Selector to test for descendants
 * @returns Cheerio instance with elements having matching descendants
 */
has(selector: string | Cheerio<Element> | Element): Cheerio<AnyNode | Element>;

// Iterate over elements
$('li').each((i, el) => {
  console.log(i, $(el).text());
});

// Transform elements
const texts = $('p').map((i, el) => $(el).text()).get();

// Filter elements
$('div').filter('.special')          // Only divs with .special class
$('li').filter((i, el) => $(el).text().length > 10) // li with long text

// Test elements
$('input').is(':checked')            // Any input checked?
$('.item').is('.active')             // Any item active?

// Remove elements
$('li').not('.keep')                 // All li except .keep
$('div').not((i, el) => $(el).hasClass('remove')) // Divs without .remove

// Elements with descendants
$('div').has('img')                  // Divs containing images
$('li').has('.icon')                 // List items with .icon

/**
 * Select first element in collection
 * @returns Cheerio instance with first element
 */
first(): Cheerio<T>;

/**
 * Select last element in collection
 * @returns Cheerio instance with last element
 */
last(): Cheerio<T>;

/**
 * Select element at specific index
 * @param i - Index of element to select
 * @returns Cheerio instance with element at index
 */
eq(i: number): Cheerio<T>;

/**
 * Get DOM elements as array or single element
 * @param i - Optional index to get single element
 * @returns Array of elements or single element
 */
get(i?: number): T | T[];

/**
 * Convert to array of DOM elements
 * @returns Array of all DOM elements
 */
toArray(): T[];

/**
 * Get index of element among siblings or within selection
 * @param selector - Optional element or selector to find index of
 * @returns Index of element, or -1 if not found
 */
index(selector?: string | Cheerio<AnyNode> | AnyNode): number;

/**
 * Get elements in specified range
 * @param start - Start index (inclusive)
 * @param end - End index (exclusive)
 * @returns Cheerio instance with elements in range
 */
slice(start?: number, end?: number): Cheerio<T>;

// Access specific elements
$('li').first()                      // First li element
$('li').last()                       // Last li element
$('li').eq(2)                        // Third li element (0-indexed)

// Get DOM elements
$('div').get()                       // Array of all div elements
$('p').get(0)                        // First p element as DOM node

// Convert to array
const elements = $('span').toArray(); // Array of span elements

// Get element index
$('li').eq(2).index()                // Index of element among siblings
$('li').index($('.active'))          // Index of .active element in li collection

// Slice collection
$('div').slice(1, 4)                 // Elements at indices 1, 2, 3
$('li').slice(-2)                    // Last 2 elements

/**
 * Return to previous selection in chain
 * @returns Previous Cheerio instance in chain
 */
end(): Cheerio<AnyNode>;

/**
 * Add elements to current selection
 * @param other - Elements to add to selection
 * @param context - Context for selector resolution
 * @returns Combined Cheerio instance
 */
add<S>(
  other: string | Cheerio<S> | S | S[],
  context?: Cheerio<S> | string
): Cheerio<S | T>;

/**
 * Add previous selection to current selection
 * @param selector - Optional filter for previous selection
 * @returns Combined Cheerio instance
 */
addBack(selector?: string): Cheerio<AnyNode>;

// Chain management
$('div').find('p').addClass('found').end().addClass('container');
// Adds 'found' to p elements, then 'container' to div elements

// Combine selections
$('h1').add('h2')                    // All h1 and h2 elements
$('.item').add($('.special'))        // Combine two selections
$('div').add('<span>New</span>')     // Add created element

// Add previous selection
$('li').filter('.active').addClass('current').addBack().addClass('item');
// Adds 'current' to active li, then 'item' to all li

// Filter function signature
type FilterFunction<T> = (this: T, i: number, el: T) => boolean;

// Accepted filter types
type AcceptedFilters<T> = string | FilterFunction<T> | T | Cheerio<T>;

// Element types
type BasicAcceptedElems<T extends AnyNode> = ArrayLike<T> | T | string;
type AcceptedElems<T extends AnyNode> = 
  BasicAcceptedElems<T> | 
  ((this: T, i: number, el: T) => BasicAcceptedElems<T>);