{"id":15752,"library":"parseley","title":"Parseley: CSS Selectors Parser","description":"Parseley is a JavaScript/TypeScript library designed for parsing CSS selector strings into a structured Abstract Syntax Tree (AST) and for serializing those ASTs back into strings. It also automatically calculates CSS specificity for each selector component. As of version 0.13.1, the library provides core functionalities such as `parse1` for parsing individual selectors, `serialize` for converting an AST back into a CSS string, and `normalize` for standardizing the order of simple selectors within an AST. It ships with comprehensive TypeScript types and is compatible with both Node.js and Deno environments. Parseley's AST structure is optimized for right-to-left processing, representing complex selectors via 'combinator' nodes integrated into 'compound' selectors rather than distinct 'complex selector' nodes. The library maintains a consistent overall AST shape, aiming to simplify client-side processing tasks.","status":"active","version":"0.13.1","language":"javascript","source_language":"en","source_url":"https://github.com/mxxii/parseley","tags":["javascript","CSS","selectors","parser","AST","serializer","specificity","typescript"],"install":[{"cmd":"npm install parseley","lang":"bash","label":"npm"},{"cmd":"yarn add parseley","lang":"bash","label":"yarn"},{"cmd":"pnpm add parseley","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`parse1` is specifically designed for parsing a single CSS selector string. For inputs potentially containing multiple, comma-separated selectors, a different parsing function should be used.","wrong":"import parse1 from 'parseley';\nconst { parse1 } = require('parseley');","symbol":"parse1","correct":"import { parse1 } from 'parseley';"},{"note":"Used to convert a `parseley` AST object back into its corresponding CSS selector string representation.","wrong":"const serialize = require('parseley').serialize;","symbol":"serialize","correct":"import { serialize } from 'parseley';"},{"note":"This function modifies the AST in-place to ensure a consistent, normalized order of simple selectors within a compound selector node.","wrong":"const normalize = require('parseley').normalize;","symbol":"normalize","correct":"import { normalize } from 'parseley';"},{"note":"Imports all named exports into a single namespace object, useful for accessing multiple utilities like `parseley.parse1`.","wrong":"const parseley = require('parseley');","symbol":"parseley (namespace)","correct":"import * as parseley from 'parseley';"}],"quickstart":{"code":"import { parse1, serialize, normalize } from 'parseley';\nimport { inspect } from 'node:util';\n\nconst str = 'div#id1 > .class2.class1[attr1]';\n\n// Parse the CSS selector string into an AST\nconst ast = parse1(str);\nconsole.log('Parsed AST:', inspect(ast, { breakLength: 45, depth: null }));\n\n// Serialize the AST back into a CSS selector string\nconst serialized = serialize(ast);\nconsole.log(`Serialized: '${serialized}'`);\n\n// Normalize the AST (e.g., reorder simple selectors) and then serialize again\nnormalize(ast);\nconst normalized = serialize(ast);\nconsole.log(`Normalized: '${normalized}'`);\n","lang":"typescript","description":"Demonstrates how to parse a CSS selector string into an AST, serialize the AST back to a string, and normalize the AST structure."},"warnings":[{"fix":"Consult the API documentation to identify the function designed for parsing multiple, comma-separated CSS selectors (e.g., `parse`) if your input can contain them. Use `parse1` strictly for individual selector strings.","message":"Parseley provides distinct parsing functions for single CSS selectors versus potentially comma-separated lists of selectors. Using `parse1` (which handles single selectors) with an input string containing multiple, comma-separated selectors will lead to a parsing error or an incomplete AST. Always ensure you are using the correct parsing function for your input type.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When traversing or programmatically interacting with the AST, expect combinators to appear as 'combinator' type nodes within 'compound' selector structures, rather than as top-level 'complex selector' nodes. Adapt your AST processing logic to handle `combinator` nodes with their associated `left` and `right` compound selectors.","message":"The internal AST representation for complex selectors in Parseley does not use a dedicated 'complex selector' node type. Instead, combinators (e.g., `>`, `+`, `~`, ` `) are represented as nodes attached to `compound` selector nodes, with `left` and `right` properties. This design is optimized for right-to-left processing.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Migrate your import statements from `const { symbol } = require('parseley');` to `import { symbol } from 'parseley';` to align with ES Module syntax.","cause":"Attempting to use CommonJS `require()` syntax to import Parseley in an ES Module context (e.g., a Node.js project with `\"type\": \"module\"` in `package.json` or a modern browser environment).","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are using named imports for all Parseley functions: `import { parse1, serialize, normalize } from 'parseley';`. If using a namespace import, access via `parseley.parse1`.","cause":"Incorrectly importing a named export (like `parse1`, `serialize`, or `normalize`) as a default import, or attempting to access it as a property of a non-existent default export.","error":"TypeError: parse1 is not a function"},{"fix":"If your input string contains multiple comma-separated selectors, use the dedicated parsing function for selector lists (e.g., `parse`, if available in the API documentation), or manually split the string by commas and parse each segment individually with `parse1`.","cause":"Using the `parse1` function with a CSS selector string that contains multiple selectors separated by commas (e.g., `'div, span'`). `parse1` is designed to parse only a single selector.","error":"Error: Unexpected token ','"}],"ecosystem":"npm"}