npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

cheerio-advanced-selectors

v2.0.1

Published

Add advanced selector support to cheerio

Downloads

7,535

Readme

cheerio-advanced-selectors

Add support for the following selectors to cheerio:

  • :first
  • :last
  • :eq(index)

More selectors can easily be added: Just open an issue and I'll look into it :)

Build status js-standard-style

This module is inspired by cheerio-eq with the added support for many different selectors.

Supports cheerio version 0.18.0 and above.

Installation

npm install cheerio-advanced-selectors

Usage

Use the .wrap() function to make cheerio-advanced-selectors take care of everything for you:

var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')

cheerio = cheerioAdv.wrap(cheerio)

var $ = cheerio.load('<div>foo</div><div>bar</div>')

$('div:first').text() // => 'foo'

Advanced usage

Alternatively use the .find() function to only use cheerio-advanced-selectors for a specific selector:

var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')

var $ = cheerio.load('<div><span>foo</span></div><div><span>bar</span></div>')

cheerioAdv.find($, 'div:eq(1)').text() // => 'bar'

If you need to run the same selector on a lot of different HTML documents, you can speed things up by pre-compiling the selector using the .compile() function:

var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')

var myH1 = cheerioAdv.compile('div:first span:eq(1) h1')

var html1 = cheerio.load('<div><span><h1>foo1</h1></span><span><h1>bar1</h1></span></div>')
var html2 = cheerio.load('<div><span><h1>foo2</h1></span><span><h1>bar2</h1></span></div>')

myH1(html1).text() // => 'bar1'
myH1(html2).text() // => 'bar2'

What's the problem?

Cheerio sacrifices advanced CSS selector support for speed. This means for instance that the :eq() selector isn't supported. The work-around is normally to use the .eq() function instead:

// this will not work:
$('div:eq(1)');

// use this instead:
$('div').eq(1);

This is a good alternative if you write the CSS selectors from scrach, but what if you are working with selectors that already contain :eq()? Don't fear, cheerio-advanced-selectors is here :)

Solution

The solution to the problem is to automatically parse the selector string at run-time. So if you give cheerio-advanced-selectors a selector like div:eq(1) it will return the following cheerio cursor: $('div').eq(1).

It also works for complex selectors, so that div:eq(1) h2:first span will be converted and interpreted as $('div').eq(1).find('h2').first().find('span').

Supported advanced selectors

This module currently only support a minimal subset of the possible advanced selectors:

  • :first
  • :last
  • :eq(index)

But don't fear :) It's easy to add support for other selectors. Just open an issue or make a pull request.

API

.wrap(cheerio)

Wraps the main cheerio module to overload the standard load function so it knows how to handle the advanced selectors.

Returns the cheerio module.

.find(cheerio, selector [, context [, root]])

Run the selector on the given cheerio object optionally within the given context and optionally on the given root.

The cheerio object is usually called $.

.compile(selector)

Compiles the selector and returns a function which take 3 arguments: fn(cheerio [, context [, root]]):

  • cheerio - a reference to the cheerio object (usually called $)
  • context - the context in which to run the selector (optional)
  • root - the HTML root on which to run the selector (optional)

License

MIT