tessl/npm-nwsapi
Fast CSS Selectors API Engine that serves as a cross-browser replacement for native CSS selection and matching functionality
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
dom-selection.mddocs/
DOM Selection
Core CSS selector-based element selection functionality providing comprehensive querying capabilities with high performance through compiled resolvers and memoization.
Capabilities
Select Function
Returns an array of all elements matching the specified CSS selector within the given context.
/**
* Returns array of all elements matching selector
* @param selector - CSS selector string
* @param context - Search context element (defaults to document)
* @param callback - Optional callback invoked for each match
* @returns Array of matching elements
*/
function select(selector, context, callback);Usage Examples:
const nwsapi = require("nwsapi");
// Basic selection
const paragraphs = nwsapi.select('p', document);
// With context
const links = nwsapi.select('a', document.getElementById('nav'));
// Complex selectors
const elements = nwsapi.select('div.container > p:first-child', document);
// With callback
nwsapi.select('.highlight', document, function(element) {
console.log('Found highlighted element:', element);
});
// Advanced CSS4 selectors
const matches = nwsapi.select(':has(> img)', document);
const scopedElements = nwsapi.select(':scope > div', container);Match Function
Tests whether an element matches the specified CSS selector.
/**
* Tests if element matches selector
* @param selector - CSS selector string
* @param element - Element to test
* @param callback - Optional callback invoked for matched element
* @returns Boolean indicating match
*/
function match(selector, element, callback);Usage Examples:
const nwsapi = require("nwsapi");
// Basic matching
const isButton = nwsapi.match('button', element);
const hasClass = nwsapi.match('.active', element);
// Complex matching
const isFirstChild = nwsapi.match(':first-child', element);
const matchesComplex = nwsapi.match('div.container > p:nth-child(2n+1)', element);
// With callback
const matched = nwsapi.match('.important', element, function(el) {
console.log('Element matches important class');
});First Function
Returns the first element matching the specified CSS selector within the given context.
/**
* Returns first element matching selector
* @param selector - CSS selector string
* @param context - Search context element (defaults to document)
* @param callback - Optional callback invoked for matched element
* @returns First matching element or null
*/
function first(selector, context, callback);Usage Examples:
const nwsapi = require("nwsapi");
// Find first match
const firstParagraph = nwsapi.first('p', document);
const firstButton = nwsapi.first('button.primary', document);
// With context
const firstLink = nwsapi.first('a', navigation);
// Complex selectors
const firstChild = nwsapi.first('div:first-child', container);
const firstOfType = nwsapi.first('h1:first-of-type', document);Closest Function
Returns the nearest ancestor element (including the element itself) that matches the specified CSS selector.
/**
* Returns nearest ancestor matching selector
* @param selector - CSS selector string
* @param context - Starting element
* @param callback - Optional callback invoked for matched element
* @returns Nearest matching ancestor or null
*/
function closest(selector, context, callback);Usage Examples:
const nwsapi = require("nwsapi");
// Find closest ancestor
const form = nwsapi.closest('form', inputElement);
const container = nwsapi.closest('.container', element);
// Navigate up DOM tree
const listItem = nwsapi.closest('li', element);
const section = nwsapi.closest('section, article', element);
// With callback
const parent = nwsapi.closest('[data-component]', element, function(ancestor) {
console.log('Found component ancestor:', ancestor.dataset.component);
});Supported Selectors
NWSAPI supports a comprehensive range of CSS selectors including:
Basic Selectors
- Type selectors:
div,p,span - Class selectors:
.class-name - ID selectors:
#element-id - Universal selector:
* - Attribute selectors:
[attr],[attr="value"],[attr~="value"],[attr|="value"],[attr^="value"],[attr$="value"],[attr*="value"]
Combinators
- Descendant:
A B - Child:
A > B - Adjacent sibling:
A + B - General sibling:
A ~ B
Pseudo-classes
- Structural:
:first-child,:last-child,:nth-child(),:nth-of-type(),:only-child,:empty,:root - Logical:
:not(),:is(),:where(),:has() - Link:
:link,:visited,:any-link - User action:
:hover,:active,:focus,:focus-within,:focus-visible - Input:
:enabled,:disabled,:checked,:indeterminate,:required,:optional,:valid,:invalid - Language:
:lang() - Location:
:target,:scope
Pseudo-elements
::before,::after,::first-line,::first-letter,::selection
Performance Notes
- Memoization: Compiled selectors are cached for reuse, providing superior performance on repeated queries
- Right-to-left parsing: Optimized parsing strategy that matches browser behavior
- Context optimization: Queries are optimized based on the provided context
- Lazy compilation: Selectors are compiled only when first used
Install with Tessl CLI
npx tessl i tessl/npm-nwsapi