/** * Methods for traversing the DOM structure. * * @module cheerio/traversing */ import { Node, Element, Document } from 'domhandler'; import type { Cheerio } from '../cheerio'; import type { AcceptedFilters } from '../types'; /** * Get the descendants of each element in the current set of matched elements, * filtered by a selector, jQuery object, or element. * * @category Traversing * @example * * ```js * $('#fruits').find('li').length; * //=> 3 * $('#fruits').find($('.apple')).length; * //=> 1 * ``` * * @param selectorOrHaystack - Element to look for. * @returns The found elements. * @see {@link https://api.jquery.com/find/} */ export declare function find(this: Cheerio, selectorOrHaystack?: string | Cheerio | Element): Cheerio; /** * Get the parent of each element in the current set of matched elements, * optionally filtered by a selector. * * @category Traversing * @example * * ```js * $('.pear').parent().attr('id'); * //=> fruits * ``` * * @param selector - If specified filter for parent. * @returns The parents. * @see {@link https://api.jquery.com/parent/} */ export declare const parent: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Get a set of parents filtered by `selector` of each element in the current * set of match elements. * * @category Traversing * @example * * ```js * $('.orange').parents().length; * //=> 2 * $('.orange').parents('#fruits').length; * //=> 1 * ``` * * @param selector - If specified filter for parents. * @returns The parents. * @see {@link https://api.jquery.com/parents/} */ export declare const parents: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Get the ancestors of each element in the current set of matched elements, up * to but not including the element matched by the selector, DOM node, or cheerio object. * * @category Traversing * @example * * ```js * $('.orange').parentsUntil('#food').length; * //=> 1 * ``` * * @param selector - Selector for element to stop at. * @param filterSelector - Optional filter for parents. * @returns The parents. * @see {@link https://api.jquery.com/parentsUntil/} */ export declare const parentsUntil: (this: Cheerio, selector?: AcceptedFilters | null | undefined, filterSelector?: AcceptedFilters | undefined) => Cheerio; /** * For each element in the set, get the first element that matches the selector * by testing the element itself and traversing up through its ancestors in the DOM tree. * * @category Traversing * @example * * ```js * $('.orange').closest(); * //=> [] * * $('.orange').closest('.apple'); * // => [] * * $('.orange').closest('li'); * //=> [
  • Orange
  • ] * * $('.orange').closest('#fruits'); * //=> [
      ...
    ] * ``` * * @param selector - Selector for the element to find. * @returns The closest nodes. * @see {@link https://api.jquery.com/closest/} */ export declare function closest(this: Cheerio, selector?: AcceptedFilters): Cheerio; /** * Gets the next sibling of the first selected element, optionally filtered by a selector. * * @category Traversing * @example * * ```js * $('.apple').next().hasClass('orange'); * //=> true * ``` * * @param selector - If specified filter for sibling. * @returns The next nodes. * @see {@link https://api.jquery.com/next/} */ export declare const next: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Gets all the following siblings of the first selected element, optionally * filtered by a selector. * * @category Traversing * @example * * ```js * $('.apple').nextAll(); * //=> [
  • Orange
  • ,
  • Pear
  • ] * $('.apple').nextAll('.orange'); * //=> [
  • Orange
  • ] * ``` * * @param selector - If specified filter for siblings. * @returns The next nodes. * @see {@link https://api.jquery.com/nextAll/} */ export declare const nextAll: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Gets all the following siblings up to but not including the element matched * by the selector, optionally filtered by another selector. * * @category Traversing * @example * * ```js * $('.apple').nextUntil('.pear'); * //=> [
  • Orange
  • ] * ``` * * @param selector - Selector for element to stop at. * @param filterSelector - If specified filter for siblings. * @returns The next nodes. * @see {@link https://api.jquery.com/nextUntil/} */ export declare const nextUntil: (this: Cheerio, selector?: AcceptedFilters | null | undefined, filterSelector?: AcceptedFilters | undefined) => Cheerio; /** * Gets the previous sibling of the first selected element optionally filtered * by a selector. * * @category Traversing * @example * * ```js * $('.orange').prev().hasClass('apple'); * //=> true * ``` * * @param selector - If specified filter for siblings. * @returns The previous nodes. * @see {@link https://api.jquery.com/prev/} */ export declare const prev: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Gets all the preceding siblings of the first selected element, optionally * filtered by a selector. * * @category Traversing * @example * * ```js * $('.pear').prevAll(); * //=> [
  • Orange
  • ,
  • Apple
  • ] * * $('.pear').prevAll('.orange'); * //=> [
  • Orange
  • ] * ``` * * @param selector - If specified filter for siblings. * @returns The previous nodes. * @see {@link https://api.jquery.com/prevAll/} */ export declare const prevAll: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Gets all the preceding siblings up to but not including the element matched * by the selector, optionally filtered by another selector. * * @category Traversing * @example * * ```js * $('.pear').prevUntil('.apple'); * //=> [
  • Orange
  • ] * ``` * * @param selector - Selector for element to stop at. * @param filterSelector - If specified filter for siblings. * @returns The previous nodes. * @see {@link https://api.jquery.com/prevUntil/} */ export declare const prevUntil: (this: Cheerio, selector?: AcceptedFilters | null | undefined, filterSelector?: AcceptedFilters | undefined) => Cheerio; /** * Get the siblings of each element (excluding the element) in the set of * matched elements, optionally filtered by a selector. * * @category Traversing * @example * * ```js * $('.pear').siblings().length; * //=> 2 * * $('.pear').siblings('.orange').length; * //=> 1 * ``` * * @param selector - If specified filter for siblings. * @returns The siblings. * @see {@link https://api.jquery.com/siblings/} */ export declare const siblings: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Gets the children of the first selected element. * * @category Traversing * @example * * ```js * $('#fruits').children().length; * //=> 3 * * $('#fruits').children('.pear').text(); * //=> Pear * ``` * * @param selector - If specified filter for children. * @returns The children. * @see {@link https://api.jquery.com/children/} */ export declare const children: (this: Cheerio, selector?: AcceptedFilters | undefined) => Cheerio; /** * Gets the children of each element in the set of matched elements, including * text and comment nodes. * * @category Traversing * @example * * ```js * $('#fruits').contents().length; * //=> 3 * ``` * * @returns The children. * @see {@link https://api.jquery.com/contents/} */ export declare function contents(this: Cheerio): Cheerio; /** * Iterates over a cheerio object, executing a function for each matched * element. When the callback is fired, the function is fired in the context of * the DOM element, so `this` refers to the current element, which is equivalent * to the function parameter `element`. To break out of the `each` loop early, * return with `false`. * * @category Traversing * @example * * ```js * const fruits = []; * * $('li').each(function (i, elem) { * fruits[i] = $(this).text(); * }); * * fruits.join(', '); * //=> Apple, Orange, Pear * ``` * * @param fn - Function to execute. * @returns The instance itself, useful for chaining. * @see {@link https://api.jquery.com/each/} */ export declare function each(this: Cheerio, fn: (this: T, i: number, el: T) => void | boolean): Cheerio; /** * Pass each element in the current matched set through a function, producing a * new Cheerio object containing the return values. The function can return an * individual data item or an array of data items to be inserted into the * resulting set. If an array is returned, the elements inside the array are * inserted into the set. If the function returns null or undefined, no element * will be inserted. * * @category Traversing * @example * * ```js * $('li') * .map(function (i, el) { * // this === el * return $(this).text(); * }) * .toArray() * .join(' '); * //=> "apple orange pear" * ``` * * @param fn - Function to execute. * @returns The mapped elements, wrapped in a Cheerio collection. * @see {@link https://api.jquery.com/map/} */ export declare function map(this: Cheerio, fn: (this: T, i: number, el: T) => M[] | M | null | undefined): Cheerio; /** * Iterates over a cheerio object, reducing the set of selector elements to * those that match the selector or pass the function's test. * * This is the definition for using type guards; have a look below for other * ways to invoke this method. The function is executed in the context of the * selected element, so `this` refers to the current element. * * @category Traversing * @example Function * * ```js * $('li') * .filter(function (i, el) { * // this === el * return $(this).attr('class') === 'orange'; * }) * .attr('class'); //=> orange * ``` * * @param match - Value to look for, following the rules above. * @returns The filtered collection. * @see {@link https://api.jquery.com/filter/} */ export declare function filter(this: Cheerio, match: (this: T, index: number, value: T) => value is S): Cheerio; /** * Iterates over a cheerio object, reducing the set of selector elements to * those that match the selector or pass the function's test. * * - When a Cheerio selection is specified, return only the elements contained in * that selection. * - When an element is specified, return only that element (if it is contained in * the original selection). * - If using the function method, the function is executed in the context of the * selected element, so `this` refers to the current element. * * @category Traversing * @example Selector * * ```js * $('li').filter('.orange').attr('class'); * //=> orange * ``` * * @example Function * * ```js * $('li') * .filter(function (i, el) { * // this === el * return $(this).attr('class') === 'orange'; * }) * .attr('class'); //=> orange * ``` * * @param match - Value to look for, following the rules above. See * {@link AcceptedFilters}. * @returns The filtered collection. * @see {@link https://api.jquery.com/filter/} */ export declare function filter>(this: Cheerio, match: S): Cheerio; export declare function filterArray(nodes: T[], match: AcceptedFilters, xmlMode?: boolean, root?: Document): Element[] | T[]; /** * Checks the current list of elements and returns `true` if *any* of the * elements match the selector. If using an element or Cheerio selection, * returns `true` if *any* of the elements match. If using a predicate function, * the function is executed in the context of the selected element, so `this` * refers to the current element. * * @category Attributes * @param selector - Selector for the selection. * @returns Whether or not the selector matches an element of the instance. * @see {@link https://api.jquery.com/is/} */ export declare function is(this: Cheerio, selector?: AcceptedFilters): boolean; /** * Remove elements from the set of matched elements. Given a Cheerio object that * represents a set of DOM elements, the `.not()` method constructs a new * Cheerio object from a subset of the matching elements. The supplied selector * is tested against each element; the elements that don't match the selector * will be included in the result. * * The `.not()` method can take a function as its argument in the same way that * `.filter()` does. Elements for which the function returns `true` are excluded * from the filtered set; all other elements are included. * * @category Traversing * @example Selector * * ```js * $('li').not('.apple').length; * //=> 2 * ``` * * @example Function * * ```js * $('li').not(function (i, el) { * // this === el * return $(this).attr('class') === 'orange'; * }).length; //=> 2 * ``` * * @param match - Value to look for, following the rules above. * @param container - Optional node to filter instead. * @returns The filtered collection. * @see {@link https://api.jquery.com/not/} */ export declare function not(this: Cheerio, match: AcceptedFilters): Cheerio; /** * Filters the set of matched elements to only those which have the given DOM * element as a descendant or which have a descendant that matches the given * selector. Equivalent to `.filter(':has(selector)')`. * * @category Traversing * @example Selector * * ```js * $('ul').has('.pear').attr('id'); * //=> fruits * ``` * * @example Element * * ```js * $('ul').has($('.pear')[0]).attr('id'); * //=> fruits * ``` * * @param selectorOrHaystack - Element to look for. * @returns The filtered collection. * @see {@link https://api.jquery.com/has/} */ export declare function has(this: Cheerio, selectorOrHaystack: string | Cheerio | Element): Cheerio; /** * Will select the first element of a cheerio object. * * @category Traversing * @example * * ```js * $('#fruits').children().first().text(); * //=> Apple * ``` * * @returns The first element. * @see {@link https://api.jquery.com/first/} */ export declare function first(this: Cheerio): Cheerio; /** * Will select the last element of a cheerio object. * * @category Traversing * @example * * ```js * $('#fruits').children().last().text(); * //=> Pear * ``` * * @returns The last element. * @see {@link https://api.jquery.com/last/} */ export declare function last(this: Cheerio): Cheerio; /** * Reduce the set of matched elements to the one at the specified index. Use * `.eq(-i)` to count backwards from the last selected element. * * @category Traversing * @example * * ```js * $('li').eq(0).text(); * //=> Apple * * $('li').eq(-1).text(); * //=> Pear * ``` * * @param i - Index of the element to select. * @returns The element at the `i`th position. * @see {@link https://api.jquery.com/eq/} */ export declare function eq(this: Cheerio, i: number): Cheerio; /** * Retrieve one of the elements matched by the Cheerio object, at the `i`th position. * * @category Traversing * @example * * ```js * $('li').get(0).tagName; * //=> li * ``` * * @param i - Element to retrieve. * @returns The element at the `i`th position. * @see {@link https://api.jquery.com/get/} */ export declare function get(this: Cheerio, i: number): T; /** * Retrieve all elements matched by the Cheerio object, as an array. * * @category Traversing * @example * * ```js * $('li').get().length; * //=> 3 * ``` * * @returns All elements matched by the Cheerio object. * @see {@link https://api.jquery.com/get/} */ export declare function get(this: Cheerio): T[]; /** * Retrieve all the DOM elements contained in the jQuery set as an array. * * @example * * ```js * $('li').toArray(); * //=> [ {...}, {...}, {...} ] * ``` * * @returns The contained items. */ export declare function toArray(this: Cheerio): T[]; /** * Search for a given element from among the matched elements. * * @category Traversing * @example * * ```js * $('.pear').index(); * //=> 2 $('.orange').index('li'); * //=> 1 * $('.apple').index($('#fruit, li')); * //=> 1 * ``` * * @param selectorOrNeedle - Element to look for. * @returns The index of the element. * @see {@link https://api.jquery.com/index/} */ export declare function index(this: Cheerio, selectorOrNeedle?: string | Cheerio | Node): number; /** * Gets the elements matching the specified range (0-based position). * * @category Traversing * @example * * ```js * $('li').slice(1).eq(0).text(); * //=> 'Orange' * * $('li').slice(1, 2).length; * //=> 1 * ``` * * @param start - An position at which the elements begin to be selected. If * negative, it indicates an offset from the end of the set. * @param end - An position at which the elements stop being selected. If * negative, it indicates an offset from the end of the set. If omitted, the * range continues until the end of the set. * @returns The elements matching the specified range. * @see {@link https://api.jquery.com/slice/} */ export declare function slice(this: Cheerio, start?: number, end?: number): Cheerio; /** * End the most recent filtering operation in the current chain and return the * set of matched elements to its previous state. * * @category Traversing * @example * * ```js * $('li').eq(0).end().length; * //=> 3 * ``` * * @returns The previous state of the set of matched elements. * @see {@link https://api.jquery.com/end/} */ export declare function end(this: Cheerio): Cheerio; /** * Add elements to the set of matched elements. * * @category Traversing * @example * * ```js * $('.apple').add('.orange').length; * //=> 2 * ``` * * @param other - Elements to add. * @param context - Optionally the context of the new selection. * @returns The combined set. * @see {@link https://api.jquery.com/add/} */ export declare function add(this: Cheerio, other: string | Cheerio | S | S[], context?: Cheerio | string): Cheerio; /** * Add the previous set of elements on the stack to the current set, optionally * filtered by a selector. * * @category Traversing * @example * * ```js * $('li').eq(0).addBack('.orange').length; * //=> 2 * ``` * * @param selector - Selector for the elements to add. * @returns The combined set. * @see {@link https://api.jquery.com/addBack/} */ export declare function addBack(this: Cheerio, selector?: string): Cheerio; //# sourceMappingURL=traversing.d.ts.map