@xmldom/xmldom

Since version 0.7.0 this package is published to npm as @xmldom/xmldom and no longer as xmldom, because we are no longer able to publish xmldom.
For better readability in the docs, we will continue to talk about this library as "xmldom".

xmldom is a javascript ponyfill to provide the following APIs that are present in modern browsers to other runtimes:

convert an XML string into a DOM tree

new DOMParser().parseFromString(xml, mimeType) => Document

create, access and modify a DOM tree

new DOMImplementation().createDocument(...) => Document

serialize a DOM tree back into an XML string

new XMLSerializer().serializeToString(node) => string

The target runtimes xmldom supports are currently Node >= v10 (ES5) and Rhino (not tested as part of CI).

When deciding how to fix bugs or implement features, xmldom tries to stay as close as possible to the various related specifications/standards.
As indicated by the version starting with 0., this implementation is not feature complete and some implemented features differ from what the specifications describe.
Issues and PRs for such differences are always welcome, even when they only provide a failing test case.

This project was forked from it's original source in 2019, more details about that transition can be found in the CHANGELOG.

Usage

Install:

npm install @xmldom/xmldom

Example:

In NodeJS

const { DOMParser, XMLSerializer } = require('@xmldom/xmldom')

const source = `<xml xmlns="a">
	<child>test</child>
	<child/>
</xml>`

const doc = new DOMParser().parseFromString(source, 'text/xml')

const serialized = new XMLSerializer().serializeToString(doc)

