parsel-js

library1.2.2jsnpmunverified

Parsel.js is a lightweight and permissive JavaScript library designed for parsing CSS selectors and calculating their specificity. It provides a robust Abstract Syntax Tree (AST) representation of selectors, enabling developers to analyze, manipulate, or traverse selector structures. The current stable version is 1.2.2, with releases occurring relatively frequently, including both patch and minor updates to address bugs and introduce new features like support for relative selector lists. Key differentiators include its minimal footprint and forgiving parsing logic, making it suitable for environments where strict CSS validation might be too restrictive. It also includes built-in functionality for computing the CSS specificity of any given selector.

serialization

npm install parsel-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PARSEL-JS

parsel-js

serializationjavascriptv1.2.2

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.

parse

✓ import { parse } from 'parsel-js';

✗ const parse = require('parsel-js').parse;

Primary function for parsing a CSS selector string into an AST. Use named import for ESM.

specificity

✓ import { specificity } from 'parsel-js';

✗ const specificity = require('parsel-js').specificity;

Calculates the CSS specificity of a given selector string. Available via named import.

walk

✓ import { walk } from 'parsel-js';

✗ const walk = require('parsel-js').walk;

Traverses the AST of a parsed selector, allowing for custom callbacks at each node. Use named import.

CommonJS require

✓ const { parse, specificity } = require('parsel-js');

✗ const parsel = require('parsel-js'); // Then parsel.parse()

While CommonJS is supported, directly destructuring named exports is generally preferred for clarity.

Demonstrates parsing a complex CSS selector, calculating its specificity, and walking its AST.

import { parse, specificity, walk } from 'parsel-js'; const selectorString = 'div.container > p:nth-child(2)[data-test="value"]'; // Parse the selector into an Abstract Syntax Tree (AST) const ast = parse(selectorString); console.log('Parsed AST:', JSON.stringify(ast, null, 2)); /* Example AST output (truncated for brevity): { "type": "list", "list": [ { "type": "complex", "left": {"type": "type", "name": "div"}, "combinator": " ", "right": {"type": "compound", ...} } ] } */ // Calculate the CSS specificity of the selector const spec = specificity(selectorString); console.log(`Specificity of '${selectorString}': (${spec.a}, ${spec.b}, ${spec.c})`); // e.g., (0, 1, 2) or similar // Walk the AST to inspect nodes console.log('\nWalking the AST:'); walk(ast, (node) => { console.log(` Node Type: ${node.type}${node.name ? ' - Name: ' + node.name : ''}`); });

Debug

Known issues

gotchaThe v1.2.0 release on npm was reportedly 'broken' and required a v1.2.1 patch solely to fix publishing issues. Users who installed v1.2.0 might have encountered unexpected problems or incomplete packages.

fix

Ensure you are using v1.2.1 or later. If locked to v1.2.0, update to v1.2.1 to get the correctly published package.

affects: 1.2.0

gotchaVersion 1.1.2 introduced a change to use the `.cjs` extension for CommonJS entrypoints. While generally a fix for correct module resolution, it could theoretically cause issues in specific, older bundler configurations or environments that do not correctly resolve `.cjs` files.

fix

Ensure your build tooling and environment correctly handle CommonJS modules with the `.cjs` extension. If encountering module resolution errors, check your `tsconfig.json` or bundler configuration.

affects: >=1.1.2

gotchaEarlier versions (pre-1.0.3) had issues with parsing trimmed attribute selector values and quoted attributes, sometimes returning incorrect results or '§' for quoted values.

fix

Upgrade to version 1.0.3 or later to ensure correct parsing of attribute selectors, especially those with quotes or leading/trailing whitespace in values.

affects: <1.0.3

Errors

Common errors & fixes

Module not found: Can't resolve 'parsel-js'

Incorrect module resolution due to environment or outdated build tools, potentially related to the `.cjs` entrypoint change.

fix

Verify that your build system (e.g., Webpack, Rollup) and TypeScript configuration (if applicable) are up-to-date and correctly configured to resolve `parsel-js`. For TypeScript, ensure `moduleResolution` is set appropriately (e.g., `NodeNext` or `Bundler`).

SyntaxError: Unexpected token 'export'

Attempting to use `parsel-js`'s ESM exports in a CommonJS-only environment without proper transpilation or configuration.

fix

For CommonJS, use `const { parse } = require('parsel-js');`. If you need ESM features in a CommonJS environment, configure your bundler (like Webpack) to transpile `node_modules` or ensure your Node.js version supports ESM via `type: "module"` in `package.json`.

Parsed selector with empty string attribute value is incorrect.

Bug in older versions where empty string attribute values were not parsed correctly.

fix

Upgrade to `parsel-js` version 1.2.2 or higher, which includes a fix for empty string attribute parsing.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/LeaVerou/parsel ↗

packagehttps://www.npmjs.com/package/parsel-js ↗

homepagehttps://parsel.verou.me/ ↗