0
# Installation
1

2
System for installing NWSAPI as a replacement for native browser querySelector methods and restoring original functionality. The installation system allows NWSAPI to override native DOM methods transparently.
3

4
## Capabilities
5

6
### Install Function
7

8
Installs NWSAPI as the default CSS selector engine by replacing native querySelector/querySelectorAll methods.
9

10
```javascript { .api }
11
/**
12
 * Installs NWSAPI as native QSA replacement
13
 * @param all - Optional boolean to enable automatic iframe installation
14
 * @returns NWSAPI Dom object
15
 */
16
function install(all);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const nwsapi = require("nwsapi");
23

24
// Basic installation
25
nwsapi.install();
26

27
// Now native methods use NWSAPI
28
const elements = document.querySelectorAll('.test'); // Uses NWSAPI
29
const element = document.querySelector('#header');   // Uses NWSAPI
30

31
// Installation with iframe support
32
nwsapi.install(true); // Automatically installs in iframes as well
33

34
// Verify installation
35
console.log('Original querySelector available:', !!document._querySelector);
36
```
37

38
### Uninstall Function
39

40
Restores native querySelector/querySelectorAll methods and removes NWSAPI overrides.
41

42
```javascript { .api }
43
/**
44
 * Restores native QSA methods
45
 * @returns NWSAPI Dom object
46
 */
47
function uninstall();
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
const nwsapi = require("nwsapi");
54

55
// Install NWSAPI first
56
nwsapi.install();
57

58
// Later, restore native methods
59
nwsapi.uninstall();
60

61
// Native methods restored
62
const elements = document.querySelectorAll('.test'); // Uses native browser engine
63

64
// Verify uninstall
65
console.log('NWSAPI uninstalled, native methods restored');
66
```
67

68
## Installation Modes
69

70
### Automatic Installation
71

72
NWSAPI can be automatically installed when the script loads:
73

74
```html
75
<!-- Automatic installation on load -->
76
<script type="text/javascript" src="nwsapi.js" onload="NW.Dom.install()"></script>
77
```
78

79
### Conditional Installation
80

81
```javascript
82
const nwsapi = require("nwsapi");
83

84
// Install only in specific environments
85
if (typeof window !== 'undefined' && window.document) {
86
  // Browser environment
87
  nwsapi.install();
88
} else {
89
  // Node.js or headless environment - no installation needed
90
  console.log('Running in headless mode');
91
}
92

93
// Install based on browser capabilities
94
if (!document.querySelector || !document.querySelectorAll) {
95
  // Older browser without native QSA
96
  nwsapi.install();
97
} else {
98
  // Modern browser - compare performance first
99
  benchmarkAndInstall();
100
}
101
```
102

103
### Selective Installation
104

105
```javascript
106
const nwsapi = require("nwsapi");
107

108
// Custom installation that preserves some native methods
109
function selectiveInstall() {
110
  // Store native methods
111
  const nativeQS = document.querySelector;
112
  const nativeQSA = document.querySelectorAll;
113
  
114
  // Install NWSAPI
115
  nwsapi.install();
116
  
117
  // Restore native for simple selectors (performance optimization)
118
  const originalQSA = document.querySelectorAll;
119
  document.querySelectorAll = function(selector) {
120
    if (/^[#.]?[\w-]+$/.test(selector)) {
121
      // Simple selector - use native for best performance
122
      return nativeQSA.call(this, selector);
123
    } else {
124
      // Complex selector - use NWSAPI for compatibility
125
      return originalQSA.call(this, selector);
126
    }
127
  };
128
}
129
```
130

131
## Installation Effects
132

133
### Method Overrides
134

135
When installed, NWSAPI overrides the following native methods:
136

137
```javascript
138
// Before installation
139
document.querySelector           // Native browser implementation
140
document.querySelectorAll        // Native browser implementation
141
Element.prototype.querySelector  // Native browser implementation
142
Element.prototype.querySelectorAll // Native browser implementation
143

144
// After installation
145
document.querySelector           // NWSAPI implementation
146
document.querySelectorAll        // NWSAPI implementation  
147
Element.prototype.querySelector  // NWSAPI implementation
148
Element.prototype.querySelectorAll // NWSAPI implementation
149

150
// Original methods preserved as
151
document._querySelector          // Original native method
152
document._querySelectorAll       // Original native method
153
Element.prototype._querySelector // Original native method
154
Element.prototype._querySelectorAll // Original native method
155
```
156

157
### Performance Impact
158

159
```javascript
160
const nwsapi = require("nwsapi");
161

162
// Benchmark before installation
163
console.time('native-query');
164
document.querySelectorAll('.test');
165
console.timeEnd('native-query');
166

167
// Install NWSAPI
168
nwsapi.install();
169

170
// Benchmark after installation
171
console.time('nwsapi-query');
172
document.querySelectorAll('.test');
173
console.timeEnd('nwsapi-query');
174

175
// NWSAPI often faster for complex selectors
176
console.time('complex-native');
177
document._querySelectorAll('div:has(> p:nth-child(2n+1))');
178
console.timeEnd('complex-native');
179

180
console.time('complex-nwsapi');
181
document.querySelectorAll('div:has(> p:nth-child(2n+1))');
182
console.timeEnd('complex-nwsapi');
183
```
184

