fast-xml-parser 3.20.3 → 3.21.0

package/README.md

@@ -23,6 +23,8 @@ To cover expenses, we're planning to launch [FXP Enterprise](https://github.com/
 </a>
 <a href="https://paypal.me/naturalintelligence"> <img src="static/img/support_paypal.svg" alt="Stubmatic donate button" width="200"/></a>
 
+Check [ThankYouBackers](https://github.com/NaturalIntelligence/ThankYouBackers) for our contributors
+
 ## Users
 List of some applications/projects using Fast XML Parser. (Raise an issue to submit yours)
 
@@ -103,13 +105,19 @@ The list of users is collected either from the list published by Github, cummuni
 
 ## How to use
 
-To use it in **NPM package**  install it first
+### Installation
+
+To use it as an **NPM package**:
+
+`npm install fast-xml-parser`
 
-`$npm install fast-xml-parser` or using [yarn](https://yarnpkg.com/) `$yarn add fast-xml-parser`
+Or using [yarn](https://yarnpkg.com/):
+
+`yarn add fast-xml-parser`
 
 To use it from a **CLI** install it globally with the `-g` option.
 
-`$npm install fast-xml-parser -g`
+`npm install fast-xml-parser -g`
 
 To use it on a **webpage** include it from a [CDN](https://cdnjs.com/libraries/fast-xml-parser)
 
@@ -117,14 +125,14 @@ To use it on a **webpage** include it from a [CDN](https://cdnjs.com/libraries/f
 
 
 ```js
-var jsonObj = parser.parse(xmlData [,options] );
+const jsonObj = parser.parse(xmlData [,options] );
 ```
 
 ```js
-var parser = require('fast-xml-parser');
-var he = require('he');
+const parser = require('fast-xml-parser');
+const he = require('he');
 
-var options = {
+const options = {
     attributeNamePrefix : "@_",
     attrNodeName: "attr", //default is 'false'
     textNodeName : "#text",
@@ -141,27 +149,28 @@ var options = {
       hex: true,
       leadingZeros: true,
       //skipLike: /\+[0-9]{10}/
-    }
+    },
     arrayMode: false, //"strict"
     attrValueProcessor: (val, attrName) => he.decode(val, {isAttributeValue: true}),//default is a=>a
     tagValueProcessor : (val, tagName) => he.decode(val), //default is a=>a
-    stopNodes: ["parse-me-as-string"]
+    stopNodes: ["parse-me-as-string"],
+    alwaysCreateTextNode: false
 };
 
 if( parser.validate(xmlData) === true) { //optional (it'll return an object in case it's not valid)
-    var jsonObj = parser.parse(xmlData,options);
+    let jsonObj = parser.parse(xmlData,options);
 }
 
 // Intermediate obj
-var tObj = parser.getTraversalObj(xmlData,options);
-var jsonObj = parser.convertToJson(tObj,options);
+const tObj = parser.getTraversalObj(xmlData,options);
+let jsonObj = parser.convertToJson(tObj,options);
 
 ```
 As you can notice in the above code, validator is not embedded with in the parser and expected to be called separately. However, you can pass `true` or validation options as 3rd parameter to the parser to trigger validator internally. It is same as above example.
 
 ```js
 try{
-  var jsonObj = parser.parse(xmlData,options, true);
+  let jsonObj = parser.parse(xmlData,options, true);
 }catch(error){
   console.log(error.message)
 }
@@ -200,7 +209,7 @@ Validator returns the following object in case of error;
 * **tagValueProcessor** : Process tag value during transformation. Like HTML decoding, word capitalization, etc. Applicable in case of string only.
 * **attrValueProcessor** : Process attribute value during transformation. Like HTML decoding, word capitalization, etc. Applicable in case of string only.
 * **stopNodes** : an array of tag names which are not required to be parsed. Instead their values are parsed as string.
-
+* **alwaysCreateTextNode** : When `true`, forces the parser always return a property for the `textNodeName` even if there are no attributes or node children.
 </details>
 
 <details>
@@ -223,18 +232,18 @@ $cat xmlfile.xml | xml2js [-ns|-a|-c|-v|-V] [-o outputfile.json]
 	<summary>To use it <b>on webpage</b></summary>
 
 ```js
-var result = parser.validate(xmlData);
+const result = parser.validate(xmlData);
 if (result !== true) console.log(result.err);
-var jsonObj = parser.parse(xmlData);
+const jsonObj = parser.parse(xmlData);
 ```
 </details>
 
 ### JSON / JS Object to XML
 
 ```js
-var Parser = require("fast-xml-parser").j2xParser;
+const Parser = require("fast-xml-parser").j2xParser;
 //default options need not to set
-var defaultOptions = {
+const defaultOptions = {
     attributeNamePrefix : "@_",
     attrNodeName: "@", //default is false
     textNodeName : "#text",
@@ -245,10 +254,11 @@ var defaultOptions = {
     indentBy: "  ",
     supressEmptyNode: false,
     tagValueProcessor: a=> he.encode(a, { useNamedReferences: true}),// default is a=>a
-    attrValueProcessor: a=> he.encode(a, {isAttributeValue: isAttribute, useNamedReferences: true})// default is a=>a
+    attrValueProcessor: a=> he.encode(a, {isAttributeValue: isAttribute, useNamedReferences: true}),// default is a=>a
+    rootNodeName: "element"
 };
-var parser = new Parser(defaultOptions);
-var xml = parser.parse(json_or_js_obj);
+const parser = new Parser(defaultOptions);
+const xml = parser.parse(json_or_js_obj);
 ```
 
 <details>
@@ -267,6 +277,7 @@ With the correct options, you can get the almost original XML without losing any
 * **supressEmptyNode** : If set to `true`, tags with no value (text or nested tags) are written as self closing tags.
 * **tagValueProcessor** : Process tag value during transformation. Like HTML encoding, word capitalization, etc. Applicable in case of string only.
 * **attrValueProcessor** : Process attribute value during transformation. Like HTML encoding, word capitalization, etc. Applicable in case of string only.
+* **rootNodeName** : When input js object is array, parser uses array index by default as tag name. You can set this property for proper response.
 </details>
 
 ## Benchmark

package/package.json

@@ -1,19 +1,18 @@
 {
   "name": "fast-xml-parser",
-  "version": "3.20.3",
+  "version": "3.21.0",
   "description": "Validate XML or Parse XML to JS/JSON very fast without C/C++ based libraries",
   "main": "./src/parser.js",
   "scripts": {
-    "test": "jasmine spec/*spec.js",
+    "test": "npx nyc jasmine spec/*spec.js",
     "unit": "jasmine",
+    "coverage": "npx nyc report --reporter html --reporter text -t .nyc_output --report-dir .nyc_output/summary",
     "perf": "node ./benchmark/perfTest3.js",
     "lint": "eslint src/*.js spec/*.js",
     "bundle": "webpack && webpack --config webpack-prod.config.js",
-    "coverage": "istanbul cover -x \"cli.js\" -x \"spec/*spec.js\" jasmine spec/*spec.js;",
-    "coverage:check": "istanbul check-coverage --branch 90 --statement 90",
     "prettier": "prettier --write src/**/*.js",
     "publish-please": "publish-please",
-    "prepublishOnly": "publish-please guard"
+    "checkReadiness": "publish-please --dry-run"
   },
   "bin": {
     "xml2js": "./cli.js"
@@ -76,8 +75,6 @@
     "babel-loader": "^8.2.2",
     "eslint": "^5.16.0",
     "he": "^1.2.0",
-    "http-server": "^0.12.3",
-    "istanbul": "^0.4.5",
     "jasmine": "^3.6.4",
     "nimnjs": "^1.3.2",
     "prettier": "^1.19.1",
@@ -91,6 +88,7 @@
     "url": "https://paypal.me/naturalintelligence"
   },
   "dependencies": {
+    "nyc": "^15.1.0",
     "strnum": "^1.0.4"
   }
 }

package/src/json2xml.js

@@ -32,6 +32,7 @@ const props = [
   'supressEmptyNode',
   'tagValueProcessor',
   'attrValueProcessor',
+  'rootNodeName', //when array as root
 ];
 
 function Parser(options) {
@@ -79,6 +80,11 @@ function Parser(options) {
 }
 
 Parser.prototype.parse = function(jObj) {
+  if(Array.isArray(jObj) && this.options.rootNodeName && this.options.rootNodeName.length > 1){
+    jObj = {
+      [this.options.rootNodeName] : jObj
+    }
+  }
   return this.j2x(jObj, 0).val;
 };
 

package/src/nimndata.js

@@ -48,7 +48,7 @@ const _e = function(node, e_schema, options) {
         //attributes can't be repeated. hence check in children tags only
         str += chars.arrStart;
         const itemSchema = e_schema[0];
-        //var itemSchemaType = itemSchema;
+        //const itemSchemaType = itemSchema;
         const arr_len = node.length;
 
         if (typeof itemSchema === 'string') {

package/src/node2json.js

@@ -6,7 +6,7 @@ const convertToJson = function(node, options, parentTagName) {
   const jObj = {};
 
   // when no child node or attr is present
-  if ((!node.child || util.isEmptyObject(node.child)) && (!node.attrsMap || util.isEmptyObject(node.attrsMap))) {
+  if (!options.alwaysCreateTextNode && (!node.child || util.isEmptyObject(node.child)) && (!node.attrsMap || util.isEmptyObject(node.attrsMap))) {
     return util.isExist(node.val) ? node.val : '';
   }
 

package/src/node2json_str.js

@@ -19,10 +19,10 @@ const _cToJsonStr = function(node, options, level) {
   const keys = Object.keys(node.child);
 
   for (let index = 0; index < keys.length; index++) {
-    var tagname = keys[index];
+    const tagname = keys[index];
     if (node.child[tagname] && node.child[tagname].length > 1) {
       jObj += '"' + tagname + '" : [ ';
-      for (var tag in node.child[tagname]) {
+      for (let tag in node.child[tagname]) {
         jObj += _cToJsonStr(node.child[tagname][tag], options) + ' , ';
       }
       jObj = jObj.substr(0, jObj.length - 1) + ' ] '; //remove extra comma in last

package/src/parser.d.ts

@@ -16,6 +16,7 @@ type X2jOptions = {
   tagValueProcessor: (tagValue: string, tagName: string) => string;
   attrValueProcessor: (attrValue: string, attrName: string) => string;
   stopNodes: string[];
+  alwaysCreateTextNode: boolean;
 };
 type strnumOptions = {
   hex: boolean;
@@ -45,7 +46,7 @@ type J2xOptionsOptional = Partial<J2xOptions>;
 type ESchema = string | object | Array<string|object>;
 
 type ValidationError = {
-  err: { code: string; msg: string, line: number };
+  err: { code: string; msg: string, line: number, col: number };
 };
 
 export function parse(xmlData: string, options?: X2jOptionsOptional, validationOptions?: validationOptionsOptional | boolean): any;

package/src/util.js

@@ -10,6 +10,7 @@ const getAllMatches = function(string, regex) {
   let match = regex.exec(string);
   while (match) {
     const allmatches = [];
+    allmatches.startIndex = regex.lastIndex - match[0].length;
     const len = match.length;
     for (let index = 0; index < len; index++) {
       allmatches.push(match[index]);
@@ -67,7 +68,7 @@ exports.getValue = function(v) {
 // const fakeCallNoReturn = function() {};
 
 exports.buildOptions = function(options, defaultOptions, props) {
-  var newOptions = {};
+  let newOptions = {};
   if (!options) {
     return defaultOptions; //if there are not options
   }

package/src/validator.js

@@ -35,7 +35,7 @@ exports.validate = function (xmlData, options) {
     }else if (xmlData[i] === '<') {
       //starting of tag
       //read until you reach to '>' avoiding any '>' in attribute value
-
+      let tagStartPos = i;
       i++;
       
       if (xmlData[i] === '!') {
@@ -71,7 +71,7 @@ exports.validate = function (xmlData, options) {
         if (!validateTagName(tagName)) {
           let msg;
           if (tagName.trim().length === 0) {
-            msg = "There is an unnecessary space between tag name and backward slash '</ ..'.";
+            msg = "Invalid space after '<'.";
           } else {
             msg = "Tag '"+tagName+"' is an invalid name.";
           }
@@ -87,6 +87,7 @@ exports.validate = function (xmlData, options) {
 
         if (attrStr[attrStr.length - 1] === '/') {
           //self closing tag
+          const attrStrStart = i - attrStr.length;
           attrStr = attrStr.substring(0, attrStr.length - 1);
           const isValid = validateAttributeString(attrStr, options);
           if (isValid === true) {
@@ -96,17 +97,20 @@ exports.validate = function (xmlData, options) {
             //the result from the nested function returns the position of the error within the attribute
             //in order to get the 'true' error line, we need to calculate the position where the attribute begins (i - attrStr.length) and then add the position within the attribute
             //this gives us the absolute index in the entire xml, which we can use to find the line at last
-            return getErrorObject(isValid.err.code, isValid.err.msg, getLineNumberForPosition(xmlData, i - attrStr.length + isValid.err.line));
+            return getErrorObject(isValid.err.code, isValid.err.msg, getLineNumberForPosition(xmlData, attrStrStart + isValid.err.line));
           }
         } else if (closingTag) {
           if (!result.tagClosed) {
             return getErrorObject('InvalidTag', "Closing tag '"+tagName+"' doesn't have proper closing.", getLineNumberForPosition(xmlData, i));
           } else if (attrStr.trim().length > 0) {
-            return getErrorObject('InvalidTag', "Closing tag '"+tagName+"' can't have attributes or invalid starting.", getLineNumberForPosition(xmlData, i));
+            return getErrorObject('InvalidTag', "Closing tag '"+tagName+"' can't have attributes or invalid starting.", getLineNumberForPosition(xmlData, tagStartPos));
           } else {
             const otg = tags.pop();
-            if (tagName !== otg) {
-              return getErrorObject('InvalidTag', "Closing tag '"+otg+"' is expected inplace of '"+tagName+"'.", getLineNumberForPosition(xmlData, i));
+            if (tagName !== otg.tagName) {
+              let openPos = getLineNumberForPosition(xmlData, otg.tagStartPos);
+              return getErrorObject('InvalidTag',
+                "Expected closing tag '"+otg.tagName+"' (opened in line "+openPos.line+", col "+openPos.col+") instead of closing tag '"+tagName+"'.",
+                getLineNumberForPosition(xmlData, tagStartPos));
             }
 
             //when there are no more tags, we reached the root level.
@@ -127,7 +131,7 @@ exports.validate = function (xmlData, options) {
           if (reachedRoot === true) {
             return getErrorObject('InvalidXml', 'Multiple possible root nodes found.', getLineNumberForPosition(xmlData, i));
           } else {
-            tags.push(tagName);
+            tags.push({tagName, tagStartPos});
           }
           tagFound = true;
         }
@@ -168,8 +172,12 @@ exports.validate = function (xmlData, options) {
 
   if (!tagFound) {
     return getErrorObject('InvalidXml', 'Start tag expected.', 1);
-  } else if (tags.length > 0) {
-    return getErrorObject('InvalidXml', "Invalid '"+JSON.stringify(tags, null, 4).replace(/\r?\n/g, '')+"' found.", 1);
+  }else if (tags.length == 1) {
+      return getErrorObject('InvalidTag', "Unclosed tag '"+tags[0].tagName+"'.", getLineNumberForPosition(xmlData, tags[0].tagStartPos));
+  }else if (tags.length > 0) {
+      return getErrorObject('InvalidXml', "Invalid '"+
+          JSON.stringify(tags.map(t => t.tagName), null, 4).replace(/\r?\n/g, '')+
+          "' found.", {line: 1, col: 1});
   }
 
   return true;
@@ -181,11 +189,11 @@ exports.validate = function (xmlData, options) {
  * @param {*} i
  */
 function readPI(xmlData, i) {
-  var start = i;
+  const start = i;
   for (; i < xmlData.length; i++) {
     if (xmlData[i] == '?' || xmlData[i] == ' ') {
       //tagname
-      var tagname = xmlData.substr(start, i - start);
+      const tagname = xmlData.substr(start, i - start);
       if (i > 5 && tagname === 'xml') {
         return getErrorObject('InvalidXml', 'XML declaration allowed only at the start of the document.', getLineNumberForPosition(xmlData, i));
       } else if (xmlData[i] == '?' && xmlData[i + 1] == '>') {
@@ -251,8 +259,8 @@ function readCommentAndCDATA(xmlData, i) {
   return i;
 }
 
-var doubleQuote = '"';
-var singleQuote = "'";
+const doubleQuote = '"';
+const singleQuote = "'";
 
 /**
  * Keep reading xmlData until '<' is found outside the attribute value.
@@ -269,7 +277,6 @@ function readAttributeStr(xmlData, i) {
         startChar = xmlData[i];
       } else if (startChar !== xmlData[i]) {
         //if vaue is enclosed with double quote then single quotes are allowed inside the value and vice versa
-        continue;
       } else {
         startChar = '';
       }
@@ -310,23 +317,23 @@ function validateAttributeString(attrStr, options) {
   for (let i = 0; i < matches.length; i++) {
     if (matches[i][1].length === 0) {
       //nospace before attribute name: a="sd"b="saf"
-      return getErrorObject('InvalidAttr', "Attribute '"+matches[i][2]+"' has no space in starting.", getPositionFromMatch(attrStr, matches[i][0]))
+      return getErrorObject('InvalidAttr', "Attribute '"+matches[i][2]+"' has no space in starting.", getPositionFromMatch(matches[i]))
     } else if (matches[i][3] === undefined && !options.allowBooleanAttributes) {
       //independent attribute: ab
-      return getErrorObject('InvalidAttr', "boolean attribute '"+matches[i][2]+"' is not allowed.", getPositionFromMatch(attrStr, matches[i][0]));
+      return getErrorObject('InvalidAttr', "boolean attribute '"+matches[i][2]+"' is not allowed.", getPositionFromMatch(matches[i]));
     }
     /* else if(matches[i][6] === undefined){//attribute without value: ab=
                     return { err: { code:"InvalidAttr",msg:"attribute " + matches[i][2] + " has no value assigned."}};
                 } */
     const attrName = matches[i][2];
     if (!validateAttrName(attrName)) {
-      return getErrorObject('InvalidAttr', "Attribute '"+attrName+"' is an invalid name.", getPositionFromMatch(attrStr, matches[i][0]));
+      return getErrorObject('InvalidAttr', "Attribute '"+attrName+"' is an invalid name.", getPositionFromMatch(matches[i]));
     }
     if (!attrNames.hasOwnProperty(attrName)) {
       //check for duplicate attribute.
       attrNames[attrName] = 1;
     } else {
-      return getErrorObject('InvalidAttr', "Attribute '"+attrName+"' is repeated.", getPositionFromMatch(attrStr, matches[i][0]));
+      return getErrorObject('InvalidAttr', "Attribute '"+attrName+"' is repeated.", getPositionFromMatch(matches[i]));
     }
   }
 
@@ -373,7 +380,8 @@ function getErrorObject(code, message, lineNumber) {
     err: {
       code: code,
       msg: message,
-      line: lineNumber,
+      line: lineNumber.line || lineNumber,
+      col: lineNumber.col,
     },
   };
 }
@@ -390,11 +398,16 @@ function validateTagName(tagname) {
 
 //this function returns the line number for the character at the given index
 function getLineNumberForPosition(xmlData, index) {
-  var lines = xmlData.substring(0, index).split(/\r?\n/);
-  return lines.length;
+  const lines = xmlData.substring(0, index).split(/\r?\n/);
+  return {
+    line: lines.length,
+
+    // column number is last line's length + 1, because column numbering starts at 1:
+    col: lines[lines.length - 1].length + 1
+  };
 }
 
-//this function returns the position of the last character of match within attrStr
-function getPositionFromMatch(attrStr, match) {
-  return attrStr.indexOf(match) + match.length;
+//this function returns the position of the first character of match within attrStr
+function getPositionFromMatch(match) {
+  return match.startIndex + match[1].length;
 }

package/src/xmlstr2xmlnode.js

@@ -44,7 +44,8 @@ const defaultOptions = {
   attrValueProcessor: function(a, attrName) {
     return a;
   },
-  stopNodes: []
+  stopNodes: [],
+  alwaysCreateTextNode: false
   //decodeStrict: false,
 };
 
@@ -67,7 +68,8 @@ const props = [
   'attrValueProcessor',
   'parseTrueNumberOnly',
   'numParseOptions',
-  'stopNodes'
+  'stopNodes',
+  'alwaysCreateTextNode'
 ];
 exports.props = props;