0
# xmldom
1

2
xmldom is a pure JavaScript implementation of the W3C DOM (Document Object Model) Level 2 Core specification, providing complete XML parsing and manipulation capabilities for Node.js, Rhino, and browser environments. It offers standard DOMParser and XMLSerializer interfaces that are fully compatible with browser implementations, enabling seamless XML document processing across different JavaScript environments.
3

4
## Package Information
5

6
- **Package Name**: xmldom
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES5 compatible)
9
- **Installation**: `npm install xmldom`
10

11
## Core Imports
12

13
```javascript
14
const { DOMParser, XMLSerializer, DOMImplementation, Node, DOMException } = require('xmldom');
15
```
16

17
For ES6/TypeScript:
18

19
```javascript
20
import { DOMParser, XMLSerializer, DOMImplementation, Node, DOMException } from 'xmldom';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { DOMParser, XMLSerializer } = require('xmldom');
27

28
// Parse XML string into DOM document
29
const parser = new DOMParser();
30
const doc = parser.parseFromString(`
31
  <books>
32
    <book id="1" title="XML Processing" />
33
    <book id="2" title="DOM Manipulation" />
34
  </books>
35
`, 'text/xml');
36

37
// Access and manipulate DOM
38
const books = doc.getElementsByTagName('book');
39
console.log(books.length); // 2
40
console.log(books.item(0).getAttribute('title')); // "XML Processing"
41

42
// Add new element
43
const newBook = doc.createElement('book');
44
newBook.setAttribute('id', '3');
45
newBook.setAttribute('title', 'JavaScript XML');
46
doc.documentElement.appendChild(newBook);
47

48
// Serialize back to XML string
49
const serializer = new XMLSerializer();
50
const xmlString = serializer.serializeToString(doc);
51
console.log(xmlString);
52
```
53

54
## Architecture
55

56
xmldom implements the complete W3C DOM Level 2 Core specification with the following key components:
57

58
- **Parser Interface**: DOMParser for converting XML strings to DOM documents with robust error handling
59
- **Serializer Interface**: XMLSerializer for converting DOM nodes back to XML strings  
60
- **DOM Node Hierarchy**: Complete implementation of Node, Document, Element, Attr, Text, and other DOM node types
61
- **Collection Interfaces**: NodeList and NamedNodeMap for managing collections of nodes and attributes
62
- **Namespace Support**: Full XML Namespace support with namespace-aware methods and properties
63
- **Error Handling**: Comprehensive DOMException system with detailed error codes and messages
64
- **SAX-style Parsing**: Internal SAX parser for efficient XML processing with configurable error handlers
65

66
## Capabilities
67

68
### XML Parsing
69

70
Core XML parsing functionality with configurable error handling, namespace support, and both XML and HTML parsing modes.
71

72
```javascript { .api }
73
class DOMParser {
74
  constructor(options?: {
75
    locator?: object;
76
    errorHandler?: {
77
      warning?: (msg: string) => void;
78
      error?: (msg: string) => void;
79
      fatalError?: (msg: string) => void;
80
    } | ((level: string, msg: string) => void);
81
    xmlns?: object;
82
    domBuilder?: object;
83
  });
84
  
85
  parseFromString(source: string, mimeType: string): Document;
86
}
87
```
88

89
[XML Parsing](./xml-parsing.md)
90

91
### DOM Manipulation
92

93
Complete DOM manipulation capabilities including document creation, element manipulation, attribute handling, and tree traversal.
94

95
```javascript { .api }
96
interface Document extends Node {
97
  readonly doctype: DocumentType | null;
98
  readonly implementation: DOMImplementation;
99
  readonly documentElement: Element | null;
100
  
101
  createElement(tagName: string): Element;
102
  createTextNode(data: string): Text;
103
  createComment(data: string): Comment;
104
  getElementById(elementId: string): Element | null;
105
  getElementsByTagName(tagname: string): NodeList;
106
  getElementsByClassName(className: string): NodeList;
107
}
108

109
interface Element extends Node {
110
  readonly tagName: string;
111
  
112
  getAttribute(name: string): string;
113
  setAttribute(name: string, value: string): void;
114
  removeAttribute(name: string): void;
115
  getElementsByTagName(name: string): NodeList;
116
  hasAttribute(name: string): boolean;
117
}
118
```
119

120
[DOM Manipulation](./dom-manipulation.md)
121

122
### XML Serialization
123

124
XML serialization functionality for converting DOM nodes and documents back to XML strings with proper formatting and namespace handling.
125

