@xmldom/xmldom

What is @xmldom/xmldom?

The @xmldom/xmldom package is a pure JavaScript W3C standard-based (XML DOM Level 2 Core) DOMParser and XMLSerializer module. It allows users to parse XML strings into a DOM tree and serialize DOM objects back into XML strings. This package is useful for server-side and client-side manipulation of XML data.

What are @xmldom/xmldom's main functionalities?

Parsing XML to DOM

This feature allows you to parse a string of XML and create a DOM tree, which can then be manipulated or queried.

const { DOMParser } = require('@xmldom/xmldom');
const xmlString = '<root><child>Hello World</child></root>';
const doc = new DOMParser().parseFromString(xmlString, 'text/xml');
console.log(doc.documentElement.nodeName); // 'root'

Serializing DOM to XML

This feature enables you to take a DOM tree and convert it back into a string of XML, which can be stored or transmitted.

const { XMLSerializer } = require('@xmldom/xmldom');
const doc = new DOMParser().parseFromString('<root></root>', 'text/xml');
doc.documentElement.appendChild(doc.createElement('child'));
const xmlString = new XMLSerializer().serializeToString(doc);
console.log(xmlString); // '<root><child/></root>'

Manipulating DOM

This feature demonstrates how to manipulate the DOM tree by changing the text content of an element.

const { DOMParser } = require('@xmldom/xmldom');
const xmlString = '<root><child>Old Value</child></root>';
const doc = new DOMParser().parseFromString(xmlString, 'text/xml');
doc.getElementsByTagName('child')[0].textContent = 'New Value';
const newXmlString = new XMLSerializer().serializeToString(doc);
console.log(newXmlString); // '<root><child>New Value</child></root>'

Other packages similar to @xmldom/xmldom

libxmljs

libxmljs is a Node.js package that provides bindings to the libxml C library. It allows for parsing and serializing XML, and it is known for its high performance. However, it requires compiling native code, which can be a disadvantage compared to the pure JavaScript implementation of @xmldom/xmldom.

cheerio

Cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It can parse markup and provides an API for manipulating the resulting data structure, similar to jQuery. While it is not a full XML DOM parser, it can handle a subset of XML and is often used for web scraping and server-side DOM manipulation.

jsdom

jsdom is a pure-JavaScript implementation of many web standards, notably the WHATWG DOM and HTML Standards, for use with Node.js. It is designed to simulate a web browser's environment and can be used to test and scrape web applications. jsdom is more comprehensive than @xmldom/xmldom as it includes support for HTML and the DOM Level 3, but it is also heavier and more complex.

README

@xmldom/xmldom

The currently active maintainers decided to publish this code as @xmldom/xmldom because the npm library xmldom contains security issues but can currently not be published by us.

For better readability in the docs we will continue to talk about this library as "xmldom".

xmldom is a javascript ponyfill for the following APIs supported in browsers:

• 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)

Note that this xmldom library is not required if your code targets a modern browser. But this library is recommended if your code needs to also work in other runtimes like NodeJS or Rhino.

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.

xmldom implements the following interfaces (most constructors are currently not exposed):

• Attr
• CDATASection
• CharacterData
• Comment
• Document
• DocumentFragment
• DocumentType
• DOMException (constructor exposed)
• DOMImplementation (constructor exposed)
• Element
• Entity
• EntityReference
• LiveNodeList
• NamedNodeMap
• Node (constructor exposed)
• 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 "detecting HTML" (by checking the default namespace). There is an upcoming change to better align the implementation with the latest specs, related to https://github.com/xmldom/xmldom/issues/203.

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:

• XMLReader
• DOMHandler

There is an idea/proposal to make ti possible to replace it with something else in https://github.com/xmldom/xmldom/issues/55

Forked

Original project location: https://github.com/jindw/xmldom

More details about the transition can be found in the CHANGELOG and in https://github.com/xmldom/xmldom/issues/62

Usage

Install:

npm install @xmldom/xmldom

