@jcsj/xml-js v2.0.0-beta.2

Convert XML text to Javascript object / JSON text (and vice versa).

Synopsis

Features

• Maintain Order of Elements: Most libraries will convert <a/><b/><a/> to {a:[{},{}],b:{}} which merges any node of same name into an array. This library can create the following to preserve the order of elements: {"elements":[{"type":"element","name":"a"},{"type":"element","name":"b"},{"type":"element","name":"a"}]}.

This is very important and it is the main reason why this library was created. Read also Compact vs Non-Compact for more info.

• Fully XML Compliant: Can parse: elements, attributes, texts, comments, CData, DOCTYPE, XML declarations, and Processing Instructions.

• Reversible: Whether converting xml→json or json→xml, the result can be converted back to its original form.

• Minimal Dependencies: This library depends only on one external npm module.

• Change Property Key Name: Usually output of XML attributes are stored in @attr, _atrr, $attr or $ in order to avoid conflicting with name of sub-elements. This library store them in attributes, but most importantly, you can change this to whatever you like.

• Support Upwards Traversal: By setting {addParent: true} option, an extra property named parent will be generated along each element so that its parent can be referenced. Therefore, anywhere during the traversal of an element, its children and its parent can be easily accessed.

• Support Command Line: To quickly convert xml or json files, this module can be installed globally or locally (i.e. use it as script in package.json).

• Customize Processing using Callback Hooks: Custom functions can be supplied to do additional processing for different parts of xml or json (like cdata, comments, elements, attributes ...etc).

• Portable Code: Written purely in JavaScript which means it can be used in Node environment and browser environment (via bundlers like browserify/JSPM/Webpack).

• Typings Info Included: Support type checking and code suggestion via intellisense. Thanks to the wonderful efforts by DenisCarriere.

Compact vs Non-Compact

Most XML to JSON converters (including online converters) convert <a/> to some compact output like {"a":{}} instead of non-compact output like {"elements":[{"type":"element","name":"a"}]}.

While compact output might work in most situations, there are cases when elements of different names are mixed inside a parent element. Lets use <a x="1"/><b x="2"/><a x="3"/> as an example. Most converters will produce compact output like this {a:[{_:{x:"1"}},{_:{x:"3"}}], b:{_:{x:"2"}}}, which has merged both <a> elements into an array. If you try to convert this back to xml, you will get <a x="1"/><a x="3"/><b x="2"/> which has not preserved the order of elements!

