0
# Configuration
1

2
Configuration system for customizing NWSAPI engine behavior including duplicate ID handling, caching strategies, case sensitivity options, and error logging preferences.
3

4
## Capabilities
5

6
### Configure Function
7

8
Configures engine behavior with various options. When called without parameters, returns the current configuration.
9

10
```javascript { .api }
11
/**
12
 * Configures engine behavior
13
 * @param option - Configuration object with boolean flags, or string to get single option value
14
 * @param clear - Optional boolean to clear resolver cache
15
 * @returns Current configuration object or boolean value for string queries
16
 */
17
function configure(option, clear);
18
```
19

20
**Usage Examples:**
21

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

25
// Get current configuration
26
const currentConfig = nwsapi.configure();
27
console.log('Current config:', currentConfig);
28

29
// Set specific options
30
nwsapi.configure({
31
  LOGERRORS: false,    // Disable error logging
32
  IDS_DUPES: false     // Disallow duplicate IDs
33
});
34

35
// Enable all caching
36
nwsapi.configure({
37
  LIVECACHE: true
38
});
39

40
// Case sensitive tag matching
41
nwsapi.configure({
42
  MIXEDCASE: false
43
});
44

45
// Reset to defaults
46
nwsapi.configure({
47
  IDS_DUPES: true,
48
  LIVECACHE: true,
49
  MIXEDCASE: true,
50
  LOGERRORS: true
51
});
52

53
// Query single configuration option
54
const logErrors = nwsapi.configure('LOGERRORS');
55
console.log('Error logging enabled:', logErrors);
56

57
// Configure with cache clearing
58
nwsapi.configure({
59
  LIVECACHE: false  // Disable caching
60
}, true);  // Clear existing resolver cache
61
```
62

63
### Emit Function
64

65
Emits error or warning messages to the console or throws exceptions based on configuration.
66

67
```javascript { .api }
68
/**
69
 * Emits error/warning messages
70
 * @param message - Message to emit
71
 * @param proto - Optional error constructor prototype
72
 * @returns void
73
 */
74
function emit(message, proto);
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
const nwsapi = require("nwsapi");
81

82
// Basic error emission (logs to console if LOGERRORS is true)
83
nwsapi.emit('Invalid selector syntax');
84

85
// Emit with custom error type
86
nwsapi.emit('Custom error message', TypeError);
87

88
// Behavior depends on configuration
89
nwsapi.configure({ LOGERRORS: true });
90
nwsapi.emit('This will be logged');
91

92
nwsapi.configure({ LOGERRORS: false });
93
nwsapi.emit('This will be silent');
94
```
95

96
### Config Object
97

98
Direct access to the current configuration state object.
99

100
```javascript { .api }
101
/**
102
 * Current configuration state object
103
 * @type ConfigOptions
104
 */
105
const Config: {
106
  IDS_DUPES: boolean;   // Allow duplicate IDs
107
  LIVECACHE: boolean;   // Cache results and resolvers  
108
  MIXEDCASE: boolean;   // Case insensitive tag matching
109
  LOGERRORS: boolean;   // Log errors to console
110
};
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
const nwsapi = require("nwsapi");
117

118
// Read current configuration directly
119
console.log('Duplicate IDs allowed:', nwsapi.Config.IDS_DUPES);
120
console.log('Caching enabled:', nwsapi.Config.LIVECACHE);
121

122
// Check all settings
123
Object.entries(nwsapi.Config).forEach(([key, value]) => {
124
  console.log(`${key}: ${value}`);
125
});
126

127
// Note: Direct modification not recommended - use configure() instead
128
// nwsapi.Config.LOGERRORS = false; // Don't do this
129
nwsapi.configure({ LOGERRORS: false }); // Do this instead
130
```
131

132
## Configuration Options
133

134
### IDS_DUPES
135

136
Controls whether multiple elements with the same ID are allowed.
137

138
```javascript { .api }
139
/**
140
 * Allow duplicate IDs option
141
 * @default true
142
 * @type boolean
143
 */
144
IDS_DUPES: boolean;
145
```
146

147
**Behavior:**
148
- `true` (default): Allows multiple elements with same ID, returns first match
149
- `false`: Strict mode, warns about duplicate IDs
150

151
**Examples:**
152

153
```javascript
154
const nwsapi = require("nwsapi");
155

156
// Allow duplicates (default)
157
nwsapi.configure({ IDS_DUPES: true });
158
const element = nwsapi.byId('duplicate-id'); // Returns first match
159

160
// Strict mode - no duplicates
161
nwsapi.configure({ IDS_DUPES: false });
162
const element2 = nwsapi.byId('duplicate-id'); // May warn about duplicates
163
```
164

165
### LIVECACHE
166

167
Controls caching behavior for both query results and compiled resolvers.
168

169
```javascript { .api }
170
/**
171
 * Enable live caching option
172
 * @default true
173
 * @type boolean
174
 */
175
LIVECACHE: boolean;
176
```
177

178
**Behavior:**
179
- `true` (default): Caches both compiled resolvers and query results
180
- `false`: Only caches compiled resolvers, not results
181

182
**Examples:**
183

184
```javascript
185
const nwsapi = require("nwsapi");
186

187
// Full caching (default) - best performance
188
nwsapi.configure({ LIVECACHE: true });
189

