0
# DOM Helpers
1

2
Fast helper methods for common element lookup operations by ID, tag name, and class name, with optional context filtering for improved performance over generic selector queries.
3

4
## Capabilities
5

6
### ById Function
7

8
Returns the first element with the specified ID, optionally filtered to descendants of a given element.
9

10
```javascript { .api }
11
/**
12
 * Returns element by ID
13
 * @param id - Element ID to find
14
 * @param from - Optional root element to search within
15
 * @returns Element with matching ID or null
16
 */
17
function byId(id, from);
18
```
19

20
**Usage Examples:**
21

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

25
// Find element by ID in entire document
26
const header = nwsapi.byId('main-header');
27

28
// Find element by ID within specific context
29
const button = nwsapi.byId('submit-btn', formElement);
30

31
// Handle case where element doesn't exist
32
const element = nwsapi.byId('nonexistent');
33
if (element) {
34
  console.log('Found element:', element);
35
} else {
36
  console.log('Element not found');
37
}
38
```
39

40
### ByTag Function
41

42
Returns an array of elements with the specified tag name, optionally filtered to descendants of a given element.
43

44
```javascript { .api }
45
/**
46
 * Returns elements by tag name
47
 * @param tag - Tag name to search for
48
 * @param from - Optional root element to search within
49
 * @returns Array of elements with matching tag name
50
 */
51
function byTag(tag, from);
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const nwsapi = require("nwsapi");
58

59
// Find all paragraphs in document
60
const paragraphs = nwsapi.byTag('p');
61

62
// Find all links within navigation
63
const navLinks = nwsapi.byTag('a', navigationElement);
64

65
// Find all form inputs
66
const inputs = nwsapi.byTag('input', formElement);
67

68
// Case insensitive by default
69
const divs = nwsapi.byTag('DIV'); // Same as byTag('div')
70

71
// Iterate through results
72
nwsapi.byTag('img').forEach(function(img) {
73
  console.log('Image source:', img.src);
74
});
75
```
76

77
### ByClass Function
78

79
Returns an array of elements with the specified class name, optionally filtered to descendants of a given element.
80

81
```javascript { .api }
82
/**
83
 * Returns elements by class name
84
 * @param class - Class name to search for (without dot prefix)
85
 * @param from - Optional root element to search within
86
 * @returns Array of elements with matching class name
87
 */
88
function byClass(class, from);
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
const nwsapi = require("nwsapi");
95

96
// Find all elements with 'highlight' class
97
const highlighted = nwsapi.byClass('highlight');
98

99
// Find elements with class within specific container
100
const cards = nwsapi.byClass('card', containerElement);
101

102
// Multiple class matching (finds elements with any of the classes)
103
const buttons = nwsapi.byClass('btn');
104
const primaryButtons = nwsapi.byClass('btn-primary');
105

106
// Iterate and modify
107
nwsapi.byClass('hidden').forEach(function(element) {
108
  element.style.display = 'block';
109
});
110

111
// Check if results exist
112
const warnings = nwsapi.byClass('warning');
113
if (warnings.length > 0) {
114
  console.log('Found', warnings.length, 'warning elements');
115
}
116
```
117

118
## Performance Characteristics
119

120
### Optimization Benefits
121

122
- **Direct DOM API usage**: Helper methods use optimized native DOM methods when available
123
- **Reduced parsing overhead**: No CSS selector parsing required
124
- **Context filtering**: Optional `from` parameter allows efficient scoped searches
125
- **Browser optimization**: Leverages browser's native `getElementById`, `getElementsByTagName`, and `getElementsByClassName`
126

127
### Performance Comparison
128

129
```javascript
130
// Faster - uses native DOM methods
131
const fast = nwsapi.byClass('button');
132

133
// Slower - requires CSS selector parsing and compilation
134
const slow = nwsapi.select('.button');
135

136
// Much faster for repeated operations due to direct API access
137
for (let i = 0; i < 1000; i++) {
138
  nwsapi.byId('element-' + i); // Optimized
139
}
140
```
141

142
### Best Practices
143

144
- Use helper methods when you need simple ID, tag, or class lookups
145
- Use `select()` for complex selectors requiring CSS parsing
146
- Provide `from` context when searching within specific containers
147
- Helper methods are ideal for performance-critical code paths
148

149
## Context Filtering
150

151
All helper methods support optional context filtering through the `from` parameter:
152

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

156
// Search entire document
157
const allButtons = nwsapi.byTag('button');
158

159
// Search only within form
160
const formButtons = nwsapi.byTag('button', formElement);
161

162
// Search within multiple contexts
163
const contexts = [nav, main, footer];
164
const allLinks = contexts.reduce((links, context) => {
165
  return links.concat(nwsapi.byTag('a', context));
166
}, []);
167
```
168

169
## Error Handling
170

171
Helper methods are designed to be robust and handle edge cases gracefully:
172

173
```javascript
174
const nwsapi = require("nwsapi");
175

176
// Returns null if ID not found
177
const missing = nwsapi.byId('nonexistent'); // null
178

179
// Returns empty array if no matches
180
const noMatches = nwsapi.byTag('nonexistent'); // []
181
const noClasses = nwsapi.byClass('nonexistent'); // []
182

183
// Handles invalid contexts gracefully
184
const invalid = nwsapi.byTag('div', null); // Searches document
185
const invalid2 = nwsapi.byClass('test', undefined); // Searches document
186
```