155 lines
5.9 KiB
Markdown
155 lines
5.9 KiB
Markdown
# xml-streamer
|
|
|
|
[](https://travis-ci.org/Sai1919/xml-streamer)
|
|
## Motivation
|
|
|
|
You use [Node.js](https://nodejs.org) for speed? You process XML streams? Then you want the fastest XML to JS parser: xml-streamer
|
|
|
|
## Install
|
|
|
|
```
|
|
npm install xml-streamer
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
```javascript
|
|
(function () {
|
|
"use strict";
|
|
|
|
var Parser = require('xml-streamer')
|
|
var opts = {resourcePath: '/items/item'}
|
|
|
|
var parser = new Parser(opts)
|
|
|
|
parser.on('data', function (data) {
|
|
// consume the data object here
|
|
})
|
|
|
|
parser.on('end', function () {
|
|
// parsing ended no more data events will be raised
|
|
})
|
|
|
|
parser.on('error', function (error) {
|
|
// error occurred
|
|
// NOTE: when error emit emitted no end event will be emitted
|
|
console.error(error)
|
|
})
|
|
|
|
xmlStream.pipe(parser) // pipe your input xmlStream to parser.
|
|
// readable
|
|
parser.on('readable', function () {
|
|
// if you don't want to consume "data" on "data" events you can wait for readable event and consume data by calling parser.read()
|
|
})
|
|
}())
|
|
|
|
```
|
|
|
|
## API
|
|
|
|
* `#on('readable' function () {})`
|
|
* `#on('end' function () {})` `Note: No end event will be emmited when error is emitted`
|
|
* `#on('error' function (err) {})`
|
|
* `#on('nodeName' function (err) {})` //if you are interested to listen on the "nodeName" instead of "data"
|
|
* `#stop()` pauses
|
|
* `#resume()` resumes
|
|
* `#read()` returns object if stream is readable
|
|
|
|
## Available Constructor Options
|
|
|
|
* `resourcePath`: `Type: String` Manditory field. Used to extract the XML nodes that you are interested in.
|
|
|
|
// Ex: let the XML be
|
|
```xml
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<items>
|
|
<item id="1" test= 'hello'>
|
|
<subitem sub= "TESTING SUB">one</subitem>
|
|
<subitem sub= "2">two</subitem>
|
|
</item>
|
|
<item id="2">
|
|
<subitem>three</subitem>
|
|
<subitem>four</subitem>
|
|
<subitem>five</subitem>
|
|
</item>
|
|
</items>
|
|
```
|
|
if you are interested in `item` nodes then resourcePath would be: `/items/item`
|
|
if you are interested in `subitem` nodes then resourcePath would be: `/items/item/subitem`
|
|
if you are interested in `items` nodes then resourcePath would be: `/items`
|
|
|
|
* `emitOnNodeName`: `Type: Boolean` Optional field. Set this to true if you want to listen on node names instead of data event. `default: false`
|
|
|
|
// Ex: consider the above XML snippet
|
|
```javascript
|
|
if you are interested in `item` nodes. You can listen for `data` event by default to get those nodes in JS object form
|
|
|
|
parser.on('data', function (data) {
|
|
// item nodes as javascipt objects
|
|
})
|
|
|
|
or else you can set `emitOnNodeName: true` and listen on node names like
|
|
|
|
parser.on('item', function (data) {
|
|
// item nodes as javascipt objects
|
|
})
|
|
```
|
|
|
|
`NOTE:` when you set `emitOnNodeName:true` "data" events are emitted normally. So make sure you don't listen for both the events.
|
|
|
|
* `attrsKey`: `Type: String` Optional field. pass the value with which you want to reference attributes of a node in its object form. `default: '$'`
|
|
|
|
* `textKey`: `Type: String` Optional field. pass the value with which you want to reference node value in its object form. `default: '_'`
|
|
|
|
// In the above XML snippet `subitem` node will look like this after converted to javascript object
|
|
```javascript
|
|
{
|
|
"$": {
|
|
"sub": "TESTING SUB"
|
|
}
|
|
"_": "one"
|
|
}
|
|
// if you want like this
|
|
{
|
|
"attrs": {
|
|
"sub": "TESTING SUB"
|
|
},
|
|
"text": "one"
|
|
}
|
|
```
|
|
// Then set `attrsKey= "attrs"` and `textKey= "text"`
|
|
|
|
|
|
## upcoming features
|
|
|
|
1. `allowing to listen on interested nodes instead of passing resourcePath in options`
|
|
2. `handling of compressed streams`
|
|
3. `handling of different encodings`
|
|
|
|
|
|
## Namespace handling
|
|
|
|
A word about special parsing of *xmlns:* Note that "resourcePath" in the options is not an XPATH.
|
|
So the value given to the resourcePath is treated as simple value and no expression evaluations are done.
|
|
|
|
## Benchmark
|
|
|
|
`xml-streamer` internally uses `node-expat`
|
|
|
|
`npm run benchmark`
|
|
|
|
| module | ops/sec | native | XML compliant | stream |
|
|
|---------------------------------------------------------------------------------------|--------:|:------:|:-------------:|:--------------:|
|
|
| [sax-js](https://github.com/isaacs/sax-js) | 99,412 | ☐ | ☑ | ☑ |
|
|
| [node-xml](https://github.com/dylang/node-xml) | 130,631 | ☐ | ☑ | ☑ |
|
|
| [libxmljs](https://github.com/polotek/libxmljs) | 276,136 | ☑ | ☑ | ☐ |
|
|
| **node-expat** | 322,769 | ☑ | ☑ | ☑ |
|
|
|
|
Higher is better.
|
|
|
|
## Testing
|
|
|
|
```
|
|
npm install -g standard
|
|
npm test
|
|
``` |