NWMatcher CSS Selector Engine

1.4.4 · active · verified Sun Apr 19

NWMatcher is a fast and W3C CSS3-compliant JavaScript selector engine, currently at version 1.4.4. It provides robust methods for selecting, matching, and traversing DOM elements using CSS selectors, aiming for behavior consistent with modern web browsers. The library is actively maintained through regular bug fixes, performance enhancements, and improved compliance with CSS specifications, particularly for headless environments like Node.js with JSDOM. It distinguishes itself by offering a reliable, standalone solution for scenarios where native `querySelectorAll` might not be available, or when fine-grained control over selector parsing and matching is required. This includes comprehensive support for CSS2/CSS3 selectors, pseudo-classes, and extensive configuration options to tailor its behavior. Recent releases focus on addressing specific behavioral quirks, optimizing DOM traversal, and ensuring broad W3C compatibility across diverse environments.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates initializing NWMatcher in a Node.js JSDOM environment, performing various DOM selections, matching elements, and configuring engine options. It covers `select`, `first`, `match`, `byId`, `getAttribute` methods and `configure`.

import { JSDOM } from 'jsdom';
import * as nwmatcher from 'nwmatcher'; // For TypeScript with CommonJS interop

// 1. Setup a JSDOM environment to simulate a browser DOM
const dom = new JSDOM(`<!DOCTYPE html>
<html>
  <head>
    <title>NWMatcher Example</title>
  </head>
  <body>
    <div id="container">
      <p class="text important">First paragraph</p>
      <span class="text">A span element</span>
      <p class="text">Second paragraph</p>
      <a href="#" class="link">Click here</a>
    </div>
    <div id="other-container">
      <p>Another paragraph in a different container</p>
      <button id="myButton" disabled>Submit</button>
    </div>
  </body>
</html>`);

const { window } = dom;
const document = window.document;

// 2. Initialize NWMatcher with the JSDOM window object for headless environments.
// In a browser, NW.Dom would typically be available globally.
const NW = nwmatcher.init(window);

console.log('--- DOM Selection Examples ---');

// Select all elements matching a selector
const allParagraphs = NW.select('p', document);
console.log(`Found ${allParagraphs.length} paragraphs.`);
// Expected: 3 paragraphs

// Select the first element matching a selector
const firstImportantParagraph = NW.first('p.important', document);
console.log(`First important paragraph text: "${firstImportantParagraph?.textContent}"`);
// Expected: "First paragraph"

// Match an element against a selector
const targetElement = document.getElementById('myButton');
const matchesDisabled = NW.match(targetElement, ':disabled');
console.log(`Button matches ':disabled': ${matchesDisabled}`);
// Expected: true

// Using context for selection
const container = document.getElementById('container');
const paragraphsInContainer = NW.select('.text', container);
console.log(`Found ${paragraphsInContainer.length} elements with class 'text' within #container.`);
// Expected: 3 (p.text.important, span.text, p.text)

console.log('\n--- Engine Configuration Example ---');
// Disable native Query Selector API usage and suppress errors for demonstration
NW.configure({ USE_QSAPI: false, VERBOSITY: false, LOGERRORS: false });
console.log('NWMatcher configured to not use native QSA and suppress errors.');

// Re-run a selection with new configuration
const allLinks = NW.select('a.link');
console.log(`Found ${allLinks.length} links after re-configuration.`);
// Expected: 1 link

// Example of DOM helper method
const myButtonElement = NW.byId('myButton');
console.log(`Found button by ID: ${myButtonElement?.id}`);
// Expected: "myButton"

// Example of attribute getter
const linkHref = NW.getAttribute(allLinks[0], 'href');
console.log(`Href of the link: ${linkHref}`);
// Expected: "#"

view raw JSON →