126
```javascript { .api }
127
class XMLSerializer {
128
  serializeToString(node: Node, isHtml?: boolean, nodeFilter?: (node: Node) => boolean): string;
129
}
130
```
131

132
[XML Serialization](./xml-serialization.md)
133

134
### Namespace Support
135

136
Comprehensive XML Namespace support with namespace-aware methods, prefix handling, and namespace URI resolution.
137

138
```javascript { .api }
139
interface Element extends Node {
140
  getAttributeNS(namespaceURI: string, localName: string): string;
141
  setAttributeNS(namespaceURI: string, qualifiedName: string, value: string): void;
142
  removeAttributeNS(namespaceURI: string, localName: string): void;
143
  getElementsByTagNameNS(namespaceURI: string, localName: string): NodeList;
144
  hasAttributeNS(namespaceURI: string, localName: string): boolean;
145
}
146

147
interface Document extends Node {
148
  createElementNS(namespaceURI: string, qualifiedName: string): Element;
149
  createAttributeNS(namespaceURI: string, qualifiedName: string): Attr;
150
  getElementsByTagNameNS(namespaceURI: string, localName: string): NodeList;
151
}
152
```
153

154
[Namespace Support](./namespace-support.md)
155

156
### Error Handling
157

158
Robust error handling system with DOMException classes, configurable error handlers, and detailed parsing error reporting.
159

160
```javascript { .api }
161
class DOMException extends Error {
162
  readonly code: number;
163
  static readonly INDEX_SIZE_ERR: 1;
164
  static readonly DOMSTRING_SIZE_ERR: 2;
165
  static readonly HIERARCHY_REQUEST_ERR: 3;
166
  static readonly WRONG_DOCUMENT_ERR: 4;
167
  static readonly INVALID_CHARACTER_ERR: 5;
168
  // ... additional error codes
169
}
170
```
171

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

174
## Types
175

176
```javascript { .api }
177
interface Node {
178
  readonly nodeName: string;
179
  nodeValue: string | null;
180
  readonly nodeType: number;
181
  readonly parentNode: Node | null;
182
  readonly childNodes: NodeList;
183
  readonly firstChild: Node | null;
184
  readonly lastChild: Node | null;
185
  readonly previousSibling: Node | null;
186
  readonly nextSibling: Node | null;
187
  readonly attributes: NamedNodeMap | null;
188
  readonly ownerDocument: Document | null;
189
  readonly namespaceURI: string | null;
190
  prefix: string | null;
191
  readonly localName: string | null;
192
  textContent: string | null;
193
  
194
  insertBefore(newChild: Node, refChild: Node | null): Node;
195
  replaceChild(newChild: Node, oldChild: Node): Node;
196
  removeChild(oldChild: Node): Node;
197
  appendChild(newChild: Node): Node;
198
  hasChildNodes(): boolean;
199
  cloneNode(deep: boolean): Node;
200
  normalize(): void;
201
  isSupported(feature: string, version: string): boolean;
202
  hasAttributes(): boolean;
203
}
204

205
interface NodeList {
206
  readonly length: number;
207
  item(index: number): Node | null;
208
}
209

210
interface NamedNodeMap {
211
  readonly length: number;
212
  getNamedItem(name: string): Node | null;
213
  setNamedItem(arg: Node): Node | null;
214
  removeNamedItem(name: string): Node;
215
  item(index: number): Node | null;
216
  getNamedItemNS(namespaceURI: string, localName: string): Node | null;
217
  setNamedItemNS(arg: Node): Node | null;
218
  removeNamedItemNS(namespaceURI: string, localName: string): Node;
219
}
220

221
interface DOMImplementation {
222
  hasFeature(feature: string, version: string): boolean;
223
  createDocumentType(qualifiedName: string, publicId: string, systemId: string): DocumentType;
224
  createDocument(namespaceURI: string | null, qualifiedName: string | null, doctype: DocumentType | null): Document;
225
}
226

227
// DOM Node Type Constants
228
const ELEMENT_NODE: 1;
229
const ATTRIBUTE_NODE: 2;
230
const TEXT_NODE: 3;
231
const CDATA_SECTION_NODE: 4;
232
const ENTITY_REFERENCE_NODE: 5;
233
const ENTITY_NODE: 6;
234
const PROCESSING_INSTRUCTION_NODE: 7;
235
const COMMENT_NODE: 8;
236
const DOCUMENT_NODE: 9;
237
const DOCUMENT_TYPE_NODE: 10;
238
const DOCUMENT_FRAGMENT_NODE: 11;
239
const NOTATION_NODE: 12;
240
```