selery

    0.0.10 • Public • Published

    selery

    selery is a small, handwritten CSS selector parser and DOM query engine.

    It aims to be compliant with the relevant specifications (CSS Syntax Level 3, CSS Selectors Level 4, and others), while remaining compact and understandable so that it can be used as a starting point to experiment with new CSS syntax.

    ⚠️ Currently a work-in-progress

    Getting started

    selery on npm selery on bundlephobia

    You can install selery as an npm package:

    npm install selery

    Alternatively, head over to the latest release and download the selery-<version>.zip file from under Assets. The archive contains the library built in several variants to choose from, suitable for both browsers and Node.js.

    Or fetch the library from Unpkg by including this in your web page:

    <script src="https://unpkg.com/selery"></script>

    Or, to bring the library into any web page you're on (as long as its configuration doesn't prevent it), bring up the browser's Console and paste this snippet:

    with(document)body.appendChild(createElement`script`).src = '//unpkg.com/selery';

    When used with a <script> tag, the library is available under the selery global variable.

    API reference

    tokenize(selector)

    Takes a string selector and returns an array of tokens.

    let { tokenize } = require('selery');
     
    tokenize('article a[href="#"]');

    A token is a plain object having a type property, along with other optional properties, which are documented in the CSS token reference. For the sample selector 'article a[href="#"]' mentioned above, the resulting token array is:

    [
        { type: 'ident', value: 'article' },
        { type: 'whitespace' },
        { type: 'ident', value: 'a' },
        { type: '[' },
        { type: 'ident', value: 'href' },
        { type: 'delim', value: '=' },
        { type: 'string', value: '#' },
        { type: ']' }
    ];

    The function will throw an erorr if the selector supplied does not follow generally valid CSS syntax.

    parse(input, options)

    Accepts an input argument, which can be either an array of tokens obtained from the tokenize() function or, more conveniently, a string representing a selector. The latter is passed through tokenize() internally.

    It produces an abstract syntax tree (AST), also called a parse tree, for the provided input.

    let { parse } = require('selery');
     
    let tree = parse('div > span:nth-child(3)');

    Available options:

    syntax (Object) — provide custom microsyntaxes to various pseudo-classes and pseudo-elements. By default, the argument of :nth-*() pseudo-classes are parsed with the An+B microsyntax, while for the :is(), :where(), :not(), and :has(), the argument is parsed as a SelectorList.

    The keys to the syntax object are the identifier for the pseudo-class (prefixed by :) or pseudo-element (prefixed by ::), and the values are either strings (one of None, AnPlusB, or SelectorList) or functions. Function values will receive an array of tokens and can return anything suitable for storing in the AST node's argument key.

    parse(':nth-child(3)', {
        syntax: {
            /* Change the microsyntax of a pseudo-class */
            ':nth-child': 'None',
     
            /* A microsyntax defined as a function */
            ':magic': tokens => tokens.map(t => t.value).join('')
        }
    });

    serialize(input)

    Converts the input back into a string. The input argument can be either an array of tokens, or an object representing a parse tree.

    DOM API shims

    Shims for selector-accepting DOM methods using simpler DOM primitives.

    Across these methods:

    • the selector argument can be a string (as with their native DOM counterparts), an array of tokens, or an object representing a parse tree;
    • the options object accepts the following keys:
      • root (Element) — an optional scoping root;
      • scope (Element | Array) — an optional set of :scope elements.

    matches(element, selector, options)

    See the Element.matches DOM method.

    closest(element, selector, options)

    See the Element.closest DOM method.

    querySelector(element, selector, options)

    See the Element.querySelector DOM method.

    querySelectorAll(element, selector, options)

    See the Element.querySelectorAll DOM method. While the native DOM method return a NodeList, our implementation of querySelectorAll returns an Array.

    CSS token reference

    Token type Additional properties
    dimension value, unit
    at-keyword, function, hash, ident, number, string, delim value
    ), (, }, {, ], [, colon, comma, semicolon, whitespace none

    CSS selector AST reference

    All nodes in the AST contain a type property, and additional properties for each specific type, listed below.

    SelectorList

    The topmost node in the AST.

    • selectors — an array of (possibly complex) selectors.

    ComplexSelector

    A complex selector represents a pair of selectors stringed together with combinators, such as article > p.

    • left — the left-side (possibly complex, or compound) selector; null when the selector is relative, such as the > img in a:has(> img);
    • right — the right-side (possibly complex, compound) selector;
    • combinator — one of , >, ~, +, ||

    Longer sequences of selectors are represented with nested ComplexSelector elements in the AST. For example, article > p span is represented as:

    {
        type: 'SelectorList',
        selectors: [{
            type: 'ComplexSelector',
            left: {
                type: 'ComplexSelector',
                left: {
                    type: 'TypeSelector',
                    identifier: 'article'
                },
                right: {
                    type: 'TypeSelector',
                    identifier: 'p'
                },
                combinator: ' ',
            },
            right: {
                type: 'TypeSelector',
                identifier: 'span'
            },
            combinator: ' '
        }]
    }

    CompoundSelector

    A compound selector is a combination of simple selectors, all of which impose conditions on a single element, such as a.external[href$=".pdf"].

    • selectors — an array of simple selectors.

    TypeSelector

    Represents a type selector, such as article.

    • identifier (String) — the element type to match; can be * in the case of the universal selector;
    • namespace (String) — the namespace, if provided with the namespace|type syntax; an empty string corresponds to the |type syntax.

    IdSelector

    Represents an ID selector, such as #main.

    • identifier (String) — the ID to match;

    ClassSelector

    Represents a class selector, such as .primary.

    • identifier (String) — the class name to match;

    AttributeSelector

    Represents an attribute selector, such as [href^="http"].

    • identifier (String) — the attribute to match;
    • value (String) — the value to match against;
    • matcher (String) — one of =, ^=, $=, *=, ~=, |=;
    • modifier (String) — either s or i, if any.

    PseudoClassSelector and PseudoElementSelector

    Represents a pseudo-class selector (such as :visited or :is(a, b, c)) or a pseudo-element (such as ::before), respectively.

    Both types of nodes share a common structure:

    • identifier (String) — the pseudo-class or pseudo-element;
    • argument (Anything) — the argument to the pseudo-class / pseudo-element;

    In CSS, there is more than one way to interpret the argument passed to pseudo-classes and pseudo-elements which expressed with the function notation. Some pseudo-classes, such as :nth-*(), use the An+B microsyntax, others accept a list of selectors.

    You can control how the microsyntaxes get applied to the pseudo-classes and pseudo-elements with the syntax option on the parse() method.

    Supported selectors

    TODO

    See also

    Colophon

    The selery logo is typeset in Manicotti by David Jonathan Ross.

    Install

    npm i selery

    DownloadsWeekly Downloads

    13

    Version

    0.0.10

    License

    MIT

    Unpacked Size

    146 kB

    Total Files

    14

    Last publish

    Collaborators

    • danburzo