Example:

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

const doc = new DOMParser().parseFromString(
    '<xml xmlns="a" xmlns:c="./lite">\n' +
        '\t<child>test</child>\n' +
        '\t<child></child>\n' +
        '\t<child/>\n' +
        '</xml>',
    'text/xml'
)
doc.documentElement.setAttribute('x', 'y')
doc.documentElement.setAttributeNS('./lite', 'c:x', 'y2')
console.info(doc)

const nsAttr = doc.documentElement.getAttributeNS('./lite', 'x')
console.info(nsAttr)

Note: in Typescript and ES6 you can use the import approach, as follows:

import { DOMParser } from '@xmldom/xmldom'

API Reference

• DOMParser:

  parseFromString(xmlsource,mimeType)
  

  • options extension by xmldom(not BOM standard!!)

  //added the options argument
  new DOMParser(options)
  
  //errorHandler is supported
  new DOMParser({
  	/**
  	 * locator is always need for error position info
  	 */
  	locator:{},
  	/**
  	 * you can override the errorHandler for xml parser
  	 * @link http://www.saxproject.org/apidoc/org/xml/sax/ErrorHandler.html
  	 */
  	errorHandler:{warning:function(w){console.warn(w)},error:callback,fatalError:callback}
  	//only callback model
  	//errorHandler:function(level,msg){console.log(level,msg)}
  })
  	
  

• XMLSerializer

  serializeToString(node)
  

DOM level2 method and attribute:

• Node

   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 The DOMException class has the following constants (and value of type Number):

  1. DOMException.INDEX_SIZE_ERR (1)
  2. DOMException.DOMSTRING_SIZE_ERR (2)
  3. DOMException.HIERARCHY_REQUEST_ERR (3)
  4. DOMException.WRONG_DOCUMENT_ERR (4)
  5. DOMException.INVALID_CHARACTER_ERR (5)
  6. DOMException.NO_DATA_ALLOWED_ERR (6)
  7. DOMException.NO_MODIFICATION_ALLOWED_ERR (7)
  8. DOMException.NOT_FOUND_ERR (8)
  9. DOMException.NOT_SUPPORTED_ERR (9)
  10. DOMException.INUSE_ATTRIBUTE_ERR (10)
  11. DOMException.INVALID_STATE_ERR (11)
  12. DOMException.SYNTAX_ERR (12)
  13. DOMException.INVALID_MODIFICATION_ERR (13)
  14. DOMException.NAMESPACE_ERR (14)
  15. DOMException.INVALID_ACCESS_ERR (15)

  The DOMException object has the following properties: code This property is of type Number.

  • extends the Error type thrown as part of DOM API:

• DOMImplementation

   method:
   	hasFeature(feature, version)
   	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:
    	//Numbered starting from '1'
    	lineNumber
    	//Numbered starting from '1'
    	columnNumber
  

Changelog

0.7.0

Commits

Due to #271 this version was published as

• unscoped xmldom package to github (git tags 0.7.0 and 0.7.0+unscoped)
• scoped @xmldom/xmldom package to npm (git tag 0.7.0+scoped) For more details look at #278

Fixes:

• Security: Misinterpretation of malicious XML input CVE-2021-32796
• Implement Document.getElementsByClassName as specified #213, thank you, @ChALkeR
• Inherit namespace prefix from parent when required #268
• Handle whitespace in closing tags #267
• Update DOMImplementation according to recent specs #210
  BREAKING CHANGE: Only if you "passed features to be marked as available as a constructor arguments" and expected it to "magically work".
• No longer serializes any namespaces with an empty URI #244
  (related to #168 released in 0.6.0)
  BREAKING CHANGE: Only if you rely on "unsetting" a namespace prefix by setting it to an empty string
• Set localName as part of Document.createElement #229, thank you, @rrthomas

CI

• We are now additionally running tests against node v16
• Stryker tests on the master branch now run against node v14

Docs

• Describe relations with and between specs: #211, #247