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
```