XML stream to JavaScript object converter based on sax-js.
npm install xml-stream-saxxml-stream-sax is a Node.js XML stream parser and editor. It is a fork of
xml-stream that replaces node-expat
with sax-js. For most people this
distinction doesn't matter, but I was seeing some very strange bugs in node-expat
with large files, and switching to sax-js made those bugs go away.
$ yarn add xml-stream-sax
There may be minor differences in behavior compared to xml-stream, but most
stuff should be the same.
When working with large XML files, it is probably a bad idea to use an XML to
JavaScript object converter, or simply buffer the whole document in memory.
Then again, a typical SAX parser might be too low-level for some tasks (and
often a real pain).
This is why we've rolled our own stream parser that tries to address these
shortcomings. It processes an XML stream chunk by chunk and fires events only
for nodes of interest, matching them with CSS-like selectors.
Supported events:
* data on outgoing data chunk,
* end when parsing has ended,
* startElement[: selector] on opening tag for selector match,
* updateElement[: selector] on finished node for selector match
with its contents buffered,
* endElement[: selector] on closing tag for selector match,
* text[: selector] on tag text for selector match.
When adding listeners for startElement, updateElement, and text the
callback can modify the provided node, before it is sent to the consumer.
Selector syntax is CSS-like and currently supports:
* ancestor descendant
* parent > child
Take a look at the examples for more information.
Each of the four node events has a callback with one argument. When parsing,
this argument is set to the current matched node. Having a chunk of XML like
this:
``xml`
(text)
The structure of the item element node would be:
`javascript`
{
title: 'Item Title',
description: 'Description of this item.',
'$': {
'id': '123',
'type': 'common'
},
'$name': 'item',
'$text': '(text)'
}
Naturally, element text and child elements wouldn't be known until discovered
in the stream, so the structure may differ across events. The complete
structure as displayed should be available on updateElement. The $name
is not available on endElement.
It is sometimes required to select elements that have many children with
one and the same name. Like this XML:
`xml`
By default, parsed element node contains children as properties. In the case
of several children with same names, the last one would overwrite others.
To collect all of subitem elements in an array use collect:
`javascript`
xml.collect('subitem');
xml.on('endElement: item', function(item) {
console.log(item);
})
By default, element text is returned as one concatenated string. In this XML:
`xml`
one 1
two 2
The value of $text for item would be: one 1 two 2 without any
indication of the order of element a, element b, and text parts.
To preserve this order:
`javascript``
xml.preserve('item');
xml.on('endElement: item', function(item) {
console.log(item);
})