0
# @xmldom/xmldom
1

2
@xmldom/xmldom is a pure JavaScript ponyfill that provides W3C DOM Level 2 Core APIs for XML parsing and manipulation in Node.js and other ES5-compatible runtimes. It offers comprehensive DOM tree creation, traversal, and serialization capabilities without dependencies.
3

4
## Package Information
5

6
- **Package Name**: @xmldom/xmldom
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install @xmldom/xmldom`
10

11
## Core Imports
12

13
```javascript
14
const { DOMParser, XMLSerializer } = require('@xmldom/xmldom');
15
```
16

17
For ES modules:
18

19
```javascript
20
import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
21
```
22

23
Additional imports (for advanced usage):
24

25
```javascript
26
const {
27
  DOMParser,
28
  XMLSerializer,
29
  DOMImplementation,
30
  MIME_TYPE,
31
  NAMESPACE,
32
  DOMException,
33
  ParseError
34
} = require('@xmldom/xmldom');
35
```
36

37
Constructor classes are typically accessed through parser results:
38

39
```javascript
40
const { DOMParser } = require('@xmldom/xmldom');
41

42
const parser = new DOMParser();
43
const doc = parser.parseFromString('<root></root>', 'text/xml');
44

45
// Now you have access to DOM instances:
46
const element = doc.documentElement; // Element instance
47
const textNode = doc.createTextNode('text'); // Text instance
48
// Constructor classes (Document, Element, Node, etc.) are available
49
// but typically not imported directly
50
```
51

52
## Basic Usage
53

54
```javascript
55
const { DOMParser, XMLSerializer } = require('@xmldom/xmldom');
56

57
// Parse XML string into DOM Document
58
const parser = new DOMParser();
59
const xmlString = `<root>
60
  <child id="1">Hello</child>
61
  <child id="2">World</child>
62
</root>`;
63

64
const doc = parser.parseFromString(xmlString, 'text/xml');
65

66
// Access and manipulate DOM
67
const root = doc.documentElement;
68
const children = root.getElementsByTagName('child');
69
console.log(children.length); // 2
70

71
// Create new elements
72
const newChild = doc.createElement('child');
73
newChild.setAttribute('id', '3');
74
newChild.textContent = 'New content';
75
root.appendChild(newChild);
76

77
// Serialize back to XML string
78
const serializer = new XMLSerializer();
79
const result = serializer.serializeToString(doc);
80
console.log(result);
81
```
82

83
## Architecture
84

85
@xmldom/xmldom is structured around several key components:
86

87
- **Core Parsers**: `DOMParser` for parsing XML/HTML strings into DOM trees
88
- **Serialization**: `XMLSerializer` for converting DOM trees back to XML strings
89
- **DOM Implementation**: Full W3C DOM Level 2 Core node hierarchy with `Document`, `Element`, `Text`, etc.
90
- **Error Handling**: Robust error reporting with `DOMException` and `ParseError` classes
91
- **Standards Compliance**: Close adherence to W3C specifications with extensions for parsing configuration
92
- **Runtime Compatibility**: Works across Node.js >=14.6 and ES5-compatible environments
93

94
## Capabilities
95

96
### XML/HTML Parsing
97

98
Core parsing functionality for converting XML and HTML strings into navigable DOM documents. Supports multiple MIME types and configurable error handling.
99

100
```javascript { .api }
101
class DOMParser {
102
  constructor(options?: DOMParserOptions);
103
  parseFromString(source: string, mimeType: string): Document;
104
}
105

106
interface DOMParserOptions {
107
  locator?: boolean;
108
  normalizeLineEndings?: (source: string) => string;
109
  onError?: (level: 'warning' | 'error' | 'fatalError', msg: string, context: any) => void;
110
  xmlns?: Record<string, string | null | undefined>;
111
}
112
```
113

114
[XML/HTML Parsing](./parsing.md)
115

116
### DOM Tree Manipulation
117

118
Complete W3C DOM Level 2 Core implementation for creating, accessing, and modifying document trees. Includes all standard node types and manipulation methods.
119

120
```javascript { .api }
121
class Document extends Node {
122
  createElement(tagName: string): Element;
123
  createTextNode(data: string): Text;
124
  getElementById(elementId: string): Element | null;
125
  getElementsByTagName(qualifiedName: string): LiveNodeList<Element>;
126
}
127

128
class Element extends Node {
129
  getAttribute(name: string): string | null;
130
  setAttribute(name: string, value: string): void;
131
  getElementsByTagName(name: string): LiveNodeList<Element>;
132
}
133

134
class Node {
135
  appendChild(child: Node): Node;
136
  removeChild(child: Node): Node;
137
  cloneNode(deep?: boolean): Node;
138
}
139
```
140

141
[DOM Tree Manipulation](./dom-manipulation.md)
142

143
### XML Serialization
144

145
Convert DOM nodes back into XML strings with optional filtering and formatting control.
146

147
```javascript { .api }
148
class XMLSerializer {
149
  serializeToString(node: Node, nodeFilter?: (node: Node) => boolean): string;
150
}
151
```
152

153
[XML Serialization](./serialization.md)
154

155
### Error Handling
156

157
Comprehensive error reporting system with DOM-standard exceptions and parsing-specific error types.
158

159
```javascript { .api }
160
class DOMException extends Error {
161
  constructor(message?: string, name?: string);
162
  readonly name: string;
163
  readonly code: number;
164
}
165

166
class ParseError extends Error {
167
  constructor(message: string, locator?: any, cause?: Error);
168
  readonly locator?: any;
169
}
170
```
171

172
[Error Handling](./error-handling.md)
173

174
### Constants and Utilities
175

176
Standard DOM constants, MIME type definitions, namespace URIs, and utility functions for validation and type checking.
177

178
```javascript { .api }
179
const MIME_TYPE = {
180
  HTML: 'text/html',
181
  XML_APPLICATION: 'application/xml',
182
  XML_TEXT: 'text/xml',
183
  XML_XHTML_APPLICATION: 'application/xhtml+xml',
184
  XML_SVG_IMAGE: 'image/svg+xml'
185
};
186

187
const NAMESPACE = {
188
  HTML: 'http://www.w3.org/1999/xhtml',
189
  SVG: 'http://www.w3.org/2000/svg',
190
  XML: 'http://www.w3.org/XML/1998/namespace',
191
  XMLNS: 'http://www.w3.org/2000/xmlns/'
192
};
193

194
function isValidMimeType(mimeType: string): boolean;
195
function normalizeLineEndings(input: string): string;
196
```
197

198
[Constants and Utilities](./constants-utilities.md)