parseley

library0.13.1jsnpmunverified

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.

serialization

npm install parseley

github ↗package ↗

INSTALL

IMPORT

SIG · PARSELEY

parseley

serializationjavascriptv0.13.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse1

✓ import { parse1 } from 'parseley';

✗ import parse1 from 'parseley'; const { parse1 } = require('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

✓ import { serialize } from 'parseley';

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

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

normalize

✓ import { normalize } from 'parseley';

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

This function modifies the AST in-place to ensure a consistent, normalized order of simple selectors within a compound selector node.

parseley (namespace)

✓ import * as parseley from 'parseley';

✗ const parseley = require('parseley');

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

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}'`);

Debug

Known issues

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

affects: >=0.1.0

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

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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 ','

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

Upgrade

Version history

0.13.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/mxxii/parseley ↗

packagehttps://www.npmjs.com/package/parseley ↗