nwmatcher

library1.4.4jsnpmunverified

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.

serialization web-framework

npm install nwmatcher

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NWMATCHER

nwmatcher

serializationjavascriptv1.4.4

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.

nwmatcher

✓ import * as nwmatcher from 'nwmatcher';

✗ import nwmatcher from 'nwmatcher';

For TypeScript with CommonJS interop, `import * as nwmatcher` is recommended. The `nwmatcher` module object provides the `init` method, which is necessary to configure the engine with a DOM `window` object in headless environments like Node.js with JSDOM.

✓ import * as nwmatcher from 'nwmatcher'; const NW = nwmatcher.init(window);

✗ import { select, match } from 'nwmatcher';

The `NW` object (often referenced as `NW.Dom` in browser contexts) is the primary API entry point containing methods like `select`, `first`, and `match`. In Node.js, it's obtained by calling `nwmatcher.init(window)`. In browsers, `NW.Dom` is globally available after including the script.

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: "#"

Debug

Known issues

breakingClass attribute selectors became case-sensitive to mimic browser behavior more closely.

fix

Ensure all class names in selectors match the exact casing used in the HTML/DOM. Prior to v1.4.1, case-insensitivity might have been tolerated, leading to unexpected failures post-update.

affects: >=1.4.1

gotchaImproved DOM walking in `v1.4.2` explicitly avoids using unsupported DOM methods on non-'Element' nodes. While a fix, it might subtly alter behavior if previous versions erroneously processed non-element nodes in specific selector contexts.

fix

Review selectors that might implicitly target or interact with non-Element nodes (e.g., text nodes, comments). Ensure selectors are robust and explicitly target `Element` nodes where necessary.

affects: >=1.4.2

gotchaThe `configure()` method allows disabling native Query Selector API (`USE_QSAPI: false`) or disallowing complex selectors nested in `:not()` classes (`SIMPLENOT: true`). Misconfiguration can lead to unexpected selection results or performance characteristics.

fix

Always explicitly configure NWMatcher using `NW.configure({ USE_QSAPI: true, SIMPLENOT: false })` or similar, depending on your needs. For full CSS3 compliance and performance, it's often best to enable native QSA and allow complex `:not()` selectors unless specific compatibility issues arise.

affects: >=1.3.4

gotchaA minimal `nwmatcher-noqsa.js` version is available, specifically recommended for headless environments or older browsers like IE < 9 that lack robust native Query Selector API support. Using the full version in these environments when `USE_QSAPI` is enabled might lead to errors or degraded performance.

fix

For environments without native `querySelectorAll` (or where it's buggy), consider using `nwmatcher-noqsa.js` and configuring NWMatcher with `USE_QSAPI: false` to force its internal engine. For Node.js with JSDOM, using the full version with `USE_QSAPI: true` is generally fine.

affects: >=1.3.0

Errors

Common errors & fixes

ReferenceError: NW is not defined

In Node.js or other headless environments, the NWMatcher engine needs to be explicitly initialized with a DOM `window` object, and the resulting API object assigned to a variable.

fix

Instead of expecting a global `NW.Dom`, use `const nwmatcher = require('nwmatcher'); const NW = nwmatcher.init(window);` (for CommonJS) or `import * as nwmatcher from 'nwmatcher'; const NW = nwmatcher.init(window);` (for ES Modules/TypeScript with JSDOM's `window` object).

Selectors using class names are failing to match elements that previously worked.

Since `v1.4.1`, class attribute selectors became case-sensitive, mimicking browser behavior. If your HTML or selectors used mixed casing (e.g., class `MyClass` but selector `.myclass`), they will no longer match.

fix

Ensure that the casing of class names in your CSS selectors precisely matches the casing of the `class` attributes in your HTML/DOM structure.

NWMatcher throws errors/warnings to the console despite `LOGERRORS` being set to `false`.

While `LOGERRORS: false` in `configure()` mutes standard logging, the `v1.4.0` release notes mention an additional 'shunt flag' for muting *all* errors/warnings, implying `LOGERRORS` might not cover all scenarios or there could be a default verbosity.

fix

Ensure `NW.configure({ VERBOSITY: false, LOGERRORS: false });` is used to suppress both thrown exceptions and console logging. If issues persist, verify if a specific 'shunt' method or configuration option was introduced or needs to be set.

Upgrade

Version history

1.4.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/dperini/nwmatcher ↗

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

homepagehttp://javascript.nwbox.com/NWMatcher/ ↗