Note: in Typescript ~~and ES6~~ (see #316) you can use the import approach, as follows:

import { DOMParser } from '@xmldom/xmldom'

API Reference

DOMParser:

parseFromString(xmlsource, mimeType)

options extension by xmldom (not DOM standard!!)

// the options argument can be used to modify behavior
// for more details check the documentation on the code or type definition  
new DOMParser(options)

XMLSerializer
```
serializeToString(node)
```

DOM level2 method and attribute:

Node

readonly class properties (aka NodeType),
these can be accessed from any Node instance node:
if (node.nodeType === node.ELEMENT_NODE) {...
1. ELEMENT_NODE (1)
2. ATTRIBUTE_NODE (2)
3. TEXT_NODE (3)
4. CDATA_SECTION_NODE (4)
5. ENTITY_REFERENCE_NODE (5)
6. ENTITY_NODE (6)
7. PROCESSING_INSTRUCTION_NODE (7)
8. COMMENT_NODE (8)
9. DOCUMENT_NODE (9)
10. DOCUMENT_TYPE_NODE (10)
11. DOCUMENT_FRAGMENT_NODE (11)
12. NOTATION_NODE (12)
attribute:
- nodeValue | prefix
readonly attribute:
- nodeName | nodeType | parentNode | childNodes | firstChild | lastChild | previousSibling | nextSibling | attributes | ownerDocument | namespaceURI | localName
method:
- insertBefore(newChild, refChild)
- replaceChild(newChild, oldChild)
- removeChild(oldChild)
- appendChild(newChild)
- hasChildNodes()
- cloneNode(deep)
- normalize()
- isSupported(feature, version)
- hasAttributes()
DOMException

extends the Error type thrown as part of DOM API.

readonly class properties:
- INDEX_SIZE_ERR (1)
- DOMSTRING_SIZE_ERR (2)
- HIERARCHY_REQUEST_ERR (3)
- WRONG_DOCUMENT_ERR (4)
- INVALID_CHARACTER_ERR (5)
- NO_DATA_ALLOWED_ERR (6)
- NO_MODIFICATION_ALLOWED_ERR (7)
- NOT_FOUND_ERR (8)
- NOT_SUPPORTED_ERR (9)
- INUSE_ATTRIBUTE_ERR (10)
- INVALID_STATE_ERR (11)
- SYNTAX_ERR (12)
- INVALID_MODIFICATION_ERR (13)
- NAMESPACE_ERR (14)
- INVALID_ACCESS_ERR (15)
attributes:
- code with a value matching one of the above constants.
DOMImplementation

method:
- hasFeature(feature, version) (deprecated)
- createDocumentType(qualifiedName, publicId, systemId)
- createDocument(namespaceURI, qualifiedName, doctype)
Document : Node

readonly attribute:
- doctype | implementation | documentElement
method:
- createElement(tagName)
- createDocumentFragment()
- createTextNode(data)
- createComment(data)
- createCDATASection(data)
- createProcessingInstruction(target, data)
- createAttribute(name)
- createEntityReference(name)
- getElementsByTagName(tagname)
- importNode(importedNode, deep)
- createElementNS(namespaceURI, qualifiedName)
- createAttributeNS(namespaceURI, qualifiedName)
- getElementsByTagNameNS(namespaceURI, localName)
- getElementById(elementId)
DocumentFragment : Node
Element : Node

readonly attribute:
- tagName
method:
- getAttribute(name)
- setAttribute(name, value)
- removeAttribute(name)
- getAttributeNode(name)
- setAttributeNode(newAttr)
- removeAttributeNode(oldAttr)
- getElementsByTagName(name)
- getAttributeNS(namespaceURI, localName)
- setAttributeNS(namespaceURI, qualifiedName, value)
- removeAttributeNS(namespaceURI, localName)
- getAttributeNodeNS(namespaceURI, localName)
- setAttributeNodeNS(newAttr)
- getElementsByTagNameNS(namespaceURI, localName)
- hasAttribute(name)
- hasAttributeNS(namespaceURI, localName)
Attr : Node

attribute:
- value
readonly attribute:
- name | specified | ownerElement
NodeList

readonly attribute:
- length
method:
- item(index)
NamedNodeMap

readonly attribute:
- length
method:
- getNamedItem(name)
- setNamedItem(arg)
- removeNamedItem(name)
- item(index)
- getNamedItemNS(namespaceURI, localName)
- setNamedItemNS(arg)
- removeNamedItemNS(namespaceURI, localName)
CharacterData : Node

method:
- substringData(offset, count)
- appendData(arg)
- insertData(offset, arg)
- deleteData(offset, count)
- replaceData(offset, count, arg)
Text : CharacterData

method:
- splitText(offset)
CDATASection
Comment : CharacterData
DocumentType

readonly attribute:
- name | entities | notations | publicId | systemId | internalSubset
Notation : Node

readonly attribute:
- publicId | systemId
Entity : Node

readonly attribute:
- publicId | systemId | notationName
EntityReference : Node
ProcessingInstruction : Node

attribute:
- data readonly attribute:
- target

DOM level 3 support:

Node

attribute:
- textContent
method:
- isDefaultNamespace(namespaceURI)
- lookupNamespaceURI(prefix)

DOM extension by xmldom

[Node] Source position extension;

attribute:
- lineNumber //number starting from 1
- columnNumber //number starting from 1

Specs

The implementation is based on several specifications:

DOM Parsing and Serialization

From the W3C DOM Parsing and Serialization (WD 2016) xmldom provides an implementation for the interfaces:

DOMParser
XMLSerializer

Note that there are some known deviations between this implementation and the W3 specifications.

Note: The latest version of this spec has the status "Editors Draft", since it is under active development. One major change is that the definition of the DOMParser interface has been moved to the HTML spec

DOM

The original author claims that xmldom implements [DOM Level 2] in a "fully compatible" way and some parts of [DOM Level 3], but there are not enough tests to prove this. Both Specifications are now superseded by the [DOM Level 4 aka Living standard] wich has a much broader scope than xmldom. In the past, there have been multiple (even breaking) changes to align xmldom with the living standard, so if you find a difference that is not documented, any contribution to resolve the difference is very welcome (even just reporting it as an issue).

xmldom implements the following interfaces (only the ones marked with * are currently exposed):

Attr *
CDATASection
CharacterData
Comment
Document *
DocumentFragment
DocumentType *
DOMException *
DOMImplementation *
Element *
Entity
EntityReference
LiveNodeList
NamedNodeMap *
Node *
NodeList *
Notation
ProcessingInstruction
Text

more details are available in the (incomplete) API Reference section.

HTML

xmldom does not have any goal of supporting the full spec, but it has some capability to parse, report and serialize things differently when it is told to parse HTML (by passing the HTML namespace).

SAX, XML, XMLNS

xmldom has an own SAX parser implementation to do the actual parsing, which implements some interfaces in alignment with the Java interfaces SAX defines: