0
# Node Types
1

2
Base Node classes and node type system providing the foundation for the DOM tree structure, including specialized TextNode and CommentNode classes for complete HTML representation.
3

4
## Capabilities
5

6
### Node Base Class
7

8
Abstract base class providing common functionality for all DOM nodes.
9

10
```typescript { .api }
11
abstract class Node {
12
  /** Array of child nodes */
13
  childNodes: Node[];
14
  
15
  /** Parent element reference */
16
  parentNode: HTMLElement | null;
17
  
18
  /** Position range in original HTML source */
19
  range: readonly [number, number];
20
  
21
  // Abstract properties (implemented by subclasses)
22
  abstract rawTagName: string;
23
  abstract nodeType: NodeType;
24
  abstract text: string;
25
  abstract rawText: string;
26
  
27
  // Abstract methods
28
  abstract toString(): string;
29
  abstract clone(): Node;
30
}
31
```
32

33
### Node Common Methods
34

35
Methods available on all node types for DOM manipulation and content access.
36

37
```typescript { .api }
38
/** Remove node from its parent */
39
remove(): Node;
40

41
/** Get raw text content (may include HTML entities) */
42
get innerText(): string;
43

44
/** Get/set decoded text content */
45
get textContent(): string;
46
set textContent(val: string): void;
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { parse, NodeType } from "node-html-parser";
53

54
const root = parse('<div>Text <em>emphasis</em></div>');
55
const textNode = root.childNodes[0];
56

57
// Check node type
58
if (textNode.nodeType === NodeType.TEXT_NODE) {
59
  console.log("This is a text node");
60
}
61

62
// Remove node
63
textNode.remove();
64
console.log(root.innerHTML); // "<em>emphasis</em>"
65
```
66

67
### TextNode Class
68

69
Represents text content within HTML elements with whitespace handling and text manipulation.
70

71
```typescript { .api }
72
class TextNode extends Node {
73
  /** Node type constant */
74
  nodeType: NodeType.TEXT_NODE; // Value: 3
75
  
76
  /** Empty string for text nodes */
77
  rawTagName: '';
78
  
79
  /** Get/set raw text content including HTML entities */
80
  get rawText(): string;
81
  set rawText(text: string): void;
82
  
83
  /** Get decoded text content */
84
  get text(): string;
85
  
86
  /** Get raw text with normalized whitespace */
87
  get trimmedRawText(): string;
88
  
89
  /** Get decoded text with normalized whitespace */
90
  get trimmedText(): string;
91
  
92
  /** Check if node contains only whitespace */
93
  get isWhitespace(): boolean;
94
  
95
  /** Return raw text as string representation */
96
  toString(): string;
97
  
98
  /** Create copy of text node */
99
  clone(): TextNode;
100
}
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import { parse, TextNode } from "node-html-parser";
107

108
const root = parse('<p>  Hello &amp; world  </p>');
109
const textNode = root.firstChild as TextNode;
110

111
console.log(textNode.rawText);        // "  Hello &amp; world  "
112
console.log(textNode.text);           // "  Hello & world  "
113
console.log(textNode.trimmedText);    // "Hello & world"
114
console.log(textNode.isWhitespace);   // false
115

116
// Whitespace node
117
const whitespace = parse('<div> </div>').firstChild as TextNode;
118
console.log(whitespace.isWhitespace); // true
119

120
// Modify text content
121
textNode.rawText = "New content";
122
console.log(root.toString()); // "<p>New content</p>"
123
```
124

125
### CommentNode Class
126

127
Represents HTML comments in the DOM tree.
128