The reason behind this behavior is due to the inherent limitation in the compact representation. Because output like {a:{_:{x:"1"}}, b:{_:{x:"2"}}, a:{_:{x:"3"}}} is illegal (same property name a should not appear twice in an object). This leaves no option but to use array {a:[{_:{x:"1"}},{_:{x:"3"}}].

The non-compact output, which is supported by this library, will produce more information and always guarantees the order of the elements as they appeared in the XML file.

Another drawback of compact output is the resultant element can be an object or an array and therefore makes the client code a little awkward in terms of the extra check needed on object type before processing.

NOTE: Although non-compact output is more accurate representation of original XML than compact version, the non-compact version is verbose and consumes more space. This library provides both options. Use {compact: false} if you are not sure because it preserves everything; otherwise use {compact: true} if you want to save space and you don't care about mixing elements of same name and losing their order.

Tip: You can reduce the output size by using shorter key names.

Usage

Installation

npm install --save xml-js

You can also install it globally to use it as a command line convertor (see Command Line).

npm install --global xml-js

Quick start

var convert = require('xml-js');
var xml =
'<?xml version="1.0" encoding="utf-8"?>' +
'<note importance="high" logged="true">' +
'    <title>Happy</title>' +
'    <todo>Work</todo>' +
'    <todo>Play</todo>' +
'</note>';
var result1 = convert.xml2json(xml, {compact: true, spaces: 4});
var result2 = convert.xml2json(xml, {compact: false, spaces: 4});
console.log(result1, '\n', result2);

To see the result of this code, see the output above in Synopsis section.

Or run and edit this code live in the browser.

Sample Conversions

API Reference

This library provides 4 functions: js2xml(), json2xml(), xml2js(), and xml2json(). Here are the usages for each one (see more details in the following sections):

var convert = require('xml-js');
result = convert.js2xml(js, options);     // to convert javascript object to xml text
result = convert.json2xml(json, options); // to convert json text to xml text
result = convert.xml2js(xml, options);    // to convert xml text to javascript object
result = convert.xml2json(xml, options);  // to convert xml text to json text

Convert JS object / JSON → XML

To convert JavaScript object to XML text, use js2xml(). To convert JSON text to XML text, use json2xml().

var convert = require('xml-js');
var json = require('fs').readFileSync('test.json', 'utf8');
var options = {compact: true, ignoreComment: true, spaces: 4};
var result = convert.json2xml(json, options);
console.log(result);

Options for Converting JS object / JSON → XML

The below options are applicable for both js2xml() and json2xml() functions.

Convert XML → JS object / JSON

To convert XML text to JavaScript object, use xml2js(). To convert XML text to JSON text, use xml2json().

var convert = require('xml-js');
var xml = require('fs').readFileSync('test.xml', 'utf8');
var options = {ignoreComment: true, alwaysChildren: true};
var result = convert.xml2js(xml, options); // or convert.xml2json(xml, options)
console.log(result);

Options for Converting XML → JS object / JSON

The below options are applicable for both xml2js() and xml2json() functions.

The below option is applicable only for xml2json() function.

Options for Changing Key Names

To change default key names in the output object or the default key names assumed in the input JavaScript object / JSON, use the following options:

Two default values mean the first is used for non-compact output and the second is for compact output.

TIP: In compact mode, you can further reduce output result by using fewer characters for key names {textKey: '_', attributesKey: '$', commentKey: 'value'}. This is also applicable to non-compact mode.

TIP: In non-compact mode, you probably want to set {textKey: 'value', cdataKey: 'value', commentKey: 'value'} to make it more consistent and easier for your client code to go through the contents of text, cdata, and comment.

Options for Custom Processing Functions

For XML → JS object / JSON, following custom callback functions can be supplied:

var convert = require('xml-js');
var xml = '<foo:Name>Ali</Name> <bar:Age>30</bar:Age>';
var options = {compact: true, elementNameFn: function(val) {return val.replace('foo:','').toUpperCase();}};
var result = convert.xml2json(xml, options);
console.log(result); // {"NAME":{"_text":"Ali"},"BAR:AGE":{"_text":"30"}}

For JS object / JSON → XML, following custom callback functions can be supplied:

var convert = require('xml-js');
var json = '{"name":{"_text":"Ali"},"age":{"_text":"30"}}';
var options = {compact: true, textFn: function(val, elementName) {return elementName === 'age'? val + '';}};
var result = convert.json2xml(json, options);
console.log(result); // <foo:Name>Ali</Name> <bar:Age>30</bar:Age>

Command Line

Because any good library should support command line usage, this library is no different.

As Globally Accessible Command

npm install -g xml-js                       // install this library globally
xml-js test.json --spaces 4                 // xml result will be printed on screen
xml-js test.json --spaces 4 --out test.xml  // xml result will be saved to test.xml
xml-js test.xml --spaces 4                  // json result will be printed on screen
xml-js test.xml --spaces 4 --out test.json  // json result will be saved to test.json

As Locally Accessible Command

If you want to use it as script in package.json (can also be helpful in task automation via npm scripts)

npm install --save xml-js   // no need to install this library globally

In package.json, write a script:

...
  "dependencies": {
    "xml-js": "latest"
  },
  "scripts": {
    "convert": "xml-js test.json --spaces 4"
  }

Now in the command line, you can run this script by typing:

npm run convert             // task 'scripts.convert' will be executed

CLI Arguments

Usage: xml-js src [options]

  src                  Input file that need to be converted.
                       Conversion type xml->json or json->xml will be inferred from file extension.

Options:
  --help, -h           Display this help content.
  --version, -v        Display version number of this module.
  --out                Output file where result should be written.
  --spaces             Specifies amount of space indentation in the output.
  --full-tag           XML elements will always be in <a></a> form.
  --no-decl            Declaration directive <?xml?> will be ignored.
  --no-inst            Processing instruction <?...?> will be ignored.
  --no-attr            Attributes of elements will be ignored.
  --no-text            Texts of elements will be ignored.
  --no-cdata           CData of elements will be ignored.
  --no-doctype         DOCTYPE of elements will be ignored.
  --no-comment         Comments of elements will be ignored.
  --trim               Any whitespaces surrounding texts will be trimmed.
  --compact            JSON is in compact form.
  --native-type        Numbers and boolean will be converted (coerced) to native type instead of text.
  --always-array       Every element will always be an array type (applicable if --compact is set).
  --always-children    Every element will always contain sub-elements (applicable if --compact is not set).
  --text-key           To change the default 'text' key.
  --cdata-key          To change the default 'cdata' key.
  --doctype-key        To change the default 'doctype' key.
  --comment-key        To change the default 'comment' key.
  --attributes-key     To change the default 'attributes' key.
  --declaration-key    To change the default 'declaration' key.
  --instruction-key    To change the default 'processing instruction' key.
  --type-key           To change the default 'type' key (applicable if --compact is not set).
  --name-key           To change the default 'name' key (applicable if --compact is not set).
  --elements-key       To change the default 'elements' key (applicable if --compact is not set).

Contribution

Testing

To perform tests on this project, download the full repository from GitHub (not from npm) and then do the following:

cd xml-js
npm install
npm test

For live testing, use npm start instead of npm test.

Reporting

Use this link to report an issue or bug. Please include a sample code where the code is failing.

License

MIT