fast-xml-parser 5.0.9 → 5.2.0

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "fast-xml-parser",
-  "version": "5.0.9",
+  "version": "5.2.0",
   "description": "Validate XML, Parse XML, Build XML without C/C++ based libraries",
   "main": "./lib/fxp.cjs",
   "type": "module",
+  "sideEffects": false,
   "module": "./src/fxp.js",
   "types": "./src/fxp.d.ts",
   "exports": {

package/src/fxp.d.ts

@@ -210,6 +210,12 @@ type X2jOptions = {
    * Defaults to `(tagName, jPath, attrs) => tagName`
    */
   updateTag?: (tagName: string, jPath: string, attrs: {[k: string]: string}) =>  string | boolean;
+
+  /**
+   * If true, adds a Symbol to all object nodes, accessible by {@link XMLParser.getMetaDataSymbol} with
+   * metadata about each the node in the XML file.
+   */
+  captureMetaData?: boolean;
 };
 
 type strnumOptions = {
@@ -407,6 +413,18 @@ export class XMLParser {
    * @param entityValue {string} Eg: '\r'
    */
   addEntity(entityIdentifier: string, entityValue: string): void;
+
+  /**
+   * Returns a Symbol that can be used to access the {@link XMLMetaData}
+   * property on a node.
+   * 
+   * If Symbol is not available in the environment, an ordinary property is used
+   * and the name of the property is here returned.
+   * 
+   * The XMLMetaData property is only present when {@link X2jOptions.captureMetaData}
+   * is true in the options.
+   */
+  static getMetaDataSymbol() : Symbol;
 }
 
 export class XMLValidator{
@@ -414,5 +432,14 @@ export class XMLValidator{
 }
 export class XMLBuilder {
   constructor(options?: XmlBuilderOptions);
-  build(jObj: any): any;
+  build(jObj: any): string;
+}
+
+/**
+ * This object is available on nodes via the symbol {@link XMLParser.getMetaDataSymbol} 
+ * when {@link X2jOptions.captureMetaData} is true.
+ */
+export interface XMLMetaData {
+  /** The index, if available, of the character where the XML node began in the input stream. */
+  startIndex?: number;
 }

package/src/xmlparser/OptionsBuilder.js

@@ -38,6 +38,7 @@ export const defaultOptions = {
       return tagName
     },
     // skipEmptyListItem: false
+    captureMetaData: false,
 };
    
 export const buildOptions = function(options) {

package/src/xmlparser/OrderedObjParser.js

@@ -246,8 +246,7 @@ const parseXml = function(xmlData) {
           if(tagData.tagName !== tagData.tagExp && tagData.attrExpPresent){
             childNode[":@"] = this.buildAttributesMap(tagData.tagExp, jPath, tagData.tagName);
           }
-          this.addChild(currentNode, childNode, jPath)
-
+          this.addChild(currentNode, childNode, jPath, i);
         }
 
 
@@ -312,6 +311,7 @@ const parseXml = function(xmlData) {
         if(tagName !== xmlObj.tagname){
           jPath += jPath ? "." + tagName : tagName;
         }
+        const startIndex = i;
         if (this.isItStopNode(this.options.stopNodes, jPath, tagName)) {
           let tagContent = "";
           //self-closing tag
@@ -340,6 +340,7 @@ const parseXml = function(xmlData) {
           }
 
           const childNode = new xmlNode(tagName);
+
           if(tagName !== tagExp && attrExpPresent){
             childNode[":@"] = this.buildAttributesMap(tagExp, jPath, tagName);
           }
@@ -350,7 +351,7 @@ const parseXml = function(xmlData) {
           jPath = jPath.substr(0, jPath.lastIndexOf("."));
           childNode.add(this.options.textNodeName, tagContent);
           
-          this.addChild(currentNode, childNode, jPath)
+          this.addChild(currentNode, childNode, jPath, startIndex);
         }else{
   //selfClosing tag
           if(tagExp.length > 0 && tagExp.lastIndexOf("/") === tagExp.length - 1){
@@ -370,7 +371,7 @@ const parseXml = function(xmlData) {
             if(tagName !== tagExp && attrExpPresent){
               childNode[":@"] = this.buildAttributesMap(tagExp, jPath, tagName);
             }
-            this.addChild(currentNode, childNode, jPath)
+            this.addChild(currentNode, childNode, jPath, startIndex);
             jPath = jPath.substr(0, jPath.lastIndexOf("."));
           }
     //opening tag
@@ -381,7 +382,7 @@ const parseXml = function(xmlData) {
             if(tagName !== tagExp && attrExpPresent){
               childNode[":@"] = this.buildAttributesMap(tagExp, jPath, tagName);
             }
-            this.addChild(currentNode, childNode, jPath)
+            this.addChild(currentNode, childNode, jPath, startIndex);
             currentNode = childNode;
           }
           textData = "";
@@ -395,14 +396,16 @@ const parseXml = function(xmlData) {
   return xmlObj.child;
 }
 
-function addChild(currentNode, childNode, jPath){
+function addChild(currentNode, childNode, jPath, startIndex){
+  // unset startIndex if not requested
+  if (!this.options.captureMetaData) startIndex = undefined;
   const result = this.options.updateTag(childNode.tagname, jPath, childNode[":@"])
   if(result === false){
-  }else if(typeof result === "string"){
+  } else if(typeof result === "string"){
     childNode.tagname = result
-    currentNode.addChild(childNode);
+    currentNode.addChild(childNode, startIndex);
   }else{
-    currentNode.addChild(childNode);
+    currentNode.addChild(childNode, startIndex);
   }
 }
 

package/src/xmlparser/XMLParser.js

@@ -2,6 +2,7 @@ import { buildOptions} from './OptionsBuilder.js';
 import OrderedObjParser from './OrderedObjParser.js';
 import prettify from './node2json.js';
 import {validate} from "../validator.js";
+import XmlNode from './xmlNode.js';
 
 export default class XMLParser{
     
@@ -53,4 +54,18 @@ export default class XMLParser{
             this.externalEntities[key] = value;
         }
     }
-}
+
+    /**
+     * Returns a Symbol that can be used to access the metadata
+     * property on a node.
+     * 
+     * If Symbol is not available in the environment, an ordinary property is used
+     * and the name of the property is here returned.
+     * 
+     * The XMLMetaData property is only present when `captureMetaData`
+     * is true in the options.
+     */
+    static getMetaDataSymbol() {
+        return XmlNode.getMetaDataSymbol();
+    }
+}

package/src/xmlparser/node2json.js

@@ -1,5 +1,9 @@
 'use strict';
 
+import XmlNode from './xmlNode.js';
+
+const METADATA_SYMBOL = XmlNode.getMetaDataSymbol();
+
 /**
  * 
  * @param {array} node 
@@ -36,6 +40,9 @@ function compress(arr, options, jPath){
       
       let val = compress(tagObj[property], options, newJpath);
       const isLeaf = isLeafTag(val, options);
+      if (tagObj[METADATA_SYMBOL] !== undefined) {
+        val[METADATA_SYMBOL] = tagObj[METADATA_SYMBOL]; // copy over metadata
+      }
 
       if(tagObj[":@"]){
         assignAttributes( val, tagObj[":@"], newJpath, options);

package/src/xmlparser/xmlNode.js

@@ -1,5 +1,13 @@
 'use strict';
 
+let METADATA_SYMBOL;
+
+if (typeof Symbol !== "function") {
+  METADATA_SYMBOL = "@@xmlMetadata";
+} else {
+  METADATA_SYMBOL = Symbol("XML Node Metadata");
+}
+
 export default class XmlNode{
   constructor(tagname) {
     this.tagname = tagname;
@@ -11,12 +19,22 @@ export default class XmlNode{
     if(key === "__proto__") key = "#__proto__";
     this.child.push( {[key]: val });
   }
-  addChild(node) {
+  addChild(node, startIndex) {
     if(node.tagname === "__proto__") node.tagname = "#__proto__";
     if(node[":@"] && Object.keys(node[":@"]).length > 0){
       this.child.push( { [node.tagname]: node.child, [":@"]: node[":@"] });
     }else{
       this.child.push( { [node.tagname]: node.child });
     }
+    // if requested, add the startIndex
+    if (startIndex !== undefined) {
+      // Note: for now we just overwrite the metadata. If we had more complex metadata,
+      // we might need to do an object append here:  metadata = { ...metadata, startIndex }
+      this.child[this.child.length - 1][METADATA_SYMBOL] = { startIndex };
+    }
+  }
+  /** symbol used for metadata */
+  static getMetaDataSymbol() {
+    return METADATA_SYMBOL;
   }
 }