Parseley: CSS Selectors Parser

Common errors

• ReferenceError: require is not defined

  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).
  fix Migrate your import statements from `const { symbol } = require('parseley');` to `import { symbol } from 'parseley';` to align with ES Module syntax.

• TypeError: parse1 is not a function

  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.
  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`.

• Error: Unexpected token ','

  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.
  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`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install parseley npm
• yarn add parseley yarn
• pnpm add parseley pnpm

Imports

• parse1
  wrong:

  import parse1 from 'parseley';
  const { parse1 } = require('parseley');

  correct:

  import { parse1 } from 'parseley';

  `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.
• serialize
  wrong:

  const serialize = require('parseley').serialize;

  correct:

  import { serialize } from 'parseley';

  Used to convert a `parseley` AST object back into its corresponding CSS selector string representation.
• normalize
  wrong:

  const normalize = require('parseley').normalize;

  correct:

  import { normalize } from 'parseley';

  This function modifies the AST in-place to ensure a consistent, normalized order of simple selectors within a compound selector node.
• parseley (namespace)
  wrong:

  const parseley = require('parseley');

  correct:

  import * as parseley from 'parseley';

  Imports all named exports into a single namespace object, useful for accessing multiple utilities like `parseley.parse1`.

Quickstart

Demonstrates how to parse a CSS selector string into an AST, serialize the AST back to a string, and normalize the AST structure.

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

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

// Parse the CSS selector string into an AST
const ast = parse1(str);
console.log('Parsed AST:', inspect(ast, { breakLength: 45, depth: null }));

// Serialize the AST back into a CSS selector string
const serialized = serialize(ast);
console.log(`Serialized: '${serialized}'`);

// Normalize the AST (e.g., reorder simple selectors) and then serialize again
normalize(ast);
const normalized = serialize(ast);
console.log(`Normalized: '${normalized}'`);