xmldoc

Introduction

xmldoc lets you parse XML documents with ease. It's a lightweight XML document class with a single dependency on the excellent sax parser.

For more on why I wrote this class, see the blog post.

xmldoc is written in TypeScript and ships full type definitions. As of version 3.0 it is published as an ESM-only package (import only); if you need CommonJS require() support, stay on the 2.x line.

Release Notes

See CHANGELOG.md for details.

Installation

npm install xmldoc
# or
yarn add xmldoc

Usage

import { XmlDocument } from "xmldoc";

const document = new XmlDocument("<some>xml</some>");

React Native

If you're using React Native, you may need to install buffer and stream separately:

npm install buffer stream xmldoc

Classes

The primary exported class is XmlDocument, which you'll use to consume your XML text. XmlDocument contains a hierarchy of XmlElement instances representing the XML structure.

Both XmlElement and XmlDocument contain the same members and methods you can call to traverse the document or a subtree.

Members

Methods

All methods with child in the name operate only on direct children; they do not do a deep/recursive search.

It's important to note that xmldoc is designed for when you know exactly what you want from your XML file. For instance, it's great for parsing API responses with known structures, but it's not great at teasing things out of HTML documents from the web.

If you need to do lots of searching through your XML document, I highly recommend trying a different library like node-elementtree.

eachChild(func)

Similar to underscore's each method, it will call func(child, index, array) for each child of the given node.

childNamed(name)

Pass it the name of a child node and it will search for and return the first one found, or undefined.

childrenNamed(name)

Like childNamed but returns all matching children in an array, or [].

childWithAttribute(name,value)

Searches for the first child with the given attribute value. You can omit value to just find the first node with the given attribute defined at all.

descendantWithPath(path)

Searches for a specific "path" using dot notation. Example:

<book>
  <author>
    <name isProper="true">George R. R. Martin</name>
    ...
  </author>
  ...
</book>

If you just want the <name> node and you have the XmlElement for the <book> node, you can say:

const nameNode = bookNode.descendantWithPath("author.name"); // return <name> node

valueWithPath(path)

Just like descendantWithPath, but goes deeper and extracts the val of the node. Example:

const authorName = bookNode.valueWithPath("author.name"); // return "George R. R. Martin"

You can also use the @ character to request the value of a particular attribute instead:

const authorIsProper = bookNode.valueWithPath("author.name@isProper"); // return "true"

This is not XPath! It's just a thing I made up, OK?

toString([options])

This is just an override of the standard JavaScript method, it will give you a string representation of your XML document or element. Note that this is for debugging only! It is not guaranteed to always output valid XML.

The default implementation of toString(), that is, the one you get when you just console.log("Doc: " + myDoc) will pretty-print the XML with linebreaks and indents. You can pass a couple options to control the output:

xml.toString({ compressed: true }); // strips indents and linebreaks
xml.toString({ trimmed: true }); // trims long strings for easier debugging
xml.toString({ preserveWhitespace: true }); // prevents whitespace from being removed from around element values
xml.toString({ html: true }); // uses HTML self-closing tag rules for elements without children

Putting it all together:

const xml =
  "<author><name>Lorem ipsum dolor sit amet, consectetur</name></author>";
console.log(
  "My document: \n" + new XmlDocument(xml).toString({ trimmed: true }),
);

Prints:

My document:
<author>
  <name>Lorem ipsum dolor sit ame…</name>
</author>

Feedback

Feel free to file issues or hit me up on X.