fast-xml-parser 5.4.1 → 5.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-xml-parser",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "description": "Validate XML, Parse XML, Build XML without C/C++ based libraries",
   "main": "./lib/fxp.cjs",
   "type": "module",
@@ -87,7 +87,8 @@
     }
   ],
   "dependencies": {
-    "fast-xml-builder": "^1.0.0",
+    "fast-xml-builder": "file:../../fxp-builder",
+    "path-expression-matcher": "^1.1.2",
     "strnum": "^2.1.2"
   }
-}
+}

package/src/fxp.d.ts

@@ -1,3 +1,5 @@
+import { Matcher, Expression } from 'path-expression-matcher';
+
 export type ProcessEntitiesOptions = {
   /**
    * Whether to enable entity processing
@@ -34,6 +36,13 @@ export type ProcessEntitiesOptions = {
    */
   maxExpandedLength?: number;
 
+  /**
+   * Maximum number of entities allowed in the XML
+   * 
+   * Defaults to `100`
+   */
+  maxEntityCount?: number;
+
   /**
    * Array of tag names where entity replacement is allowed.
    * If null, entities are replaced in all tags.
@@ -46,12 +55,12 @@ export type ProcessEntitiesOptions = {
    * Custom filter function to determine if entities should be replaced in a tag
    * 
    * @param tagName - The name of the current tag
-   * @param jPath - The jPath of the current tag
+   * @param jPathOrMatcher - The jPath string (if jPath: true) or Matcher instance (if jPath: false)
    * @returns `true` to allow entity replacement, `false` to skip
    * 
    * Defaults to `null`
    */
-  tagFilter?: ((tagName: string, jPath: string) => boolean) | null;
+  tagFilter?: ((tagName: string, jPathOrMatcher: string | Matcher) => boolean) | null;
 };
 
 export type X2jOptions = {
@@ -96,7 +105,7 @@ export type X2jOptions = {
    * 
    * Defaults to `true`
    */
-  ignoreAttributes?: boolean | (string | RegExp)[] | ((attrName: string, jPath: string) => boolean);
+  ignoreAttributes?: boolean | (string | RegExp)[] | ((attrName: string, jPathOrMatcher: string | Matcher) => boolean);
 
   /**
    * Whether to remove namespace string from tag and attribute names
@@ -150,28 +159,33 @@ export type X2jOptions = {
   /**
    * Control how tag value should be parsed. Called only if tag value is not empty
    * 
+   * @param tagName - The name of the tag
+   * @param tagValue - The value of the tag
+   * @param jPathOrMatcher - The jPath string (if jPath: true) or Matcher instance (if jPath: false)
+   * @param hasAttributes - Whether the tag has attributes
+   * @param isLeafNode - Whether the tag is a leaf node
    * @returns {undefined|null} `undefined` or `null` to set original value.
    * @returns {unknown} 
    * 
    * 1. Different value or value with different data type to set new value.
    * 2. Same value to set parsed value if `parseTagValue: true`.
    * 
-   * Defaults to `(tagName, val, jPath, hasAttributes, isLeafNode) => val`
+   * Defaults to `(tagName, val, jPathOrMatcher, hasAttributes, isLeafNode) => val`
    */
-  tagValueProcessor?: (tagName: string, tagValue: string, jPath: string, hasAttributes: boolean, isLeafNode: boolean) => unknown;
+  tagValueProcessor?: (tagName: string, tagValue: string, jPathOrMatcher: string | Matcher, hasAttributes: boolean, isLeafNode: boolean) => unknown;
 
   /**
    * Control how attribute value should be parsed
    * 
-   * @param attrName 
-   * @param attrValue 
-   * @param jPath 
+   * @param attrName - The name of the attribute
+   * @param attrValue - The value of the attribute
+   * @param jPathOrMatcher - The jPath string (if jPath: true) or Matcher instance (if jPath: false)
    * @returns {undefined|null} `undefined` or `null` to set original value
    * @returns {unknown}
    * 
-   * Defaults to `(attrName, val, jPath) => val`
+   * Defaults to `(attrName, val, jPathOrMatcher) => val`
    */
-  attributeValueProcessor?: (attrName: string, attrValue: string, jPath: string) => unknown;
+  attributeValueProcessor?: (attrName: string, attrValue: string, jPathOrMatcher: string | Matcher) => unknown;
 
   /**
    * Options to pass to `strnum` for parsing numbers
@@ -183,9 +197,13 @@ export type X2jOptions = {
   /**
    * Nodes to stop parsing at
    * 
+   * Accepts string patterns or Expression objects from path-expression-matcher
+   * 
+   * String patterns starting with "*." are automatically converted to ".." for backward compatibility
+   * 
    * Defaults to `[]`
    */
-  stopNodes?: string[];
+  stopNodes?: (string | Expression)[];
 
   /**
    * List of tags without closing tags
@@ -204,15 +222,15 @@ export type X2jOptions = {
   /**
    * Determine whether a tag should be parsed as an array
    * 
-   * @param tagName 
-   * @param jPath 
-   * @param isLeafNode 
-   * @param isAttribute 
+   * @param tagName - The name of the tag
+   * @param jPathOrMatcher - The jPath string (if jPath: true) or Matcher instance (if jPath: false)
+   * @param isLeafNode - Whether the tag is a leaf node
+   * @param isAttribute - Whether this is an attribute
    * @returns {boolean}
    * 
    * Defaults to `() => false`
    */
-  isArray?: (tagName: string, jPath: string, isLeafNode: boolean, isAttribute: boolean) => boolean;
+  isArray?: (tagName: string, jPathOrMatcher: string | Matcher, isLeafNode: boolean, isAttribute: boolean) => boolean;
 
   /**
    * Whether to process default and DOCTYPE entities
@@ -266,12 +284,15 @@ export type X2jOptions = {
    * Change the tag name when a different name is returned. Skip the tag from parsed result when false is returned.
    * Modify `attrs` object to control attributes for the given tag.
    * 
+   * @param tagName - The name of the tag
+   * @param jPathOrMatcher - The jPath string (if jPath: true) or Matcher instance (if jPath: false)
+   * @param attrs - The attributes object
    * @returns {string} new tag name.
    * @returns false to skip the tag
    * 
-   * Defaults to `(tagName, jPath, attrs) => tagName`
+   * Defaults to `(tagName, jPathOrMatcher, attrs) => tagName`
    */
-  updateTag?: (tagName: string, jPath: string, attrs: { [k: string]: string }) => string | boolean;
+  updateTag?: (tagName: string, jPathOrMatcher: string | Matcher, attrs: { [k: string]: string }) => string | boolean;
 
   /**
    * If true, adds a Symbol to all object nodes, accessible by {@link XMLParser.getMetaDataSymbol} with
@@ -292,6 +313,17 @@ export type X2jOptions = {
    * Defaults to `true`
    */
   strictReservedNames?: boolean;
+
+  /**
+   * Controls whether callbacks receive jPath as string or Matcher instance
+   * 
+   * When `true` - callbacks receive jPath as string (backward compatible)
+   * 
+   * When `false` - callbacks receive Matcher instance for advanced pattern matching
+   * 
+   * Defaults to `true`
+   */
+  jPath?: boolean;
 };
 
 
@@ -430,9 +462,11 @@ export type XmlBuilderOptions = {
   /**
    * Nodes to stop parsing at
    * 
+   * Accepts string patterns or Expression objects from path-expression-matcher
+   * 
    * Defaults to `[]`
    */
-  stopNodes?: string[];
+  stopNodes?: (string | Expression)[];
 
   /**
    * Control how tag value should be parsed. Called only if tag value is not empty

package/src/xmlparser/DocTypeReader.js

@@ -7,8 +7,9 @@ export default class DocTypeReader {
     }
 
     readDocType(xmlData, i) {
-
         const entities = Object.create(null);
+        let entityCount = 0;
+
         if (xmlData[i + 3] === 'O' &&
             xmlData[i + 4] === 'C' &&
             xmlData[i + 5] === 'T' &&
@@ -26,11 +27,19 @@ export default class DocTypeReader {
                         let entityName, val;
                         [entityName, val, i] = this.readEntityExp(xmlData, i + 1, this.suppressValidationErr);
                         if (val.indexOf("&") === -1) { //Parameter entities are not supported
+                            if (this.options.enabled !== false &&
+                                this.options.maxEntityCount &&
+                                entityCount >= this.options.maxEntityCount) {
+                                throw new Error(
+                                    `Entity count (${entityCount + 1}) exceeds maximum allowed (${this.options.maxEntityCount})`
+                                );
+                            }
                             const escaped = entityName.replace(/[.\-+*:]/g, '\\.');
                             entities[entityName] = {
                                 regx: RegExp(`&${escaped};`, "g"),
                                 val: val
                             };
+                            entityCount++;
                         }
                     }
                     else if (hasBody && hasSeq(xmlData, "!ELEMENT", i)) {

package/src/xmlparser/OptionsBuilder.js

@@ -40,6 +40,7 @@ export const defaultOptions = {
   captureMetaData: false,
   maxNestedTags: 100,
   strictReservedNames: true,
+  jPath: true, // if true, pass jPath string to callbacks; if false, pass matcher instance
 };
 
 /**
@@ -56,6 +57,7 @@ function normalizeProcessEntities(value) {
       maxExpansionDepth: 10,
       maxTotalExpansions: 1000,
       maxExpandedLength: 100000,
+      maxEntityCount: 100,
       allowedTags: null,
       tagFilter: null
     };
@@ -69,6 +71,7 @@ function normalizeProcessEntities(value) {
       maxExpansionDepth: value.maxExpansionDepth ?? 10,
       maxTotalExpansions: value.maxTotalExpansions ?? 1000,
       maxExpandedLength: value.maxExpandedLength ?? 100000,
+      maxEntityCount: value.maxEntityCount ?? 100,
       allowedTags: value.allowedTags ?? null,
       tagFilter: value.tagFilter ?? null
     };
@@ -83,6 +86,18 @@ export const buildOptions = function (options) {
 
   // Always normalize processEntities for backward compatibility and validation
   built.processEntities = normalizeProcessEntities(built.processEntities);
+
+  // Convert old-style stopNodes for backward compatibility
+  if (built.stopNodes && Array.isArray(built.stopNodes)) {
+    built.stopNodes = built.stopNodes.map(node => {
+      if (typeof node === 'string' && node.startsWith('*.')) {
+        // Old syntax: *.tagname meant "tagname anywhere"
+        // Convert to new syntax: ..tagname
+        return '..' + node.substring(2);
+      }
+      return node;
+    });
+  }
   //console.debug(built.processEntities)
   return built;
 };