NWSAPI

NWSAPI is a fast CSS Selectors API Engine that serves as a cross-browser replacement for native CSS selection and matching functionality. It provides a right-to-left selector parser and compiler written in pure JavaScript with no external dependencies, originally developed as the successor to NWMATCHER and aimed at CSS Selectors Level 4 conformance.

The library uses regular expressions to parse CSS selector strings and metaprogramming to transform them into optimized JavaScript function resolvers, with memoization for superior performance. It provides comprehensive CSS selector support including advanced pseudo-classes like :has(), :is(), :where(), and :defined.

Package Information

• Package Name: nwsapi
• Package Type: npm
• Language: JavaScript
• Installation: npm install nwsapi

Core Imports

const nwsapi = require("nwsapi");

For AMD:

define(["nwsapi"], function(nwsapi) {
  // Use nwsapi
});

For browser global:

<script type="text/javascript" src="nwsapi.js"></script>
<script>
  var DOM = NW.Dom;
</script>

Basic Usage

const nwsapi = require("nwsapi");

// Select all elements with class 'highlight'
const elements = nwsapi.select('.highlight', document);

// Test if element matches selector
const matches = nwsapi.match('div.container', element);

// Find first matching element
const firstElement = nwsapi.first('p:first-child', document);

// Find closest ancestor matching selector
const ancestor = nwsapi.closest('ul', element);

Architecture

NWSAPI is built around several key components:

• Selector Engine: Core parsing and compilation system that transforms CSS selectors into optimized JavaScript resolvers
• Compilation System: Metaprogramming engine that generates specialized functions for different query types and contexts
• Memoization Cache: Performance optimization system that stores compiled resolvers for reuse
• Extension Framework: Plugin architecture for registering custom selectors, operators, and combinators
• Configuration System: Runtime options for controlling engine behavior and compatibility modes

Capabilities

DOM Selection

Core CSS selector-based element selection functionality. Provides comprehensive querying capabilities with high performance through compiled resolvers.

function select(selector, context, callback);
function match(selector, element, callback);
function first(selector, context, callback);
function closest(selector, context, callback);

DOM Selection

DOM Helpers

Fast helper methods for common element lookup operations by ID, tag name, and class name, with optional context filtering.

function byId(id, from);
function byTag(tag, from);
function byClass(class, from);

DOM Helpers

Engine Configuration

Configuration system for customizing engine behavior including duplicate ID handling, caching, case sensitivity, and error logging.

function configure(options);
function emit(message, proto);

Configuration

Compilation System

Advanced selector compilation functionality for creating optimized resolver functions and managing the compilation pipeline.

function compile(selector, source, mode);

Compilation

Extension Registration

Plugin system for extending NWSAPI with custom selectors, attribute operators, and combinators.

function registerSelector(name, rexp, func);
function registerOperator(operator, resolver);
function registerCombinator(combinator, resolver);

Extensions

Engine Installation

System for installing NWSAPI as a replacement for native browser querySelector methods and restoring original functionality.

function install(callback);
function uninstall(callback);

Installation

Properties

// Version string
const Version: string;

// Current configuration object
const Config: ConfigOptions;

// Registered operators registry
const Operators: { [operator: string]: OperatorResolver };

// Registered selectors registry  
const Selectors: { [name: string]: { Expression: RegExp; Callback: Function } };

// Engine compilation state snapshot
const Snapshot: object;

Types

// Configuration object
interface ConfigOptions {
  IDS_DUPES?: boolean;    // Allow duplicate IDs (default: true)
  LIVECACHE?: boolean;    // Cache results and resolvers (default: true)
  MIXEDCASE?: boolean;    // Case insensitive tag matching (default: true)
  LOGERRORS?: boolean;    // Log errors to console (default: true)
}

// Callback function for element operations
type ElementCallback = (element: Element) => void;

// Selector resolver function
type SelectorResolver = (match: RegExpMatchArray, source: string, mode: number, callback?: Function) => { source: string; status: boolean };

// Operator resolver configuration
interface OperatorResolver {
  p1: string;
  p2: string;
  p3: string;
}