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

parseley

v0.12.1

Published

CSS selectors parser

Downloads

7,590,774

Readme

parseley

lint status badge test status badge License: MIT npm npm deno

Parser for CSS selectors.


Features

  • Convert CSS selector strings into objects that are easy to work with;

  • Serialize back if needed;

  • Get specificity for free.

Changelog

Available here: CHANGELOG.md.

Install

Node

> npm i parseley
import * as parseley from 'parseley';

Deno

import * as parseley from 'https://deno.land/x/parseley@.../parseley.ts';

Usage example

import { parse1, serialize, normalize } from 'parseley';
import { inspect } from 'node:util';

const str = 'div#id1 > .class2.class1[attr1]';

const ast = parse1(str);
console.log(inspect(ast, { breakLength: 45, depth: null }));

const serialized = serialize(ast);
console.log(`Serialized: '${serialized}'`);

normalize(ast);
const normalized = serialize(ast);
console.log(`Normalized: '${normalized}'`);
{
  type: 'compound',
  list: [
    {
      type: 'class',
      name: 'class2',
      specificity: [ 0, 1, 0 ]
    },
    {
      type: 'class',
      name: 'class1',
      specificity: [ 0, 1, 0 ]
    },
    {
      type: 'attrPresence',
      name: 'attr1',
      namespace: null,
      specificity: [ 0, 1, 0 ]
    },
    {
      type: 'combinator',
      combinator: '>',
      left: {
        type: 'compound',
        list: [
          {
            type: 'tag',
            name: 'div',
            namespace: null,
            specificity: [ 0, 0, 1 ]
          },
          {
            type: 'id',
            name: 'id1',
            specificity: [ 1, 0, 0 ]
          }
        ],
        specificity: [ 1, 0, 1 ]
      },
      specificity: [ 1, 0, 1 ]
    }
  ],
  specificity: [ 1, 3, 1 ]
}
Serialized: 'div#id1>.class2.class1[attr1]'
Normalized: 'div#id1>.class1.class2[attr1]'

Documentation

Input reference

https://www.w3.org/TR/selectors-4/#grammar

https://www.w3.org/TR/css-syntax-3/#token-diagrams

Terminology used in this project is more or less consistent to the spec, with some exceptions made for clarity. The term "type" is way too overloaded in particular, the term "tag" is used where appropriate instead.

Any pseudo elements are left for possible future implementation. I have no immediate need for them and they require some careful consideration.

Output AST

Consistency: overall AST shape is always the same. This makes client code simpler, at least for a certain processing tasks.

For example, always use compound selectors, even when there is only one simple selector inside.

Comma-separated selectors might not be needed for every use case. So there are two functions - one can parse commas and always returns the top-level list regardless of the comma presence in a particular selector, and the other can't parse commas and returns a compound selector AST directly.

Complex selectors are represented in the way that makes the left side to be an another condition on the right side element. This was made with the right-to-left processing direction in mind. One consequence of this is that there is no such thing as a "complex selector" node in the AST hierarchy, but there are "combinator" nodes attached to "compound selector" nodes.

All AST nodes have their specificity computed (except the top-level list of comma-separated selectors where it doesn't really make sense).

Motivation and inspiration

| Package | Hits | Misses | ---------- | --------- | --------- | parsel | Sensible AST; specificity calculation; cool name | Not friendly to node.js; based on regex | css-what and css-select | The idea to process complex selectors in right-to-left order | css-select is a solution for a different problem compared to what I needed; css-what produces only a list of tokens | scalpel | Introduced me to nearley parsing toolkit (albeit I'm not using it here anymore) | AST it produces is very far from what I can use | css-selector-parser | Configurable and lightweight | Again, AST is far from my needs