190
// Resolver-only caching - saves memory but slower repeated queries
191
nwsapi.configure({ LIVECACHE: false });
192

193
// Performance comparison
194
console.time('first-query');
195
nwsapi.select('.test'); // Compiles selector
196
console.timeEnd('first-query');
197

198
console.time('second-query');
199
nwsapi.select('.test'); // Uses cached resolver (and result if LIVECACHE: true)
200
console.timeEnd('second-query');
201
```
202

203
### MIXEDCASE
204

205
Controls case sensitivity for tag name matching.
206

207
```javascript { .api }
208
/**
209
 * Case insensitive tag matching option
210
 * @default true
211
 * @type boolean
212
 */
213
MIXEDCASE: boolean;
214
```
215

216
**Behavior:**
217
- `true` (default): Tag names are matched case-insensitively
218
- `false`: Tag names are matched case-sensitively
219

220
**Examples:**
221

222
```javascript
223
const nwsapi = require("nwsapi");
224

225
// Case insensitive (default)
226
nwsapi.configure({ MIXEDCASE: true });
227
const divs1 = nwsapi.byTag('div');  // Matches <div>
228
const divs2 = nwsapi.byTag('DIV');  // Also matches <div>
229

230
// Case sensitive
231
nwsapi.configure({ MIXEDCASE: false });
232
const divs3 = nwsapi.byTag('div');  // Matches <div>
233
const divs4 = nwsapi.byTag('DIV');  // Does NOT match <div>
234
```
235

236
### LOGERRORS
237

238
Controls whether errors and warnings are logged to the console.
239

240
```javascript { .api }
241
/**
242
 * Enable error logging option
243
 * @default true
244
 * @type boolean
245
 */
246
LOGERRORS: boolean;
247
```
248

249
**Behavior:**
250
- `true` (default): Logs errors and warnings to console
251
- `false`: Suppresses error and warning output
252

253
**Examples:**
254

255
```javascript
256
const nwsapi = require("nwsapi");
257

258
// Enable logging (default)
259
nwsapi.configure({ LOGERRORS: true });
260
nwsapi.select('invalid::selector'); // Will log error to console
261

262
// Disable logging
263
nwsapi.configure({ LOGERRORS: false });
264
nwsapi.select('invalid::selector'); // Silent failure
265

266
// Selective logging for production
267
if (process.env.NODE_ENV !== 'production') {
268
  nwsapi.configure({ LOGERRORS: true });
269
} else {
270
  nwsapi.configure({ LOGERRORS: false });
271
}
272
```
273

274
## Configuration Patterns
275

276
### Development vs Production
277

278
```javascript
279
const nwsapi = require("nwsapi");
280

281
// Development configuration
282
nwsapi.configure({
283
  LOGERRORS: true,     // Enable debugging
284
  IDS_DUPES: false,    // Strict validation
285
  LIVECACHE: true,     // Full performance
286
  MIXEDCASE: true      // Flexible matching
287
});
288

289
// Production configuration
290
nwsapi.configure({
291
  LOGERRORS: false,    // Silent operation
292
  IDS_DUPES: true,     // Tolerant of duplicates
293
  LIVECACHE: true,     // Maximum performance
294
  MIXEDCASE: true      // Cross-browser compatibility
295
});
296
```
297

298
### Memory-Conscious Configuration
299

300
```javascript
301
const nwsapi = require("nwsapi");
302

303
// Reduce memory usage
304
nwsapi.configure({
305
  LIVECACHE: false,    // Don't cache results
306
  LOGERRORS: false,    // Minimal overhead
307
  IDS_DUPES: true,     // Standard behavior
308
  MIXEDCASE: true      // Standard behavior
309
});
310
```
311

312
### Strict Validation Configuration
313

314
```javascript
315
const nwsapi = require("nwsapi");
316

317
// Maximum validation
318
nwsapi.configure({
319
  IDS_DUPES: false,    // No duplicate IDs
320
  LOGERRORS: true,     // Show all warnings
321
  MIXEDCASE: false,    // Exact case matching
322
  LIVECACHE: true      // Performance optimization
323
});
324
```
325

326
## Configuration State Management
327

328
### Saving and Restoring Configuration
329

330
```javascript
331
const nwsapi = require("nwsapi");
332

333
// Save current configuration
334
const savedConfig = nwsapi.configure();
335

336
// Make temporary changes
337
nwsapi.configure({ LOGERRORS: false });
338

339
// Perform operations...
340
nwsapi.select('.test');
341

342
// Restore previous configuration
343
nwsapi.configure(savedConfig);
344
```
345

346
### Configuration Validation
347

348
```javascript
349
const nwsapi = require("nwsapi");
350

351
// Validate configuration before applying
352
function safeConfig(options) {
353
  const validKeys = ['IDS_DUPES', 'LIVECACHE', 'MIXEDCASE', 'LOGERRORS'];
354
  const filtered = {};
355
  
356
  for (const key in options) {
357
    if (validKeys.includes(key) && typeof options[key] === 'boolean') {
358
      filtered[key] = options[key];
359
    }
360
  }
361
  
362
  return nwsapi.configure(filtered);
363
}
364

365
// Use safe configuration
366
safeConfig({
367
  LOGERRORS: false,
368
  INVALID_OPTION: true  // Will be ignored
369
});
370
```