185
## Installation Patterns
186

187
### Framework Integration
188

189
```javascript
190
const nwsapi = require("nwsapi");
191

192
// Vue.js integration
193
const VueNWSAPI = {
194
  install(Vue) {
195
    nwsapi.install();
196
    Vue.prototype.$nwsapi = nwsapi;
197
  }
198
};
199

200
// React integration
201
function withNWSAPI(Component) {
202
  // Install on first render
203
  nwsapi.install();
204
  return Component;
205
}
206

207
// jQuery integration
208
if (typeof jQuery !== 'undefined') {
209
  nwsapi.install();
210
  jQuery.fn.nwsapi = function(selector) {
211
    return nwsapi.select(selector, this[0]);
212
  };
213
}
214
```
215

216
### Testing Environment Setup
217

218
```javascript
219
const nwsapi = require("nwsapi");
220

221
// Jest setup
222
beforeAll(() => {
223
  nwsapi.install();
224
});
225

226
afterAll(() => {
227
  nwsapi.uninstall();
228
});
229

230
// Mocha setup
231
before(function() {
232
  nwsapi.install();
233
});
234

235
after(function() {
236
  nwsapi.uninstall();
237
});
238

239
// Custom test helper
240
function withNWSAPI(testFn) {
241
  return function() {
242
    nwsapi.install();
243
    try {
244
      return testFn.apply(this, arguments);
245
    } finally {
246
      nwsapi.uninstall();
247
    }
248
  };
249
}
250

251
// Usage
252
it('should work with NWSAPI', withNWSAPI(function() {
253
  const elements = document.querySelectorAll(':has(> img)');
254
  expect(elements.length).toBe(3);
255
}));
256
```
257

258
### Production Deployment
259

260
```javascript
261
const nwsapi = require("nwsapi");
262

263
// Production installation with error handling
264
function safeInstall() {
265
  try {
266
    nwsapi.configure({
267
      LOGERRORS: false  // Disable logging in production
268
    });
269
    
270
    nwsapi.install();
271
    
272
    // Track installation success
273
    if (window.gtag) {
274
      gtag('event', 'nwsapi_installed', {
275
        'custom_parameters': {
276
          'version': nwsapi.Version
277
        }
278
      });
279
    }
280
    
281
    return true;
282
  } catch (error) {
283
    console.error('NWSAPI installation failed:', error);
284
    return false;
285
  }
286
}
287

288
// Conditional production installation
289
if (window.location.hostname !== 'localhost') {
290
  safeInstall();
291
}
292
```
293

294
## Installation Verification
295

296
### Testing Installation Status
297

298
```javascript
299
const nwsapi = require("nwsapi");
300

301
// Check if installed
302
function isNWSAPIInstalled() {
303
  return document.querySelector === nwsapi.select ||
304
         typeof document._querySelector !== 'undefined';
305
}
306

307
// Verify installation works
308
function verifyInstallation() {
309
  nwsapi.install();
310
  
311
  try {
312
    // Test with NWSAPI-specific selector
313
    const elements = document.querySelectorAll(':has(> *)');
314
    console.log('Installation verified - advanced selectors work');
315
    return true;
316
  } catch (error) {
317
    console.error('Installation verification failed:', error);
318
    return false;
319
  }
320
}
321

322
// Health check
323
function healthCheck() {
324
  const tests = [
325
    () => document.querySelectorAll('div').length >= 0,
326
    () => document.querySelector('body') !== null,
327
    () => typeof document._querySelector === 'function'
328
  ];
329
  
330
  return tests.every(test => {
331
    try {
332
      return test();
333
    } catch (error) {
334
      return false;
335
    }
336
  });
337
}
338
```
339

340
### Compatibility Checks
341

342
```javascript
343
const nwsapi = require("nwsapi");
344

345
// Browser compatibility check
346
function checkCompatibility() {
347
  const features = {
348
    querySelector: !!document.querySelector,
349
    querySelectorAll: !!document.querySelectorAll,
350
    getElementsByClassName: !!document.getElementsByClassName,
351
    documentElement: !!document.documentElement
352
  };
353
  
354
  const compatible = Object.values(features).every(Boolean);
355
  
356
  if (compatible) {
357
    nwsapi.install();
358
    return true;
359
  } else {
360
    console.warn('Browser not compatible with NWSAPI installation');
361
    return false;
362
  }
363
}
364

365
// Feature detection for advanced selectors
366
function supportsAdvancedSelectors() {
367
  try {
368
    document.querySelectorAll(':has(*)');
369
    return false; // Native support found
370
  } catch (error) {
371
    return true;  // Native support missing - NWSAPI beneficial
372
  }
373
}
374

375
if (supportsAdvancedSelectors()) {
376
  nwsapi.install();
377
}
378
```