0
# NWSAPI
1
2
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.
3
4
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`.
5
6
## Package Information
7
8
- **Package Name**: nwsapi
9
- **Package Type**: npm
10
- **Language**: JavaScript
11
- **Installation**: `npm install nwsapi`
12
13
## Core Imports
14
15
```javascript
16
const nwsapi = require("nwsapi");
17
```
18
19
For AMD:
20
21
```javascript
22
define(["nwsapi"], function(nwsapi) {
23
// Use nwsapi
24
});
25
```
26
27
For browser global:
28
29
```html
30
<script type="text/javascript" src="nwsapi.js"></script>
31
<script>
32
var DOM = NW.Dom;
33
</script>
34
```
35
36
## Basic Usage
37
38
```javascript
39
const nwsapi = require("nwsapi");
40
41
// Select all elements with class 'highlight'
42
const elements = nwsapi.select('.highlight', document);
43
44
// Test if element matches selector
45
const matches = nwsapi.match('div.container', element);
46
47
// Find first matching element
48
const firstElement = nwsapi.first('p:first-child', document);
49
50
// Find closest ancestor matching selector
51
const ancestor = nwsapi.closest('ul', element);
52
```
53
54
## Architecture
55
56
NWSAPI is built around several key components:
57
58
- **Selector Engine**: Core parsing and compilation system that transforms CSS selectors into optimized JavaScript resolvers
59
- **Compilation System**: Metaprogramming engine that generates specialized functions for different query types and contexts
60
- **Memoization Cache**: Performance optimization system that stores compiled resolvers for reuse
61
- **Extension Framework**: Plugin architecture for registering custom selectors, operators, and combinators
62
- **Configuration System**: Runtime options for controlling engine behavior and compatibility modes
63
64
## Capabilities
65
66
### DOM Selection
67
68
Core CSS selector-based element selection functionality. Provides comprehensive querying capabilities with high performance through compiled resolvers.
69
70
```javascript { .api }
71
function select(selector, context, callback);
72
function match(selector, element, callback);
73
function first(selector, context, callback);
74
function closest(selector, context, callback);
75
```
76
77
[DOM Selection](./dom-selection.md)
78
79
### DOM Helpers
80
81
Fast helper methods for common element lookup operations by ID, tag name, and class name, with optional context filtering.
82
83
```javascript { .api }
84
function byId(id, from);
85
function byTag(tag, from);
86
function byClass(class, from);
87
```
88
89
[DOM Helpers](./dom-helpers.md)
90
91
### Engine Configuration
92
93
Configuration system for customizing engine behavior including duplicate ID handling, caching, case sensitivity, and error logging.
94
95
```javascript { .api }
96
function configure(options);
97
function emit(message, proto);
98
```
99
100
[Configuration](./configuration.md)
101
102
### Compilation System
103
104
Advanced selector compilation functionality for creating optimized resolver functions and managing the compilation pipeline.
105
106
```javascript { .api }
107
function compile(selector, source, mode);
108
```
109
110
[Compilation](./compilation.md)
111
112
### Extension Registration
113
114
Plugin system for extending NWSAPI with custom selectors, attribute operators, and combinators.
115
116
```javascript { .api }
117
function registerSelector(name, rexp, func);
118
function registerOperator(operator, resolver);
119
function registerCombinator(combinator, resolver);
120
```
121
122
[Extensions](./extensions.md)
123
124
### Engine Installation
125
126
System for installing NWSAPI as a replacement for native browser querySelector methods and restoring original functionality.
127
128
```javascript { .api }
129
function install(callback);
130
function uninstall(callback);
131
```
132
133
[Installation](./installation.md)
134
135
## Properties
136
137
```javascript { .api }
138
// Version string
139
const Version: string;
140
141
// Current configuration object
142
const Config: ConfigOptions;
143
144
// Registered operators registry
145
const Operators: { [operator: string]: OperatorResolver };
146
147
// Registered selectors registry
148
const Selectors: { [name: string]: { Expression: RegExp; Callback: Function } };
149
150
// Engine compilation state snapshot
151
const Snapshot: object;
152
```
153
154
## Types
155
156
```javascript { .api }
157
// Configuration object
158
interface ConfigOptions {
159
IDS_DUPES?: boolean; // Allow duplicate IDs (default: true)
160
LIVECACHE?: boolean; // Cache results and resolvers (default: true)
161
MIXEDCASE?: boolean; // Case insensitive tag matching (default: true)
162
LOGERRORS?: boolean; // Log errors to console (default: true)
163
}
164
165
// Callback function for element operations
166
type ElementCallback = (element: Element) => void;
167
168
// Selector resolver function
169
type SelectorResolver = (match: RegExpMatchArray, source: string, mode: number, callback?: Function) => { source: string; status: boolean };
170
171
// Operator resolver configuration
172
interface OperatorResolver {
173
p1: string;
174
p2: string;
175
p3: string;
176
}
177
```