129
```typescript { .api }
130
class CommentNode extends Node {
131
  /** Node type constant */
132
  nodeType: NodeType.COMMENT_NODE; // Value: 8
133
  
134
  /** Comment tag identifier */
135
  rawTagName: '!--';
136
  
137
  /** Comment content */
138
  rawText: string;
139
  
140
  /** Get comment content (same as rawText) */
141
  get text(): string;
142
  
143
  /** Return formatted comment string */
144
  toString(): string; // Returns <!--content-->
145
  
146
  /** Create copy of comment node */
147
  clone(): CommentNode;
148
}
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import { parse, CommentNode, NodeType } from "node-html-parser";
155

156
// Parse HTML with comments (requires comment: true option)
157
const root = parse('<!-- This is a comment --><div>Content</div>', {
158
  comment: true
159
});
160

161
const commentNode = root.childNodes[0] as CommentNode;
162

163
console.log(commentNode.nodeType === NodeType.COMMENT_NODE); // true
164
console.log(commentNode.rawText);     // " This is a comment "
165
console.log(commentNode.text);        // " This is a comment "
166
console.log(commentNode.toString());  // "<!-- This is a comment -->"
167

168
// Create comment programmatically
169
const newComment = new CommentNode(' New comment ');
170
root.appendChild(newComment);
171
```
172

173
### NodeType Enum
174

175
Enumeration defining constants for different node types following DOM standards.
176

177
```typescript { .api }
178
enum NodeType {
179
  /** HTMLElement nodes */
180
  ELEMENT_NODE = 1,
181
  
182
  /** TextNode nodes */
183
  TEXT_NODE = 3,
184
  
185
  /** CommentNode nodes */
186
  COMMENT_NODE = 8
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import { parse, NodeType } from "node-html-parser";
194

195
const root = parse('<!--comment--><div>text</div>', { comment: true });
196

197
root.childNodes.forEach(node => {
198
  switch (node.nodeType) {
199
    case NodeType.ELEMENT_NODE:
200
      console.log('Element:', node.tagName);
201
      break;
202
    case NodeType.TEXT_NODE:
203
      console.log('Text:', node.text);
204
      break;
205
    case NodeType.COMMENT_NODE:
206
      console.log('Comment:', node.rawText);
207
      break;
208
  }
209
});
210
```
211

212
## Working with Mixed Content
213

214
When working with elements containing mixed content (text, elements, and comments), you can iterate through all child nodes:
215

216
```typescript
217
import { parse, NodeType, HTMLElement, TextNode, CommentNode } from "node-html-parser";
218

219
const mixed = parse(`
220
<div>
221
  Start text
222
  <!-- A comment -->
223
  <p>Paragraph</p>
224
  End text
225
</div>
226
`, { comment: true });
227

228
mixed.childNodes.forEach(node => {
229
  if (node.nodeType === NodeType.ELEMENT_NODE) {
230
    const element = node as HTMLElement;
231
    console.log(`Element: ${element.tagName}`);
232
  } else if (node.nodeType === NodeType.TEXT_NODE) {
233
    const textNode = node as TextNode;
234
    if (!textNode.isWhitespace) {
235
      console.log(`Text: "${textNode.text.trim()}"`);
236
    }
237
  } else if (node.nodeType === NodeType.COMMENT_NODE) {
238
    const comment = node as CommentNode;
239
    console.log(`Comment: ${comment.rawText}`);
240
  }
241
});
242
```
243

244
## Node Constructors
245

246
All node types can be created programmatically:
247

248
```typescript { .api }
249
/** Create new HTMLElement */
250
new HTMLElement(
251
  tagName: string,
252
  keyAttrs: { id?: string; class?: string },
253
  rawAttrs?: string,
254
  parentNode?: HTMLElement | null,
255
  range?: [number, number]
256
);
257

258
/** Create new TextNode */
259
new TextNode(
260
  rawText: string,
261
  parentNode?: HTMLElement | null,
262
  range?: [number, number]
263
);
264

265
/** Create new CommentNode */
266
new CommentNode(
267
  rawText: string,
268
  parentNode?: HTMLElement | null,
269
  range?: [number, number],
270
  rawTagName?: string
271
);
272
```
273

274
**Usage Examples:**
275

276
```typescript
277
import { HTMLElement, TextNode, CommentNode } from "node-html-parser";
278

279
// Create elements programmatically
280
const div = new HTMLElement('div', { id: 'container', class: 'main' });
281
const text = new TextNode('Hello world');
282
const comment = new CommentNode(' TODO: Add more content ');
283

284
div.appendChild(text);
285
div.appendChild(comment);
286

287
console.log(div.toString());
288
// <div id="container" class="main">Hello world<!-- TODO: Add more content --></div>
289
```