postcss-selector-parser

To protect against Denial-of-Service (DoS) attacks via deeply nested selectors (e.g., thousands of :not() pseudo-classes), the parser uses a nesting depth limit.

• Default limit: 256.
• Behavior: If nesting exceeds the limit, the parser throws a catchable Error instead of a RangeError: Maximum call stack size exceeded.
• Customization: You can tighten this limit when processing untrusted input by passing the maxNestingDepth option to .processSync() or .process().

Warning: Raising this value to an extremely high number in environments with small call stacks (like browser workers) may reintroduce stack overflow risks.

// Tighten the limit when parsing untrusted input:
parser().processSync(untrustedSelector, {maxNestingDepth: 128});

Extra whitespaces around a node are moved into node.spaces.before and node.spaces.after.

For descendant combinators, the value is always a single space (" "). Additional whitespace for descendant selectors is stored in node.spaces.before, node.raws.spaces.before, node.raws.spaces.after, or node.raws.value depending on the presence of comments.

Install the package using npm to use the selector parser in your project.

npm install postcss-selector-parser

When initializing a Processor, you can provide options to control how selectors are handled:

• lossless (boolean): When true, whitespace is preserved. Defaults to true. Set to false to normalize whitespace (e.g., removing extra spaces).
• updateSelector (boolean): When true, if a processor method is passed a PostCSS Rule node instead of a string, the Rule's selector is automatically updated with the processed result. Defaults to true.

You can use the parser to walk through a selector's Abstract Syntax Tree (AST) and perform transformations. Pass a function to the parser that receives the selectors object, then use .walk() to iterate over individual nodes.

Note: parser(transform) creates a parser instance configured with your transformation logic. .processSync() then executes that logic on the provided selector string.

const parser = require('postcss-selector-parser');
const transform = selectors => {
    selectors.walk(selector => {
        // do something with the selector
        console.log(String(selector))
    });
};

const transformed = parser(transform).processSync('h1, h2, h3');

To remove unnecessary whitespace from a selector string, use .processSync() with the {lossless: false} option. This will return a minified version of the selector.

Example: h1, h2, h3 becomes h1,h2,h3.

const parser = require('postcss-selector-parser');
const normalized = parser().processSync('h1, h2, h3', {lossless: false});
// -> h1,h2,h3

The parser function is the main entry point for the module. You can use it to create a new processor instance. You can optionally provide a transform function that operates on the parsed AST, or an options object to set default options for the returned Processor.

const parser = require('postcss-selector-parser');

// Create a processor without a transform function
const processor = parser();

// Create a processor with a transform function
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};
const processor = parser(transform);

// Process a selector string
const result = processor.processSync('*.class');
// => .class

Nodes can be navigated within the tree structure:

• node.parent: Returns the parent node.
• node.next(): Returns the next child of the parent node.
• node.prev(): Returns the previous child of the parent node.

// Check parent relationship
root.nodes[0].parent === root;

// Check next sibling
const next = id.next();
if (next && next.type !== 'combinator') {
    throw new Error('Qualified IDs are not allowed!');
}

The container.split(callback) method allows you to divide a group of nodes into an array of arrays based on a condition. The callback receives a node and should return true to trigger a split.

Example: Splitting a selector string by combinators.

// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
    return selector.type === 'combinator';
});

// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]