xml-query: A JavaScript repository from eppsilon

Super small (~60 LOC) library for retrieving values and attributes
from the XML AST generated by xml-reader
with an easy-to-use jQuery-like interface.

Install

npm install --save xml-query

Usage

Reading xml streams/strings

The following XML will be used to illustrate all examples

<message id="1001" date="2016-06-19">
    <from>Bob</from>
    <to>Alice</to>
    <subject>Hello</subject>
    <body>Bla bla bla</body>
</message>

Let's read the XML using xml-reader.

const XmlReader = require('xml-reader');

const xml =
`<message id="1001" date="2016-06-19">
    <from>Bob</from>
    <to>Alice</to>
    <subject>Hello</subject>
    <body>Bla bla bla</body>
</message>`;

const ast = XmlReader.parseSync(xml);

xmlQuery()

const xmlQuery = require('xml-query');

// creating from single ast
const xq = xmlQuery(ast);

// creating from an array of asts
const xq = xmlQuery([ast, ...more]);

.get()

Retrieve one of the elements.

xmlQuery(ast).find('body').get(2); // returns the `subject` node

.find()

Find by name. Including top level nodes and all its children.

xmlQuery(ast).find('body'); // xmlQuery containing the body element

.has()

Returns true if it has the given element. Faster than find() because it stops on first occurence.

xmlQuery(ast).has('body'); // true

.attr()

Get all attributes. If a name is provided, it returns the value for that key.

xmlQuery(ast).attr(); // {id: '1001', date: '2016-06-19'}
xmlQuery(ast).attr('id'); // '1001'

.children()

Returns a new xmlQuery object containing the children of the top level elements.

xmlQuery(ast).children();

.each()

Iterate over a xmlQuery object, executing a function for each element.

xmlQuery(ast).each(node => console.log(node.name));
// from
// to
// subject
// body

.map()

Iterate over a xmlQuery object, executing a function for each element. Returns the results in an array.

xmlQuery(ast).map(node => node.name); // ['from', 'to', 'subject', 'body']

.prop()

Get the value of a property for the first element in the set.

xmlQuery(ast).prop('name'); // 'message'

.text()

Get the combined text contents of each element, including their descendants

xmlQuery(ast).find('subject').text(); // 'hello'

.eq()

Returns a new XmlQuery object for the selected element by index

xmlQuery(ast).children().eq(2); // xmlQuery containing the 'subject' node

.first()

Returns a new XmlQuery object for the first element. Same as .eq(0)

xmlQuery(ast).children().first(); // xmlQuery containing the 'from' node

.last()

Returns a new XmlQuery object for the last element. Same as .eq(length - 1)

xmlQuery(ast).children().last(); // xmlQuery containing the 'body' node

.length

Number of elements. Returns the same result as .size()

xmlQuery(ast).children().length; // 4

.size()

Number of elements. Returns the same result as .length

xmlQuery(ast).children().size(); // 4

License

MIT

eppsilon/xml-query